Use the bpeconfig.jacl script to configure Business Process Choreographer

IBM BPM, V8.0.1, All platforms > Install IBM BPM > IBM BPM Advanced for z/OS: Process Server > Configure IBM BPM Advanced for z/OS: Process Server > Configure components > Configure optional components > Configure Business Process Choreographer
Use the bpeconfig.jacl script to configure Business Process Choreographer

You can use the bpeconfig.jacl script to configure Business Process Choreographer and all the necessary resources on a given server or cluster. You can also use this script to configure a Business Process Archive Manager configuration, that case is described in Use the bpeconfig.jacl script to configure Business Process Archive Manager.

Know what else you want to configure on the deployment target. The script can also optionally configure a Business Process Explorer on the same deployment target.
The script uses the database parameters to generate and optionally run an SQL file, which creates the necessary database objects.

Procedure
Verify that you know which options and parameters you are going to use. Refer to the values you planned in Plan to configure Business Process Choreographer. If you run the script in batch mode, you must include all required parameters. If you run the script interactively, any required parameters that are not provided on the command line are prompted for. For detailed information about the script, examples, its options and parameters, see bpeconfig.jacl script file.
Planning bpeconfig.jacl parameters for a Business Process Choreographer configuration
Condition Plan action
If the server (or in a ND environment, the dmgr) is not running:
Include the wsadmin option:
-conntype NONE
Do not use this option if the server (or dmgr) is running.
If the server (or dmgr) is running and administrative security is enabled:
Include the following wsadmin parameters for a user ID that is authorized to run wsadmin:
-user   userName
-password   userPassword
If you are not using the default profile:
Include the wsadmin parameter:
-profileName  profileName
If you want to run the script interactively and be prompted for all mandatory and optional parameters: Invoke the script and only specify any necessary wsadmin parameters, but none of the script parameters listed below in this table.
By specifying no script parameters, -promptMode defaults to ASK.
If you want to run the script interactively and be prompted for all mandatory and optional parameters, but also specify some script parameters:
Specify any necessary wsadmin parameters and any script parameters, but also include the option:
-promptMode ASK
Any script parameters that you specify are also prompted for, and the values you provided are offered as defaults, which you can accept or change.
If you want to run the script interactively and want any missing optional script parameters to take their default values without being prompted for:
Specify any necessary wsadmin parameters and all mandatory script parameters, but also include the option:
-promptMode USE_DEFAULT
If a mandatory parameter is missing the script switches to -promptMode ASK mode.
If you want any missing mandatory parameters to cause the script to fail, rather than prompting for them:
Include the option:
-promptMode FAIL_IF_MISSING
Use this option if the script is invoked without the possibility to get input from the console.
If you want to use a response file that specifies parameter values for the script:
Include the option:
-options  responseFile
For more information, refer to the description of the -options parameter in bpeconfig.jacl script file.
If you are not creating the configuration on the default server:
Include either the parameter:
-cluster  clusterName
or both parameters:
-node  nodeName
-server  serverName
To create a Business Process Choreographer configuration: Either do not specify the -operationMode parameter, or specify -operationMode RUNTIME
If you want to create a Business Process Archive Manager: You cannot create it on the same deployment target as a Business Process Choreographer configuration. It must be configured separately on another deployment target as described in Use the bpeconfig.jacl script to configure Business Process Archive Manager.
Because the script will configure the Business Flow Manager and Human Task Manager:
Include the parameters required for the Business Flow Manager and Human Task Manager:
-jmsBFMRunAsUser  userID
-jmsBFMRunAsPwd  password -jmsHTMRunAsUser  userID
-jmsHTMRunAsPwd  password
For the administrator and monitor parameter pairs ending in Users and Groups you must specify either one or both parameters.
{-adminUsers  userList |
 -adminGroups  groupList} 
{-monitorUsers  userList |
 -monitorGroups  groupList}
