Box actions

The Box block finds, reads and organises files and folders in Box, and manages enterprise users. For the plain-language guide, see Box.

When to use it

Use it for a daily document sync: list the files changed since the last run, download each one or read its PDF pages, and hand the result to the next step. There is no Box trigger and no upload action.

Connection

• Provider id: box. Box OAuth.
• The block sees only what the Box user behind the connection can see. listUsers and createUser need an enterprise admin connection.
• Pin an account with config.connection. Without it, the step uses the company's default Box connection.

Actions

Settings

Folder id 0 is the root folder.

List Files Updated Since

• Needs query or fileExtensions, because Box search needs a query. With only fileExtensions (for example pdf,xlsx), the query is the extensions joined with OR.
• The window starts at since (ISO 8601) or hoursBack hours ago (default 24), minus 10 minutes for Box's search index lag. A file near the boundary can appear in two runs; de-duplicate by id and modified_at.
• It pages through every result, newest first, 200 at a time. More than 10,000 matches fails the step; narrow with ancestorFolderIds, fileExtensions or query.
• Each file carries id, type, name, size, extension, created_at, modified_at, parent and path_collection.

Download File

• Without persistToFolder, the file must be 3 MiB or smaller and comes back as base64 content with name, size and mimeType.
• With persistToFolder (a folder path in Files), the file can be up to 96 MiB. It is saved as <fileId>-<name> and the step returns workspaceFileId, filePath and persisted: true with no content. Pass workspaceFileId as fileId to the PDF block or the Workspace Files block.
• A file Box has not finished processing fails with "not ready to download yet"; retry later.

Read PDF Pages

• Fetches only the byte ranges the selected pages need, up to 96 MiB in total.
• pages is 1-based, such as 1-2, 14. firstPages and lastPages take pages from the front and end. Empty reads the whole document, up to 500 pages.
• Scanned image-only pages return empty text.

Paging and filters

• listFolderItems, listUsers and search take limit and offset. listFolderItems returns entries, totalCount and offset; type (file, folder or web_link) filters the returned page.
• deleteFile and deleteFolder move items to the trash. deleteFolder refuses a non-empty folder unless recursive is true.

Output

• listFilesUpdatedSince returns since, count and files.
• downloadFile returns fileId, name, size, mimeType and either content or workspaceFileId and filePath.
• readPdfPages returns fileId, name, size, bytesRead, pages (text of each selected page), text (all of it joined), pageCount, pagesRead and fileName.
• The other actions return the Box API object.

Read fields with {{steps.<stepId>.<path>}}, for example {{steps.new_invoices.files}}.

Example

Every morning, list the PDFs changed in the invoices folder in the last day, then save the newest one to Files so a PDF step can read it.

{
  "name": "Read new Box invoices",
  "trigger": { "type": "schedule", "cron": "0 7 * * *", "timezone": "America/Los_Angeles" },
  "steps": [
    {
      "id": "new_invoices",
      "type": "action",
      "name": "List new invoice PDFs",
      "action": "box.listFilesUpdatedSince",
      "config": {
        "fileExtensions": "pdf",
        "ancestorFolderIds": "123456789",
        "hoursBack": 24
      }
    },
    {
      "id": "save_invoice",
      "type": "action",
      "name": "Save the newest invoice to Files",
      "action": "box.downloadFile",
      "config": {
        "fileId": "{{steps.new_invoices.files.0.id}}",
        "persistToFolder": "box-invoices"
      }
    }
  ]
}

Live catalog

• GET /api/v1/blocks/box returns the actions and fields.
• GET /api/v1/blocks/box/actions/<operation>/examples returns stored examples where they exist.

Errors and limits

• downloadFile waits up to 5 minutes for the file content.
• A missing required field fails the step before Box is called. Box errors fail the step with Box's message.