Operations

After installing IBPM and building solutions to be deployed upon it, there will come a time when the environment must be managed for operations.

Configuration Files

IBPM uses some configuration files that are read during the Process Server and Process Center startup. These files contain XML content and are designed to be readable and editable in a text or XML editor. Only an educated runtime administrator should consider editing these files.

The files are located in the folder called:

<Install>/profiles/<profileName>/config/cells/<cellName>/nodes/<nodeName>/server/<serverName>/[process-center|process-server]/config/system

The names of the files are:

00Static.xml
50AppServer.xml
60Database.xml
80EventManager.xml
98Database.xml
99Local.xml
99Sharepoint.xml

The idea behind these files is that they contain settings for the operation of the server. All the files are read in numeric order based on the numerics at the start of the file name. It is allowable for one file to override the settings made in a previous file. Think of it as all the files being merged together in the numeric order and the result being a single XML document with replacements for previous entries.

These files are not designed to be edited by the deployment administrator. They can be examined to see what values are to be in effect. If changes are desired, it is strongly recommended to place those changes in the file called:

<Install>/<...path...>/100Custom.xml

This is assured to be the last file read. Changes in this file will override any of the settings in the other files.

Any changes made to files are not reflected until the servers are restarted.

When changes are made, it is extremely good practice to watch the logs of a server startup. If any problems are found in the parameter settings, that is where they will show up and should be corrected before continuing.

Unfortunately, despite the wealth of over-ridable entries in these files, very little published documentation exists on them so unless explicitly directed to make changes by IBM staff, these are probably best left alone. If changes are made, make sure that logs of what was changed, when, why and most importantly, any source emails or documentation from IBM on those changes should be recorded.

See also:

Networking

The Process Center and Process Server products run on top of WAS. When running the products on a laptop, it is not uncommon to change networking characteristics. It has been found that if the network IP addresses change from under the server, bad things can happen. A solution to this is to create a localhost entry in the hosts file. On windows, this can be found in C:\Windows\System32\drivers\etc. It is also a good idea to determine your own machine's hostname through the hostname command and create an alias for that to be 127.0.0.1.

WAS Server

When IBPM is installed, a WAS profile is created that installs at <Install>/AppServer. This AppServer can be registered as a Windows service. This shows up as an entry called:

IBM WebSphere Application Server V8.0 – ProcessCenter01

Stopping the server

A WAS server can be stopped by running the command stopServer <serverName>. When run, a dialog appears prompting for the userid/password to be used to allow shut down. For convenience during development, this pair of parameters can be scripted with the "-user <userName> -password <password>" options. When a server is defined on Windows, a stop entry is added to the menu of available commands.

From 8.5 onwards with the arrival of the mandatory network deployment model, we can stop and start the servers through the nodeagent.

Windows Services

WAS can be configured as a Windows Service to allow it to start at machine boot time. The service can be registered by the WAS supplied command called "WASService".

Port Numbers

TCP/IP port numbers are the endpoints for TCP/IP communications. When combined with hostname or IP address, the port number provides the unique endpoint for a browser or service request. The port numbers for the servers:

  • SOAP – Look in the console for a line which reads: JMXSoapAdapte A ADMC0013I: The SOAP connector is available at port nnnn

The port number for SOAP is listed on that line.

See also:

WAS Admin Console

WAS has an administrative console known as the "Integrated Solutions Console" or ISC. It can be accessed from:

https://localhost:9044/ibm/console/logon.jsp

The default administrative userid is admin/admin.

JDBC Resources

A set of predefined JDBC resources are created when IBPM is installed.

JNDI name Description
jdbc/TeamWorksDB Used by the Process Center to access the repository of artifacts for the common shared model.
jdbc/PerformanceDB Used by the Performance Data Warehouse to hold performance information.
jdbc/ProcessDB Used by Process Servers to store runtime information used during the execution of processes.

JNDI Resources

We can examine the JNDI namespace using the command "dumpNameSpace.sh". My experiments seem to show that we should target the specific cluster member under examination. For example:

$ dumpNameSpace.sh -host <hostname> -port <port>

