Complete Deferred Task

Last updated
Save as PDF

This web method is used to complete a deferred task in an existing run. This is similar to the Update Deferred Task, except this method will complete the task and continue processing any child nodes attached with 'Complete' connectors. It is typically called from a post-submit hook from the source application. The URL for this web method contains the complete-deferred-task action, followed by the name of the Source the tree is attached to. The source URL parameter must be URL encoded. The body content must contain the unique token value assigned to the deferred task. The body content may also contain a message, and results from the external process.

Details

HTTP Request

Method: POST

URL: /app/api/v1/complete-deferred-task/{SOURCE}

Body Content:

{
    "message": "Completed the task in the external system",
    "results": {
        "externalId": "EXT-555"
    },
    "token": "TOKEN"
}

Notes: The parts in the URL denoted by curly braces {} are called route parameters. These are pieces of data that can be passed to the API as variables.

URL Route Parameters

This method requires only one route parameter, which is the name of the Source the tree is attached to.

Route Parameter Name	Description	Required / Optional
SOURCE	The name of the Source the tree is attached to.	Required

Body Content

This method also expects extra data to be passed from the source application. This data will be added to the deferred task as Deferred Task Results. The data must be sent as a JSON formatted string attached as body content, and must contain a property named "token", which contains the unique token value for the task.

Body Parameter Name	Description	Required / Optional
message	A message that will be attached to the task. Usually pass some information from the source application indicating what was done to trigger the completion of this task.	Optional
results	Any data that should be available in the tree as results of this node.	Optional
token	The unique key or token that identifies the deferred task.	Required

Example:

{
    "message": "Support ticket TKT-555 was closed.",
    "results": {
        "assigned_technician": "John Doe",
        "ticket_id": "TKT-555",
        "ticket_status": "Closed",
        "ticket_closed_time": "2014-09-12T14:00:06Z"
    },
    "token": "unique_token_value_for_task"
}

HTTP Response

Response Type: application/json

Response Data:

A successful API response will contain a 200 response code and a JSON formatted response body. The JSON response object will contain the following properties:

Response Property	Description
message	A message describing the action Kinetic Task took based on the the API request.
trigger	Details about the trigger that was created in Kinetic Task to complete the deferred task.

Example response:

{
    "message": "Completed the ...",
    "trigger": {
        ...
    }
}

A failed API response will contain either a 400 or a 500 series response code based on the exception type, and a JSON formatted response body containing the exception message. See the table below for the types of responses that may be encountered with this API web method.

Example of a failed request:

Response Code: 404

Response Body:

{
    "message": "Unknown source: SOURCE NAME."
}

Response Codes

Response Code	Reason
200	Successful request.
400	If no body content was sent, or was not sent as JSON, a message will be returned that says "Malformed application/json content".
400	If the "token" parameter was not sent in the body content, or if the provided token value does not match any tasks in Kinetic Task.
400	If there was a problem creating the trigger that completes the task.
401	If a Basic Authentication header was provided, but the credentials were not valid.
403	If the source has any applied API policy rules, and one or more of the policy rules was violated.
404	If the source route parameter does not match any Source in Kinetic Task.
500	If there was an unexpected server error.

Examples

Example - Simple with required body content

This is a simple example showing how to complete a deferred task. This example does not use any authorization, so no headers need to be provided. Body content is always required to complete a deferred task, so this example shows that also.

In this example, you can see a deferred task was created during a run. The screenshot below shows the token that was automatically created for this deferred task. The value of this token will be used as the token parameter when calling the API. Since this API method requires the source name as well, the value "Playground" needs to be added as a URL route parameter when the call is made.

Method: POST

URL: /app/api/v1/complete-deferred-task/Playground

Route Parameters:

Source: Playground

Body Parameters:

{
   "token": "443944c206034ea2ca848af3f981b24d5a058996",
   "message": "Record in source application has been completed",
   "results": {
       "Source User Id": "don.demo",
       "Source Record Id": "555"
   }
}

Response Code: 200

Response Body:

{
    "message": "Completed the \"Deferred Task\" deferred task.",
    "trigger": {
        "createdAt": "2014-07-18T13:47:48.382Z",
        "createdBy": "SYSTEM",
        "id": 10,
        "nodeId": "utilities_defer_v1_1",
        "nodeName": "Deferred Task",
        "run": {
            "id": 8,
            "sourceId": 4,
            "tree": {
                "name": "My First Tree",
                "sourceGroup": "Testing"
                "source": {
                    "name": "Playground"
                }
            }
        }
    }
}