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