Skip to main content

REST — Folders

  • Updated

REST — Folders

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.

light bulb

All requests require a Session Id URL parameter and basic request headers. In the following topic, headers are omitted in the interest of brevity.

red exclamation point

Beginning 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 (that is non-writable) resource. Each object in the tree is a Node. Nodes are represented as JSON objects with the following properties:

light bulb

The top-level node has only an Entity property.

NameTypeDescription
namestringThe name of this folder or report
leaf_flagBooleanWhether this node is a report.
true if the item is a report, false if it is not
readonly_flagBooleanWhether this node is read-only for the active role
typeenumReport Type (null if this is a folder)
userstringThe active role
Entity (v2021.1)entity (pre-v2021.1)array of NodeIf this is a folder, an array of the nodes contained within
content_id v2021.1+stringthe content_id of this item in the Storage Management database
content_type v2021.1+enuminteger value from wrContentType — the type of item this is (for example report, folder)
report_type v2021.1+enuminteger value from wrReportType — the type of report this item is (for example ExpressView, Advanced). This is a duplicate of the type property above.
access_flags v2021.1+integera 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 (that is non-writable) resource. Folders are represented as JSON objects with the following properties:

NameTypeDescription
NamestringFull path from root folder to this folder
StatusconstFolder 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"
}
light bulb

The Id property is not used.

Move or Rename a Folder

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

POST /rest/Folders/Rename
NameTypeWritableDescription
OldNamestringrequiredFull path from the root to the folder to be moved or renamed
NewNamestringrequiredFull 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 ReportsOverseas Holdings', ^
	'NewName':'Asset ReportsRegional Holdings'}"
light bulb

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

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"
}

Related articles