Add custom Module assets

Note: Please use the recommendations described in this article with care. They should only be carried out by experienced partners. Advanced knowledge is required: A common understanding of the configuration of the censhare Server, especially the meaning, usage, and dependencies of the definitions in the Master data tables.

Target groups

Solution developers

Partners

Context

• This article describes how to create asset XML for custom Module assets.

• Each Module asset XML relies on master data definitions, for example, feature definitions. You can create your own definitions that are stored in masterdata.xml files.

• A synchronization creates Module assets from the custom asset XML.

Prerequisites

• Administrator permissions

• Access to the censhare Admin Client

• SSH access to the file system of censhare Server (censhare-Server" and censhare-Custom directories).

Introduction

The Module assets are the main source of the censhare system configuration. For example, workspace Module assets describe the setup of user workspaces. Each system comes with preconfigured Module assets that are needed to operate the server.

On top of this, you can add custom Module assets, which depend on the specific project requirements. Custom Module assets are defined and stored in asset XML files.

Custom Module asset files are stored separately from the standard Module asset files to ensure that your customizations are not overwritten when you update the system.

Advantages of asset XML files for customizations:

• Portable from one system to another.

• Store the complete customization in one directory.

• Manage customizations in a git repository
  
  

(1) It is possible to create custom Module assets directly in a censhare system. It is not recommended to use this method for several reasons: There is no easy way to keep track of all custom Module assets. There is no easy way to transfer custom Module assets to another system. It is not possible to keep track of changes in custom Module assets.

(2) The use of asset XML to define assets is not limited to Module assets. You can also define other assets and synchronize them with the censhare Server.

You can use custom Module assets to define asset XML. You create the desired Module asset in censhare. The Module asset is then exported as an asset XML file and further definitions like asset relations can be added.

Module assets in censhare

All standard Modules are based on Module asset files, for example:

• Brandings

• Categories

• Completeness checks

• Content Editor setups

• Macros

• Metadata dialog and display templates

• Reports

• Searches

• Tables

• Transformations

• Workspaces

An asset XML file contains the following elements and attributes:

• a unique identifier (usually a resource key)

• asset attributes (domains, workflow target, workflow step, etc.)

• asset features

• asset relations

• asset references

• asset files (master, preview, thumbnail, etc.)

The standard Module file definitions comprise mandatory and optional Modules. Optional Modules provide additional functionality, for example, server actions, chart templates, sample assets.

You find all standard Module files in the following directories: 

$stringEscapeUtils.escapeHtml($body)

The custom definitions of Module files use the same XML schema as the standard Module files. Custom Module files are placed in the censhare-Custom directory.

When the censhare Server starts, it checks if a standard Module files or a custom Module file exists. If the corresponding Module asset does not exist, it is created. Otherwise, the existing Module asset is updated. There are server actions to manually synchronize standard and custom Module files.

Customizations of Module assets must be done in the corresponding Module XML files. Customizations that you do in a Module asset cannot be written into the original Module XML files. When you synchronize module assets, any changes of the original Module assets are overwritten.

Data definitions that are used in Module assets are stored in the master data. censhare provides a standard set of master data. To add custom master data, you create a masterdata.xml file in the censhare-Custom directory. 

The use of asset XML to define assets is not restricted to Module assets. You can define other assets and synchronize them with the censhare Server.

Key steps

• Module asset files: Get familiar with the XML structure of a Module asset. Understand how to work with attributes, features, files, references and relations.

• Work with Modules files: Learn how to set up a folder structure for your different Module files. Get familiar with some points when you create, update Module file or delete a Module asset created via a Module XML file.

• Synchronize custom Module files: Learn how to synchronize the Module assets. Understand the update and synchronization process.

Build your own Module asset files

To start from scratch, create a Module asset in censhare and export the asset in an XML file. Edit the XML file.

The asset XML

An asset XML file is based on pure XML and has the ".asset.xml" file extension.  

The root XML tag is asset:  

<asset ...> .... </asset>

A basic set of asset properties is defined as attributes of the <asset> tag. All other asset properties are set as <asset_feature> tags. The reason for this is the technical implementation of the storage of the property values in the relational database.  

The asset table in the database stores all values that are stored as attributes of the <asset> tag. For each asset, there is an entry with its basic properties like domain, workflow step or workflow target. For example, the <asset> tag for a transformation Module asset:  

<asset name="censhare:report.exchange-rates-usd"
		type="module.transformation."
		application="texteditor"
		domain="root."
		domain2="root.”>
</asset>

The <asset_feature> tags are stored as entries in the asset_feature table. Each entry represents a property with its attributes. For each property that is stored as a feature, there is also a feature definition in the feature table in the censhare Admin Client. For example, the XML entry for a localized name property of an asset: 

<asset_feature feature="censhare:name"
				language="en"
				value_string="Exchange Rates US Dollar"/>

Unique identifier

A unique identifier is required to check, if an asset already exists upon synchronization. If the asset exists, censhare updates it. If the asset does not exist, or if the XML file does not contain a unique identifier, censhare creates a new asset.  

The following unique identifiers can be used:

• resource key: It is set as feature tag in the asset XML. An asset can be found via its resource key, independent of the domain it is located in. The resource key can identify an asset on different systems. The system does not create a resource key if there is none present in the asset XML: There is no possibility that the key interferes with values created by the system. This is important if you transfer the file to another censhare system. It is recommended to define a resource key as unique identifier whenever this is possible. 

  For example, the XML entry for a resource key: 

  <asset_feature feature="censhare:resource-key"
  				value_string="censhare:report.exchange-rates-usd"/>

  CODE

• id_extern: This attribute is used to identify assets that are imported through an interface from an external source. With the next import, censhare can detect if the asset already exists and update it instead of creating a new one. If the asset XML does not contain the attribute, censhare creates a value during the synchronization. As of that, it can interfere if you transfer the asset XML file to another censhare system. 

  Example id_extern: 

  <asset name="Test, Module 2"
  		type="person."
  		application="metadata"
  		domain="root."
  		domain2="root."
  		language="fr"
  		id_extern="sd:TestModule.Person2">

  CODE

• UUID: If the asset XML does not provide a feature entry with the UUID, censhare creates a value during the synchronization. As of that, it can interfere if you transfer the asset XML file to another censhare system.   

  Example UUID: 

  <asset_feature feature="censhare:uuid"
  				value_string="sd:UUID-Personal-asset-15"/>

  CODE

The ID of an asset is not suitable as a unique identifier that is valid on different systems. The asset ID is automatically created by the system and is different on each censhare system. It is also not known until the asset has been created from the asset XML file for the first time.

Storage items

You can add storage items (asset files) to XML configuration. The storage item can be the master file or other files, for example, a PDF and a preview file.

Example:  

<storage_item element_idx="0"
			key="master"
			mimetype="application/indesign"
			relpath="file:New York magazine.indd"
			color="rgb"/>
<storage_item element_idx="0"
			key="pdf" mimetype="image/jpeg"
			relpath="file: New York magazine.pdf"
			color="rgb"/>

The key attribute defines the kind of the file, for example, master or pdf. For a list of all possible values, see the file types table in the Master data section of the censhare Admin Client. For a list of the MIME type values, see the MIME types table in the Master data section. The relpath attribute stores the relative path and the name of the file. The relative path starts folder of the file.  

You must also create an index entry for the files. If not, the asset creation fails. For example: 

<asset_element idx="0" key="actual." isversioned="1"/>

Asset relations

censhare has directed and non-directed relations. A directed relation has a parent asset and a child asset. In non-directed relation both assets are handled equal. In the asset XML in censhare you cannot detect if the relation is directed or not.

Both are configured directed relations in the asset XML: One asset has the <child_asset_rel>tag and the other asset the <parent_asset_rel> tag. For the direction of the asset relation, go to the censhare Admin Client to the Asset relation types table in the Master data folder. The attribute Type of an asset relation stores the direction type.  

The asset relation is identified by the key attribute in the XML tag, which is the ID of the asset relation, for example, key= "user.product-supply." For list of all IDs, see the Asset relation types table in the censhare Admin Client.  

To create an asset relation in the XML file, use the following tag and attributes:

(1) The related asset must already exist.

(2) It is best practice to use files as ID for referencing other asset XML files in the same custom directory. If you refer to a file in another directory, you must ensure that this directory has already been processed before actual one.

Asset references

An asset reference is stored as an asset property. The stored value is an ID of another asset.

The "<asset_feature>" XML tag for asset reference has two attributes:

• The asset feature that stores the asset reference.

• The type of ID that points to the referenced asset:

  • UUID

  • Resource key

  • File: the name of the asset XML file that is referenced.

If the asset feature for the desired reference does not exist, create an entry for it in a masterdata.xml file. Among other settings, set the following attributes for asset feature entry depending on the used ID:

To reference an asset in asset XML file, use one of the following ID types:

The referenced asset must already exist. For more information on sequence of folders, see Create folder structure.  

Full example

<?xml version="1.0" encoding="UTF-8" ?> 
<!-- basic asset attributes --> 
<asset name="censhare:report.exchange-rates-usd" type="module.transformation."
application="texteditor" domain="root." domain2="root.”> 
<!-- set further attributes as feature values --> 
<asset_element idx="0" key="actual."/> 
<asset_feature feature="censhare:name" language="de" 
value_string="Wechselkurse US Dollar"/>
<asset_feature feature="censhare:name" language="en" 
value_string="Exchange Rates US Dollar"/> 
<asset_feature feature="censhare:resource-enabled" value_long="1"/>
<asset_feature feature="censhare:resource-in-cached-tables" value_long="1"/>
<asset_feature feature="censhare:resource-key" 
value_string="censhare:report.exchange-rates-usd"/>
<asset_feature feature="censhare:resource-usage" 
value_key="censhare:report-transformation"/> 
<!-- asset relation: points to the other asset via its resource key -->
<child_asset_rel key="user.exchange_office." 
child_asset_ref_resource_key="sd:location.city.SanFrancisco"/> 
<!-- asset reference: refers to another asset via its resource key --> 
<asset_feature feature="censhare:transformation-localization" 
value_asset_key_ref="censhare:localization.transformations"/> 
<!-- files assigned to the asset --> 
<storage_item element_idx="0" key="master" mimetype="application/xslt+xml" 
relpath="file:censhare_report.exchange-rates-usd.xsl"/> 
<storage_item element_idx="0" key="preview" mimetype="image/jpeg" 
relpath="file:censhare_report.exchange-rates-usd.preview.jpg"/>
</asset>

Attributes

For available attributes of the XML tags, see the "censhare server database schema (corpus)" file on the censhare Server:  

$stringEscapeUtils.escapeHtml($body)

Each XML tag is represented by a table definition in database. The columns are the attributes for the XML tag. For example, for the <storage_item> XML tag there is the STORAGE_ITEM table.  

If you add attributes from the table definition to the XML, be careful. It can lead to the problem that censhare creates a new version each time the censhare Server starts or the Update server configuration is executed.

The reason for this is that some of the attributes are set by the system when it creates the asset from asset XML file. If you set them in the file, they are overwritten by the system. When censhare then compares the actual asset version and the version in the asset XML file, they are different.  

It is recommended to define the desired asset in censhare and then export it via the Export module assets server action. The export removes all attributes that are set by the system from the asset XML. For more information, see Create asset files.

Module files

Folder structure

Custom asset XML files are stored in the censhare-Custom directory in a dedicated directory in the following path: 

censhare-Custom/censhare-Server/app/CUSTOMER_NAME/

You can use a folder structure to organize your files for a better overview. For example: 

censhare-Custom/censhare-Server/app/masterdata/
censhare-Custom/censhare-Server/app/assets/
censhare-Custom/censhare-Server/app/test/

In the "test" folder you can place asset XML files that are in the developing state, for example. On a productive system, you then configure once that only the "masterdata" and "assets" folders are synched. So, you only have to configure once which custom folders are synchronized on which system.

The synchronization process is folder-based. If there is an error during the synchronization of a folder, the complete folder is ignored. Child folders are not affected. Working with multiple folders makes it easier to find errors.

censhare processes the custom folders in alphabetical order. To ensure that module assets are created in the required order (for example, if you create asset relations), use prefixes:

• 01_widgets

• 02_container

• 03_pages

Asset relations

Custom asset XML files can relate on each other. Related assets must already exist when censhare reads an asset XML file. For example:

• The referenced asset is part of the standard assets in censhare.

• The asset XML file with the referenced asset is placed in the same folder as the actual asset XML file.

• The asset XML file with the referenced asset is placed in a custom folder that comes before the actual asset XML file in alphabetical order.

For example, an asset XML file in the 02_container folder can relate to an asset XML file in the 02_container or the 01_widgets folder, but not to the 03_pages folder. For more information on sequence of folders, see Create folder structure.  

If the related asset does not exist, an error occurs and the folder is skipped. A message is only written into the server log. No warning is displayed.

Create assets files

The recommended way to create an asset XML file:

1. Create the asset in censhare.

2. Configure the asset.

3. Create the asset XML file via the Export module assets server action.

4. Add a unique identifier.

5. Adapt it to your needs.

The Export module assets server action does not include the master data definitions that are used in the asset. If you use custom master data, you must define them in a masterdata.xml file.

Update asset files

If you update the asset XML file, censhare updates the asset when the synchronization process is executed. Existing values are updated and new values added. If you remove an entry in XML file, the according value is deleted in the asset.  

Note: censhare only updates an asset if there is a unique identifier in the asset XML. Without a unique identifier, censhare creates a new asset each time the synchronization is executed.

Standard Module files

If you want to change the behavior of standard Module assets, create a Resource Replace Variant (RRV) for it as asset XML.   

Warning: Do not overwrite standard Module files with custom Module files. If you change the standard Module files, you can severely damage or break the system.

When you update or patch a system, Standard Module assets can change. This can affect standard Module assets with a RRV. If the updated standard Module assets have a different data model than RRVs that were created earlier, they throw an error.  

1. Check after a system upgrade if standard Module XML files, that have an RRV, have been changed.

2. Adjust the XML fields of the RRVs according to the new Standard Module XML.

3. Replace the Module asset XML file with the new updated version.

Delete assets

You can also delete an asset that you created via an asset XML file. This requires a unique identifier: Add the deletion attribute to the "<asset>" tag in the asset XML file and set it to "3". With the next synchronization the asset is physically deleted. For example: 

<asset name="Brand" type="module.branding." deletion="3" ...>

View XML from assets

To learn more about XML of an asset, you can inspect existing assets. In the censhare Client:

1. Change into the Admin mode.

2. Right-click the desired asset in the query window.

3. Select Admin and then Show XML.

4. A window opens with the asset XML.

In censhare Web:

1. Change into the Developer mode.

2. Open the asset in question in an asset page.

3. Click the asset page menu and select Show asset XML.

4. A window opens with the asset XML.

Configure Export module assets

1. Open the censhare Admin Client.

2. Go to the Export module assets entry in "Configuration/Modules/Administration/Module Assets/" and open it.

3. In the General setup section select Enabled.

4. Click OK.

5. Synchronize the changed configuration with the Master server, and if existing Remote servers.

Edit synchronized Module assets

Depending on what a user changes in an asset that is defined by a custom XML file the changes are kept or overwritten during the next synchronization.

Changes by a user are overwritten if:

• A user changes a value that is defined as attribute in the "<asset>" XML tag, for example domain or workflow target.

Changes by a user are kept if:

• A user changes a value that is defined as "<asset_feature>" XML tag. censhare stores the party ID of the user that changed the feature. If this is not the system user (party != "1"), it will not overwrite the feature.

• A user adds a feature that is not defined in the asset XML file.

• A user changes one of the following asset features: censhare:resource-enabled, censhare:resource-in-cached-tables, and censhare:enabled.

This is even true if you set another value in a feature entry in the asset XML file.

Synchronization of custom modules

When the censhare Server starts, the synchronization of the XML asset files is executed. You can manually execute the synchronization using the Update server configuration server action. For more information, see Synchronize custom data.

Result

You know the construction of the asset XML for Module files. You can create your own asset XML files and customize them to your needs.