Skip to content
background-image background-image

GET

The GET method within the context of endpoint usage enables you to retrieve raw or processed data with the option to configure custom failure messages and incorporate system data into the response. When employing this method with an Integray endpoint, you can securely access data, initiate integration tasks, and seamlessly manage the retrieval of records.

Configure the method GET for the created endpoint. The GET tab is divided into 3 sections: Input, Task, Output

Expected behavior

GET {companySlug}/{endpointGroupSlug}/{endpointSlug} - with task- Executes task

GET {companySlug}/{endpointGroupSlug}/{endpointSlug} - without task - Returns all or filtered data

GET {companySlug}/{endpointGroupSlug}/{endpointSlug}/{id:guid} - Return single data only

Input

Help_Endpoint_GET_Input

  • Input schema - The data structure that will be passed from the endpoint to the input of the task.

  • Query params mapping - Query parameters or URL parameters or query strings are used when a client, such as a browser, requests a particular resource from a web server using the HTTP protocol. These parameters are usually the name-value pairs, separated by an equals sign =. Query parameters have to be mapped against the structure of input data schema.

    Example:

    • Input data schema:

      Data Data type
      Lang String
      Name String

    Example

    https://www.example.com/index.html?Lang=en&Name=John

    GET parameters always start with a question mark ?. This is followed by the name of the variable and the corresponding value, separated by an equal sign, =. If an URL contains more than one parameter, they are separated by an ampersand &.

    Following special placeholders can be used:

    Placeholder Description
    ${headers} All request headers are serialized into a single JSON object
    ${bodyBase64} Entire parsed JSON as Base64 string.
    ${body.row} Currently parsed JSON token.
    ${fixed:<value>} Predefined constant.
    <token_name> Path to local token.
    <token_name>.<nested_token_name> Path to nested token.
    $.<JSONPath_expression> JSONPath expression.

Task

Help_Endpoint_GET_Task

  • Start task - A task that will be run when a GET request is received at this endpoint. To pass the incoming data to the task for processing, select Input schema and set Query parameters.

  • Save input data - The input data is saved to the database every time. Depending on the following settings, they can be deleted during the DB maitanance job.

    • Never - Input data is always deleted.
    • On error - Input data is only left in the database if the linked task fails.
    • Everytime - Input data is always left in the database.

  • Fail message

You can define your own customized messages, which will be displayed in case of failure. The default value for the Fail message is Not set.

HELP Enpdoints Fail message Not set

If the fail message rules are configured, the value is set to Configured.

Click the button with the pencil icon to configure your own messages.

+ Set default action

Set your default action, which will be executed in case of failure and no other fail message rules are met. The endpoint usually returns a fail message and you can replace it here.

HELP Endpoints Fail message Set default action

In the dialog modal window Fail message rules click the +Set default action button to configure your custom default action.

HELP Endpoints Fail message Set default action Message

In the expanded Fail message rules modal window enter your custom message and hit the Confirm button. If you want to remove the message, click the red minus-circle button. You must Save (or Save & close) the whole Endpoints settings to apply the change.

Example:

Standard fail message:

{
    "ID": "9b7e5203-658f-4739-9a26-5269f0c61b22",
    "Status": "FailedConnector",
    "Link": "https://screenshot-test.integray.app/home/data-exchange/2/task/4?taskRunID=100",
    "Message": [
        "Parsing configuration 'JS Mapping Statement' (ab00eb5f-e86e-4107-b8cd-b151a204c4c6) failed.",
        "Attempt 1/1 failed.",
        "Step failed - FailedConnector.",
        "Task failed - FailedConnector."
    ],
    "Result": null
}

Customized fail message

{
    "ID": "06c2f8c8-8836-427e-a986-c3390358f566",
    "Status": "FailedConnector",
    "Link": "https://screenshot-test.integray.app/home/data-exchange/2/task/4?taskRunID=97",
    "Message": [
        "My custom default fail message which replaces the standard message."
    ],
    "Result": null
}
+ Add rule

Add rules and define conditions for customized messages you want to have displayed in case of specific fail message types or a specific fail message content. Click the button + Add rule to start configuring your custom fail message rule.

Condition

Define the type of condition to be used:

  • Equals or

  • Contains,

and specify the condition value.

Action

Set your custom message text, which will apply in case of condition fulfillment.

HELP Configuration screen Endpoints Fail message Add rule

Example:

Customized fail message:

{
    "ID": "1fa2bd26-b1b0-4514-a81e-9b4eb78499e1",
    "Status": "FailedConnector",
    "Link": "https://screenshot-test.integray.app/home/company/2/task/4?taskRunID=102#history",
    "Message": [
        "Special message in case the message contains the word "Attempt""
    ],
    "Result": null
}

Rule conditions

