Customizing a DMX file

The Data Manager processing allows for the customization of DMX files for the initial, demo and test targets, Supported customizations include the ability to add a row, update a row, remove a row, localize at a row/attribute level and completely override a DMX file. This process allows for DMX files that are shipped with the Cúram application to be easily customized by adding new DMX files to new components in the relevant directory.

The DMX files to be customized must be in the following directory structure:

<SERVER_DIR>/components/<custom>/data/initial
<SERVER_DIR>/components/<custom>/data/demo
<SERVER_DIR>/components/<custom>/data/test

To customize DMX files that are delivered out-of-the-box, new DMX files must be created and added to new components in the relevant directory within SERVER_DIR/components/<custom>/data/initial (or /demo or /test).

This mechanism avoids the need to make changes directly to the out-of- the-box application, which would complicate later upgrades.

The customization process involves the merging of DMX files of the same name within the specified directory structure according to a precedence order. The order is based on the SERVER_COMPONENT_ORDER environment variable which contains a comma separated list of component names, the left-most having the highest priority.

Note: It is possible that more than one DMX file will contain data for a particular database table. As the merging of DMX files is based on file names it may be necessary to customize multiple DMX files in order to achieve a desired data customization for an individual entity.

Only DMX files placed within the structure above will be included in the merging process for DMX files. If sub-directories are used within the initial, demo and test directories, then these will not be included in the merging process.

The merged DMX file is output to the %SERVER_DIR%/build/datamanager/data/initial(or /demo or /test) directory.

Rules of DMX file merging

DMX files are merged based on precedence order. There is always a more important main/source DMX file, and a file which is being merged into it. The second file is called the merge file in the following sections.

The merging rules described below are applied to decide if the rows, attributes or DMX files should be merged into the new DMX file.

A DMX file will only be considered for merging if the new DMX file does not have the override attribute on the <table> element set to true.
A <row> will be inserted into the new DMX file if is determined, by using the primary key information for the record, that the <row> is not already present in the new file.
If a <row> already exists in the new DMX file and the remove attribute is set to true, then no merging will occur. If the remove attribute is set to false or is not present, then the attribute values for that row will be considered for merging.
- If the <value> element does not exist in the new DMX file, then the <value> element will be copied.
- If the <value> contains a different locale, then this <value> entry will be copied into the new file. The locale is specified by the language and country attributes on the <value> element.

All examples below assume custom is before core in the SERVER_COMPONENT_ORDER.

The Example 1 below illustrates how merging works when using the <table> level override attribute. To use the override attribute, copy the contents of the existing DMX file, i.e. the core DMX file and place it in a DMX file of the same name in a <custom> component. Then add the following to the table element:

<table override="true">

This indicates that only DMX files in this <custom> component or in a component higher up in the SERVER_COMPONENT_ORDER will be included in the merged DMX file output produced from the Data Manager processing.

Figure 1. Example 1 - Core DMX File.

<?xml version="1.0" encoding="UTF-8"?>
<table name="CONCERN">
  <column name="CONCERNID" type="id"/>
  <column name="NAME" type="text"/>
  <column name="COMMENTS" type="text"/>
  <row>
    <attribute name="CONCERNID">
      <value>22</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value>Concern 1 record</value>
    </attribute>
  </row>
  <row>
    <attribute name="CONCERNID">
      <value>23</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value>Concern 2 record</value>
    </attribute>
  </row>
</table>

Figure 2. Example 1 - Custom DMX file.

<?xml version="1.0" encoding="UTF-8"?>
<table name="CONCERN" override="true">
  <column name="CONCERNID" type="id"/>
  <column name="NAME" type="text"/>
  <column name="COMMENTS" type="text"/>
  <row>
    <attribute name="CONCERNID">
      <value>55</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value>My custom comment</value>
    </attribute>
  </row>
</table>

Figure 3. Example 1 - Resulting Merge DMX File.

<?xml version="1.0" encoding="UTF-8"?>
<table name="CONCERN" override="true">
  <column name="CONCERNID" type="id"/>
  <column name="NAME" type="text"/>
  <column name="COMMENTS" type="text"/>
  <row>
    <attribute name="CONCERNID">
      <value>55</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value>My custom comment</value>
    </attribute>
  </row>
