Using the bpeconfig.jacl script file to configure Business Process Choreographer

This sample script file configures all the resources that are required by Business Process Choreographer.

Purpose

This script can either be run interactively, or in batch mode. It configures a working business process container, and human task container without using the installation wizard or administrative console. It can create a local database, and the necessary messaging resources, and also configure the Business Process Choreographer Explorer. If the script is applied to an application server that is in a cluster, all servers in the cluster will be configured for using Business Process Choreographer.

Location

The bpeconfig.jacl script file is located in the Business Process Choreographer samples directory:

Restrictions

This sample script has the following restrictions:
In an ND environment or a cluster
To configure several application servers in an ND environment or a cluster, the bpeconfig.jacl script must run interactively. The script cannot be used to perform this type of configuration when run noninteractively.
Using an Oracle database
The bpeconfig.jacl script cannot create a local Oracle database. If you want to use a local Oracle database for Business Process Choreographer, you must create the database manually.

Runing the script in a stand-alone server environment

In a stand-alone server environment:
  • Include the -conntype NONE option only if the application server is not running.
  • If the server is running and global security is enabled, include the -username and -password options.
  • If you are not configuring the default profile, add the -profileName option.

Runing the script in an ND environment

In a Network Deployment environment:
  • Run the bpeconfig.jacl script on the deployment manager node.
  • Include the -conntype NONE option only if the deployment manager is not running.
  • If global security is enabled, include the -username and -password options.
  • If you are not configuring the default profile, add the -profileName option.

Configuring the business process container noninteractively

If you provide the necessary parameters on the command line, you will not be prompted for them. To configure Business Process Choreographer, enter one of the following commands:

On UNIX and Linux systems, if your current directory is install_root/ProcessChoreographer, enter the command:

../bin/wsadmin.sh -f bpeconfig.jacl parameters

On Windows systems, if your current directory is install_root\ProcessChoreographer, enter the command:

..\bin\wsadmin -f bpeconfig.jacl parameters
where parameters are as follows:
       -conntype NONE
       -user  userName
       -password  userPassword
       -profileName profileName
     {(-node nodeName -server serverName) | -cluster clusterName}
      {-adminBFMUsers userList   | -adminBFMGroups groupList}
      {-monitorBFMUsers userList | -monitorBFMGroups groupList}
       -jmsBFMRunAsUser userID
       -jmsBFMRunAsPwd password
      {-adminHTMUsers userList   | -adminHTMGroups groupList}
      {-monitorHTMUsers userList | -monitorHTMGroups groupList}
       -jmsHTMRunAsUser userID
       -jmsHTMRunAsPwd password
       -mailServerName mailServerName
       -mailUser mailUserID 
       -mailPwd mailPassword
       -hostName explorerVirtualHostname
       -explorerHost explorerURL
       -createDB { yes | no }
       -dbType databaseType
       -dbVersion DB2zOSversion
       -dbHome databaseInstallPath
       -dbJava JDBCDriverPath
       -dbName databaseName
       -dbUser databaseUser
       -dbPwd databasePassword
       -dbAdmin databaseAdministratorUserID
       -driverType JDBCDriverType
       -dbTablespaceDir databaseTablespacePath
       -dbServerName databaseServerName
       -dbServerPort databaseServerPort
       -dbStorageGroup DB2zOSStorageGroup
       -dbSubSystem DB2zOSSubSystem
       -dbSQLID DB2zOSSchemaQualifier
       -dbInstance InformixInstance
       -mqType JMSProviderType
       -createQM { yes | no }
       -qmNameGet getQueueManagerName
       -mqClusterName appServerClusterName
       -qmNamePut putQueueManagerName
       -mqHome MQInstallationDirectory
       -mqUser JMSProviderUserID
       -mqPwd JMSProviderPassword
       -mqSchemaName mqSchemaName
       -mqCreateTables  { true | false }
       -mqDataSource datasourceName
       -shell shell
Note: Some of the above parameters are optional, depending on the values provided for other parameters. The dependencies between parameters and the conditions that determine whether a parameter is optional or required is described for each parameter in the descriptions below. Any required parameters that are not specified on the command line are prompted for interactively.

