Set up schemata defining properties and object types including classifications that are specifically designed for a client application based on the developer libraries.

Introduction

In yuuvis® Momentum, documents are stored as document objects. The business integrator defines one or more object types and their properties according to specific needs. Any document imported will need to be classified as exactly one of the object types defined in the schema of the system. Before you continue reading through client-specific classifications, please have a look at the general structure of valid schemata for yuuvis® Momentum.
>> Schema - Defining Object Types

This article describes the usage of the classification attribute in property and object type definitions for a library-based client.

Localization

All property and object type IDs that should appear in your client have to be localized in order to replace the display of the technical IDs.
>> Localization for Clients

Secondary Object Type Classifications

This chapter relies on knowledge about the usage of Secondary Object Types (SOTs). Here, we consider only SOTs that are referenced as floating (FSOT). Those FSOTs can be assigned to objects during their lifecycle and removed again as well. Thus, additional metadata properties can be assigned to objects at any time, independent of the creation process. Clients based on our developer libraries use this concept to allow for a multi-step object creation process. It is possible to create objects having a general object type with only a few properties. After creation, either the user or a classification job analyses the object (and its binary content file if available) and selects a suitable FSOT that lets the object appear with a leading object type describing the business scope (invoice, delivery note, order, ...) and/or inserts appropriate properties.

By adding a specific classification attribute to their definition, it is possible to induce a particular behavior in your client. The following table introduces the classifications of SOTs you can use in your schemata.

Classifications available for all Object Types

This chapter relies on knowledge about the definition of object types. By specifying one of the following values for the classification attribute, it is possible to induce a particular behavior in your client.

Default 'client' and 'clientsystem' App Schemata

A library-based client is handled via two apps called client and clientsystem in yuuvis® Momentum. Both apps have their own app schema. They have to contain the definition of the following two RFSOTs that have to be referenced in all object type definitions:

• appClient:clientdefaults – This SOT contains the properties clienttitle and clientdescription and appends them to each object to which it is assigned. Thus, all objects with a PFSOT have those two properties which makes them perfect for use in mixed hit lists.
• appClientsystem:leadingType – This SOT contains the property leadingTypeId and appends it to each object to which it is assigned. It identifies the PFSOT from the client application's point of view.

Per default, the app schemata already contain these two RFSOTs after installation.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<schema xmlns="http://optimal-systems.org/ns/dmscloud/schema/v5.0/">
	<propertyStringDefinition>
        <id>clienttitle</id>
        <propertyType>string</propertyType>
        <cardinality>single</cardinality>
        <required>true</required>
        <maxLength>200</maxLength>
    </propertyStringDefinition>
    <propertyStringDefinition>
		<id>clientdescription</id>
		<propertyType>string</propertyType>
		<cardinality>single</cardinality>
		<required>true</required>
		<maxLength>200</maxLength>
	</propertyStringDefinition>
    <typeDocumentDefinition>
        <id>minidoc</id>
        <baseId>system:document</baseId>
        <contentStreamAllowed>allowed</contentStreamAllowed>
        <secondaryObjectTypeId>appClientsystem:leadingType</secondaryObjectTypeId>
        <secondaryObjectTypeId>appClient:clientdefaults</secondaryObjectTypeId>
    </typeDocumentDefinition>
	<typeSecondaryDefinition>
		<id>clientdefaults</id>
		<description>contains title and description fields mainly for mixed hit list and object header</description>
		<baseId>system:secondary</baseId>
		<propertyReference>clienttitle</propertyReference>
		<propertyReference>clientdescription</propertyReference>
        <classification>appClient:required</classification>
        <classification>appClient:create:false</classification>
	</typeSecondaryDefinition>
</schema>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<schema xmlns="http://optimal-systems.org/ns/dmscloud/schema/v5.0/">
    <propertyStringDefinition>
		<id>leadingTypeId</id>
		<propertyType>string</propertyType>
		<cardinality>single</cardinality>
		<required>false</required>
	</propertyStringDefinition>
	<typeSecondaryDefinition>
		<id>leadingType</id>
		<description>contains the field that supports a better use of FSOTs</description>
		<baseId>system:secondary</baseId>
		<propertyReference>leadingTypeId</propertyReference>
        <classification>appClient:create:false</classification>
        <classification>appClient:search:false</classification>
	</typeSecondaryDefinition>
