Metadata editor

Using metadata in the product require two distinct phases:

1. A step that determines the schema of the metadata. In other words the skeleton of the metadata and how it will later be populated
2. The population step. This can be done at different steps of the execution plan, during the data collection phase (collected metadata), during the activation (computed metadata) or in the web portal (portal metadata).

The Metadata editor is the editor that allows the user to configure the schema of the metadata and configure the method used to compute the metadata if necessary.

A metadata is created from the main menu by selecting New... and then Metadata schema.

This menu opens a wizard to create a new schema extension. The metadata id field is the name of the schema extension and it must be unique among all extensions in the project, created in the project or included in installed add-ons. Brainwave add-ons containing metadata always use a prefix bw for the metadata id. The best practice is to use a prefix describing the project (or the customer) and then an explicit schema extension name in order to avoid conflicts, for example acme_myfirstmetadata.

The best practice is to fill in the description of the created metadata with the purpose of the extension. This helps document what the schema extension will be used for.

Upon completion of the wizard an editor is opened that allows the configuration of the schema of the metadata. This is an important step as this will provide the product with the way the metadata will be created and then what elements are necessary when populating the metadata.

The following snapshot shows the definition for the first use case.

As a metadata is to be used in views and rules. The view editor and the rule editor requires icons to display the entities or attributes in the palette. This is why the metadata editor expects 2 icons: one in 16x16 and one in 48x48. An icon is provided by default but the user has the option to add custom icons.

The metadata editor is used to define both:

• The schema extension in the 'Metadata definition' tab of the editor
• The method to compute a metadata during the execution plan in the 'Metadata computation' tab of the editor.

If a metadata is not computed configuring the 'Metadata computation' is unnecessary.

A metadata can be associated with no, one or several entities:

• Defining a metadata without an entity means that you create your own concept without any relation with other Brainwave entities. In rare occasions, you need to create a new concept which is not linked to any other Brainwave entities.
• The usual way to use metadata is to extend a Brainwave concept to add attributes. In this situation, a single concept is selected in the editor. The user has the choice of having an explicit link towards the Brainwave concept or to embed the metadata attributes directly in the Brainwave concept.
• Another usage is to select several concepts. This is the method to use to create a link with attributes between 2 or more concepts.

The following paragraphs explain how to configure the entity or the links.

Metadata without entity

The following caption shows a new standalone concept called acme_my_concept. that is not linked to a Brainwave entity.

To do so, in the editor, keep all checkbox unchecked. The 'short metadata title' must be filled to see the metadata in the view editor palette.

As there are no links from the metadata to any Brainwave concept, this mode is rarely used but can be useful to store configuration information for example.

Metadata with attributes embedded in a single entity

This is the most common usage of metadata. The attributes defined in a metadata are added to a Brainwave entity. The following picture shows a metadata called acme_my_extension extending the Identity concept.

To extend a Brainwave concept check the checkbox named 'Display metadata attributes in the following concept in the view editor'.

When checked, the entity holding the attributes must be selected in the dedicated combobox among the following list:

• Organization
• Identity
• Repository
• Group
• Account
• Permission
• Application
• Asset

In this mode, all attributes defined in the metadata schema are visible directly on the entity itself in the view editor.

Metadata with an explicit link in a single entity

In this mode, there is still a single concept but the metadata designer does not want to embed the attributes in the entity. Technically this means that in the view editor, it is necessary to perform a join on the main entity to reach the desired metadata attribute. The following picture shows the metadata named acme_my_extension which has an explicit link to the identity

To do so keep the checkbox named 'Display metadata attributes in the following concept in the view editor' unchecked. Then select the link called 'Use and activate the link towards identities' and enter the label that will appear in the join section of the palette when the metadata is selected.

Metadata with several entities

Defining a metadata with links to several entities is a way to create a new relation in the Brainwave data model. The following picture illustrates a new link called acme_my_link between an identity and an application.

To create such a link, check at least 2 checkboxes defining a link towards entities in the metadata editor. The following screenshot shows the configuration for adding a link between organization and application to define a responsibility for example.

In this configuration, both the organization and the application have a new component to join in the view or rule palette to access the linked attributes. Using these joins, it is possible to go from the organization to the metadata containing the mngr_exp_date attribute and then go to the managed application.

Single or multivalued attributes

By design all metadata values are multivalued. There is no way to restrict an attribute to a single value.

