BPMConfig command-line utility

Syntax

BPMConfig
[ -create [-omitPasswordValidation] [-de|-profile|-sqlfiles|-clusterMembers] properties_file ]
[ -update [-profile profile_name [-de DE_name] [-component component_name] -contextRootPrefix prefix] | [-profile profile_name -de DE_name -virtualHost virtual_host_name] | [-profile profile_name -de DE_name -caseConfigure [-responseFile response_file]] | [-profile profile_name -de DE_name -networkDirectory networkDirectory -component component_name] | [-profile profile_name -de DE_name -enablePD  true|false -component CaseManager] | [-profile profile_name -de DE_name -enableVCS true|false -component CaseManager [-vcsSandboxPath vcsSandboxPath -vcsHeartbeatInterval vcsHeartbeatInterval -vcsCommitTimeout vcsCommitTimeout -vcsDeliverTimeout vcsDeliverTimeout [-vcsAdditionalParameters vcsAdditionalParameters]]] | [-profile profile_name -de DE_name -taskManagerAdminUser taskManagerAdminUser -taskManagerAdminPassword taskManagerAdminPassword -component ContentNavigator] | [-profile profile_name -de DE_name -caseForms -type eForms|ibmForms [-ibmFormsRenderApp ibmFormsRenderApp -translatorURL translatorURL -ibmFormsDirectory ibmFormsDirectory]] | [-performanceTuning properties_file] | [-dataSource properties_file] | [-profile profile_name -node node_name -jdbcDriverPath jdbc_driver_path] | [-profile profile_name -enableContentObjectSupport true|false [-clientDownloadServiceHostname CPE_server_hostname -clientDownloadServicePort CPE_server_port] ] ]
[ -upgrade -de properties_file [-component component_name ]  [-profile dmgr_profile_name ]
[ -export -profile profile_name -de DE_name [-db [properties_file]] [-system properties_file] [-outputDir configuration_directory] ]
[ -migrate -wasHome source_installation_directory -profile profile_name [-de DE_name] [-responseFile response_file] [-useRecommendedSettings] [-outputDir configuration_directory] ]
[ -validate properties_file [-omitPasswordValidation] | -db properties_file | -profile profile_name -de DE_name | -performanceTuning properties_file [-outputDir output_directory] ]
[ -start [-profile profile_name -de DE_name] | properties_file ]
[ -stop [-profile profile_name -de DE_name -username user_name -password password] | properties_file ]
[ -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 ]
[ -help parameter_name ]

Description

You can use the BPMConfig command to create an Business Automation Workflow 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 the deployment manager and managed nodes, instead of using the Profile Management Tool or the manageprofiles utility.

To supplement the BPMConfig command, an IBM Business Automation Workflow 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 Business Automation Workflow Configuration editor is found in the topic Configuring your environment with the IBM Business Automation Workflow Configuration editor.

install_root/BPM/samples/config

If an error occurs while running the BPMConfig command, the command will end with an error message that should help you diagnose and resolve the problem. Any messages that are related to the running of the BPMConfig command are recorded in the following file (where install_root is the installation location of IBM Business Process Manager):

Before V19.0.0.2: install_root/logs/config/BPMConfig_time_stamp.log

From V19.0.0.2: install_root/logs/config/BPMConfig_action_name_profile_name_deployment_environment_name_time_stamp.log

Where action_name is one of create, update, upgrade, export, migrate, validate, start, or stop. If the particular BPMConfig action is associated with a profile name, profile_name, deployment environment name, deployment_environment_name, or both, that information is also part of the file name. For example, the output file for the command BPMConfig.sh -export Dmgr -de De1PC would have the following output file name: BPMConfig_export_Dmgr_De1PC_[timestamp].log. But if there are errors in the command parameters, such as the action name, profile name, or deployment environment name, the BPMConfig output log file has the following file name: BPMConfig_time_stamp.log

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

Parameters

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

Creates the profiles, deployment environment configuration, 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 -omitPasswordValidation, the passwords in the configuration file are not checked for unsupported characters.

Warning: Using this parameter might cause argument-processing errors of the various commands that BPMConfig invokes behind the scenes. Alternatively, you might not see a processing error, but some characters will be lost and the actual password that is stored will not be what you specified in the properties file.

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 properties specified in the configuration 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 property in the properties file, the database tables may be created and the Process database loaded with system information. If you are migrating and Business Process Choreographer was configured in your source environment, the configuration properties 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."

Important: If you already have a version of Db2 installed and you create the deployment environment without deferring schema creation, you must have Db2® AWSE 10.5.0.0 or above. Otherwise, the database version validation will fail with an error; for example CWMCB0316E: Your database system is not the required version. The minimum supported version is 10.5.0.0 but the current version is 10.1.0.2.

If you run the BPMConfig -create command with the -profile option, the only profiles that are created are those profiles specified in the configuration 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 or more Business Automation Workflow profiles, it does not configure the deployment environment. This is useful if you want to use the Deployment Environment wizard in the administrative console to configure the deployment environment. You can create the Business Automation Workflow 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 BPMConfig command with the -create -sqlfiles action. This command generates SQL script files both for configuring new Business Automation Workflow installations and for migrating earlier versions to Business Automation Workflow V19.0.0.3. You can optionally specify an output directory for the generated scripts using the -outputDir option. 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 BPMConfig -create -sqlfiles command 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 configuration 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 properties 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 properties 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 virtual_host_name] | [-profile profile_name -de DE_name -caseConfigure [-responseFile response_file]] | [-profile profile_name -de DE_name -networkDirectory networkDirectory -component component_name] | [-profile profile_name -de DE_name -enablePD true|false -component CaseManager] | [-profile profile_name -de DE_name -enableVCS true|false -component CaseManager [-vcsSandboxPath vcsSandboxPath -vcsHeartbeatInterval vcsHeartbeatInterval -vcsCommitTimeout vcsCommitTimeout -vcsDeliverTimeout vcsDeliverTimeout [-vcsAdditionalParameters vcsAdditionalParameters]]] | [-profile profile_name -de DE_name -taskManagerAdminUser taskManagerAdminUser -taskManagerAdminPassword taskManagerAdminPassword -component ContentNavigator] | [-profile profile_name -de DE_name -caseForms -type eForms|ibmForms [-ibmFormsRenderApp ibmFormsRenderApp -translatorURL translatorURL -ibmFormsDirectory ibmFormsDirectory]] | [-performanceTuning properties_file] | [-dataSource properties_file] | [-profile profile_name -node node_name -jdbcDriverPath jdbc_driver_path] | [-profile profile_name -enableContentObjectSupport true|false [-clientDownloadServiceHostname CPE_server_hostname -clientDownloadServicePort CPE_server_port] ] ]

