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

The expected behavior:

• Resource Creation: POST is primarily used to create new resources. When a new resource is successfully created, the server should return a 201 Created status and provide the URI of the new resource.

• Non-Idempotent: POST is not an idempotent method, meaning that sending the same POST request multiple times may result in the creation of multiple identical resources. Each POST request can change the server's state.

• Success Response: A successful POST request typically returns a 201 Created status if a new resource is created. If the request is processed successfully but does not create a new resource, it might return a 201 Created or 204 No Content status.

• Data Validation: The server should validate the data sent in the request. If the data does not meet the required schema or contains errors, the server should return an error status like 400 Bad Request.

• Side Effects: Depending on the implementation, POST may cause side effects such as sending an email, triggering a workflow, or updating other resources.

Expected behavior

POST {companySlug}/{endpointGroupSlug}/{endpointSlug} - with task - Executes tasks

POST {companySlug}/{endpointGroupSlug}/{endpointSlug} - without task - Stores data only

---

Input

• 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.
${headers}	All request headers are serialized into a single JSON object
${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

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

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.

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

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.

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.

Rule for non sensitive messages only

You have the ability to configure a custom error message; however, these rules are not applied to error messages containing sensitive information, such as connector configuration scripts in JavaScript, SQL, Node.JS, Python, or PowerShell.

---

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 - Incoming data is transformed and then routed to specific fields based on predefined rules.

---

• Back to the GET

• Continue to the PUT

---

Was this page helpful?

×

Yes No

What is the reason for your feedback?

Tell us more:

Submit Privacy Policy