Whatever attribute is defined as values in the metadata schema definition, you can always create multiple values at runtime as long as the data conforms to the schema definition. It is the responsibility of the application (when collecting or when updating metadata in a workflow) to ensure that only one value is saved if single value is desired. For example, if a metadata defines an attribute called cert_name for certification, it is possible to add several certification names for a given user.

As explained earlier, the metadata is composed of several fields for the value. A value is in fact a set of, at most, 20 strings, 20 integers, 2 floats, 2 dates, 1 boolean and 1 blob. For a given metadata, it is possible to have several values, meaning several sets. If there are 3 certifications, there will be 3 sets composed of, at most, 20 strings, 20 integers, 2 floats, 2 dates, 1 boolean and 1 blob.

When updating a metadata, the full set is created, updated or deleted. Let's take the example of the certifications for an identity. The metadata contains 4 attributes (2 strings and 2 dates, the others are unused):

• cert_name: string 1
• cert_prov: string 2
• cert_date: date 1
• expn_date: date 2

We can execute these operations either in the collect or in the workflow:

• add a value (a full set of 2 strings and 2 dates)
• remove a value (a full set of 2 strings and 2 dates)
• update a value (a full set of 2 strings and 2 dates)

From this example, we can see that if we add 3 values, we will always have the same cardinality in the 4 attributes (3 string values in cert_name, 3 string values in cert_prov, 3 date values in cert_date and 3 date values in expn_date). expn_date can be null in the last set but there are still 3 values (2 non empty dates and 1 null).

In the metadata schema the type of metadata values are split in two categories:

• Simple values
• Entity values

The differences between both concepts are detailed below.

Metadata simple values

It is possible to configure a metadata in order to use simple values as attributes. To activate and define these attributes in the metadata in the simple 'values tab', choose a type and enter an identifier in the corresponding field. The available types are:

• string
• integer
• float
• date
• boolean
• blob

Once the value identifier is filled in, the label field to the right of the identifier field is then enabled. The label field is used to populate the palette in the view editor.

The field 'Details value identifier' at the bottom of the list corresponds to the blob field which can be used to save details about the metadata (for example XML or JSON content) or a binary content.

Metadata entity values

A metadata value can also contain a link or reference to an entity.

Metadata entity value use case

Entity values correspond to links from the metadata to other entities of the Ledger (accounts, identities, organizations, applications, ...).

For example, this is useful when the value is a combination of a string, a date and a Ledger entity . This is very similar to entity references in the key but the usage is different when used in values.

The need of declaring entity links as metadata values often arrives when a concept needs to reference several entities which are optional. For example, a metadata is declared to create a link between an organization and an application. Both entities are part of the metadata key. But we could also add values like identities responsible of this link. This information is optional and should not be part of the key. To model this optional the link to the identity is added to the metadata values.

Choosing between metadata keys and values

It is important to understand the difference between metadata keys and values as this will have an impact on how and when a metadata is created and what it will contain. However, there is no absolute rule to know if an entity should be part of the key or not.

Here is an example to understand the difference between referencing an entity in the key or in the value.

Let's add another feature to the certification metadata. let's consider that this is an internal certification, as a result we would like to keep a reference to who within the company delivered the certification. This means that we need to add to the certification metadata a link to an identity in the ledger.

As a result the metadata schema is now composed of 4 simple attributes, the certification name, provider, date and the expiration date, and the identity who delivered the certification.

If the identity that delivered the certification is no longer part of the company then the link to the identity concept in the ledger is not longer available for the metadata. However this does not mean that the certification no longer exists or is invalid. As a result we can see that the certification provider should not be part of the key and be added to entity values.

Portal metadata activation

On the contrary to collected or computed metadata, a portal metadata is copied from one timeslot to the next during the activation phase of the execution plan. However, a metadata can be copied to the next timeslot only if all the referenced entities defined in the key are available in the destination timeslot.

As an example, let's focus on a metadata containing a link to 2 entities in the key, application and organization, and a link to an entity value, identity.

In the first timeslot we have a metadata with the application Elyxo, the organization DCOM and, as a value, the identity Paul Martin.

In the second timeslot, if either key entity, Elyxo or DCOM, are missing then metadata is not copied over.

In the third timeslot if both key entities are found, Elyxo and DCOM, the metadata will be copied from timeslot 1 to timeslot 3

In all cases, if the entity value is missing, in this case the identity Paul Martin no longer is present in the ledger, then this does not prevent the metadata from being copied in all timeslot. The timeslot where Paul Martin is not present will fill null in the entity value. If the identity is reintegrated back in the Ledger, then the metadata will point again on the identity Paul Martin.

