...

• The first parameter is the technical name that will be the displayed expression in the your client per default. It can be localized in order to replace the displayed expression. We recommend naming conventions described below that makes it easy to distinguish between tenant-specific and global catalogs.
• As second parameter readonly can be added. Thus, the pick-list catalog values will not be editable in the client or via the admin- contoller and dms-controller endpoints of the Web-API gateway as described below. Since the client uses the dms-controller endpoints, the corresponding pick-list elements in the client will also be not editable.

The catalog values are saved in a JSON file in the config server beside the corresponding schema configuration.

Tenant-Specific Dynamic Catalogs

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<tenant name>:<catalog name> ten<tenantname>:<catalogname>.

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 line 6 to be a a dynamic catalog that is displayed as a pick-list with the technical name tenMytenant:contracts in your client. Initially, the list of values offered to users will be empty. Since there is no readonly parameter within the value of the classification attribute, the pick-list will be editable in the client.

...

If the dynamic catalog should be available to all tenants, it has to be configured as global property. This means that the property definition classified as dynamic catalog has to belong either to the system schema or to an app schema. Its values are stored in the config server besides the global schema or the corresponding app schema.

For catalogs in an app schema we recommend the naming convention app<app name>:<catalog name><catalogname>. For catalogs in an app schema we recommend to use no extra prefix but only the catalog name <catalog name>.The Web-API Gateway GET endpoint that the client calls checks first whether <catalogname>.

Also global dynamic catalogs can be defined to be editable for users with the role YUUVIS_MANAGE_SETTINGS. If the modified catalog values are saved, a tenant-specific copy of the global JSON configuration is saved besides the tenant schema together with the global catalog does exist. If not the global catalog is readvalues of tenant-specific catalogs. Whenever a global catalog is retrieved via the Web-API gateway, the tenant-specific copy will be returned for that tenant. If no tenant-specific copy exists, the global configuration is returned. This might happen if the global catalog is not editable or no changes were applied to the global catalog within the active tenant.

Not-Editable Global Catalogs

...

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 the example app Myapplication, the property contract will 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-list for the field called appMyapplication:contracts.

	<propertyStringDefinition>
		<id>contract</id>
		<propertyType>string</propertyType>
		<cardinality>single</cardinality>
		<required>false</required>
        <classification>dynamic:catalog[appMyapplication:contracts,readonly]</classification>
	</propertyStringDefinition>

...

The following code block shows an example property definition cut from an example system schema.

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, the property contract will be available in all tenants and for all applications. After restarting your client, the users will get an empty pick-list for the field called contracts.

	<propertyStringDefinition>
		<id>contract</id>
		<propertyType>string</propertyType>
		<cardinality>single</cardinality>
		<required>false</required>
        <classification>dynamic:catalog[contracts,readonly]</classification>
	</propertyStringDefinition>

...

If the catalog parameter readonly is not set, users with the role YUUVIS_MANAGE_SETTINGS 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: From now on changes made in  Changes of the global catalog are not affecting the copy. Only new tenants will get the new list elements of the global catalogsaved by a user with the role YUUVIS_SYSTEM_INTEGRATOR do not affect the copy.

Editing Catalog Values

The following actions are supported for editable catalogs / pick-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 creating or editing an object.

...

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

The catalog data is saved in the config server beside the tenant schema configuration.The format of the catalogs is JSON. The following example shows a tenant-specific list of four elements stored for the tenant Mytenant:

{
  "tenant": "Mytenant",
  "entries": [
    {
      "name": "Employment contract",
      "disabled": false
    },
    {
      "name": "Rental agreement",
      "disabled": false
    },
    {
      "name": "User contract",
      "disabled": false
    },
    {
      "name": "Purchase contract",
      "disabled": false
    }
  ]
}

dms-controller

The client uses the Web-API Gateway dms-controller endpoints that require the role YUUVIS_MANAGE_SETTINGS: 

• 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.

system-controller

In case of global catalogs, the Web-API Gateway system-controller endpoints GET and POST are used. The role YUUVIS_SYSTEM_INTEGRATOR is required.

• For the catalog contracts in the system schema: https://<domain>/api-web/system/catalogs/contracts
• For the catalog contracts in the app schema businesspartner: https://<domain>/api-web/system/catalogs/appMyapplication:contracts?appschemaname=appMyapplication

Global catalogs without an appschemaname are saved in the config-service beside the system schema configuration. Otherwise, the catalogs are saved besides the app schema configurations.

dms-controller

The client uses the Web-API Gateway dms-controller endpoints: 

...

.

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.

...