BPMConfig command-line utility

Syntax

Description

You can use the BPMConfig command to create an IBM BPM deployment environment, instead of using the Deployment Environment wizard in the WebSphere administrative console. You can also use the BPMConfig command to create profiles for IBM BPM deployment manager and managed nodes, instead of using the Profile Management Tool or the manageprofiles utility.

To supplement the BPMConfig command, an IBM BPM Configuration editor is provided that enables you to graphically edit a configuration properties file that is exported from your source environment using the BPMConfig -export command. After you modify the exported properties file in the editor, you can use the BPMConfig -create command to create a new deployment environment that is based on the modified file. Information about the IBM BPM Configuration editor is found in the topic Configuring your environment with the IBM BPM Configuration editor.

The BPMConfig command uses a properties file that contains all of the values that are used in the configuration of your deployment environment. Sample properties files are provided for you to copy and customize to configure your own environments.

WARNING: Could not open/create prefs root node Software\JavaSoft\Prefs at root 0x80000002
Windows RegCreateKeyEx(...) returned error code 5.

Parameters

-create [-de|-profile|-sqlfiles|-clusterMembers] properties_file

Creates the profiles, deployment environment configuration, the database tables, or the SQL scripts for creating the required database tables. The -create parameter can also be used to add multiple cluster members to an existing deployment environment.

If you run BPMConfig -create -de properties_file, you must run the command on the computer that has the deployment manager profile and then run it on each computer that has a managed node. Both the deployment environment and the profiles are created in a cell for those profiles that match the values for the installPath and hostName specified in the properties file and that do not yet exist. When you run the command, the scripts to create the database tables are automatically created. Depending on the value that you set for the bpm.de.deferSchemaCreation parameter in the properties file, the database tables may be created and the Process Server database loaded with system information. If you are migrating and Business Process Choreographer was configured in your source environment, the configuration files were automatically exported when BPMConfig -migrate was run and they are used to automatically recreate the Business Process Choreographer configuration in the new environment. When you have finished creating the new environment, you may need to perform some Business Process Choreographer post-migration tasks, which are described in the topic "Moving your custom configuration to the target environment."

If you run the BPMConfig command with the -profile option, the only profiles that are created are the profiles that are specified in the properties file that do not already exist. If -create -de was already run and one or more profiles already exist, the BPMConfig command reports the existing profile names in a message and continues to configure the deployment environment. When you create a new profile, by default, the new node is federated when it is created. If you want to create the profile without federating the node, specify the -federateLater option with the -create -profile action. Although the -create -profile action creates one ore more BPM profiles, it does not configure the deployment environment. This is useful if you want the use the deployment environment wizard in the administrative console to configure the deployment environment. You can create the IBM BPM deployment manager profile and managed node profile first using the-create -profile action and then start the administrative console to configure your deployment environment.

To generate the SQL scripts for creating database tables without creating a profile or a deployment environment, you can run the command with the -create -sqlfiles action. You can optionally specify an output directory for the generated scripts using the option -outputDir output_directory. If you do not specify an output directory, the scripts are generated in the dbscripts directory at the root of the profile under which you ran the command. Running the command with the -create -sqlfiles does not perform any configuration. To create or configure your deployment environment, you must run the command separately with the -create -de or -create -profile actions.

To add one or more cluster members to an existing deployment environment, run the command BPMConfig -create -clusterMembers properties_file. You must run the command on the deployment manager node. If you have remote custom nodes, you must run the syncNode command on the remote nodes to obtain the latest configuration file changes.

Before you run the command, you must add the properties of the cluster members to the properties file. The names of the added members must be different from the names of existing members on the same node. You must also increment the index of the cluster members.

You can add the cluster member properties to the properties file by using one of the following approaches:

• If a configuration file was used to generate the deployment environment, you can edit the file and add the cluster member properties, then run the command to add the cluster members to the existing deployment environment.
• If the Deployment Environment wizard was used to generate the deployment environment, you can export the configuration file using the BPMConfig -export command and add the cluster member properties to the file, then run the command to add the cluster members to the existing deployment environment.

Before you run the command to add the cluster members, ensure that the deployment manager is running and also ensure that the local node agent is stopped.