</schema>

Impact of 'appClient:clientdefaults'

 As you can see in the default schema above, the RFSOT provides the two properties clienttitle and clientdescription which are used in mixed hit lists to identify objects by Name and Description as well as in the header of the object details.

Impact of 'appClientsystem:leadingType' 

This RFSOT provides the property appClientsystem:leadingTypeId. The value for this property is set via a webhook (see SOTHOOK) as soon as a PFSOT is assigned to an object. Based on the value specified in this property, the client application identifies the leading object type and displays a corresponding icon.

Furthermore, it is possible to configure permissions for individual leading object types by specifying conditions for the appClientsystem:leadingTypeId in your role set. An example role is shown in the following code block.

<role>
		<name>contract_read</name>
		<permission>
			   <action>read</action>
			   <condition>appClientsystem:leadingTypeId = 'appMyapp:contract'</condition>
		</permission>
</role>

The appClient:leadingType object type cannot be used for searching and the appClient:leadingTypeId field cannot be used in forms.

'minidoc' Example Object Type

The default client schema contains the minidoc example object type, which only references the two RFSOTs appClient:clientdefaults and appClientsystem:leadingType. In the English default localization, it is offered as Smallest document in the Restrict to object types dialog:

After selecting the Smallest document object type, a binary content file can be added to the object. This is possible because the contentStreamAllowed property is set to allowed in the minidoc object type definition. Then, the Create form is displayed in which the new object's metadata have to be entered. Here, the two referenced properties clienttitle and clientdescription are available. Per default, their labels are Title and Description:

The creation of the new object is completed by clicking the Create object button. Any binary content files added to the object will then be imported to the yuuvis® Momentum system.

Configuring the Content Preview for the Creation Dialog

In yuuvis® Momentum, the binary content file assigned to an object can be accessed as soon as the object creation is finished successfully. If a preview of the binary content file should be displayed for users, the corresponding object has to exist already. However, you might want to provide a preview of the binary content file already within the object creation dialog. For this purpose, at first, your client application has to create the object with the desired binary content file assigned to it. A generic document object type can be used. If this process is automatized by the client application, the user dialog for object creation can now display the content preview to make the users' decision for a PFSOT and/or the corresponding property values easier.

In the following example code block, a generic document object type preemail and a characterizing PFSOT emailsot are defined. The preemail object type is not offered to users in the object creation dialog. It does not reference any properties directly, but it references the appClientsystem:leadingType, appClient:clientdefaults and emailsot SOTs. The emailsot PFSOT references the properties users may need to handle e-mail objects.

	<typeDocumentDefinition>
		<id>preemail</id>
		<description>...</description>
		<baseId>system:document</baseId>
        <classification>appClient:search:false</classification>
        <classification>appClient:create:false</classification>
		<contentStreamAllowed>required</contentStreamAllowed>
        <secondaryObjectTypeId>appClientSystem:leadingType</secondaryObjectTypeId>
        <secondaryObjectTypeId static="false">appClient:clientdefaults</secondaryObjectTypeId>
        <secondaryObjectTypeId static="false">emailsot</secondaryObjectTypeId>
    </typeDocumentDefinition>
    <typeSecondaryDefinition>
        <id>emailsot</id>
        <baseId>system:secondary</baseId>
		<propertyReference>from</propertyReference>
		<propertyReference>to</propertyReference>
		<propertyReference>cc</propertyReference>
		<propertyReference>subject</propertyReference>
		<propertyReference>hasattachment</propertyReference>
		<propertyReference>attachmentnames</propertyReference>
		<propertyReference>received</propertyReference>
        <classification>appClient:primary</classification>
    </typeSecondaryDefinition>

The client application automatically uses the preemail type to create the object after users have selected a binary content file. In a second step in the object creation dialog, the content preview is displayed to the users who can now read it in order to specify the properties provided by the emailsot PFSOT. The following screenshot shows an example for a CREATE form modeled in yuuvis® architect on the left, next to a content preview on the right. The data specified in this form is extracted from the e-mail file. The next section describes how to model and script this automatic metadata extraction.

Property Classifications

You can use the following values for the classification attribute in property definitions of the suitable types to control the form field behavior in your client application. The corresponding controls can be added to the Summary aspect area, edit and create forms, hit lists, and filters.

