I just noticed a new feature in the Yokohama release related to the Flow engine. There is a new action, called Wait for Message. This is a great and maybe a long-awaited feature, because now external content can be sent to the Flow context.
Let's see how it works
When a Flow starts a new record is created in the Flow engine context (sys_flow_context) table. The context ID will be important for us, let's keep it in mind.
When we build a Flow, and if some part of the logic expects data from outside the context, we need to add the Wait for Message flow action. This is a simple one, with one mandatory and two optional input parameters:
The Message parameter must be provided, this will be the identifier, which we need to send to the Flow. This is similar when we define an event in the classic WorkFlow and use the Wait For Event activity.
If it's not guaranteed that the message will be sent to the Flow context within the foreseeable future, it is recommended to enable the timeout option. If it is enabled, the Timeout field defines how long the flow waits before continuing its operation.
Sending message to the an active Flow
The next important step is to clarify how the message can be sent to the Flow context. There is an out-of-the-box available API, called FlowAPI. This API includes several functions, but we will focus on sendMessage(...).
Below is a short explanation of this function.
sn_fd.FlowAPI.sendMessage(String contextSysID, String message, String payload)
The sendMessage function expects three parameters:
- Sys ID of Flow or Subflow context record
- The message itself (Remember this is the content of the Message parameter in the Flow action.)
- String-type data which can be any kind of information provided to the Flow context. (It can be also JSON, but it needs to be stringified.)
Use cases
Below, you can read two use cases that illustrates how this feature can be used.
1. Sending message to a Flow, triggered by a task event.
There is a simple Flow, defined for the Incident table. The Flow starts when the Incident state changes to In Progress.
When the state of the Incident changes to In Progress, the flow starts. The next image represents the Flow context.
The next step is to send the message to the Flow context. We can get the context ID from the Flow engine context table based on the source table and sys_id of record. You can use additional filters, depending on the Flow definitions. (There can be multiple Flows defined to a record.)
var gr = new GlideRecord('sys_flow_context');
gr.addQuery('source_table', '=', 'incident');
gr.addQuery('source_record', '=', 'a623cdb073a023002728660c4cf6a768');
gr.addQuery('state', '=', 'WAITING');
gr.orderByDesc('sys_created_on');
gr.query();
if (gr.next()) {
var contextId = gr.getUniqueValue();
gs.info(contextId);
sn_fd.FlowAPI.sendMessage(contextId, "FLOW_MSG_INC", JSON.stringify({
param1: "Test",
param2: "Another content"
}));
}
Once the script is executed, we can see that the Flow is finished and the sent data can be viewed on the context page.
2. Sending a message to a Flow triggered by a script.
A Flow or Subflow can also be executed via script. Depending on the execution type, it can be synchronous or asynchronous. In our case, synchronous execution is not relevant, we are focusing on the asynchronous one. The following code snippet executes the Flow.
(This code was copied from the Flow Designer, I just modified it a bit to retrieve the Context ID.)
try {
var inputs = {};
// TODO Need to add all input parameters
// Start Asynchronously: Uncomment to run in background.
var flowStartResp = sn_fd.FlowAPI
.getRunner()
.flow('global.wait_for_message_test_flow')
.inBackground()
.withInputs(inputs)
.run();
// The context Id can be retrieved using the getCotextId() function
gs.info(flowStartResp.getContextId());
} catch (ex) {
var message = ex.getMessage();
gs.error(message);
}
Once the function is called, the Flow starts and some information (including the context id) is returned. We need this ID to send message to the Flow.
Finally, sending a message to the Flow is simple - just like in the previous example, but now we don't need to retrieve the context ID from the database.
var contextId = "...";
var flowMessage = "FLOW_MSG_INC";
sn_fd.FlowAPI.sendMessage(contextId, flowMessage, JSON.stringify({
param1: "Test",
param2: "Another content"
}));
And that's it. 🙂
Closing words
I'm happy because I have been several situations where this feature was missing. Now that it's available, I think it can be the key to efficiently solving certain implementation tasks.
1 Comment