Parameters

You can use the following parameters when invoking the script using wsadmin:
conntype NONE
This specifies that no administration connection is available. Only include this option if the application server (for stand-alone) or deployment manager (for ND) is not running.
user userName
If global security is enabled, you must provide a user ID for authentication.
password userPassword
If global security is enabled, you must provide the password for the user ID userName.
profileName profileName
Where profileName is the name of a user-defined profile. Specify this option if you are not configuring the default profile.
node nodeName
Where nodeName is the name of the node where Business Process Choreographer is to be configured. If you have only one node and exactly one server, this parameter is optional. Do not use this option if you use the cluster option to specify a cluster.
server serverName
Where serverName is the name of the server where Business Process Choreographer is to be configured. If you have only one node and exactly one server, this parameter is optional. Do not use this option if you use the cluster option to specify a cluster.
cluster clusterName
Where clusterName is the name of the cluster where Business Process Choreographer is to be configured. Do not specify this option in a stand-alone server environment, nor if you specify the node and server. This option cannot be used non-interactively.
adminBFMUsers userList
Where userList is the list of names of users, from the user registry, to which to map the BPESystemAdministrator Java 2 Enterprise Edition (J2EE) role. The separator character is the vertical line (|). This property is needed to install the business process container. This parameter has no default value. Either one or both of the adminBFMUsers or adminBFMGroups options must be set.
adminBFMGroups groupList
Where groupList is the list of names of groups, from the user registry, to which to map the BPESystemAdministrator J2EE role. The separator character is the vertical line (|). This property is needed to install the business process container. This parameter has no default value. Either one or both of the adminBFMUsers or adminBFMGroups options must be set.
monitorBFMUsers userList
Where userList is the list of names of users, from the user registry, to which to map the BPESystemMonitor J2EE role. The separator character is the vertical line (|). This property is needed to install the business process container. This parameter has no default value. Either or both monitorBFMUsers or monitorBFMGroups must be set.
monitorBFMGroups groupList
Where groupList is the list of names of groups, from the user registry, to which to map the BPESystemMonitor J2EE role. The separator character isthe vertical line (|). This property is needed to install the business process container. This parameter has no default value. Either or both monitorBFMUsers or monitorBFMGroups must be set.
jmsBFMRunAsUser userID
Where userID is the run-as user ID from the user registry for the business process container JMS API. This property is needed to install the business process container. This parameter has no default value. It must be set.
jmsBFMRunAsPwd password
Where password is the password for the business process container JMS API. This property is needed to install the business process container. This parameter has no default value. It must be set.
adminHTMUsers userList
Where userList is the list of names of users, from the user registry, to which to map the TaskSystemAdministrator Java 2 Enterprise Edition (J2EE) role. The separator character is the vertical line (|). This property is needed to install the task container. This parameter has no default value. Either one or both of the adminHTMUsers or adminHTMGroups options must be set.
adminHTMGroups groupList
Where groupList is the list of names of groups, from the user registry, to which to map the TaskSystemAdministrator J2EE role. The separator character is the vertical line (|). This property is needed to install the task container. This parameter has no default value. Either one or both of the adminHTMUsers or adminHTMGroups options must be set.
monitorHTMUsers userList
Where userList is the list of names of users, from the user registry, to which to map the TaskSystemMonitor J2EE role. The separator character is the vertical line (|). This property is needed to install the task container. This parameter has no default value. Either or both monitorHTMUsers or monitorHTMGroups must be set.
monitorHTMGroups groupList
Where groupList is the list of names of groups, from the user registry, to which to map the TaskSystemMonitor J2EE role. The separator character is the vertical line (|). This property is needed to install the task container. This parameter has no default value. Either or both monitorHTMUsers or monitorHTMGroups must be set.
jmsHTMRunAsUser userID
Where userID is the run-as user ID from the user registry for the human task container JMS API. This property is needed to install the human task container. This parameter has no default value. It must be set.
jmsHTMRunAsPwd password
Where password is the password for the human task container JMS API. This property is needed to install the human task container. This parameter has no default value. It must be set.
mailServerName mailServerName
Where mailServerName is the host name of the mail server to be used by the human task manager to send notification mails. It is needed when configuring the mail session. If this parameter is not set, the mail session configuration will be skipped. The default value is the fully qualified host name of the local host.
mailUser mailUserID
Where mailUserID is the user ID to access the mail server. It is needed to create the mail session for the human task manager to send notification mails. The default value is empty, which is only appropriate if no authentication is required.
mailPwd mailPassword
Where mailPassword is the password to access the mail server. It is needed to create the mail session for the human task manager to send notification mails.
hostName explorerVirtualHostname
Where explorerVirtualHostname is the virtual host where the Business Process Choreographer Explorer will run. The default value is default_host.
explorerHost explorerURL
Where explorerURL is the URL of the Business Process Choreographer Explorer. If this parameter is not specified for a non-cluster environments, a default value is computed, for example, http://localhost:9080. The value of this parameter is used for the EscalationMail.ClientDetailURL custom property of the human task manager.
createDB { yes | no }
Possible values are yes or no. If set to yes, the script will create the database. For z/OS databases and Oracle, this script cannot create the database, it can only create the table spaces and tables. For other database types, the default value is yes.
dbType databaseType
Where databaseType is the database type. This is needed for installing the business process container, for creating the database or database tables, and for creating the data source. There is no default value. Possible values are:
  • Cloudscape
  • DB2
  • zOS-DB2
  • MSSQL
  • Oracle
