Metadata Designer Creating a Metadata Definition

This article introduces you to the Metadata Definition Designer page and to the fundamentals of the structure of metadata in Flex. It also explains how to create and configure a metadata definition.

 

Metadata Definition Designer

The Metadata Designer has three parts, the Metadata Panel (A), the Metadata Canvas (B) and the Configuration Panel (C).

 

The Metadata Panel (A) gives access to the metadata field types to enable you to create your definition. The buttons available in this panel comprise all the types listed in the metadata field types section.

You can view the items in the Metadata panel in two different modes:

• List View:you will see the items in a list format with just the names of the items on display.
• Icon View:you will see the items that can be placed on the Metadata canvas in the form of tiles with icons.

To switch between List View and Icon View, click the toggle icon.

The Metadata Canvas (B) is the area in which you design your metadata definition. This canvas presents a graphical view of your metadata model in the form of a collapsible tree view.

The Configuration Panel (C) provides additional information and configuration options for a selected metadata field (item).

If you have not selected an item, then summary information about the metadata definition is provided.

 

 

Metadata Definitions

A metadata definition defines the structure of a data model, including field types, field names, access, validation rules, and hierarchy. This model does not comprise any values as the values vary depending on each definition instance.

A metadata definition is a type of Dalet Flex object and can be created and edited.

Metadata definitions adhere to the following rules:

• A metadata definition must be associated with a Dalet Flex object type.
• Whenever a new Dalet Flex object that supports metadata is instantiated, a new metadata instance is automatically created for the object.
• A metadata definition must have at least one field.

Whenever a metadata definition is saved, a merge occurs to ensure that all the related definition instances are kept up to date with the new data model defined by the updated definition . Therefore, removing a field will result in data loss.

 

Metadata Instances (Instances of a definition)

A metadata instance represents a single instance of a metadata definition with a unique collection of values. A metadata instance is created when a Dalet Flex object, which is associated with a metadata definition , is created. When a new metadata instance is created, all fields associated with the definition are converted to field instances within the metadata instance. Field instances reference the original field and allow for the capture and storage of a value.

Below is an example of a metadata instance, which is a single instance of the metadata definition shown above. You can see that there are fields that can be filled in with values, whereas the definition above simply defines the data model.

 

Metadata Fields

A metadata definition is a collection of related fields. Dalet Flex supports a large range of field types to assist with modelling your data in a meaningful fashion. Metadata field types are pluggable and new types can be created using Dalet Flex's API. This section explains how to create and configure new fields, as well as what field types and options are available.

 

Field Types

Metadata field types can be grouped into different types:

• Basic: Fields that are classed as structural or container-based (or composite types) and can carry additional fields
• Primitives: Represent common, "primitive" data types such as float, integer, and date. These types are basic building blocks for data
• Objects: These field types represent references to existing Dalet Flex objects
• Regions: These fields are associated yto a pre-built set of locations
• Resources: These fields hold associated images, files, URLs, Emails and VFS Location

 

Configuring Fields

The following options are available in the Configuration Pane for most field types:

• Name: A name is unique to the metadata definition
• Display Name: A display name can be used to specify how the name is displayed in a user interface. By default the name is used.
• Description: An optional description can be assigned
• Default Value: Some fields support a default value. This is used by Dalet Flex to set the initial value when a field is first instantiated. An example of a field type that supports this is the Integer.
• Searchable: This option defines whether the field can be searched as part of a search form or via the API
• Editable: This option defines whether the field can be edited or is always read-only.
• Commentable: This option sets whether comments can be added to this field. If selected you can manage which groups can add comments. Comments can only be added to fields in Flex CORE, not in FlexMAM.
• Form: The user interface form field type to use when editing this field (example include date, text box, text area)

Please take note that the Name and Display Name fields have the following restrictions:

• Both are mandatory
• The field name and display name cannot be more than 50 characters in length
• The field name can only comprise lower case letters, numbers and hyphens. For example, "a-field-name"
• The field name must be unique within the current metadata definition, meaning that you cannot have two fields with the same name.

 

Advanced Field Configuration

Multiplicity

Multiplicity allows for more than one instance of this field type to be created. By default, when a field is defined, it results in the creation of one field instance per definition instance. If multiplicity is set, then the number of instances that can be created per field can be controlled. Examples include:

• 1..* (one to many)
• 1 (Only one of that field)
• 0..1 (zero or one)
• 0..* (zero to many)

 

