Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 22. Collaboration mechanisms

Elements with execution semantics use collaboration mechanisms. Different elements use the collaboration mechanism differently. For example, if you use signalling, the Throw Signal Intermediate Event element sends a signal, and the Catch Signal Intermediate Event element receives the signal. That means Red Hat JBoss BPM Suite provides you with two elements with execution semantics that make use of the same signal mechanism in a collaborative way.

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 KIE session instance.

For external system interaction, use Send and Receive Tasks with proper handler implementation.

Escalations
Used as signalling between processes to trigger escalation handling.
Errors
Used as 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.

22.1. Signals

Signals in Red Hat JBoss BPM Suite correspond to the Signal Event in the specification 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.

22.1.1. Triggering Signals

The following Throw Events trigger signals:

  • Intermediate Throw Event
  • End Throw Event

Every signal defines its signal reference, that is the SignalRef property, which is unique in the respective session.

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

Default (ksession)

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

  • Singleton: All instances available for the KIE session 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 22.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 the External Send Task manually. Use the org.jbpm.process.workitem.jms.JMSSendTaskWorkItemHandler work item handler, 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 22.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 is 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, specify the following data inputs in the DataInputAssociations property of the signal event in the Process Designer. See Section 22.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. The parameter is optional.
  • SignalDeploymentId: The target deployment ID.

Figure 22.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, that is to limit a number of sessions 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>
Copy to Clipboard

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>
Copy to Clipboard

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.

22.1.2. Catching and Processing Signals

Signals are caught by the following catch event types:

  • 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 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, enter 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”.

22.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)
Copy to Clipboard

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 signalled process.

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);
Copy to Clipboard

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());
Copy to Clipboard

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

22.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.

22.2.1. Sending Messages

Like signals, messages are sent by throw events of one of the following types:

  • 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.

22.2.2. Catching Messages

The process for catching messages does not differ from receiving signals, with the exception of using the MessageRef element property instead of SignalRef. See Section 22.1.2, “Catching and Processing Signals” for further information.

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 22.2.3, “Sending Messages Using API” for further information.

22.2.3. Sending Messages Using API

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

ksession.signalEvent(eventType, data, processInstanceId);
Copy to Clipboard

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 Task or using on-entry or on-exit actions of a node, use the following method: 

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

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

22.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.

Attributes

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
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat