Synchronize custom data

Custom master data and Module asset XML files must be synchronized with the censhare Server to become active. Overview of the synchronization and how to execute it.

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

Custom master data are defined in masterdata.xml files.
Custom module assets are defined in asset XML files.

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

After porting and distributing master data and module asset XML files to a system (for example, to a QA or production server), the definitions stored in the XML files must be executed. The execution is called synchronization. censhare automatically synchronizes the XML configuration files at startup. To introduce changes to a running system, you can execute the synchronization manually. For example, to introduce and test changes in the files to a running system.

For example, transfer and synchronize changes to a QA system for testing and acceptance of change requests. After acceptance and approval, transfer the changes to the production system and synchronize the system.

The synchronization processes the respective directories and sub-directories in alphabetical order. Each folder to synchronize has to be added to the Server configuration. If there is an error while the synchronization of a folder, all XML configuration files in that folder are not synchronized.

Update of master data

If a masterdata.xml file is synchronized, censhare creates new entries for all definitions that do not exist in the database. Definitions that already exist are updated. No definitions are deleted. If you remove an entry from a masterdata.xml file, this has no effect on the definitions in the database.

If entries in the master data are added via synchronization, they are locked in censhare Admin Client. To change these master data, edit the respective masterdata.xml file, upload it to the server, and synchronize the server.

Update of module assets

Identify changes in asset XML files

During the synchronization, censhare copies all files from the custom directories to the corresponding directories in the working directory of the censhare Server. Each asset XML file is compared to the XML representation of the corresponding asset in the system. If censhare detects a difference, the asset is updated.

Identify existing module assets

To update an existing module asset, the XML definition must contain a unique identifier. Otherwise, censhare creates a new asset instead of the existing one, each time the synchronization is executed.

General rules

Asset attributes:

The synchronization replaces all attribute values in the asset with the values that are written into the asset XML. Any changes by users of these attributes are overwritten.
Changes of other attributes by users are kept.

Asset features and asset relations:

XML entries from the asset XML file are synchronized. Changes by user for these features or asset relations are overwritten.
Users can add additional features and asset relations. These features and relations are not affected by synchronization.

Update of asset features

If an asset feature is created during a synchronization, censhare sets the system user as origin in the feature entry: attribute party="1".
Asset features are synchronized if they have been created by the system user (party="1") :
- Not existing asset features are created.
- Changed values of asset features are updated.
- Asset features are removed if there is no longer an entry in the asset XML file.
If a user changes one of the following asset features, they are not overwritten during synchronization:
- censhare:resource-enabled
- censhare:resource-in-cached-tables
- censhare:enabled

Update of asset relations

If an asset relation is created during synchronization, censhare adds an asset relation feature with the ID "censhare:module-rel". The attribute value_string stores the source of the relation. This allows to decide if this is a custom-defined relation or a relation that was created by the system. For example:
CODE
```
<child_asset_rel child_asset="234152" child_currversion="0”      
key="user.javascript-controller." parent_asset="234154">
   <asset_rel_feature feature="censhare:module-rel"
      value_string="/opt/corpus/work/runtime.master"/>
    </child_asset_rel>
```
The asset relation feature is created because there is no attribute that stores the user that created the relation.
All asset relations that have this special asset relation feature are synchronized:
- Not existing asset relations are created.
- Changed asset relations are updated. An asset relation is identified by its asset relation key and the referenced asset.
- Asset relations are deleted if the corresponding entry in the asset XML file is removed.
If an asset relation is removed by a user, it is only recreated if the corresponding asset XML file changes.

The synchronization process

The synchronization process consists of two parts:

Update server configuration server action:
- censhare copies the asset XML files to corresponding folders in the runtime.SERVER_NAME folder in the working directory of the censhare Server.
- For example: censhare-Custom/censhare-Server/app/PROJECT_1/MODULES_1 to censhare-Server/work/runtime.SERVER_NAME/ PROJECT_1/MODULES_1.
- If there are changes, censhare creates a config event.
Synchronize system module assets (runtime area) server action:
- Listens for config events.
- Starts the synchronization of module asset files. The server action only reads folder that is stored in its configuration.

Time of execution:

Start of the censhare Server
Execution of the Update server configuration server action

Note: The Synchronize system module assets (runtime area) server action must be activated. Otherwise, no synchronization takes place. This is valid for both ways of synchronization: restart of censhare Server and manual execution.

Steps

Configure synchronization

Each custom folder in censhare-Custom/censhare-Server/app/ or censhare-Custom/censhare-Server/app/web/ directory has to be added for synchronization. This is done in the Synchronize module assets (runtime area) server action:

Go to the "Configuration/Modules/Administration/Module Assets" folder in the censhare Admin Client.
Open Synchronize module assets (runtime area) server action.
Click the plus icon in the Search paths section: a new Path text field opens.
Enter the relative path of the custom directory. It points to the directory "../censhare-Custom/censhare-Server/app/". For example, if the full path is "../censhare-Custom/censhare-Server/app/custom_defs", enter "custom_defs".
Ensure that the enabled checkbox is selected for the added path.
Click OK.
Update the server configuration.
Synchronize with remote servers if existing.

Manual synchronization

In the censhare Admin Client click Server actions.
Select the Update server configuration entry in the list: a dialog window opens.
Select Refresh last changes for the Mode field and All for the Range field.
Click OK.
A dialog opens and shows all files that have changed. If there are configuration errors, these are also shown. Click OK if there are no errors shown.
Otherwise, work on the errors and try again.

Always check the server log to be sure that there are no errors after synchronization. There is no extra error message shown while the synchronization.

Result

You understand how custom master data definitions and custom Module assets are updated while synchronization. You know that the synchronization is executed when the censhare Server restarts. You can manually execute the synchronization. You know that errors during the synchronization are only written into the log file. There is no additional warning.