Workflow Builder for Integrations¶

giosg Workflow Builder is a low-code tool to integrate any systems with HTTP REST APIs that consume and output JSON or XML data and authenticate using common industry-standard mechanisms such as OAuth.

Integrations can be deployed and run from the UI in a single click, with results seen immediately.

Workflow Builder REST APIs make it easy to run integrations and check their results. An example is shown later in this document. Full API documentation is available on request.

Accessing the tool¶

Workflow Builder for Integrations is available for giosg customers at:

https://workflowbuilder.giosg.com.

When using the tool, note that only users with giosg Settings permission are able to create or modify workflows.

Building logic¶

Using Logic Blocks¶

Logic is constructing by drag & dropping Logic Blocks onto Logic Canvas from the toolbox available via right mouse click. The Start block is where execution starts from when the Logic Action is run. All blocks connected into a Logic Stack below it are then executed one by one.

Using expressions¶

Some Blocks have Expression Fields that can contain for example basic comparisons for numbers and strings. Expressions can be created using the following:

variables created in the UI that appear in the Variables Panel on the left
input variables passed manually or at runtime when workflow is triggered
common math and logic operators such as + (also for text), or, and etc.
expression functions (see below for a full list)

Variables whose values are data structures can be accessed using a dot notation. Let's presume myvar contains following dictionary/map value:

{
  "topkey": {
     "secondlevelkey": {"leaf": 10},
     "myarr": [1,2,3]
  }
}

For example, to access the value of its deepest leaf key, myvar.topkey.secondlevelkey.leaf would then be used to get it. For getting the value of the first element of myarr, myvar.topkey.myarr[0] would be used.

The following Expression functions are provided:

contains(collection, value) ➞ bool: Check whether collection contains value.

decode_jwt(str token, str key) ➞ any: Decode JWT token and return JWT token payload.

exists(str name) ➞ bool: Check whether variable exists.

length(value) ➞ int: Get length of any collection.

to_base64(any | null value) ➞ str: Convert any value to base64 encoded string.

to_number(str value) ➞ float | int: Convert string to integer or float number.

to_str(any | null value) ➞ str: Convert any value to string.

var(name) ➞ any: Accessor for variables whose names contain e.g. whitespaces

HTTP connection support¶

HTTP requests originate from out.giosg.com. Source IP addresses for all outbound HTTP traffic from giosg are documented in docs.giosg.com.

Setting HTTP request URL, headers and body¶

Enter the request URL as a quoted string into the URL field of the HTTP block.

Headers are entered as a {"name":"value", "name2":"value2"} dictionaries with both header names and values as quoted string values. Variables are left unquoted.

For HTTP body, enter the content and choose the HTTP body type from the ones that are available:

JSON (application/json)
XML (application/xml)
Form (application/x-www-form-urlencoded)

Note

Form data is entered as key=value pairs, one per line. Enclose variables inside double curly braces e.g. key={{variablename}}. Form encoding is done automatically by WFBI.

Configuring HTTP authentication¶

The following types of authentication are supported.

Basic Authentication
Custom auth header
OAuth 2.0 Authorization Code Grant
OAuth 2.0 Client Credentials Grant

To configure authentication, an integration has to usually be configured in the other system (such as Salesforce or Hubspot) first. The authentication details are specific to each such configuration.

Accessing JSON response data¶

HTTP response JSON data is automatically parsed and available as part of the response variable, such as http_response_1.json. For example http_response_1.json.topkey.secondlevelkey.leaf could be used to access the deepest-level value in the following JSON structure:

{
  "topkey": {
     "secondlevelkey": {"leaf": 10}
  }
}

Accessing XML response data¶

HTTP response XML element tree can in most cases be traversed by tag names using a dot notation, the same as by keys for a JSON structure. Given the following xml:

  <book>
    <author>Richard Adams</author>
    <title>Watership Down</title>
    <stock>1271</stock>
    <price>39,99</price>
  </book>

