Process templates, instances, and versioning

This topic describes the life cycle of a process template for business process applications, process instances, describes how to implement process versioning, and explains the semantics of the valid-from attribute.

What are process templates?

Process templates define business processes within an enterprise application. Every time that a new instance of a business process is created, it is based on the process template definition that is currently valid.

How do I define a process template?

You define your process templates using WebSphere Integration Developer. During modeling you can specify a valid-from timestamp attribute for a process. If you do not explicitly specify a valid-from attribute, it is set to the current time each time the code is generated.

How to avoiding name clashes between different versions

If you are defining a new version of a process, in WebSphere Integration Developer, you must:
  • Regenerate the code. If you explicitly set the valid-from attribute in your process, ensure that you specify a new value for this attribute.
  • Define a new name for the enterprise application.
  • Define a new context root for the Web application.

How do I version the interfaces of process templates?

A new version of a process model must always support the same interfaces as the previous version. But the new version can also provide new interfaces that are not present in the previous version, for example, the new version might have additional receive or pick activities.

What deploy code is generated?

When WebSphere Integration Developer generates the deploy code for your process, the constructs in the process model are mapped to various J2EE constructs and artifacts. For each business process, a stateless session bean is generated (also known as a process facade). All deploy code is packaged into the enterprise application (EAR) file.

What does the session bean do?

The session bean provides an interface between the client of the process, and the process itself. To interact with the session bean, the client must use the session facade in the current enterprise application by using its JNDI lookup name. The session bean provides methods for all operations that are declared in the "my role" specifications of all partner links for the process.

How else can a client interact with process instances?

If you do not want the client to use the session bean access methods, you can program the client to use generic API calls and JMS messaging to interact with processes.

When is a process instance created?

A new process instance is created from a process template if a new service request is received, or if the process is explicitly invoked or initiated using an API call. A process instance is created only if all the following conditions apply.
  • The process template is currently valid.
  • The process template supports the requested service.
  • The process template is not in the stopped state.
  • The application that contains the requested process is not in the stopped state.
Otherwise, if one or more of these conditions are not true, the request is rejected.

How can a client use the generic API to create a new process instance?

The call and initiate methods that take a process template name result in a new process instance providing the conditions described in "When is a process instance created?" are met.

If you try to start a process using the initiate or sendMessage methods:
  • If you specify a service template or activity template that is contained in a process template that is no longer valid, then the request is rejected
  • If the template is in the stopped state, you get an EngineProcessModelStoppedException.
  • If the template is valid and in the started state, but the application is stopped, you get a CreateFailed exception.
Note: The sendMessage request is accepted if it is sent to a running instance; even if the process template is no longer valid, though no new instance is created.

How can I find process templates that I can create instances of?

To find a process template, use the queryProcessTemplates API. It only returns templates that are contained in an application that is not stopped. Before trying to invoke an instance of any of the process templates, you must filter out any process templates that are not in the started state.

Example: Using queryProcessTemplates to get a valid process template

The example shows how you can get the currently valid template for a specific process that is in the started state:
String templateName = "MyTemplateName";
 String strNow = new com.ibm.bpe.api.UTCDate().toXsdString();
 String where = " PROCESS_TEMPLATE.NAME = " + templateName + " AND "
              + " PROCESS_TEMPLATE.VALID_FROM = (SELECT MAX(VALID_FROM) FROM PROCESS_TEMPLATE"
              + " WHERE NAME=PROCESS_TEMPLATE.NAME"
              + " AND VALID_FROM <= TS('" + strNow + "')"
              + " AND STATE = (" + ProcessTemplateData.STATE_STARTED + "))";

 ProcessTemplateData[] processTemplates = process.queryProcessTemplates (where,
                                                                          null,
                                                                          null,
                                                                          null);

What if a client must access a specific old session bean interface?

If a client must interact with a running instance of an 'old' process template, it must call the methods of the session bean in the enterprise application that contains the old template. To do this, the client must use the JNDI lookup name of the old process facade.

If the client tries to call an operation belonging to a process template that is currently not valid or is in the stopped state, the request is accepted only if the request addresses a running instance. Otherwise, when there are no running instances matching the correlation data in the request, the request is rejected with a ProcessError exception, and no new process instance is created.

