Integration Designer

​

Overview

​

Key features

​

Managing integration endpoints

​

Systems

​

Creating a new system definition

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

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

For example:

• For our integration example, you can declare configuration parameters and use the variables to store your tableId and baseId and reference them the Variables tab.

• Use variables in the Base URL to switch between different environments, such as UAT or production.

​

Endpoint parameter types

​

Path parameters

• 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 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

• 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

• 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

• 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

​

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

​

Service account

• 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:

Store tokens in a configuration parameter so updates propagate across all requests seamlessly when tokens are refreshed or changed.

​

Certificates

• 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 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

​

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

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

​

Worflow start node

{
  "firstName": "John"
}

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

Make sure the data is also mapped in the Start Integration Workflow node action where you have the data.

​

REST endpoint nodes

Unlike some nodes, the Endpoint Call node can be run independently, making it possible to test the connection or retrieve data without executing the entire workflow.

• 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

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

​

Data mapping nodes (scripts)

​

End node

Multiple End nodes can be included within a single workflow. This allows the workflow to have multiple possible end points based on different execution paths.

​

Testing the workflow

​

Debugging

​

Workflow integration

1

Create a BPMN Process

1. Open the FlowX Process Designer:
   • Navigate to Projects -> Your application -> Processes.
   • Create a new process or edit an existing one.
2. Define the Data Model:

Needed if you want to send data from your user task to the workflow.

• Establish the data model that will be shared between the process and the workflow.
• Ensure all necessary data fields that the workflow will use are included.

2

Configure a User Task or Service Task

1. Add a Task:
   • Insert a User Task or Service Task into your BPMN diagram.
   • A User Task requires user input, while a Service Task can trigger automated actions without manual intervention.
2. Configure Actions for the Task:
   • In the node config, add a Start Integration Workflow action.
   • Select the target workflow you want to integrate. This links the task with the predefined workflow in the Integration Designer.

3. Map the Payload:
   • If input data is defined in the Start Node of the workflow, it will be automatically mapped in the Start Integration Workflow action. Ensure that the workflow’s Start Node contains the fields you need.
   • Additional payload keys and values can also be set up as needed to facilitate data flow from the process to the workflow.

3

Receive Data from the Workflow

1. Add a Receive Message Task:
   • To handle data returned by the workflow, add a Receive Message Task in the BPMN diagram.
   • This task captures the workflow’s output data, such as processing status or results sent via Kafka.

2. Set Up a Data Stream Topic:
   • In the Receive Message Task, select your workflow from the Data Stream Topics dropdown.
   • Ensure that the workflow output data, including status or returned values, is accurately captured under a predefined key.

​

Integration with external systems

​

Integration in FlowX

1

Define a System

Navigate to the Integration Designer and create a new system:

• Name: Airtable Credit Data
• Base URL: https://api.airtable.com/v0/

2

Define Endpoints

In the Endpoints section, add the necessary API endpoints for system integration:

1. Get Records Endpoint:
   • Method: GET
   • Path: /${baseId}/${tableId}
   • Path Parameters: Add the values for the baseId and for the tableId so they will be available in the path.
   • Header Parameters: Authorization Bearer token

See the API docs.

2. Create Records Endpoint:
   • Method: POST
   • Path: /${baseId}/${tableId}
   • Path Parameters: Add the values for the baseId and for the tableId so they will be available in the path.
   • Header Parameters:
     • Content-Type: application/json
     • Authorization Bearer token
   • Body: JSON format containing the fields for the new record. Example:

Report incorrect code

Copy

Ask AI

   {
    "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}"
            }
        }
    ]
}

3

Design the Workflow

1. Open the Workflow Designer and create a new workflow.
   • Provide a name and description.
2. Configure Workflow Nodes:
   • Start Node: Initialize the workflow.

On the start node add the data that you want to extract from the process. This way when you will add the Start Workflow Integration node action it will be populated with this data.

Report incorrect code

Copy

Ask AI

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

Make sure this keys are also mapped in the data model of your process with their corresponding attributes.

• REST Node: Set up API calls:
  • GET Endpoint for fetching records from Airtable.
  • POST Endpoint for creating new records.
• Condition Node: Add logic to handle credit scores (e.g., triggering a warning if the credit score is below 300).

Condition example:

Report incorrect code

Copy

Ask AI

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

• Script Node: Include custom scripts if needed for processing data (not used in this example).
• End Node: Define the end of the workflow with success or failure outcomes.

4

Link the Workflow to a Process

1. Integrate the workflow into a BPMN process:
   • Open the process diagram and include a User Task and a Receive Message Task.

In this example, we’ll use a User Task because we need to capture user data and send it to our workflow.

2. Map Data in the UI Designer:
   • Create the data model
   • Link data attributes from the data model to form fields, ensuring the user input aligns with the expected parameters.

3. Add a Start Integration Workflow node action:

• Make sure all the input will be captured.

5

Monitor Workflow and Capture Output

Receive Workflow Output:

• Use the Receive Message Task to capture workflow outputs like status or returned data.
• Set up a Data stream topic to ensure workflow output is mapped to a predefined key.

6

Start the integration

• Start your process to initiate the workflow integration. It should add a new user with the details captured in the user task.

• Check if it worked by going to your base in Airtable. You can see, our user has been added.

​

FAQs