IMIconnect Developer Hub

Welcome to the IMIconnect developer hub. You'll find all the resources to help you get started with IMIconnect quickly. We are here to support you if you get stuck. Let's jump right in!

Get Started

Flow Builder

Flow Builder is an editor that allows you to create interactive communication flows with minimal programming or scripting efforts. It has an easy-to-use drag and drop interface called 'Flow Canvas' that allows you to build communication flows using 'Nodes'. The communication logic is built on a flow canvas by connecting and configuring nodes in a logical order. A node contains complete information such as initiation, execution, error-handling, condition, notifications, logic - switch statements, and decision logic required to automate complex processes.

A service has one or more flows associated with it, these flows are triggered by rules defined in the service, there can be multiple rules defined, to trigger a flow.

Benefits of using Flow Builder:

  • A flow can have simple validations and expressions.
  • A flow can be grouped for better design control and usability.
  • A flow can be invoked using a rule within a service.
  • A flows can be replicated to create a new flow.

There are two types of flows

  • Flow
  • Voiceflow

List of nodes under each flow.

Flow Builder Interface

Flow Builder Interface is an interactive, easy-to-use interface to build and manage communication flows in simple steps via intuitive drag-and-drop configurable nodes.

The User Interface(UI) has the following sections:

Feature
Description
  1. Flow Canvas

This is the region where you can build and configure a flow.

The flow canvas allows you to drag and drop nodes from the Nodes Palette and connect node using connectors to build a flow

  1. Nodes Palette

It contains all available 'Nodes'. Drag and drop a node into the flow canvas to use it. For more information, see Nodes

Catagories: Nodes are categorised into groups based on their usability. When you click a node category, nodes of the selected category are displayed.

  • FLOW - These nodes contain most common functionality, hence these nodes used by the majority of the flows.

  • UTILITIES - These nodes are designed to support the functionality of message flow.

  • INTEGRATIONS - This category of nodes are custom nodes build with third-party APIs to connect with their respective systems.

  • VOICE NODES - These nodes are designed to support the functionality of a voice flow.

SearchBar: Allows you to search a node from the list of available nodes. You can see the nodes displayed, as you type in the search box.

For more information on connectors, see Connectors

  1. Bottom-line Toolbar

Contain tools to manage the flow, nodes and the activities on flow canvas.

  • Toolbar: Contain tools to manage activities on flow canvas.
  • Shortcut Key: Click to view keyboard shortcut to use the flow builder.
  • Documentation: Click on 'Documentation' icon to view the flow builder help section.
  • Debug: Click to start the flow in debug mode, see Debug
  1. Flow Management
  • Setting: Define global session parameters for the flow.
  • Share: Generate a link to share the flow with other users.
  • Edit : Click to open the flow in edit mode
  • Notepad: Provide information about the flow.
  1. Flow Version

Displays the current version and state of flow. Click to view the version of the flow. For more information, see Flow Versioning

Toolbar

The toolbar contains buttons to manage the nodes and flow on the flow canvas.

Toolbar button
Description

Undo

A multi-level undo that reverses an action and its relative effect.

Redo

A multi-level redo that will undo a previous action.

Delete

Deletes a selected node or a connector.

Auto arrange

For better visibility, all the nodes in the flow are arranged in an order from left to right with equal distance between each node.

For example, a node that is invoked in the final stage will be moved to end of the flow (extreme right.). For more information, see Configuring Events

Actual Size

Resets to default canvas size (from zoom in/out level)

Fit to screen

Flow canvas gets refreshed and the whole flow with all the nodes is display in the flow canvas.

Zoom in

Magnify the canvas.

Zoom out

Shrink the canvas.

Session Parameters

When you double-click a node, a configuration window pops up with various configuration tabs that allow you to define and configure 'Session Parameters' and 'Custom Log IDs.'

By default, a predefined set of session parameters covering popular channel attributes are available, however, you can add custom variables to address flow requirements. These parameters can be subsequently accessed within each node either to retrieve or assign a value.

Custom Logs

Custom logs can be accessed within each node to log the state of session parameters

For more information, see Defining Session Data and Custom Logs

Nodes

A Node is a discrete function that executes in a flow. These nodes are based on their configurable properties are classified into different categories for easy identification and navigation. You can drag and drop nodes to place them on the flow canvas, the node snaps to canvas-gride. You can drag a node to any position on the canvas gride that is free, however, you cannot place a node vertical (over and under) to a node.

