Flows & Handlers

Flows is a set of statements, written like pseudocode using simplified language, for implementing integrations.

Flows is a set of statements like pseudocode, written using simplified language, for implementing integrations.

Introduction to Flows

Flows act as a neural schema for system integration, carrying out the whole integration process end to end. The flow is responsible for handling business logic, making API calls to the targeted system, formatting and validating data, logging transactions and so on.

Flows are created by developing a logical program sequence using lines of code-representation known as Handlers. Handlers form the backbone of every Flow.

What are Handlers?

Handlers are statements used to build a flow, in the form of code-representation by following an algorithmic approach. Every handler has its functional logic and requires a certain set of parameters to be defined to carry out its activities. Multiple Handlers are available to the user to build their flow.

Some example functionalities that Handlers can perform include

  • Making API calls to any system

  • Assigning data to variables

  • 🔀 Mapping of the API fields

  • 🗒 Display log messages

  • Sending data to the destination system in the required format

  • 📩 Sending emails and so on

The same handler can be used N number of times in a Flow.

How to use Handlers?

Simply drag and drop Handlers to the ‘Play Area’ to include them in your Flow. Once it is positioned in the coding area, its parameters need to be assigned. These parameters are different for each handler and are discussed in detail below.

Drag & Drop Feature

Handlers can also be copied, moved, and commented on within the Play Area and can also be deleted when they are no longer needed.

Selecting Multiple Handlers

Multiple Handlers can be selected by selecting the checkbox alongside each handler statement. Once the handlers are selected, user may Cut/Copy/Delete the statements as needed.

Available Handlers

API Calls

Triggers an API Call in which you can pass parameters and payload to any system. The API responses will be stored in a defined variable which is available for further usage in the Flow.

API Call Handler

It is recommended to use the If, Else handlers after the API call handler, to ensure the validity of the API response.

Parameters

Definition

Type

Systems

Platform to send and receive responses

Choose from the dropdown list

API

API endpoints of the selected system. Depending on the Platform chosen, the list of API’s in the dropdown changes.

Choose from the dropdown list

Response Variable

Stores API response

Example: customer_info, create_customer_data, etc

Variable

Payload

Request Body. Information sent along with the API call

Variable (defined), JSON, Array

URL Arguments

Arguments used in a dynamic URL.

API URL: /api/customer/{customer_id}/fetch

URL Argument: {"customer_id":"2"}

Formatted URL: /api/customer/2/fetch

In this case, customer_id is replaced with the number 2.

Variable (defined), JSON

Parameters

Request parameters

API URL: api/customer/get/?format={format}

Query Params: {"format":"json"}

Formatted URL: api/customer/get/?format=json

Here, format = json will be the query parameters.

Variable (defined), JSON

Incrementer

Increments the value of a specified variable by a given step.

Incrementer Handler

Parameters

Definition

Type

Variable

Variable to be incremented.

Example: line_number, total_records

Variable (defined)

Value

Value by which the respective variable is increased

Numeric, Variable (defined)

Example

Increment variable line_number by 1

Here, the variable line_number will be incremented by value 1

Formatter

The formatter is used to stringify/dump the JSON.

Formatter Handler

Parameters

Definition

Type

Value

Data to be formatted.

Example: orders_summary, ["test", "array", "data"], {'data': orders_summary}

Variable (Defined), Array, Dictionary

Variable

Stores formatted value

Variable

Delimiter

One or more characters for specifying boundary between separate entities

Line ending

Default Value

Available Options

  • JSON Dumps - the output might include white-spaces.

  • JSON Dumps with separators - Eliminate white-space. To get the most compact JSON representation.

Try Block

The Try Block is used to catch an error.

No parameters are assigned for the Try Block

Exception Block

The Exception block handles the exceptions caught by the Try Block

Exception Handler

Parameters

Definition

Type

Catch

Types of Exception

Example: Exception, ValueError

String

Variable

Stores exception data

Variable