My server's port was 9810.

WAS Security

Here is an un-tested recipe for programmatically creating WAS based users:

com.ibm.websphere.wim.Service service =
 new com.ibm.websphere.wim.client.LocalServiceProvider(null);
 commonj.sdo.DataObject root = com.ibm.websphere.wim.util.SDOHelper.createRootDataObject();
 commonj.sdo.DataObject entity = com.ibm.websphere.wim.util.SDOHelper.createEntityDataObject(root, null,DO\_PERSON\_ACCOUNT);
 entity.set("uid", "kolban");
 entity.set("password", "mypassword");
 commonj.sdo.DataObject result = service.create(root);

The wsadmin command

WAS provides a command called "wsadmin" that is the primary tool for changing WAS configuration settings. It can be invoked from the command line interactively or by being passed a file of command to execute. It supports a variety of scripting languages including JACL and Jython but Jython is the one that is recommended.

See also:

Java programming for admin commands

There are times when we might wish to perform WAS admin commands from within a Java environment. WAS provides a framework to achieve this.

First there is the object known as the CommandMgr. From the CommandMgr, we create an instance of an AdminCommand.

If we want to know what commands are available, the cmdMgr.listAllCommands() will return a collection.

Once we know which command we want to execute, we can create an AdminCommand instance with:

AdminCommand adminCommand = cmdMgr.createCommand("CommandName");

From an adminCommand, we can ask what the parameters are for it. We can get these through:

List parameters = adminCommand.listParameterName();

We can then set a parameter with:

adminCommand.setParameter("Name", value);

Next we can execute the command with:

adminCommand.execute();

And finally retrieve the results with:

Collection results = adminCommand.getResult();

See also:

Java Client programming for admin commands

WAS provides client APIs for performing distributed admin commands. The core of these is a class called AdminClient which is created from an AdminClientFactory. The AdminClientFactory has a static method called createAdminClient() which takes a Java Properties object. From these properties the AdminClientFactory creates an instance of AdminClient ready for use.

The properties passed to AdminClientFactory include:

Property Name Description
AdminClient.CONNECTOR_TYPE How to connect. Choices include CONNECTOR_TYPE_SOAP CONNECTOR_TYPE_RMI CONNECTOR_TYPE_JSR160RMI CONNECTOR_TYPE_JMS CONNECTOR_TYPE_IPC
AdminClient.CONNECTOR_HOST The host to connect (eg. "localhost")
AdminClient.CONNECTOR_PORT The port to connect (eg. "8879" for SOAP, "2809" for RMI, "9809" for Dmgr RMI)
AdminClient.USERNAME The userid to connect
AdminClient.PASSWORD The password to connect
com.ibm.CORBA.ConfigURL The path to sas.client.props
AdminClient.CONNECTOR_SOAP_CONFIG (com.ibm.SOAP.ConfigURL)
com.ibm.SLL.ConfigURL The path to ssl.client.props
AdminClient.CACHE_DISABLED Set to "true" for server side calls.

When using the Oracle JRE, more setup is required:

  • Add the JAR com.ibm.ws.admin.client_8.5.0.jar to the classpath
  • Add the JAR com.ibm.ws_orb_8.5.0.jar to the classpath
  • Set the following properties when creating an AdminClient:
props.setProperty(AdminClient.CONNECTOR_HOST, "localhost");
props.setProperty(AdminClient.CONNECTOR_PORT, "8879"); // Dmgr
props.setProperty(AdminClient.CONNECTOR_PORT, "8881"); // Process Center
props.setProperty(AdminClient.CONNECTOR_TYPE, AdminClient.CONNECTOR_TYPE_SOAP);
props.setProperty(AdminClient.CONNECTOR_SECURITY_ENABLED, "true");
props.setProperty(AdminClient.USERNAME, "cadmin");
props.setProperty(AdminClient.PASSWORD, "password");
props.setProperty(AdminClient.CACHE_DISABLED, "false");
props.setProperty("javax.net.ssl.trustStore", "C:/Projects/JMX/DummyClientTrustFile.jks");
props.setProperty("javax.net.ssl.keyStore", "C:/Projects/JMX/DummyClientKeyFile.jks");
props.setProperty("javax.net.ssl.trustStorePassword", "WebAS");
props.setProperty("javax.net.ssl.keyStorePassword", "WebAS");
  • Export the certificate
    • Go to WAS admin console Security > SSL certificate and key management > Key stores and certificates > CellDefaultKeyStore > Personal certificates
    • Extract the default certificate

  • Run the keystore tool to import the certificate into the keystore named in the properties of AdminClient