The administration job user ID and password are optional.
-adminJobUser  userID 
-adminJobPwd  password
If you do not want to use the default context roots for the APIs:
Include the optional parameters for context roots:
-contextRootBFMREST  contextRootBFMREST
-contextRootBFMWS  contextRootBFMWS
-contextRootHTMREST  contextRootHTMREST
-contextRootHTMWS  contextRootHTMWS
If you want to enable a simple mail transfer protocol (SMTP) server for sending escalation e-mails:
Include the parameter:
-mailServerName  mailServerName
If the mail server requires authentication, also include the parameters:
-mailPwd  mailPassword
-mailUser  mailUserID 
Because you can either have the script file create the database, or just have it generate the SQL script without running the scripts:
Include the option:
-createDB { yes | no }
Select no because you will create the database separately after the configuration is complete.
If you select yes, the script will fail because it cannot create a DB2 for z/OS database.
If you used the database design tool to create a database design file:
Include the parameter
-bpcdbDesign  databaseDesignFile
The values specified in the database design file have precedence over any occurrences of the following parameters included on the command line: -dbJava, -dbName, -dbPwd, -dbSchema, -dbServerName, -dbServerPort, -dbTablespaceDir, -dbType, and-dbUser.
If you did not use the database design tool to create a database design file:
Include the parameter:
-dbType  databaseType
Also provide the parameters required for your database type:
-dbConnectionTarget  DB2zOSSubSystem 
-dbHome  databaseInstallPath
-dbJava  JDBCDriverPath 
-dbName  databaseName 
-dbPwd  databasePassword 
-dbSchema  schemaQualifier
-dbServerName  databaseServerName 
-dbServerPort  databaseServerPort 
-dbStorageGroup  DB2zOSStorageGroup 
-dbTablespaceDir  databaseTablespacePath 
-dbUser  databaseUser 
When running the script in batch mode on a cluster, if your database requires the -dbJava parameter, specify the parameter for each node that hosts a cluster member in the following way:
-dbJava. nodeName  JDBCDriverPath_on_ nodeName 
Specify the Business Process Choreographer message engine store settings:
Include the following parameters:
-medbUser  meDatabaseUser
-medbPwd  meDatabasePassword 
-mqCreateTables { yes | no } -mqSchemaName  mqSchemaName
If you do not want to configure Business Process Choreographer Explorer on the same deployment target as the Business Process Choreographer configuration:
Include the option:
-createExplorer no
You can run the clientconfig.jacl script later to create Business Process Choreographer Explorer configurations.
If you want to configure Business Process Choreographer Explorer on the same deployment target as the Business Process Choreographer configuration:
Include any of these optional parameters:
-createExplorer yes 
-contextRootExplorer  explorerContextRoot
-explorerHost  explorerURL
-hostName  explorerVirtualHostname
-maxListEntries  maximum
-remoteCluster  clusterName
-remoteNode  nodeName
-remoteServer  serverName
-restAPIBFM  restAPIURL^{*
-restAPIHTM  restAPIURL^*}
* In a ND environment, -restAPIBFM and -restAPIHTM are required.
Invoke the bpeconfig.jacl script file, either in batch mode providing the options and configuration parameters that you planned, or in interactive mode. For details about the script file, refer to bpeconfig.jacl script file.
Activate Business Process Choreographer: Perform Activating Business Process Choreographer.
Optional: Verify that the basic Business Process Choreographer configuration works: Perform Verifying that Business Process Choreographer works.
If you want to change the JMS authentication user IDs, the run-as user IDs, or the mappings of roles onto users and groups, using the administrative console, click Security > Business Integration security to change the security settings.
Optional: Use the administrative console to change settings for the Human Task Manager:

If you want to change any of the Human Task Manager settings for the escalation emails, such as the sender address or the URL prefix for the Business Process Choreographer Explorer, click either Servers > Clusters > WebSphere application server clusters > cluster_name or Servers > Server Types > WebSphere application servers > server_name, then on the Configuration tab, in the Business Integration section, expand Business Process Choreographer, and click Human Task Manager, and make your changes.
If you want to change the email server address, port number, the user ID, or password for the email server, click Resources > Mail > Mail sessions, select Cell scope, then click HTM mail session_ suffix, where suffix is either node_name_ server_name or cluster_name, depending on where Business Process Choreographer is configured. Make your changes.

