Subflow Triggering
The Flow Designer feature in ServiceNow makes it possible to build No-Code workflows. There is a difference between flows, subflows and actions in ServiceNow. The main difference between a flow and a subflow is that a flow consists of a trigger (a change in a ServiceNow table), and a subflow can either be triggered by another flow or a script. b+s Connects supports triggering subflows from a script based on events occurring on the b+s Connects gadget. This allows for endless and amazing possibilities.
Possible events
ServiceNow subflows can be triggered based on the following events.
Agent State Change Events
This event is raised when a specific channel's state changes.
| Field | Type | Description |
|---|---|---|
| event | String | Event name "agentStateChange". |
| version | Integer | API version. |
| requestId | String | Identifier to match this event to a request. |
| channelType | String | Channel type (Voice). |
| channelId | String | Channel identifier (voice_<peripheral_id>) |
| newState | String | New state (Logout, Offline, Ready, NotReady, Active, Wrapup, Unknown). |
| newReasonCode | String | New reason code. Negative values indicate no code available. |
| newReasonCodeLabel | String | New reason name. |
| newStateChangeTime | String | New state change time. |
| oldState | String | Previous state: (Logout, Offline, Ready, NotReady, Active, Wrapup, Unknown). |
| oldReasonCode | String | Previously selected reason code. Negative values indicate no code available. |
| oldReasonCodeLabel | String | Previously selected reason name. |
| oldStateChangeTime | String | Previous state change time. |
Workitem events (e.g. Call events)
There are several workitem events that can occur. The different events are workitemCreate, participantMapping, workitemConnect, workitemPause, workitemResume, workitemTransferred, workitemWrapup and workitemEnd. All these events contain the same following data.
| Field | Type | Description |
|---|---|---|
| event | String | Name of the event. |
| version | Integer | API version. |
| requestId | String | Identifier to match this event to a request (for future use). |
| id | String | Call ID or Task ID for the current work item. |
| ani | String | When there’s only one participant and the direction is outgoing, toAddress is picked otherwise fromAddress is chosen. |
| agentId | String | Agent ID. |
| state | String | Current State (Unknown, Initiated, Offered, Active, Paused, Wrapup, Ended, EndedAbandoned, EndedTransferred, EndedUnknown). |
| direction | String | Incoming or Outgoing. |
| channelType | String | Channel type (Voice, Mail, Chat, Task, Federation). |
| channelId | String | Channel identifier (voice_<peripheral_id>, <Media Routing ID>)For CCX: voice_-1 |
| ctiData | Object | Please see the ctiData reference for available data and format. |
| connectedAt | String | Date and time in UTC when the call was established (e.g 2020-07-28T09:51:17.696Z). |
| participants | String | List of participants with their address. |
| classification | String | Work item class (Customer, Consultation, Conference, Transfer, Internal, Unknown). |
| activity | Object | Object including the interaction. See activity record reference |
| participantLookupResult | Array<Object> | List of the found participant lookup entries. See ServiceNow record reference |
| associatedParticipant | Object | The assigned record of the participant lookup. See ServiceNow record reference |
| associations | Array<Object> | List of all records that got assigned to the interaction over the b+s Connects application. This includes the assigned participant. See ServiceNow record reference |
| capabilities | Array<Object> | List of actions that can be carried out. |
ctiData
The availability of the following fields is dependent on the Finesse version. Please see the Finesse documentation for more details.
| Field | Type | Description |
|---|---|---|
| callVariable1-10 | String | Peripheral variables 1 to 10. |
| user.< variable > | String | ECC variables. |
| DNIS | String | DNIS of the call. |
| callType | String | Type of the call. |
| dialedNumber | String | Dialed Number of the call. |
| outboundClassification | String | Outbound call classification (VOICE, FAX, ANS_MACHINE, INVALID, DO_NOT_CALL, or BUSY). |
| callKeyCallId | String | The unique number for the call routed on that particular day (CCE only). |
| callKeyPrefix | String | The day when the call was routed (CCE only). |
| mediaId | String | Media routing ID. |
| queueName | String | Name of the queue. |
| queueNumber | String | Queue name ID. |
| wrapUpReason | String | Currently set call wrap-up reason. |
Activity record
The activity is an object containing the interaction sys_id of the workitem and the recordType (which in this case always is interaction).
It is possible that the interaction is undefined for the workitemCreate event.
| Field | Type | Description |
|---|---|---|
| id | String | Unique identifier of the ServiceNow interaction |
| recordType | String | Type of the activity record. This is always interaction. |
ServiceNow record
It is possible that the field associatedParticipant is undefined.
ServiceNow records consist of the following fields.
| Field | Type | Description |
|---|---|---|
| id | String | Unique identifier of the ServiceNow record |
| recordType | String | The ServiceNow table of the record. e.g. sys_user |
| name | String | The name / title of the record. |
Error Events
This event is raised when an error is encountered in b+s Connects.
| Field | Type | Description |
|---|---|---|
| event | String | Event name "error". |
| version | Integer | API version. |
| requestId | String | Identifier of the request that might have caused the error. This is empty if the source of the error cannot be detected. |
| message | String | Short message describing the encountered error. |
How to create a subflow
Please refer to the official ServiceNow documentation in order to see how to create subflows and actions. Depending on your subscription you may also be able to use the features of ServiceNow's IntegrationHub in order to have even more great possibilities.
ServiceNow role required: admin, flow_designer or delegated_developer
Race conditions
Subflows are executed asynchronously, this means that they could interfere with each other when altering the same table. Channel Blending can be affected as well if a subflow influences the agent state.
Performance consideration
Running these Subflows within a specific scope instead of the global scope can result in a faster execution time and reduce the above mentioned race side effects. For more information, refer to this community thread.
Input parameter
In order to make use of the parameters passed by an event, an input parameter with the name bsevent of type Object has to be created.
This object paramter can then contain the needed fields depending on the event that should be triggered. See the tables above for the possible input paramters the bsevent object can contain.
The bsevent parameter has to be created on the subflow even if the parameters are not used, otherwise an error will be returned.
Output parameter
b+s Connects offers the possibility of reacting on the output of a subflow. There are 4 different scenarios available:
No output
Don't return anything in order to just execute the subflow without causing anything to happen on the b+s Connects gadget.
Pop ServiceNow Records
Return a ServiceNow record in order to open it up. To do so the output needs to consist of the two required fields id and table and the optional field interaction. Where id has to contain the sysid of the record within ServiceNow, the table field has to contain the name of the ServiceNow table this record is part of, and the interaction can contain the interaction sysid, in case you want to pop the record in the Workspace within an existing interaction.
Create an error on the b+s Connects gadget
In case of an error occurring on the subflow it is also possible to return it to the agent and display it accordingly. Therefore the output parameter has to contain a field named type with the value error and a second field called message containing the error message that you want to display to the agent.
Write a trace entry in the b+s Connects gadget
In order to make a log entry in the b+s Connects gadget you can add the following two fields to the output parameter: type with value trace and message containing the message to log.
Multi Tab behaviour
In case the gadget is loaded more than once, only one of the tabs is actually triggering the subflow, so you don't have to worry that wathever the flow does will be made multiple times. Nevertheless the screenpops/errors will be displayed on all the open browser tabs where the b+s Connects gadget is loaded.
Reloading the b+s Connects gadget
In case an agent reloads the b+s Connects gadget during an active workitem, the On Workitem Create event will be triggered a second time. All other events will not be executed again in case of a reload.
Samples
We recommend using the sample subflows available as an update set in order to get started. The update set can be downloaded here. There are three different Subflows and one action available. These examples are meant to be used as a starting point and most probably it doesn't make sense to use them in production without any modifications. All samples include all the possible input values (except for Cisco ECC variables) even if most of them are not used in the scripts.
The following samples reference the above mentioned update set.
b+s Connects Workitem Event Sample
This sample shows how to create an incident in case the event was triggered based on an incoming voice call. It adds the Wrap Up Reason in the "short description" field and puts the caller assigned to the interaction in the "opened for" field.
The created incident will then pop on the agents screen.
For outgoing Voice calls, the script will add a log message to ServiceNow and also return a trace message to the b+s Gadget.
If the event was triggered from a channel other than the voice channel, it will write an error log to ServiceNow and return an error to the b+s Gadget that will be displayed to the agent.
b+s Connects Agent State Change Event Sample
This sample shows how to change the AWA state in case of a Voice agent state change. It uses a sample action that is also part of this update set to trigger the state change.
Be aware that the action script to change the AWA state doesn't include any channels. In case you want to set states for just some channels, you have to adjust this script.
b+s Connects Error Event Sample
This sample adds an error log message to ServiceNow.