dbVersion DB2zOSversion
Where DB2zOSversion is either the value 7 or 8. This parameter is only required when the database type is DB2 for z/OS. It has no default value.
dbHome databaseInstallPath
Where databaseInstallPath is the installation directory of the database system. It is used to create the database or the database tables, and for creating the data source. The default value, and requirements depends on the database and on the platform:
For DB2:
  • On Windows platforms, the default is current_drive\Program Files\IBM\SQLLIB where current_drive is the current drive letter.
  • On Solaris platforms, the default is /export/home/${dbUser}/sqllib.
  • On other platforms, the default is /home/${dbUser}/sqllib.
The directories ${dbHome}/bnd and ${dbHome}/bin must exist.
For Oracle:
  • On Windows platforms, the default is c:\oracle\ora90.
  • On Solaris and HP-UX platforms, the default is /opt/oracle.
  • On other platforms, the default is /usr/oracle.
The file ${dbHome}/jdbc/lib/odbc14.jar must exist.
For Sybase:
  • On Windows platforms, the default is current_drive\Program Files\Sybase where current_drive is the current drive letter.
  • On Solaris and HP-UX platforms, the default is /opt/sybase.
  • On other platforms, the default is /usr/sybase.
The file ${dbHome}/jConnect-*/classes/jconn2.jar must exist.
dbJava JDBCDriverPath
Where JDBCDriverPath is the directory where the JDBC driver is located. This parameter is only required for the following combinations of database and driver types:
  • MSSQL DataSource with the DataDirect driver type. There is no default value.
  • DB2 or DB2 for z/OS, with a type 4 driver. The default value is ${dbHome}/java.
dbName databaseName
Where databaseName is the name of the Business Process Choreographer database. It is used to create the database or the database tables, and for creating the data source. For Oracle, this is the TNS. The default value is BPEDB.
dbUser databaseUser
Where databaseUser is the user ID to access the database. It is used to create the database tables and the data source. The default value depends on the database and platform:
  • For DB2 on Windows platforms: "db2admin"
  • For DB2 on other platforms: "db2inst1"
  • For Oracle: "system"
  • For Sybase on Windows: <currently logged on user>
  • For Sybase on other platforms: "sa"
  • For MSSQL: <currently logged on user>
dbPwd databasePassword
Where databasePassword is the password for the user ID databaseUser.
dbAdmin databaseAdministratorUserID
Where databaseAdministratorUserID is the user ID of the database administrator. It is only required when creating the database and database tables for the following database types on Linux and UNIX platforms:
  • For DB2 for z/OS, the default is db2inst1.
  • For Oracle, the default value is oracle.
  • For Sybase, the default value is sybase.
