List

Lists records in the data collection page by page.

Specification

• parametersSchema – schema for parameters that can be passed to the operation.
• filterFields – list of fields from the fieldsSchema that can be used to filter the records.

Input

• parameters – parameters matching parametersSchema.
• filter – list of fields from filterFields and their values to filter the records by.
• cursor – cursor returned from the previous page of the results. If not provided, the first page is returned.

Output

• records – list of records that match the filter.
• cursor – cursor for the next page of the results. If not provided, there are no more pages.
• drilldowns – list of additional requests that should be made to this operation to get all the records. See Drilldowns for more information.

Drilldowns

If it is not possible to return all records at once and additional requests need to be made, you can return a list of drilldowns.

Each drilldown can have the following properties:

• parameters – parameters for the drilldown operation.
• filter – filter for the drilldown operation.

Example:

{
  "drilldowns": [
    {
      "parameters": {
        "recursive": true
      },
      "filter": {
        "type": "file",
        "parentFolderId": "123"
      }
    },
    {
      "parameters": {
        "recursive": true
      },
      "filter": {
        "type": "file",
        "parentFolderId": "124"
      }
    }
  ]
}

Examples when drilldown can be used:

• Requesting a list of files, but the external application only supports returning files from one folder at a time. You can return drilldowns for each folder.
• Requesting a list of tasks, but the API only supports returning tasks from a given project. You can return a list of drilldowns, one for each project.

Drilldowns can be recursive, i.e., when returning a list of files from a sub-folder, you can return drilldowns for each sub-sub-folder, and so on.

If you cannot get all the drilldowns with one request, use cursor. A response can return no records but only drilldowns—the engine will iterate over pages of drilldowns and collect them all.

Drilldowns are executed in the order they were returned, using the following logic:

• When making the original request, all the records are returned right away, and drilldowns are saved in the cursor.
• When no more cursor is returned, the engine will start making requests for drilldowns in the order they were returned.
• If drilldowns return more drilldowns, they are appended to the list of drilldowns to execute.