Scroll

REST - Folder Management

Management of the folder and report tree is available with REST. Unlike other resources, managing the tree affects the base configuration, and is not temporary to a session. Therefore it also affects concurrent users.

Note. All requests require Session Id URL parameter and basic request headers. In the following examples, headers are omitted for clarity.

Node JSON

The folders tree is represented as an output-only (ie. non-writeable) resource. Each object in the tree is a Node. Nodes are represented as JSON objects with the following properties:

Name Type Description
name string The name of this folder or report
leaf_flag boolean Whether this node is a report
readonly_flag boolean Whether this node is read-only for the active role
type enum Report Type (null if this is a folder)
user string The active role
entity array of Node If this is a folder, an array of the nodes contained within
Note. The top-level node has only an entity property.

Example

{
  "entity": [
    {
      "name":          "Asset Reports",
      "leaf_flag":     false,
      "readonly_flag": false,
      "type":          null,
      "user":          "Admin",
      "entity": [
        {
          "name":          "Sales Report",
          "leaf_flag":     true,
          "readonly_flag": false,
          "type":          "advanced",
          "user":          "Admin",
          "entity":        null
        },
        {
          "name":          "Financial Holdings",
          "leaf_flag":     false,
          "readonly_flag": false,
          "type":          null,
          "user":          "Admin",
          "entity": [
            {
              "name":          "Liquidity Report",
              "leaf_flag":     true,
              "readonly_flag": false,
              "type":          "expressview",
              "user":          "Admin",
              "entity":        null
            },
            {
              "name":          "Regional Holdings",
              "leaf_flag":     true,
              "readonly_flag": false,
              "type":          "dashboard",
              "user":          "Admin",
              "entity":        null
            }
          ]
        }
      ]
    }
  ]
}

Show Folders Tree

GET /rest/reports/list

Show the full folder tree for the current configuration.

Using curl

curl http://{webservice}/rest/reports/list?sid={sid} -X GET

Example response

Status: 200 OK

{
  "entity": [
    {
      "name": "Asset Reports",
... "entity": [ { "name": "Sales Report", ... "entity": null }, { "name": "Financial Holdings", ... "entity": [ { "name": "Liquidity Report", ... "entity": null } ] } ] } ] }

Folder JSON

The /rest/folders endpoint represents each folder as an output-only (ie. non-writeable) resource. Folders are represented as JSON objects with the following properties:

Name Type Description
Name string Full path from root folder to this folder
Status const Folder Status

Create a Folder

POST /rest/folders/{Name}

Name is the full path from the root folder to the name of the folder to be created. Spaces and unusual characters must be URL-encoded. Folder names are case sensitive.

Using curl

curl http://{webservice}/rest/folders/Asset%20Reports/Overseas%Holdings?sid={sid} -X POST

Example response

Status: 200 OK

{
  "Id":     null,
  "Name":   "Asset Reports/Overseas Holdings",
  "Status": "Created"
}
Note. The "Id" property is not used.

Move or Rename a Folder

POST /rest/folders/rename

Folders are moved or renamed by supplying the following JSON resource:

Name Type Writeable Description
OldName string required Full path from the root folder to the name of the folder to be moved or renamed
NewName string required Full path from the root folder to the new folder location and name

Using curl

curl http://{webservice}/rest/folders/rename?sid={sid} -X POST ^
	-d "{'OldName':'Asset Reports\\Overseas Holdings', ^
	'NewName':'Asset Reports\\Regional Holdings'}"
Note. Windows file paths are delineated by double-backslashes: \\

Example response

Status: 200 OK

{
  "Id":     null,
  "Name":   "Asset Reports/Regional Holdings",
  "Status": "Renamed"
}

Delete a Folder

DELETE /rest/folders/{Name}

Name is the full path from the root folder to the name of the folder to be created. Spaces and unusual characters must be URL-encoded. Folder names are case sensitive. The folder must be empty to be deleted.

Using curl

curl http://{webservice}/rest/folders/Asset%20Reports/Overseas%Holdings?sid={sid} -X DELETE

Example response

Status: 200 OK

{
  "Id":     null,
  "Name":   "Asset Reports/Overseas Holdings",
  "Status": "Deleted"
}

Hidden Article Information

Article Author
Exago Development
created 2017-02-21 17:26:38 UTC
updated 2017-05-16 13:36:13 UTC

Labels
REST, API, Web Service, Folders,
Have more questions? Submit a request