- Novelties, tutorials
CONFIGURE AN «EXTERNAL LIST» INTEGRATION
Engracia Villar
- May 20, 2020
- 10:05 am
- 902
- No Comments
An integration of “External List” type is a bridge that CaptureData uses to request a list of data from external APIs. This bridge is configured from Gladtolink.
To create an external list integration, go to the integrations screen, and create a new one. In the “Service” section, search and select the “External List” option.
Call settings.
The first step to perform this type of integration is to configure the call and the parameters that you are going to send to the server to show it the data it has to send you.
Basic Configuration.
The first section that we must configure is “Basic configuration”. In this section you have the essential elements to make the call.
Route: This parameter corresponds to the API route or URL where you want to consult the data.
Type : Corresponds to the type of call that will be used to send the data, it can be of different types: GET, POST or PUT. In the case of POST and PUT, another parameter must also be defined, the “Type of shipment“.
Shipping type: It corresponds to the type of additional parameters that we are going to send within the body of the call.
Page Settings and Search.
This section corresponds to the specific configuration for external lists. It is used to define the parameters related to paging and the results filter.
In case the API you are requesting data has support for paging or filtering, you must specify the name of the parameter and where it is in the call (Body, Header or Query).
Page parameter name: This parameter corresponds to the name the API identifies the requested page. API is required to have paging support.
This parameter will be a natural number that will start at 1 and will be increased when subsequent pages have to be requested.
Search parameter name: This parameter corresponds to the text string that the user can enter to filter the elements. Its implementation is determined by the server that receives the requests. For usability, we recommend to use a plain text search.
Elements per page: This parameter corresponds to the number of elements the API is expected to return in its response, with a minimum of 10 and a maximum of 100 elements in each page request.
Regarding the paging of elements, we must take into account the following:
- If the service returns the specified number of elements per page, at the bottom of the page the following request will be executed, increasing the page parameter by 1.
- If the service returns fewer elements than expected or zero, these elements will be shown and it will be understood that the last page has been reached, so no more requests will be executed.
- If the service returns more items than specified they will not be processed and the user will be alerted.
Reply Settings.
After configuring the call, the next step is to configure how you will treat the data that the target API sends.
JSON Array Reply: In this section you must add a sample object of the response to be received (in JSON Array format) in order to process the data from Gladtolink.
Depending on how the data returned by the source service is formatted, you must upload an example with the array that contains the elements to process from our response. It may look something like this:
The values that each attribute contains are indifferent, but they must contain a value of the desired type (Int, string…), since the important thing is to identify the attributes that the object will contain, their name and type.
Response form.
This section configures how the data obtained from the API will be linked or mapped. First select a form, where such data will be saved.
Status : the result of the connection will be saved in this field.
Message, in case of failure: In the event that the requested data cannot be correctly accessed, the server will return an error message, that will be saved in this field.
Attribute name: In case the API returns object (not array) directly, the name of the parameter that contains the same Array that was uploaded in the example must be specified. If the service response is directly an Array, it can be left empty.
Attributes of the list objects: For each element of the JSON in the previous example, there will be a field that you must link to a field in the selected form. Please note that each attribute can only be linked to one field, and you cannot link more than one attribute to the same form field.
