How to use IBM App Connect with Box

Box is a secure web-based file-sharing service that helps your team to collaborate. You can create and edit documents with your colleagues in real time from anywhere and on any device.

With Box, the whole team can see the same set of files, and can change those files in real time from anywhere, on any device. So no sending copies of files as email attachments, and everyone always has the latest file version on hand, making collaboration seamless. Use App Connect to connect additional apps to Box. So whenever a new campaign is created in Salesforce, for example, a folder is created in Box automatically, making your team more collaborative and saving time for other work.

  • A connector in IBM App Connect Enterprise as a ServiceApp Connect Enterprise as a Service connector
  • A connector in IBM App Connect on IBM CloudCloud-managed connector
  • A local connector in a Designer instance of IBM App Connect in containers (Continuous Delivery release)Local connector in containers (Continuous Delivery release) or later
  • A local connector in a Designer instance of IBM App Connect in containers (Long Term Support)Local connector in containers (Long Term Support release)

Connecting to Box

To connect App Connect to a Box account, select the type of user:
  • Admin user
  • Non-admin user
Then, provide the following connection details:
  • Email address: The email address used to log in to Box.
  • Password: The password for the specified email address.

To connect to Box from the App Connect Designer Catalog page for the first time, under Box click Connect. When prompted, grant App Connect read and write access to the files and folders that are stored in Box. This creates an account in App Connect.

For more information about ways to connect to Box, see Managing accounts in App Connect.

  • If you are already logged in to Box in the same browser window as App Connect on IBM Cloud®, App Connect connects to that Box account without prompting you for the email address and password. To connect to a different Box account, log out from Box first or open App Connect in a new browser window.
  • If you don't have a Box account, you can create an individual account to try Box for free.

Before you use the account that is created in App Connect in a flow, rename the account to something meaningful that helps you to identify it. To rename the account on the Catalog page, select the account, open its options menu (⋮), then click Rename Account.

What should I consider first?

