Chapter 6. Life Cycle

6.1. Asset Repository Interaction

Business Central uses Git as the implementation of its asset repository. In BPMS 6, this is implemented as a simply file-based Git repository in a hidden folder. Users are advised not to directly interact with this file-based repository.

When running, Business Central provides access to its repository through both the git:// and ssh:// protocols. While either protocol may be used to retrieve (i.e., pull) data from the repository, adding or updating data (i.e., push) is only possible through authenticated SSH to ensure security. The credentials used to log in to Business Central may also be used to authenticate with the asset repository through SSH.

When a design-time cluster is set up, the asset repositories of the cluster nodes are synchronized by ZooKeeper. This means that data may be pull from or even pushed to any single node while relying on the cluster to replicate the changes across the available nodes.

6.2. JBoss Developer Studio

While this reference architecture uses the web tooling and process designer to create the sample mortgage application, software developers will often benefit from a Java IDE with better development support and integration with other Java and non-Java technology.

JBoss Developer Studio is based on Eclipse and available from the Red Hat customer support portal. JBDS provides plugins with tools and interfaces for JBoss BRMS and BPMS, called the Drools plugin and the jBPM plugin respectively.

One of the plugins that is included in JBDS is the eclipse Git plugin. This plugin can be used to synchronize the content of the JBDS workspace with the asset repository of BPMS.

To set up a BPMS project in JBDS, after it has been created in the web designer environment, use Import and select Projects from Git. Select the option to Clone URI. Copy and paste the ssh URL for the repository in question into the URI field of the JBDS cloning dialog. This URL can be found in the Authoring / Administration page of Business Central, after changing it from the default of git to ssh. Depending on the IP address of the BPMS server in question, the user name used to access Business Central and the configured ssh port, this URL will be similar to the following:

ssh://172.16.71.100:8003/Mortgage

Pasting into the URI field automatically fills out the various fields including Host, Repository Path, Protocol, and Port. Also fill in the user name and password configured to access Business Central; credentials are required when using the ssh protocol and allow additions and modifications to be pushed back to the server.

The completed dialog for the reference environment looks as follows:

Figure 6.1. Source Git Import

Select Next to move forward to the next dialog. JBoss BPM Suite 6.0 uses the default master branch in its asset repository so this is typically the one and only branch that will be presented and selected at the next step. The third step is to select a local branch, also typically assigned to master, and a remote name which is set to origin by convention. In this step, select a local directory that will host the local copy of the repository. This is where the JBDS project will be stored.

Clicking Next after selecting the local destination opens the import project wizard selection. Select the last option to import the repository as a general project. The structure of the BPMS asset repository does not fit the expected structure of a jBPM project. This is remedied later by opening a jBPM file and when prompted, converting the project into a jBPM project. At this point, continue to select a descriptive local project name and finish the import process.

Once a JBDS project has been set up as a clone of a BPMS asset repository, it acts like any other project that uses Git as source control. Changes can be made and committed locally and when ready, those changes can be pushed upstream to the asset repository. Similarly, changes made through the web tools can be retrieved by pulling from the remote repository.

JBoss BPM Suite 6.3 only uses the master branch of Git but developers may still take advantage of other branching and tagging features through third-party tooling. This can take place when working with a clone in JBDS or when otherwise interacting with the asset repository, as long as Business Central only deals with the master branch.

6.3. Process Simulation

Business process simulation is a valuable analytic instrument for the purpose of assessing the behavior of business processes over time. This can help estimate the number of external calls, plan for human resources to handle the user tasks and otherwise assist in sizing and estimating technical and business aspects of the process.

In the web process designer, make sure to validate the process, view all issues and correct them before proceeding to process simulation.

From the toolbar of the web process designer, open the process simulation menu item and selected Process Paths:

Figure 6.2. Process Path Button

This brings up a dialog that shows all the possible process paths, as calculated for this process. The number of paths depends on the number of decision points and the potential complexity of the process. For this process, you may see around 42 different paths calculated. Select a path and click the Show Path button to see it in the process designer:

Figure 6.3. Process Paths

