Customization best practices

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

The customization of master data and module assets is done in XML files. The following best practices are important to avoid errors or bad coding.

Prerequisites

• Administrator permissions

• Access to the censhare Admin Client

• SSH access to the file system of censhare Server. Minimal access is required to the censhare-Server and censhare-Custom directories.

• A common understanding of the configuration of the censhare Server, especially master data and modules.

Introduction

Customization of a censhare system is done in master data and module assets. The masterdata.xml file is the main instrument to define and maintain custom master data. Asset XML files are used to define maintain custom module assets.  

The master data and module asset XML files are managed with third-party tools. For example, git, RPM, or scp (Secure copy). These software tools allow you to version and port customizations to another censhare system. Automatic or manual synchronization then imports these XML files into the system and creates or updates the respective assets. 

Custom master data

Best practices

• Do not manage custom data in the censhare Admin Client. 
• Create and manage custom master data in masterdata.xml files in the censhare-Custom folder.
• Use the censhare Admin Client to define master data, export them as XML and add the XML to a masterdata.xml file.
• Be careful with your definitions: Definitions in masterdata.xml files overwrite all existing master data.

• Always edit the masterdata.xml file for changes. Changes in the censhare Admin Client are not written back to the file

Special cases

• Users/User groups: As of version 2019.2, censhare uses log-in names as unique identifiers of users. IDs to refer to users or user groups are deprecated.
• User groups: Use log-in names to add users to a user group definition. 
• Workflows: Use the log-in name to add a user as the default target for a workflow step. 

Deletion

• Master data cannot be deleted via masterdata.xml files.

• Exception 1: Feature values of Features. If a feature value is removed from the feature definition, the feature value is also removed from the master data in the server. The feature itself cannot be deleted this way.

• Exception 2: Workflow steps of a workflow. If a workflow step is removed from the workflow definition, the workflow step is also removed from the master data in the server. The workflow itself cannot be deleted this way.

Custom module assets

Best practices

• Define all custom module assets in asset XML files in the censhare-Custom folder. 

• There is no easy way to keep track of changes if module assets are directly created in the system.
• To change an asset, always edit the asset XML file. Changes that you do directly in censhare Web or the censhare Client are not written back into the file. 
• To create an asset XML snippet, define module assets in censhare and export the assets via Export module asset. This removes system attributes from the XML. 
• If standard Module assets change after a system upgrade, you must also change or delete the corresponding custom Module assets that replace these standard Module assets.
• Always add a unique identifier to the asset XML definition. 
• Use the resource keys as ID whenever possible.

• Do not use asset IDs in asset XML files or XSLTs. This does not allow to transfer of the XML files to another censhare system.

Asset XML

• To create an asset XML file, configure the asset with all needed features in censhare. Use Export module asset to export the XML. 
• Do not set attributes in the asset XML that are added by the system. This causes censhare to create a new asset version with each synchronization. 

Folder structure

• Storage items or master data that are referenced in an asset XML file must already exist when the folder is synchronized. 

• To ensure that assets are created in the required order, add prefix numbers to the folder names of the custom modules. 

• Only place the minimal number of asset XML files and master data definitions in one folder. If the synchronization fails, fewer data are affected and troubleshooting is easier.

Deletion

• To delete an existing asset, add the attribute deletion="3" in asset XML file. The asset is then physically deleted with the next synchronization.

Synchronization of custom data

• The Synchronize module assets (runtime area) configuration must be activated.

Other topics

Server Modules

• Do not add a command-owner in server action configurations. If the user does not exist anymore, the server crashes when the command is executed.

Solved topics

• Synchronization: Custom folders are synchronized at every restart of the server. After restarting the server, manual synchronization is no longer necessary.

• Resource replace variants from workspace assets: Custom resource replace variant relations are no longer overwritten when the server restarts. Customization of the workspace is no longer reset.

Result

You know the best-practices when you are creating custom master data and module assets.