Then, we can simply use book.author or book.title to access the element contents. But if the tag name contains e.g. a dash - character, key access must be used. For example if tag is original-author, then book["original-author"] can be used.

Additionally:

XML attributes are accessed by prefixing them with a @ character
Sequences of identical tags (by name) are accessed using array indexing
Element (text) content is always named #text

For example, presuming this XML:

<library>
   <book author="Lewis Carroll">Alice in Wonderland</book>
   <book author="Richard Adams">Watership down</book>
</library>

Then library.book[1]['@author'] is used to access "Richard Adams", the second book author. And library.book[1]['#text'] would give the name, "Watership Down".

Special XML cases

Case 1. When you have a single child element, you will get the element itself. This is due to the nature of XML; there is no way to infer the intent, i.e. element vs. list with single element.

So in effect case such as:

<library>
   <book author="Richard Adams">Watership down</book>
</library>

Would infer the book node as a object property instead of a list. So library.book['@author'] is used to access the book author in this case.

Case 2. When you have a simple element that has just text content, no attributes, just the text content is returned. So presuming a simple book name list:

<library>
   <book>Alice in Wonderland</book>
   <book>Watership down</book>
</library>

Then library.book[1] would return "Watership down". No #text is used.

XML namespaces and entities

Namespace prefixes or entities in XML are not expanded. Consider the following xml:

<library xmlns="http://defaultns.com/"
      xmlns:a="http://a.com/"
      xmlns:b="http://b.com/">
  <a:book>
    <a:author>Richard Adams</a:author>
    <a:title>Watership Down</a:title>
    <b:stock>1271</b:stock>
    <b:price>39,99</b:price>
  </a:book>
</library>

A namespace in tag (or attribute) is simply part of the name. So here, namespaced elements can be accessed simply by including the namespace prefix and the separator with the tag name: library["a:book"]["a:title"] or library["a:book"]["b:price"].

Running integrations¶

Running manually from the UI¶

A workflow Logic Action can be run manually using the "Play" button. A results panel will automatically open with lots of information. Arbitrary test input data can also be manually provided via the UI.

Triggering integrations from Interactions¶

For Workflow Builder customers, a "Custom Action" click action is available in Interaction Builder. Any published integration workflow available in customer's Workflow Builder is selectable for running as a Custom Action.

When a Custom Action runs, all custom data fields and input fields of an interaction are sent to the workflow as parameters in the following kind of JSON payload format:

{
    "formData": {
       "name": "John Doe",
       "email": "john@giosg.com",
       "phone": "+358123456"
    },
    "variables": {
        "dataField": "dataFieldValue",
    },
    "clicks": ["NextViewButton", "InputFieldName", "AnotherElement"]
}

This data is then available in WFBI as three variables: formData, variables and clicks. The clicks are sorted in the chronological order they were clicked in, in the interaction that was run.

Triggering integrations via API calls¶

The unique trigger URL of a workflow can be retrieved by clicking the trigger URL button in the Logic Editor UI. The endpoint is of the following format:

https://api.giosg.com/workflow_builder/public/workflows/<uuid>/trigger_workflow

The <uuid> part is the UUID of the workflow.

A special wf_tag query string parameter can also optionally be added when triggering a workflow run. The system will then apply a tag to the workflow run. The tag makes it easy to identify particular workflow run(s) in the execution log UI.

To trigger workflow draft versions, change the last part of the endpoint to /trigger_draft, instead of /trigger_workflow.

When triggering a workflow, parameters can be passed to it in a HTTP POST JSON body, or as query string variables if HTTP GET is used. The JSON top-level keys, or the query string parameter names, will then be available in Logic Actions as variables with exact same names.

Reviewing results¶

Integration run results can be seen in the Execution Log, available via right click menu in the integration listing UI.

If workflow is using async mode, the results for a particular execution can be retrieved via API:

https://api.giosg.com/workflow_builder/public/execution/<id>/status

Here, <id> is the execution id of the workflow that was returned when the integration was triggered.