Masterdata.xml files allow you to add your own custom definitions for master data to projects. These files can be distributed from a QA system to a productive system. For some master data, the import on other systems requires or offers some special handling, for example, user, user group, or features. This article explains how to set up master data entries for these special cases.

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 special cases for creating individual master data for projects. It does not provide a general overview of how to create masterdata.xml files for projects.

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 the meaning, usage, and dependencies of the definitions in the Master data tables.

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 on those systems. When you create your own XML entries for the masterdata.xml, you can rely on XML entries in the insert-data.xml. Another possibility is to define entries in the censhare Admin Client that are then exported as XML entries.  

But there are some master data definitions that require special treatment or offer special possibilities when using XML entries. This includes the following master data:  

  • Users

  • User groups

  • Workflows

  • Features

The handling and possibilities are described in the following special cases:  

  • Users and User groups. This also includes the definition of user assets and the assignment of users and user groups to workflow step as default target.

  • Definition of Feature assets

  • Advanced XML configuration for features

Special case: User and User groups

Use case

With masterdata.xml, all custom definitions can be maintained in one place. This includes user and user groups. This allows you to maintain user and user group definitions also as custom data and easily synchronize them between different systems.    

  • With censhare version 2017.4 and earlier, it is not possible to synchronize user and user groups via masterdata.xml.

  • With censhare version 2017.5 to 2019.1, a maximum of 98 user and user definitions can be synchronized with other systems.

  • As of censhare version 2019.2, user data can be synchronized via XML without restrictions.

You can also define user data in an XML configuration for a Person asset. In the masterdata.xml, add a reference to the Person asset in the user XML entry. This is introduced with version 2019.2.  

With version 2019.2 also the way how users are referenced as standard targets in workflow steps of a workflow definition changed.  

Problem

Users are identified by their ID on a censhare system. The IDs are created sequentially when a new user entry is created. Due to that, it is not possible to guarantee that a user has the same ID on different systems. The ID cannot be used to identify the same user on different systems.  

The same problem occurs with the standard target for a workflow step. A workflow step stores the user ID respective user group ID as the standard target.  

Solution

  • censhare uses the login name of a user to determine if a user already exists on another system since 2019.2. For more information, see the following sections.

  • For the system from 2017.5, 2018.1, 2018.2, 2018.3, and 2019.1 there is a fix.

Define User entries

Since version 2019.2, censhare uses the login name to identify a user entry on another system. Like resource keys, login names are the same on different systems. If a user with the login name in the XML entry, does not exist on another system, censhare creates a new entry with a different ID but the same login name. When the next synchronization is done, censhare finds the existing entry using the login name. No new entry is created.  

Create user entries using the censhare Admin Client:  

  1. Create the user entry in the censhare Admin Client.

  2. Export the user entry.

  3. Copy the user XML entry to your masterdata.xml file.

  4. Remove the id attribute.

For example, a user definition after the export from the censhare Admin Client:    

<party id="123" isgroup="0" display_name="Insert-Data" name="Data" 
   login="XML" main_role="admin" main_domain="root." main_domain2="root." 
   isactive="1" isvisible="1" issystem="0"  firstname="Insert" 
   count_invalid_logins="0"  auth_standard="1" auth_extern="0" sync_extern="0"
   tcn="0" rowid="107">       
      <party_role role="admin" domain="root." domain2="root." enabled="1" 
         tcn="0" rowid="116"/>  
</party>
CODE

The same user definition without the id attribute:    

<party isgroup="0" display_name="Insert-Data" name="Data" login="XML" 
   main_role="admin" main_domain="root." main_domain2="root." isactive="1" 
   isvisible="1" issystem="0"  firstname="Insert" count_invalid_logins="0" 
   auth_standard="1" auth_extern="0" sync_extern="0" tcn="0" rowid="107"> 
      <party_role role="admin" domain="root." domain2="root." enabled="1" 
         tcn="0" rowid="116"/>  
</party>
CODE

Define User assets

When censhare imports a user XML definition for the first time, it also creates a Person asset that can contain all personal data like the address. The ID of the person asset is stored in the user entry on the new system. If a user shall have the same person asset on different systems, you can create an asset XML from this Person asset. A reference to it is stored in the user XML entry in the masterdata.xml file.  

When user XML entry is imported, censhare also creates the Person asset and stores its ID in the user entry in the User table in the Master data.  