driverType JDBCDriverType
Where JDBCDriverType is the type of JDBC driver. It is used to create the data source.
  • For DB2, possible values are Universal or CLI.
  • For Oracle, possible values are oci8 or thin. It is also used for installing the business process container.
  • For MSSQL, possible values are Embedded or DataDirect.
dbTablespaceDir databaseTablespacePath
Where databaseTablespacePath is the directory where the database table spaces are created. It is used to create the database and database tables. This parameter is only required for the following database types:
  • For Oracle, there is no default value. You must provide a value.
  • For DB2, the default value is empty, which means that no table spaces are created.
dbServerName databaseServerName
Where databaseServerName is the host name server that hosts the database for Business Process Choreographer. database. It is used to create the data source. For Sybase it is also used to create the database.
  • For DB2, the default value is empty.For DB2 UDB, this parameter is optional, and if it is not specified, a type 2 JDBC driver will be configured for DB2, otherwise a type 4 JDBC provider will be configured.
  • For all other database types, the default value is the fully qualified host name of the local host.
dbServerPort databaseServerPort
Where databaseServerPort is the TCP/IP port for the database server for Business Process Choreographer. This parameter is required if dbServerName is specified.
  • For DB2, the default value is 50000.
  • For Oracle with the driver type thin, the default value is 1521.
  • For Sybase, the default value is 4100.
  • For MSSQL, the default value is 1433.
dbStorageGroup DB2zOSStorageGroup
Where DB2zOSStorageGroup is the storage group used to create the Business Process Choreographer database table . This parameter is only required for DB2 on z/OS. There is no default value, and must not be empty.
dbSubSystem DB2zOSSubSystem
Where DB2zOSSubSystem is the DB2 sub system used to create the Business Process Choreographer database table and the data source. This parameter is only required for DB2 on z/OS. The default value is BPEDB.
dbSQLID DB2zOSSchemaQualifier
Where DB2zOSSchemaQualifier is the schema qualifier used to create the database tables. This parameter is only required for DB2 on z/OS. There is no default value. The value can be empty. Only specify a value when using the Universal JDBC driver type.
dbInstance InformixInstance
Where InformixInstance is the instance name for a Business Process Choreographer Informix database. The default value is ids1.
mqType JMSProviderType
Where JMSProviderType is the type of Java Message Service (JMS) provider to use for Business Process Choreographer. It is used to create the queue manager and the queues, the listener ports or ActivationSpecs, and the queue connection factories.

Where JMSProviderType is one of the following values:

WPM
For default messaging (WebSphere Platform Messaging). This option is always available.
MQSeries
For WebSphere MQ. This option requires that the product WebSphere MQ is installed.
createQM { yes | no})
Controls whether the script creates a local WebSphere MQ queue manager. This option only has an effect if the parameter mqType has the value MQSeries. The default value for this parameter is yes. Use the value no if you do not want the script to create the WebSphere MQ queue manager, for example, if you want to create the queue manager on a different server to the one where you are running the script.
qmNameGet getQueueManagerName
Where getQueueManagerName is the name of the queue manager for GET requests. It is used to create the queue manager and the queues, and to create the listener ports and the queue connection factories. It must not contain the - character. The default value for getQueueManagerName is BPC_nodeName_serverName. This option only has an effect if the parameter mqType has the value MQSeries.
mqClusterName appServerClusterName
Where appServerClusterName is the name of the WebSphere Application Server cluster where the default JMS provider's message engines are to be created. This has nothing to do with a WebSphere MQ cluster. This option is only used when configuring Business Process Choreographer in a cluster and the mqType option is set to WPM.
qmNamePut putQueueManagerName
Where putQueueManagerName is the queue manager name for PUT requests. It is used only when the mqClusterName parameter has been set. It is used to create the queue manager and the queues, and to create the listener ports and the queue connection factories. It must not contain the - character, and it must not be the same as the queue manager name specified for the qmNameGet parameter. The default value for putQueueManagerName is BPCC_nodeName_serverName.
mqHome MQInstallationDirectory
Where MQInstallationDirectory is the installation directory of WebSphere MQ. This is used to create the queue manager and the queues (Windows systems only) and for creating the listener ports and the queue connection factories. If the WebSphere variable MQ_INSTALL_ROOT is set, its value is used, and is not modified. This option only has an effect if the parameter mqType has the value MQSeries.