-update [-profile PROFILE_NAME -de DE_name [-component COMPONENT_name] -contextRootPrefix prefix] | [-profile PROFILE_NAME -de DE_name -virtualHost virtualHostName] | [-dataSource configuration_file] | [-jvm configuration_file] | [-jms configuration_file] | [-workManager configuration_file] | [-threadPool configuration_file] | [-webContainer configuration_file] | [-orb configuration_file] | [-messagingEngine configuration_file]

Use the -update parameter to configure a custom context root for a deployment environment. Alternatively, you can use the -update parameter to update datasource information for the deployment environment. The specified custom context root is used as a prefix to the default BPM context roots. Create the deployment environment before you run the command. Stop the deployment manager, node agents, and all running servers before you run the command. Run the command from the <install_root>\bin directory in the Windows environment.

The -profile PROFILE_NAME value identifies the deployment manager profile. It is suggested that you create a backup copy of the profile before running the -update parameter. The -de DE_name value identifies the deployment environment name. The -component COMPONENT_name value identifies the component, and the only value (with respect to a custom context root) is ProcessPortal. The -contextRootPrefix prefix value specifies the custom context root prefix that you want to use. The prefix must begin with a leading forward slash (/). The specified prefix is added to the beginning of the default context root. If you specify a leading forward slash (/) by itself, the -contextRootPrefix parameter will revert any customized context root back to the IBM BPM default context root. For more information about customizing context roots, see the topic "Customizing context roots for the components in a deployment environment."

Do your process applications use inbound web services, the web API, or the REST API? All URLs exposed by IBM Business Process Manager will contain the newly configured context root, therefore this change will affect client applications that are using the previous context root as an endpoint. Update your client applications to use the new custom context root.

Any previously installed Process Designer must be downloaded and installed again because Process Designer must use the new context root configuration.

Update the web server plug-in. The web modules are updated in the product applications when you run the BPMConfig -update -contextRootPrefix command. If the product applications are mapped to a web server, the plugin-cfg.xml file for the web server must be updated with the new context roots. Any web server plug-ins might need to be propagated (or generated and propagated). For more information, see Plug-ins configuration in the WebSphere Application Server product information.

Clear your browser cache before you start IBM Business Process Manager user interfaces.

Important: If you update the value of -contextRootPrefix, you must change any hard-coded URLs in your existing applications. To successfully deploy applications, the Process Center must at least be at the V8.5.0.1 level.

Note: If you see a window requesting you to log in a second time when you create a context root prefix, try these changes to fix the problem. Are you using Lightweight Third Party Authentication (LTPA) security? A log in is requested because you have multiple cells sharing the same IBM HTTP Server (IHS) without sharing the LTPA keys. Share the LTPA keys. Another reason for this problem is a limitation that users can access only one cell on the same IHS. If a user wants to access another cell on the same IHS, it can be done through another browser; that is, use one browser per cell.

If you specify -update -profile PROFILE_NAME -de DE_name -virtualHost virtualHostName, the web modules of the IBM BPM applications in the specified deployment environment are mapped to the specified virtual host. If you have more than one deployment environment in your cell, you can either use context root prefixes to differentiate between the multiple deployment environments or you can use the BPMConfig -update -virtualHost command to configure another virtual host.

If you specify -update -dataSource configuration_file, the database name, database server name, and database server port are all updated for the deployment environment. For Oracle databases, the database URL is also updated. However, the associated user authentication and schema are not updated. As a result, you must ensure that the database that you are updating has the same user and schema as those configured in the current deployment environment.

You can also use the following options with the -update parameter to update performance-tuning properties for the deployment environment specified in the configuration file:

-jvm configuration_file

Update the JVM performance-tuning properties.

-jms configuration_file

Update the connection factory and activation specification performance-tuning properties.

-workManager configuration_file

Update the work manager performance-tuning properties.

-threadPool configuration_file

Update the thread pool performance-tuning properties.

-webContainer configuration_file

Update the web container performance-tuning properties.

-orb configuration_file

Update the Object Request Broker (ORB) performance-tuning properties.

-messagingEngine configuration_file

Update the messaging engine performance-tuning properties.

-upgrade -de properties_file

Upgrades an existing IBM BPM Standard deployment environment to an IBM BPM Advanced deployment environment. The upgrade enables you to take advantage of the additional capabilities that are provided in an IBM BPM Advanced environment.