Interdependent fields

 Dalet Flex is supports interdependent fields.  Interdependent field support allows you to link together events generated from one field to updates on other fields. This functionality effectively allows fields to change their state based on changes made to other fields in the same metadata definition. With this functionality, it is possible to change the state of form fields and show / hide fields depending on values added in a field. It allows forms to be more dynamic and intuitive. Interdependent metadata fields are only supported in Flex CORE.

 

Field Validation Options

Validation options allow you to define how values entered into a field are validated. The following fields can be defined:

• Required: When this checkbx is selected, the field is mandatory.
• Description: This option allows you to provide a description of the validation rule. This can be presented to a user when they are filling in the form field to ensure that they know what the validation rules are.
• Max. Length: This rule enforces a maximum text length for an entry type.
• Script: This field allows you to validate a rule against some script. It supports simple scripting validation to ensure that fields are of a given format etc
  • The script field expects an expression script which is used to validate the value of the metadata field value. The following objects are accessible in the scripting context:
    value: The raw value associated with the variable instance
    variable: The variable object
    variableInstance: The variable instance object

Examples of validation scripts are:

Validates that a field contains a valid email address

org.apache.commons.validator.routines.EmailValidator.getInstance().isValid(variableInstance.value)

Validates that a date is not less than 90 days from now

!variableInstance.hasValue() || org.apache.commons.lang3.time.DateUtils.addDays(new Date(), 90).before(variableInstance.value)

 

Permissions Options

Dalet Flex supports per-field access control. This means that you can specify which user groups can view and edit a particular field in a definition instance. The options available are as follows:

• Access: This means that the selected user group has access to the field but cannot see the field
• Read: This means that the selected user group has read access to the field (cannot edit)
• Edit: This means that the selected user group has edit access to the field (can also read)

Access control for a metadata definition, is hierarchical and is based on visibility. This means that if access is blocked to a user from higher up the metadata model tree, then branches further down the hierarchy are not visible to the user either.

Allowing the application of access control to individual fields in a metadata definition ensures that users can only see or edit fields that are relevant to them.

Comment Permissions

Form Types

When creating a new metadata field, you will be offered the option to choose a form type. The form type defines the input field type  displayed when you enter values into a metadata field in the Dalet Flex user interface. The form types offered depend on the field type you have selected. For example for a field of type text, the user will be offered a standard one-line text input field or a multi-line textarea field and for a Boolean field the available form types are Radio, Checkbox and Select.

The supported form types are:

Text: A single line of text.

Textarea: Multiple lines of text.

Password: A password entry box (values hidden from the User).

Radio: A selection element that allows you to choose only one of a predefined set of options.

Checkbox: A seletion element that allows you to make a binary choice, i.e. a choice between one of two possible mutually exclusive options.

Select: A select box with one or more values to choose from. For single option types, a drop down is shown, for multi-option types a multi-select box is shown.

Date: A date pop-up, supporting date selection only.

Time: A time pop-up supporting date and time selection.

Colour: A colour picker pop up.

Typeahead: A field that supports typeahead - a list of matching values are offered as the user begins to type a word or phrase. The typeahead form type is very useful when you have an option field type that has a large number of options.

Text Fields: Text fields represent strings of text. Examples of Text field types are:

• String: A single line of text
• Password: A single line of text, with the value hidden from the user
• Text: One or more lines of text

Number Fields: The following options relate to number field types and further extend the capability of fields in the Dalet Flex metadata framework. Examples of number field types are integer and float.

• Units: For number field types (integer, double) units are available. Examples include bitrate, bits, bytes.
• Formatting: For number field types, formatting can be provided to control how a number is presented to users.
• Format Description: This is an optional field that allows for a user to provide descriptive information about the format rules specified.

Unit types are pluggable and new types can be created using Dalet Flex's API.

Examples of number field types are:

• Integer
• Long
• Boolean
• Float
• Double

Date Fields

Date fields are used to capture time-based information. There are 2 main field types:

• Date: Captures day, year and month 
• Time: Captures day, year, month, hour, minute and second

Colour Field

There is a single colour field. This field allows a user to specify a color with a color chooser pop-up. The colour field can be surprisingly useful, particularly when capturing information about look and feel, e.g. in the case of a player definition.

 

Complex Fields

A complex field is a special type of field that enables nesting of other fields to make hierarchical data structures. Hence, a complex field acts as a container for other metadata fields. By adding complex fields to existing complex fields, you can nest fields several levels deep to make powerful, description data models. For example, you might create a complex field called "film-details" which contains key fields which describe a film.