If MQ_INSTALL_ROOT is not set, the default value used for MQInstallationDirectory depends on the platform:

Windows systems:
current_drive\Program Files\IBM\WebSphere MQ
AIX:
/usr/mqm
Solaris and HP-UX:
/opt/mqm
mqUser JMSProviderUserID
Where JMSProviderUserID is the user ID to access the JMS provider.
  • If mqType has the value WPM, this parameter is used to create the ActivationSpecs and the connection factories; the default value is the currently logged on user.
  • If mqType has the value MQSeries, this parameter is used on non-Windows platforms to create the queue manager and the queues. The default value for JMSProviderUserID depends on the platform:
    Windows systems:
    currently_logged-on_user
    Linux and UNIX systems
    mqm
mqPwd JMSProviderPassword
Where JMSProviderPassword is the password for the user ID provided for mqUser. This parameter has no default value.
mqSchemaName mqSchemaName
Where mqSchemaName is the name of the database schema for the default JMS provider's messaging engine. The default value is BPEME. This option is only used when configuring Business Process Choreographer in a cluster and the mqType option is set to WPM.
mqCreateTables { true | false})
This Boolean parameter controls whether the default JMS provider automatically creates its tables in the message engine database upon the first connection. The default value is true. This option is only used when configuring Business Process Choreographer in a cluster and the mqType option is set to WPM.
mqDataSource datasourceName
Where datasourceName is the JNDI name of the data source to be used by the default JMS provider's message engine. This must be a cluster-level data source in the WebSphere cluster identified by mqClusterName. The underlying database for the default JMS provider must be created manually. This option is only used when configuring Business Process Choreographer in a cluster and the mqType option is set to WPM.
shell shell
On UNIX and Linux platforms, this parameter determines the shell that is used to run external commands. The default value is /bin/sh.

Running the configuration script interactively

