Explanation of the usage of dynamic catalogs provided by the Web-API Gateway as editable pick-up lists in metadata forms.

Introduction

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.

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.

Notes:

• 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) can't be localized.
• The list elements can't be manipulated by client form scripting.

Defining Dynamic Catalogs

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[<parameters>] for the attribute classification. Two comma-separated string parameters are accepted:

• 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 will not be editable in the client or via the admin-contoller of the Web-API gateway as described below.

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

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.

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

If the example schema is uploaded as a tenant schema via the endpoint POST /api/admin/schema 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-list for the field called tenMytenant:contracts.

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

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

Global Dynamic Catalogs

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.

For catalogs in an app schema we recommend the naming convention app<app name>:<catalog name>. 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 a tenant-specific copy of the global catalog does exist. If not the global catalog is read.

Not-Editable Global Catalogs

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

In this case you should 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.

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

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

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.

Editing Catalog Values

The following actions are supported:

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

Editing via Client

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

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

Editing via Web-API Gateway

admin-controller

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
    }
  ]
}

system-controller

In case of global catalogs, 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.

dms-controller

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.

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.