Drag a complex into your metadata definition and give it a name and then drag and drop any field that you want to nest in the complex on top of the complex field. You can also click the Quick Add icon that is displayed when you hover over the complex field.

A complex field definition:

A complex field instance:

Complex Fields with a Column Layout

In FlexMAM, you can improve the way connected metadata is displayed and make better use of the space in metadata forms by creating a column layout for complex metadata fields.

In Metadata Designer, add a complex field to a metadata definition and select the Column Layout check box.

Drag the fields that you want to appear in the columns of your table to the complex and configure their properties as you would for a regular complex. You should note these properties when configuring a column layout complex metadata field:

• Supported field types: string, password, text, integer, long, float, double, single-option.
• When a non-supported field is added to a column layout complex, the complex and the invalid field are highlighted in red and you cannot save the metadata definition
• The maximum recommended number of fields to add to a column layout complex is four
• To avoid issues, dynamic warnings are displayed as you configure a column layout complex.
  
  

For example, the column configuration for the "film details" complex, might look like this.

In FlexMAM, the column layout complex looks like this.

 

Option fields

Option fields allow you to select a value from a set list of options specified when the field is created. There are two types of option fields:

• Single Option fields: Single option fields allow a user to select only one option form a set list of options.
• Multiple Option fields: Multiple option fields allow a user to select one or more options form a set list of options.

When defining an option type field, you can enter option values. Each value comprises a name and a display name. You can also select default values, meaning that these values will be selected by default when a field of this type is first instantiated. The order of the individual option values can be set when the field is first defined. When creating a multiple option field, you can select more than one default value. For single option types, only one default value can be created.

A single option field definition:

A single option field instance:

A multi option field definition:

A multi option field instance:

 

Adding a new Option Value: To add a new Option value, enter the value in the Display Name box and press the green cross button.

Select the default Value: For Multi-option field types you can select more than one default value. For a single-option type you can select only one.

 

Backing Store fields

When creating an option type field, a user is often expected to enter a static list of options, for example "red", "green", "yellow". But what if the list of options is very large or changes regularly? What if the user does not know what the values are as they are stored in a different system? Backing Store field support is an advanced feature of option field types which addresses these challenges by allowing a user to configure an option type field to dynamically load the option values from an external source. This functionality offers some significant advantages:

• Data Integrity: If the values are stored in an external system (i.e. a rights management system) then by loading the options dynamically, the user can be sure that the data is always up to date.
• Easier Integration: This approach avoids data migration between external systems and Dalet Flex. By looking up data from the source as required, there is no need to migrate data and no need to rely on batch scripts and timed updates.
• Intelligent Workflow: Often workflow decision nodes are driven by values held within metadata fields (i.e. if Content Type = "Movie", then deliver to iTunes). Therefore workflow can be orchestrated by data contained in other systems without the need for data migration.

To configure an option field to be backing store enabled:

Add a single or multi option field to the canvas

Select the Backing Store checkbox; the Option Values panel is hidden and the Backing Store panel is displayed.

In the Backing Store drop down, select the Backing Store type:
- File: The values are loaded from a flat file.
- Database: The values are loaded from an external database.

Next enter the Identifier. The identifier is a text string query that maps to the underlying data store, using Hibernate Query Notation. Hibernate is a popular object-relational data mapping framework.

 

External API Backing Store

The External API Backing Store enables users to populate a drop down (single or multi-value fields) in the Metadata Designer with data from an external API.

Once this custom development has been carried out, you can use the External API Backing Store functionality by following these steps:

 

Open a metadata definition and addaa single or multi option field.

 In the configuration panel, select the Backing Store check box.

Expand the Backing Store drop down.

From the Type drop down, select External API.

In the Identifier field, enter the name of a Dalet Flex customer specific service. This name will be registered in Consul.

When Dalet Flex requires values, it calls the Dalet Flex customer specific service, passing in the ID provided in the Metadata Designer, which in turn makes a call to the target external API, converting the data where necessary.

 

Object Fields

An object field is a field that allows a user to reference an existing Dalet Flex object. For example a user may create a field that references another asset or another user. This concept is extremely powerful as it allows metadata definitions to reference other Dalet Flex object types in the system.

The two main types of object field are:

• Object: Allows a user to define a reference to a specific type of Dalet Flex object.
• Asset: Allows a user to define a reference to a specific type of Dalet Flex asset.

When making objects available in a metadata instance object field, Dalet Flex will only present objects that the user has visibility for.