Value for 'classification'	Property Type	Description
email	string	An e-mail icon is displayed beside the form field. A click on the icon opens the locally installed e-mail client with the e-mail address specified. The entered value is validated via an internal browser function. Valid addresses have to match the standard. Note: Values like "Mike Johnson" <mike.johnson@mycompany.com> result in case rendering problems. Use only mike.johnson@mycompany.com instead.
url	string	A URL icon is displayed beside the form field. A click on the icon opens the specified URL in a browser. The entered value is validated via an internal browser function. Valid addresses have to match the standard.
phone	string	A phone icon is displayed beside the form field. A click on the icon opens the specified number in the available phone application. In Chrome, a connected Android phone can be used. No validation takes place.
id:organization (as of 2022 Spring) id:organization[APPROVER1,APPROVER2] (as of 2022 Summer) id:organization[APPROVER1,APPROVER2,username1] (as of 2023 Spring)	string	Useful for properties that store a user ID and appear with the corresponding user name. As soon as users start typing in the form field, a selection list with user names is provided for which the entered term was found in the user name, name, surname or e-mail address. If users select one of them, the corresponding user ID is stored as property value while the user name is shown in the form as a chip. If roles are specified, only user names of users having at least one of those roles are offered for the corresponding form field.
id:reference[] id:reference[myObjectTypeId,...]	string	Useful for properties that store an object type ID or an object ID and appear with the corresponding object type or object name. As soon as users start typing in the form field, a selection list with matching object type or object names is provided. If users select one of them, the corresponding object type ID or object ID is stored while the name is shown in the form as a chip. If no name is available, the ID is displayed instead. For object ID property fields, an Anchor icon is additionally displayed beside the form field. A click on this icon opens the referenced object. For object type ID property fields, it is possible to limit the object types that are offered to users in the selection list. For this purpose, specify all object type IDs to be considered in the classification attribute. An empty list allows all object types. Note: It is not possible to specify base types (system:object, system:folder, system:documents).
catalog[new,draft,review,released,rejected]	string	Configuration of a static catalog. Users can only select the values specified in the list. Only one language is supported here.
Pattern to be used in the global schema: dynamic:catalog[myObjecttype,readonly] Pattern to be used in an app schema: dynamic:catalog[appMyapp:myObjecttype,readonly] Pattern to be used in a tenant schema: dynamic:catalog[tenMytenant:myObjecttype,readonly]	string	Configuration of a dynamic catalog that can be maintained per tenant. Users can only select the values specified in the list. Users with the YUUVIS_MANAGE_SETTINGS role can deactivate and remove values or add new values if the optional parameter readonly is NOT set. Only one language is supported here. The catalog values are stored separately for each tenant. It is possible to set up standard values for each catalog using a specific system controller endpoint of the Web-API Gateway. If no tenant-specific variant has been saved so far, the standard values are used. >> Maintaining Dynamic Catalogs
custom:catalog[myURL]	string	Retrieves the catalog values from a custom microservice that is called via the specified URL. The URL can be absolute (e.g., https://mydomain/myservice/myfunction?myparameter=mycatalogname) or relative (e.g., /myservice/myfunction?myparameter=mycatalogname). Note:  If an absolute URL is used, ensure to handle CORS issues. The internal token with the user information is transferred to the microservice. The language set by the user can be read from the header. The response format must have the following JSON structure: { "entries": [ {"name": "Bill", "disabled": "false"}, {"name": "Ted", "disabled": "false"} ]; }
digit	number	Numbers are rendered with a delimiter, e.g., 123,456,789.35. Otherwise, no digital grouping is used, e.g., 123456789.35.
sortable	table	Enables the user to sort table rows manually by drag & drop.
switch	boolean	Values are represented by a switch with the available positions true (right position), false (left position) and null (middle position). Per default (if switch is not specified), the values for boolean properties are displayed as checkboxes. A null value is represented as crossed-out box.
appClient:standardform:hidden	any type	The property is not displayed in any standard form by the client application.
appClient:summary:hidden (as of 2022 Summer)	any type	The property is not displayed in the summary aspect area of objects displayed by the client application.

Summary

A client based on our developer libraries requires some specific definitions and configurations in its schemata. The classification attribute is used to manage the handling of individual object types and properties.