The reference is done by the party_asset_ref_file attribute in the XML entry. It contains the name of the asset XML file with a person asset definition. The asset XML file must be in the same folder as the masterdata.xml file.  

For example, there is a very basic asset XML definition for a Person asset:  

<!-- file name: Insert-data-user.asset.xml -->  
<?xml version="1.0" encoding="UTF-8"?>  
<asset name="Data, Insert" type="person." application="metadata"
    domain="root.tracker." domain2="root." language="fr">    
  <asset_feature feature="censhare:address">      
    <asset_feature feature="censhare:address.personal-data">        
      <asset_feature feature="censhare:address.first-name" 
          value_string="Insert"/>
      <asset_feature feature="censhare:address.last-name" 
          value_string="Data"/>   
    </asset_feature>
  </asset_feature>  
</asset>
CODE

Note: You can create the asset XML from a Person asset in the censhare Client using the Export module asset server action.

This asset XML definition must be stored in a text file. The name of the text is then used to reference the definition in the respective user XML entry in the masterdata.xml:  

party_asset_ref_file="Insert-data-user.asset.xml"     

Here is the user XML entry with the reference to the Person asset XML file:   

<party isgroup="0" display_name="Insert-Data" name="Data" login="XML" 
   main_role="admin" main_domain="root." main_domain2="root." isactive="1" 
   isvisible="1" issystem="0"  firstname="Insert" count_invalid_logins="0" 
   auth_standard="1" auth_extern="0" sync_extern="0" tcn="0" rowid="107"  
   party_asset_ref_file="Insert-data-user.asset.xml"/>
CODE

Add users to a user group

A user group has nearly the same definition as a user. The main difference is that the isgroup attribute is set to "1" for a user group entry. Both definitions are stored in the party table in the database. Due to that, a user group is also identified by its ID in the censhare system. Like with user XML entries, this does not work when importing the masterdata.xml file. Due to that, the user group is also identified by its login name when importing it.

First, you have to define the user group XML in the master data. You can define it in the censhare Admin Client and then export it. In this case, you must add the login attribute in the XML with a suitable value for the login name. Here is an example:      

<party isgroup="1" login="Insert-data-group" display_name="Insert-data-group" 
   name="Insert-data-group" main_domain="root." main_domain2="root." 
   main_role="admin" isactive="1" isvisible="1" issystem="0" 
   count_invalid_logins="0" auth_standard="1" auth_extern="0" sync_extern="0" 
   tcn="1" rowid="116">
CODE


The login name of the user group cannot be used to log in to a censhare system.


After the user group definition, you add the XML definition for the users. You can define and export it in the censhare Admin Client. Here is an example:    

<party isgroup="0" display_name="Insert-Data" name="Data" login="XML" 
      main_role="admin" main_domain="root." main_domain2="root." isactive="1" 
      isvisible="1" issystem="0"  firstname="Insert" count_invalid_logins="0" 
      auth_standard="1" auth_extern="0" sync_extern="0" tcn="0" rowid="107"  
      party_asset_ref_file="Insert-data-user.asset.xml">       
   <party_role role="admin" domain="root." domain2="root." enabled="1" 
      tcn="0" rowid="116"/>   
</party>
CODE

Now, you add the XML element for the relation to the user groups. It looks like this:  

<parent_partyrel parent_login="Insert-data-group"/>

The parent_login attribute contains the login name of the user group where you want to add the user.  

This is then added to the user XML entry:  

<party isgroup="0" display_name="Insert-Data" name="Data" login="XML" 
    main_role="admin" main_domain="root." main_domain2="root." isactive="1" 
    isvisible="1" issystem="0"  firstname="Insert" count_invalid_logins="0" 
    auth_standard="1" auth_extern="0" sync_extern="0" tcn="0" rowid="107"  
    party_asset_ref_file="Insert-data-user.asset.xml">       
  <party_role role="admin" domain="root." domain2="root." enabled="1" 
    tcn="0" rowid="116"/> 
  <parent_partyrel parent_login="Insert-data-group"/>   
</party>
CODE


Note: You must add the user group XML definition before the user XML definition. Otherwise, the user group is not known when the user is imported, and the import fails.


Here is the whole definition of the example:  

