The 99Local.xml and 100Custom.xml configuration files

Many default IBM Process Server configuration settings are saved in the 99Local.xml file; the 100Custom.xml file is used to modify one or more of those default settings. Both files are stored in the profile root for the server.

IBM default configuration settings are distributed across multiple configuration XML files, 99Local.xml being one of them. There are other XML files, such as 98Database.xml or 50AppServer.xml. You can overwrite the settings from any of the default configuration files, which start with a number less than 100. To do that, create custom XML configuration files with a number equal to or greater than 100, for example, 100Custom.xml. It is perfectly valid to have a file 100Custom.xml for typical custom configuration and another file, such as 110SomeOtherConfig.xml. Settings in 110SomeOtherConfig.xml can overwrite those in 100Custom.xml if the file has a replace tag.
Note: The updateBPMconfig administrative task is available to update the XML configuration files including the 100Custom.xml file to provide a single file that has all of the changes applied to the environment. The administrative task creates the 100Custom.xml file if it does not exist. If you have multiple versions of the custom file, such as 101Custom.xml, 102Custom.xml, and so on, only the 100Custom.xml file is updated.

Although the documentation discusses 99Local.xml and 100Custom.xml, remember that there are other configuration files as you plan and make configuration changes.

When you modify a server configuration, always make the changes to the 100Custom.xml file, not to the original configuration file. In this way, all customizations are captured in a single file and are readily available if you upgrade to a new version of IBM® Business Process Manager.

IBM Business Process Manager merges the changes you make in the 100Custom.xml file with the original configuration based on the value of the merge attribute. Use one of the following values, depending on how you want to merge updated elements between the 100Custom.xml and the original configuration. Attribute values must be in quotation marks (for example, "mergeChildren").
Table 1. Merge attributes for the 100Custom.xml file
Value for merge attribute Description
append Appends the new tag
mergeChildren Merges the new tag with the first of the existing tags (default behavior)
replace Replaces all old tags with the new one
IBM Business Process Manager matches the elements you update in the 100Custom.xml file with the original configuration based on the value of the match attribute. Use one of the following values, depending on how you want to match updated elements between the 100Custom.xml and the original configuration. Attribute values must be in quotation marks (for example, "elementName").
Table 2. Match attributes for the 100Custom.xml file
Value for merge attribute Description
id Matches the element with the id attribute
name Matches the element with the name attribute
elementName Matches the element with the element name

Locating configuration files

Path names to configuration files and other resources in the following topics are specific to the server you are configuring. For example, the 100Custom.xml and 99Local.xml files are stored in the profile root for the server, where the value of server_type is either process-center or process-server, depending on which server you are configuring.

In addition, the location of the configuration files depends on whether your environment is stand-alone, clustered network deployment, or single server network deployment.

Important: If the 100Custom.xml file does not yet exist (if, for example, you haven’t customized any of your configuration settings), you must create it. Open the appropriate 99Local.xml file for your environment and save it as 100Custom.xml in the directory indicated in Table 3.
Table 3. Location of 99Local.xml and 100Custom.xml configuration files
Environment type Location of 99Local.xml file Location of 100Custom.xml file
Stand-alone server
PROFILE_ROOT\config\cells\cell_name
\nodes\stand-alone_node_name\servers
\server_name\server_type
\config\system\99Local.xml 
PROFILE_ROOT\config\cells\cell_name
\nodes\stand-alone_node_name\servers
\server_name\server_type
\config\100Custom.xml
Network deployment cluster
In the network deployment Process Server cluster:
PROFILE_ROOT\config\cells\cell_name
\clusters\cluster_name\server_type
\config\system\99Local.xml
Each Process Server cluster member at:
PROFILE_ROOT\config\cells\cell_name
\nodes\custom_node_name\servers
\cluster-member-name\server_type
\config\system\99Local.xml
In the network deployment Process Server cluster:
PROFILE_ROOT\config\cells\cell_name
\clusters\cluster_name\server_type
\config\100Custom.xml
Note: For ND environments, XML configuration files on the cluster level are templates for XML configuration files that are created when new cluster members are added.
Each Process Server cluster member at:
PROFILE_ROOT\config\cells\cell_name
\nodes\custom_node_name\servers
\cluster-member-name\server_type
\config\100Custom.xml
Important: At run time, only the settings from these cluster member files are read.
Network deployment single server
PROFILE_ROOT\config\cells\cell_name
\nodes\custom_node_name\servers
\server_name\server_type
\config\system\99Local.xml
PROFILE_ROOT\config\cells\cell_name
\nodes\custom_node_name\servers
\server_name\server_type
\config\100Custom.xml

Making changes to configuration files for a network deployment cluster

For network deployment environments, XML configuration files on the cluster level are templates for XML configuration files that are created when new cluster members are added. If you make changes to the file at the cluster member level (PROFILE_ROOT\config\cells\cell_name\nodes\custom_node_name\servers\cluster-member-name\server_type\config\100Custom.xml), make the changes at the cluster level as well (PROFILE_ROOT\config\cells\cell_name\clusters\cluster_name\server_type\config\100Custom.xml). Making the changes to the templates at the cluster level ensures that the changes are also created on any new cluster member, if one is added in the future.

At run time, only the settings from cluster member files are read. If you make changes after deployment, you need to make them in the cluster member version of the file for each server in order to have the changes take effect at run time.

Always make changes to any of these XML configuration files on the deployment manager (Dmgr) server.
  1. Make changes to cluster members, that is to the XML file for each node (see the path earlier in this section, but work in the deployment manager file system).
  2. Make changes to the cluster level to ensure that each new cluster will be created with your customizations.
  3. After making the changes, select Full Resynchronize to replicate the settings from the deployment manager server to the individual nodes. If you edit these configuration files on an individual node, the changes may be lost in the next update.

Backing up configuration files

CAUTION:
It is always a good idea to make a backup copy of the files that you are changing. However, when backing up these files, you must always either save the copies in a directory that is not in or under the .../config directory, or change the file extension of the copies from .xml to something else.

All of the files in the .../config directory that end in .xml are loaded when you start or restart the product. The XML files are loaded in a sequence where those starting with a letter of the alphabet are loaded before ones that start with numbers, which are loaded in numeric order. So any copies of XML configuration files that keep the .xml extension can cause unexpected behavior.

For example, if you have the following files in the ../config directory, they are loaded in the order shown.
.../config/system/Copy of 99Local.xml
.../config/system/00Static.xml
.../config/system/50AppServer.xml
.../config/system/60Database.xml
.../config/system/80EventManager.xml
.../config/system/98Database.xml
.../config/system/99Local.xml
.../config/100Custom.xml
In this example, the possibly old settings in the Copy of 99Local.xml file take effect first and all settings in the 99Local.xml file are ignored – except for elements that include the attribute merge="replace".
Tip: Always use a standard extension for the copies (for example, .bak).