A.3. Collaboration mechanisms

Elements with execution semantics make use of general collaboration mechanisms. Different Elements allow you to access and use the mechanism in a different way; for example, there is a mechanism called signalling: a Signal is sent by a Throw Signal Intermediate Event Element and received by a Catch Signal Intermediate Event (two Elements with execution semantics make use of the same Signal mechanism).

Collaboration mechanism includes the following:

Signals
General, mainly inter-process instance communication
Messages

Messages are used to communicate within the process and between process instances. Messages are implemented as signals which makes them scoped only for a given KSession instance.

For external system interaction send and receive task should be used with proper handler implementation.

Escalations
Mainly signalling between processes to trigger escalation handling.
Errors
Mainly inter-process signalling of escalation to trigger escalation handling.

All the events are managed by the signaling mechanism. To distinguish individual objects of individual mechanism the signal use different signal codes or names.

A.3.1. Signals

Signals in Red Hat JBoss BPM Suite correspond to the Signal Event in BPMN 2.0, and are the most flexible of the listed mechanisms. Signals can be consumed by an arbitrary number of elements both within its process instance and outside of it. Signals can also be consumed by any element in any session within or cross the current deployment, depending on the scope of the event that throws the signal.

A.3.1.1. Triggering Signals

The following Throw Events trigger signals:

Types of Signal Throw Events

  • Intermediate Throw Event
  • End Throw Event

Every signal defines its signal reference (SignalRef), which is unique in the respective session.

A signal can have one of the following scopes, which restricts its propagation to the selected elements:

Signal Scopes

Default (ksession)

Signal only propagates to elements within the given ksession. The behavior varies depending on what runtime strategy is used:

  • Singleton: All instances available for the ksession are signalled.
  • Per Request: Signal propagates within the currently processed process instance and process instances with Start Signal Events.
  • Per Process Instance: Same as per request.
Process Instance
The narrowest possible scope, restricting the propagation of the signal to the given process instance only. No catch events outside that process instance will be able to consume the signal.
Project
Signals all active process instances of given deployment and start signal events (regardless of the strategy).
External
Allows to signal elements both within the Project and across deployments. The External scope requires further setup.

To select the scope in the Process Designer, click Signal Scope under Core Properties of a Signal Throw Event:

Figure A.1. Selecting Signal Scope (Default)

signal select scope
Signalling External Deployments

When creating an external signal event, you need to specify the Work Item handler for External Send Task manually. Use org.jbpm.process.workitem.jms.JMSSendTaskWorkItemHandler, which is shipped with Red Hat JBoss BPM Suite. It is not registered by default because each supported application server handles JMS differently, mainly due to different JNDI names for queues and connection factories.

Procedure: Registering External Send Task Handler

  1. In Business Central, open your project in the Project Editor and click Project Settings: Project General Settings → Deployment descriptor.
  2. Find the list of Work Item handlers and click Add.

  3. Provide these values:

    • Name: External Send Task
    • Value: new org.jbpm.process.workitem.jms.JMSSendTaskWorkItemHandler()
    • Resolver type: mvel

    Figure A.2. Registered External Send Task Handler

    register externalworkitemhandler signal

    This will generate a corresponding entry in the kie-deployment-descriptor.xml file.

The JMSSendTaskWorkItemHandler handler has five different constructors. The parameterless constructor used in the procedure above has two default values:

  • Connection factory: java:/JmsXA
  • Destination queue: queue/KIE.SIGNAL

You can specify custom values using one of the following constructors instead:

  • new org.jbpm.process.workitem.jms.JMSSendTaskWorkItemHandler("CONNECTION_FACTORY_NAME", "DESTINATION_NAME")
  • new org.jbpm.process.workitem.jms.JMSSendTaskWorkItemHandler("CONNECTION_FACTORY_NAME", "DESTINATION_NAME", TRANSACTED), where TRANSACTED can only have two values: true or false. The argument affects the relevant JMS session. See the Interface Connection Javadoc for more information.

