Define form settings for presentation of metadata in a client's graphical user interface.

Introduction

The Forms tile is available on the dashboard for users with the YUUVIS_TENANT_ADMIN or YUUVIS_SYSTEM_INTEGRATOR roles.

You can model the Metadata aspect area in CREATE and EDIT forms that are offered in your client to view and edit metadata. It also possible to combine the form modeling with situation-specific scripts. To check the current layout during modeling, yuuvis® architect provides a form preview presenting the modeled metadata form as it will appear in your client.

The labels displayed in the metadata forms for the client can not be customized in the form modeler, but by means of the Localization sub-tool of the yuuvis® architect.

The yuuvis® Momentum Schema

All work with yuuvis® Momentum begins with a data model – the yuuvis® Momentum schema. The schema is used to define object types via which users create and manage business objects. It is part of the yuuvis® Momentum core and can be accessed or modeled only via the corresponding core endpoints.

>> Schema - Defining Object Types

The schema is divided in three parts that can be customized independently by means of separate endpoints. Thus, permissions can be set for customizing the individual parts.

• The system schema is a global part. The object types defined in here can be used by all tenants and applications.
  → yuuvis® architect: Modeling of metadata forms is possible only with the role YUUVIS_SYSTEM_INTEGRATOR.
• An app schema contains object types for one specific application. If necessary, multiple application schemata can be defined. The object types defined in the application schemata can be used by all tenants.
  → yuuvis® architect: Modeling of metadata forms is possible only with the role YUUVIS_SYSTEM_INTEGRATOR.
• A tenant schema contains object types for one specific tenant. A user cannot use objects types defined in a tenant schema not belonging to the own tenant.
  → yuuvis® architect: Modeling of metadata forms is possible only with the role YUUVIS_TENANT_ADMIN.

Note: The roles used by the yuuvis® architect are not defined in the schema but in a tool-specific role set. This role set is required also for the yuuvis® client. However, yuuvis® Momentum allows you to define your own roleset, but then you will not be able to use the yuuvis® architect tool or the yuuvis® client.

Object Types

An object type identifies a business object by means of specific metadata which can be used to find and identify the object. Metadata describes the properties of a business object. For example, an invoice document is defined by its invoice date, invoice number, and vendor/customer. The properties are defined and assigned to the object types in the schema.

The object types are defined in the schema as one of those three basic object types: document, folder and secondary object type. A business object can be instantiated only from a document object type or a folder object type, but not from a secondary object type.

Document and folder object types

From document and folder object types defined in the schema, document and folder objects (short documents and folders) can be instantiated. Those objects have the properties that are assigned to the object type in the schema from which they are instantiated. Documents and Folders in the system can be found via their metadata.

Document object types enable the instantiated documents to include a document file in addition to metadata. Document files can be text files, e-mails, image files, etc. Documents can reference a folder to be its parent.

Folder object types enable the instantiated folders to be the parent of multiple documents in the system. Each document can be contained in one parent folder only.

In a document or folder object type definition, multiple secondary object types can be referenced.

Secondary Object Types

Secondary object types are abstract object types. No business objects can be instantiated from secondary object types. However, they act as groups of properties that can be referenced in multiple document and folder object type definitions. Thus, the properties for secondary object types can be available also for the referencing object types. These additional properties are included in the search as well.

The reference on a secondary object type in a document or folder object type definition can be either static or floating.

• The properties of static secondary object types are automatically assigned during the creation of any instance of the referencing document or folder object type. They are available for the instantiated objects for their whole lifetime.
• The properties of floating secondary object types are assigned to an instance of the referencing document or folder object type only on request. They can be added to an object or removed at runtime independently on the creation process.

Floating secondary object types in the yuuvis® architect

In contrast to static secondary object types, floating secondary object types can be handled in a flexible way during the import or at runtime for already existing documents or folders with an update. The concept of  floating secondary object types fits the import behavior where files are imported as documents of a general document object type with no or only a few defined metadata properties. After creation, a classification job analyses the document and assigns specific floating secondary object types to that document providing the typical properties of a specific business object like an invoice, a delivery note, an order, etc.

In order to be able to assign a floating secondary object type, it has to be referenced as floating in the corresponding document (or folder) object type definition.

Note: A floating secondary object type must not be referenced by more than one object type to assure the form modeling.

The operating principle of the yuuvis® Momentum architect is based on a classification of the secondary object types. Floating secondary object types referenced in a document or folder object type definition can be given a classification tag appClient:primary or appClient:required.

Classification 'primary'

With respect to the above-mentioned import process, the user can specify business types for an object manually by means of assigning a floating secondary object type. Here, the choice is between primary-classified floating secondary object types, characterized by the appClient:primary classification tag. All of them need to be referenced as floating in the corresponding object type definition in the schema. After importing an object with the general object type, exactly one of those secondary object types can be selected. Thus, the business type of the object will be determined by assigning its metadata: a specific business type name like invoice, order, etc. and a corresponding description.