Use the -update parameter to configure a custom context root for a deployment environment. Alternatively, you can use the -update parameter to update data source information for the deployment environment. The specified custom context root is used as a prefix to the default Business Automation Workflow 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.

You can also use the -update parameter with the jdbc_driver_path value to configure custom JDBC paths. This command updates the JDBC driver path variables. On a stand-alone server, run the command to configure the server. In a network deployment environment, run the command to configure the deployment manager and run it again for each managed node.

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. You can omit the -de option if there is only one deployment environment in the WebSphere cell. The -component component_name value identifies the component, and the values (with respect to a custom context root) are ProcessPortal, CaseManager, and ContentNavigator. If -component component_name is not specified, the context root is updated for all components.

The TargetObjectStore value has been replaced with CaseManager.

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. You can omit the -de option if there is only one deployment environment in the WebSphere cell. The -component component_name value identifies the component, and the values (with respect to a custom context root) are ProcessPortal, CaseManager, and ContentNavigator. 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 option will revert any customized context root back to the Business Automation Workflow default context root. For more information about customizing context roots, see the topic "Customizing context roots for the components in a deployment environment."

Note: In V18.0.0.1 (only), when the -contextRootPrefix option is specified, IBM Business Automation Workflow applications are handled differently than case applications. For example, if the option value was set to /abc, the Process Center application context root would be changed from /ProcessCenter to /abc/ProcessCenter. However, the Case Builder application would be changed from /CaseBuilder to /abcCaseBuilder without the forward slash character (/) between abc and CaseBuilder.

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.

Case management configuration must be updated with the new context root. Start the Case configuration tool and run all tasks.

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 the topic Plug-ins configuration in the WebSphere Application Server product information.