See below a user object type defined in the metadata definition:

See below how this is displayed in the metadata instance:

Key-Value Variables

You can add key-value variables to your metadata definition. For example, if you had metadata which is associated with an asset, you could have a key-value field for actors-roles. When you add a key-value field to your metadata definition, two empty fields appear in the interface when the definition is instantiated for an asset and you can add the relevant information.  For example, you could have the name of the actor who appeared in the film, and the role they played as a pair in the same field.

A key-value definition:

A key-value field instance:

Creating and Configuring a Metadata Definition

Creating a New Metadata Definition

In Dalet Flex Core, on the toolbar, click New and select Metadata Definition or open the Metadata Designer from FlexMAM.

 

In the Create Metadata Schema pop-up in the Name field, enter a name for your definition.

In the Visibility field, select any accounts, sub-accounts, and groups that you want this definition to be visible in.

In the Description field, enter an optional description.

Once you have created your metadata definition, you can add fields to it. A metadata definition must contain at least one field.

 

Editing an Existing Metadata Definition

On the Metadata Designer landing page, click on an existing definition from the list.

In the bottom of the right-hand panel, click the Edit option.

The definition opens, and you can begin editing it.

 

Validating and Saving a Metadata Definition

Your metadata definition is automatically validated as you add and configure the individual fields. Every field that is added to the canvas must have a valid name and display name. The following rules apply:

• Both name and display name are mandatory.
• If a field has already been saved, the name will no longer be editable. It will be greyed out.
• The field name and display name cannot be more than 50 characters each in length
• The field name can only comprise lower case letters, numbers and hyphens. For example, “a-field-name”
• The field name must be unique within the current metadata definition.

After you have added all the fields to the canvas and configured their properties, you must save the  metadata definition by clicking the icon. A summary panel is displayed with information about the metadata definition.

 

 

When you save a metadata definition, Flex will find all related metadata instances and update the model. This is known as a metadata merge and the save process could take some time to complete. When saving a metadata definition a confirmation dialog asking you to confirm that you wish to proceed with a merge that may result in the loss of data is displayed. 

 

Adding and Removing Fields

Creating and updating a metadata definition involves adding items to, and removing items from, the Metadata canvas. Typically you add new fields from the Metadata panel and then configure them with the Metadata Configuration Panel.

 

To add a field to the Metadata canvas:

In the Metadata panel on the left-hand side, double-click on the field you wish to add, and it will be added to the bottom of the list of existing fields on the canvas.

 

Alternately, you can click and drag the field from the Metadata panel,straight onto the canvas.

If you have more than one field on the canvas, you can move your new field into the correct position, by clicking and dragging the field. The other fields will then adjust accordingly.

Configure your new field by providing a name a description and any other options available, in the Configuration Panel.

 

If you wish to add more fields of the same type, you can keep clicking the field type in the Metadata panel and new fields will appear below the last one that was added.

You can also add a new field, directly in the canvas by clicking the+icon, on an existing field in the canvas. When you click the + icon, you will see a list of existing fields to choose from.

 

Using Quick Add

You can also add fields to your metadata definition, using the search field located at the top of the Metadata Designer.

 

       

To use the Quick Add bar:

Start typing the name of the field you wish to add, and the option will appear in the typeahead.

 

Select your desired field from the lookup, and it will appear in the search bar.

Click the + symbol, and the field will appear on the canvas.

 

To add a new field via an existing field:

You can also add a new field to the canvas, by clicking the + icon located on an existing field, as shown below.

Removing fields

You can remove one or all the fields that are on the canvas.

To remove a single field:

Hover over the field you wish to delete.

Click the Delete icon.

In the Delete Metadata Schema pop-up, click OK to confirm.

 

To remove all fields:

Click the Delete All Fields icon, located at the top-right of the page.

 

In the Delete Metadata Schema Fields pop-up, click OK to confirm.

The fields are deleted from the canvas.

 

Moving fields

Creating and updating a metadata definition involves adding fields to, and removing fields from, the canvas.

There are a number of ways to move fields on the canvas and change their position in relation to other fields. Before a field can be moved it must first be highlighted by clicking on it. Please note that at the current time, you can only move fields within the same container (Complex field). You cannot currently move them from one complex type to another.

 

To drag items around the canvas:

Hold down your left mouse button over the field you wish to move.

While holding down your left mouse button, drag the field up or down in relation to the other fields. The other fields will adjust accordingly. Release the left mouse button to stop dragging the item.