When the command is run to upgrade your deployment environment, the upgrade is based on the properties that are found in the specified properties file. You probably need to edit the properties in the file before you run the command. Sample properties files that can be edited and used to upgrade a deployment environment are found in the following location:

install_root/BPM/samples/config/upgradede

Note: If you customized the Process Portal themes, be aware that when you run the BPMConfig –upgrade command, it changes the import settings for Business Space system artifacts in the oobLoadedStatus.properties file, and overwrites your customizations. Before running BPMConfig -upgrade back up your customizations. Then, reimport and merge the customizations with the deployed theme after completing the upgrade process.

If you added a supported customization to your IBM BPM Standard deployment environment, such as a context root prefix or an update to the virtual host mapping, the same customization is automatically applied to the IBM BPM Advanced deployment environment during the upgrade. For example, if you set the bpm.de.contextRootPrefix property and the bpm.de.virtualHost property in your IBM BPM Standard properties file, the context root and virtual host mapping of all web modules are automatically updated for the IBM BPM Advanced capabilities when the environment is upgraded.

When you choose the databases that you want to use in the new IBM BPM Advanced deployment environment, you can use your existing IBM BPM databases or you can specify new databases and buses for the advanced capabilities of the environment. Scripts are provided to generate the resources that are required to support the databases and buses. For example, if you set the bpm.de.deferSchemaCreation property to false, all of the tables that are required for the advanced environment capabilities are generated automatically in your databases.

Note: Although you can upgrade your deployment environment from IBM BPM Standard to IBM BPM Advanced, you cannot change the environment type from Process Center to Process Server (or from Process Server to Process Center) or change your topology from single-cluster to three-clusters (or from three-clusters to single-cluster) or change your database type.

-validate properties_file OR -db properties_file OR -profile PROFILE_NAME -de DE_name [-outputDir output_directory]

If you specify -validate properties_file, it validates that the properties file can be used to create a deployment environment.

If you specify -validate -db properties_file, it validates that connections to the databases can be successfully established using the specified user names and passwords. It does not validate the contents of the databases, such as the schema.

EmbeddedECMDb has to use the same schema name as the database user name. Otherwise, running the BPMConfig -validate command in a working IBM BPM environment of V8.5.5 or later gives you the following error: CWMCB0239E: The database schema value BPMECM2S for component EmbeddedECM should be the same as the database user name BPMSAND.

If you specify -validate -profile PROFILE_NAME -de DE_name [-outputDir output_directory], a status report is generated for the specified deployment environment. The status report lists the components that are configured in the deployment environment and displays the status of each component and its associated resources. The report also displays the status of key security roles and the runtime status of Process Center, IBM Process Server, and Performance Data Warehouse. The name of the generated status report is ConfigValidationReport_deName.html, where deName is the name of the deployment environment. For example, ConfigValidationReport_De1.html. If you specify an output directory, the status report is generated into a directory that is named html that is appended to the output directory. For example, if you specify E:/Output as the output directory, the status report is generated into E:/Output/html. If you do not specify an output directory, the status report is generated into an html directory that is appended to the directory where you ran the BPMConfig command. For example, install_root/bin/html.

With secure LDAP configured, running the BPMConfig -validate command to verify the exported properties file gives you the following error: CWMCB0345E: LDAP protocol ldaps: is not supported. You can safely ignore this error.

For more information about validation errors if you are upgrading, see JR51260: DBUpgrade fails with CWMCB0258E, CWMCB0260E, or CWMCB0345E errors when you upgrade IBM BPM v8.5.0.x to IBM BPM V8.5.5.0.

-start [-profile PROFILE_NAME -de DE_name] OR properties_file

Starts the deployment environment using the specified deployment manager profile. You can run the command with a properties file or you can specify the profile and deployment environment name. If you choose to specify the profile and deployment environment name, the command must be run on the deployment manager machine after all remote nodes have been manually started. If you choose to run the command with a properties file, the BPMConfig command must be run on every machine, including the deployment manager machine and all remote nodes. You can use the properties file that you used when you created your deployment environment using the BPMConfig command. Alternatively, you can export a properties file by running the BPMConfig command with the -export parameter (as described in the -export section).