You can use more than one condition. The logical operator among the configured conditions is AND i.e. all set conditions must be met to trigger the action.

You can also define as many custom rules as you require. In case there are custom rules set and conditions are not met, the default action is triggered. In case the default action is not defined, the standard platform fail message will be returned.

Output

Help_Configurations_Endpoint_GET_Output

  • Output schema - The data structure that will make up the endpoint response.

  • Save output data - If this option is selected, the result of the bound task is not only returned as the response of the endpoint, but also saved to the database.

  • Include system data in response - If selected, encapsulates the result of the task in the Data element and adds additional system fields.

    Include system data in response - ON

        {
        "ID": "364fe099-ed93-ec11-8708-c89402b99bb6",
        "status": "FinishedSuccess",
        "Message": null,
        "Result": [
            {
                "hello": "Bob"
            }
        ]
    }

    Include system data in response - OFF

        [
        {
            "hello": "Bob"
        }
    ]

  • Output step - Step, after which data will be selected from the data structure to be used as endpoint response.

  • Output mapping - Defines the rules for parsing incoming JSON data into task input schema. Each of the pairs binds a single column of the input schema to a property in JSON.

Endpoint output custom data types

The integration platform is set in a way, where the data scheme JSON returns always an array. It means that the data is encapsulated within square brackets [ ] to represent a collection or list of items. Each item within the array is typically separated by a comma. This structure allows you to handle the data consistently as an array, even if there is only one element present. If you don't want the JSON data to be returned as an array, you will find two built-in options depending on your specific requirements: Endpoint JSON output and Endpoint JSON (single) output.

XML data doesn't have a built-in concept of arrays as JSON does. However, you can represent a collection of similar elements in XML using repeated child elements within a parent element. In the platform, you will find two built-in options (analogical to the JSON ones): Endpoint XML output wrapping the XML element into another element and Endpoint XML (single) output returning the single (first) element of the XML.

The next custom output type in the platform is the Endpoint file output which enables the download of data from the endpoint in the form of a file.

For the moment the last and most recent custom output type is the Endpoint HTML output. This output schema allows to return HTML content. This HTML content won't be validated on the side of integray platform and will be treated as text inside the data schema.

Task run log warning in case of result containing more than one member

In case the above-described custom data types are used on the endpoint output and the output schema contains more than one member a log warning will be written into the Task run log stating: Based on the selected endpoint output schema, the first array member only was returned in the output. All the other members were ignored. The task run as well as the task step will be marked in the info log as successfully finished (Step successfully finished., Task successfully finished.).

Endpoint JSON output

Returns the inner value of JSON tag. The platform configuration requires the selection of the output schema - Endpoint JSON Output (version). Dependent on the requirement to include or exclude the system data in response, you will check the respective check box. Works with both HTTP methods GET and POST.

Endpoint JSON Output

Example with no system data in response:

[
    {
        "Name": "Boris",
        "Age": 47,
        "Nationality": "Slovak"
    },
    {
        "Name": "Tomas",
        "Age": 42,
        "Nationality": "Slovak"
    }
]

Example with the system data in response:

The output in this case includes the system identification data including ID, Status, Link, and Message. Dependent on your needs, you may choose the inclusion of the system data in the endpoint HTTP method configuration, in the section output, where you check in the box Include system data in response. 

{
    "ID": "776675e6-ba18-4b86-b84d-da39746c4051",
    "Status": "FinishedSuccess",
    "Link": "https://...........net/home/data-exchange/7/task/88?taskRunID=419",
    "Message": null,
    "Result": [
                {
                    "Name": "Boris",
                    "Age": 47,
                    "Nationality": "Slovak"
                },
                {
                    "Name": "Tomas",
                    "Age": 42,
                    "Nationality": "Slovak"
                }
            ]
}

Endpoint JSON (single) output

Returns first member of the array without array wrapper. The endpoint result may contain numerous JSON members, but you need to return just the first one of them. Then you select this custom endpoint output type. Note, there is no array wrapper used. The platform configuration requires the selection of the output schema - Endpoint JSON (single) Output (version). Dependent on the requirement to include or exclude the system data in response, you will check the respective check box. Works with both HTTP methods GET and POST.

Endpoint JSON (single) Output

Example with no system data in response:

{
    "Name": "Boris",
    "Age": 47,
    "Nationality": "Slovak"
}

Example with the system data in response:

{
    "ID": "4168f486-0ccd-432a-930d-04a2d223ec65",
    "Status": "FinishedSuccess",
    "Link": "https://............net/home/data-exchange/7/task/88?taskRunID=420",
    "Message": null,
    "Result": {
                "Name": "Boris",
                "Age": 47,
                "Nationality": "Slovak"
            }
}

Endpoint XML output