Before you use App Connect Designer with Box, take note of the following considerations:

  • (General consideration) You can see lists of the trigger events and actions that are available on the Catalog page of the App Connect Designer.

    For some applications, the events and actions in the catalog depend on the environment (IBM® Cloud Pak for Integration or App Connect on IBM Cloud) and whether the connector supports configurable events and dynamic discovery of actions. If the application supports configurable events, you see a Show more configurable events link under the events list. If the application supports dynamic discovery of actions, you see a Show more link under the actions list.

  • (General consideration) If you are using multiple accounts for an application, the set of fields that is displayed when you select an action for that application can vary for different accounts. In the flow editor, some applications always provide a curated set of static fields for an action. Other applications use dynamic discovery to retrieve the set of fields that are configured on the instance that you are connected to. For example, if you have two accounts for two instances of an application, the first account might use settings that are ready for immediate use. However, the second account might be configured with extra custom fields.
  • When you use the 'Create file' action to add a file to Box, the following points apply:
    • You must specify a parent folder for the file that you want to create. This folder must already exist in Box, and can be selected from a pre-populated list of Box folders in your account.
      Create file fields for Box with folder selected
      Tip: If you want to specify a dynamic value (which is returned by a previous event or action) for a folder instead of a static value from the pre-populated list, you can switch to advanced mode to set this value. You'll notice that the drop-down list is converted to a text Box, which you can then use to map to a folder ID from a previous node.
      Specifying a dynamic value for a folder using advanced mode
    • If you don't provide an extension for the file name, a text file (.txt) is created by default.
    • You must use the Type of file field to indicate whether the file content should be treated as plain text (Text), or whether base64 encoding (Binary) should be applied for file formats such as PDF, Microsoft Word, and so on.
  • When you use the 'Create folder' action to create a Box folder, the folder will be created at the root level by default. This is indicated by the default value of 0 (zero) that is shown in the Parent ID field.
    Create folder fields for Box

    In the Box UI, you can find this ID in your root folder's URL.

    Parent ID in a Box root folder's URL

    To specify a different parent folder for the folder being created, overwrite the default ID of 0 with a hardcoded value or a mapped value. The parent folder must already exist.

    • To obtain the hardcoded ID of a parent folder, open the folder in Box; the folder's ID is shown as a sequence of numbers at the end of the URL in the browser address bar. For example, in the URL, the folder ID is 31234567893.
    • If your flow contains a previous action that returns a folder ID (for example, a 'Retrieve folders' action), you can also specify the parent ID as a mapped field.
      Parent ID field showing a mapped value
  • When retrieving or transferring the contents of a file, the maximum permitted file size is 10 MB if the file content needs to be parsed or transformed using JSONata functions. Otherwise, the maximum file size is 50 MB.

    For the 'Create file' action, you can specify the file content by specifying text or by mapping to content from a previous node in the flow. If mapping to content, specify only a single mapped value, and do not append or prepend a string of text to the mapped value. Valid and invalid examples are shown in the following table.

    Valid examples Invalid examples
    Valid example showing File content field mapped to text only
    Valid example showing File content field mapped to Box file content only
    Invalid example showing Box File content field mapped to preprended text and Box file content
    Invalid example showing File content field mapped to both Box file content and appended text
    Invalid example showing File content field mapped to two instances of Box file content
  • When you use the 'Retrieve file metadata' action, you must specify a filter condition. You must either provide the ID of a Box file (ID condition), or provide a search string (Search string condition) that is to be searched in the name, description, and comments of files.
  • When you use the 'Create task' action to add a task to a Box file, you must specify the ID of the file (Item ID field). You can map the ID value from an earlier action (for example, Retrieve file metadata) or by specifying a known file ID (for example, from the file address in the Box web browser interface

Troubleshooting tips

When added to a flow, some Box actions will immediately make an API call to Box to retrieve the set of existing objects that the action can be performed on or against. For example, the 'Create file' action makes an initial call to obtain the list of existing folders that you can create the file in. If you see a Not connected validation error when you add such actions, but do not see this error for other Box actions (which typically make a call only when the flow runs), this might be due to a broken connection between App Connect and Box.

Box / Create file action showing 'Not connected' message

To confirm the cause, you can also check the App Connect on IBM Cloud logs for errors; for a broken connection, you might see an error such as this:Request to failed with status 401

To re-establish a broken connection, you must re-authorize your Box account by updating the connection details for that account. For more information, see Managing accounts in App Connect.

Events and actions

Box events

These events are for changes in this application that trigger a flow to start performing the actions in the flow.

Note: Events are not available for changes in this application. You can trigger a flow in other ways, such as at a scheduled interval or at specific dates and times.

Box actions

These are actions on this application that you want a flow to complete.

Create bookmark
Retrieve bookmarks
Update bookmarks
Delete bookmarks
Create collaboration
Retrieve collaborations
Update collaborations
Delete collaborations
Create comment
Retrieve comments
Update comments
Delete comments
Create file
Retrieve file metadata
Update files
Delete files
Retrieve file content
Copy file
Folder items
Retrieve folder items
Create folder
Retrieve folders
Update folders
Delete folders
Copy folder
Group memberships
Update group memberships
Delete group memberships
Shared links
Retrieve shared links
Create or update shared link
Task assignments
Create task assignment
Retrieve task assignments
Update task assignments
Delete task assignments
Create task
Retrieve tasks
Update tasks
Delete tasks

More items are available when you have connected App Connect to Box.


Screenshot of the dashboard tile for a template that uses Box

Use templates to quickly create flows for Box

Learn how to use App Connect templates to quickly create flows that perform actions on Box; for example, open the Templates gallery, then search for Box.

Screenshot of the dashboard tile for a flow that connects Wufoo to Box

Creating an event-driven flow that copies a Wufoo attachment to Box

Learn how to use App Connect Designer to create an event-driven flow that copies a Wufoo file attachment in a submitted form and adds the file to Box.