Import Tree

Last updated
Save as PDF

This web method is used to import a tree or local routine from a tree export file. This API method only supports trees that were exported using the Kinetic Task v4 tree export format. If you need to import trees that were exported from Kinetic Task v2 or v3, you will need to use the Import Tree form on the Kinetic Task web consoles. This method is the inverse of the Export Trees web method. The URL for this web method contains the import-tree action.

Details

HTTP Request

Method: POST

URL: /app/api/v1/import-tree

Body Content:

{
    "structure": "<tree>...</tree>"
}

Body Content

This web method expects all data to be sent as a JSON formatted string attached as body content, and must contain the structure parameter. All other parameters are optional, and will override values in the contents of the structure parameter.

Body Parameter Name	Description	Required / Optional
structure		Required
definitionId		Optional
source		Optional
sourceGroup		Optional
name		Optional
notes		Optional
ownerEmail		Optional
status		Optional
type		Optional

Example:

{
    "structure": "<tree>...</tree>"
}

In this example, the tree will be imported using all values that were exported with the tree.

Response Messages

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.
tree	Details about the imported tree.

Example response:

{
    "message": "Imported the ..."
    "tree": {
        ...
    }
}

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": "Malformed tree structure"
}

Response Codes

Response Code	Reason
200	Successful request.
400	If there was a problem importing the tree or local routine.
400	If the required structure body parameter was not provided.
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.
500	If there was an unexpected server error.

Examples

Example - Simple

This is a simple example showing how to import a tree, and override the tree name. This example does not use any authorization, so no headers need to be provided.

Method: POST

URL: /app/api/v1/import-tree

Body Content Parameters:

structure - Playground
name - Playground

Body Content:

{
    "structure": "<tree>...</tree>",
    "name": "Override Tree Name"
}

This example is attempting to import the tree export file, and then override the name of the tree that is embedded in the export file.

Response Code: 200

Response Body:

{
    "message": "Imported the \"Playground :: Documentation :: Override Tree Name\" tree",
    "tree": {
        "createdAt": "2014-09-15T17:22:18.554Z",
        "createdBy": "SYSTEM",
        "id": 87,
        "name": "Override Tree Name",
        "notes": "An example tree",
        "ownerEmail": "support@kineticdata.com",
        "source": {
            "name": "Playground"
        },
        "sourceGroup": "Documentation",
        "status": "Active",
        "updatedAt": "2014-09-15T17:22:18.554Z",
        "updatedBy": "SYSTEM"
    }
}