Email Sender

Sends an email from the Flow to the assigned recipient list.

Parameters

Definition

Type

Send To

Recipient emails in comma-separated values

String

Subject

Subject Line of the email

String

Message

Body of the email

String

Initialize Variable

Assigns and stores data in the specified variable which can be used in the Flow, after the variable declaration.

Initialize Variable

Available Options

Parameters

Definition

Type

Value

String/Non-String

Choose from drop-down list

Value or data assigned to a variable

Examples:

  • String:Hello World

  • Non String:

    • Number ⇒ 0

    • Array ⇒ [1, 2, 3, 4, 5]

    • Dictionary ⇒ { "customer_id": 123}

Mixed

Name

Variable that stores the assigned value.

Variable

Example 1

Assign value 0 to variable Area_Code

Here, 0 is assigned to the variable: Area_Code

Example 2

Assign value orders_info[‘data’][‘customers’] to variable customers

Here, the value in the dictionary: orders_info[‘data’][‘customers’] is assigned to a variable: customers

Example 3

Assign value {"entity_id": customer['id'], "shipto_id": ""} to variable customer_info

Here, the dictionary {"entity_id": customer['id'], "shipto_id": ""} is assigned to variable customer_info

Example 4

Assign value dependent_customers[item['customer_id']]['customer_id'] to
variable mapped_orders['hdr']['customerId']

Here, the value in dictionary dependant_customers[item['customer_id']][customer_id] is assigned to variable mapped_orders['hdr']['customerId']

Modify Variable

The handler is used to change or modify the contents of a variable (mainly array and dictionary), that has already been used in the flow.

Modify Variable Handler

Available Options

Parameters

Definition

Type

Variable

Variable to be changed or updated. This variable should be already used in the flow and is to be modified

Variable (defined)

Value

String/Non-String

Choose from drop-down list

The data to replace or change in the variable

JSON, Array

Type

Type of data to be modified

  • Dictionary/JSON

  • Array

Choose from the dropdown list

Action

Action to modify existing data

  • Append ⇒ Push a value into the array as the last element

  • Update ⇒ Push a value into the dictionary as last element

  • Assign ⇒ To assign new {key: value} pair into the dictionary or to modify the existing value of a key in a dictionary

  • Pop:

    • Array - Removes the last element

    • Dictionary - Removes the value of the given key

  • Remove

    • Array - Removes the given value

  • Deep Copy

    • Array and Dictionary - Makes a copy of the variable and assigns a new value

To learn more, find the use cases below

String

Use Case 1 - Dictionary(Action: Assign)

Modify variable customer_info['customer_id'] with value custom_attribute['value']
  • Assume the variable customer_info is a dictionary/JSON and contains the value {“entity_id”:12, “name”: “Alice Blue”}

  • To add more keys with values to the dictionary, the modifier handler is used

  • The below step adds customer_id to the dictionary

  • After processing, the customer_info variable contains the value {“entity_id”:12, “name”: “Alice Blue”, “customer_id”: custom_attribute[‘value’]}

Use Case 2 - Array(Action: Append)

