Configure asset relations and references

censhare comes with a whole set of predefined asset relation types. Create and configure asset relation types or asset references to your needs.

Introduction

In order to create and configure an asset relation type or an asset reference, you need the appropriate rights in the censhare Admin Client. The configuration is done in the master data. Double click the entry "Asset relation types" in order to configure a relation, or "Features" to configure a reference.

Asset relations

Relation types are created in a hierarchical structure and you can create as many hierarchy levels as you want. The ID of a relation type is interpreted by censhare as a path. Between two hierarchy levels is a period, and at the end is also a period. That means the last portion of the ID is a unique identifier while the portions in front of that refer to a hierarchy level.

An example ID might look like this:

user.content.text-snippet.

The first part, "user.", is in all relations that can be created by a user. The second part, "content." shows that the relation belongs to asset content in some thematic way. The third portion identifies the relation.

The following table shows the first hierarchy level of relations in censhare. This should not be changed.

ID	Name	Meaning
actual.	placement	This relation and its sub-types are used by the system to display placements in layouts. They are versioned by default. As such, every version of the layout and its various placements can be restored.
similar.	similar	This relation shows the similarity between the assets and therefore has no direction.
user.	assignment	Users can use this relation and its sub-types to show the relationships between assets. The general type "Assignment" here shows an overall relationship between two assets. The sub-types each represent a special relationship or an aspect of a relationship between assets. New relation types are typically created as sub-types of this type.
variant.	variant	This relation and its sub-types are used by the system to create asset variants. Do not make any changes to these relations!

Creating relation types

To create a new relation type, click "Add" and define the parameters and filters:

Icon	Meaning
	Button: New

Configure the relation as follows:

Field	Required	Meaning
Enabled	no	If this field is selected, users can see the relation. If not, users can't see this type. The field thus offers you the simple option of deactivating a relation type without having to delete it.
ID	yes	The field contains the ID for the relation type. The ID also reflects the hierarchy of the relation. New relations are typically created as sub-types of the general type "Assignment". The ID reads "user.[unique ID]." or "user.[Level_1].[unique_ID]" if a sub-type is to be created. A period is interpreted as the next hierarchy level. Only existing paths are allowed. If you want to create the relations "user.editor.proofreader" and "user.editor.translator", first create the relation type "user.editor".
Name [en]	yes	This field contains the general name of the relation in English. If no name is entered for the parent or child context, then this name is used.
Name [de]	yes	This field contains the general name of the relation in German. If no name is entered for the parent or child context, then this name is used.
Parent title [en]	no	Here you have the option of entering an English name for the parent relation. If relations of this type are created or displayed in the context of the parent asset, then this name is used.
Child title [en]	no	Here you have the option of entering an English name for the child relation. If relations of this type are created or displayed in the context of the child asset, then this name is used.
Parent title [de]	no	Here you have the option of entering a German name for the parent relation. If relations of this type are created or displayed in the context of the parent asset, then this name is used.
Child title [de]	no	Here you have the option of entering a German name for the child relation. If relations of this type are created or displayed in the context of the child asset, then this name is used.
Description [en]	no	Das Feld dient zu Dokumentationszwecken.
Description [de]	no	This field is for documentation purposes.
Domain	no	Here you can assign a domain to the relation type. Domains can display an organizational structure, for example. It, therefore, makes sense that the relation type "Author" is only available in the "Editorial" domain because it is important for an editorial staff member to assign an author to a text. In the "Accounting" domain, on the other hand, the relation type "Invoicing" could be available with the feature "Payment per line". An employee in accounting can then link the same assets (text and author) using this type and enter the agreed payment as a feature value of the relation. Visibility is determined by both the user and asset domains. Users need to be logged into the same domain, sub-domain or supra-domain as the relation domain. The synchronization is done in both domain directions, i.e. child and parent. The assets to be linked need to be created in the same domain or sub-domain as the relation domain. The synchronization is only done in the child domain direction here.
2nd Domain	no	Here you can assign a second domain to the relation type. For more information see the description in the field "Domain".
Parent sorting	no	The number value in this field specifies the position that a parent relation has in a selection list, for example. The requirement for this is that the sorting option is set for organizing the entries. If the sorting is alphabetical, then this value plays no role.
Child sorting	no	The number value in this field specifies the position that a child relation has in a selection list, for example. The requirement for this is that the sorting option is set for organizing the entries. If the sorting is alphabetical, then this value plays no role.
Type	no	A relation can have a direction or not. For more information see the section "Directed relations" in the article "Asset relations and asset references".
Usage	no	A relation can be used in the relation n:m, n:1, 1:m or 1:1. For more information see the section "Number of possible relations" in the article "Asset relations and asset references".
Versioned	no	If this field is activated, censhare saves that relation status for every version of the related assets. For non-versioned relations, only the status of the current asset versions are saved.
User editable	no	This field needs to be activated for all relations created, edited or deleted by users between two assets. Deactivate it for relations that are only used by the system.
Filters	no	Here you can add filters for parent or child assets for which this relation is to be available.

Asset references

To create an asset reference you need to create a feature in the master data and configure it as an "Asset reference". For a full description of features see the article Creating a new feature. Below we will only describe the fields relevant to referencing.

Field	Required	Meaning
Value type	no	There are two options for referencing assets in a feature. Select "Asset reference" in order to use an asset ID as an identifier. Select "Asset key reference" in order to use an asset resource key as an identifier. The benefit of the second variant is that asset feature references can also be imported into other systems because the resource key of an asset is unique in all systems. If there is no resource key in a referenced asset, this will be dynamically generated from the UUID of the asset. Please note that the dynamic generation of resource keys is only possible in censhare Web. Users in Java Client need the resource key when creating a feature reference. Assets with no key cannot be referenced in the Java Client. After selecting one of the two value types, a new area "Asset reference" will appear below the "General" area.

