Skip to main content
Kinetic Community

Update Deferred Task

This web method is used to update a deferred task in an existing run.  This is similar to the Complete Deferred Task, except the task engine only processes child tasks connected with "update" connectors.  This web method is typically called from a post-submit hook from the source application. The URL for this web method contains the update-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/update-deferred-task/{SOURCE}

Body Content:

{
    "message": "Updated 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 updated.",
    "results": {
        "assigned_technician": "John Doe",
        "ticket_id": "TKT-555",
        "ticket_status": "In Progress",
        "ticket_updated_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 API request.
trigger Details about the trigger that was created in Kinetic Task to update the deferred task.

 

Example response:

{
    "message": "Updated 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: 400

Response Body:

{
    "message": "The token \"BAD_TOKEN\" does not match a corresponding task record."
}

 

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 token value does not match any tasks in Kinetic Task.
400 If there was a problem creating the trigger that updates 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 update a deferred task.  This example does not use any authorization, so no headers need to be provided.  Body content is always required to update 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 the URL route parameter when calling the API.

 

update-deferred-task-token.png

 

Method: POST

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

Route Parameters:

  1. Source - Playground

​​Body Parameters:

{
   "token": "a93b6fdd2b367046cf928e75a261a2b1fa9e5139",
   "message": "Requesting feedback from the original user",
   "results": {
       "Source User Id": "don.demo",
       "Source Record Id": "555"
   }
}

 

Response Code: 200

Response Body:

{
    "message": "Updated the \"Deferred Task\" deferred task.",
    "trigger": {
        "createdAt": "2014-07-18T14:11:01.883Z",
        "createdBy": "SYSTEM",
        "id": 12,
        "nodeId": "utilities_defer_v1_1",
        "nodeName": "Deferred Task",
        "run": {
            "id": 8,
            "sourceId": 4,
            "tree": {
                "name": "My First Tree",
                "sourceGroup": "Testing",
                "source": {
                    "name": "Playground"
                }
            }
        }
    }
}