Both cross-project signalling and process instance signalling within a project is supported. To do so, you can specify the following data inputs in the DataInputAssociations property of your Signal event in the Process Designer. See Section A.3.1.2, “Catching and Processing Signals” for more information.

  • Signal: the name of a signal which will be thrown. This value should match the SignalRef property in the signal definition.

    SignalWorkItemId: the ID of a Work Item which will be completed.

    These two data inputs are mutually exclusive.

  • SignalProcessInstanceId: the target process instance ID (optional).
  • SignalDeploymentId: the target deployment ID (required).

Figure A.3. Specifying SignalDeploymentId Data Input

data input and assignment

The data inputs provide information about the signal, target deployment, and target process instance. For external signalling, the deployment ID is required, because an unrestricted broadcast would negatively impact the performance in large environments.

To send signals and messages in asynchronous processes, you need to configure a receiver of the signals accordingly: that is to limit a number of session for a given endpoint. By default, the receiver message-driven bean (org.jbpm.process.workitem.jms.JMSSignalReceiver) does not limit a concurrent processing.

Open the EAP_HOME/standalone/deployments/business-central.war/WEB-INF/ejb-jar.xml file and add the following activation specification property to the JMSSignalReceiver message-driven bean: 

<activation-config-property>
  <activation-config-property-name>maxSession</activation-config-property-name>
  <activation-config-property-value>1</activation-config-property-value>
</activation-config-property>

The message-driven bean should look like the following: 

<message-driven>
  <ejb-name>JMSSignalReceiver</ejb-name>
  <ejb-class>org.jbpm.process.workitem.jms.JMSSignalReceiver</ejb-class>
  <transaction-type>Bean</transaction-type>
  <activation-config>
    <activation-config-property>
      <activation-config-property-name>destinationType</activation-config-property-name>
      <activation-config-property-value>javax.jms.Queue</activation-config-property-value>
    </activation-config-property>
    <activation-config-property>
      <activation-config-property-name>destination</activation-config-property-name>
      <activation-config-property-value>java:/queue/KIE.SIGNAL</activation-config-property-value>
    </activation-config-property>
    <activation-config-property>
      <activation-config-property-name>maxSession</activation-config-property-name>
      <activation-config-property-value>1</activation-config-property-value>
    </activation-config-property>
  </activation-config>
</message-driven>

This setting ensures that all messages, even the ones that were sent concurrently, will be processed serially and that notifications sent to the parent process instance will be delivered and will not cause any conflicts.

A.3.1.2. Catching and Processing Signals

Signals are caught by the following Catch Event types:

Types of Signal Catch Events

  • Start Catch Event
  • Intermediate Catch Event
  • Boundary Catch Event

To catch and process a signal, create an appropriate Catching Signal Event in the Process Designer, and set the following properties:

SignalRef

The Signal’s Reference.

Value: The same as the Throwing Signal Event’s SignalRef.

DataOutputAssociations

The variables used to store the output of the received signal, if applicable.

To assign a data output:

  1. Select the appropriate catch event type in the Business Process Designer.
  2. Click 3140 to open the Properties tab.
  3. click the drop down menu next to the DataOutputAssociations property, and click Add.
  4. In the new row, fill in a name for the association.
  5. Select the expected data type from the dropdown menu. Selecting Custom… enables you to type in any class name.
  6. Select the target process variable, where the output will be stored.

  7. Click Save to save the association.

    For more information about setting process variables, see Section 4.9, “Variables”.

A.3.1.3. Triggering Signals using API

To signal a process instance directly, that is equivalent to the process Instance scope, use the following API function: 

ksession.signalEvent(eventType, data, processInstanceId)

Here, the parameters used are as follows:

eventType

The signal’s reference, SignalRef in Process Designer.

Value: A String. You can also reference a process variable using the string #{myVar} for a process variable myVar.

data

The signal’s data.

Value: Instance of a data type accepted by the corresponding Catching Signal Event. Typically an arbitrary Object.