Before running process simulation, various simulation properties need to be set up for the business process. This includes, as you’ve likely seen in process validation, a probability value for each sequence flow that leaves or enters a diverging/converging gateway. As logically expected, the sum of probability values for all sequence flows leaving or entering any given diverging gateway should always be 100. If this sum is not 100, validation will show a validation issue of type simulation to warn the user of the problem and prompt its correction.

Other simulation properties include the cost of executing a node per time unit, the minimum and maximum processing time that’s envisioned for a node and how it may be distributed. For user tasks, staff availability and the number of working hours also affect process simulation.

For the boundary event of this mortgage process, the probability relates to the chances that an error would occur when calling the web service. In this case there are no multiple outgoing paths that must add up to 100.

From the same drop-down menu, select Run Process Simulation, enter the number of process instances to create and the interval at which they will be created in the desired time unit. Running simulation on the mortgage process for 200 instances with one instance started every 5 minutes generated a report such as the following:

Figure 6.4. Process Simulation Results

6.4. Business Activity Monitoring

The Dashbuilder application included in BPM Suite 6 allows the creation of reports, panels, pages and entire workspaces for the purpose of Business Activity Monitoring. The BPMS database is set up as a source of data by default but other external data sources may also be defined and added.

Business Central includes links to both Business Dashboards and the Process & Task Dashboard. These links redirect the browser to the jBPM dashboard of the Dashbuilder application. The jBPM dashboard is preconfigured with sample reports on BPMS processes and tasks by running queries against the BPMS database.

Start the mortgage process multiple times and use various users to claim the tasks that get created. Undeploy the credit web service for a number of process instantiations to create a number of Troubleshoot tasks. Then proceed to log in to Business Central as different users and claim the tasks to generate a more meaningful report:

Figure 6.5. Dashbuilder Dashboard

6.5. Governance

Red Hat provides an implementation of the SOA Repository Artifact Model and Protocol (S-RAMP) specification by OASIS. The specification and the implemented product can provide design-time governance for BPMS.

To use Red Hat JBoss S-RAMP Repository, download the separately provided Red Hat JBoss S-RAMP Repository 6.0.0 Installer from the Red Hat Customer Support Portal.

While S-RAMP Repository is a core component of JBoss Fuse Service Works, it is also an entitlement provided for BPM Suite 6 and used for design-time governance with BPMS. For complete documentation of this component, refer to the Design Time Governance section of the JBoss FSW documentation.

While the JBoss S-RAMP Repository may be configured to share the same Maven Repository with BPMS and therefore be aware of built artifacts, no integration is provided between the Git-based asset repository used in BPMS and S-RAMP in BPM Suite 6.0. To govern individual assets used in BPMS, manually upload the assets to S-RAMP. The S-RAMP repository provides a user-friendly interface, a REST API and a command-line interface that can all be used to create a manual or semi-automatic process for managing the BPMS asset repository content. Better integration with design-time governance is left to future versions of JBoss BPM Suite.

Governance workflows can be defined and implemented as BPMN 2.0 processes. This is achieved by configuring a query that detects interesting changes in the governance repository and triggers the deployed business process.

6.6. Process Execution

While the simplest way to run a process is through Business Central, several alternative methods have been provided to accommodate various client requirements.

6.6.1. Business Central

Business Central provides a unified environment for design and development as well as execution and monitoring of business processes. The form designer helps create process forms that can instantiate a process while collecting the required initial information from the user. Forms that have been created with this tool are automatically associated with the process through a naming convention and any future attempt to run the process from Business Central renders the form and uses it to populate the process variables.

6.6.2. Remote Client

Business Central also provides a REST server that can be used to start and interact with processes from a remote client. The client is deemed logically remote as it only interacts with the process through XML or JSON data sent through HTTP or JMS. This does not preclude the client application from physically residing in the same JVM or even being bundled in the same Web Application as Business Central.

The URL for sending REST / HTTP calls to Business Central always includes a static part that can be called the application context, which locates the server and the web application deployment. For a local default installation, the application context may be http://localhost:8080/business-central. This is always followed by /rest, which is the subcontext for REST calls. All requests need to be authenticated calls. What follows that varies and depends on the type of call and the deployment and process that is being targeted.

6.6.2.1. Simple Process Calls

