Flows & Handlers

"Flows" are a set of statements, written like pseudocode using simplified language, for implementing integrations.
"Flows" are 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.
​
​
1.The list of Pipes associated with a Flow are displayed below the Flow Status Area. 
Pipe List in the Flows page
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/Comment 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
While clicking on the API dropdown list, a differentiator to identify global and custom APIs will be seen. See image below: 
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
DropDown
API
API endpoints of the selected system. Depending on the Platform chosen, the list of API’s in the dropdown changes.
DropDown
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
Files
Upload one or many files contents. Example: 
[ 
('file', ('foo.csv', "hello,there,csv,data")), ('file', ('bar.txt', "this is a file content")) 
]
Variable (defined), JSON, Array
Headers
Request Headers 
Example: 
{"Accept": "application/json"}
Variable (defined), JSON
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
Override time
To override the timeout at Flow level. Read more below.
​
For XML Payload (Examples)
Plain request
{'plain_request': {'key1':'value1','key2':'value2'}}
Not a plain request
{'body':{'key1':'value1','key2':'value2'}}
Use keywords(DYNAMIC_TOKEN, GET_FROM_CREDENTIALS) to fetch and pass the respective dynamic information in headers and payload.
DCKAP Integrator accepts API responses in JSON, CSV and Text formats.
API Call Handler also has the facility to add headers from Flows.
To override the API manager timeout at the Flow level.
Choose: Yes/No from the drop-down list Yes - Override the timeout based on read and connect values mentioned here No - Do not override the timeout based on read and connect values mentioned here
"Connect" refers to the maximum allowed time for DCKAP Integrator to establish communication with the system to which the API call is made. 
"Read" refers to the maximum allowed time for the system to respond back to DCKAP Integrator.
MySQL
Connects to the SQL database and allows users to configure data in the SQL database.
Parameters
Definition
Type
Variable
Stores the response data (SQL response)
Variable
Systems
System to connect to
DropDown
Database Name
Database name to connect to
​
Action
Operation to be performed on the data. See below for examples.
DropDown
Data
Data to be configured in the database
String/Non-string
Table Name
Table name in the database
String/Non-string
Condition
Condition to validate to configure the data
String/Non-string
Limit
Number of records needed
String/Non-string
Different Action Types with examples: 
Action: Insert 
Description: Used to insert a record into a table
Example: 
INSERT into table_name (name, email, contact_no) values ('John Smith', '[email protected]', '+17427772299');
Action: Insert Many 
Description: Used to insert multiple records into a table
Example:  
INSERT into table_name (name, email, contact_no) values ('John Smith', '[email protected]', '+17427772299'), ('Max Roger', '[email protected]', '+17217772299'), ('Mike Hussey', '[email protected]', '+17347772299');
Action: Replace 
Description: Used to insert records into a table if there is no record found already, otherwise records will get updated
Example:
INSERT into table_name (name, email, contact_no) values ('John Smith', '[email protected]', '+17427772299'), ('Mike Hussey', '[email protected]', '+17347772299') ON DUPLICATE KEY UPDATE name=VALUES(name), email=VALUES(email), contact_no=VALUES(contact_no);
Action: Update 
Description: Used to update a record from the table
Example: UPDATE table_name SET name='Steve Smith', contact_no='+17433773377' WHERE email='[email protected]';
Action: Delete 
Description: Used to delete a record from the table
Example:
DELETE from table_name WHERE email='[email protected]';
Action: Select 
Description: Used to retrieve a record from the table
Example: SELECT * FROM table_name WHERE email='[email protected]' limit 10;
​
To retrieve column names from the table below example query should be executed,
Query: SELECT * FROM table_name WHERE 1=0;
​
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
Character Set
Choose one option from the drop-down for the character set type to be interpreted in the emails
Choose from drop-down: 
US-ASCII 
ISO-8859-1
UTF-8
Content Transfer Encoding
Mail encoding method
Choose from drop-down: 
Quoted Printable 
Base64 
7Bit 
8Bit 
Binary
Message Type
Plain Text for sending string messages
HTML for sending mail as per a template
Choose from drop-down: 
Plain Text 
HTML
Dynamic Data
For Plain text, leave it blank
For HTML Message Type: 
a) if there is dynamic data, pass it as a dictionary here
​
b) else leave it blank
Dictionary
Message
If string, give the string input
If non-string, provide the HTML template.
String/ Non-string
​
Example 1
​
Message Type: Plain Text
Dynamic Data: Leave it blank
Message: String
Dear Sir,
This is to inform you that we received your ticket.
Example 1
Example 2
​
Message Type: HTML
Dynamic Data: Leave it blank
Message: Non-String
<html>
   <head>
      <h1> Line1 </h1>
   </head>
   <body>
      <i>This is a mail to communicate that we are working on your ticket </i>
   </body>