If the requested template is part of an enterprise application that is in the stopped state, no interaction with the template is possible.

What is the package name?

The package name is generated from the target namespace in the process model in a way that is compliant with the axis wsdl2java tool. For example, for a namespace http://x.y.com/a or urn:x.y.com/a, the package name is com.y.x.a, and the transformed package name used to construct the JNDI name, is com/y/x/a.

What is the JNDI name of my session bean?

The JNDI lookup name of the process facade (session bean) is created by concatenating the following strings:
  • The package name (transformed to replace all dots with slashes).
  • The process name.
  • A normalized form of the valid-from timestamp.

Example JNDI name for a session bean

If the target namespace of the process is http://www.example.com/processXyZ, the process name is SampleProcess, and the valid-from timestamp is 2005-01-01T00:00:00, then the generated JNDI lookup name for the session facade of this process is com/example/www/processXyZ/SampleProcess20050101T000000.

How are process models deployed?

When you install an enterprise application that contains business process model J2EE constructs, the process model constructs are stored in the Business Process Choreographer database. If the database system is not running, or if it cannot be accessed, the deployment fails. When the process model constructs are in the Business Process Choreographer database, they are known as process templates, and they can be used to create running process instances. Newly installed process templates, are by default, in the started state, however, the newly installed enterprise application is in the stopped state.

What happens if a process template is in the started state, but the application it belongs to is in the stopped state?

If a currently valid process template is in the started state, but the application is in the stopped state, no new process instances are created from the template. In this case, process instances can be created from a process template that is no longer valid, if this template has the most recent valid-from date.

How are new process model versions introduced into a production system?

Each new version of a process model that is to be deployed must be packaged into a new enterprise application. Each installed enterprise application can be started and stopped individually.

New versions of a process template have the same name, but a different valid-from attribute. You can deploy many different versions of a process template, each in a different application. All of the different process template versions are stored in the database. Whenever a new instance of the process template is required, it is the valid-from attribute values and the status of the application that determine which process template is used to create the new instance.

What are the semantics of the valid-from attribute?

When a new process instance is required, there could be many process templates in the database that have the same process name. The following rules determine which version of the process is used to create new process instances:
  • Process instances are never created from a process template that has a valid-from value that is in the future.
  • Because only process instances can actually run, the process template states 'started' and 'stopped' control whether new instances can be created from the template. Process instances are never created from a process template that has a state property 'stopped'.
  • Of the process templates that are in the started state and have a valid-from value in the past, the process template with the most recent valid-from date is used to create the process instance. This is the only template that is considered to be valid now. Any templates with older valid-from values are no longer valid.
  • If the template that is currently valid is deleted or the application is stopped, a process template that was no longer valid can become valid if it now has the most recent valid-from value.
  • If none of the process template have a valid-from value that lies in the past, no instance is created, and an error is generated.
These semantics allow you to define when changes to business processes come into effect, for example, tax changes that come into effect at midnight in a new year. The switchover to the new process templates is automatic, and requires no operator actions.

How do I stop new process instances being created?

Using the administrative console, select a process template, and click Stop. This changes the state of the template to 'stopped', and no more instances are created from the template. After stopping the currently valid template, any attempts to create a process instance from the template result in an EngineProcessModelStoppedException error, unless another process template in the started state has a valid-from attribute in the near future that causes it to it become the currently valid template, from which new instances can then be created as required.

What happens to running instances when a newer process template becomes valid?

The fact that the template from which they were instantiated is no longer valid has no effect on running instances. Existing process instances continue running to completion. Old and new instances are run in parallel until all the old instances have finished, or until they have been terminated.

What happens to a running instance if the template it was created from is stopped?

Changing the state of a process template to 'stopped' only stops new instances being created. Existing process instances continue running until completion in an orderly way.

How can I tell if any process instances are still running?

Log on to the Business Process Choreographer Explorer as a process administrator, and go to the Process Instances Administered By Me page, this displays any running process instances. If necessary, you can terminate and delete these process instances.

Why can't I stop a business process application if it has any process instances?

Process instances are a part of a business process application, and they are protected from being unintentionally terminated by an administrator accidentally uninstalling their business process, without realizing that instances are still running. For this reason, you can only stop a business process application if it has no process instances.