Box integration

What it does

The Box integration lets your agency move work in and out of your clients' Box accounts without leaving TaskJuice. Connect a Box account once and your workflows can read and write folders and files, upload and download content, mint shared links, post comments, apply metadata templates, and search the account through the Box Content API v2. When something happens inside a watched folder or file — an upload, a comment, a signature, a collaboration change — Box notifies TaskJuice and your workflow reacts in seconds.

Connect a Box account

1. Open your workspace in TaskJuice and navigate to Connections.
2. Choose Box and click Connect.
3. Sign in to the Box account you want to wire up and approve the requested scopes (root_readwrite, manage_webhook).
4. TaskJuice returns you to the workspace with the connection ready to use in any workflow.

To revoke access, sign in at box.com, open Account Settings, go to Apps, and remove the TaskJuice authorization. The full grant flow is documented in the Box OAuth 2.0 guide.

Set up a trigger

Box webhooks are created in Box, not in TaskJuice. Every Box webhook watches one specific file or folder, which is a choice only you can make — so TaskJuice does not create them for you.

For each trigger you want to use:

1. Add the Box trigger to your workflow and publish it. TaskJuice mints a delivery URL for the connection.
2. In Box, open the Developer Console, pick your app, and go to Webhooks (or call POST /2.0/webhooks directly).
3. Create a V2 webhook whose address is the TaskJuice delivery URL, whose target is the file or folder you want to watch, and whose triggers include the Box event strings the TaskJuice trigger listens for.
4. Under Manage signature keys, copy the primary key and paste it into the trigger's inbound-auth field in TaskJuice.

A webhook on a folder also covers items inside it, so watch the highest folder that makes sense rather than one webhook per file. A webhook only delivers the trigger strings you list on it, so a Box Sign trigger needs the matching SIGN_REQUEST.* strings added explicitly — Box accepts them on a folder target, but they are not implied by the file and folder ones. Box allows one webhook per (item, application, user) and 1000 webhooks per application per user, and it cannot watch the root folder (id 0).

Every inbound POST is authenticated by recomputing HMAC-SHA256 over the raw request body concatenated with the box-delivery-timestamp header using your Box webhook primary key, then comparing the base64 digest against the value Box sends in the box-signature-primary header. Activations that fail the check are rejected before they reach your workflow.

Triggers

Every Box event arrives as { type, id, created_at, trigger, webhook, created_by, source, additional_info }. Read trigger to tell apart the Box events a TaskJuice trigger folds together, and read the record off source.

source is the full record, not a stub. Verified against a live Box account: a file event carries all 22 fields Box holds — name, size, sha1, description, file_version, parent, path_collection, item_status, shared_link, four timestamps and created_by / modified_by / owned_by. A folder event carries the equivalent 21. You do not need a Get File step to read them.

What source actually contains depends on the event family, and it is not always the item:

Box never sends file CONTENT on a webhook. Add a Download File step on source.id when a workflow needs the bytes.

Box Sign is the exception to the table. On the three Sign triggers source is the DOCUMENT being signed — the same file record a file trigger sends — and the sign-specific data rides on additional_info, which on this family alone is an object rather than an array. Read additional_info.sign_request_id and additional_info.signer_emails; to read a signer's individual state, call GET /2.0/sign_requests/{id} with an HTTP step on the same connection.

Files

• box/file-uploaded — a file is uploaded to, or moved into, the watched folder.
• box/file-copied — a file is copied.
• box/file-moved — a file moves from one folder to another.
• box/file-renamed — a file is renamed.
• box/file-removed — a file is trashed or permanently deleted. Read trigger to tell the two apart.
• box/file-restored — a file is restored from trash.
• box/file-accessed — a file is previewed or downloaded. Read trigger to tell the two apart.
• box/file-lock-changed — a file is locked or unlocked.

Folders