Simple process calls allow callers to start a new process instance, signal a waiting process, abort a running process, retrieve information about process variables or otherwise interact with a running process instance.

These calls either use simple HTTP GET methods or require HTTP POST methods that accept both JSON and XML as input.

For example, a process may be started through an HTTP POST call to the following URL:

/runtime/{deploymentId}/process/{procDefID}/start

For the BPMS example application running on a local default installation:

http://localhost:8080/businesscentral/rest/runtime/com.redhat.bpms.examples:mortgage:1/process/com.redhat.bpms.examples.mortgage.MortgageApplication/start

If any process variables are expected when the process is started, they should be provided as query parameters. To represent a map, submit each key-value pair of the map as a separate query parameter which suffixing the key with “map_”. By utilizing query parameters, the sending of objects via query is prevented, however, even the POST request doesn’t process the content provided, so it’s recommended to use KIE Server remote API or Command Execution (described below) instead. As an example of utilizing query parameters, to pass a map of process variables with two entries where one sets the process variable name to John and the other sets the process variable age to 30, provide the following query parameters:

.../start?map_name=John&map_age=30

A simpler example is a REST call to retrieve basic information about a running process instance. This is achieved through an HTTP GET call to the following URL:

/runtime/{deploymentId}/process/instance/{procInstanceID}

For the BPMS example application running on a local default installation, to query the first process instance that was created, this URL would look as follows:

http://localhost:8080/businesscentral/rest/runtime/com.redhat.bpms.examples:mortgage:1/process/instance/1

Note that this only queries the runtime, which excludes any process that has reached a wait state (user task, async callback, etc). Use History Calls for more complete information.

6.6.2.2. Simple Task Calls

Simple task calls allow callers to manage the lifecycle of a task by claiming it, releasing it, forwarding it, skipping it or otherwise managing or altering its assignment and lifecycle.

Simple task calls also query the task content and data, as well as complete a task while assigning required variables to the task.

These calls either use simple HTTP GET methods or require HTTP POST methods that accept both JSON and XML as input.

For example, a task content may be retrieved through an HTTP GET call to the following URL:

/task/content/{contentID}

For the BPMS example application running on a local default installation, to retrieve the details of task 1, this URL would look as follows:

http://localhost:8080/business-central/rest/task/1/

To claim this task for a given user, make an HTTP POST call to the following URL:

http://localhost:8080/business-central/rest/task/1/claim

The next step, according to the task lifecycle, would be to start work on the task on behalf of the user. This, again, is simply a matter of making an HTTP POST call to the following URL:

http://localhost:8080/business-central/rest/task/1/start

Finally, the task may be completed by making a call to:

http://localhost:8080/business-central/rest/task/1/complete

If any variables are expected when the task is completed, they should be provided as query parameters. To represent a map in HTTP calls, submit each key-value pair of the map as a separate query parameter which suffixing the key with “map_”. For example, to pass a map of process variables with two entries where one sets the process variable name to John and the other sets the process variable age to 30, provide the following query parameters:

.../complete?map_name=John&map_age=30

6.6.2.3. History Calls

To access the audit log and retrieve historical process and task information, issue simple GET commands to the history API.

For example, for an overview of all the process instances of the MortgageApplication process, send an HTTP GET query without any parameters as follows:

http://localhost:8080/businesscentral/rest/history/process/com.redhat.bpms.examples.mortgage.MortgageApplication

To get information on a specific process instance, use the process instance ID, for example:

http://localhost:8080/business-central/rest/history/instance/1

To retrieve the variable values of this process:

http://localhost:8080/business-central/rest/history/instance/1/variable

This can be further narrowed down to investigate how the value of a particular process variable changed over time. For example, to inquire about the application variable of this process, use the following query:

http://localhost:8080/business-central/rest/history/instance/1/variable/application

To view the value of the application in all process instances of all process definitions in this deployment, issue the following query:

http://localhost:8080/business-central/rest/history/variable/application

There is also a query that searches the variables directly for a value. As a practical matter, this results in a search of all process instances of any process definition type for a process variable with a given value.

For example, to look for mortgage applications by an applicant with a given Social Security Number, the following query may be issued:

http://localhost:8080/business-central/rest/history/variable/ssn/value/333224442