processInstanceId
The Process ID of the Process being signalled.

You can use a more general version of the above function, which does not specify the parameter processInstanceId. That results in signalling all processes in the given ksession, that is equivalent to the Default scope: 

ksession.signalEvent(eventType, data)

The usage of the arguments eventType and data is the same as above.

To trigger a Signal from a script, that is a Script Task, or using on-entry or on-exit actions of a node, use the following API function: 

kcontext.getKieRuntime().signalEvent(
    eventType, data, kcontext.getProcessInstance().getId());

The usage of the arguments eventType and data is the same as above.

A.3.2. Messages

A Message represents the content of a communication between two Participants. In BPMN 2.0, a Message is a graphical decorator (it was a supporting element in BPMN 1.2). An ItemDefinition is used to specify the Message structure.[1]

Messages are similar objects to Signals; the main difference is that when you are throwing the message, you must uniquely identify the recipient of the Message. In Red Hat JBoss BPM Suite, this is achieved by specifying both the element ID and the Process Instance ID. For this reason, Messages do not benefit from the scope feature of Signals.

A.3.2.1. Sending Messages

Like Signals, Messages are sent by Throw Events of one of the following types:

Types of Message Throw Events

  • Intermediate Throw Event
  • End Throw Event
  • Send Task

When creating the appropriate Throw Event, register a custom handler for the Send Task Work Item. Red Hat JBoss BPM Suite provides only dummy implementation by default. It is recommended to use the JMS-based org.jbpm.process.workitem.jms.JMSSendTaskWorkItemHandler.

Note

If necessary, you can emulate the message-sending mechanism using signals and their scopes so that only one element can receive the given signal.

A.3.2.2. Catching Messages

The process for catching messages does not differ from receiving signals, except you use the MessageRef element property instead of SignalRef. See Section A.3.1.2, “Catching and Processing Signals”.

Warning

When catching messages through the API, the MessageRef property of the Catching Event is not the same as the eventType parameter of the API call. See Section A.3.2.3, “Sending Messages using API”.

A.3.2.3. Sending Messages using API

To send a message using the API, use the following function: 

ksession.signalEvent(eventType, data, processInstanceId)

Here, the parameters used are as follows:

eventType

A String that starts with Message- and contains the message’s reference (MessageRef). You can also reference a process variable using the string #{myVar} for a process variable myVar.

Examples:

  • Message-SampleMessage1 for MessageRef SampleMessage1.
  • #{myVar} for process variable myVar. The value of myVar must be a String starting with Message-.
data

The message’s data.

Value: An arbitrary Object.

processInstanceId
The Process ID of the process being messaged.

To send a Message from a script (a Script Task) or using on-entry or on-exit actions of a node, use the following API function: 

kcontext.getKieRuntime().signalEvent(
    eventType, data, kcontext.getProcessInstance().getId());

The usage of the arguments eventType and data is the same as above.

A.3.3. Escalation

"An Escalation identifies a business situation that a Process might need to react to." [2]

The Escalation mechanism is intended for the handling of events that need the attention of someone of higher rank, or require additional handling.

Escalation is represented by an escalation object that is propagated across the process instances. It is produced by the Escalation Intermediate Throw Event or Escalation End Event, and can be consumed by exactly one Escalation Start Event or Escalation Intermediate Catch Event. Once produced, it is propagated within the current context and then further up the contexts until caught by an Escalation Start Event or Escalation Intermediate Catch Event, which is waiting for an Escalation with the particular Escalation Code. If an escalation remains uncaught, the process instance is ABORTED.

Mandatory Attributes

Escalation Code
string with the escalation code

[1] Business Process Model and Notation (BPMN). Version 2.0, OMG Document Number: formal/2011-01-03 http://www.omg.org/spec/BPMN/2.0
[2] Business Process Model and Notation (BPMN). Version 2.0, OMG Document Number: formal/2011-01-03 http://www.omg.org/spec/BPMN/2.0