Defining Object Types for yuuvis® client
As of yuuvis® Momentum Version 2020 Autumn, the client supports the new 'floating' secondary object types that were introduced by the core system in the version before. This article is intended for administrators who configure various schema with such floating secondary object types to be used in yuuvis® client which is available as a reference implementation. It explains step by step which settings have which effects on the client.
Table of Contents
For information on how to manage yuuvis® client custom parts like localization files, forms or icons, please refer to the "Web-API Gateway (API-WEB)" article.
For information on how to model forms with scripts, please refer to the "yuuvis® architect" article. Schema modeling is not yet available in yuuvis® architect.
Definitions
The user will be handling different object types. The glossary below will give you an overview of the most important terms and their definition:
| Term | Short | Definition |
|---|---|---|
| Object | An object containing a set of system-specific basic metadata and depending on its object type contains custom metadata. There are two main types of objects: folders and documents | |
| Folder object type | A folder object can contain document objects but no folder objects. | |
| Document object type | Document objects can contain one file and can be filed into the general filing location or into one folder only. | |
| Object type | OT | Object types are defined in a schema by an administrator. Object types contain those attributes (fields) a user needs to search for a classified document. An object type can include secondary object types in the meaning of reuse. |
| Secondary object type | SOT | SOTs are grouping attributes that can be reused by several object types. SOTs cannot be used to instantiate an object but will become part of it. SOTs can be referenced statically or floating. |
| Floating secondary object type | FSOT | While a static SOT becomes part of the object when instantiated, a floating SOT can be extended later on and removed again as well. The concept of floating SOTs fits the import behavior where files are imported and a general object type with no or only a few custom fields is defined. After creation, a classification job analyses the file and assigns the specific FSOT to that object, so the object turns into an invoice, a delivery note, an order, etc. |
With respect to the client, some additional object types can be defined:
| Term | Short | Definition |
|---|---|---|
| Primary floating secondary object type | PFSOT | With respect to the above-mentioned import process, the user can specify object types manually. This means the user must be controlled in a way that he is only able to assign such object types that then become the leading object type. This means the initially used general object type is transformed to an invoice, order, etc. This object type is defined by the value A floating secondary object type must not be referenced by more than one objetc type to assure the form modeling (see below). |
| Required floating secondary object type | RFSOT | In case the user assigns a specific FSOT, e.g., invoice, order, etc., it may be necessary to assign some further FSOTs that do not become a leading object type as well, e.g., the client-specific defaults with title and description. This object type is defined by the value |
| Extendable floating secondary object type | EFSOT | While required FSOTs are automatically assigned together with the primary FSOT, extendable FSOTs can be assigned later on if necessary. Examples are general address data, e-mail address data, and approval process attributes. This object type does not need an extra |
Requirements and the Smallest Document
To be able to use object types in yuuvis® client, three important configurations are required:
- Referencing the
appClient:clientdefaultsobject type - Referencing the
appClientsystem:leadingTypeobject type - Managing the localization files
In addition, you can customize object-type-specific icons as well.
Referencing the appClient:clientdefaults Object Type
Each object type must reference the appClient:clientdefaults Secondary Object Type (SOT). This object type contains the two fields 'Title' and 'Description', which are used in mixed hit lists to identify objects, and in the header of the object details:
The availability of this object type is ensured by importing the Client app schema into the system during 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 resultlist 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>
The schema contains the two fields clienttitle and clientdescription, which are referenced by the clientdefaults secondary object type.
Furthermore, the schema contains the minidoc example object type, which only references the clientdefaults secondary object type, i.e., has no fields itself. In the standard localization, the 'Smallest document' object type is offered in the object types selection dialog:
Note: After deploying a schema it is necessary to localize all the technical names of the object types and fields as described here: Web-API Gateway (API-WEB)
When the object is created by the user, the two fields 'Title' and 'Description' are offered as mandatory fields in the creation form as defined above:
Note: The just selected file is not uploaded to the backend at this stage, so no preview can be shown within the browser while entering the metadata. The file is uploaded together with the metadata entered after a click <Create object>.
Referencing the appClientsystem:leadingType Object Type
Each object type must also reference the appClientsystem:leadingType secondary object type (SOT). This object type contains the appClientsystem:leadingTypeId quasi-system field. This field is used to show the user an object-type-specific icon and to support the permissions on objects.
The availability of this object type is ensured by importing the Clientsystem app schema into the system during installation.
<?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>
The appClient:leadingType object type cannot be used for searching and the appClient:leadingTypeId field cannot be used in forms. Therefore it is a quasi-system field with respect to the client. This field is filled by a webhook after CREATE and especially after the UPDATE of an object if a Floating Secondary Object Type (FSOT) has been assigned. The leading object type is then this assigned FSOT. More explanations will come later.
You may have understood that the minidoc object type that is part of the Client app schema references the appClient:leadingType as well.
Permissions for Leading Object Types
In case primary floating secondary object tpyes are used, and you want to control object access, you have to use the appClient:leadingType field in the role set definition, e.g.:
<role> <name>contract_read</name> <permission> <action>read</action> <condition>appClientsystem:leadingTypeId = 'appMyapp:contract'</condition> </permission> </role>
Configurations for Creating Objects While Seeing a Preview
The configuration of the smallest document comes with only two default fields 'Title' and 'Description.' During the object creation process a user does not see any preview of the document file next to the create form. Only after the user has finally created the object by clicking <Create object> the preview is available. To support your users at an earlier stage you can configure the system in a way that a preview is provided for certain object types during the creation.
To display the preview, it is necessary to upload the document file in a first step and then get the form and preview side by side in a second step. You need to configure a preparing object type that can be assigned one or more secondary object types. Our technical name for such object types is Floating Secondary Object Type. In order for a secondary object type to turn into a floating one you reference it with the attribute static = "false".
<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>
In this example the object type preemail references no field of its own. Beside the required appClientsystem:leadingType and appClient:clientdefaults (here also referenced as FSOT) the emailsot FSOT is referenced.
emailsot references the fields the user may need to handle e-mail objects.
Please note this requirement: emailsot needs a classification tag with the value appClient:primary. A short outlook for this: you can use a preparing object for more than one FSOT, but only one of the referenced ones should be assigned as the leading object type. You may think that you need several different object types within a personal file, e.g., one for the application, one for certificates, one for a sicknote, et,c. However, you may also realize that it does not make sense to assine more than one of the object types to the preparing object. Other FSOTs may be assigned additionally such as adress data or notices. With the primary classification, you can control to assign only one of the leadings types.
There are three other classification tags that have been used for the configuration of the preparing object preemail:
appClient:create:falseensures that this object type is not availble to users while creating an object.appClient:search:falseensure that this object type is not availble to users while searching an object.appClient:extension:remove:falseensure that this object type once extended cannot be removed by the user.
In this example, the preparing object is made invisible for the user. The only object type that can be used is the FSOT.
In other cases, you may want users to start with the preparing object type and to display the list of possible FSOTs in the second creation step, so that users can see the preview first and can then select the object type they want to assign.
And this is what users sees after the e-mail file was uploaded: the CREATE form next to the document file preview in the second creation step.
The form in this example is a custom form that can be modeled with the help of yuuvis® architect.
The data specified in this form is extracted from the e-mail file. How to model and how to script this, is explained in "Configurations for Specific Form Field Behaviors" heading below.
Configurations for Specific Form Field Behaviors
You can use the following classification tags to control the form field behavior in the client:
| Classification tag | Field type / Object tpye | Description |
|---|---|---|
email | string | An e-mail button is displayed that allows opening the installed e-mail client with the e-mail address specified. The entered value is validated with help of an internal browser function. Valid addresses are those following the standard specifications → wikipedia This e-mail field is displayed both in the Summary aspect and the result list column. Values like "Mike Johnson" <mike.johnson@mycompany.com> result in case rendering problems. Make sure that only 'mike.johnson@mycompany.com' is used. |
url | string | A URL button is displayed that allows opening the URL specified in a browser. The entered value is validated with the help of an internal browser function. Valid addresses are those following the standard specifications → wikipedia This URL field is displayed both in the Summary aspect and the result list column. |
phone | string | A phone button is displayed that allows opening the number specified in the phone application available. In the Chrome browser a connected Android phone can be used. No validation takes place. This phone field is displayed both in the Summary aspect and the result list column. |
id:organization | string | The organization field offers a list of found users while typing characters. The user ID is stored while the user name is shown in a chip. This field is displayed both in the Summary aspect and the result list column. |
| string | The reference field offers a list of found objects while typing characters. The object ID is stored while its title is shown in a chip. The object can be opened with a click on the anchor icon. If a referenced object does not have a title, its object ID is shown instead. A list of technical object type names allows filtering the possible results. An empty list allows searching all object types. This field is displayed in both the Summary aspect and the result list column. |
catalog[new,draft,review,released,rejected] | string | This is the configuration of a simple static catalog. Users of any tenant can only select the values specified in the list. Only one language is supported here. |
digit | number | If this tag is not specified, no digital grouping takes place. Otherwise, numbers are rendered with a delimiter as 123,456,789.35 instead of 123456789.35. |
| object type | Beginning with version 2020 Winter aka 2.4, system tags can be used for filtering and for display as a result list column in the reference client. Tags can be assigned to any object without any predefinition, so it is necessary to define them. Use a classification tag that is part of the object type definition you want to display the tag. Restriction: In the case of FSOTs you need to use the classification tag for each of them. Beginning with 2021 Autumn the classification tag specified for the object type that references the FSOTs is inheriting the classification tag. The values of tags can be localized. Tag values are numbers that are not meaningful to the user. yuuvis® architect provides a key for each tag and its value to be localized in the following format: mytagname, mytagname:0, ... mytagname:5. The tag name can contain only lower-case characters and ':', which allows you to use prefixes just like in app schemas. You can read about tagging of objects here: Tagging |