• box/folder-created — a folder is created inside the watched folder.
• box/folder-changed — a folder is renamed, moved or copied. Read trigger to tell the three apart.
• box/folder-removed — a folder is trashed or permanently deleted.
• box/folder-restored — a folder is restored from trash.
• box/folder-downloaded — a folder is downloaded.

Comments, tasks and collaborations

• box/comment-created — a comment is created on a file.
• box/comment-changed — a comment is edited or deleted.
• box/task-assignment-created — a task is assigned on a file.
• box/task-assignment-updated — a task assignment changes, for example a reviewer approves or rejects it.
• box/collaboration-created — a collaboration is created on the watched folder.
• box/collaboration-changed — a collaboration is accepted, rejected, updated or removed.

Shared links and metadata

• box/shared-link-created — a shared link is created on the watched item.
• box/shared-link-changed — a shared link is updated or deleted.
• box/metadata-instance-created — a metadata template instance is applied to a file or folder.
• box/metadata-instance-changed — a metadata template instance is updated or removed.

Box Sign

• box/sign-request-completed — a Box Sign request is completed by every signer.
• box/sign-request-signed — a signature is requested from a signer, or a signer signs.
• box/sign-request-failed — a Box Sign request is declined, expires, bounces a signer email, or errors while finalizing.

Catch-all

• box/content-event — any subscribed Box event that has no dedicated TaskJuice trigger above. Read trigger to branch on the Box event string.

Actions

Folders

• box/get-folder fetches metadata for a single folder by id. Use 0 for the All Files root.
• box/list-folder-items lists the immediate children of a folder, paged with a marker.
• box/create-folder creates a folder inside the specified parent.
• box/update-folder renames a folder or edits its description.
• box/delete-folder moves a folder to the trash. Box refuses a non-empty folder with a 400 unless Delete Contents is on.

Files

• box/get-file fetches metadata for a single file — name, size, sha1, parent folder, owner, and shared link.
• box/update-file renames a file or edits its description.
• box/copy-file copies a file into a destination folder, optionally renaming the copy.
• box/move-file reparents a file into a different folder, optionally renaming it in the same call.
• box/delete-file moves a file to the Box trash, restorable for 30 days by default.

Content

• box/upload-file uploads a file into a Box folder through the Box upload host, taking a file reference produced by an earlier step.
• box/download-file downloads a file's bytes and stores them as a TaskJuice file reference a later step can re-upload or attach.

Sharing, comments and metadata

• box/create-file-shared-link mints or replaces the shared link on a file and returns the link URL.
• box/create-folder-shared-link mints or replaces the shared link on a folder and returns the link URL.
• box/create-comment posts a comment on a file. Use Tagged Message to @-mention collaborators.
• box/create-file-metadata applies a metadata template instance to a file.
• box/get-file-metadata reads one metadata template instance from a file.

Search

• box/search searches files and folders by query string, with an optional result-type filter.
• box/find-file searches and returns only file results.
• box/find-folder searches and returns only folder results.

Known limitations

• The Box API enforces per-app and per-user rate limits. When a 429 status is returned, TaskJuice surfaces it as a retryable error so the workflow can back off and retry.
• Box search is paged by Offset and Page Size, not by a cursor. Offset must be a multiple of Page Size — with a page size of 25, walk the pages as offset 0, 25, 50; any other value is rejected with a 400. Box also rejects an offset above 10000, so narrow the query rather than paging deeper. box/list-folder-items is the one listing action that pages by marker, because that endpoint supports it.
• Folder and file ids are entered as text. Box publishes no folders-only listing endpoint — GET /2.0/folders/{id}/items interleaves files, folders and web links with no type filter — so a folder dropdown would be less useful than pasting the id from the Box URL.
• Webhooks must be created in Box against a specific file or folder target, and TaskJuice cannot create them for you. Box's webhook listing does not return the delivery address, so TaskJuice also cannot detect or reconcile webhooks you remove in Box — if a trigger goes quiet, check the webhook still exists in the Developer Console.
• Folder and file names are case-preserving but case-insensitive within a parent in Box; pass names in the casing you want surfaced in the UI.