Returns all members of an array with element and for row elements. The platform configuration requires the selection of the output schema - Endpoint XML Output (version). Dependent on the requirement to include or exclude the system data in response, you will check the respective check box. Works with both HTTP methods GET and POST.

Endpoint XML Output

Example with no system data in response:

<root>
    <xml>
        <root>
            <row>
                <Name>Boris</Name>
                <Age>47</Age>
                <Nationality>Slovak</Nationality>
            </row>
            <row>
                <Name>Tomas</Name>
                <Age>42</Age>
                <Nationality>Slovak</Nationality>
            </row>
        </root>
    </xml>
</root>
Example with the system data in response:

<response>
    <id>3e58954e-71e5-4090-ab41-8670c0a3619f</id>
    <status>FinishedSuccess</status>
    <link>https://................net/home/data-exchange/7/task/88?taskRunID=423</link>
    <messages/>
    <result>
        <root>
            <xml>
                <root>
                    <row>
                        <Name>Boris</Name>
                        <Age>47</Age>
                        <Nationality>Slovak</Nationality>
                    </row>
                    <row>
                        <Name>Tomas</Name>
                        <Age>42</Age>
                        <Nationality>Slovak</Nationality>
                    </row>
                </root>
            </xml>
        </root>
    </result>
</response>

Endpoint XML (single) output

Returns string as XML without any validation - the first member of JSON XML array. The platform configuration requires the selection of the output schema - Endpoint XML (single) Output (version). Dependent on the requirement to include or exclude the system data in response, you will check the respective check box. Works with both HTTP methods GET and POST.

Endpoint XML (single) Output

Example with no system data in response:

<root>
    <row>
        <Name>Boris</Name>
        <Age>47</Age>
        <Nationality>Slovak</Nationality>
    </row>
    <row>
        <Name>Tomas</Name>
        <Age>42</Age>
        <Nationality>Slovak</Nationality>
    </row>
</root>
Example with the system data in response:

<response>
    <id>7c7054f8-6474-4a10-b053-1ee8f5281127</id>
    <status>FinishedSuccess</status>
    <link>https://dev-dx-099.olo.xeelo.net/home/data-exchange/7/task/88?taskRunID=425</link>
    <messages/>
    <result>
        <root>
            <row>
                <Name>Boris</Name>
                <Age>47</Age>
                <Nationality>Slovak</Nationality>
            </row>
            <row>
                <Name>Tomas</Name>
                <Age>42</Age>
                <Nationality>Slovak</Nationality>
            </row>
        </root>
    </result>
</response>

Endpoint file output

Returns the file as output and enables the download of data from the endpoint in the form of a file. i.e. in case you have an endpoint with configured HTTP GET method and "store" there a file, the output for this endpoint and method will be download of the respective file. This custom endpoint output works with GET method only.

Enpoint file output

Please note, that checking the attribute "Include system data in response" doesn't play a role in this custom output type. In case the file does exist, it will be downloaded and you will find it in the download folder. In case, the file doesn't exist, there will be a standard format JSON response with a message relating to a Failed connector.

Note: if anything goes wrong with the execution of the custom endpoint output linked task as such, the platform responds with the standard format of the error message in JSON format despite the output being JSON or XML or a file.

Endpoint HTML output

This output schema allows returning HTML content. The HTML content won't be validated on the side of integray platform and will be treated as text inside the data schema. The output returns only the first member included i.e. if there would be more members included in the output, only the first will be returned and all the others will be ignored. This output is enhancing the options in the platform as it enables to publish of previously collected, manipulated, enhanced data on the endpoint, which is then available for consequent use.

Example: Using HTML table data as the input and returning it to endpoint HTML output schema:

<html>
<head>
    <style>
        table {
            border-collapse: collapse;
        }
        th {
            font-weight: bold;
            color: white;
            background-color: blue;
            border: 1px solid black;
            padding: 5px;
        }
        td {
            border: 1px solid black;
            padding: 5px;
        }
    </style>
</head>
<body>
    <table>
        <thead>
            <tr>
                <th>ID</th>
                <th>Name</th>
                <th>Type</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>1</td>
                <td>John</td>
                <td>Employee</td>
            </tr>
            <tr>
                <td>2</td>
                <td>Mary</td>
                <td>Contractor</td>
            </tr>
            <tr>
                <td>3</td>
                <td>Steven</td>
                <td>Employee</td>
            </tr>
        </tbody>
    </table>
</body>
</html>`
HELP Configuration screen Endpoints HTML output

The result - endpoint output (not included system data in response):

HELP Configuration screen Endpoints HTML output result

Please note, that checking the attribute "Include system data in response" doesn't play a role in this custom output type. In case the output fails, there will be a standard format JSON response with a message relating to a Failed connector.

Was this page helpful?

Privacy Policy

©Integray 2024

Privacy Policy