Messages and signals allow forms, end points, site templates and other process instances to interact with a process outside of the normal user task activities.
Messages
Messages are sent to a specific workflow process instance and can be caught by message boundary or intermediate events.
Sending Messages
To send a message to a process instance you need to know either the business key or the
All messages have a name, known as the "message reference". The message events in a process instance listen out for these references. This means you can add multiple message events to a model, each of them waiting for a different message reference.
From Forms
Messages can be sent to a process instance from a form using the Workflow - Message Action field. This field has a property where you set your message reference.
In this model, an intermediate message event pauses the workflow execution when it is reached. Its message reference is set as
To trigger this message and resume the execution, the form field would look like this:
Messages can only be sent like this if your form is part of the process you'd like to message, for example your form is part of a user task in the process instance you are messaging. This lets you message another part of the same workflow when the user task is completed. This works because task forms are supplied the business key of their process instance and the Message Action field automatically uses it.
From Scripted Actions
To send a message to an instance outside of normal workflow, for example from an end point, Workflow Script Task, Form Script Action, or even site templates, you'll need to use the Workflow worker's API and know either the business key or ID of the process instance to message.
The
function(params, credentials) {
let message = this.callWorkerMethod("workflow", "sendMessage", {
"processInstanceBusinessKey": params.businessKey,
"messageName": "ReleaseTheHounds",
"variables": {
"newvariable": "newValue",
"anotherNewOne": "another new value"
},
"userId": "TIMG",
"startUserId": "ANONYMOUS",
"historyRecording": {
"labels": {
"labela": "${PROCESSNAME}",
"labelb": "${BUSINESSKEY}"
},
"subject": {
"description": "${PROCESSDESCRIPTION}",
"userId": "TIM",
"proxyUserId": null
},
"event": {
"event": "MESSAGE",
"description": "Message Sent",
"userRole": "user",
"userId": "TIM",
"proxyUserId": null,
"private": false
},
"storeFormData": false,
"formName": "TIMSFORM",
"logSubmission": true,
"logSummary": false
}
});
return message;
}
Receiving Messages
Message events in workflow models wait for a message reference before they are triggered. Message references do not need to be unique. This means you can have several message events with the same reference in one model, all of which will be triggered when a message with that reference is received.
Intermediate Events
In this model, a user completes a task, then the execution will pause at the message event. The execution waits for a message to be received then continues to the mail task. If the message is sent to the workflow before the execution arrives at the message event, it will have no effect, and another message will need to be sent for the execution to proceed.
Boundary Messages
In this model the user task is held within a sub-process. A message boundary event is attached to the sub-process. When the message is received the sub-process will be interrupted (assuming it hasn't already completed).
Whether the sub-process is cancelled or not is set in the message event. This allows you to build sub-processes that will either end when a message is received, or perhaps allow a second flow of execution to start, leaving the sub-process in place.
Signals
Signals are similar to messages with one major difference. Messages are always sent to a specific process instance. Signals can be broadcast to all workflow instances, and any signal event with a matching signal reference will be triggered. Signals can also be sent from within workflows, using the intermediate signal throwing event.
Signal Definitions
Before you can start to use signals in your workflow model, they need to be defined in the model you are working on.
Click on any blank space in the work area, then select the "Advanced" tab. You'll see the signal definition property in the left-hand column:
In the definition you need to set the signal name and ID (it's best if these are both the same), and its scope:
Signal Scope
As mentioned above, signals can be broadcast to all workflow instances, and any that have events listening for the signal definition will respond. This means understanding signal scope is very important.
Consider this example.
An instance of this workflow has two parallel paths of execution, paths A and B. When the user task in Path A completes, the execution triggers a signal throwing event, which is caught by the boundary event attached to the user task in Path B. When it is caught Path B is interrupted.
This is a perfectly valid way of doing things.
However, the signal thrown in Path A could be broadcast to all instances of this workflow, meaning that the actions in one instance will interrupt every other active instance!
There may well be cases when you want this to happen. For example, your workflow may relate to a delivery service, and should the delivery truck break down, you need to notify every instance/delivery that is currently active.
On the other hand, if all you want to do is to throw a signal that will be caught by the boundary event in this instance without affecting any other instances, you need to change the scope of your signal definition.
The default value is Global. Changing the scope to Process Instance means that the thrown signal will be contained within this instance and that any events that are listening for this signal will only respond if it is thrown from within the same instance.
Sending Signals
As in the example above, signals can be sent using the intermediate signal throwing event in the workflow modeller.
You can also send signals from forms, end points and site code using signalEvent in the Workflow worker's API.
This example sends a signal from an end point. The signal it throws has been defined (in the workflow modeller) as having Global scope, so all instances will respond.
function(params, credentials) {
let signal = this.callWorkerMethod("workflow", "signalEvent", {
"signalName":"MyGlobalSignal",
"userId":"tim"
});
return signal;
}
Should the signal definition have a Process Instance scope, you cannot send signals to it using the API. The event listeners within the instances will only ever respond to signals sent from within the same instance.
You can target a specific instance by providing the execution ID. Execution IDs can be tricky.
As a process instance executions progress, they generate a series of child executions as each task in the instance is reached, each of which has a unique ID. These executions are represented by an array of objects.
For example, this model generates four executions.
Once an instance starts, it's possible to see the following, by calling the Workflow worker's getExecutions and providing the process instance ID:
{
"jsonrpc": "2.0",
"id": 875,
"result": {
"id": "_272",
"result": {
"result": {
"count": 4,
"list": [{
"id": "38177",
"activityId": "Signal",
"parentId": "38175",
"isEnded": false,
"processInstanceId": "38158",
"isSuspended": false,
"activeActivityIds": ["Signal"]
}, {
"id": "38176",
"activityId": "UserTask1",
"parentId": "38158",
"isEnded": false,
"processInstanceId": "38158",
"isSuspended": false,
"activeActivityIds": ["UserTask1"]
}, {
"id": "38175",
"activityId": null,
"parentId": "38158",
"isEnded": false,
"processInstanceId": "38158",
"isSuspended": false,
"activeActivityIds": ["Signal"]
}, {
"id": "38158",
"activityId": "Gateway",
"parentId": null,
"isEnded": false,
"processInstanceId": "38158",
"isSuspended": false,
"activeActivityIds": ["Signal", "UserTask1"]
}]
}
},
"jsonrpc": "2.0"
}
}
To send a signal to this instance, you need to target ID 38177, the execution that corresponds to the "Signal"
Here's how we can signal the instance from an end point.
function( params, credentials ) {
let signal = this.callWorkerMethod("workflow", "signalEvent", {
"signalName":"MyGlobalSignal",
"executionId":"38177",
"userId":"tim"
});
return signal;
}
Receiving Signals
There are two workflow events you can use to receive signals, one intermediate event that will pause an execution when reached, releasing it when a signal is received, and a boundary event that can be attached to tasks and sub-processes, interrupting them when the signal is received. These work in the same way as the message events described above.
Share this page
