Skip to main content
Kinetic Community

Run Tree

This web method is used to start a new run of an existing tree.  It is typically called from a post-submit hook from the source application. The URL for this web method contains the run-tree action, followed by the parameters necessary for Kinetic Task to identify the tree it is supposed to run.

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:

  1. Source - Playground
  2. Group - Testing
  3. 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:

  1. Source - Playground
  2. Group - Testing
  3. 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:

  1. Source - Playground
  2. Group - Testing
  3. 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:

  1. Source - Playground
  2. Group - Testing
  3. 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."
}