<partys>  
  <!--- User group definition --->      
  <party isgroup="1" login="Insert-data-group" display_name="Insert data grp"
      name="Insert-data-group" main_domain="root." main_domain2="root."
      main_role="admin" isactive="1" isvisible="1" issystem="0" 
      count_invalid_logins="0" auth_standard="1" auth_extern="0" 
      sync_extern="0" tcn="1" rowid="116">    
  </party>  
  <!--- User definition --->      
  <party isgroup="0" display_name="Insert-Data" name="Data" login="XML" 
      main_role="admin" main_domain="root." main_domain2="root." isactive="1" 
      isvisible="1" issystem="0"  firstname="Insert" count_invalid_logins="0" 
      auth_standard="1" auth_extern="0" sync_extern="0" tcn="0" rowid="107"  
      party_asset_ref_file="Insert-data-user.asset.xml">        
    <party_role role="admin" domain="root." domain2="root." enabled="1" 
        tcn="0" rowid="116"/>        
    <!--- Assign user to user group --->        
    <parent_partyrel parent_login="Insert-data-group"/>      
  </party>   
</partys>
CODE

Define Workflows

Workflow steps can define a default target. This can be a user or typically a user group. To add a user/user group to an XML workflow step definition add the def_party_login attribute and enter the login name of the user/user group. For example:  

def_party_login="Insert-data-group"

Here is an example of a workflow step that has a group as the default target assigned:

<workflow_step wf_id="300" wf_step="5" name="Step 2: Edit User XML" 
  name_de="Step 2: Edit User XML" wf_state_id="10" 
  def_party_login="Insert-data-group" completion_percentage="10.0" 
  sorting="5" enabled="1" tcn="1" rowid="84"/>
CODE

Each workflow step has a workflow state. You have to add this definition, too. It has to be before the XML workflow definition. Here is a workflow state example:      

<workflow_state id="10" name="Work in progress (custom)" 
  name_de="In Bearbeitung (bearbeitet)" color="16731727" enabled="1" 
  tcn="1" rowid="1"/>
CODE

Here is the complete example:  

<workflow_states>      
  <workflow_state id="1" name="Created (custom)" 
    name_de="Angelegt (bearbeitet)"color="16711680" enabled="1" 
    tcn="1" rowid="11"/>      
  <workflow_state id="5" name="Finished (custom)" 
    name_de="Fertig (bearbeitet)" color="46080" enabled="1" 
     tcn="1" rowid="10"/>      
  <workflow_state id="10" name="Work in progress (custom)" 
    name_de="In Bearbeitung (bearbeitet)" color="16731727" enabled="1" 
    tcn="1" rowid="1"/>  
</workflow_states>  
<workflows>      
  <workflow id="300" name="Insert-Data Workflow" 
       name_de="Insert-Data Workflow" domain="root." domain2="root." 
       enabled="1" tcn="1" rowid="45">        
    <workflow_step wf_id="300" wf_step="5" name="Step 2: Edit User XML" 
         name_de="Step 2: Edit User XML" wf_state_id="10" 
         def_party_login="Insert-data-group" completion_percentage="10.0" 
         sorting="5" enabled="1" tcn="1" rowid="84"/>  
<workflow_step wf_id="300" wf_step="10" 
         name="Step 3: Import into source system" 
         name_de="Step3: Import into source system" wf_state_id="10" 
         def_party_login="XML" completion_percentage="50.0" sorting="15" 
         enabled="1" tcn="1" rowid="85"/>        
    <workflow_step wf_id="300" wf_step="15" 
          name="Step 4 Import into target system" 
          name_de="Step 4 Import into target system" wf_state_id="5" 
          def_party_login="Insert-data-group" completion_percentage="100.0" 
          sorting="30" enabled="1" tcn="0" rowid="86"/>        
    <workflow_step wf_id="300" wf_step="1" name="Step 1: Export User XML" 
          name_de="Step 1: Export User XML" wf_state_id="1" 
          def_party_login="XML" completion_percentage="0.0" sorting="1" 
          enabled="1" tcn="0" rowid="87"/>      
  </workflow>    
</workflows>
CODE


The deployment of workflow definitions with workflow steps and workflow states in a masterdata.xml file can overwrite already existing workflow definitions when deployed to another system!

Explanation: Workflows, workflow steps, and workflow states are identified by their IDs. These IDs are numbers that are manually created. The IDs must be unique: Workflow IDs must be unique within all workflow IDs. Workflow state IDs must be unique within all workflow state IDs. Workflow step IDs must be unique within their workflow definition.

The censhare dedicated solutions also provide a set of workflows with workflow steps and workflow states. They use the reserved range from 900.000 to 1.000.000 for workflow IDs and workflow states. Do not use this range for custom workflow IDs or workflow state IDs! They can be overwritten if the censhare dedicated workflows/workflow states are installed or updated!