Metadata values conflicts

Another aspect that can influence the use of an entity in the key or in the value is the metadata life cycle. This is especially important when the metadata is collected and later updated in the portal. When a metadata has been changed in the portal, the collected values in the next timeslots are ignored, as a portal metadata has a higher priority than both the collected and computed metadata.

When a metadata can be collected and modified in the portal, you must take care of which entities are in the key and which entities are in the value. This influences the way conflicts between collected metadata and portal metadata are handled.

During the activation phase when the product merges the collected (or computed) metadata with the portal version of the same metadata, the operation is executed for each metadata key. The key is composed of the metadata name, the metadata subkey and all the key entities defined in the schema. In other words, for a single key, all the values are considered atomic during the merge operation.

This means that if there are several values in a key, then either:

• The metadata was not updated portal side and so all values are collected.
• The metadata was updated portal side and so all values are copied from the previous timeslot.

This ensures that the values are consistent.

Let's take an example with 2 entities (organization and application) where an organization is responsible for an application. There are 3 distinct ways to design the metadata schema:

1. The organization is in the key and the application in the value.
2. Both organization and application are in the key.
3. The Application is in the key and the organization in the value.

The organization is in the metadata key

Let's examine the first option. This design means that, for a given organization, we have a list of managed applications, 0 or more.

During the data collection phase it is determined that:

• The organization DCOM manages the 3 applications Elyxo, FileShare and `SAP``
• The organization DFIN manages 2 applications FileShare and PeopleSoft.

In the web portal, a user decides to change the list of managed applications:

• DCOM now manages Elyxo and PeopleSoft
• DFIN now manages FileShare and SAP

The information entered by the user in the web portal now becomes the reference and the whole list is copied from timeslot to timeslot ignoring what is collected.

In a later timeslot, if during the data collection phase the import files say that:

• DCOM manages FileShare and PeopleSoft
• DFIN manages FileShare and SAP

The list of values entered by the user has a higher priority. And so the values in the metadata will be taken from the previous timeslot and remain:

• DCOM now manages Elyxo and PeopleSoft
• DFIN now manages FileShare and SAP

In this configuration, in order to get all applications managed by a given organization (DCOM), we must fetch a unique metadata whose key is the organization and the values the list of applications.

The following table shows the timeslots with data collected or updated in the portal. The last columns with a title 'Timeslot 2 (final result)' shows what the user can see when looking at the management information in the portal.

The general rule for dealing with conflicts is that the whole list of the values (applications) for a given key (organization) is taken either from a single source:

• The collect
• The previous timeslot.

In this scenario, the application list for both DCOM and DFIN have been modified in the portal so the portal metadata wins.

This product behavior prevents a merge of the application list provided during the data collection phase or, if the list was edited in the portal, from the previous timeslot. Upon conflict, the list is considered atomic and we can not end up with applications coming from both lists.

Both organization and application are in the metadata key

Now let's examine the second option. Both the organization and the application are part of the key.

In this configuration, there is no more list of values for a given key as the key contains both entities. Instead of having one metadata with a list of applications, we end up with several metadata, each one having an organization and only one application. Each metadata is independent from the other, even if some of them share the same organization.

In this case, to get all the applications managed by DCOM, we must fetch all the metadata with the organisation equals to DCOM. At most, we have 8 metadata:

• DCOM - Elyxo
• DCOM - FileShare
• DCOM - SAP
• DCOM - PeopleSoft
• DFIN - Elyxo
• DFIN - FileShare
• DFIN - SAP
• DFIN - PeopleSoft

The same scenario as detailed previously is executed, the metadata are collected then changed in the portal. The end result is different as shown in the following table.

As a reminder, for each key, the activation keeps either the collected data or, if updated in the portal, the data from the previous timeslot.

The result shows that individual keys have been handled separately by the activation.

Let's review which application is managed by DCOM:

• Elyxo is not managed anymore because the last collect does not include this application.
• FileShare is managed because it has been removed by the user for DCOM. Removing a metadata on the portal side means that the data will be taken from the collect at the next timeslot. The key is then collected again.
• SAP is no longer managed as it has been removed by the user in the portal and has not been collected afterwards.
• PeopleSoft is only managed by DCOM, as it has been collected in the last timeslot. However DFIN no longer manages PeopleSoft as this was updated on the portal side and has not been collected in the last timeslot.

The application is Metadata key

Now let's examine the third option where the application correspond to the metadata key and the organization correspond to the metadata value.

In this model, the application either have no metadata, meaning no organization is managing it, or a metadata with at least one organization managing it.

The result is shown in the following table:

After executing our scenario, we find the following results:

• Elyxo has no managing organization anymore because the last collect does not include Elyxo.
• FileShare has DFIN as a managing organization as DCOM was removed by the user. The whole value list, the list of organizations only containing DFIN, is used from the previous timeslot and the collected list is ignored.
• SAP has DFIN as a managing organization for the exact same reason as FileShare.
• PeopleSoft has DCOM as managing organization because the user changed the value list in the portal to keep only DCOM for this application.

Conclusion

It is important to understand that there is no absolute truth about which model is the good one. The choice of the key will depend on the use case and the data semantics.

With the previous example, using the first option with organization in the key and applications in the value seems to be a better solution. But it depends on:

• The authoritative data source. The collected one or information provided by the users in the portal
• The entity semantics of the entities
• The company context
• The way the data it is edited in the portal
• ...

A parameter to help decide if an entity goes in the key or in the value is to consider if the entity list should be considered as:

• Atomic, and taken as a whole from the collect or from the portal.
• Standalone, and putting all entities in the key

Metadata in the rule editor

Metadata can be used in the rule editor in 4 different situations:

1. Metadata with attributes embedded into another entity
2. Metadata with explicit links to other entities
3. Metadata with value links to other entities
4. Standalone metadata without entity

In case 1, 2 and 3 (embedded, key link, and value link ) , the metadata can be used in rules through specific joins from the linked entities.
For example, if the metadata is linked or embedded to Identity entity , a join to this metadata will be available from the identity entity in the palette.

The metadata join will propose various criteria on the attributes of the metadata, depending on the type of the attribute, and criteria on generic properties of the metadata, such as description, creator, subkey , etc.

In case (1) metadata with attributes embedded into another entity , it's also possible to use the metadata directly as criteria on the embedding entity in the rule editor.
But this requires the metadata to follow some restrictions:

• the metadata subkey must be empty ( not set through computation or code)
• runtime values of all metadata attributes must only contain single values.

For this reason, this option must be set explicitly by checking the Display also in Smart Search interface and rule editor as criteria of the single concept box.

In which case, the embedding entity will propose additional criteria for the embedded metadata attributes which can be used like the other entity attributes:

Metadata in the Smart Search

When this option is checked for embedded metadata attributes, you can also enable the use of metadata criteria in the Smart Search user interface in the web portal.

To do so, you will have to provide additional labels to help build user-friendly search sentences in the Smart Search user interface. The meaning of the label depends on the type of the attribute:

• for string, integer , float and date attributes, you must provide a prefix label. The label that will appear in the UI for this attribute is built by concatenating the prefix and the attribute.

For example, if the prefix is "which" and the label is "certification name", the search label attribute will be "which certification name". In French, the prefix would be "dont le" and the label "nom de certification", giving in the search "dont le nom de certification".

• for boolean attribute, you must provide the negative form of the attribute, assuming the label is the positive form.

For example, the label could be "has expired" and the negation would be "has not expired"

• leaving the search prefix or negation label empty for an attribute will hide the attribute from the list of Smart Search criteria for the embedding entity.

This is how the SmartSearch could look like. In the example above, certification date and expiration dates are hidden.

Localizing metadata labels

You can localize all the metadata labels (name, attributes , relations and search labels) by clicking the blue flag to the right of the label edit box. This will create the appropriate entry in the specified properties file. To make the localization task much easier, you can generate a localization template for all the active attributes and relations. To generate the template text to the clipboard, click on the Copy Label localization template to the clipboard button at the bottom right of the editor.

In the example above, this will copy the following text to the clipboard.
You can then paste the text to the appropriate properties files and fill the blanks or translate the labels.

Metadata.link.id_cert_embed.metadata=
Metadata.value.id_cert_embed.value1string=certification name
Metadata.value.id_cert_embed.value1string.search=which
Metadata.value.id_cert_embed.value2string=certification provider
Metadata.value.id_cert_embed.value2string.search=which
Metadata.value.id_cert_embed.value1date=certification date
Metadata.value.id_cert_embed.value1date.search=
Metadata.value.id_cert_embed.value2date=certification expiration date
Metadata.value.id_cert_embed.value2date.search=
Metadata.value.id_cert_embed.valueboolean=certification has expired
Metadata.value.id_cert_embed.valueboolean.search=certification has not expired