When run on the deployment manager machine (where the IBM BPM installation resides that hosts the deployment manager profile), the -start parameter starts multiple elements of the deployment environment using the specified deployment manager profile, including the deployment manager, the node agents, and the cluster members.

Note: When run with the start option, the BPMConfig command sends instructions to start all the servers defined in the clusters and returns the command completion status. In some cases, the command might return as completed before all the servers have been started. Verify in the Process Admin Console that all the servers are started and that the applications are started before processing any events, such as starting Process Designer.

-stop [-profile PROFILE_NAME -de DE_name -username user_name -password password] OR properties_file

Stops the deployment environment using the specified deployment manager profile. The command must be run on the deployment manager machine, but it does not need to be run on any remote nodes. You can run the command with a properties file or you can specify the profile, deployment environment name, user name and password. If you choose to run the command with a properties file, you can use the properties file that you used when you created your deployment environment using the BPMConfig command. Alternatively, you can export a properties file by running the BPMConfig command with the -export parameter (as described in the -export section). The user name and password that are used can be the cell administrator or the deployment environment manager administrator user name and password. If you do not specify a user name and password, you are prompted to provide them when the command is run.

Important: The stop option does not stop the deployment manager and the node agents. If necessary, you must stop them manually.

-export -profile profile_name -de DE_name [-outputDir configurationDirectory]

Exports configuration properties from an existing deployment environment to a folder. These configuration properties can be used for the following purposes:

• Modify the properties with the IBM BPM Configuration editor and then create another deployment environment on a different IBM BPM installation that is similar to the exported deployment environment (a clone with modifications).
• Compare the configuration of the exported deployment environment with another deployment environment that you also exported.
• Extend the existing deployment environment with additional cluster members by running BPMConfig -create clusterMembers properties_file.

The following properties are exported:

• Cell and deployment environment configuration properties
• Deployment manager and managed node configuration properties
• Cluster and cluster member configuration properties
• Database, data source, and JDBC provider configuration properties
• Authentication alias and role mapping configuration properties
• LDAP configuration properties
• Deployment environment and Process Portal context root prefix (if set in the current deployment environment)
• Business Process Choreographer customization properties
• Additional performance-tuning configuration properties

The -profile option specifies the name of the deployment manager profile or stand-alone profile. The optional -outputDir option is the full path to the folder where you want to put the configuration files. If you do not specify the -outputDir option, the configuration files are placed in the default output directory current_dir/deployment_environment_name (where current_dir is the current working directory).

Tip: If you are running this command more than once because you have more than one deployment environment, remember to specify different output directory names if you use the -outputDir option.

The output directory contains files similar to the following files. To reflect the requirements of your new deployment environment, make updates to the exported properties file listed in the first row of the table. No updates are needed to the other files listed in the table, but ensure that those files are kept together in the same directory for future reference.

Table 1. Configuration files for each deployment environment

Sample name	Description
de_name.properties	This properties file contains the configuration information from your source environment. You use this file when you configure the target environment. For more information, see the reference topic about configuration properties for the BPMConfig command.
fileRegistry.xml	If you use a file-based user registry, the user registry file is copied from the source environment to be added to the target environment.
ltpa.jceks	If you use LTPA, the LTPA key file is copied from the source environment to be added to the target environment.
ldap_additional_properties.xml	If you use a federated repository and an unencrypted LDAP connection in the source environment, additional properties of the LDAP server are copied from the source environment to the output directory, where they are later used automatically to create the target environment.
Application-config-bpc.xml and resources-bpc.xml	If you have Business Process Choreographer configured in the source environment, the configuration files are copied from the source environment to the output directory, where they are later used automatically to create the target environment.
Support-config-bpc.xml	If you have Business Process Choreographer Archive Manager configured on the support cluster in the source environment, the configuration is copied from the source environment to the output directory, where it is later used automatically to create the target environment.

-migrate -wasHome source_installation_directory -profile profile_name [-de DE_name] [-responseFile path_to_response_file] [-outputDir configurationDirectory]

Use this command to migrate from an older product or version. You must specify the following parameters:

• The -wasHome option specifies the full path to the IBM BPM installation directory for the previous installation in the source environment. For example: opt/BPMInstall/BMP751Adv or E:\BPMInstall\WPS700 or C:\IBM\Lombardi72\AppServer.
• The -profile option specifies the name of the deployment manager profile or stand-alone profile.
• The optional -de option specifies the name of the deployment environment, which you can find in the administrative console. Do not use this parameter if you are migrating from a stand-alone environment.

