​

Overview

Integration Designer facilitates the integration of the FlowX platform with external systems, applications, and data sources.

​

Key features

​

Managing integration endpoints

​

Systems

A system is a collection of resources—endpoints, authentication, and variables—used to define and run integration workflows.

​

Creating a new system definition

With Systems feature you can create, update, and organize endpoints used in API integrations. These endpoints are integral to building workflows within the Integration Designer, offering flexibility and ease of use for managing connections between systems. Endpoints can be configured, tested, and reused across multiple workflows, streamlining the integration process.

Go to the Systems section in FlowX Designer at Projects -> Your project -> Integrations -> Systems.

1. Add a New System, set the system’s unique code, name, and description:
   • Name: The system’s name.
   • Code: A unique identifier for the external system.
   • Base URL: The base URL is the main address of a website or web application, typically consisting of the protocol (http or https), domain name, and a path.
   • Description: A description of the system and its purpose.
   • Enable enumeration value mapping: If checked, this system will be listed under the mapped enumerations. See enumerations section for more details.

2. Set up authorization (Service Token, Bearer Token, or No Auth). In our example, we will set the auth type as a bearer and we will set it at system level:

​

Defining REST integration endpoints

In this section you can define REST API endpoints that can be reused across different workflows.

1. Under the Endpoints section, add the necessary endpoints for system integration.

2. Configure an endpoint by filling in the following properties:
   • Method: GET, POST, PUT, PATCH, DELETE.
   • Path: Path for the endpoint.
   • Parameters: Path, query, and header parameters.
   • Response Settings: Expected response codes and formats.
   • Body: JSON payload for requests.

​

Defining variables

The Variables tab allows you to store system-specific variables that can be referenced throughout workflows using the format ${variableName}.

These declared variables can be utilized not only in workflows but also in other sections, such as the Endpoint or Authorization tabs.

​

Endpoint parameter types

When configuring endpoints, several parameter types help define how the endpoint interacts with external systems. These parameters ensure that requests are properly formatted and data is correctly passed.

​

Path parameters

Elements embedded directly within the URL path of an API request that acts as a placeholder for specific value.

• Used to specify variable parts of the endpoint URL (e.g., /users/{userId}).
• Defined with ${parameter} format.
• Mandatory in the request URL.

​

Query parameters

Query parameters are added to the end of a URL to provide extra information to a web server when making requests.

• Query parameters are appended to the URL after a ? symbol and are typically used for filtering or pagination (e.g., ?search=value)
• Useful for filtering or pagination.
• Example URL with query parameters: https://api.example.com/users?search=johndoe&page=2.

​

Header parameters

Used to give information about the request and basically to give instructions to the API of how to handle the request

• Header parameters (HTTP headers) provide extra details about the request or its message body.
• They are not part of the URL. Default values can be set for testing and overridden in the workflow.
• Custom headers sent with the request (e.g., Authorization: Bearer token).
• Define metadata or authorization details.

​

Body parameters

The data sent to the server when an API request is made.

• These are the data fields included in the body of a request, usually in JSON format.
• Body parameters are used in POST, PUT, and PATCH requests to send data to the external system (e.g., creating or updating a resource).

​

Response body parameters

The data sent back from the server after an API request is made.

• These parameters are part of the response returned by the external system after a request is processed. They contain the data that the system sends back.
• Typically returned in GET, POST, PUT, and PATCH requests. Response body parameters provide details about the result of the request (e.g., confirmation of resource creation, or data retrieval)

​

Enum mapper

The enum mapper for the request body enables you to configure enumerations for specific keys in the request body, aligning them with values from the External System or translations into another language.

On enumerations you can map both translation values from different languages or values for different source systems.

Make sure you have the enumerations created with corresponding translations and system values values in your application already:

​

Configuring authorization

• Select the required Authorization Type from a predefined list.
• Enter the relevant details based on the selected type (e.g., Realm and Client ID for Service Accounts).
• These details will be automatically included in the request headers when the integration is executed.

​

Authorization methods

The Integration Designer supports several authorization methods, allowing you to configure the security settings for API calls. Depending on the external system’s requirements, you can choose one of the following authorization formats:

​

Service account

Service Account authentication requires the following key fields:

• Identity Provider Url: The URL for the identity provider responsible for authenticating the service account.
• Client Id: The unique identifier for the client within the realm.
• Client secret: A secure secret used to authenticate the client alongside the Client ID.
• Scope: Specifies the access level or permissions for the service account.

​

Basic authentication

• Requires the following credentials:
  • Username: The account’s username.
  • Password: The account’s password.
    • Suitable for systems that rely on simple username/password combinations for access.

​

Bearer

• Requires an Access Token to be included in the request headers.
• Commonly used for OAuth 2.0 implementations.
• Header Configuration: Use the format Authorization: Bearer {access_token} in headers of requests needing authentication.

• System-Level Example: You can store the Bearer token at the system level, as shown in the example below, ensuring it’s applied automatically to future API calls:

​

Certificates

You might want to access another external system that require a certificate to do that. Use this setup to configure the secure communication with the system.

It includes paths to both a Keystore (which holds the client certificate) and a Truststore (which holds trusted certificates). You can toggle these features based on the security requirements of the integration.

When the Use Certificate option is enabled, you will need to provide the following certificate-related details:

• Keystore Path: Specifies the file path to the keystore, in this case, /opt/certificates/testkeystore.jks. The keystore contains the client certificate used for securing the connection.
• Keystore Password: The password used to unlock the keystore.
• Keystore Type: The format of the keystore, JKS or PKCS12, depending on the system requirements.