Clear your browser cache before you start the user interfaces. After running the BPMConfig command, run the syncNode command on each node to obtain the latest configuration file changes.

Important: If you update the value of the -contextRootPrefix option, you must change any hard-coded URLs in your existing applications. To successfully deploy applications, the Workflow 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 login 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 virtual_host_name, the web modules of the Business Automation Workflow 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 -profile profile_name -de DE_name -caseConfigure, the command collects the case management configuration parameters and configures the case data sources for the upgrade path.

You can run this command silently by specifying the -responseFile response_file parameter. See the Sample case configuration response files.

If you specify -update -profile profile_name -de DE_name -networkDirectory networkDirectory -component component_name, you can update the network directory for the IBM Content Navigator or the IBM Case Manager. The -component parameter is required and the supported values are CaseManager and ContentNavigator.

If you specify -update -dataSource properties_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 -performanceTuning option with the -update parameter to update performance tuning properties for the deployment environment specified in the configuration properties file. If you specify -performanceTuning properties_file, all performance tuning properties in the configuration properties file are updated. For the list of performance tuning properties that can be edited, see Configuration properties for the BPMConfig command.

If you specify -update -profile profile_name -enableContentObjectSupport true|false, you can enable or disable content object support in IBM Business Automation Workflow. By default, internal Content Platform Engine 5.5.3 or later is used with IBM Business Automation Workflow (such as used with IBM Business Automation Workflow 19.0.0.2 and later), and content object support is enabled.

If an internal Content Platform Engine is used, you can enable content object support by using the -enableContentObjectSupport parameter. You can also use the same parameter to disable content object support regardless of the internal Content Platform Engine version. See the example in the Examples section below.

However, if (and only if) an external Content Platform Engine is used that is version 5.5.3 or later and content object support is not enabled, you can manually enable content object support by using the -enableContentObjectSupport parameter with the -clientDownloadServiceHostname and -clientDownloadServicePort parameters. You can also use the same parameters to disable content object support regardless of the external Content Platform Engine version. The -clientDownloadServiceHostname and the -clientDownloadServicePort parameters are required to ensure a connection between the BPMConfig command and the remote Content Platform Engine server. The -clientDownloadServiceHostname parameter specifies the hostname where the Content Platform Engine server is running. The -clientDownloadServicePort parameter provides the HTTP or HTTPS port number of the server where the external Content Platform Engine application is deployed. The default port numbers are 9080 and 9443. If you are using IBM Business Automation Workflow 19.0.0.2 or later, you must use the HTTPS port number, 9443. See the example in the Examples section below.

Note: For an external Content Platform Engine 5.5.3 container, content object support is not supported and you cannot use the BPMConfig command to enable it.

-upgrade -de properties_file [-component component_name] [-profile dmgr_profile_name ]

Upgrades an existing Standard deployment environment to an Advanced deployment environment. The upgrade enables you to take advantage of the additional capabilities that are provided in an Advanced deployment environment. You can also run the upgrade command to add BPCArchive to a 3-cluster topology or to add the BPM document store for DB2 on z/OS. The valid values for the -component option are BPCArchive and EmbeddedECM.

To upgrade your deployment environment, use the following command:

BPMConfig.sh -upgrade -de properties_file

After you run the command, synchronize the nodes so that the managed nodes obtain the latest configuration properties file changes.

The upgrade is based on the properties that are found in the specified configuration properties file. You probably need to edit the properties in the file before you run the command. Sample configuration 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 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 Advanced deployment environment during the upgrade. For example, if you set the bpm.de.contextRootPrefix property and the bpm.de.virtualHost property in your Standard deployment environment properties file, the context root and virtual host mapping of all web modules are automatically updated for the advanced capabilities when the environment is upgraded.

When you choose the databases that you want to use in the new Advanced deployment environment, you can use your existing Business Automation Workflow 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 Standard to Advanced, you cannot change the environment type from Workflow Center to Workflow Server (or from Workflow Server to Workflow Center) or change your topology from single-cluster to three-clusters (or from three-clusters to single-cluster) or change your database type.

To add BPCArchive to a 3-cluster topology or to add the BPM document store for DB2 on z/OS to an existing deployment environment, run the appropriate command on the deployment manager:

BPMConfig.sh -upgrade -de properties_file -component BPCArchive
BPMConfig.sh -upgrade -de properties_file -component EmbeddedECM