</table>

In the resulting merge file, no rows are taken from the core DMX file as the custom DMX file is completely overriding the core DMX file through the following: <table override="true">, resulting in all entries in the core file being excluded.

The Example 2 below illustrates how the merging process works when the <row> level remove attribute is set. To remove a row, copy the row from the existing DMX file and place it in a DMX file of the same name in a <custom> component. Then set the remove attribute on that row to true.

Figure 4. Example 2: Core DMX file.

<?xml version="1.0" encoding="UTF-8"?>
<table name="CONCERN">
  <column name="CONCERNID" type="id"/>
  <column name="NAME" type="text"/>
  <column name="COMMENTS" type="text"/>
  <row>
    <attribute name="CONCERNID">
      <value>1</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value>Concern 1 core</value>
    </attribute>
  </row>
  <row>
    <attribute name="CONCERNID">
      <value>2</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value>Concern 2 core</value>
    </attribute>
  </row>
</table>

Figure 5. Example 2 : Custom DMX file.

<?xml version="1.0" encoding="UTF-8"?>
<table name="CONCERN">
  <column name="CONCERNID" type="id"/>
  <column name="NAME" type="text"/>
  <column name="COMMENTS" type="text"/>
  <row>
    <attribute name="CONCERNID">
      <value>1</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value>Concern 1 custom</value>
    </attribute>
  </row>
  <row remove="true">
    <attribute name="CONCERNID">
      <value>2</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value language="en">Concern 2 en custom</value>
    </attribute>
  </row>
  <row>
    <attribute name="CONCERNID">
      <value>5</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value>Concern 5 custom</value>
    </attribute>
  </row>
</table>

Figure 6. Example 2 : Result merge file.

<?xml version="1.0" encoding="UTF-8"?>
<table name="CONCERN">
  <column name="CONCERNID" type="id"/>
  <column name="NAME" type="text"/>
  <column name="COMMENTS" type="text"/>
  <row>
    <attribute name="CONCERNID">
      <value>1</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value>Concern 1 custom</value>
    </attribute>
  </row>
  <row remove="true">
    <attribute name="CONCERNID">
      <value>2</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value language="en">Concern 2 en custom</value>
    </attribute>
  </row>
  <row>
    <attribute name="CONCERNID">
      <value>5</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value>Concern 5 custom</value>
    </attribute>
  </row>
</table>

For Example 2, the <row> where the CONCERNID is set to 2, does not merge the <row> from the core DMX file. When processing the merged DMX file in Example 2, the <row> where the CONCERNID is set to 2 will not be included when creating the SQL insert statements, thus ensuring no entry will exist on the database for this <row>.

Example 3 below illustrates the setting and merging of the language and country attributes on the <value> element.

Figure 7. Example 3: Core DMX file.

In this example, the COMMENTS attribute for the CONCERNID=2 has a value for the fr and the en_GB locales.

<?xml version="1.0" encoding="UTF-8"?>
<table name="CONCERN">
  <column name="CONCERNID" type="id"/>
  <column name="NAME" type="text"/>
  <column name="COMMENTS" type="text"/>
  <row>
    <attribute name="CONCERNID">
      <value>1</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value>Concern 1 core</value>
    </attribute>
  </row>
  <row>
    <attribute name="CONCERNID">
      <value>2</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value language="fr">Concern 2 French core</value>
      <value language="en"
                country="GB">Concern 2 en_GB core</value>
    </attribute>
  </row>
</table>

Figure 8. Example 3 : Custom DMX file.

In this example, the COMMENTS attribute for the CONCERNID=2 has a value for the en locale only. The COMMENTS attribute for the CONCERNID=5 has a value for the en_US locale only.

<?xml version="1.0" encoding="UTF-8"?>
<table name="CONCERN">
  <column name="CONCERNID" type="id"/>
  <column name="NAME" type="text"/>
  <column name="COMMENTS" type="text"/>
  <row>
    <attribute name="CONCERNID">
      <value>1</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value>Concern 1 custom</value>
    </attribute>
  </row>
  <row remove="true">
    <attribute name="CONCERNID">
      <value>2</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value language="en">Concern 2 en custom</value>
    </attribute>
  </row>
  <row>
    <attribute name="CONCERNID">
      <value>5</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value language="en"
                country="US">Concern 5 en_US custom</value>
    </attribute>
  </row>
