Management of the folder and report tree is available with the REST Web Service API. Unlike other resources, managing the tree affects the base configuration, and is not temporary to a session. Therefore it also affects concurrent users.
NoteAll requests require a Session ID URL parameter and basic request headers. In the following document, headers are omitted in the interest of brevity.
ImportantBeginning with v2020.1 it is strongly recommended to set the Storage Management identity keys before manipulating the folder tree as it can be arranged differently for different parties of users.
Node JSON
The Report 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:
NoteThe top-level node has only an Entity property.
| Name | Type | Description |
|---|---|---|
| name | string | The name of this folder or report |
| leaf_flag | boolean | Whether this node is a report. true if the item is a report, false if it is not |
| 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 (v2021.1) entity (pre-v2021.1) | array of Node | If this is a folder, an array of the nodes contained within |
| content_id v2021.1+ | string | the content_id of this item in the Storage Management database |
| content_type v2021.1+ | enum | integer value from wrContentType — the type of item this is (e.g. report, folder) |
| report_type v2021.1+ | enum | integer value from wrReportType — the type of report this item is (e.g. ExpressView, Advanced). This is a duplicate of the type property above. |
| access_flags v2021.1+ | integer | a decimal representation of the access_flags from the content_access table of this content item |
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
Show the full Report Tree for the current configuration.
GET /rest/Reports/List
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 (i.e. non-writable) 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
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.
POST /rest/Folders/{Name}
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"
}
NoteThe 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 | Writable | Description |
|---|---|---|---|
| OldName | string | required | Full path from the root to the folder to be moved or renamed |
| NewName | string | required | Full path from the root 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'}"
NoteWindows file paths are delineated by double-backslashes:
\\
Example response
Status: 200 OK
{
"Id": null,
"Name": "Asset Reports/Regional Holdings",
"Status": "Renamed"
}
Delete a Folder
Name is the full path from the root to the name of the folder to be created. Spaces and special characters must be URL-encoded. Folder names are case sensitive. The folder must be empty to be deleted.
DELETE /rest/Folders/{Name}
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"
}