...

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 their schema definition, they can be configured to be 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 so-called dynamic catalogs.

...

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

Dynamic Catalogs used by one specific Tenant

If only one specific tenant will use a dynamic catalog, it is recommended to configure this catalog with a the attibute classification-tag for the field that should contain one of its values. 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 line 6 to be a a dynamic catalog that is displayed as a pick-list with the technical name name 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  by a user of the example tenant Mytenant, the property contract will be available only in the specific tenant Mytenant. After uploadingrestarting your client, the users will get an empty pick-list for that field. A user the field called tenMytenant:contracts.

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 attribute, e.g.:

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

Editing via Client

Users with the role YUUVIS_MANAGMANAGE_SETTINGS can maintain this list. 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.

...

• .

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 already four values Employment contract, Rental agreement, User contract and Purchase contract were already added.

Image Added

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.

Editing via Web-API Gateway

Users with the role YUUVIS_TENANT_ADMIN can maintain the dynamic catalog contracts using the are offered the same maintenance actions via the Web-API Gateway GET and POST endpoints , POST and PATCH endpoints: https://<domain>/api-web/admin/catalogs/tenMytenant:contracts of the admin-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

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:

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

Image Removed

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

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>

...

Image Added

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. 

...