...

...

In some metadata fields, you may want to provide a selection list of possible values from which the users have to choose. Those lists are configured via so-called catalogs. In their schema definition, they can be configured to be editable or not editable directly in your client for users with the proper authorization. A change in the schema definition is not required in order to modify the available values for the so-called dynamic catalogs.

...

• We use the term catalog from a technical perspective and the term list from the user's perspective.
• The catalog values (corresponding to list elements) cannot be localized.
• The list elements can't cannot be manipulated by client form scripting.

...

A property can be classified in the schema definition to be displayed as a dynamic catalog in your client by setting the value dynamic:catalog[<catalog name>] for the attribute classification.  The Per default, the catalog name will be the displayed expression used as display name in your client per default. It can be localized in order to replace the displayed expressiondisplay name. We recommend using naming conventions as described below that makes which make it easy to distinguish between tenant-specific and global catalogs.

...

Catalogs can be set as readonly via Web-API gateway. Thus, the catalog values cannot be modified via the dms-controller endpoints of the Web-API gateway. Since the client uses the dms-controller endpoints, the corresponding pick-selection list elements in the client will also not be not editable. Changes can be applied only via the system-controller endpoints in case of global catalogs and via the admin-controller endpoints in case of tenant-specific catalogs. This catalog management is also possible via yuuvis® architect.
>> yuuvis® architect

In order to avoid the occurance of empty pick selection lists in your client, we recommend to create the JSON configuration of the catalog first and introduce the definition into the schema afterwards.

...

If only one specific tenant will use a dynamic catalog, it is recommended to configure this catalog as a tenant-specific property. Its technical name should follow the naming convention ten<tenantname>:<catalogname>. A user with the role YUUVIS_TENANT_ADMIN role is required.

The catalog values are saved in the config server beside the tenant schema configuration.

In the following code block, an example schema definition of the example string property contract is displayed. The property is classified by in line 6 to be a dynamic catalog that which is displayed as a pick selection list with the technical name tenMytenant:contracts in your client. Initially, the list of values offered to users will be empty.

...

If the example schema is uploaded as a tenant schema via the endpoint POST /api/admin/schema by  endpoint by a user of the example tenant mytenant, the property contract will be available only in the specific tenant mytenant. After restarting your client, the users will get an empty pick selection list for the field called tenMytenant:contracts.

...

For catalogs in an app schema, we recommend the naming convention app<appname>:<catalogname>. For global catalogs, we recommend to use no extra special prefix but only the catalog name <catalogname>.

...

Not-Editable Global Catalogs

Users with the role YUUVIS_SYSTEM_INTEGRATOR role can set up global catalogs with initial standard elements and set the catalogs to readonly.

In this case, you should only use only standard values that are suitable for all tenants. 

The following code block shows an example property definition cut from an example app schema. If the example schema is uploaded as an app schema via the endpoint POST /api/system/apps/{app}/schema for  endpoint for the example app myapplication, the property contract will not only be available only for the specific app myapplication, but to all tenants using this app. After restarting your client, the users will get an empty pick selection list for the field called appMyapplication:contracts.

...

The following code block shows an example property definition cut from an example system schema. If the example schema is uploaded as system schema via the endpoint POST /api/system/schema endpoint , the property contract will be available in all tenants and for all applications. After restarting your client, the users will get an empty pick selection list for the field called contracts.

...

If the catalog parameter readonly is not set, users with the role YUUVIS_MANAGE_SETTINGS role can change the list elements in your client. With the first update of such a catalog, a new catalog with the same technical name (without additional tenant-specific prefix) is saved for that tenant.

Note: Changes of the global catalog saved by a user with the role YUUVIS_SYSTEM_INTEGRATOR role do not affect the copy.

Editing Catalog Values

The following actions are supported for editable catalogs/ pick-selection lists:

• Create a new list element.
• Remove a list element. A warning is given if this element is used by an object.
• Disable a list element. Such elements are offered for search but not during while creating or editing an object.

Editing via Client

Users with the role YUUVIS_MANAGE_SETTINGS role can maintain pick lists that are based on a property classified as a dynamic catalog without the readonly parameter.

The edit dialog can be opened by clicking the pencil symbol at icon next to the field. The screenshot below shows the edit dialog for the example pick selection list contracts where the four values Employment contract, Rental agreement, User contract, and Purchase contract were already added.

...

admin-controller

Users with the role YUUVIS_TENANT_ADMIN role are offered the maintenance actions also in read-only catalogs via the Web-API Gateway GET and POST endpoints https://<domain>/api-web/admin/catalogs/tenMytenant:contracts of the admin-controller.

...

The client uses the Web-API Gateway dms-controller endpoints that require the role YUUVIS_MANAGE_SETTINGS role in case of POST and PATCH requests: 

• The values for the catalog are read with the GET endpoint https://<domain>/api-web/dms/catalogs/tenMytenant:contracts.
  
• If the catalog does not exist, it is created with the POST endpoint https://<domain>/api-web/dms/catalogs/tenMytenant:contracts.
• If the catalog already exists, changes of its values are saved with the PATCH endpoint https://<domain>/api-web/dms/catalogs/tenMytenant:contracts.

Swagger

...

UI

There is a Swagger - UI that supports you in using the mentioned endpoints: https://<domain>/api-web/swagger-ui.html. The screenshot below displays a part of the Web-API Gateway Swagger - UI showing the first endpoints of the admin-controller.

...

Summary

In order to display a pick selection list of with pre-defined elements in metadata forms of your client, the corresponding property definitions have to be classified as dynamic catalogs. They can be global or tenant-specific. The dynamic catalogs can be configured to be editable or not editable for client users.