Depending on the type of people directory provider that you use for people assignment, you might need to configure it:

The system and user registry people directory providers can be used without configuring them.
If you are using Lightweight Directory Access Protocol (LDAP), perform Configure the LDAP people directory provider.
If you are using the Virtual Member Manager (VMM), perform Configure the Virtual Member Manager people directory provider.

If you configured VMM, and you want to use people substitution, perform Configure people substitution.
If you want to use group work items, use the administrative console to enable them. Click either Servers > Clusters > WebSphere application server clusters > cluster_name or Servers > Server Types > WebSphere application servers > server_name, then on the Configuration tab, in the Business Integration section, expand Business Process Choreographer, and click Human Task Manager, then select Enable group work items.
If you have WebSphere application security enabled and you have a long-running process that calls a remote EJB method, make sure that your Common Secure Interoperability Version 2 (CSIv2) inbound authentication configuration has CSIv2 identity assertion enabled. For more information about this, refer to Configure Common Secure Interoperability Version 2 inbound communications.
If you require high security, change the default user IDs and passwords for the XA recovery authentication alias that were created for you. An additional XA recovery alias is created for both of the Business Process Choreographer data sources.

In the administrative console, click Security > Global security then in the Authentication section, expand Java Authentication and Authorization Service , click J2C authentication data.
Locate the new XA recovery aliases, which are based on the name of the standard alias with the postfix "_XAR" appended.
For example, BPCDB_Test.AppTarget_Auth_Alias_XAR and BPCME_01_Auth_Alias_XAR.
By default, the user ID and password for the XA recovery alias are the same ones used for the Business Process Choreographer database user. If that is not acceptable for your security requirements, change the XA recovery alias user IDs and passwords. The database identity for the XA recovery authentication alias on a data source must have authorization to do XA recovery. Depending on the authorization schema for your installation, this level of authorization might be different from the level of authorization that the identity needs to access database tables for an application.

If you have not yet installed and configured Business Process Choreographer Explorer, you can configure it now. Perform Configure Business Process Choreographer Explorer.
If you configured Business Process Choreographer in a ND environment:
If you will use the Business Process Choreographer Explorer, Business Process Archive Manager, the Business Space, or a client that uses the Representational State Transfer (REST) API, you must change the default context roots for the REST API so that they are unique for each combination of host name and port. To set the context roots perform the following:
To set the context roots for the Business Flow Manager, click Applications > Application Types > WebSphere enterprise applications then application_ suffix > Context Root for Web Modules, where application is BPEContainer for a Business Process Choreographer configuration or BPArchiveMgr for a Business Process Archive Manager configuration, and suffix is either node_name_ server_name or the cluster_name where Business Process Choreographer or Business Process Archive Manager is configured. Then make sure that the context roots for the following web modules and are correct and unique.

BFMIF_ scopeWeb
BFMJAXWSAPI
BFMRESTAPI

To set the context roots for the Human Task Manager, click Applications > Application Types > WebSphere enterprise applications then application_ suffix > Context Root for Web Modules, where application is TaskContainer for a Business Process Choreographer configuration or TaskArchiveMgr for a Business Process Archive Manager configuration, and suffix is either node_name_ server_name or the cluster_name where Business Process Choreographer is configured. Then make sure that the context roots for the following web modules and are correct and unique.

HTMIF_ scopeWeb
HTMJAXWSAPI
HTMRESTAPI
To change the REST URLs that the Business Process Choreographer Explorer uses:
Click Servers > Clusters > WebSphere application server clusters > cluster_name or Servers > Server Types > WebSphere application servers > server_name . On the Configuration tab, in the Business Integration section, expand Business Process Choreographer and click Business Process Choreographer Explorer. Update the Business Flow Manager and Human Task Manager REST API URLs.
Update the endpoints in config-rest.xml using a command similar to the following example, which uses PS.AppTarget as the cluster name:
wsadmin>AdminTask.updateRESTServiceProvider(['-clusterName',  'PS.AppTarget', '-appName', 'BPEContainer_PS.AppTarget', '-webModuleName','bfmrestapi.war', '-contextRoot', '/rest/bpm/bfmPS2/'])

