BPMConfig command-line utility

The BPMConfig command is used to create or extend a typical network deployment environment. For example, it can also be used to create the database scripts and profiles, start and stop the deployment environment, and validate the deployment environment configuration.

Syntax

Description

Use the BPMConfig command to create a typical network deployment environment, instead of using the Deployment Environment wizard or wsadmin commands. Use the BPMConfig command to create the BPMDmgr and BPMNode profiles, instead of using the Profile Management Tool or the manageprofiles utility. You can also use BPMConfig to:

Extend an existing deployment environment that was created using the BPMConfig command
Create new profiles
Create a custom context root for the deployment environment
Create the required database tables or generate the SQL scripts that you can use to create your database tables at a later time
Validate the configuration settings in an existing configuration properties file
Start and stop the deployment environment
Display usage information for a specified parameter.

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

Messages related to the running of the BPMConfig command are recorded in the following file:

install_root\logs\config\BPMConfig_time_stamp.log
install_root/logs/config/BPMConfig_time_stamp.log

Important: Run the BPMConfig command with the same properties file on all computers that will participate in the deployment environment. You must first run the command on the computer that has the deployment manager profile and then run it on each computer that has a managed node. At any given time, only one profile creation can be performed on a computer and only one node federation can be performed against a particular deployment manager. For this reason, if you are creating multiple profiles at once on different computers, you must use the federateLater option of the BPMConfig command when creating the managed node profiles and then run the command with the create de option sequentially on each computer to federate the managed nodes.

Note: If you are using IBM BPM on a Microsoft Windows operating system and you are not logged in as an administrative user, you may receive the following warning when you run the BPMConfig command (for example, when running BPMConfig -validate):

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

This warning occurs because a non-administrative user does not have write permissions on the Windows registry. The java.util.prefs.WindowsPreferences utility attempts to save information in HKEY_LOCAL_MACHINE\Software\JavaSoft\Prefs instead of under HKEY_CURRENT_USER\Software\JavaSoft\Prefs. To prevent the warning from being issued in the future, log into Windows as the administrator and create the key HKEY_LOCAL_MACHINE\Software\JavaSoft\Prefs.

Note: You might encounter a FileNotFoundException message when configuring a context root prefix. This message can be ignored.

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.

Parameters

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

Creates the profiles, deployment environment configuration, the database tables or the SQL scripts for creating the required database tables.

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 for profiles that match the values for the installPath and hostName specified in the properties file and that do not already exist. Depending on the value that you set for the bpm.de.deferSchemaCreation parameter in the properties file, either the database tables are created or the scripts to generate the database tables are created.

If you run the BPMConfig command with the -profile, option, the only profiles created are the profiles specified in the properties file that do not already exist. 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.

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.

-update [-profile PROFILE_NAME -de DE_name -component COMPONENT_name -contextRootPrefix prefix]

Use the -update parameter to configure a custom context root for a deployment environment. The specified custom context root will be used as a prefix to the default BPM context roots. Create the deployment environment before you run the command. Stop all running servers before you run the command. Run the command from the <install_root>\bin directory in the Windows environment.

PROFILE_NAME identifies the deployment manager profile. DE_name identifies the deployment environment name. COMPONENT_name identifies the component. The only value for this component with respect to a custom context root is ProcessPortal. prefix specifies the custom context root prefix you want. The prefix value requires a leading forward slash (/). The specified prefix is added to the beginning of the default context root.

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.

Notes:

You might encounter a FileNotFoundException message saying that the 100Custom.xml file cannot be found (No such file or directory) in the log file when configuring a context root prefix. This message can be ignored.
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.

-validate properties_file

If you specify -validate properties_file, it validates whether the configured deployment environment is correct by comparing it against the values in the properties file that is used to create that deployment environment.

-start [-profile PROFILE_NAME -de DE_name -username user_name -password password] 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, deployment environment name, user name and password. If you choose to specify the profile, deployment environment name, user name and password, 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.

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. The user name and password that are used can be the cell administrator or the deployment environment manager administrator user name and password.

-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 makes use of a configuration properties file that contains the required and optional parameters used by the command, as well as usage information about the properties and their defaults.

To create your own properties file, make a copy of one of the sample configuration properties files found in the product-specific directories in the following parent directory:

install_root\BPM\samples\config
install_root/BPM/samples/config

Begin with the sample file that most closely resembles the environment that you want to configure. For example, if you are configuring a single cluster environment with a single database using Standard edition, then begin by making a copy of the Standard-SingleCluster-Db2-SingleDb.properties file and then modifying the properties.

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

Important: Before you run the BPMConfig command, you must have already installed the database software and created the databases. You must also have created all the users (especially for SQL Server and Oracle) that you specify in the properties file.

Examples

Create a new deployment environment and profiles using a customized copy of the samples properties file that is installed with the product:

BPMConfig -create -de my.environment.properties

Create only the profiles based on a customized copy of the samples properties file that is installed with the product, my_environment.properties:

BPMConfig -create -profile my_environment.properties

Generate the SQL scripts to create your database tables in the output directory /MyBPMScriptDir:

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

Update a deployment environment that has a deployment manager profile name of mydeploymentmgrprofilename and a deployment environment name of mydeploymentenvname. The custom context root that is to be added to the beginning of the default context root is mycorporation.

<install_root>\bin\BPMConfig -update -profile mydeploymentmgrprofilename -de mydeploymentenvname -contextRootPrefix /mycorporation

Update a deployment environment that has a deployment manager profile name of mydeploymentmgrprofilename and a deployment environment name of mydeploymentenvname. The context root prefix to be added to Process Portal only is mycorporationprocessportal.

<install_root>\bin\BPMConfig -update -profile mydeploymentmgrprofilename -de mydeploymentenvname -component ProcessPortal -contextRootPrefix /mycorporationprocessportal

Validate that the deployment environment configuration specified in the properties file my_environment.properties matches the current configuration of the deployment environment:

BPMConfig -validate my_environment.properties

Start the De1 deployment environment within the DmgrProfile profile:

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

BPMConfig -start my_environment.properties

Stop the De1 deployment environment within the DmgrProfile profile:

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

BPMConfig -stop my_environment.properties

Display usage information for the BPMConfig command:

BPMConfig -help

Display usage information for a specified parameter, such as the create parameter shown in the following example:

BPMConfig -help create