This example, illustrates running the bpeconfig.jacl script to install and configure a business process container that uses an existing DB2 database, a human task container, and a Business Process Choreographer Explorer.
  1. On the server, or for ND, on the deployment manager, start the script:
    • On UNIX® and Linux® systems, enter the command:
      install_root/bin/wsadmin.sh  
             -f install_root/ProcessChoreographer/sample/bpeconfig.jacl 
       ( [-username userName][-password password]|[-conntype NONE])
         [-profileName profileName]
    • On Windows® systems, enter the command:
      install_root\bin\wsadmin.bat  
             -f install_root\ProcessChoreographer\sample\bpeconfig.jacl
       ( [-username userName][-password password]|[-conntype NONE])
         [-profileName profileName]
  2. Interactively enter responses to the questions that are displayed:
    1. In an ND environment, you will be offered a cluster to configure in. If it is not the correct cluster, enter No to be offered the next cluster. If it is the correct cluster, enter Yes.
    2. For the question Install the business process container?, enter Yes.
    3. For the question User(s) to add to role BPESystemAdministrator, enter the user IDs for the users who will perform the role of business process administrator.
    4. For the question Group(s) to add to role BPESystemAdministrator, enter the groups from the domain user registry that are mapped onto the role of business process administrator.
    5. For the question User(s) to add to role BPESystemMonitor, enter the user IDs for the users who will perform the role of business process monitor.
    6. For the question Group(s) to add to role BPESystemMonitor, enter the groups from the domain user registry that are mapped onto the role of business process monitor.
    7. If you get the question Use WebSphere default messaging or WebSphere MQ, enter one of the two displayed options.
    8. For the question Run-as UserId for role JMSAPIUser, enter the run-as user ID that will be used for the JMSAPIUser role.
    9. Enter the password for the run-as user ID.
    10. For the question Use a DB2, an Informix, an Oracle, or an SQL Server database [DB2/Informix/Oracle/MSSQL]?, for this example, enter DB2. Selecting a different database results in other database-specific questions.
    11. For the question Use WebSphere default messaging or WebSphere MQ [WPM/MQSeries]?, select the JMS provider that you want to use.
    12. For the question Create the DataSource for the Process Choreographer database?, enter Yes.
    13. Enter the database name.
    14. For the question Universal or CLI?, enter the type of the JDBC driver.
    15. For the question DB2 User ID, enter the user ID used to create the database tables and schema.
    16. For the question Database server name (may be empty, set to use the type 4 driver), enter the name of the server that hosts the database.
    17. For the question Database server port, enter the database server port, for example, 50000.
    18. For the question Create the Process Choreographer database?, enter No if the database already exists, otherwise, enter Yes.
    19. For the question DB2 tablespace directory (may be empty) enter the directory for the table space, or leave it empty.
    20. For the question Create the ActivationSpecs for the business flow manager?, enter Yes or No.
    21. If you get the question User ID for access to default messaging, enter the user ID to use to access the default JMS provider.
    22. If you get the question Name of the message engine cluster, enter the name of the message engine cluster.
    23. If you get the question Name of the message engine database schema, enter the name of the message engine database schema.
    24. If you get the question Automatically create the message engine database tables [true/false]?, enter true to automatically create the message engine database tables, otherwise enter false.
    25. If you get the question Message engine datasource JNDI name, enter the JNDI name of the message engine data source.
    26. For the question Install the task container?, enter Yes.
    27. For the question User(s) to add to role TaskSystemAdministrator, enter the user IDs for the users who will perform the role of task administrator.
    28. For the question Group(s) to add to role TaskSystemAdministrator, enter the groups from the domain user registry that are mapped onto the role of task administrator.
    29. For the question User(s) to add to role TaskSystemMonitor, enter the user IDs for the users who will perform the role of task monitor.
    30. For the question Run-as UserID for role EscalationUser, enter the run-as user ID for the role of escalation user.
    31. For the question Create the mail notification session for the human task manager?, enter No if you do not want to create the mail notification session for the human task manager. Otherwise, enter Yes, and specify the mail transport host and user ID.
    32. For the question Create the ActivationSpecs for the human task manager?, enter Yes to create J2EE ActivationSpecs for the human task manager Message Driven Bean (MDB), otherwise enter No.
    33. If you get the question Configure in cluster 'MECluster' [Yes/no]?, enter Yes to configure in the specified cluster, otherwise, enter No.
    34. If you get the question Add JDBC provider permissions to server.policy [Yes/no]?, enter Yes to automatically add the permissions for the JDBC provider to the server.policy file, otherwise, enter No.
    35. For the question Install the BPC Explorer?, enter Yes to install the Business Process Choreographer Explorer, then for the Virtual host for the BPC explorer, enter the name of the virtual host for the BPC Explorer, for example, default_host, then for the question Precompile JSPs?, enter Yes if you want Java Server Pages (JSPs) to be precompiled, otherwise enter No .
    36. For the question Create aliases for your_server in host your_host?, enter Yes to create aliases for your server in the your virtual host, otherwise enter No.
    37. For the question Enable global security using the Local OS user registry?, enter Yes to enable global security using the local operating system user registry, otherwise, enter No.
    38. For the question Server user ID, enter the server user ID.
    39. For the question Enforce Java 2 security?, enter Yes to enforce Java 2 security, otherwise, enter No.
    40. For the question Set 'com.ibm.SOAP.loginUserid' in soap.client.props?, enter Yes to set the login user ID in the SOAP client properties, otherwise, enter No.
    41. For the question Delete the temporary directory?, enter Yes to delete the temporary directory specified, otherwise, enter No.
  3. In case of problems, check the log files.

Log files

If you have problems creating the configuration using the bpeconfig.jacl script file, check the following log files: Both files can be found in the logs directory for your profile:

Terms of use |

Last updated: Tue Feb 21 17:31:25 2006

(c) Copyright IBM Corporation 2005.
This information center is powered by Eclipse technology (http://www.eclipse.org)