Asset relationships - SysAdmin

censhare allows users to represent relationships between assets as asset relations or asset references. Technical concept and comparison of relation types from the users' perspective. Configuration walk-through of relations and references.

Context

Creating and managing features and relation types in the Master data of the system.

Prerequisites

You need access to the censhare Admin Client.

Introduction

censhare can save connections between assets as relations or as references. A relation is a connection between two assets that is mapped through a third element, namely, a relation. A reference is a feature that refers to a different asset and therefore has the value type "Asset reference". Below we will also use the term "Asset reference" for the feature itself.

The following article gives you a bit of technical knowledge of how relations and references are best used in censhare. Both concepts and the data models that they are based on are explained by examples.

Data model

The censhare data model knows objects and relationships between those objects. censhare uses assets to display objects. The properties of an object are saved as features. The term "metadata" is used in censhare for this and censhare saves feature definitions as master data. You can find the master data in the Admin Client in the "Master data" folder of the "Features" table. Here you can also create and edit feature definitions. In censhare Web, the "Metadata" widget is there to show you features on asset pages. Users can also edit selected metadata by going to the "Edit properties" dialog in the asset menu.

Relationships between objects – between assets – are displayed using relations. These relationships are saved in a relational database, which means every relation is represented by a dataset with attribute values (relation values). Connections between assets can also be displayed in the form of references. Here, a feature is created that refers to another asset. Features are saved in the database as an asset that contains the reference.

Below, "relationship" will be used as a general term for asset relations and asset references when it needs to be clarified that two assets have a connection to each other. On the other hand, in order to keep it clear that both relationship types can be used in censhare, the specific terms relation or reference will also be used.

To make it easier to understand asset references and the boundaries between asset relations, we will explain below how features are structured in censhare.

Features

In censhare, features are saved in assets and in asset relations. Some features such as the ID or the resource key are required by the system. Other features like product features are edited by users. The definitions for these features are created in the censhare Admin Client. Features in censhare Web are also displayed as assets. To do that, censhare provides you with a special module asset of the type "Feature". As soon as you create a new feature in the Admin Client as an administrator you can then also find that feature in censhare Web as an asset representation. Feature assets are needed for generating dynamic value lists, among other things. For more information on this see the following section.

Sources for feature values

Features represent general properties and master data in order to characterize assets, for example the feature "Color". Users can then create the feature in an asset and give it a value. For example, they can give the "Color" feature the value "Red" for the "Single-color t-shirt" product.

Feature values differentiate themselves in terms of their value types. Simply put, feature values can have a text (string), a number value or a date. A complete list of value types can be found in the article "Creating a new feature" in the section "Notes regarding value types". Features that have a text, a number or a date can contain any values: in a text field a character string, in a number field a number or in a date field a date.

There are also features that can only take certain values. For example, a t-shirt can be manufactured in the colors red, blue, yellow or green. No other colors are available. In this case, instead of creating a text feature you create a feature with a static values list. When editing a product, users can then select one of the saved values for the "Color" feature, for example. The advantage of a values list is obvious: Users don't need to know which colors are available and subjective entries like "light red", "fire engine red" or "dark red" aren't possible.

You can create static value lists of the type "Value list (string)" or "Hierarchal value list (string)" in the Admin Client. The feature values are added there in the "Value" area. In the example with the "Color" feature, the values "Red", "Blue", "Yellow" and "Green" were created in the feature.

In addition to static value lists, censhare also knows dynamic value lists. The process for creating dynamic value lists is a little different. Values are not created in the feature itself, but rather created as module assets of the type "Feature value" in censhare Web. Assigning the feature value assets to a feature is done using the value list assets.

The configuration using feature value assets and value lists has a lot more flexibility. Users can create new feature values as assets if they have the appropriate privileges to do so. Using XSLT transformations, the lists can be sorted, localized and enriched with text, for example.

A list of feature values generates dynamic value lists from which users can select a value. In doing so, a module asset of the type "Value list" is referenced. Dynamic value lists can contain assets (asset references or asset resource key references), numbers or text (string).

