Dynamic catalogs are introduced with version 2021 Summer at the latest. Beginning with 2021 Summer Alpha2, the Web-API Gateway offers the endpoints for maintaining such catalogs, and the users are offered a pick-up list including an edit dialog if the property readonly is not set.

These catalogs are named dynamic because they can be changed by responsible users without changing the schema configuration.

In the following, the different use of such dynamic catalogs is described.

Hints:

The catalog elements can't be localized.
We use the term catalog from a technical perspective and the term list from the user's perspective.
The elements of a list can't be manipulated by client form scripting.

Dynamic catalogs used by a specific tenant

If only a specific tenant will use a dynamic catalog it is recommended to configure this catalog with a classification-tag for the field that should contain one of its values:

Schema excerpt example of a field of type string of classification dynamic catalog

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

After uploading the tenant-schema 'Mytenant' the user will get an empty pick-list for that field. A user with the role YUUVIS_MANAG_SETTINGS can maintain this list:

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.

An administrator with the role YUUVIS_TENANT_ADMIN can maintain the dynamic catalog contracts using the Web-API Gateway GET and POST 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 list of four elements stored for the tenant Mytenant:

Example for a tenant-specific dynamic catalog

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

The user with edit rights can open this dialog after click onto the pencil at the field:

Picture: screenshot of the client dialog for editing the pick list contracts

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

The list elements from 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 does exist changes of its list elements are saved with the PATCH endpoint https://<domain>/api-web/dms/catalogs/tenMytenant:contracts.

There is a Swagger -UI that supports you in using the mentioned endpoints: https://<domain>/api-web/swagger-ui.html

Picture: Screenshot with a part of the Web-API Gateway Swagger-UI showing the first endpoints of the admin-controller with

Set a catalog to read-only

If a catalog should be stable after setting it up, the parameter readonly can be set into the classification-tag, e.g.:

<classification>dynamic:catalog[tenMytenant:contracts,readonly]</classification>

Global dynamic catalogs used by all tenants

In this case, your tenants should use object types that are configured in a system or app-schema and should use only standard values an administrator with the role YUUVIS_SYSTEM_INTEGRATOR can set up global catalogs with initial standard elements and set the catalogs readonly.

Recommendation: In an app-schema, use the prefix of the application for your catalog name as given here:

Schema excerpt example of a field of type string of classification dynamic catalog

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

Recommendation: In the system-schema, use no perfix for your catalog name as given here:

Schema excerpt example of a field of type string of classification dynamic catalog

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

In this case the Web-API Gateway system-controller endpoints GET and POST are used.

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.

The Web-API Gateway GET endpoint that the client calls checks first whether a tenant-specific copy of the global catalog does exist. If not the global catalog is read.

Editable global catalogs

If the catalog parameter readonly is not set users with the role YUUVIS_MANAGE_SETTINGS can change the list elements. With the first update of such a catalog, a new catalog with the same technical name is saved for that tenant.

Note: From now on changes made in the global catalog are not affecting the copy. Only new tenants will get the new list elements of the global catalog.

Managing dynamic catalogs

Dynamic catalogs used by a specific tenant

Global dynamic catalogs used by all tenants