Skip to content

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:

1
2
3
4
5
6
{
  "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 accounts:

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

The following types of authentication are supported.

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

For OAuth Authorization Code Grant:

  • redirect URL is https://workflowbuilder.giosg.com/oauth_callback
  • additional authorization request parameters can be given, for example to enable automatic server-side token refresh with Google by setting the access_type parameter to offline

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:

1
2
3
4
5
{
  "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:

1
2
3
4
5
6
  <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:

1
2
3
4
<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:

1
2
3
<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:

1
2
3
4
<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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "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.

Accessing run results

Integration run results can be seen in the Execution Log, available via right click menu in the integration listing UI. The API endpoint for retrieving results of a particular run is:

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

The <id> path parameter refers to the execution id of the workflow that was returned when the integration was triggered.