PATCH

The PATCH method allows you to apply partial updates to existing resources when using endpoints. When using this method with an Integray endpoint, you can modify specific fields of a record without altering the entire resource. This makes PATCH a powerful tool for scenarios where only a subset of data needs to be updated, offering flexibility and efficiency in data management.

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

The expected behavior:

Partial Updates: PATCH modifies only specific fields of a resource, leaving other fields unchanged.
Non-Idempotent: Applying the same PATCH request multiple times might not yield the same result each time, but should be consistent if the same changes are applied.
Safe Updates: Only specified fields are updated; unspecified fields remain unaffected.
Validation and Error Handling: The server should validate the request and return appropriate error codes like 400 Bad Request or 409 Conflict if issues arise.
Success Response: Typically returns 201 Created with the updated resource or 204 No Content if no body is needed.

Expected behavior

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

PATCH {companySlug}/{endpointGroupSlug}/{endpointSlug} - without task - Not found

PATCH {companySlug}/{endpointGroupSlug}/{endpointSlug}/{id:guid} - without task - Updates properties only

Input

Input schema - The data structure that will be passed from the endpoint to the input of the task. The schema defines which parts of the resource can be updated. Refer to the relevant data schema in the reference list, or define your own Data schemas.

Payload mapping - Establishes the rules for parsing incoming JSON data into the task input schema. Each pair binds a single column of the input schema to a property in JSON. Since PATCH operations often involve partial updates, it is crucial to map only the fields that need modification.

Special placeholders that 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 PATCH request is received at this endpoint. The task processes the incoming data according to the specified schema and applies the necessary updates to the existing records.

Note

The PATCH method is not supported if the stored or submitted entity is of array type. If the data is provided as an array, the user will receive a 400 Bad Request response.

Start task async - Specifies whether the endpoint will wait for the task to complete before responding.

OFF - The task starts synchronously.
ON - The task runs asynchronously.

Synchronous task launch

The response from the endpoint 201 Created is returned after the task is completed.

Property	Description
`ID`	GUID of received endpoint data.
`Status`	Status of the finished task run.
`Message`	Error message detailing any issues encountered.
`Result`	Task output data.

Example

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

Reaching timeout

If a timeout is reached, the request is terminated with an HTTP status code 408 Request Timeout and the task run status is set to FailedTimeout.

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

This situation may occur if:

A timeout is reached on a step.
The remote agent is unavailable.
The task is not runnable.
The orchestrator on the company is disabled.

Asynchronous task execution

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

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

Example

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

To retrieve the result of the running task later, send an HTTP GET request along with the received ID to .../<endpoint_slug>/<ID>. Ensure that the Save output data option is enabled for the linked task.

Save input data - Determines whether the input data is saved to the database. Depending on the settings below, the data can be deleted during sanitization.
- Never - Input data is always deleted.
- On error - Input data is retained in the database only if the linked task fails.
- Everytime - Input data is always retained in the database.
Fail message - Customize the error messages displayed in case of a 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 entire 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 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 be used to create the response for the PATCH endpoint. Since PATCH typically modifies only part of a resource, the output schema should reflect only the changed data or the relevant parts of the resource.
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. This is useful for keeping a record of the changes made via the PATCH operation.

Include system data in response - If selected, the result of the task is encapsulated in the Data element, and additional system fields are added to the response.

Include system data in response - ON

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

Include system data in response - OFF

    {
        "updated_field": "new_value"
    }

Output step - Specifies the step after which data will be selected from the data structure to be used as the response for the PATCH request. This allows control over which part of the task's result is returned to the client.
Output mapping - Transforms the outgoing data and routes it to specific fields based on predefined rules. This ensures that the response is structured according to the requirements of the client or the system that will consume the data.

PATCH

Input

Task

Output

Feedback

Was this page helpful?