Configuration file overview and explanation for Lombardi Teamworks, WebSphere Lombardi Edition (WLE), and the IBM Business Process Manager (BPM) products

Note: This document does not apply to the IBM Business Process Manager Version 8.0.1 products.

Background
The configuration files in the ../config/ directories are loaded in numerical order. For example, the standard files are loaded in this order: 00Static.xml, 50AppServer.xml, 60Database.xml, 80EventManager.xml, 98Database.xml, 99Local.xml, 100Custom.xml. By default, the first time the element that is loaded it will stick in the configuration. For example, if both 99Local.xml and 100Custom.xml file contain the <environment-name> tag, then the one in 99Local.xml file loads first, unless the merge attribute is set to replace. There is more information on this scenario later in this document.

You can see the full configuration space by looking in the TeamworksConfiguration.running.xml file. The TeamworksConfiguration.running.xml file shows the actual values from all of the Teamworks XML configuration files in the .../config/ directory with which the server is actually running.

Where can I find the TeamworksConfiguration.running.xml file in the different versions of the Product?

• Lombardi Teamworks Version 6.x: The file is located in the Teamworks-install\process-server\resources\config directory.
  
  
  To view the TeamWorksConfigurationRunning.xml file for Lombardi Teamworks 6.1 and beyond on WebSphere Lombardi Edition, see JSP Page to display TeamWorksConfigurationRunning.
  
  
• WebSphere Lombardi Edition Version 7.x: The file is located in the WLE_INSTALL\process-center(server) directory.
  
  
• IBM Business Process Manager Version 7.5.x and 8.0 products: The file is located in the BPM_INSTALL\...\profiles\profile_name\config\\cells\cell_name\nodes\node_name\servers\server_name\process-center(server) directory.
  
  
  The profile_name, cell_name, node_name, and server_name variables refer to the profile, cell, and server names in your environment.

Using the 100Custom.xml file to add new configuration values or replace existing values
The 100Custom.xml file is designed to hold the customization and changes that you want to make to any of the configuration files. The idea is that if you do a fresh installation of a new version, you can simply drop in your existing 100Custom.xml file and all the changes that you have made will be picked up and used instead of the default values. Ask yourself, if I have to reinstall the product, what would I need to change in the configuration files? Those changes are the things that you want to put in the 100Custom.xml file.

For example, consider adding any additional columns or views for your task manager to the 100Custom.xml file. Any tuning options, such as for the event manager in the 80EventManager.xml file, are appropriate to put in the 100Custom.xml file. Any changes to default values, such as your system lane user, should be made in the 100Custom.xml file.

Alternatively, if you are changing your database URLs (database name, database machine name, and so on) then consider making those changes directly to the 98Database.xml file. This approach is because these values are written down correctly when you install a new version of the product.

One note on the 100Custom.xml file changes: When you move to a new version of the product, you always want to review the changes in the 100Custom.xml file to make sure that they are still appropriate in the new version. For example, some of the default settings or database queries that you use in customizing the Process Portal might change between releases. Other settings might no longer apply.

The merge attribute
When you load or replace values using the 100Custom.xml file, you need to be careful which merge setting you use for each element. The "merge" attribute supports the following:

• "append" - This value appends the new tag regardless
  
  
• "mergeChildren" - This value merges the new one with the first of the existing ones. (DEFAULT BEHAVIOR). In other words "mergeChildren" merges a child with parent element but please note thatmergeChildren doesn't really merge a child if it doesn't have any attributes and that child only has text.
  
  
• "replace" - This value replaces all old tags with this new tag.
  
  

You can see usage examples for "append" and "replace" in the 50AppServer.xml and 60DataBase.xml files, which overrides things in 00static.xml file depending on the database or application server.

For example, from the sample 100Custom.xml file, you might want to change the <environment-name> value. In the 99Local.xml file you have something like the following code:
<properties>
...
   <common merge="mergeChildren">
   ...
       <environment-name>Environment_from_99Local</environment-name>
   ...
   </common>
...
</properties>

To change the environment name in the 100Custom.xml file, you might use the following code:

<properties>
   <common merge="mergeChildren">
       <environment-name merge="replace">Environment_from_100Custom
       </environment-name>
   </common>
</properties>

Where can I find stock configuration files and the 100Custom.xml file in different versions of the product?

• 100Custom.xml file:
  • Lombardi Teamworks Version 6.x: The file is located in the Teamworks-install\process-server\resources\config directory.
    
    
  • WebSphere Lombardi Edition Version 7.x: The file is located in the WLE_INSTALL\process-center(server)\config directory.
    
    
  • IBM Business Process Manager Version 7.5.x and 8.0 products: The file is located in the BPM_INSTALL\...\profiles\profile_name\config\\cells\cell_name\nodes\node_name\servers\server1\process-center(server)\config directory.
    
    
    The profile_name, cell_name, node_name, and server_name variables refer to the profile, cell, and server names in your environment.
• Stock configuration files like 99Local.xml, 98Database.xml, and so on:
  • Lombardi Teamworks Version 6.x: The files are located in the Teamworks-install\process-server\resources\config\system directory.
    
    
  • WebSphere Lombardi Edition Version 7.x: The files are located in the WLE_INSTALL\process-center(server)\config\system directory.
  • IBM Business Process Manager Version 7.5.x and 8.0 products: The files are located in the BPM_INSTALL\...\profiles\profile_name\config\\cells\cell_name\nodes\node_name\servers\server_name\process-center(server)\config\system directory.
    
    
    The profile_name, cell_name, node_name, and server_name variables refer to the profile, cell, and server names in your environment.

What do you need to know before backing up existing configuration files?

It is always a good idea to make a backup copy of the files that you are changing. However, these config files are one area where you need to use some caution when backing them up. Specifically, always change the extension from .xml when backing up these files. The following information explains why you want to change the file extension:

ALL of the files in the .../config directory ending in .xml are loaded by the product on startup. These files are loaded in some sort of alphabetical order - letters are first then numbers in numerical order. For example, if you have the following files in the ../config directory they are loaded in the order shown below:

.../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

This scenario means that any settings in the "Copy of 99Local.xml" takes effect and any settings in the 99Local.xml file are ignored except for elements including the merge="replace" as noted previously.

Note: Make sure that you use a different extension, like .bak, when backing up these files.