Using workflow builder with interactions

Overview

This tutorial explains how to use interaction builder to trigger and pass data to Workflow builder integrations.

Prerequisites

Interaction Builder and Workflow Builder need to be installed and enabled in your account. Contact support@giosg.com for help.

See Connected accounts documentation on how to setup authentication from workflow builder to the integrated system.

See Getting started with Workflow Builder integrations for integration system requirements. Create an interaction noting that we will use workflow integrations to map the interaction's element values to the properties required by the integrated system's APIs.

Triggering interactions

Published workflows are available for running from interactions using a "Custom action" click action. In the Actions menu for an IB button, select "Custom action" and select the name of the appropriate workflow from the dropdown menu.

Warning

Custom action does not submit to giosg by default. Therefore, it is highly recommended to add a regular "Submit" action to the click actions timeline before the "Custom action". This is to prevent data loss in case the integration fails - data will still be saved with the interaction's form submissions.

Passing data from an interaction to a workflow

On triggering a workflow from an interaction, data that has until that point been collected from the visitor’s actions is passed to the workflow as a JSON object with the following format:

{
    "clicks": ["nextViewButton", "anotherElement", "submitButton"],
    "formData": {
       "name": "John Doe",
       "email": "john@giosg.com",
       "phone": "+358123456"
       "checkbox": true,
       "dropdown_item": "Second item",
       "radio_select": "option 1"
    },
    "variables": {
        "dataField": "dataFieldValue",
    }
}

• formData: holds form input fields (text, dropdown selects, radio selects and checkbox elements) with element name as the attribute names and user input as value. See Interaction builder form data documentation
• clicks: an array of button element names, in the order that they have been clicked.
• variables: the custom data fields in the interaction. Refer to our interaction builder JS api for instructions on using javascript to set data to custom data fields.

This data can then be accessed within workflow builder using for example: formData.name, variables.dataField, and clicks[0]

Property names used in the workflow need to match the interaction's element names exactly.

Notice

Be aware: element names passed to workflow builder are case sensitive. Spaces are transposed as underscores (i.e. Element name) will be received as Element_name.

Custom data fields are always initialized as empty strings. Form data is not. If no value is set to a custom data field, it will be still be accessible in the workflow variables object with value "". An empty text input field, however, if not filled before triggering the corresponding workflow, will not be included in the formData object.

Passing data from a workflow to an interaction

To pass data from a workflow to the interaction that triggered it, create a variable in the workflow with an identical name to a custom data field in the interaction. The value given to the workflow variable will then be set to the interaction's data as well.

To check the custom variable's value in interaction builder, add an action sequence after the "Custom action". Under "..check if..." select "Custom data field equals", select the name of the data field from the dropdown, and type in the value set in the workflow. When the interaction detects that the variable value is set, it will run any following actions. For example (data field is "status"):

See workflow builder blocks documentation for more information about setting values to variables in workflows.

Alternately, data field values can be checked using interaction builder javascript apis, for example:

in the workflow a variable "result" is set to "finished", in the interaction, a data field named result can be checked after triggering an interaction with "Run custom Javascript" action:

if($i.dataFields.status ===  "finished") {
    $i.views.Thank_you.switchTo();
}

What's next?

• Triggering integrations via APIs
• Using interactions as interfaces for chat console apps