Skip to main content
Kinetic Community

Archive Trees

This web method is used to deactivate trees and local routines so they no longer show up in the system.  Archived trees are no longer runnable.  See the Restore Trees web method for the inverse of this method. The URL for this web method contains the archive-trees action.

Details

HTTP Request

Method: POST

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

Body Content:

{
    "source": "Source 1",
    "sourceGroup": "Group 1",
    "names": []
}

 

Body Content

This web method expects all data to be sent as a JSON formatted string attached as body content, and must contain properties for the source and sourceGroup parameters listed in the table below.  An optional names parameter may be provided to archive only the trees and local routines specified, otherwise all tree and local routines in the Source / Group combination will be archived.

 

Body Parameter Name Description Required / Optional
source The name of the Source that the trees and local routines belong to. Required
sourceGroup The name of the Group that the trees and local routines belong to. Required
names An array of tree and local routine names that should be archived.  If this parameter is not provided, all trees and local routines in the Source / Group combination will be archived. Optional

If the names parameter is not provided, ALL trees and local routines that belong to the source and sourceGroup parameters will be archived.  Otherwise, only trees and local routines that match the list of provided names will be archived.

 

Example:

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

In this example, all trees belonging to the Source named "Kinetic Request" and the "IT Service Catalog > iPad Request" group will be archived.

 

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": "Archived 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 archiving 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 archive 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/archive-trees

Body Content Parameters:

  1. source - Playground
  2. sourceGroup - Testing

 

​​Body Content:

{
    "source": "Playground",
    "sourceGroup": "Testing"
}

 

This example is attempting to archive all trees and local routines from the Playground source and Testing group.  The names of trees are not specified, so all trees will be archived.

 

Response Code: 200

Response Body:

{
    "message": "Archived 2 trees.",
    "trees": [
        {
            "createdAt": "2014-09-15T19:12:23.330Z",
            "createdBy": "SYSTEM",
            "id": 45,
            "name": "Archive Trees Example",
            "notes": "An example tree",
            "ownerEmail": "support@kineticdata.com",
            "source": {
                "name": "Playground"
            },
            "sourceGroup": "Testing",
            "status": "Delete",
            "updatedAt": "2014-09-15T19:32:58.663Z",
            "updatedBy": "SYSTEM"
        },
        {
            "createdAt": "2014-09-15T19:12:25.150Z",
            "createdBy": "SYSTEM",
            "definitionId": "routine_playground_testing_v1",
            "id": 46,
            "name": "Archive Routine Example",
            "notes": "An example routine",
            "ownerEmail": "support@kineticdata.com",
            "source": {
                "name": "Playground"
            },
            "sourceGroup": "Testing",
            "status": "Delete",
            "updatedAt": "2014-09-15T19:32:58.663Z",
            "updatedBy": "SYSTEM"
        }
    ]
}