Tip: censhare recommends configuring a corresponding widget for dynamic value lists. Users create a feature there by selecting a value from the list in a metadata dialog. This process is recommended for product features, for example. Independent of that, users can create a feature from a dynamic value list or use the menu option "Add relation" to create one.

Asset references

There is a third value type in features, namely asset references or asset resource key references. Because both types are not distinguishable in the configuration or for users, this article will only address asset references, but both types are always meant here.

Asset references are hybrid structures that have properties of both a feature and a relation. They are created in the Admin Client as features. For example, a newspaper editorial team works with both in-house employees and freelance authors. All authors are represented in censhare by a person asset. In text assets, the feature "Author" is created. Using an asset reference, every text can be assigned to an author. To do that the text asset saves the asset ID of the author in the "Author" feature.

Technically speaking, an asset ID or a resource key is saved in the parent asset when creating a reference. However, for asset references, the user interface in censhare Web doesn't show the ID or key saved in the feature, but rather the referenced asset itself.

To create or display an asset reference, users go to the asset menu and open the "Add relation" or "Display relation" dialog in censhare Web. From the user perspective, references are more like relations despite the fact that technically speaking they are features. 

For an asset reference, only the asset that refers to another asset will save the reference as a feature, but it won't save the referenced asset as such. An asset can save multiple asset references with the same feature if the parameter "Multiple values" has been activated in the feature. For example, a text can have multiple author references. censhare then creates a feature for every asset reference in the parent asset.

In the XML representation of an asset, asset references are displayed as follows (additional XML attributes were left out for clarity here):

<asset_feature asset_id="20590" 
               feature="censhare:feature.author" 
               value_asset_id="20611" />

The element <asset_feature> represents a feature. censhare creates an XML tag for every feature. The name of the feature is "feature" in the XML attribute. The value - in this case the ID of the referenced asset - is "value_asset_id" in the XML attribute. This name tells censhare that the value is not to be interpreted as a string or a number, but rather as a reference to another asset.

Schematically, an asset reference is structured as follows:

The parent asset (1) possesses a feature (2) with the value type "Asset reference“. The feature value is the ID of the referenced asset. The asset reference (3) refers to the child asset (4) with the ID indicated in the feature. The reference is unidirectional and is only saved in the asset feature.

But censhare also has further configuration options for users to apply asset references in a similar way to applying asset relations. For example, a parent relation and a child relation can also be entered for references, and filters can be set for the parent and child context. 

Note: The direction-specific display of asset references is only available when creating a reference. Under the menu option "Show relations", references are only displayed in the child relation. For more information see the section "References and relations from the user perpective".

Relations

Unlike asset references, relations are saved in their own database table independently of the related assets and represented in both related assets. Both related assets know about each other.

For example, in some cases it makes sense in a relation to show the author connection referred to in the previous section as a reference. The author is then not a feature of the text, but instead a third element that relates a text with a person. The meaning of this relationship is "Author".

Relations can be augmented in the censhare data model using metadata. Metadata is configured as a feature and saved in the relation. That is possible because every relation is saved as its own dataset. Technically speaking, asset and relation features are the same. They only differ in that they are saved in an asset and in a relation, respectively.

With a relation feature, for example, you can describe the "Author" relation with a "Status" feature. In the feature you can enter whether it is an in-house author, a freelance author, a main author or a co-author. The feature only serves this special relation. The same person can be a co-author one time and another time a main author of a text. In both cases he/she is the author of a text, not the editor responsible for it. For more information see the section "Relation features".

Directional dependencies

Relations can be direction dependent or direction independent. This characteristic also says something about the type of relationship between two assets, but not about the assets themselves. This becomes clearer with these two examples:

The "Cross-selling" relation is a direction-independent relationship between two products. It doesn't matter which direction you see this relationship from. For both products, the other product is a "cross-selling" opportunity. That means, every one of the related products can be cross-sold when one of the other products arises in a sales situation.

