Skip to content
background-image background-image

POST

The POST method within endpoint usage enables you to submit and process data. When employing this method with an Integray endpoint, you can securely transmit data, initiate integration tasks, and efficiently manage creating new records with the option to configure custom failure messages and incorporate system data into the response.

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

Input

Help_Configurations_Endpoints_POST

  • Input schema - The data structure that will be passed from the endpoint to the input of the task. Find the relevant data schema in the reference list. If not found, define your own Data schemas.

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

    Following special placeholders can be used:

Placeholder Description
${body} Entire parsed JSON.
${bodyBase64} Entire parsed JSON as Base64 string.
${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_Configurations_Endpoints_POST_TASK

  • Start task - A task that will be initiated when a POST request is received at this endpoint. To pass the incoming data to the task for processing, select Input schema and set Payload mapping.

  • Start task async - Specifies if the endpoint will wait with response until the task is completed.

    • OFF - the task is started synchronously.
    • ON - the task is running asynchronously.

    Synchronous task launch

    The response from the endpoint 201 Created is returned after the completion of the bound task.

    Property Description
    ID GUID of received endpoint data.
    Status Status of finished task run.
    Message Error message describing error in detail.
    Result Task output data.

    Example

        {
        "ID": "e1d68685-dd93-ec11-8708-c89402b99bb6",
        "Status": "FinishedSuccess",
        "Message": null,
        "Result": [
            {
                "hello": "Bob"
            }
        ]
    }

    Reaching timeout

    If a timeout is reached, the request is terminated with HTTP status code 400 Bad Request and task run status FailedTimeout.

        {
        "ID": "2373a025-de93-ec11-8708-c89402b99bb6",
        "Status": "FailedTimeout",
        "Message": null,
        "Result": null
    }

    This situation can occur if:

    • A timeout is reached on the step.
    • The remote agent is unavailable and has timed out.
    • The task is not in the runnable state.
    • The orchestrator on the company is disabled.

    Asynchronous task execution

    Response (201 Created) is returned from endpoint immediately. This response contains:

    Property Description
    ID GUID of received endpoint data.
    Status Status of executed task run. It will be always Scheduled.
    Message Error message. It will be always null.
    Result Task output data. It will be always null.

    Example

        {
        "ID": "bed9e935-d993-ec11-8708-c89402b99bb6",
        "Status": "Scheduled",
        "Message": null,
        "Result": null
    }

    If you want to get the result of the running task later, send an HTTP GET request together with the received ID to .../<endpoint_slug>/<ID>. Remember to enable the Save output data option for the linked task.

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

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

  • Output schema - The data structure that will make 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

Was this page helpful?

Privacy Policy

©Integray 2024

Privacy Policy