Modify variable customer_info['customer_id'] with value custom_attribute['value']
  • Assume the variable customer_info is an array/list and contains the value [{“entity_id: 1}, {“entity_id: 2}, {“entity_id: 3}]

  • To add an item to the array, the Modify Variable handler is used

  • The below step adds customer_id to the Array

  • After processing, the customer_info variable contains the value [{“entity_id: 1}, {“entity_id: 2}, {“entity_id: 3}, {"custom_attribute['value']}]

Mapping

Provides the ability to get mappings from the user and format data between two different system APIs.

This adds a new mapping card in the pipes section to get mappings in the pipe. The Modifiers will also be provided in the same section.

Based on the Mapping configuration, the destination payload will be prepared from the source data.

Mapping Handler

Available Options

Parameters

Definition

Type

Display name

Mapping name displayed in the pipe

Alphanumeric

Source

API used to request data from the Source system

Choose from the dropdown list

Destination

API used to send data to the Destination system

Choose from the dropdown list

Variable

Stores mapped data

Variable

Source Data

Source data that will be formatted and sent to destination API as per the mapping configuration

JSON, Array

Ignore Keys

Keys that should be ignored by the system, while processing data in the mapping structure defined by the user.

For more information, click here.

Alphanumeric

Example

Prepare mapping with name Customers Information from source Get Customers- Magento 2
to destination Create Customers - Epicor P21 Custom Server

Creates a mapping node in the pipe to provide the mapping of data between the specified source and destination APIs.

Use Case - Ignore Keys

{
"customer": [
{
"name":"alice",
"address": {
"street": "Jarvis St.",
"door_number": "5A"
}
},
{
"name":"bob",
"address": {
"street": "Marvel St.",
"door_number": "7D"
}
}
]
}

Assume the field street is mapped from source to destination system and the path generated for this field will be customer/address/street.

During Mapping, when the user sends this customer data(Parameter: Data) inside a loop, one entry at a time, to get the street address, the resulting path generated will be address/street.

In this case, the user should mention the parent keys to be ignored. In this case customer. If multiple keys need to be ignored, then the user should mention them as comma-separated values.

If, Else If & Else

To define and check for decision-making conditions inside the Flow.

Condition parameters are defined for the If and Else If handlers. If this condition is satisfied, the children of If will be executed. Otherwise, the children of Else will be executed.

If Handler

Available Options

Parameters

Definition

Type

Condition

Condition that needs to be satisfied for the children-statements to be executed

Example: admin_details['status']

If the value is true, the children will be executed

Mixed

No parameters are assigned for the Else Handler.

Examples

If specified condition matched

Some example conditions that can be used with the If statement, which need to be true for the proceeding children-statements to be executed

customers['status']

If the condition returns true

customers["status"] == 200

If the condition is satisfied

orders and customers

If both order and customers variables contain values

orders or customers

If either one variable has value

'customer_id' in item

If the dictionary item has key customer_id

Loop

Executes a block of code repeatedly in a cyclic fashion, each time with a different value.

Loop Handler

Available Options

Parameters

Definition

Type

Iterable

Data to be iterated/looped

Example: Sales_rep_data['data']

The loop will keep running until there is an item in the data

Array

Key

Variable assigned to the loop counter

Example: key, item

Variable

Examples

Loop till specified condition matched
  • orders

  • mapped_orders["lines"]

Step Progress

Denotes the progress of data processed inside a loop. The outcome of this handler is visually seen in the progress bar in the Integrations page. This helps in understanding how much data synchronization has been processed.

Step Progress Handler

Use predefined variables records_processed and total_records to track the records. Add Incrementer handler in the loop to increment the values on every count.

Available Options

Parameters

Definition

Type

Processed Records

Number of records that are processed

Variable

Total Records

Total number of records which is to be processed

Variable

Steps

This handler is placed one level above the previous handler Step Progress. It is used to visually split the business logic of the flow, for better understanding while synchronizing the data.

Steps Handler

Available Options

Parameters

Definition

Type

Message

Displayed in the progress bar of pipes

Examples:

  • Fetching M2 Orders

  • Updating P21 Orders

Alphanumeric

Logger

The Logger handler is used to log any errors or warnings in the flow. The Logs menu in the project area displays all the logs from the synchronization.

Logger Handler

This is a general level log and to log at the entity level, click here.

Available Options

Parameters

Definition

Type

General Message

Content that needs to be logged

Mixed

Step Logger

The Step Logger handler is similar to the Logger handler but used to provide logs at the item level. The Step Logger marks every single entity inside the loop as Success or Failure.

This can be viewed by clicking the "View" button in the Logs section.

Step Logger Handler

For more general level logging, click here.

Available Options

Parameters

Definition

Type

Type

Status of the execution. Success or Failure.

Choose from the dropdown list

Entity ID

ID of the entry. Useful in identifying if the entities succeeded or failed.

Example: item[‘itemCode’], mapped_orders['hdr']['webReferenceNumber']

Variable, Number

Message

Content that needs to be logged

Mixed

Detailed Message

Detailed content to be logged. Verbose.

Mixed

Console

Displays messages in the Logs section console area. This is especially useful in debugging the Flow itself.

The messages can be either static or dynamic.

Console Handler

Available Options

Parameters

Definition

Type

Message

Content that needs to be displayed

Example:

Dynamic ⇒ Variable: order_info, line_no

Static ⇒ HelloWorld, 12345

Mixed

Get Last Synchronized Time

Gets the last synchronized time of a system, in the required time zone

Get Timezone Handler

Available Options

Parameters

Definition

Type

Variable

Stores the last updated time

Variable

Systems

The output (Last sync time) is got in this System's timezone

Choose from the dropdown list

Format

To change the format of the output time

Example: Month-Day-Year HH:MM:SS

Choose from the dropdown list

Credential Keys

Retrieves any credential details from the respective project. (Example: Name, System, Hostname)

Credential Keys Handler

Available Options

Parameters

Definition

Type

Value

Data that were assigned while setting up the credentials of the system

Value: Name, System, Hostname

Alphanumeric

System

System from which the credential details are to be obtained

Choose from the dropdown list

Variable

Stores the obtained value

Variable

Return Value

Returns data to the caller, in real-time.

This applies only to the dynamic pipes.

Return Value Handler

Available Options

Parameters

Definition

Type

Return Value

String/Non String

Choose from drop-down list

Payload

Variable, JSON, Array

Date Time Formatter

Add or subtract minutes or hours from a given time value.

Available options

Parameters

Definition

Type

Variable

Stores the output

Alphanumeric

Date

String/Non-string

Actual date-time in UTC format or variable name containing the date-time in UTC format

Choose from drop-down list

Action

Advance/Recede

To add or subtract hours and minutes

Choose from drop-down list

Hours and Minutes

Value of hours and minutes to be added or subtracted to the given time

Numeric

Time Converter

Converts Time from one format to the other (12Hr clock to 24Hr clock and vice versa).

Parameters

Definition

Type

Convert

The conversion time format

Choose from drop-down list

Variable

Variable to store the output

Alphanumeric

Enter Hours

Hours value

Numeric (1-12 or 1-24)

Enter Minutes

Minutes value

Numeric (1-60)

Enter Seconds

Seconds value

Numeric (1-60)

Meridiem

Choose AM or PM

Choose from drop-down list

Time Zone converter

Converts a given time to the selected timezone.

Parameters

Definition

Type

Variable

Stores the output

Alphanumeric

Time

Time to be changed to the selected time-zone

UTC Format

Timezone

Timezone to which the time needs to be converted

Choose from drop-down list

Data Type converter

Converts data from one data type to another (string to integer or integer to string).

Parameters

Definition

Type

Variable

Stores the output

Alphanumeric

Value

Value or variable whose data type has to be converted

Alphanumeric

Data type

Data type that the value has to be converted to

String/ Integer

Choose from drop-down list

Current DateTime

Converts current time to the timezone of selected system.

Available options

Parameters

Definition

Type

Variable

Stores the output

Alphanumeric

System

Current time is converted to this timezone

Alphanumeric

Pagination

To send required paginated data for API calls.

Available options

Parameters

Definition

Type

Variable

Output from the handler

(Part of the data (from input data) as per the number of records mentioned)b

Alphanumeric

Response Data

The input to the handler i.e., the data which needs to divided into smaller arrays.

Example: response data will be the output from an API call

Alphanumeric

Number of records

Number of records the user needs in the output every time

Numeric

While Loop

Loop till specified condition is true.

Available options

Parameters

Definition

Type

Condition

Loop till specified condition is true

JSON

Break

To break a loop.