You must first update the configuration properties file. For instructions, see the topics Configuring Business Process Archive Manager and Configuring the BPM document store for DB2 on z/OS. After you run the command, synchronize the nodes so that the managed nodes obtain the latest configuration properties file changes.

You can also use this command to re-install a system application that was accidentally removed. It can recover the default application configuration and the previously-set context root. To use this command, you must first restart the Business Automation Workflow environment. Then run the following command:

BPMConfig -upgrade -profile dmgr_profile_name

After you run the command, restart the Business Automation Workflow environment again to force it to take effect.

Note: If applications under the BPC component are removed, you must restart the environment twice before all applications will run normally again.

-export -profile profile_name [-de DE_name] [-db [properties_file]] [-system properties_file] [-outputDir configuration_directory]]

Exports configuration properties from an existing deployment environment to an output configuration directory. Also optionally exports database information and/or system data for performance analysis purposes.

If you want to use the -export parameter to only export configuration properties from an existing deployment environment without exporting database information or system data, use the following command syntax:

BPMConfig.sh -export -profile profile_name [-de DE_name] [-outputDir configuration_directory]

Note: In the above command syntax, the -profile option specifies the name of the deployment manager profile or stand-alone profile. The -de option can be omitted if there is only one deployment environment in the WebSphere cell.

If you want to use the -export parameter to export configuration properties from an existing deployment environment and export database information and/or system data, use the following command syntax:

BPMConfig.sh -export -profile profile_name [-de DE_name] [-db [properties_file]] [-system properties_file] [-outputDir configuration_directory]

Note: In the above command syntax, the -profile option specifies the name of the deployment manager profile or stand-alone profile. The -de option can be omitted if there is only one deployment environment in the WebSphere cell. The -db option is used to export database information and the -system option is used to export system data. Both the database information and the system data are exported for performance analysis purposes. The following considerations apply when exporting database information and system data:

• You can only use the -system option to export system data on machines that are running the Linux or AIX operating systems. You cannot use the -system option to export system data on machines that are running the Windows operating system.
• If you are specifying both the -db option and the -system option, the -db option must be specified first in the command syntax.
• An input configuration properties file is optional for the -db option and required for the -system option. However, the two options use the same input file, which contains properties that enable you to export database information and system data. If you specify both the -db option and -system option in the command syntax, you must not specify an input file for the -db option and only specify an input file for the -system option. (You can change properties for both the -db and -system options in the input file that you specify with the -system option.) A sample input properties file named PerformanceAnalysis.properties is provided for you to copy and customize. It is located in the following directory (where install_root is the installation location of Business Automation Workflow):

  install_root/BPM/samples/config/performanceanalysis/

For more detailed information about using the -db and -system options to export database information and system data for performance analysis purposes, see the topics Using the BPMConfig command to export database information for performance analysis and Using the BPMConfig command to export system data for performance analysis.

If you are using the -export parameter to export configuration properties from an existing deployment environment, the exported properties can be used for the following purposes:

• Modify the properties with the IBM Business Automation Workflow Configuration editor and then create another deployment environment on a different Business Automation Workflow 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 the command BPMConfig -create clusterMembers properties_file.

The following configuration properties are exported:

• Cell and deployment environment
• Deployment manager and managed node
• Cluster and cluster member
• Data source and JDBC provider information
• Authentication alias and role mapping
• LDAP
• Deployment environment and Process Portal context root prefix (if set in the current deployment environment)
• Business Process Choreographer customization
• 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 directory where you want to put the exported configuration files. If you do not specify the -outputDir option, the configuration files are placed in the default output directory install_root/temp/DE_name.

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 configuration files similar to the files in the following table. To reflect the requirements of your new deployment environment, make updates to the exported configuration 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 properties from your source environment. You use this file when you configure the target environment. For more information about the configuration properties, see the topic 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, user-defined 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. Restriction: If you extend the federated repository to use a custom login property (such as userPrincipalName) in addition to the default uid property in the source environment, LDAP is not configured for the target environment, with the following warning: CWMCB0600W: LDAP could not be configured! You may configure LDAP separately after BPMConfig has terminated successfully. If you see this warning, manually configure LDAP with the login properties you want to use after the migration is complete.
ProcessServer_100SourceCustomMerged.xml and PDW_100SourceCustomMerged.xml	If you have XML configuration properties files, they are copied from the source environment. The exported configuration files are merged and renamed to 101CustomMigrated.xml in 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 response_file] [-useRecommendedSettings] [-outputDir configuration_directory]