</html>
Example 2
Example 3
​
Message Type: HTML
Dynamic Data:  
{"keys": ["Name","Age","Company"], 
"records": 
[
{"name": "Alex", "age": 25, "company": "DCKAP"},
{"name": "David", "age": 28, "company": "DCKAP"}
]
}
Message: Non-String
<!DOCTYPE html> 
<html>
   <head>
      <style> 
         table, th, td { border: 1px solid black; } 
      </style>
   </head>
   <body>
      <table>
         <tr>
            {% for key in keys %}
            <td>{{key}}</td>
            {% endfor %} 
         </tr>
         <tr>
               {% for dict_item in records %}
                      {% for key, value in dict_item.items() %} 
                              <td>{{value}}</td>
                      {% endfor %}
                      <tr></tr>
               {% endfor %} 
         </tr> 
      </table>
   </body>
</html>
Example 3
Base-64 HTML Combination and occasionally Base-64 plain text combinations don't work as expected. This will be addressed in the upcoming releases.
​
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 
DropDown
​
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 
DropDown
​
The data to replace or change in the variable 
JSON, Array
Type
Type of data to be modified
Dictionary/JSON
Array
DropDown
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
DropDown
Destination
API used to send data to the Destination system
DropDown
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.
When an API or system is changed in the Flow, then the previously configured mapping becomes unstable. 
So users will be alerted if the mapping should be retained or if it should be deleted during the save and merge process.
If the mapping is retained, the errors will be highlighted. 
​
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 (Works like a For 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"]
​
MSSQL 
Connects to the Microsoft SQL database and allows users to configure data in the SQL databases.
Parameters
Definition
Type
Variable
Stores the response data (SQL response)
Variable
Systems
MSSQL System to connect to
DropDown
Database Name
Database name to connect to
​
Action
Operation to be performed on the data. See below for examples.
DropDown
Data
Data to be configured in the database
String/Non-string
Table Name
Table name in the database
String/Non-string
Condition
Condition to validate to configure the data
String/Non-string
Limit
Number of records needed
String/Non-string
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.
DropDown
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
Get Last Success Time
If Yes, fetches the last succeeded sync time. If No, fetches the last synced time irrespective of its status. Default is No.
DropDown
Systems
The output (Last sync time) is got in this System's timezone
DropDown
Format
To change the format of the output time
 Example: Month-Day-Year HH:MM:SS
DropDown
​
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
DropDown
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
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

`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`
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
Parameters	Definition	Type
Message	Displayed in the progress bar of pipes Examples: Fetching M2 Orders Updating P21 Orders	Alphanumeric
Parameters	Definition	Type
Message	Content that needs to be displayed Example: Dynamic ⇒ Variable: `order_info`, `line_no` Static ⇒ `HelloWorld`, `12345`	Mixed
Parameters	Definition	Type
Variable	Stores the response data (SQL response)	Variable
Systems	MSSQL System to connect to	DropDown
Database Name	Database name to connect to
Action	Operation to be performed on the data. See below for examples.	DropDown
Data	Data to be configured in the database	String/Non-string
Table Name	Table name in the database	String/Non-string
Condition	Condition to validate to configure the data	String/Non-string
Limit	Number of records needed	String/Non-string