Interfaces

Interfaces allow you to connect different data structures and formats (XML, JSON, CSV, etc.) from your systems with our API.

You can have as many interfaces as you need, and they depend on the format of the data (JSON, XML, CSV, etc.) but also on the structure of it. So, for example, you can have many JSON interfaces that receive totally different data structures.

You can visualize it as the "key" (interface) to be used in your "door" (API) to access or insert data in your server. Defining an interface is important because you won't be able to insert data and run processes without it.

It's needed when you want to insert data or upload a batch of data records to be run on a flow or define URLs, which could be a Direct URL, a Website URL, or a Dynamic URL.

Create an Interface

The first thing that we need to choose while creating an Interface, it's which is the format of the data. We can have four different formats:

JSON (JavaScript Object Notation)

It's a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. JSON is the format that Flowize internally uses, and any other format will be converted to it with the help of the mapping. Example:

{
  "user": {
    "name": "Jane",
    "age": 32
  }
}

Once you have chosen the JSON type, you need to decide if the JSON data that you are going to send follows your Global Data Structure or not.

Data Structure is the template of the data you will use in your flows, contents, etc. In other words, is the standard set of data that will be available in your Flows and Contents, independently of the structure that you sent to the API.

It is convenient to define a Data Structure as it will allow you to use @data variables that will be replaced in your contents and/or flows, independently of the interface used. Another advantage of @data variables is that they can be updated through the flow process.

If you haven't already created a Data Structure, don't worry, you can define it before continuing or skip the step if you don't plan to use @data variables, and you will only use @interface variables.

Option	Usage
Data Structure	There is nothing more to configure, you are free to "Save" unless you want to configure more details about your interface as its name or the security
Custom Structure	An editor will appear where you can paste or upload a file that will be the example of the JSON you are going to use with this Interface

When you have a Data Structure defined, you can also map some variables of your Custom Structure to your Data Structure as it's explained in the previous post.

XML (eXtensible Markup Language)

It's a markup language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. Example:

<?xml version="1.0" encoding="UTF-8"?>
<menu>
    <food>
        <name>Belgian Waffles</name>
        <price>$5.95</price>
        <description>
            Two of our famous Belgian Waffles with plenty of real maple syrup
        </description>
        <calories>650</calories>
    </food>
</menu>

Once you have chosen the XML type, an editor will appear where you can paste or upload a file that will be the example of the XML you are going to use with this Interface.

When you have a Data Structure defined, you can also map some of the variables of your Custom Structure to your Data Structure, as explained in the previous post.

CSV (Comma Separated Values)

It's a comma-separated values file, which allows data to be saved in a tabular format. Although it's mainly known for using the comma as a separator between values, other divisions can be used. The most common ones are commas, semicolons, colons, pipes, or tabs.

Once you have chosen the CSV type, an editor will appear where you can paste or upload a file that will be the example of the CSV you are going to use with this Interface.

Below the editor, a preview of the data tabulated is shown and truncated to a maximum. There are different options that you can configure based on how your CSV file is organized:

• Header. If the first line of your CSV file contains headers (column names of each of the fields). If you select YES, that line will be used to generate the keys of the JSON object. If not, automatic names will be generated like " Column1, Column2, etc."
• Delimiter. It's the character which separates the values in each row of the file. Most common delimiters are comma (,), semicolon (;), colon (:) and tabs.
• Enclosure. It's the character that encloses the values of each field. Most common enclosures are quote (") and single quote ('). Fields containing a line-break, double-quote or commas should be quoted. If they are not, the payload will likely be impossible to process correctly.

When you have a Data Structure defined, you can also map some variables of your Custom Structure to your Data Structure as it's explained in the previous post.

Multi Record

If your data format doesn't follow any of the other three formats, you can try it with this format and define your own rules on how the data is organized. For example, you can map files used by banks like SWIFT file formats (MT101, MT940, ...)

As the process of defining how the structure of the data is going to be received differs depending on the format you use, we will see each type of data separately. Once you have chosen the Multi Record type, you can choose from the Multi Record templates or create your template so later on, you can use it for other interfaces.

In the editor that will appear, you can paste or upload a file that will be the example of the data you will use with this Interface. After pasting it, you can define how and where your data record starts in the file.

Type: There are different types of Multi Record based on how the fields are delimited:

Type	Usage
Multi Record Delimited	If your data always starts when :20: appears
Multi Record Fixed	If your data always starts when 01, appears
Multi Record Fixed by Position	300 starting in position 83

Header: You have to choose if your data contains a header or not.

Repeat Header: You need to select if the header needs to be repeated on every record or not.

Header starts with: In case your header always starts with the same pattern, you can also type it. It can be one only character or a list of possible characters. The symbol | is equivalent to the OR logic operator.

• E.g.: {
• E.g.: {head}
• E.g.: 01|02|03

Delimiter: It's the character which separates the values in each row of the file. Most common delimiters are comma ( ,), semicolon (;), colon (:) and tabs. If "Custom Delimiter" is selected, but you don't provide any, the default delimiter will be a comma (,).

Enclosure: It's the character that encloses the values of each field. Most common enclosures are quote (") and single quote (').