Use the BPMConfig -migrate command to migrate from an older product or version. You must specify the following options:

• The -wasHome option specifies the full path to the 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 or stand-alone profile.
• The -de option specifies the name of the deployment environment, which you can find in the administrative console. This option is required if you are migrating more than one deployment environment. If you are migrating only one deployment environment, you can omit this option. Do not use this option if you are migrating from a stand-alone environment.

Optionally, you can run BPMConfig -migrate silently during migration by creating a response file and specifying the -responseFile response_file option (where response_file is the full path to the response file). If you do not specify the -responseFile 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 the content of 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

If you want to use the recommended values for the performance tuning properties after migration, instead of using the values from the source environment, you can optionally specify the -useRecommendedSettings option. For performance tuning properties, such as the JVM heap size or thread pool configuration, the command compares the source value with the recommended value. If the source value is smaller, the recommended value is added to the configuration properties file instead. You can review and modify the properties later with the IBM Business Automation Workflow Configuration editor.

Restriction:

• If you are migrating from a stand-alone environment, you must migrate the performance tuning properties manually.
• If the source environment is a network deployment environment, BPMConfig -migrate adds a default cluster member in the properties file for each migrated cluster. However, it does not migrate existing cluster members; you must add them in the properties file manually.

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 install_root/temp/DE_name.

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 files in the following table:

Table 2. Migration files

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, user-defined additional properties of the LDAP server are copied from the source environment to be migrated to the target environment. Restriction: If you extend the federated repository to use a custom login property (such as userPrincipalName) in addition to the default uid property in the source environment, LDAP is not configured for the target environment, with the following warning: CWMCB0600W: LDAP could not be configured! You may configure LDAP separately after BPMConfig has terminated successfully. If you see this warning, manually configure LDAP with the login properties you want to use after the migration is complete.
ProcessServer_100SourceCustomMerged.xml and PDW_100SourceCustomMerged.xml	If you have XML configuration properties files, they are copied from the source environment to be migrated to the target environment. The exported configuration files are merged and renamed to 101CustomMigrated.xml in 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.

-validate properties_file [-omitPasswordValidation] | -db properties_file | -profile profile_name [-de DE_name] [-outputDir output_directory] | -performanceTuning properties_file

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

If you specify -validate -omitPasswordValidation, the passwords in the configuration file are not checked for unsupported characters.

Warning: Specifying this parameter can result in serious consequences.

If you specify -validate -db properties_file, the command 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 Business Automation Workflow or IBM Business Process Manager 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] (where the -de option is optional when there is only one deployment environment in the WebSphere cell), 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 Workflow Center, Workflow Server, and Performance Data Warehouse. The name of the generated status report is ConfigValidationReport_DE_name.html, where DE_name 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 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.

If you specify -validate -performanceTuning properties_file, the command validates all performance tuning parameters in the configuration properties file, such as the JVM heap size and thread pool configuration. If the value in the file is different from the recommended value, you see a warning message. For example, if the recommended value for the JVM maximum heap size is 2048, but the value in the configuration properties file is 1024, the following warning message is shown: The parameter 'maximumHeapSize' for Dmgr value [2014] is less than the target default value [2048]. For the list of performance tuning properties that can be edited, see Configuration properties for the BPMConfig command.

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

Running BPMConfig -validate generates the TeamworksConfiguration.running.xml files in the specified output directory. The optional parameter -outputDir defaults to install_root/bin. The TeamworksConfiguration.running.xml files are are generated for each server, and also at the cluster level for both Process Center (Workflow Center) and Performance Data Warehouse. For example, for a single cluster with one member, the following files are generated:

outputDir\cells\PCCell1\clusters\SingleCluster\performance-data-warehouse\TeamWorksConfiguration.running.xml
outputDir\cells\PCCell1\clusters\SingleCluster\process-center\TeamWorksConfiguration.running.xml
outputDir\cells\PCCell1\nodes\Node1\servers\SingleClusterMember1\performance-data-warehouse\TeamWorksConfiguration.running.xml
outputDir\cells\PCCell1\nodes\Node1\servers\SingleClusterMember1\process-center\TeamWorksConfiguration.running.xml

