Run Tree

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.

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:

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

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."
}