...

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. By setting or not setting the property readonly in In their schema definition, they can be configured to be editable or not directly in your client  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 into the Web-API gateway 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 elements can't values (corresponding to list elements) cannot be localized.
• The elements of a list can't list elements cannot 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[<catalog name>] for the attribute classification. Per default, the catalog name will be used as display name in your client. It can be localized in order to replace the display name. We recommend using naming conventions as described below which make it easy to distinguish between tenant-specific and global catalogs.

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

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 selection list elements in the client will also not be 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 empty selection lists in your client, we recommend to create the JSON configuration of the catalog first and introduce the definition into the schema afterwards.

Tenant-Specific Dynamic Catalogs

If only one specific tenant will use a dynamic catalog, it is recommended to configure this catalog with as a classification-tag for the field that should contain one of its values. tenant-specific property. Its technical name should follow the naming convention ten<tenantname>:<catalogname>. A user with access to the Admin Endpoints and admin-controller Endpoints (default: user with the 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  The property is available only within the tenant Mytenant. The property is classified by classified in line 6 to be a a dynamic catalog that which is displayed as a selection list with the technical name name tenMytenant:contracts in your client. Initially, the list of values offered to users will be empty.

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

Upload the If the example schema is uploaded as a tenant schema via the endpoint POST /api/admin/schema as  endpoint by a user of the tenant Mytenant. After uploadingexample 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 that field. A user with the role YUUVIS_MANAG_SETTINGS can maintain this list. The following actions are supportedselection list for the field called tenMytenant:contracts.

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. 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<appname>:<catalogname>. For global catalogs, we recommend to use no special prefix but only the catalog name <catalogname>.

Also global dynamic catalogs can be defined to be editable for users with the advancedUserRole (default: users with the YUUVIS_MANAGE_SETTINGS role). 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 values 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

Users user with access to the System Endpoints and system-controller Endpoints (default: users with the 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 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 POST /api/system/apps/{app}/schema endpoint for the example app myapplication, the property contract will not only be available for the specific app myapplication, but to all tenants using this app. After restarting your client, the users will get an empty selection 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]</classification>
	</propertyStringDefinition>

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 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 selection list for the field called contracts.

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

Editable Global Catalogs

If the catalog parameter readonly is not set, users with the advancedUserRole (default: users with the 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 via system-controller do not affect the copy.

Editing Catalog Values

The following actions are supported for editable catalogs/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 advancedUserRole (default: users with the role YUUVIS_TENANTMANAGE_ADMIN SETTINGS role) can maintain the dynamic catalog contracts using the 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 icon next to the field. The screenshot below shows the edit dialog for the example selection list contracts where the four values Employment contract, Rental agreement, User contract, and Purchase contract were already added.

Image Added

Editing via Web-API Gateway

admin-controller

Users with access to the admin-controller Endpoints (default: user with the 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 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 Mytenantmytenant:

{
  "tenant": "Mytenant",
  "readonly" true,
  "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:

Image Removed

...

system-controller

In case of global catalogs, the Web-API Gateway system-controller endpoints GET and POST are used. In the default configuration, 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 myapplication: https://<domain>/api-web/system/catalogs/appMyapllication: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 that require per default the YUUVIS_MANAGE_SETTINGS role in case of POST and PATCH requests: 

• The list elements from 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 does exist already exists, changes of its list elements 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

Image Removed

Picture: Screenshot with . The screenshot below displays 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:

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

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

Image Added

Summary

In order to display a selection list 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 for client users.

Image Added