Optionally, create a response file and specify the -responseFile option to run BPMConfig -migrate silently during migration. If you do not specify this option, you are prompted for the deployment environment type, the topology of the target environment, and whether the target environment has a single messaging engine bus or multiple buses. The following example shows a response file:

# Deployment environment type for the target environment. Value is Advanced, Standard or AdvancedOnly
target.deType=Advanced
# Topology for the target environment(number of cluster). Value is 1 or 3
target.clusterNumber=3
# Node number for the target environment. Value is a number, such as 2.
target.nodeNumber=2
# Bus option for the target environment for 3-cluster topology. Value is true or false
target.isSingleBus=false

The optional -outputDir option is the full path to the folder where you want to put the configuration files. If you do not specify the -outputDir option, the configuration files are placed in the default output directory current_dir/deployment_environment_name (where current_dir is the current working directory).

Tip: If you are running this command more than once because you have more than one deployment environment, remember to specify different output directory names if you use the -outputDir option.

The output directory contains files similar to the following files:

Table 2. Files for migration

Sample name	Description
DE1-Advanced-PS-ThreeClusters-DB2-MultiBus.properties	This properties file contains the configuration information from your source environment. You use this file when you configure the target environment. For information about the properties, see the reference topic about properties that are migrated.
fileRegistry.xml	If you use a file-based user registry, the user registry file is copied from the source environment to be migrated to the target environment.
ltpa.jceks	If you use LTPA, the LTPA key file is copied from the source environment to be migrated to the target environment.
ldap_additional_properties.xml	If you use a federated repository and an unencrypted LDAP connection in the source environment, additional properties of the LDAP server are copied from the source environment to be migrated to the target environment.
PDW_100SourceCustomMerged.xml and ProcessServer_100SourceCustomMerged.xml	If you have XML configuration properties files, they are copied from the source environment to be migrated to the target environment.
Application-config-bpc.xml and resources-bpc.xml	If you have Business Process Choreographer configured in the source environment, the configuration files are copied from the source environment to be migrated to the target environment.
Support-config-bpc.xml	If you have Business Process Choreographer Archive Manager configured on the support cluster in the source environment, the configuration is copied from the source environment to be migrated to the target environment.

-delete [-profiles properties_file] | [-profile profile_name -de DE_name] | [-profile profile_name -de DE_name -node node_name] | [-profile profile_name -de DE_name -node node_name -clusterMember cluster_member_name] -acceptDeletionPrompt

The -delete parameter is used to delete profiles, deployment environments, and cluster members.

• To delete profiles, run the following command:

  BPMConfig -delete -profiles properties_file

  It is suggested that you create a backup copy of the profiles before running the -delete parameter.

  Note: When you run this command, it is possible that some files under the profile root directory will not be deleted because they are locked. You should check the profile root directory, and if it still exists, you should recursively delete it.
• To delete a deployment environment, run the following command (where profile_name is the name of the deployment manager):

  BPMConfig -delete -profile profile_name -de DE_name

  The command to delete a deployment environment or a node must be run on the deployment manager machine.

  When the command is used to delete a deployment environment, it deletes the resources (such as clusters and applications) that were configured when the deployment environment was created by the BPMConfig command or the Deployment Environment wizard. The command also deletes the buses that are used by the deployment environment.

  The command retains the author alias and users that are used by the deployment environment. It also retains the database for the deployment environment as well as the DB scripts (which are in the directory profile_install_root\dbscripts\de_name).

  Before running the command to delete a deployment environment on IBM BPM Advanced, you must first manually undeploy the applications HTM_PredefinedTasks_V8000_clusterName and HTM_PredefinedTaskMsg_V8000_clusterName. Otherwise, the command will fail to delete the deployment environment.

  If there are resources that you or other users have manually configured in the deployment environment, you must delete the resources manually.

  After running the BPMConfig command, you must run the syncNode command to obtain the latest configuration file changes.

  Note: After you have run this command, you will need to manually delete the following directories on each managed node that hosted application cluster members of the deleted IBM BPM deployment environment:

  managed_node_profile/BusinessSpace/application_cluster_name
  managed_node_profile/SearchIndex/task/application_cluster_name
  managed_node_profile/FileNet/application_cluster_name

