Move Trees
Details
HTTP Request
Method: POST
URL: /app/api/v1/move-trees
Body Content:
{ "source": { "from": "Source 1", "to": "Source 2" }, "sourceGroup": { "from": "Group 1", "to": "Group 2" }, "names": [] }
Body Content
This web method expects all data to be passed from the source application. The data must 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.
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 | A 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 |
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.
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 and local routines 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 and local routines will be moved in this example because a list of tree names 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": "Moved 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 moving 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 update the source group for all trees and local routines that match the source and sourceGroup parameters. This example does not use any authorization, so no headers need to be provided.
Method: POST
URL: /app/api/v1/move-trees
Body Content Parameters:
- source.from - Playground
- source.to - Playground
- sourceGroup.from - Testing
- sourceGroup.to - Documentation
- names - Move Trees Example
Body Content:
{ "source": { "from": "Playground", "to": "Playground" }, "sourceGroup": { "from": "Testing", "to": "Documentation" }, "names": [ "Move Trees Example" ] }
This example is attempting to move a single tree from the Playground source and Testing group, to the Playground source and Documentation group. The name of the tree is specified as "Move Trees Example". If any other trees are in the Playground source and belong to the Testing group, they will remain there.
Response Code: 200
Response Body:
{ "message": "Moved 1 tree.", "trees": [ { "createdAt": "2014-07-15T13:11:48.903Z", "createdBy": "SYSTEM", "id": 22, "name": "Move Trees Example", "notes": "An example tree", "ownerEmail": "support@kineticdata.com", "source": { "name": "Playground" }, "sourceGroup": "Documentation", "status": "Active", "updatedAt": "2014-07-17T20:39:54.419Z", "updatedBy": "SYSTEM" } ] }