wsadmin>AdminTask.updateRESTServiceProvider(['-clusterName',  'PS.AppTarget', '-appName', 'TaskContainer_PS.AppTarget', '-webModuleName','taskrestapi.war', '-contextRoot', '/rest /bpm/htmPS2/'])
.
If you changed any of the context roots for the Business Flow Manager or Human Task Manager you must also modify the corresponding endpoints:

If you use the Business Process Choreographer Explorer or Business Process Archive Explorer: Change the REST endpoint to match the new context roots by clicking either Servers > Clusters > WebSphere application server clusters > cluster_name or Servers > Server Types > WebSphere application servers > server_name, then on the Configuration tab, in the Business Integration section, expand Business Process Choreographer, and click Business Process Choreographer Explorer, select the BPCExplorer_ scope or BPCArchiveExplorer_ scope instance that you want to modify, and set the new value.
For example, if the context root for the Business Flow Manager REST API is /rest/bpm/bfm then the full URL might be something like http://system7.mycompany.com:9080/rest/bpm/bfm.
If you mapped the modules to an HTTP server, proxy server, IP sprayer, load balancer, or similar server, the URL should be based on the hostname and port number for that server.
If you use the Business Space: Change the REST endpoints to match the new context roots by clicking either Servers > Clusters > WebSphere application server clusters > cluster_name or Servers > Server Types > WebSphere application servers > server_name, then on the Configuration tab, in the Business Integration section, expand Business Process Choreographer, and either Business Flow Manager or Human Task Manager, then under Additional Properties click REST Service Endpoint, and set the new value.
If you mapped the modules to an HTTP server, proxy server, IP sprayer, load balancer, or similar server, the URL should be based on the hostname and port number for that server.
Optional: Update your virtual host configuration. By default, the web modules of the Business Process Choreographer applications are configured for the default_host virtual host. Verify that the ports associated with the host alias are correct. You might need to add host aliases for the host names and ports of additional cluster members or for the web server that is used. For more details about virtual hosts, refer to Virtual hosts.
Results
Business Process Choreographer is configured.

Configure Business Process Choreographer

Related tasks:
Troubleshooting the Business Process Choreographer configuration