6.6.2.4. Command Execution

Advanced users looking to send a batch of commands via the REST API can use the execute operation. This is the only way to have the REST API process multiple commands in one operation. The execute calls are available through both REST and JMS API. The only accepted input format is JAXB, which means that REST calls over HTTP may only send XML and cannot use the JSON format.

Issue Execute commands to /runtime/{deploymentId}/execute. For the sample deployment, the URL would be:

http://localhost:8080/businesscentral/rest/runtime/com.redhat.bpms.examples:mortgage:1/execute

The posted content must be the JAXB representation of an accepted command. Refer to the official RedHat documentation for a full list of commands.

6.6.2.5. Client API for REST or JMS Calls

A client API is available to help Java clients interact with the BPMS REST API. For example, to start a new instance of the mortgage process:

String deploymentId = "com.redhat.bpms.examples:mortgage:1";
String applicationContext = "http://localhost:8080/business-central";
String processId = "com.redhat.bpms.examples.mortgage.MortgageApplication";
URL jbpmURL = new URL( applicationContext );

RemoteRestRuntimeFactory remoteRestSessionFactory =
    new RemoteRestRuntimeFactory( deploymentId, jbpmURL, userId, password );

RuntimeEngine runtimeEngine = remoteRestSessionFactory.newRuntimeEngine();
KieSession kieSession = runtimeEngine.getKieSession();

Map<String,Object> processVariables = new HashMap<String, Object>();
Application application = new Application();
application.setAmortization( 30 );
...
processVariables.put( "application", application );
kieSession.startProcess( processId, processVariables );

This code results in the start process command being sent to the REST API.

Notice the choice of runtime factory in the above example:

RemoteRestRuntimeFactory remoteRestSessionFactory =
    new RemoteRestRuntimeFactory( deploymentId, jbpmURL, userId, password );

An alternative choice would have been the JMS API:

RemoteJmsRuntimeEngineFactory jmsFactory =
    new RemoteJmsRuntimeEngineFactory( deploymentId, new InitialContext() );
RuntimeEngine runtimeEngine = jmsFactory.newRuntimeEngine();

The RuntimeEngine interface provides abstraction from the underlying method and protocol so the rest of the client code remains unchanged when using JMS instead of HTTP REST calls.

The client API may also be used to create Command objects and execute them through REST/HTTP or JMS, or in fact execute a batch of commands at once.

6.6.3. Local Application

While the Business Central forms may provide a suitable method of starting processes and completing tasks for some client requirements, many will require greater control and flexibility on their user interface. In some cases the starting of processes and the completion of tasks may not directly be user-driven and in other cases when it is, the command may come from a JSF or other UI technology.

These applications can be deployed on the same server or cluster as BPMS. By declaring a dependency on the required BPMS modules and configuring the appropriate datasource, custom code may be used to interact with processes and tasks.

Custom applications can declare a maven dependency on the required packages, including the BPMS project.

Java EE dependency injection can simplify access to the KieSession, for example:

@Inject
@Singleton
private RuntimeManager runtimeManager;

RuntimeEngine runtime = runtimeManager.getRuntimeEngine(EmptyContext.get());

KieSession ksession = runtime.getKieSession();