Truststore credentials

• Truststore Path: The file path is set to /opt/certificates/testtruststore.jks, specifying the location of the truststore that holds trusted certificates.
• Truststore Password: Password to access the truststore.

​

Workflows

A workflow defines a series of tasks and processes to automate system integrations. Within the Integration Designer, workflows can be configured using different components to ensure efficient data exchange and process orchestration.

​

Creating a workflow

1. Navigate to Workflow Designer:
   • In FlowX.AI Designer to Projects -> Your application -> Integrations -> Workflows.
   • Create a New Workflow, provide a name and description, and save it.
2. Start to design your workflow by adding nodes to represent the steps of your workflow:

• Start Node: Defines where the workflow begins and also defines the input parameter for subsequent nodes.
• REST endpoint nodes: Add REST API calls for fetching or sending data.
• Fork nodes (conditions): Add conditional logic for decision-making.
• Data mapping nodes (scripts): Write custom scripts in JavaScript or Python.
• End Nodes: Capture output data as the completed workflow result, ensuring the process concludes with all required information.

​

Workflow nodes

Users can visually build workflows by adding various nodes, including:

• Workflow start node
• REST endpoint nodes
• Data mapping nodes (scripts)
• Fork nodes (conditions)
• End node

​

Worflow start node

The Start node is the default and mandatory first node in any workflow. It initializes the workflow and defines the input parameters defined on it for subsequent nodes.

The Start node defines the initial data model for the workflow. This input data model can be customized. You can enter custom JSON data by clicking inside the code editor and typing their input. This input data will be passed to subsequent nodes in the workflow.

{
  "firstName": "John"
}

{
  "First Name": "${firstName}"
}

When you try to send input data from a process to a workflow, you can use the Start workflow node to map the data coming from a process and to send it acrross the entire workflow.

​

REST endpoint nodes

The REST endpoint node enables communication with external systems to retrieve or update data by making REST API calls. It supports multiple methods like GET, POST, PUT, PATCH, and DELETE. Endpoints are selected via a dropdown menu, where available endpoints are grouped by the system they belong to.

The node is added by selecting it from the “Add Connection” dropdown in the workflow designer.

Input and output

Each REST endpoint node includes some essential tabs:

• Params:
• Response key: The response from the endpoint node, including both data and metadata, is organized under a predefined response key.
• Input:
  • This tab contains read-only JSON data that is automatically populated with the output from the previous node in the workflow.
• Output:
  • It displays the API response in JSON format.

​

Condition (fork) nodes

The Condition node evaluates incoming data from a connected node based on defined logical conditions(if/else if with). It directs the workflow along different paths depending on whether the condition evaluates to TRUE or FALSE.

• If the condition evaluates to TRUE, the workflow follows the If path.
• If the condition evaluates to FALSE, it follows the Else if path.

You can include multiple Condition nodes within a single workflow, enabling the creation of complex branching logic and decision-making flows.

Parallel processing and forking

The Condition node can split the workflow into parallel branches, allowing for multiple conditions to be evaluated simultaneously. This capability makes it ideal for efficiently processing different outcomes at the same time.

​

Data mapping nodes (scripts)

The Script node allows you to transform and map data between different systems during workflow execution by writing and executing custom code in JavaScript or Python. It enables complex data transformations and logic to be applied directly within the workflow.

​

End node

The End node signifies the termination of a workflow’s execution. It collects the final output and completes the workflow process.

The End node automatically receives input in JSON format from the previous node, and you can modify this input by editing it directly in the code editor. If the node’s output doesn’t meet mandatory requirements, it will be flagged as an error to ensure all necessary data is included.

The output of the End node represents the final data model of the workflow once execution is complete.

​

Testing the workflow

​

Debugging

Use the integrated console after running each workflow (either if you test your workflow in the workflow designer or in a process definition). It provides useful info like logs, input and output data about eacg endpoint and other details like execution time etc.

​

Workflow integration

Integrating workflows into a BPMN process allows for structured handling of tasks like user interactions, data processing, and external system integrations.

This is achieved by connecting workflow nodes to User Tasks and Service Tasks using the Start Integration Workflow action.

​

Integration with external systems

This example demonstrates how to integrate FlowX with an external system, in this example, using Airtable, to manage and update user credit status data. It walks through the setup of an integration system, defining API endpoints, creating workflows, and linking them to BPMN processes in FlowX Designer.

​

Integration in FlowX

   {
    "typecast": true,
    "records": [
        {
            "fields": {
                "First Name": "${firstName}",
                "Last Name": "${lastName}",
                "Age": ${age},
                "Gender": "${gender}",
                "Email": "${email}",
                "Phone": "${phone}",
                "Address": "${address}",
                "Occupation": "${occupation}",
                "Monthly Income ($)": ${income},
                "Credit Score": ${creditScore},
                "Credit Status": "${creditStatus}"
            }
        }
    ]
}

{
"firstName": "${firstName}",
"lastName": "${lastName}",
"age": ${age},
"gender": "${gender}",
"email": "${email}",
"phone": "${phone}",
"address": "${address}",
"occupation": "${occupation}",
"income": ${income},
"creditScore": ${creditScore},
"creditStatus": "${creditStatus}"
}

input.responseKey.data.records[0].fields["Credit Score"] < 300

This example demonstrates how to integrate Airtable with FlowX to automate data management. You configured a system, set up endpoints, designed a workflow, and linked it to a BPMN process.

​

FAQs