IBM BPM, V8.0.1, All platforms > Install IBM BPM > IBM BPM Advanced: Process Server > Install IBM BPM Advanced: Process Server > On Windows > Network deployment environment > Configure profiles and create an ND environment > Create an ND environment > Use the administrative console > 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 an ND environment, the dmgr) is not running: Include the wsadmin option: -conntype NONEDo 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 userPasswordIf you are not using the default profile: Include the wsadmin parameter: -profileName profileNameIf 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 ASKAny 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_DEFAULTIf 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_MISSINGUse 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 responseFileFor 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 clusterNameor both parameters:-node nodeName -server serverNameTo 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 passwordFor 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 passwordIf 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 contextRootHTMWSIf you want to enable a simple mail transfer protocol (SMTP) server for sending escalation e-mails: Include the parameter: -mailServerName mailServerNameIf the mail server requires authentication, also include the parameters:
-mailPwd mailPassword -mailUser mailUserIDBecause 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 select yes, the bpeconfig.jacl script will generate and run an SQL file to create the database objects in the default table space, which is not suitable for a high-performance system. In this case also plan to stop the server and use the -conntype NONE option.
If you select no, and the database does not already exist, then you or your database administrator must run the generated SQL script. For a high-performance system, specify no, because you will need to customize the SQL script before running it. Also specify no if you do not have the authority to create the database yourself, so that you can provide the SQL script to your database administrator to customize and run.
You must also specify no if you are using a database which has restricted support.
The script cannot create a DB2 for z/OS database.
The script cannot create the following types of databases:
- DB2 for z/OS
- Oracle
- A remote Microsoft SQL Server
If you select yes and you are running the script in connected mode, creating the database or schema can fail if it takes longer than the a default timeout of three minutes.
The bpeconfig.jacl script cannot create an Oracle schema user. You must create all necessary schema users manually before running the bpeconfig.jacl script.
If you used the database design tool to create a database design file: Include the parameter
-bpcdbDesign databaseDesignFileThe 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 databaseTypeAlso 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 -dbVersion version -dbWinAuth { no | yes }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_ nodeNameIf you are using one of the following databases, bpeconfig.jacl can also create the database instance:
- A local DB2 for Linux, UNIX, or Windows
Specify the Business Process Choreographer message engine store settings: Include the following parameters: -medbUser meDatabaseUser -medbPwd meDatabasePassword -mqCreateTables { yes | no } -mqSchemaName mqSchemaNameIf 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 noYou 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 an ND environment, -restAPIBFM and -restAPIHTM are required.
- If you selected the Business Process Choreographer sample configuration option when you created a default profile, the Business Flow Manager, Human Task Manager, and Business Process Choreographer Explorer are already configured.
You can check if they are configured, by looking in the administrative console for enterprise applications with names that start with:
- BPCExplorer
- BPEContainer
- HTM_PredefinedTasksMsg
- HTM_PredefinedTasks
- TaskContainer
The sample configuration is not suitable for a production system. Because you can only have one Business Process Choreographer or Business Process Choreographer Archive Manager configuration on a deployment target, you must remove the sample configuration, as described in Advanced only: Removing the Business Process Choreographer configuration before you can create a new configuration.
- If you have an ND environment, use the administrative console to make sure that the Service Component Architecture is configured:
- If you want to configure Business Process Choreographer on a server, click Servers > Server Types > WebSphere application servers > server_name, then in the Business Integration section, click Service Component Architecture.
- If you want to configure Business Process Choreographer on a cluster, click Servers > Clusters > WebSphere application server clusters > cluster_name, then in the Business Integration section, click Service Component Architecture.
- If it is not enabled, select Support the Service Component Architecture components, complete all the configuration settings as appropriate, then click Apply and Save.
- If you are using WebSphere Platform Messaging (WPM) as the JMS provider, then create the database for the data store for the Business Process Choreographer messaging engine:
- If you want to use the -mqCreateTables yes option to have the messaging engine create the default schema the first time that it uses the database, perform the following:
- If the database does not already exist, create it.
- Grant the database user ID the rights to create tables and views in the schema that you planned to use.
- Otherwise, if you will use the -mqCreateTables no option, create the tables before the default messaging provider tries to access the database. You can use the database design tool to generate a DDL file that can be used to create the tables.
- To use the option -createDB yes to run the generated SQL scripts to create the database schema:
- If you are using one of the following databases:
- DB2 for z/OS
- Oracle
- a remote Microsoft SQL Server
and your database does not already exist, create an empty database manually according to the documentation for your database.
For example, for Oracle, make sure that all necessary schema users exist, and that the schema name matches the user ID used to access the messaging engine database.
- Verify that the database client, for example db2.exe, is on the path for the scripting client.
- Verify that the application server is stopped.
- Invoke the bpeconfig.jacl script file, either in batch mode providing the options and configuration parameters that you planned, or in interactive mode.
For example:
To configure Business Process Choreographer on a stand-alone server on a Windows platform, using a DB2 database, the batch mode command might be like the following:
wsadmin -conntype none -f bpeconfig.jacl -adminGroups bpcadmins -createDB no -dbJava d:\\programs\\IBM\\SQLLIB\\java -dbName BPEDB -dbSchema WPRBE00 -dbServerName db2host.acme.com -dbTablespaceDir d:\\DB2\\tablespacedir -dbType DB2 -dbUser db2user -dbPwd secret -explorerHost http://wpshost.acme.com:80/bpc -jmsBFMRunAsUser jmsuser -jmsBFMRunAsPwd secret -jmsHTMRunAsUser escalationuser -jmsHTMRunAsPwd secret -mailServerName smtphost.acme.com -mailUser {} -monitorGroups bpcmonitors -mqCreateTables yes -mqSchemaName WPRBM00 -mqUser sibuser -mqPwd secret -operationMode RUNTIME -promptMode FAIL_IF_MISSING -restAPIBFM http://wpshost.acme.com:80/rest/bpm/bfm -restAPIHTM http://wpshost.acme.com:80/rest/bpm/htmFor other platforms, the file system paths would be different. For details about the script file, refer to bpeconfig.jacl script file.- If you either used the -createDB no option to defer that creation of the database, or if the bpeconfig.jacl script failed create the database, you or your database administrator should perform the actions described in Use a generated script to create the database schema for Business Process Choreographer before you activate Business Process Choreographer in step 8.
If your database is local, and it will exist by the time you activate Business Process Choreographer in step 8, and you do not perform the actions described in Use a generated script to create the database schema for Business Process Choreographer, the default schema will be created the first time that Business Process Choreographer accesses the database.
- 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.
- If you want to configure a remote Business Process Choreographer client that uses the Process Server client, perform, Configure a remote client application.
Results
Business Process Choreographer is configured.
Configure Business Process Choreographer
Related tasks:
Troubleshooting the Business Process Choreographer configuration