During runtime, only one secondary object type with this classification can be assigned to an instantiated object.

Whenever one of the referenced primary-classified floating secondary object type is assigned, all required-classified floating secondary object types referenced in the same object type definition are assigned at the same time.

Classification 'required'

Business objects may need more metadata properties than provided by the initial general object type together with the user-selected primary-classified floating secondary object type. With the floating secondary object types classified as required by the appClient:required classification tag, additional metadata properties are assigned automatically together with the assignment of any primary-classified floating secondary object type. The assignment of multiple required-classified floating secondary object types is allowed.

Extending Types without Classification

In the schema, secondary object types can be defined without any classification primary or required. Nevertheless, they can be referenced as floating secondary object types in an object type definition. Thus, they allow for the user to assign additional metadata independently on other secondary object types. They can also be assigned or removed later on if necessary. Examples are general address data, e-mail address data, and approval process attributes.

Types for Business Objects

Any business object in the yuuvis® system needs an object type - either a document or a folder object type. The document or folder object type can reference static secondary object types. Thus, any instance of the document or folder object type is provided with a set of metadata coming from the final object type definition and a set of metadata coming from the referenced static secondary object type.

The assignment of a primary-classified floating secondary object type makes an object appearing with a specific business pseudo-type determined by the properties of the primary-classified floating secondary object type.  Since all referenced required-classified floating secondary object types are assigned at the same time, the object has now a fixed set of metadata containing the properties of the original general object type from the creation, the assigned primary-classified floating secondary object type and from the assigned required-classified floating secondary object types. This set of metadata will be the same for any object to which the corresponding primary-classified floating secondary object type is assigned. Thus, you can consider them as pseudo-types you can choose for your business objects. They are identified by the title property of the primary-classified floating secondary object types.

Modeling Forms for Metadata

In your client, the properties of your business objects are presented in different aspect areas. The properties provided by document an folder object types themselves are displayed in the summary aspect area that can not be customized in the yuuvis® architect. However, the properties provided by assigned secondary object types are displayed in the metadata aspect area which can indeed be customized. For each type of your business objects, you can customize separate forms in the yuuvis® architect for the Create and Edit working scenarios. For example, you can hide fields from an edit form that are only necessary to create an object. The corresponding form is provided to the user in the yuuvis® client accordingly.

You can use default forms if you don’t want to create custom forms. These forms are generally sufficient for technical data transfers.

Depending on your roles, you have different permissions. You can model only the metadata forms for which you are authorized by your roles. With the YUUVIS_TENANT_ADMIN role only object types defined in the tenant schema will appear in the architect. With the YUUVIS_SYSTEM_INTEGRATOR role only object types defined in the global system and app schema will appear in the architect.

In general, metadata aspect area forms consist of a form model with arranged groups of fields and optionally a script for manipulating field values. The following instructions will help you to customize the forms displaying metadata in your client in case of an object edit or creation.

• Click the Forms tile to open view for the form modeling. Alternatively, click the menu button on the top left and choose Forms. 

• In the column Select object type, find a tree to navigate through all object types for which you have the permission to model the metadata forms.
  

  Node	Content	Required Role
  Application	Further nodes are displayed, each of them corresponds to one specific application with an own app schema. Each node contains types defined in the specific app-schema: Document and folder object types. Pseudo-types determined by a primary-classified floating secondary object type.	YUUVIS_SYSTEM_INTEGRATOR
  Extending Types	Floating secondary object types without the classification primary or required defined in the system schema, the app schema or the own tenant schema.	For system and app schema: YUUVIS_SYSTEM_INTEGRATOR For tenant schema: YUUVIS_TENANT_ADMIN
  System	Types defined in the system schema: Document and folder object types. Pseudo-types determined by a primary-classified floating secondary object type.	YUUVIS_SYSTEM_INTEGRATOR
  Tenant	Types defined in the own tenant schema: Document and folder object types. Pseudo-types determined by a primary-classified floating secondary object type.	YUUVIS_TENANT_ADMIN

• Click either EDIT in order to customize the edit form or CREATE in order to customize the create form displayed in your client. In the case you have saved a model for EDIT but not for CREATE, you are asked whether to reuse the EDIT model for CREATE as well.

The browser window is now divided in 3 areas: On the left a building set area, the Model tree and the Layout area. After the click onto a field in the Model tree or Layout area, an additional Properties area is opened on the right-hand side.

Building set area

The left-hand area is now showing the selected type and the kind of form (EDIT or CREATE) you are currently modifying. Below, you can find a list of all available elements you can use to build up your metadata aspect area form. On the top, there are two structuring elements: Group and GroupStack. Below, metadata properties are listet that are always assigned to the selected object type via the secondary object types. All these properties will be assigned to each object of this business object type, independently of the form of presentation.