Condition	Plan action
If the server (or in a ND environment, the dmgr) is not running:	Include the wsadmin option: -conntype NONE Do not use this option if the server (or dmgr) is running.
If the server (or dmgr) is running and administrative security is enabled:	Include the following wsadmin parameters for a user ID that is authorized to run wsadmin: -user userName -password userPassword
If you are not using the default profile:	Include the wsadmin parameter: -profileName profileName
If you want to run the script interactively and be prompted for all mandatory and optional parameters:	Invoke the script and only specify any necessary wsadmin parameters, but none of the script parameters listed below in this table. By specifying no script parameters, -promptMode defaults to ASK.
If you want to run the script interactively and be prompted for all mandatory and optional parameters, but also specify some script parameters:	Specify any necessary wsadmin parameters and any script parameters, but also include the option: -promptMode ASK Any script parameters that you specify are also prompted for, and the values you provided are offered as defaults, which you can accept or change.
If you want to run the script interactively and want any missing optional script parameters to take their default values without being prompted for:	Specify any necessary wsadmin parameters and all mandatory script parameters, but also include the option: -promptMode USE_DEFAULT If a mandatory parameter is missing the script switches to -promptMode ASK mode.
If you want any missing mandatory parameters to cause the script to fail, rather than prompting for them:	Include the option: -promptMode FAIL_IF_MISSING Use this option if the script is invoked without the possibility to get input from the console.
If you want to use a response file that specifies parameter values for the script:	Include the option: -options responseFile For more information, refer to the description of the -options parameter in bpeconfig.jacl script file.
If you are not creating the configuration on the default server:	Include either the parameter: -cluster clusterName or both parameters: -node nodeName -server serverName
To create a Business Process Choreographer configuration:	Either do not specify the -operationMode parameter, or specify -operationMode RUNTIME
If you want to create a Business Process Archive Manager:	You cannot create it on the same deployment target as a Business Process Choreographer configuration. It must be configured separately on another deployment target as described in Use the bpeconfig.jacl script to configure Business Process Archive Manager.
Because the script will configure the Business Flow Manager and Human Task Manager:	Include the parameters required for the Business Flow Manager and Human Task Manager: -jmsBFMRunAsUser userID -jmsBFMRunAsPwd password -jmsHTMRunAsUser userID -jmsHTMRunAsPwd password For the administrator and monitor parameter pairs ending in Users and Groups you must specify either one or both parameters. {-adminUsers userList \| -adminGroups groupList} {-monitorUsers userList \| -monitorGroups groupList} The administration job user ID and password are optional. -adminJobUser userID -adminJobPwd password
If you do not want to use the default context roots for the APIs:	Include the optional parameters for context roots: -contextRootBFMREST contextRootBFMREST -contextRootBFMWS contextRootBFMWS -contextRootHTMREST contextRootHTMREST -contextRootHTMWS contextRootHTMWS
If you want to enable a simple mail transfer protocol (SMTP) server for sending escalation e-mails:	Include the parameter: -mailServerName mailServerName If the mail server requires authentication, also include the parameters: -mailPwd mailPassword -mailUser mailUserID
Because you can either have the script file create the database, or just have it generate the SQL script without running the scripts:	Include the option: -createDB { yes \| no } Select no because you will create the database separately after the configuration is complete. If you select yes, the script will fail because it cannot create a DB2 for z/OS database.
If you used the database design tool to create a database design file:	Include the parameter -bpcdbDesign databaseDesignFile The values specified in the database design file have precedence over any occurrences of the following parameters included on the command line: -dbJava, -dbName, -dbPwd, -dbSchema, -dbServerName, -dbServerPort, -dbTablespaceDir, -dbType, and-dbUser.
If you did not use the database design tool to create a database design file:	Include the parameter: -dbType databaseType Also provide the parameters required for your database type: -dbConnectionTarget DB2zOSSubSystem -dbHome databaseInstallPath -dbJava JDBCDriverPath -dbName databaseName -dbPwd databasePassword -dbSchema schemaQualifier -dbServerName databaseServerName -dbServerPort databaseServerPort -dbStorageGroup DB2zOSStorageGroup -dbTablespaceDir databaseTablespacePath -dbUser databaseUser When running the script in batch mode on a cluster, if your database requires the -dbJava parameter, specify the parameter for each node that hosts a cluster member in the following way: -dbJava. nodeName JDBCDriverPath_on_ nodeName
Specify the Business Process Choreographer message engine store settings:	Include the following parameters: -medbUser meDatabaseUser -medbPwd meDatabasePassword -mqCreateTables { yes \| no } -mqSchemaName mqSchemaName
If you do not want to configure Business Process Choreographer Explorer on the same deployment target as the Business Process Choreographer configuration:	Include the option: -createExplorer no You can run the clientconfig.jacl script later to create Business Process Choreographer Explorer configurations.
If you want to configure Business Process Choreographer Explorer on the same deployment target as the Business Process Choreographer configuration:	Include any of these optional parameters: -createExplorer yes -contextRootExplorer explorerContextRoot -explorerHost explorerURL -hostName explorerVirtualHostname -maxListEntries maximum -remoteCluster clusterName -remoteNode nodeName -remoteServer serverName -restAPIBFM restAPIURL^{* -restAPIHTM restAPIURL^} In a ND environment, -restAPIBFM and -restAPIHTM are required.