If a workflow ID in a masterdata.xml file is also used by a workflow in the censhare dedicated solutions, this definition is changed by the masterdata.xml file. If workflow step ID within this workflow definition also is the same, this definition is changed, too. If a workflow state ID in a masterdata.xml file is also used by a standard workflow state definition, this definition is changed by the masterdata.xml file.

Special case: Define feature assets

Use case

Features are defined as entries in the Features table in the database. From these feature definitions, censhare automatically create a Feature asset. If there are changes in a feature definition, censhare automatically updates the respective Feature asset.  

The Feature asset contains the information provided by the respective feature definition. If necessary, you can provide your own definition of the Feature asset in a Feature asset XML file.  

For example, you can set relations to other assets that are also defined as asset XML files in the same folder. Using this, you can define a dynamic value list for a feature. An example of this is in the following folder of the censhare Server

../install/system/required/features/beacon.estimote-color

Solution

The relation between the feature definition and the asset XML file is set via the Asset resource key field of the feature definition. For example:  

asset_resource_key="insert-data:feature.first-name.key"

This resource key must be also defined as feature entry in the asset XML of the Feature:  

<asset_feature feature="censhare:resource-key" 
  value_string="insert-data:feature.first-name.key"/>
CODE

When censhare creates/update the feature definition, it searches if there is an asset XML file that contains this resource key. This functionality is available since version 2019.2.  

Steps

  1. Create a feature definition in the censhare Admin Client. This should contain the desired resource key in the Asset resource key field.

  2. Export the entry and add it to the respective masterdata.xml file.

  3. Synchronize the masterdata.xml file.

  4. Search for the Feature asset using the defined resource key.

  5. Export the asset XML using Export module asset server action.

  6. Adapt the asset XML to your needs and place the asset XML file in the same folder as the masterdata.xml.

Here is an example for a feature XML definition:    

<features>          
  <feature key="insert-data:first-name" type="censhare:intern" storage="0" 
    domain="root." domain2="root." name="First name" name_de="Vorname" 
    description="First name (address)" description_de="Vorname (Adresse)" 
    value_type="4" ui_control="3" ismultivalue="0" isassetinfo="0" 
    assetinfo_sorting="0" issearchable="1" sorting="10" language_type="0" 
    color_type="0" bdb_key="2894" enabled="1" has_relevance="0" 
    target_object_type="asset" trait="address" trait_property="idFirstName" 
    trait_property_top_level="0" user_modifiable="1" is_xml_attr="0" 
    asset_resource_key="insert-data:feature.first-name.key" tcn="4" 
    rowid="2894">          
  </feature>    
</features>
CODE

Here is an example with a basic asset XML definition for feature XML entry above that has the defined resource key: Respective asset XML for feature definition:  

<?xml version="1.0" encoding="UTF-8"?>  
<asset name="First name" type="module.feature." 
    application="default" deletion="2" 
    domain="root.tracker." domain2="root." language="de">    
  <asset_feature feature="censhare:module.masterdata-definition" 
      value_string="feature/insert-data:first-name"/>    
  <asset_feature feature="censhare:resource-enabled" value_long="1"/>    
  <asset_feature feature="censhare:resource-in-cached-tables" value_long="0"/>
  <asset_feature feature="censhare:resource-key" 
      value_string="insert-data:feature.first-name.key"/>  
</asset>
CODE

Special case: advanced XML configuration for features

In the masterdata.xml a feature definition can have an XML configuration since 2019.2. This XML section contains XML definitions for the index of the related feature.  

The feature definition with

<feature ... />

can have an XML configuration:

<feature ...>      
  <xml_config>         
    ...      
  </xml_config>  
</feature>
CODE

Here is an example for an XML configuration:

<feature ...>       
  <xml_config>            
    <index-configs>                
      <index-config is-custom="true" type="direct-value" isnull-column="true" 
           notnull-column="true" collator-columns="true">                   
        <fulltext stemming="false" use-frequency="true" 
           strip-diacritics="false" 
           expand-junction-operator="AND_NOT_EMPTY"/>     
        <hint>   
          <property name="altresults-enabled" value="false"/>     
        </hint>     
       </index-config>            
    </index-configs>        
  </xml_config>  
</feature>
CODE

Result

You know how to create XML entries for the masterdata.xml for the special cases related to users, user groups, and feature definitions. You understand the concept of how users and user groups are identified in different systems.