Skip to main content
Kinetic Community

Clone Trees

This web method is used to clone trees and local routines from one Source / Group to another Source / Group, and is similar to the Move Trees web method. The URL for this web method contains the clone-trees action.

Details

HTTP Request

Method: POST

URL: /app/api/v1/clone-trees

Body Content:

{
    "source": {
        "from": "Source 1",
        "to": "Source 2"
    },
    "sourceGroup": {
        "from": "Group 1",
        "to": "Group 2"
    },
    "localRoutines": [
        {
            "from": "routine_source1_group1_v1",
            "to": "routine_source2_group2_v2"
        }
        {
            "from": "routine_source1_group1_v2",
            "to": "routine_source2_group2_v2"
        }
    ],
    "names": []
}

 

Body Content

This web method expects all data to be sent as a JSON formatted string attached as body content, and must contain all properties for the source and sourceGroup parameters listed in the table below.  In addition, if the Source / Group to clone trees from contains any local routines, new unique definition ids must be provided for the cloned local routines.

 

Body Parameter Name Description Required / Optional
source A JSON object representing the name of the Source where trees and local routines should be moved from, and the name of the Source where trees and local routines should be moved to. Required
source.from The name of the Source where trees and local routines should be moved from. Required
source.to The name of the Source where trees and local routines should be moved to. Required
sourceGroup JSON object indicating the name of the Source Group to copy the trees / local routines from, and the name of the Source Group to copy the trees / local routines to. Required
sourceGroup.from The name of the Group within the source.from Source parameter value where trees and local routines should be moved from. Required
sourceGroup.to The name of the Group within the source.to Source parameter value where trees and local routines should be moved to. Required
localRoutines A JSON object indicating the definitionIds of all local routines in the Source / Group being cloned, and what the new values should be for the new local routines.  This is necessary because all routines must contain unique definition ids. Optional *
names An array of tree and local routine names that should be moved.  If this parameter is not provided, all trees and local routines in the Source / Group combination will be moved. Optional

If the names parameter is not provided, ALL trees and local routines that belong to the source.from and sourceGroup.from parameters will be moved into to the source.to Source, and the group property will be changed to match the value of the sourceGroup.to parameter.  Otherwise, only trees and local routines that match the list of provided names will be moved.

* If the Source / Group / Names combination being cloned contains any local routines, then the localRoutines parameter is required and must contain the defintionIds of the local routines being cloned, and what the new definitionIds should be.

 

Example:

{
    "source": {
        "from": "Kinetic Request",
        "to": "Kinetic Request"
    },
    "sourceGroup": {
        "from": "IT Service Catalog > iPad Request",
        "to": "IT Service Catalog > iPhone Request"
    }
}

In this example, all trees belonging to the Source named "Kinetic Request" and the "IT Service Catalog > iPad Request" group will be moved to the "IT Service Catalog > iPhone Request" group within the same source.  All trees will be moved in this example because a list of tree names and map of local routine definitionIds was omitted from the body content.

 

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.
trees A list of trees

 

Example response:

{
    "message": "Cloned 2 trees."
    "trees": [
        {...},
        {...}
    ]
}

 

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": "Unknown source: Non Existent Source"
}

 

Response Codes

Response Code Reason
200 Successful request.
400 If there was a problem cloning any of the trees or local routines.
400 If any of the required body parameters 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 clone all trees and local routines that match the source and sourceGroup parameters, and assign a new definitionId to the cloned local routine.  This example does not use any authorization, so no headers need to be provided.

 

Method: POST

URL: /app/api/v1/clone-trees

Body Content Parameters:

  1. source.from - Playground
  2. source.to - Playground
  3. sourceGroup.from - Testing
  4. sourceGroup.to - Documentation
  5. localRoutines.from - routine_playground_testing_v1
  6. localRoutines.to - routine_playground_documentation_v1

​​Body Content:

{
    "source": {
        "from": "Playground",
        "to": "Playground"
    },
    "sourceGroup": {
        "from": "Testing",
        "to": "Documentation"
    },
    "localRoutines": [
        "from": "routine_playground_testing_v1",
        "to": "routine_playground_documentation_v1"
    ]
}

 

This example is attempting to clone all trees and a single local routine from the Playground source and Testing group, to the Playground source and Documentation group.  The name of the trees is not specified, so all trees will be cloned.

 

Response Code: 200

Response Body:

{
    "message": "Cloned 2 trees.",
    "trees": [
        {
            "createdAt": "2014-09-15T17:22:18.554Z",
            "createdBy": "SYSTEM",
            "id": 23,
            "name": "Clone Trees Example",
            "notes": "An example tree",
            "ownerEmail": "support@kineticdata.com",
            "source": {
                "name": "Playground"
            },
            "sourceGroup": "Documentation",
            "status": "Active",
            "updatedAt": "2014-09-15T17:22:18.554Z",
            "updatedBy": "SYSTEM"
        },
        {
            "createdAt": "2014-09-15T17:22:18.997Z",
            "createdBy": "SYSTEM",
            "definitionId": "routine_playground_documentation_v1",
            "id": 24,
            "name": "Clone Routine Example",
            "notes": "An example routine",
            "ownerEmail": "support@kineticdata.com",
            "source": {
                "name": "Playground"
            },
            "sourceGroup": "Documentation",
            "status": "Active",
            "updatedAt": "2014-09-15T17:22:18.997Z",
            "updatedBy": "SYSTEM"
        }
    ]
}