Section "Asset reference"

Parent title [en]	no	Here you have the option of entering an English name for the parent relation. If relations of this type are created in the context of the parent asset, then this name is used. (1)
Child title [en]	no	Here you have the option of entering an English name for the child relation. If relations of this type are created in the context of the child asset, then this name is used. (1)
Parent title [de]	no	Here you have the option of entering a German name for the parent relation. If relations of this type are created in the context of the parent asset, then this name is used. (1)
Child title [de]	no	Here you have the option of entering a German name for the child relation. If relations of this type are created in the context of the child asset, then this name is used. (1)
Filters	Nein	Here you can add filters for parent or child assets for which this relation is to be available.

(1) Note:

The parent- or child-specific identifier is only used when creating a reference. That means users can create a reference in both the parent asset context and the child asset context. In both cases, censhare still saves the reference only in the parent asset.

Configuring full-text indexes for features and referenced assets

Asset references are saved as features in censhare. Just like with every feature, a full-text index can also be configured for an asset reference, which helps users when searching for referenced assets in the context of that reference. Because for technical reasons an asset reference saves an ID or a resource key, users need to look for this ID or key in order to find an asset.

On the other side, the reference - the parent asset that contains the reference - is not saved in the referenced asset. If a user looks for it, the search would only find the referenced asset but not other assets that contain a feature with this reference. These two limitations can be avoided by configuring a full-text index.

For example, the full-text search for the indexed feature "Author" is configured for the feature "Author", which contains an asset reference. If a user searches for the name of a person, then not only will assets for that person be shown in the quick search, but also text assets that contain a reference to the person in the "Author" feature. The automatic search suggestions show assets with this feature in a separate "Author" grouping.

Two steps are required to configure the full-text index:

First, a full-text index feature must be created. This feature generates a text index for the referenced asset.
If users are also supposed to be able to look for a reference in the quick search, then the corresponding full-text index for the virtual index needs to be added in the feature "censhare:text.meta".

For more detailed instructions on creating a full-text index and configuring the quick search see the article Creating a full-text index.

Configuring the widget "Asset lists based on related assets"

To display asset relations and asset references you can place a widget on asset pages. To configure a widget of that type, censhare provides you with the generic widget "Asset list based on referenced assets". There are already several widgets in the standard workspace that are based on this widget type. Among them are the "Authors", "Main content from", "Placed in" or "Assignments" widgets.

In developer mode, you can go to the option "Add widget type" in the asset menu to add the generic widget "Asset list based on referenced assets" to an asset page. The widget shows relations or references in one direction for a certain type. To configure it, specify the following settings:

Section "Generelle Konfiguration"

For the configuration of this section, see the article General widget configuration.

Section "Relation or reference"

Field	Meaning
Type	From the list, select the reference or relation to be shown in the widget.
Direction	Here you enter whether assets should be shown in the parent or child relation.
Manual sorting	If this field is activated, users in censhare Web can change the position of an asset in the list view. If the cursor is moved over a list element, the buttons "Move up one position" and "Move down one position" will appear.
Drag & drop	If this field is activated, users in censhare Web can link assets using the drag and drop function.
Grouping	Alternatively, you can select a feature from the list in order to group assets in the list view according to that feature. That increases clarity in long asset lists.

Section "Edit relation metadata"

Field

Meaning

Template

A corresponding metadata dialog needs to be configured in order for users in censhare Web to be able to assign a feature to a relation. The user sees this when he/she opens the asset menu of an asset in the widget list and then selects the option "Edit relation metadata".

For example, censhare has the templates "Budget relation metadata dialog“ and "Resource replace variant metadata dialog". The former assigns an amount to a budget relation while the latter controls the visibility of Resource replace variants for module assets.

To create a new template, click "Add", enter a resource key and a name and confirm everything with "OK".
The template is then there and can be selected from the list. However, it can't be used yet because no features are referenced yet. An example configuration can be found in the article Example configuration of a relation feature and relation metadata dialog".

Compared to the list view in the menu option "Show relations", the widget has the advantage that the related or referenced assets can be shown directly in the asset page. Users don't have to first carry out the "Show relations" action in the asset menu. Another advantage of this widget is that references are shown in both directions, in the parent-child relation as well as in the child-parent relation.

The example already used in this article about author references illustrates this. If a user opens the relations for a text asset, he/she will see all referenced person assets there under the "Author" grouping. However, if a user opens the relations for a person asset, no text assets will be shown that contain a reference to the author. With a widget, this limitation can be bypassed. Placed in a person asset, even text assets with an author reference to this asset can be shown in the widget.

A referenced feature or a relation type can be configured for each widget and assets can either be shown in the child or parent relations. To show multiple references or relations, multiple widgets need to be created.

Via the "Add" button in the widget action list, users can link assets with the current context asset. Click the button to start the asset chooser dialog. If asset filters are defined for the specified type of relation or reference, only the corresponding assets will be shown. For example, only person assets can be selected in the "Authors" widget. The relation type doesn't need to be selected in this action because only references for the pre-specified type are possible.

For instructions on customizing the workspace see the article Assets in the standard workspace structure. For further information on configuring the widget selection list and the dynamic display of widgets on asset pages see the article Special customizations of pages, tabs and widgets.