Merging an Application prx File

Prx files are located in the /properties directory of a component and the root /project/properties directory. The Social Program Management Platform is shipped with a set of prx files. These may be overridden by placing new prx files in the SERVER_DIR/components/<custom >/properties directory, where <custom> is any new directory created under components that conforms to the same directory structure as components/core. This mechanism avoids the need to make changes directly to the out-of-the-box application, which would complicate later upgrades.

This override process involves merging all prx files according to a precedence order. The order is based on the SERVER_COMPONENT_ORDER environment variable. This environment variable contains a comma-separated list of component names: the left most has the highest priority, and the right most the lowest.

Figure 1. SERVER_COMPONENT_ORDER example

SERVER_COMPONENT_ORDER=custom,Appeal,ISProduct,sample

The order shows that the precedence of Appeal is higher than that of the sample component. The core component always has the lowest priority and as such does not need to be specified. Any components which are not specified are placed alphabetically above core and below those which are specified.

Note: After changing the component precedence order in SERVER_COMPONENT_ORDER it is necessary to preform a re-insert of the merged properties. This is done by invoking build insertproperties.

When merging prx files, the components listed in the SERVER_COMPONENT_ORDER are taken in order of highest to lowest priority. In the above example the Application.prx file from the sample component is merged with the Application.prx located in the core component. The Application.prx from ISProduct is then merged into the intermediate results and the merge process continues until the Application.prx in the custom component is merged.

Rules of PRX Merges

PRX files are merged based on precedence order. As described above there is always a more important main/source Application.prx file, and a file which is being merged into it. The second file is called the merge file in the following sections.

An Application.prx files can be customized by:

Adding a property providing mandatory property values.
Overriding an existing properties description.
Overriding an existing properties display name.
Override an existing properties value or default value.
Adding a new locale to provide a new display name and description for that locale.
Removing a property by setting the property tag removed to be true.

An Application.prx files cannot be customized by:

Changing an existing property name.
Changing an existing properties type.
Changing an existing properties category.
Changing the static or dynamic setting of a property.

Duplicate property nodes will always be overwritten by the Application.prx file in the component with the highest precedence order. The main Application.prx example file below and the merge Application.prx file below illustrate these rules:

Figure 2. Sample main Application.prx file

<property name="curam.trace" dynamic="true">
    <type>STRING</type>
    <value>trace_ultra_verbose</value>
    <default-value>trace_ultra_verbose</default-value>
    <category>CODETABLE</category>
    <locales>
      <locale language="en" country="US">
        <display-name>Trace Property</display-name>
        <description>Details of the Trace Property</description>
      </locale>
    </locales>
  </property>

Figure 3. Sample merge Application.prx file

<property name="curam.trace" dynamic="true">
    <type>STRING</type>
    <value>trace_off</value>
    <default-value>trace_off</default-value>
    <category>CODETABLE</category>
    <locales>
      <locale language="en" country="GB">
        <display-name>New Trace Display Name</display-name>
        <description>New Description</description>
      </locale>
    </locales>
  </property>
  <property name="property2" dynamic="true">
    <type>STRING</type>
    <value>value</value>
    <default-value>default</default-value>
    <category>CODETABLE</category>
    <locales>
      <locale language="en" country="GB">
        <display-name>Display Name</display-name>
        <description>Description</description>
      </locale>
    </locales>
  </property>

As a result of the merge process the new Application.prx produced would be:

Figure 4. Resulting Application.prx File

<property name="curam.trace" dynamic="true">
    <type>STRING</type>
    <value>trace_off</value>
    <default-value>trace_off</default-value>
    <category>CODETABLE</category>
    <locales>
      <locale language="en" country="US">
        <display-name>Trace Property</display-name>
        <description>Details of the Trace Property</description>
      </locale>
      <locale language="en" country="GB">
        <display-name>New Trace Display Name</display-name>
        <description>New Description</description>
      </locale>
    </locales>
  </property>
  <property name="property2" dynamic="true">
    <type>STRING</type>
    <value>value</value>
    <default-value>default</default-value>
    <category>CODETABLE</category>
    <locales>
      <locale language="en" country="GB">
        <display-name>Display Name</display-name>
        <description>Description</description>
      </locale>
    </locales>
  </property>