keytool -importcert -keystore DummyClientTrustFile.jks -alias myserver -file myserver.cer -storepass WebAS

Here is an example Java fragment which acrhives a process app:

try {
	java.util.Properties props = new java.util.Properties();
	props.setProperty(AdminClient.CONNECTOR_TYPE, AdminClient.CONNECTOR_TYPE_SOAP);
	props.setProperty(AdminClient.CONNECTOR_HOST, "localhost");
	props.setProperty(AdminClient.CONNECTOR_PORT, "8880");
	props.setProperty(AdminClient.CONNECTOR_SECURITY_ENABLED, "true");
	props.setProperty(AdminClient.USERNAME, "cadmin");
	props.setProperty(AdminClient.PASSWORD, "password");	
	props.setProperty("javax.net.ssl.trustStore", "/home/kolban/BPM/Projects/WASAdmin/PlainWASAdminClient/data/truststore.jks");
	AdminClient client = AdminClientFactory.createAdminClient(props);
	CommandMgr commandMgr = CommandMgr.getCommandMgr(client);
	AdminCommand cmd = commandMgr.createCommand("BPMArchiveProcessApplication");
	cmd.setParameter("containerAcronym", "YC_0PGS");
	cmd.execute();
	CommandResult result = cmd.getCommandResult();
	System.out.println("Result: " + result);
	System.out.println("All done!");
} catch (Exception e) {
	e.printStackTrace();
}

BPM AdminCommands

  • BPMListServers – The list of servers known to a Process Center

JMX Programming

See also:

Changing Passwords

Session timeouts

When a BPM user is using one of the web screens supplied by the product, the user may 'timeout" meaning that their credentials expire. We can over-ride the default settings for the timeout interval as follows:

Open up the WAS admin console.

Visit Applications > Application Types > WebSphere enterprise applications

For each of the following applications, drill in and modify their "Sessions" attributes:

  • IBM_BPM_Portal_
  • IBM_BPM_Teamworks_
  • IBM_BPM_WebAPI_
  • IBM_BPM_WebPD_

Operational Databases

IBPM makes use of a number of databases that host data for its own operation. Because IBPM is an IBM product, it is recommended to use DB2 as the database management system. More IBMers are going to be familiar with DB2 than alternative database systems. An instance of DB2 is provided with IBPM to provide the necessary Database environment. These databases used for IBPM operations should not be used for hosting application data. It is strongly recommended to separate operational data from application oriented data.

Process Server Database

The Process Server Database is used to manage the state of in-flight processes and tasks. Although there is no documentation on the tables contained within this database nor should any assumptions be made about its content, it can be instructive to examine the content. It is strongly advised never to change the content of tables in this database unless explicitly instructed to do so by IBM.

Performance Data Warehouse Database

The Performance Data Warehouse database tracks information relating to the performance of the processes run by the Process Server. This includes historical data kept over time about the outcomes of completed processes.

Defining custom databases

Within an IBPM solution, there are times when we will want to access data contained in application databases. These can be accessed through SQL statements within the solution. Before we can use these databases, they must first be defined to the IBPM environment as WAS JDBC definitions. The instructions for achieving this are well documented in the WAS documentation and there are additional TechNotes and DeveloperWorks articles available for reference. A summary is reproduced here.

JDBC resources are defined in the WAS runtime. The WAS Admin Console can be used to manually define such definitions. In addition, scripting can be used to create the same definitions if desired.

To launch the WAS Admin Console, open a browser to:

https://localhost:9044/ibm/console/logon.jsp