It's different when the relation type "Accessory" is selected. There are also two products connected here, for example a pack rack and a bicycle. The relationship "Accessory" is direction dependent. A pack rack can be an accessory for a bicycle, but a bicycle can't be an accessory for a pack rack. censhare expresses this using different names for the relation. In the direction Bicycle > Pack rack the relation is "Accessory from" but in the other direction it is called "Accessory for". You can define the direction-dependent names when creating a relation in the Admin Client.

Number of possible relations

In principle, two assets can have unlimited relations in which each one describes a certain connection or a partial aspect of that connection. If you look at one concrete type of relation, you can in turn define in different cases how many parent-child relations exist there. The direction is also taken into consideration here. The possible number of related parent or child assets is expressed in censhare in the "Usage" field.

Even if an asset has multiple relations of the same type, censhare creates a separate dataset for each of these relations. If asset A has an author relation to assets B, C and D, censhare creates three relations in the database for relation A-B, A-C and A-D.

Related assets are saved in pairs in the notation parent asset / asset ID and child asset / asset ID. This dataset is stored by censhare in the Oracle database in the table asset_rel. The relation is not saved in the asset datasets of the Oracle database. Still, the censhare database (cdb) creates an XML representation of every asset. Relations are displayed in there by a "Parent relation" or "Child relation" element. For more information see the section "Database storage and performance of relations and references".

In the XML representation of a parent asset, an asset relation is recorded as follows (additional XML attributes were left out for clarity here):

<child_asset_rel child_asset="20590" 
                 parent_asset="20611" 
                 key="user.product-part" />

The element <child_asset_rel> represents a relation in the parent asset. The connected assets are saved in the XML attributes "child_asset" and "parent_asset". An additional XML attribute "key" contains the relation type. The same relation is represented in the child asset by the element <parent_asset_rel>. The XML attributes are identical:

<parent_asset_rel child_asset="20590" 
                  parent_asset="20611" 
                  key="user.product-part" />

The asset (1) contains a child relation and the asset (3) has a parent relation. This relationship is displayed in the relation (2), which is saved separately from the connected assets. On the other hand, in (2) the ID of the parent asset (4) and the child asset (5) are saved. The relationship is bidirectional. In (2), other features can be saved as well.

Relation metadata

Relations can have properties. These are saved as metadata in a relation. Relation properties can take on the following tasks, among other things:

• Assigning a whole number value to a relation: This can be a whole number value, for example to give a ranking to a product in the "Up-selling" relationship, or simply to assign a meaning. Up-selling offers can then be output in descending order.

• Assigning an amount to a relation: For example, in the "Budget for" relationship you can enter an amount. The "Budget" relation then represents a partial aspect of the relationship between a task and a person or department. The budget recipient (person or department) may have the assigned amount for the task.

• Assigning a role to a relation: This allows you to define containers and widgets for different roles in the change variants of module assets in the workspace, i.e. asset pages. The module assets are connected via the "Resource replace variant" relation with the associated standard module asset and the desired role is assigned to the relation. For more information see the article "Assets in the standard workspace structure" and "Modifying module assets using replace variants“.

• Assigning a sub-type to a relation: Create a value list of sub-types for a feature in order to characterize it more accurately. For example, the relation "Author" can be selected as "Co-author", "Main author", "Publisher" or "Ghostwriter".

Relation properties are configured like asset features in the Admin Client. In the "Target object" feature parameter you need to select "Asset relation". For more information on configuring features see the article "Creating a new feature".

The relation feature is then created in the system but users still can't add a feature to a relation. To do that, you need to add the right widget to the right asset page definitions. This satisfies two functions:

First, it defines a relation type that is assigned to the feature. Second, it generates a metadata dialog in which the user can enter a value. An example configuration can be found in the article "Example relation feature configuration and relation metadata dialog".

References and relations from the user perspective

In censhare Web, users work with relations and references in a similar way. You can show relations and references in the asset menu and search for relations and references using the various search options. The widget "Asset list based on related assets" displays assets of a certain relation type or a certain reference. Multiple widgets can be configured for an asset page.

The following table presents relations and references in their various functions in censhare Web:

Note (1): The full-text search must be indexed for this function. For more information see the section "Configuring the full text search for features and referenced assets".