</table>

Figure 9. Example 3 : Result merge file.

<?xml version="1.0" encoding="UTF-8"?>
<table name="CONCERN">
  <column name="CONCERNID" type="id"/>
  <column name="NAME" type="text"/>
  <column name="COMMENTS" type="text"/>
  <row>
    <attribute name="CONCERNID">
      <value>1</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value>Concern 1 custom</value>
    </attribute>
  </row>
  <row remove="true">
    <attribute name="CONCERNID">
      <value>2</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value language="en">Concern 2 en custom</value>
      <value language="fr">Concern 2 French core</value>
      <value language="en"
                country="GB">Concern 2 en_GB core</value>
    </attribute>
  </row>
  <row>
    <attribute name="CONCERNID">
      <value>5</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value language="en"
                country="US">Concern 5 en_US custom</value>
    </attribute>
  </row>
</table>

In Example 3 above, for the <row> where the CONCERNID is set to 2, the resulting merge file has values for the en, fr and the en_GB locales, i.e. a merge of both core and custom <value> elements.

Example 4 below illustrates the <row> level locales attribute.

Figure 10. Example 4: Core DMX file.

<?xml version="1.0" encoding="UTF-8"?>
<table name="CONCERN">
  <column name="CONCERNID" type="id"/>
  <column name="NAME" type="text"/>
  <column name="COMMENTS" type="text"/>
  <row>
    <attribute name="CONCERNID">
      <value>1</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value>Concern 1 core</value>
    </attribute>
  </row>
  <row locales="en_GB">
    <attribute name="CONCERNID">
      <value>2</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value language="fr">Concern 2 French core</value>
      <value language="en"
                country="GB">Concern 2 en_GB core</value>
    </attribute>
  </row>
</table>

Figure 11. Example 4 : Custom DMX file.

<?xml version="1.0" encoding="UTF-8"?>
<table name="CONCERN">
  <column name="CONCERNID" type="id"/>
  <column name="NAME" type="text"/>
  <column name="COMMENTS" type="text"/>
  <row>
    <attribute name="CONCERNID">
      <value>1</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value>Concern 1 custom</value>
    </attribute>
  </row>
  <row locales="en,en_US">
    <attribute name="CONCERNID">
      <value>2</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value language="en">Concern 2 en custom</value>
    </attribute>
  </row>
</table>

Figure 12. Example 4 : Result merge file.

<?xml version="1.0" encoding="UTF-8"?>
<table name="CONCERN">
  <column name="CONCERNID" type="id"/>
  <column name="NAME" type="text"/>
  <column name="COMMENTS" type="text"/>
  <row>
    <attribute name="CONCERNID">
      <value>1</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value>Concern 1 custom</value>
    </attribute>
  </row>
  <row locales="en,en_US">
    <attribute name="CONCERNID">
      <value>2</value>
    </attribute>
    <attribute name="NAME">
      <value/>
    </attribute>
    <attribute name="COMMENTS">
      <value language="en">Concern 2 en custom</value>
      <value language="fr">Concern 2 French core</value>
      <value language="en"
                country="GB">Concern 2 en_GB core</value>
    </attribute>
  </row>
</table>

In Example 4 above, the value for the locales attribute is taken from the row in the component that is higher up in the SERVER_COMPONENT_ORDER, i.e. the custom component.

The primary key/composite key for a record is used to determine the overriding/merging process for DMX files. DMX files will be merged based on the definition of the primary key for the table/entity the DMX file represents. For all modelled entities, the primary key information is stored in the generated <SERVER_MODEL_NAME>_PrimaryKeys.xml file in the build directory, i.e. %SERVER_DIR%/build/svr/gen/ddl. For all non-modelled components, the primary key information for entities must be stored in a file called <SomeName>_PrimaryKeys.xml within %SERVER_DIR%/components/<custom>/data/ddl directory. If this file is named correctly in the specified location, the DMX processing will contain the relevant primary key information for the non-modelled component.