Complete Deferred Task
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" } } } } }