ProcessInstance processInstance = ksession.startProcess(...

The runtime strategy may be specified through annotations as @Singleton, @PerProcessInstance or @PerRequest.

To interact with tasks, use the RuntimeManager to get the RuntimeEngine and then retrieve the TaskService and KieSession from the engine. At the end, if outside a container managed transaction, dispose of the retrieved engine explicitly.

Even when calls to start a process or complete a task originate from a custom application deployed alongside BPMS, the decision to treat it as a local client or a REST client requires some thought and depends on whether a loosely-coupled or a tightly-coupled design between the application and BPMS is more desirable.

6.7. Maven Integration

JBoss BPM Suite 6.0 uses Maven for build management. While the Maven repository is locally maintained and accessible through the file system, it is often the case that a BPMS cluster should be treated as a logical entity and intrusive integration including access to the local file system of an instance may have adverse side effects.

Once a project has been built by Business Central, BPMS 6.0 serves its Maven artifact by HTTP through the /maven2 sub-context. For example, to access the Maven project file for the mortgage application, the following query may be used:

http://localhost:8080/businesscentral/maven2/com/redhat/bpms/examples/mortgage/1/mortgage-1.pom

Similarly, the build JAR artifact for the project may be retrieved from the following URL:

http://localhost:8080/businesscentral/maven2/com/redhat/bpms/examples/mortgage/1/mortgage-1.jar

6.8. Session Strategy

JBoss BPM Suite supports three different strategies for session management and reuse. Each strategy is described in more detail here. The choice of session strategy largely depends on the anticipated level of concurrency as well as the use of the rule engine in the processes. Using a single global session means that any object inserted into rule engine working memory for a process instance may impact firing of rules for other instances of the same process or even an entirely different process definition.

The concurrency consideration is also an important one in the choice of session strategy. Generally speaking, any work done within the scope of a KIE session is single-threaded. When a session is shared between various requests (or process instances), that means that the processing is serialized. This may or may not be acceptable for a given use case.

6.8.1. Singleton

In this model, a single KIE session is created within the given scope and used for all new and existing process instances of all process definitions.

When creating a deployment through Business Central, use Singleton to select this strategy.

The equivalent annotation, used in the client API, is @Singleton.

6.8.2. Per Process Instance

In this model, a new KIE session is created within the given scope for every new process instance of a given process definition and reused again when signaling, continuing or otherwise executing the same process instance in the future.

When creating a deployment through Business Central, use Process instance to select this strategy.

The equivalent annotation, used in the client API, is @PerProcessInstance.

6.8.3. Per Request Session

In this model, a new KIE session is created for every request, regardless of whether a new process instance is being created or a process instance previously created in another session is being continued.

When creating a deployment through Business Central, use Request to select this strategy.

The equivalent annotation, used in the client API, is @PerRequest.

6.9. Timer Implementation

BPMS 6 requires and uses timers for various reasons. The default timer used in BPMS 6.0 is an internal implementation using thread pools. Upon initialization, the BPMS environment looks for a Java system property called org.quartz.properties. If found, the value of this property is presumed to be the fully qualified location of the quartz property file.

In a cluster environment, Quartz should be configured to use a central database for persistence. The recommended interval for cluster discovery is 20 seconds and is set in the org.quartz.jobStore.clusterCheckinInterval of the quartz-definition.properties file. Depending on your set up consider the performance impact and modify the setting as necessary. Refer to the official Red Hat documentation for details on how to configure Quartz in BPMS 6.3.

6.10. REST Deployment

One required step in build automation is deployment of business processes. To accommodate this requirement, the REST API provides support for deployment.

Assuming the deployment ID of the mortgage application, issue an HTTP POST to the following URL to trigger deployment:

http://localhost:8080/businesscentral/rest/deployment/com.redhat.bpms.examples:mortgage:1/deploy

The deploy operation is asynchronous and deployment will continue and complete after the response of the REST operation has been returned.

The session strategy can also be specified at the time of deployment through the REST interface. For example, to use “per process instance” as the session strategy:

http://localhost:8080/businesscentral/rest/deployment/com.redhat.bpms.examples:mortgage 1/deploy?strategy=PER_PROCESS_INSTANCE

6.11. Continuous Integration

Standard and widely used software tooling such as Git and Maven make it easier to include BPMS applications in an organization’s various automated processes. Assets can be easily retrieved from and placed in the asset repository as outlined in Asset Repository Interaction. Maven Integration makes it easier to include BPMS In the build process and deployment. To deploy BPMS projects, deployment can be triggered through a simple REST call.

Additional functionality exposed through the REST API allows a caller to create an organizational unit, create a repository and create a project within that repository. At that point, assets can be pushed to the project repository before triggering build and deployment. Refer to the official Red Hat documentation for further details on the REST API for the Knowledge Store.

This collection of features and resources helps implement continuous integration in BPMS projects.

Where did the comment section go?

Red Hat's documentation publication system recently went through an upgrade to enable speedier, more mobile-friendly content. We decided to re-evaluate our commenting platform to ensure that it meets your expectations and serves as an optimal feedback mechanism. During this redesign, we invite your input on providing feedback on Red Hat documentation via the discussion platform.