Login as admin/admin or another WAS administrative userid.

First we must create a JDBC provider entry that points to our new Database server.

Navigate to the JDBC providers section found at Resources → JDBC → JDBC providers

Click the New button to begin a new definition.

Select the definitions appropriate to the database type being defined. The following shows those for DB2.

Paths to the local driver files for the database server may need to be entered:

Now that a JDBC provider has been defined, we can now create a JDBC Data source definition which names a Database hosted by that kind of server.

Navigate to the JDBC Data sources section found at Resources → JDBC → Data sources

Click the New button to begin a new resource definition.

See also:

SI Bus Resources

With WAS being an implementation of Java EE, it must provide an implementation of Java Messaging Service (JMS). WAS implements JMS through a native messaging and queuing provider called System Integration Bus (SI Bus). IBPM creates two instances of SI Buses. These are:

|| |Name|Type| |EventMgrControlTopicDestination|Topic| |TWClientTopicDestination|Topic| |cacheTopicDestination|Topic| |eventerrorqueueDestination|Queue| |eventmgrOpTopicDestination|Topic| |eventqueueDestination|Queue|

JMS Resources are also created

|| |jms/eventqueue|| |jms/eventerrorqueue|| |jms/ViewManagerQueue|| |jms/RepresentationManagerQueue|| |jms/PostLoadCalculcationManagerQueue|| |jms/DataDefLoaderQueue|| |jms/DataDefLoaderErrorQueue||

See also:

Cleaning/removing completed processes

When a BPD instance has completed, the record of that BPD instance is not deleted from the databases. As such, over time, the databases will become full of historical information.

A wsadmin command called BPMProcessInstanceCleanup is provided that will clean/remove data associated with previously ended process instances. The syntax for this command is:

-containerAcronym <acronym> - The acronym for the Process App containing the process instances to be removed.

-containerSnapshotAcronym <acronym> – The acronym of the snapshot containing the process instance details to be removed.

-instanceStatus <Status> - A filter describing the state of process instances to be deleted. This can be one of:


-instanceID <instanceIds> - A list of one or more instanceIds that are to be deleted.

-endAfterLocal … - A date/time that says which instances to delete after a date

-endBeforeLocal … - A date/time that say which instances to delete before a date

-outputFile <outputFileName> - The name of a file which will be used to record the outcome of the deletions including which instances were deleted.

The wsadmin command called BPMShowProcessApplication can be used to list the details of a Process Application as known to IBM BPM. This command takes a parameter which is the acronym id of the Process Application to be shown.

eg.

print AdminTask.BPMShowProcessApplication('[-containerAcronym MyApp]')

An example output of this command is:

Name: 801Tests Acronym: T801 Description: Toolkit: false Tracks: Track Name: Main Track Acronym: Main Default: true Tip: Created On: 2012-11-22 12:12:53.8 Created By: User.9 State: State[Inactive] Capability: Capability[Standard] No of running instances: 0 List of Snapshots: Name: SN1 Acronym: SN1 Created On: 2012-11-22 12:12:53.8 Created By: User.9 Is Default: false State: State[Inactive] Capability: Capability[Standard] No of running instances: 0

In addition to the previous recipe, IBPM provides a stored procedure called LSW_BPD_INSTANCE_DELETE that clears historic data. This recipe is deprecated and should simply not be used from 8.5.5 onwards.

The signature of this procedure looks as follows:

CREATE PROCEDURE LSW_BPD_INSTANCE_DELETE(IN bpdInstanceId DECIMAL(12,0))

Here is a Java application that will delete such instances:

package com.kolban.wle; import java.sql.CallableStatement; import java.sql.Connection; import java.sql.DriverManager; import java.sql.PreparedStatement; import java.sql.ResultSet; public class CleanBPD { public static void main(String[] args) { CleanBPD cleanBPD = new CleanBPD(); cleanBPD.run(); } private void run() { System.out.println("Running"); try { Class.forName("com.ibm.db2.jcc.DB2Driver").newInstance(); String url = "jdbc:db2://localhost:50000/PROCDB"; String userid = "db2admin"; String password = "db2admin"; Connection con = DriverManager.getConnection(url, userid, password); PreparedStatement queryStmt = con.prepareStatement("SELECT BPD_INSTANCE_ID FROM LSW_BPD_INSTANCE WHERE EXECUTION_STATUS = 2"); CallableStatement deleteStmt = con.prepareCall("{CALL LSW_BPD_INSTANCE_DELETE(?)}"); ResultSet rs = queryStmt.executeQuery(); while(rs.next()) { int bpdId = rs.getInt("BPD_INSTANCE_ID"); System.out.println("Deleting BPD: ID = " + bpdId); deleteStmt.setInt(1, bpdId); deleteStmt.execute(); } } catch (Exception e) { e.printStackTrace(); } } }

See also:

Adding and removing Process Servers from Process Center

Process Center is the hub of knowledge about process applications while Process Servers act as the run-time environments for executing work. When a new Process Server is created, it initially knows nothing about any available Process Centers. In order for a Process Center to know about the Process Server, the Process Server's configuration needs to be changed to refer to the target Process Center. The configuration file called 99Local.xml contains this information. An example of the relevant section is as follows:

<repository-server-url>/ProcessCenter</repository-server-url> <repository-server-user-auth-alias></repository-server-user-auth-alias> <repository-server-designated-user-auth-alias>BPMAuthor_Auth_Alias</repository-server-designated-user-auth-alias> <repository-server-interval>-1</repository-server-interval>

The highlighted lines are the ones that need changed.

The repository-server-urlshould be changed to the URL of the ProcessCenter while the repository-server-interval should have a value of 10 (just not -1).

For example:

<repository-server-url>http://localhost:9080/ProcessCenter</repository-server-url> <repository-server-user-auth-alias>myAlias</repository-server-user-auth-alias> <repository-server-designated-user-auth-alias>BPMAuthor_Auth_Alias</repository-server-designated-user-auth-alias> <repository-server-interval>10</repository-server-interval>

The name of the server as shown in Process Center can also be found in the 99Local.xml file under the <server-name> section:

<server-name>envName1</server-name> <server-description>A running process server</server-description> <server-host>localhost</server-host> <server-port>9081</server-port> <environment-type>Test</environment-type>

The instructions above seem to have been superseded by new information. Within the Deployment Environment configuration found in the WAS Admin Console we have an entry called "Process Server Settings":

If we drill down into there, we can find the configuration details there of how the Process Server should connect to the Process Center:

Deployment of applications to servers

Process Applications can be deployed to multiple Process Server instances. In order to deploy an application, a snapshot of the application must first be taken. It is the content of the snapshot that is deployed. Changes made to the application after the snapshot will not be reflected in the deployed application until after a new snapshot is taken and that instance of the snapshot deployed.

See also:

Offline Application Deployment

During development, the applications are built and tested in the Process Center environment with its local/unit test run-time. However, when it comes time to deploy to production, many customers wish to perform manual install of such solutions directly into their Process Servers as opposed to a dynamic push out from a Process Center. There are many reasons for this but a primary one is that an exact copy of the application is desired so that the system can be recreated as needed from artifacts stored on the file system. Another common reason for manual deployment is that it can be scripted and supplied to operations staff for production installation and management. The script and associated artifacts can then be logged as the system of record for the production system.

In order to perform a manual deployment of a solution, we must first export the package that represents the solution. This can be done from the Process Center console. Before we can do this, we need to define our target environment as an "offline server".

In Process Center, switch to the Servers tab and click the "Add a New Offline Server" button:

A dialog will appear prompting for details of the new (offline) server:

Once completed, it will appear in the list:

In the Process Apps tab for the snapshot of the application that is to be deployed, click the Install button:

Next select the offline server and then the "Create installation package" button:

After a few moments, the details of the Snapshots for the Process App will change to show that a deployment package is available:

At this point, Process Center has built the package for deployment. Now we have to retrieve the package from the Process Center. This is achieved from the Windows DOS command prompt. Open a DOS window and change directory to:

The Wsadmin command called BPMExtractOfflinePackage can be used to create an installation package. It has the following options:


|| |Note: Another useful command is called BPMShowProcessApplication which will list the details of a named Process App.

print AdminTask.BPMShowProcessApplication('[-containerAcronym APP01]') Name: App01 Acronym: APP01 Description: Toolkit: false Tracks:

Track Name: Main Track Acronym: Main Default: true

Tip: Created On: 2012-11-12 11:49:49.159 Created By: User.9 State: State[Inactive]

List of Snapshots: Name: SN1 Acronym: SN1 Created On: 2012-11-12 11:49:49.159 Created By: User.9 State: State[Inactive]|

For example, the following command will extract an installation package:

AdminTask.BPMExtractOfflinePackage('[-containerAcronym APP01 -containerSnapshotAcronym SN1 -containerTrackAcronym Main -serverName PS1-offline -outputFile C:/temp/APP01.zip]')

The result of running this command will be a new file that contains the package for the application. This should be copied to the machine hosting the Process Server on which it is to be installed. To deploy the application to the server, use another command. This command is called BPMInstallOfflinePackage. This takes as input the package file name and will deploy it for execution.

For example:

AdminTask.BPMInstallOfflinePackage('[-inputFile C:/temp/APP01.zip]')

See also:

Un-Deployment of applications from servers

There may come a time when a previously deployed application is not desired to be run again. At this point you may wish to remove the application from the Process Server. To achieve that task, first de-activate the Process App from the Process Admin Console:

Once the snapshot has been de-activated, it can be deleted using the wsadmin command:

AdminTask.BPMDeleteSnapshot('[-containerAcronym DEPLOY1 -containerSnapshotAcronyms [SN1]]')

This will remove the Snapshot from the server.

Governance of deployment

When an application is to be deployed to a server we may wish to apply governance to this. We may not simply wish an application to be deployed just because it can.

IBM BPM provides the capability to design a process which will be executed prior to deployment. The outcome of this process determines whether or not the application will in fact be deployed. The way this is achieved is that we create a process definition (BPD) that we can consider a "governance process". We then associate this governance process with a process application that we wish to govern. When an attempt to deploy the process application is made, an instance of the governance process will be executed and based on the outcome of that process, the new process application will either be deployed or not.

To build a governance process, we create a new process application and then add an IBM supplied toolkit called "System Governance" as a dependency. Once done, when we create a new BPD, we will find that we have a template option:

When a process application is associated with the System Governance toolkit, the icon for that process app changes when it is viewed from Process Center. A small "mallet" is shown associated with the entry:

We can use the "Installation Requested Template" as the template to create a governance process. Once the governance process implementation has been made, we must take a snapshot of its containing process application. Next we must perform an un-common step, we must flag the new snapshot as being "Released". We can do this from within Process Center by examining the snapshot which has a pull-down menu. From that menu entry we can select "Status":

Once selected, we can change the status attribute of the process app:

The input to the process is an instance of "ProcessAppInstallation" contained within a variable called "ProcessAppInstallationRequest".

The ProcessAppInstallation looks like:

The notion here is that these details provide the information to be used by participants and rules within the governance process to determine whether to allow or deny the process from being installed. It is the responsibility of the governance process to allow or deny the installation. The "System Governance" toolkit provides a set of services that can be invoked by the governance process to process the outcome. Included in the services are:


Governance – Install Snapshot

This service installs a snapshot in the Process Servers. It has the following parameters:

Input: ProcessAppInstallation

Output: InstallResponse

The InstallResponse indicates the outcome of the installation.

Governance – Cancel Snapshot Installation

This service cancels the installation of a snapshot. It requires the following parameters:

Input: ProcessAppInstallation

Governance – Get All Process Servers

This service retrieves a list of all the known process servers.

Governance – Set Installation Status

This services sets the status attributes of an installation. The parameters to this service are:

Input: processServerID

Input: snapshotID

Input: status

Input: description

Governance – Get Installation Status

Applying Governance to a Process App to be governed

Once a governance process has been built, we must finally apply it to one or more other process apps which are to be governed.