Nodes are connected in a logical sequence using connectors to form a flow. Each node comes with specific configurable properties. Double-click to open a node and supply it with appropriate data to configure it.

Nodes encapsulate an action or a decision to form the basis of a flow. Each node performs a specific function, and in some cases depending on the outcome, can decide between two possible paths to continue. For a flow to work, a node must be connected to other nodes using connectors and configure the events.

There are three elements of a node, a node accepts input, provides output and setting to configure the events that node has to perform. When you delete a node in a flow, the successive connectors (event nodes) are also deleted and there might be a need to reconstruct the flow.

  • All node comes with predefined edges, except the 'Evaluate' node.
  • A node edge can be connected to another node with a connector.
  • A node edge is used to end the flow, by configuring the 'End Flow Setting'

Node Events

A node event is a possible outcome of a node. Depending on the data supplied, a node can have one or more outcomes. Events of a node are either connected to the next node or configured to terminate the flow.

Node Events in a node helps to define and configure possible outcomes of an event. By default, the node event tab lists the possible outcome of that particular node, you can define a node event and assign a result label.

To view Node Events of a Node

  1. Select and double-click a node to open the node configuration window
  2. Click NODE EVENTS tab to see the list of node events.

Connectors

Connections are made using connectors within the nodes. Connectors appear when you point, hold and drag a node edge towards a target node (except the Start node, as it does not accept inputs). When you are about to connect an event to the target node, the target node is highlighted. A dotted line appears till you connect the event. After the event is connected, the dotted line turns into a continuous line.

Flow

A flow is communication service built using nodes by defining business logic to address a business requirement. Flows are built as part of a service and can be triggered using a rule. Refer Invoking Flows.

Creating a Flow

  1. From service Settings, click Flows.
  2. Click ADD NEW FLOW. The 'create a flow' screen appears.
  3. To create a new flow, enter a Name for the flow and select the Flow type Flow or VoiceFlow.
  4. To create a Voice flow select Voice option and then select the folder from select media folder drop-down. The media files should be uploaded before you create a voice flow.
  5. To copy an existing flow, select the flow from the Copy an existing flow drop-down.
  6. Click NEXT.
  7. The flow builder screen appears with a Start node.
  8. Drag-and-drop or double-click the nodes on the flow canvas as per the business logic.
  9. Drag the exit point of the source node towards the left side of the target node. Some nodes may have two or more exit events. At least one should be connected to continue the flow.
  10. Release the mouse to connect the node.
  11. Set the default session data that would form the input to the flow.
  12. Enter the Session Key if the flow type is flow.
  13. Click SAVE. All the errors and warnings are displayed in the Errors & Warnings pane at the right side of the flow canvas.

When msisdn is configured as a session key, the flow will create a new session per msisdn account.

Working with Error and Warnings

When you save a flow, it might be incomplete or have errors. When you attempt to save incomplete flows, errors are generated and listed under ERROR & WARNING pane, at the right side of the flow canvas. Most of the errors and warnings are self-explanatory, hence you can address the errors by editing the flow.

Errors and Warnings are generated under the following context,

  • When you save an incomplete flow.
  • When a mandatory parameter is left incomplete in a flow.
  • When a node edge is left unassigned.
  • When a connector is incomplete.

Editing a Flow

You can edit a flow when you need to fix an error or update a flow. However, you can also edit to fine-tune the flow as per the updated business process.

  1. Search/Locate a service on the services dashboard.
  2. Select/Click the service block.
  3. On the setting page, click Flows, on the left pane
    All the Flows are displayed on the flow list page.
  4. Locate the flow you want to edit, click the corresponding Manage button and select Edit from the drop-down list. The FLOW INTERFACE is displayed.
  5. On the top right corner of the flow canvas, click Edit
  6. Now make the necessary modifications to the flow and click SAVE. For more information, see Flow Version

When you 'save' a flow, it is saved as 'Draft Workflow' and when you make the flow live, the flow status is changed to 'Live Workflow'.

Flow States

DRAFT WORKFLOW: A flow is saved as 'draft workflow' if the flow is partially complete and you are still working on building the flow