The properties are characterized by their name that will be displayed in the form, by their data type in italic (-string-, -boolean- etc.) and by their schema-intern property ID in small letters below.

If a property is displayed in grey letters, it is already part of the metadata form for your client.

If a property is displayed in white letters, it is currently not part of your form presenting the metadata in your client. You can drag and drop the property into the Model tree area.

Note: Properties provided by the document or folder object type itself are not available for form modeling. However, they are always assigned to all instances of the corresponding object type and are provided in the summary aspect area in the client.

Model tree area

In this area you define the structure of your metadata aspect area form. By means of drag and drop, you add elements from the building set on the left. You can arrange the form elements using drag and drop to design groups and compositions of properties. Click x to delete unwanted GroupStacks, Groups, and properties from the form. Properties, groups and compositions can be rearranged by drag and drop within a form.

By default, form layouts are organized into a Main Area for the most important metadata and a Data Area. This layout structure is optional. You may only use the Main Area. Later in time, the Data Area should be used for grouping the metadata within the summary aspect of the object details in yuuvis® client.

All Groups and GroupStacks in the model tree can be collapsed or expanded for a better overview.

You can use the buttons Import and Export in order to download your form model as JSON file and import it later on again. The file can be used only for the specific object type. During import, the file is validated and specific errors are reported.

The button Clear model removes all properties from the Model tree together with allmost all Groups and GroupStacks. Only the Group Main Area and the GroupStack Data Area remain.

Save your form via Save and thus apply it to your client.

Group

Groups combine properties and group them visually. Properties whose contents are related, can thus be logically combined (e.g., a person’s name, contact details, and postal address, etc.) like in an address book entry. The corresponding fields in the form will be visually grouped by means of background color and layout.

Elements within a group are arranged vertically by default. In order to arrange them horizontally, go to the Properties area and choose Row instead of Column.

For example, you can arrange a person’s first and last name next to each other in the first row in an address book entry and place the contact details below in a block with entire lines.

In the Properties area, you can give groups a unique identification key. This key is required in order to display a label for the Group in your form. Customize the labels via Localization. If not specified in the corresponding localization configuration, the identification key will be displayed in the metadata form.

GroupStack

GroupsStacks combine several groups. Groups combined via GroupStack are shown as tabs within the GroupStack area. The name of the Groups in a GroupStack is shown as title of the tabs.

The Data Area is per default an empty GroupStack. Thus, no property fields can be arranged here outside of groups.

Layout area

In this area you can see the properties as fields displayed in their Groups and GroupStacks. The arrangement corresponds to the structure defined in the Model tree. If you select an element in the Model tree, it will be highlighted in the Layout. The highlighting of elements within a GroupStack will be visible only if the corresponding tab is selected.

The Layout area displays an overview of the structure and does not distinguish between arrangement in rows or columns.

Via Open form preview you can have a look at your model as it will look like in your client.

Via Open script you can open a scripting window providing further form modeling possibilities. Thus, yuuvis® architect makes it possible to assign situation-specific scripts to the current form. As a scripting support, IntelliSense is available: Click Copy to clipboard on the left corner to choose a technical field name. Add the selected string surrounded with the correct syntax to your script at the position of your cursor via Ctrl + V.
>> Form Scripting (Client-side)

Properties area

After the click onto any element in the Model tree or Layout area, an additional Properties area is opened on the right-hand side. Information on the selected element is provided here.

On the top, the name and element type is displayed in a first block.

The second block below differs for the types of elements:

• For a single property field, you can tick or untick the checkbox Read-only in order to define the behavior in the client. For a string property, you can modify the number of Lines that will be provided for the property field in the client.
  Under Schema you can see the settings of the property definition for the selected property.
• For a table property, you get the Read-only checkbox together with the Schema settings of the property definition, too. Additionally, an overview of the available columns is provided. They are named with their identification key and their type (string etc.). By clicking one of them, you can define for the individual column the number of Lines for each entry and to be Read-only or not. By drag and drop, you can change the order of the colums or move them between Colums used and Columns not used. Thus, you can include or exclude columns from the metadata form.
• For a Group, you can select either Row or Column as Layout for the arrangement of the included property fields. Except for the Main Area, you can define a unique identification key for the Group. This key is required in order to display a label for the Group in your form. Customize the labels via Localization.
• For a GroupStack, there is no second information block displayed.

Summary

The form modeling in yuuvis® architect allows for a user with YUUVIS_TENANT_ADMIN or YUUVIS_SYSTEM_INTEGRATOR role to customize CREATE and EDIT forms that are offered in your client. The role authorizes the user to model forms in the metadata aspect area for object types of either tenant-specific or global schema definition, respectively. Furthermore, situation-specific modeling is possible via form scripting.

The labels displayed in the metadata forms for the client can not be customized in the form modeler, but by means of the Localization sub-tool of the yuuvis® architect.