Use the API to set up reference catalogs on your domain

This article is for developers with a full understanding of how to work with our API. 

Important note about the API explorer
When you follow the link we provide to the API explorer, you'll see a red warning.
API_image01.png
The API itself is not deprecated. It's the Google API explorer that is deprecated. All the processes described in our API articles function correctly and safely if you use this Google API explorer. 


Reference catalogs let you define properties that behave like categories but which are defined at the domain level. This means that users can access exactly the same set of properties that behave like categories with the same values in all libraries on your domain. 

Learn more:

This article is for AODocs super administrators who want to set up reference catalogs on their domain. It describes how to create a reference catalog with values.

Important:
– You must set up your reference catalogs by API.
– Reference catalogs are always single-level. You can't configure sublevels as you can for categories.

Learn more about what else you can do with reference catalogs using the API.

Automatically generated table of contents


Create reference catalogs

1. As a super administrator, follow this link to the referenceCatalog API:

https://apis-explorer.appspot.com/apis-explorer/?base=https://ao-docs.appspot.com/_ah/api#search/referencecatalog/referenceCatalog/v1/referenceCatalog.referenceCatalog.createReferenceCatalog

2. Enter the name of the reference catalog you want to create, for example, Country.

3. Press Authorize and execute.

The response is displayed in the lower part of the screen. You can see the name and ID of your newly created reference catalog. It currently has no values.

image01.png


Create values for reference catalogs

Important: You must have the ID of the reference catalog for which you want to create values. If you have just created your reference catalog, you can recover its ID in the response to the call to create it. Otherwise, you can list the reference catalogs and IDs on your domain.

1. As a super administrator, follow this link to the referenceCatalog API:

https://apis-explorer.appspot.com/apis-explorer/?base=https://ao-docs.appspot.com/_ah/api#search/referencecatalog/referenceCatalog/v1/referenceCatalog.referenceCatalog.saveReferenceCatalogValues 

2. In the catalogId field, enter the ID of the reference catalog for which you want to create values.

3. In the Request body field, select referenceCatalogValues in the add a property menu.

image02.png

4. Press the green plus button to add an array element. A new add a property menu appears.

image03.png

5. Select name in the drop-down menu.

image04.png

6. Enter the value you want to add to your reference catalog, for example, France

7. Optionally, you can define an ID for the value:

  • Select id in the add a property menu. 
  • Enter an ID for your value, for example, France33.

Note: An ID is automatically generated if you don't define one.

image05.png

8. Repeat steps 4 to 7 as many times as you like to enter more values. 

Tip: Alternatively, prepare a JSON file with all your values beforehand. Switch to Freeform editor and paste the content of your JSON file into the text field.
image06.png

9. Press Authorize and execute. The response is displayed in the lower part of the screen.

image07.png


List the reference catalogs on your domain with their IDs

1. As a super administrator, follow this link to the referenceCatalog API:

https://apis-explorer.appspot.com/apis-explorer/?base=https://ao-docs.appspot.com/_ah/api#search/referencecatalog/referenceCatalog/v1/referenceCatalog.referenceCatalog.getReferenceCatalogs

2. Enter your domain name. 

3. Press Authorize and execute

image04.png

The response is displayed in the lower part of the screen. It lists all the reference catalogs on your domain. Copy the ID of the reference catalog for which you want to create values

image05.png


Access the list of all actions available for managing your reference catalogs

As a super administrator, follow this link to the referenceCatalog API:

https://apis-explorer.appspot.com/apis-explorer/?base=https://ao-docs.appspot.com/_ah/api#search/referencecatalog/referenceCatalog/v1/

The referenceCatalog API has the following methods.

referenceCatalog.referenceCatalog.createReferenceCatalog

referenceCatalog.referenceCatalog.deleteReferenceCatalog

  • Deletes a reference catalog.
  • Enter the reference catalog ID.
referenceCatalog.referenceCatalog.getReferenceCatalog
  • Lists details of a reference catalog, including its name, ID and number of values.
  • Enter the reference catalog ID.

referenceCatalog.referenceCatalog.getReferenceCatalogValue

  • Lists details of a reference catalog value, including its name, when it was created and when it was last updated.
  • Enter the reference catalog ID and the value ID.

referenceCatalog.referenceCatalog.getReferenceCatalogValueSuggestions

  • Lists values with a specific prefix in a reference catalog (for example, all values beginning with "ch").
  • Enter the reference catalog ID and the required prefix.

referenceCatalog.referenceCatalog.getReferenceCatalogValues

  • Lists all the values of a reference catalog with their IDs. 
  • Enter the reference catalog ID.

referenceCatalog.referenceCatalog.getReferenceCatalogs

  • Lists all reference catalogs on your domain with their IDs.
  • Enter the name of your domain.

referenceCatalog.referenceCatalog.saveReferenceCatalogValues

referenceCatalog.referenceCatalog.updateReferenceCatalog
  • Updates a reference catalog (for example, changes its name).
  • Enter the domain and then the reference catalog ID in the Request body field.

 

Was this article helpful? 0 out of 0 found this helpful
If you didn’t find what you were looking for, don’t hesitate to leave a comment!
Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.