Masterdata store all the basic data that are needed to operate censhare. censhare provides a standard set that is imported via an insert-data.xml file. To add custom definitions, you can add your own masterdata.xml files. This article gives you an overview of how to work with master data and create custom definitions.
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
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.
Context
The master data are an essential configuration part of a censhare system. They contain all the data definitions that are needed for the operation of the system. For example, these data define the asset types and file systems. Each system comes with a preset of definitions that allow operating the server.
On top of this, a system requires custom definitions. These depend on the specific project requirements. Custom master data configurations are stored separately from the standard server configurations in XML files. This setup is the basic prerequisite to easily distribute your custom definitions to other servers.
In a typical use case, a solution developer customizes the system for a project. For testing purposes and acceptance of change requests, the customization data are transferred to a QA system. After acceptance and approval, the changes are then transferred to the productive system.
Introduction
The masterdata.xml file is the main instrument to define and maintain custom master data. The masterdata.xml file is then copied to other censhare systems to synchronize the master data definitions there. The common practice is to maintain all master data definitions for a project in masterdata.xml files only, not via the censhare Admin Client. This is the only way to ensure that all master data definitions can be safely transferred to another system.
The censhare Admin Client provides an interface to edit master data. This interface should only be used for development and test purposes, not for customizations of production systems. Changes in the censhare Admin Client cannot be tracked, transferred, or reverted.
The best practice to customize master data is to use one or more masterdata.xml files.
Note: You create any masterdata.xml file at your own risk because you can overwrite standard definitions in the Master data tables that are still needed.
Key steps
Master data in the censhare Admin Client: Learn how to use the censhare Admin to create XML entries for master data definitions.
The insert-data.xml file: Learn how censhare imports the standard master data and how this is related to the Master data section in the censhare Admin Client.
The masterdata.xml file: Learn how to add custom master data definitions, and how insert-data.xml and masterdata.xml relate to each other.
Note: If you want to transfer your masterdata.xml to another system, there are some special cases. For instance, you cannot use IDs to identify users or user groups on other systems. So, there is another solution with login names.
Master data in the Admin Client
Concept
All master data in the censhare System are maintained in database tables. The censhare Admin Client is a simple interface to access and manipulate these data in the database. For each entry in the censhare Admin Client, there exists a corresponding table in the database. For example, the database table domain corresponds with the 1st Domain table in the censhare Admin Client.
Important: It is not recommended to maintain production master data in the censhare Admin Client. Us the following procedure to develop custom master data that you export as XML snippet and add to the masterdata.xml file:
- Create or edit the respective entry in the desired Master data table in the censhare Admin Client.
- Export the entry as XML definition.
- If necessary, edit the XML directly.
- Add the XML snippet to the masterdata.xml file of the respective project folder in the censhare-Custom area of your censhare Server.
Create master data
To change master data in the censhare Admin Client:
Open the censhare Admin Client.
Go to the respective table in the Master data folder.
Open the table with a double-click.
Add, edit, or delete the desired data.
All changes take effect immediately. No server synchronization action is required.
Import and export master data
Export
When you enter master data in the censhare Admin Client, you can export the customization as XML:
Open the table in the Master data folder whose definitions you want to export.
Mark the entries you want to export.
Click Export icon in the top bar of the master data table.
A file dialog opens; select the name and location for the file and then Save.
The export file includes, among others, the enclosing XML tags for the exported Master data table. Inside the closing tags, you find the XML definitions for the exported entries. Add these XML snippets to the masterdata.xml file. For more information, see
Import
Note: Is it not recommended to transfer master data by importing them into the censhare Admin Client. Use the import function only for test purposes. For system configurations, always use the masterdata.xml file in the respective custom directory. Otherwise, it is not possible to ensure that all data are always transferred to another system.
Any exported XML definitions can be imported back into the same or any other system:
Click the Import icon in the top bar of the censhare Admin Client.
The Import XML files dialog opens.
Click Open file for import and select the XML files you want to import.
To import another XML file, repeat the previous step.
To remove a file from the list, click the Delete icon.
To start the import, click the Import icon.
A dialog window shows a summary of the possible imports.
Select the desired action: imports and changes, only imports or only changes.
Click OK to start the import.
The insert-data.xml file
Concept
The insert-data.xml file contains standard master data that are required to start a censhare system. To access the file go to:
../censhare-product/censhare-Server/app/config/insert-data.xml
This file contains all definitions that are required to start a fresh censhare system. This insert-data.xml file is only executed at the first system startup.
If you update your system, a database update package is provided. This package contains an insert-data.xml file to add or update master definitions for the new version. Update packages are stored in the following folder:
../database/update/
For example, there is the update package for version 2019.2. You find it in the folder
../database/update/update_pack_2019.2/
The following folder contains the related insert-data.xml file:
../database/update/update_pack_2019.2/config
If you update your system over multiple versions, censhare installs the update packages for each version consecutively:
2018.1 to 2018.2
2018.2 to 2018.3
2018.3 to 2019.1
2019.1 to 2019.2
Each XML entry in insert-data.xml always contains the primary key of the respective database table as an attribute. censhare uses the primary key to detect if a table entry of the XML entry already exists. If this is true, censhare updates the table entry. Otherwise, censhare creates a new table entry.
You can find the table definitions of the database in the following file:
../censhare-Server/database/doc/index.html
When censhare creates an entry from the insert-data.xml file, it stores the path of the source file in the source attribute, for example:
source="censhare-Server/app/config/insert-data.xml"
Attributes of an entry that are imported via the insert-data.xml, are locked. To edit these attributes in the censhare Admin Client, switch to the Admin mode to unlock the entries.
After initialization, censhare excludes the following tables from updating via insert-data.xml:
asset_del_policy
filesystem_def
filesystem_repl_def
party
server_def
Typically, projects adapt or add entries in these tables. As insert-data.xml cannot write into these tables, it cannot change custom definitions in these tables by accident that have been added later on a customer system.
The structure of insert-data.xml
The XML schema of an insert-data.xml or a masterdata.xml file is as follows:
<?xml version="1.0" encoding="UTF-8" ?>
<data xmlns:corpus="http://www.censhare.com/xml/3.0.0/corpus"> ... </data>
The "xmlns:corpus" attribute in the "<data>" XML tag references to the definition for "corpus" namespace. This declaration is required for specific attributes in the insert-data.xml.
Note: If you do not use these attributes in your masterdata.xml file, you do not need the namespace declaration.
All master data entries for a certain table must reference the respective database table:
<domains>
<domain pathid="root.custom_tests." parent="root." shortname="custom_tests"
name="Custom Tests" sorting="13" enabled="1" tcn="0" rowid="81"/> </domains>
The table for the first domain in the database has "pathid" as its primary key. censhare searches if there is a table entry where pathid = "root.custom_temp." If a table entry already exists, censhare updates the table entry. Otherwise, censhare creates a new table entry.
Inside the enclosing tags, you find the XML tags for the master data entry. This can be a simple entry like in the example above or an XML structure.
The following table shows the master data tables and their corresponding enclosing XML tags:
Master data table | XML tag |
1st Domains | <domains> |
2nd Domains | <domain2s> |
Application servers | <server_defs> |
Asset applications | <asset_applications> |
Asset relation types | <asset_rel_typedefs> |
Asset types | <asset_typedefs> |
Asset versions | <asset_del_policys> |
Client versions | <client_versions> |
Colours | <colors> |
Events | <events> |
External applications | <ext_apps> |
Feature category group assignments | <feature_categorys> |
Feature groups | <feature_groups> |
Feature types | <feature_types> |
Feature value relations | <feature_value_rel_defs> |
Features | <features> |
File system replications | <filesystem_repl_defs> |
File systems | <filesystem_defs> |
File types | <storage_keydefs> |
Formats | <asset_formats> |
Holidays | <holiday_calendars> |
Image crops | <image_crops> |
Image resolutions | <image_resolutions> |
Languages | <language_defs> |
MIME types | <mimetypes> |
Permission keys | <permission_keydefs> |
Permission sets | <permission_sets> |
Regions | <regions> |
Regions (print) | <print_regions> |
Roles | <roles> |
Schedule types | <schedule_step_typedefs> |
Translation abbreviations | <translation_abbreviations> |
Unit sets | <unit_sets> |
Units | <units> |
User groups | <partys> |
User settings | <user_params> |
Users | <partys> |
Workflow states | <workflow_states> |
Workflows | <workflows> |
The masterdata.xml file
Concept
The masterdata.xml file is used to add custom master data. For example, this can be customizations for a project or a customer. Important: Do not change the file name of the masterdata.xml.
The masterdata.xml file is used to add custom master data. For example:
Custom domain tree
Workflows with workflow steps and workflow states
Asset relations
Feature definitions for assets and references
Languages
Note: The XML schema and structure of the masterdata.xml is the same as insert-data.xml. Do not change the file name of the masterdata.xml
Besides master data definitions, there can also be custom definitions for module assets. All these custom definitions are kept together in an own directory in the censhare-Custom area below the following path:
../censhare-Custom/censhare-Server/app/CUSTOM_DIR
Modules for censhare Web are placed in a folder with the following path:
../censhare-Custom/censhare-Server/app/web/CUSTOM_DIR
There can be more than one folder for custom definition, for example for different projects. Each folder (custom project) can have its own masterdata.xml file.
The structure of masterdata.xml
Insert-data.xml and the masterdata.xml share the same structure.
Overwrite standard master data entries
As of censhare 2019.2, entries in the masterdata.xml file can overwrite all existing definitions in all Master data tables without restrictions.
A masterdata.xml file can only create or adapt master data definitions. It cannot delete already existing definitions!
It is not possible to delete existing definitions. Instead, disable existing master data entries. For example, to deactivate the censhare Defaultuser, set the isactive attribute to "0":
<party id="10" login="censhare" display_name="censhare Defaultuser"
email="corpus@censhare.de" isactive="0" isgroup="0" issystem="0"
locale="en" main_domain="root." main_domain2="root."
main_role="admin" name="censhare Defaultuser">
<parent_partyrel child_id="10" parent_id="2"/>
<party_role domain="root." domain2="root." party_id="10" role="admin"/>
</party>
If you customize a censhare system with version 2019.1 or older, the insert-data.xml and masterdata.xml share the same restrictions and logic when updating master data. masterdata.xml cannot write into the same master data tables as insert-data.xml. Also, not all attributes in certain tables can be overwritten
Configure
The Synchronize module assets (runtime area) server action is part of the synchronization of the masterdata.xml file and module asset definitions. It is located in the "Configuration/Modules/Administration/Module Assets" folder in the censhare Admin Client. Each custom folder, in "app/" or "app/web/", must be added to the configuration for synchronization.
To add a directory path for the custom directory:
Open the 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 checked.
Click OK.
Update the server configuration
Synchronize with remote servers if existing.
Synchronize custom master data
Each time the censhare Server starts, the synchronization of the XML asset files is executed. Besides that, you can manually execute the synchronization using the Update server configuration server action.
Create a masterdata.xml file
To avoid creating master data from scratch, use one of the following ways:
Configure the master data entry in the censhare Admin Client and export it.
Find a similar definition in the insert-data.xml file and copy it.
When you create custom master data, always check for dependencies. For example, if you create a feature definition with child features. You must export the feature and the child feature configurations.
In the censhare Admin Client
Create the entry in the censhare Admin Client
Export the entry from the censhare Admin Client
Add the enclosing XML tags for the respective master data table if not already there.
Copy the XML definition from the export file into your masterdata.xml file.
In the insert-data.xml file
Open the insert-data.xml file.
Search the enclosing XML tag for the respective master data table.
Copy the desired configuration.
Check if the enclosing XML tag for this XML definition in the insert-data.xml already exists in the masterdata.xml.
If not, add the enclosing XML tag to the masterdata.xml.
Paste the XML configuration into the enclosing XML tag in the masterdata.xml and adapt the XML configuration.
Handle special cases
For some master data, the import on other systems requires or offers some special handling, for example, user, user group, or features.
Result
You understand how the master data definition is related to each other in the censhare Admin Client, the insert-data.xml file, and the masterdata.xml file. You understand the structure of the masterdata.xml file.
You can create your own masterdata.xml file. You can use the censhare Admin Client to export XML entries that you then adapt and add to your masterdata.xml file.