You saved the flow, but there are errors in the flow that are required to be addressed. This can also be an incomplete flow. When the flow is in DRAFT WORKFLOW, you will notice the corresponding Attach Rule button is disabled.

LIVE WORKFLOW: The flow is successfully created & saved without errors. The flow is production-ready now. You will notice the corresponding Attach Rule button is active.

Sharing a Flow

If you want to share a flow with an external user for a brief view, you can generate a shareable link. Now you can now share the link and password with the user using various channels like email or chat.

To view the flow, the targeted user is required to click on the shared link and enter the password when prompted. No other credential or additional information is required to access the flow/link.

  1. After a flow is created and successfully saved, click the share icon available in the top right corner of the flow screen.
  2. The share flow settings screen appears, as displayed in the figure below.
  1. Turn the slider towards right to enable the Link sharing,
  2. Click copy icon at the end of the URL to copy the URL into the clipboard.
  3. Enter a password and click DONE.

Now, the URL and password can be shared via email or any other medium. When the user clicks on the URL, a password prompt screen appears. On entering the correct password, the respective flow is displayed.

Working with Node, Connectors, and Events

Connections are made using connectors within the nodes. Connectors appear when you point, hold and drag a node edge towards a target node (except the Start node, as it does not accept inputs). When you are about to connect an event to the target node, the target node is highlighted. A dotted line appears till you connect the event. After the event is connected, the dotted line turns into a continuous line. The figure below illustrates these steps.

Each node can have multiple incoming and limited outgoing edge that are used to configure events. Each node has its different set of outgoing events called 'Node Edges'. If the node does not have an outgoing edge, then it must be configured to end the flow.

  • To configure a node, drag-drop an edge anywhere on the screen and select a relative event. The below image represents a configured node.

  • You can connect a source node to a target node, however, you cannot loop back to the immediat previous node.

  • To modify a configured event, select and double-click the node/connector and modify the action required at the respective location, click Save to complete.

  • To delete a node or a connector, point, and select the respective node/connector, press delete button on the keyboard. The selected node/connector is deleted and disappears from the flow canvas.

For easy comprehension of the flow, based on the node event, the connectors are displayed in different colors.

  • A green color line indicates the flow continuation events in the flow.
  • An orange color line indicates time-bound events of the node.
  • A red color line indicates the error events that are used to handle errors or end the flow.

Invoking Flows

There are various ways to invoke a flow within a service, some of the way to invoke the flows are listed below.

Flow
Voiceflow
  • You can invoke a flow using rules.

  • You can invoke a flow from
    another flow.

  • You can invoke a flow using an event scheduler.

  • You can invoke a voiceflow using a rule.

  • You can invoke a voiceflow using Messaging API.

  • You can invoke a voiceflow using a wokflow.

  • You can invoke a voiceflow within a voiceflow.

  • You can invoke a voiceflow using an event scheduler.

Important considerations:

  • A flow must begin with a 'Start' node and terminate with an 'End Event' of a node.

  • All nodes in a flow must be stitched using a connector and appropriately configured.

  • Ensure all error and warnings are fixed, before publishing a flow.

  • A voiceflow must start with a Start node and end with a Disconnect node.

  • A voiceflow must be compiled before using it in a flow.

  • All data in view mode is read-only.

Compile a Flow

This option is applicable to voice flows only. A voice flow must be compiled before using it in a service.

Managing a Flow

In a service, flow management is performed on the services setting page. A service has one or more flows associated with it, these flows are configure by rules defined, there can be multiple rules defined, to trigger a flow.

  1. Open a service.
  2. On the services page; under Setting, click Flows.
    All the flows under the selected service are displayed. The activities performed on this page:
Activity
Description

ADD NEW FLOWS

Click to create a new flow.

List Flows

Sorting the flows based on the 'Flow type' choice; available flow types are ' Voice-text' ' 'Flow'.

Sort Flows

Sorting the flows based on the choice made. The choices are ' Newest First' or 'Last Modified'

Attach a rule

Click to configure a rule to invoke the flow.

Manage

Allows you to perform various activities on the corresponding flow.

Manage - Working with a Flow
Click Manage button corresponding to a flow to view a list of activities you can perform with a flow.

Select
Description

Edit

Open the flow canvas in full view. Provides you with the option to edit, debug, work with flow versions.

Report

