Applying customizations

Compare your customized files from the backups of your existing installations with the corresponding files in the new IBM® Business Process Manager V8.0.1 installations to ensure that all of your settings are correctly applied to the new installations.

Switch to a custom user registry or migrate the users at the file user registry, or both:

Before you run the wsadmin command or migrate the users at the file user registry, check the security configuration at the source version. Open the WAS administrative console and go to Security > Global security > Federated repositories. There are three possible security configurations, as shown in the following table. Perform the appropriate action for each security configuration.

Table 1. Actions for each security configuration
Security configuration at the source version	Action
If the repositories in the realm include only `o=twinternal`, you enabled only the process database to store users.	If you store users in the process database, run the switchToCustomSecurityProvider.py script command to change its default file-based security provider to a custom provider that is compatible with the original Lombardi database provider. Versions earlier than IBM Business Process Manager V7.5.0 use the process database to store users.
If the repositories in the realm include only `o=defaultWIMFileBasedRealm`, you enabled only the file user registry to store users.	If you store users in the file user registry, copy the WAS_HOME/profiles/PROFILE_NAME/config/cells/CELL_NAME/fileRegistry.xml file from the source version to the target version. Note: If a fileRegistry.xml file exists at the target version, back it up before it is overwritten. Before you copy the fileRegistry.xml file, make sure the deployment manager and node agents are stopped. Run the resetPasswordForFileUserReg.py script to reset the internal user's password according to the password that is stored in the list of authorization aliases. By default, the internal user's password and the profile administrator's password are the same. The internal users include tw_admin, tw_user, tw_webservice, and tw_author.
If the repositories in the realm include both `o=defaultWIMFileBasedRealm` and `o=twinternal`, you enabled both the file user registry and the process database to store users.	IBM Business Process Manager V7.5.0 or 7.5.1 users have the option to use the federated repositories. All users added by the administrative console are stored in the file user registry and all users added by the Process Administrative console are stored in the process database. Perform the following actions: Run the switchToCustomSecurityProvider.py script command to change the default file-based user registry to a custom provider. (That is, enable both the file user registry and the process database user registry at the target version). Copy the WAS_HOME/profiles/PROFILE_NAME/config/cells/CELL_NAME/fileRegistry.xml file from the source version to the target version. Note: If a fileRegistry.xml file exists at the target version, back it up before it is overwritten. Before you copy the fileRegistry.xml file, make sure the deployment manager and node agents are stopped. Run the resetPasswordForFileUserReg.py script to reset the internal user's password according to the password that is stored in the list of authorization aliases. By default, the internal user's password and the profile administrator's password are the same. The internal users include tw_admin, tw_user, tw_webservice, and tw_author.

To run the switchToCustomSecurityProvider.py script, start the deployment manager and custom node agents and then go to [target_install_root]/profiles/[deployment_manager_profile_name]/bin. Run the command as shown in the following examples:

Operating system	Command
Windows	`wsadmin.bat -conntype SOAP -user <user_name> -password <password> -f <target_install_root>\BPM\base\profile\actions\scripts\switchToCustomSecurityProvider.py -adminUserName tw_admin -adminPassword tw_admin -nodeName DN2 -serverName BPMPC.AppTarget.DN2.0 -profileName <dmgr_profile>`
Unix	`./wsadmin.sh -conntype SOAP -user <user_name> -password <password> -f <target_install_root>/BPM/base/profile/actions/scripts/switchToCustomSecurityProvider.py -adminUserName tw_admin -adminPassword tw_admin -nodeName DN2 -serverName BPMPC.AppTarget.DN2.0 -profileName <dmgr_profile>`

where dmgr_profile is the name of the Deployment manager profile. You must specify the -adminUserName, -adminPassword, -nodeName, and -serverName parameters in the order shown in the preceding examples. The -adminUserName is the user ID that is used for administrative security, the -nodeName parameter denotes the name of any node, and the -serverName parameter denotes the name of any server or cluster member on that node where either Process Server or Process Center is configured. The -nodeName and -serverName parameters are required for copying the 98Database.xml file from the given node and server to the deployment manager cell.

After running the wsadmin command, the IBM BPM internal security provider is changed to a custom provider.

Note: The switchToCustomSecurityProvider.py command must be invoked exactly once per deployment manager (once per cell) where Process Server or Process Center is configured.

To run the resetPasswordForFileUserReg.py script, make sure the deployment manager and node agents are started, and then go to [target_install_root]/profiles/[deployment_manager_profile_name]/bin and run the command as shown in the following examples:

Operating system	Command
Windows	`wsadmin.bat -conntype SOAP -user <user_name> -password <password> -f <target_install_root>\BPM\base\profile\actions\scripts\resetPasswordForFileUserReg.py -wsadmin_classpath <target_install_root>\BPM\Lombardi\lib\PSAntTasks.jar;<target_install_root>\BPM\Lombardi\lib\svrcoreclnt.jar`
Unix	`./wsadmin.sh -conntype SOAP -user <user_name> -password <password> -f <target_install_root>/BPM/base/profile/actions/scripts/resetPasswordForFileUserReg.py -wsadmin_classpath <target_install_root>/BPM/Lombardi/lib/PSAntTasks.jar:<target_install_root>/BPM/Lombardi/lib/svrcoreclnt.jar`

where <user_name> is the user ID required when the server is running in secure mode and <password> is the password required when the server is running in secure mode.

Note: The resetPasswordForFileUserReg.py command must be invoked exactly once per deployment manager (once per cell) where Process Server or Process Center is configured.

Ensure that you have applied customized settings for the following artifacts:

Application server database connection pool settings and tuning parameters
Email templates
Logging configurations
Customized files such as CSS files, CoachDesigner.xsl, images, HTML files, and JAR files by taking the following steps:
- Include as managed assets the customized files in your current version that have not yet been added to process applications or toolkits.
- If you customized the CoachDesigner.xsl file, upload it as a managed asset so that you can use in place of the default xsl file that is installed as part of the migration.
  Note: Starting in WebSphere Lombardi Edition version 7.2.0, the CoachDesigner.xsl file is a managed asset.
  For more information, see Editing process application settings and Editing toolkit settings.
LDAP configuration
If you used the internal Lombardi security provider in conjunction with an external LDAP security provider (such as Active Directory) in your previous Lombardi installation, configure LDAP as soon as you have completed upgrading your existing databases. For instructions, see Configuring external security providers.
X-Windows Virtual Frame Buffer (Xvfb)
Although it is needed to render reports when running versions before WebSphere Lombardi Edition version 7.2.0 on UNIX platforms, X-Windows Virtual Frame Buffer (Xvfb) is not necessary with IBM BPM V8.0.1. If Xvfb is not needed for other purposes on your UNIX server, you can stop Xvfb. If Xvfb is required for other purposes, running it in the same screen as IBM BPM causes report rendering to fail. In this case, change the value of the $DISPLAY environment variable on your UNIX host before starting IBM BPM servers.