Run Tree
Details
Definition
Method: POST
URL: /app/api/v1/run-tree/{SOURCE}/{GROUP}/{TREE}
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 three route parameters that identity the Source, Group, and Name of the tree that should be run.
Route Parameter Name | Description | Required / Optional |
---|---|---|
SOURCE | The name of the source the tree is associated to. | Required |
GROUP | The group categorization for the tree. | Required |
TREE | The name of the tree. | Required |
Since these values contain user input that may contain non-URL friendly characters, it is recommended to encode each parameter value when constructing the URL.
Optional Body Content
Extra data for the source application can be passed as body content. The data can be sent as name/value pairs in one of two ways: a JSON formatted string attached as body content, or as form contents by setting the "Content-Type" header to "application/x-www-form-urlencoded". All data passed in this way will be sent to the source consumer, and will be available to the tree as a binding variable in the form: @source['Data']['PARAMETER_NAME'].
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 what Kinetic Task did with the API request. |
run | Details about the run that was created in Kinetic Task. |
Example response:
{ "message": "Initiated run #3 for the ...", "run": { ... } }
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": "The \"Playground :: Testing :: My First Test Tree\" tree does not exist." }
Response Codes
Response Code | Reason |
---|---|
200 | Successful request. |
400 | If there was a problem creating the run, or the trigger that starts the run. |
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 provided Source parameter does not match any sources in Kinetic Task. |
404 | If the combination of the provided Source, Group, Tree parameters do not match any trees in Kinetic Task. |
500 | If there was an unexpected server error. |
Examples
Example - Simple
This is a simple example where the Source does not have any applied API Policy Rules, so it does not require a basic authentication header.
Method: POST
URL: /app/api/v1/run-tree/Playground/Testing/My+First+Tree
Route Parameters:
- Source - Playground
- Group - Testing
- Name - My First Tree
Response Code: 200
Response Body:
{ "message": "Initiated run #4 for the \"Playground :: Testing :: My First Tree\" Tree.", "run": { "createdAt": "2014-07-17T20:39:54.419Z", "createdBy": "SYSTEM", "id": 4 } }
Example - Simple with body content
This is another simple example where the Source does not have any applied API Policy Rules, so it also does not require a basic authentication header. This example does provide data from the source application passed into the request body. The API will use this apply this data to the run.
Method: POST
URL: /app/api/v1/run-tree/Playground/Testing/My+First+Tree
Route Parameters:
- Source - Playground
- Group - Testing
- Name - My First Tree
Body Parameters:
- Source User Id - don.demo
Response Code: 200
Response Body:
{ "message": "Initiated run #5 for the \"Playground :: Testing :: My First Tree\" Tree.", "run": { "createdAt": "2014-07-17T20:41:42.596Z", "createdBy": "SYSTEM", "id": 5 } }
Notice the "sourceData" property contains the content passed from the source application. This information will be bound to the run and can be used in the tree by accessing the @source['Data'] variable in task nodes and connectors. In this example, the variable @source['Data']['Source User Id'] results in the value "don.demo".
Example - Basic Authorization
This is an example where the Source has an applied API Policy Rule that only allows access from an expected identity. This example uses an Authorization header since the API uses Basic Auth to retrieve the identity information.
Method: POST
URL: /app/api/v1/run-tree/Playground/Testing/My+First+Tree
Route Parameters:
- Source - Playground
- Group - Testing
- Name - My First Tree
Body Parameters:
- Source User Id - don.demo
Headers:
- Authorization: Basic ZG9uLmRlbW86U3VwM3JTM2NyM3Q=
Response Code: 200
Response Body:
{ "message": "Initiated run #6 for the \"Playground :: Testing :: My First Tree\" Tree.", "run": { "createdAt": "2014-07-17T21:10:43.049Z", "createdBy": "don.demo", "id": 6 } }
Example - Basic Authorization with invalid credentials
This is an example where an Authorization header was provided, but the credentials were invalid.
Method: POST
URL: /app/api/v1/run-tree/Playground/Testing/My+First+Tree
Route Parameters:
- Source - Playground
- Group - Testing
- Name - My First Tree
Body Parameters:
- Source User Id - don.demo
Headers:
- Authorization: Basic ZG9uLmRlbW86d3JvbmdfcGFzc3dvcmQ=
Response Code: 401
Response Body:
{ "message": "Authentication credentials were missing or incorrect." }