-start [-profile profile_name [-de DE_name]] | properties_file

Starts the deployment environment. You can run the command by specifying the deployment manager profile name and the deployment environment name or you can run the command with a configuration properties file. If you run the command by specifying the deployment manager profile name, you can omit the -de option if there is only one deployment environment in the WebSphere cell.

The command must be run on the deployment manager machine after all remote node agents have been manually started. The -start parameter uses the deployment manager profile to start multiple elements of the deployment environment, including the deployment manager, any local node agents, and the cluster members.

Note: When run with the start parameter, 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] | properties_file

Stops the deployment environment. 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 configuration properties file or you can specify the deployment manager profile name, deployment environment name, user name and password. If you run the command by specifying the deployment manager profile name, you can omit the -de option if there is only one deployment environment in the WebSphere cell. If you choose to run the command with a configuration 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 configuration 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 those of the cell administrator or the deployment environment manager administrator. If you do not specify a user name and password, you are prompted to provide them when the command is run.

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

-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 all Business Automation Workflow profiles at once, when your environment is on a single computer, run the following command:

  BPMConfig -delete -profiles properties_file

  The deployment manager must be running, and BPMConfig must be run on the computer with the profiles that you want to delete. This command will delete all profiles in the configuration properties file on the installation where you run the command, including the deployment manager profile. If you want to delete only one or more managed node profiles, see Removing a managed node profile from a deployment environment instead.

  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 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_root/dbscripts/cell_name.DE_name).

  The BPMConfig command runs in disconnected (local) mode and it does not have access to IBM BPM databases. Before you run the BPMConfig command to delete the deployment environment, ensure that there are no long-running tasks and then uninstall the applications HTM_PredefinedTasks_V8000_cluster_name and HTM_PredefinedTaskMsg_V8000_cluster_name (where cluster_name is the name of the application cluster for the deployment environment). To uninstall the applications, you can use the WebSphere administrative console or you can use an administrative command and script, as described in the topic Deploying BPEL process and human task applications and its subtopics.

  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 Business Automation Workflow 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 remove a managed node from a deployment environment, run the following command (where node_name is the name of the managed node and profile_name is the name of the deployment manager profile):

  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 will delete all cluster members on a node but will not compromise the functionality of the Business Automation Workflow deployment environment. At least one cluster member will always remain in every cluster of the 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

  For the full procedure, see Removing a managed node profile from a deployment environment.

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

  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 a parameter name, it returns usage information for the BPMConfig command. If you specify the -help parameter with a parameter name (such as the -create parameter), it displays usage information for the specified parameter. For example: -help create.

Examples

BPMConfig -create -de myenvironment.properties 

BPMConfig -create -profile myenvironment.properties

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

BPMConfig -create -clusterMembers myenvironment.properties

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

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

BPMConfig -update -dataSource myenvironment.properties

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

BPMConfig -update -profile Dmgr01 -node Dmgr01 -jdbcDriverPath E:\temp\jdbcdrivers\Oracle
BPMConfig -update -profile Dmgr01 -node Node01 -jdbcDriverPath E:\temp\jdbcdrivers\Oracle
BPMConfig -update -profile Dmgr01 -node Node02 -jdbcDriverPath /root/temp/jdbcdrivers/Oracle

Enable content object support for an internal Content Platform Engine:

BPMConfig -update -profile profile_name -enableContentObjectSupport true

Disable content object support for an external Content Platform Engine:

BPMConfig -update -profile profile_name -enableContentObjectSupport false -clientDownloadServiceHostname CPE_server_hostname -clientDownloadServicePort 9443

BPMConfig -upgrade -de myenvironment.properties

BPMConfig -validate myenvironment.properties 

BPMConfig -validate -db myenvironment.properties 

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

BPMConfig -start -profile DmgrProfile -de De1

BPMConfig -start myenvironment.properties

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

BPMConfig -stop myenvironment.properties

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

BPMConfig.sh -export -profile DmgrProfile -de De1 -db -system /home/user/performanceAnalysis.properties -outputDir /home/user/ConfigExport

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

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

BPMConfig -delete -profiles myenvironment.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