Summary of flow activity in visual and numerical values.

Export

Allows you to export the Flow.

Delete

Delete the flow and removes it from the flow list.

Debug

The Debug feature in a flow details the execution and transactional details. It helps you to view the sequence of activities in a node and progress of the flow. You can search and filter a transaction log using the search feature.

Debug panel displays following details of each flow execution:

  • A list of most recent transaction logs of the flow.

  • Option to drill down into details of each Transaction by clicking on the Transaction ID.

  • Date and Timestamp of a given transaction. You can filter the logs based on selected date range and day ( Logs are available for the latest 30 days)

  • Duration: Total time the system has taken to execute the request in milliseconds.

The DEBUG button is present at the right bottom of the flow canvas.

Click Debug to open the split window.

Important considerations

  • Ensure to save and make the flow live before executing the flow.
  • Most recent 10 transactions are listed, however, you can use the timestamp to view transactions up to 30 days.
  • Click on a transaction sequence to view(drill down) the details of each flow.

Using Debug Feature

You can make use of the Debug feature to view the Flow sequence, look out for error or unexpected behavior and transaction details of each Node.

  1. Search/Locate the service on the services dashboard.
  2. Click on the service you want to debug.
  3. On the setting panel, click Flows.
    All the flows are displayed in the flow list.
  4. Choose the flow you want to Debug, click the corresponding MANAGE button and select EDIT.
    The Flow canvas opens in full view mode.
  5. Click Debug button available at the bottom right corner of the flow canvas.
    The debug screen appears split view mode (two halves screens), the upper part contains the Flow with each Node assigned a number. The lower section of the screen presents the Transaction Details of the Flow.

Start Debug activity

Debug functionality lists the events that took place while the flow was executed. Debug helps to view transaction details of the Flow and activity particulars of each Node. Using Debug you can view and ensure that the flow meets the goals it is designed for.

Feature
Description

Transaction logs

The details below this heading are of Transactions log.

DECRYPT LOGS

Provide a passcode to decrypt and view transaction details.

Note: Encryption is enabled when the 'DEBUG LOGGING' option is enabled on the General setting page.

Contact your IMIconnect admin for Decryption passcode.

Help

View information about Debug feature.

Refresh

Click to refresh the transaction log details.

Close(X )

Click to close the split windows mode.

Date & Time

Date and Time of the Transaction ID.

Transaction ID

Transaction ID of the Flow, Click the transaction ID for a drill down node level details and the flow

Search

Search a particular transaction using 'Traansactional ID' or by choose a time stamp.

Invoked By

The Rule that invoked and started the Flow.

Time Elapsed(s:ms)

Total time taken to complete the Flow in ms/s

Laste Node

Sort

sort icon s are availabe for each of the heading, click to sort the details of the column in ascending or decending order.

View Debug logs

‘Transactional Logs’ are set of records that contain the sequence of all the activity related to the flows. The log records include details such as the timestamp, title, execution status as well as an option to view detailed log.

The most recent 10 transaction logs are displayed by default, however, you can use a timestamp to view transaction logs.

  1. Click the datestamp under Transaction Logs
  2. Select Custom Range button to define a datestamp, choose From and To dates from the calendar.
  3. Click Apply and search.
    The Transaction IDs between the selected dates are displayed.
  4. Click a Transaction ID to view additional details.
  5. The selected Transaction ID is displayed near the Transaction logs and is displayed in pink color. The table below details now display the details of the Transaction ID.
Name
Description

Transaction ID

The Transaction ID generated when the flow was invoked by a Rule.

Flow Time Elapsed

Time required to complete the flow in millisecond or seconds

Invoked by

The rule that triggered the flow.

Sequence

The sequence of node in the flow.

Time Stamp

Execution date and time of the node.

Node ID - Label

Name and ID of the node in execution at a timestamp.

Time Elapsed

Response time to execute the Node.

  1. Click a record to view the Flow sequence.
  2. Click |> to view the drill-down of the sequence.
    To copy Data, click the clipboard icon next to available data.
  3. Toggle |> to close the drill-down view.

When you click on the Transaction ID records in the table, you will notice that the corresponding Node is selected in the other pane.
You can sort the Time Stamp and Node ID by clicking the icons next to it.
Use F12 function key to toggle between full screen and split screen.

Flow Builder