New Record starts with: Choose which record type will be the start of a new record. In the example that we show, we know that always our data records start with the ":20:", and as the delimiter is ":", we need to type "20".

Delimited field index: Choose which column from 1 to n is the starting point. So if the value is "2" then it will start in column "2". In our example, these are the first column values:

• Column 1: ":"
• Column 2: "2"
• Column 3: "0"
• Column 4: ":"
• Column 5: "P"
• Column 6: "1"

Indicator size: Defines what the length of the indicator between delimiters is. Use 0 for the entire field. If you have a document like this:

{1:F01INGBNL2ABXXX0000000000}{2:I940INGBNL2AXXXN}{3:{108:B12345678S000001}}{4: :20:P140104000009999 :25:NL20INGB0001234567EUR :28C:00003

and your delimiter is ":" then, these are the posibilities:

1. The header starts with the character => {

2. Delimited field index of the first record-type indicator => 2

   Indicator size	Will recognize
   0	"20" "25" "28C"
   1	"2" "2" "2"
   2	"20" "25" "28"
   3	"20" "25" "28C"

3. Delimited field index of the first record-type indicator => 2

   Indicator size	Will recognize
   0	"0" "5" "8C"
   1	"0" "5" "8"
   2	"0" "5" "8C"

While you are setting up these parameters, you will see in the editor outlined how the codes are being recognized, where the data record starts, etc. Once you are okay with the preview, we can move into setting up the Sections, that will define how our data record is structured.

Sections and Parameters

Once we reach here, our data structure is flat, which means that only has one level, identified by "root". In the example, we show only the first lines:

{
  "root": {
    "header": "{1:F01INGBNL2ABXXX0000000000}{2:I940INGBNL2AXXXN}{3:{108:B12345678S000001}}{4:",
    "20": "P140104000009999",
    "25": "NL20INGB0001234567EUR",
    "28C": "00003",
    "60F": "C140102EUR1000,00"
  }
}

If you want to change the text of any key, for example, you want to change "20" into "transaction_detail", just type it in the input.

Now let's focus, for example in the line "60F": "C140102EUR1000,00" The value "C140102EUR1000,00" is not worth it for us, and we know it is a compound of different values. Our goal is to achieve this:

{
  "root": {
    "header": "{1:F01INGBNL2ABXXX0000000000}{2:I940INGBNL2AXXXN}{3:{108:B12345678S000001}}{4:",
    "20": "P140104000009999",
    "25": "NL20INGB0001234567EUR",
    "28C": "00003",
    "opening_balance": {
      "credit_debit": "C",
      "date": "140102",
      "currency": "EUR",
      "balance": "1000,00"
    }
  }
}

Edit Parameters: Click in the "Edit Parameters" next to the "60F" input, and a modal window will appear. Then, type "opening_balance" in the label of the parameter to change the name of it. Then you have to choose how are you going to split the values. There are four possibilities:

Split way	Description
Per length	To define from which position to which position is each value. In this example, you need to keep in mind that we start in position "6" because from the start of the line we have 5 characters ":60F:"
Per delimiter	You can use the same kind of delimiters explained before
Flexible length	If your values are based in length but it is not always the same, and you don't have delimiters
Regular expression	If you know how to write regular expressions, this is very useful when it's very complex to extract the values from a string

In our case, we are going to choose "Flexible length". Then we need to start "Adding new Parameter" till we have 4, that is our goal.

Then we start typing all the labels of the parameters.

In length, we need to put the maximum length the parameter can have. We have the opportunity to decide if the length is fixed or flexible. For example, we know that "credit_debit" is always 1 character, and it's always a letter [a-zA-Z].

On the other side, we have "balance" that its length can vary from 4 characters (0,00) to 15 characters ( 999999999999,99). In type we choose "Amount" which includes digits [0-9] and [,.] characters.

Type: These are the different types you can choose:

Type	Includes
Only digits	Only numbers [0-9]
Only letters	Letters in lower and upper case [a-zA-Z]
Letters + Symbols	[a-zA-Z] and symbols like `[]{}()\
Alphanumeric	Numbers and letters [a-zA-Z0-9]
Alphanumeric + Symbols
Amount	Characters used in amounts [0-9] and [,.]

Param ending

Row example:

140D1030103C125,00NRTINONREF//00000000000009/TRCD/00190/ defines what should be the ending of the string.

Based on the example above, if as LENGTH we put 5, OPTION is NOT FIXED, TYPE Alphanumeric and ENDING as "D" then we will map "140D"; or if as LENGTH we put 5, OPTION is NOT FIXED, TYPE Alphanumeric and ENDING as "C" then we will map EMPTY because the LENGTH is not enough to reach the "C".

You can test if you are mapping the parameters correctly by clicking in the "Detect parameters" and it will highlight them.

RAW

The RAW interface allows the inclusion of any content without imposing any mapping or structure. It is a flexible format intended for single record submissions and does not support batching. Unlike other interface formats (JSON, XML, CSV, or Multi Record), the RAW format directly accepts input as-is, without converting or validating the data.

The RAW interface is ideal when you need to pass through unstructured data without any processing or transformations within the system.

This is an example of use:

curl -k -i -X POST 'https://api-xxxx-xxxx-xxxx.onflowize.com/v1/record' \
-H 'X-Apikey: *****************' \
-H 'X-Environment: TEST' \
-H 'X-App: raw_interface' \
-H 'X-Flow: {{flow_name}}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/x-raw' \
-d 'This is an interface type raw, where I can send whatever I want.'

Mapping the interface data

If you want to save some of your interface data in your Data Structure, then you only have to click on the option "Yes, map variables", and below the list of your Data Structure variables will appear along with your interface variables.

Keep in mind, that the type of variable matters so, if in your data record you have a variable which is an array, and you don't have arrays in your interface, you won't be able to map that variable as the types have to match.

Also, you have the possibility to "automap" the variables. If you click this button, the system will try to autofill the mapping of your interface with the Data Structure if they share the same names and are at the same level.

Interface Details

In this tab, you can configure additional details of your Interface. You can define the Interface name and type a Description to explain the objective of it.

Based on the name that you type, an Interface ID will be generated, always in lowercase and without spaces. You need to send this ID in the headers of the API request to identify how the data you are sending will be mapped with your Data Structure.

Below you will have your API key, and you can check it if you click in the button. You need it to authenticate in every request you do to the API.

Next, you have a table with the information of the API endpoints. Depending on the type of Interface, you can have two different endpoints:

• Data Record. You need to use this endpoint when you want to insert them one by one. This option is only enabled for JSON or XML, as CVS and Multi Record are meant to be used with a batch of records.
• Batch. You need to use this endpoint when you want to insert more than one data record in the same request. You can use it with the four different types but keep in mind that:

        - If JSON, you need to send in the request an array of JSON objects. Example:

[
  {
    "user": {
      "name": "Jane",
      "age": 32
    }
  },
  {
    "user": {
      "name": "Peter",
      "age": 41
    }
  }
]

        - If XML, the first level after the root tag will be considered as the array of data records that you want to insert. Example:

    <?xml version="1.0" encoding="UTF-8"?>
<menu>
    <food>
            
        <name>Belgian Waffles</name>
            
        <price>$5.95</price>
            
        <description>
              Two of our famous Belgian Waffles with plenty of real maple syrup
               
        </description>
            
        <calories>650</calories>
    </food>
    <food>
            
        <name>Apple Pie</name>
            
        <price>$8.95</price>
            
        <description>
              Pie with an apple filling spiced with cinnamon
               
        </description>
            
        <calories>342</calories>
    </food>
</menu>

        - If CVS, all you lines must have the same number of columns.

Interface Security

If you want to secure your Interface, activate this setting.

You will be able to whitelist IPs of your servers so only request from those will be accepted in the API. If you don't type any IP, all requests using your credentials will be accepted in the API.

Also, you can enable oAuth2 authentication for your Interface. oAuth2 is an authorization framework that enables external applications to obtain limited access to your Interface.

Variables

Below you can see the Interface variables name that you will be able to use in your flows or contents.

Testing the Interface

Once you have saved your Interface, a new tab will appear, and you will be able to test the Interface you have configured.

In order to test it, you need have, at least, one flow already created. Below, you can see an example of the cURL request that is sent to the API. In that request, some headers are essential for you to know as you will need to add them when you send the request to the API:

Header	Description
X-Apikey	Your API key
X-Environment	Useful when you want to sent TEST data records
X-App	The Interface ID you want to use
X-Flow	The name of the Flow where you want to send the data
Content-Type	Depending on your data format, should be: application/json, application/xml, text/csv, text/plain...

Accessing Header Variables in Flowize

In Flowize, you now have the ability to access header variables of an interface within a flow. This enables you to use the data sent in the headers for various functionalities in your flow, offering a higher degree of customization and control.

However, to utilize this feature, there are specific formatting requirements that need to be followed. Here's a step-by-step guide:

Formatting the Header Name

1. The header name must be written completely in lowercase. The structure for accessing the header variables is as follows:

@interface-header.interface_name.header_name@

2. The interface_name is the name of the interface that you are using, and header_name is the name of the header variable you wish to access.

Example

Here's an example for better understanding:

@interface-header.interface_example.x-usertype@

In this example, interface_example is the interface name and x-usertype is the header name.

Using an API Platform

When sending the header variable via Postman, for example, the header variable will be sent like "X-usertype" with the value "test". So, your Postman setup would look like this:

Key: X-usertype
Value: test

Case Sensitivity

Please note that the header name is case sensitive. For instance, x-Usertype, X-Usertype, and other variations will not work. Always ensure to use lowercase letters only when specifying the header name in Flowize.

By following these instructions, you'll be able to successfully use the header variables of an interface within a flow in Flowize. Remember, the correct case and structure are crucial for this feature to function as expected.