• To delete all cluster members on a node, run the following command (where node_name is the node name of the target cluster members):

  BPMConfig -delete -profile profile_name -de DE_name -node node_name

  After running the BPMConfig command, you must run the syncNode command to obtain the latest configuration file changes.

  This command action to delete all cluster members on a node will not compromise the functionality of the IBM BPM deployment environment. At least one cluster member will always remain in every IBM BPM cluster of the IBM BPM deployment environment.

  Note: After you have run this command, you will need to manually delete the following directories:

  managed_node_profile/BusinessSpace/application_cluster_name
  managed_node_profile/SearchIndex/task/application_cluster_name
  managed_node_profile/FileNet/application_cluster_name

• To delete an individual cluster member, run the following command (where cluster_member_name is the name of the target cluster member):

  BPMConfig -delete -profile profile_name -de DE_name -node node_name -clusterMember cluster_member_name

  You need to run the command only on the deployment manager node. If you have remote custom nodes, you must run the syncNode command on the remote nodes to obtain the latest configuration file changes. Before you run the syncNode command, ensure that the deployment manager is running and also ensure that the local node agent is stopped. If you have local custom nodes that are on the same machine as the deployment manager node, there is no need to run the syncNode command because it is automatically invoked for local nodes when the BPMConfig command is run.

  Note: After you have run this command, you will need to manually delete the following directories if the deleted application cluster member was the last one on the managed node:

  managed_node_profile/BusinessSpace/application_cluster_name
  managed_node_profile/SearchIndex/task/application_cluster_name
  managed_node_profile/FileNet/application_cluster_name

• If you do not want to be prompted to confirm that you want to delete the specified resources, append the -acceptDeletionPrompt option to the end of the command syntax.

-help parameterName

Displays usage information for the specified parameter name. If you specify the -help parameter by itself without an option, it returns usage information for the BPMConfig command. If you specify the -help parameter with an option (such as the -create option), it displays usage information for the specified option. For example: -help create.

The BPMConfig command uses a configuration properties file that contains the required and optional parameters that are used by the command, as well as usage information about the properties and their defaults.

When you specify the properties file to use, you can specify either an absolute path or a path relative to the current directory.

Examples

BPMConfig -create -de my.environment.properties 

BPMConfig -create -profile my_environment.properties

BPMConfig -create -sqlfiles my_environment.properties -outputDir /MyBPMScriptDir

BPMConfig -create -clusterMembers my_environment.properties

BPMConfig -update -profile mydeploymentmgrprofilename -de mydeploymentenvname -contextRootPrefix /mycorporation

BPMConfig -update -profile mydeploymentmgrprofilename -de mydeploymentenvname -component ProcessPortal -contextRootPrefix /mycorporationprocessportal

BPMConfig -update -dataSource my_environment.properties

BPMConfig -update -profile DmgrProfile -de De1 -virtualHost virhost1

BPMConfig -upgrade -de my_environment.properties

BPMConfig -validate my_environment.properties 

BPMConfig -validate -db my_environment.properties 

BPMConfig -validate -profile DmgrProfile -de De1 -outputDir E:/Output

BPMConfig -start -profile DmgrProfile -de De1

BPMConfig -start my_environment.properties

BPMConfig -stop -profile DmgrProfile -de De1 -username DmgrAdmin -password mypassword

BPMConfig -stop my_environment.properties

BPMConfig -export -profile DmgrProfile -de De1 -outputDir E:\ConfigExport

BPMConfig -migrate -wasHome E:\BPM751Adv -profile DmgrProfile -de De1 -outputDir E:\ConfigExport  

BPMConfig -migrate -wasHome /opt/BPM751Adv/ -profile Dmgr01 -de DE1 -outputDir /home/user_name/751configuration -responseFile /home/user_name/bpm_response.txt 

BPMConfig -delete -profiles my_environment.properties

BPMConfig -delete -profile DmgrProfile -de De1

BPMConfig -delete -profile DmgrProfile -de De1 -node Node1

BPMConfig -delete -profile DmgrProfile -de De1 -node Node1 -clusterMember Server1

BPMConfig -help

BPMConfig -help create