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, you don't need to send copies of files as email attachments, and everyone always has the latest file version on hand, making collaboration seamless. Use App Connect to connect more apps to Box. So, for example, whenever a new campaign is created in Salesforce, a folder is created in Box automatically, making your team more collaborative and saving time for other work.

Supported product and API versions

To find out which product and API versions this connector supports, see Detailed System Requirements on the IBM Support page.

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:

Authorization method Connection field Description Applicability
BASIC OAUTH Access token In the Box developer console, create a custom application by using the Standard OAuth 2.0 (User Authentication) method to generate a client ID and client secret. An access token is generated from the client ID, client secret, and redirect URI. For more information, see http://ibm.biz/acboxoauth2nosdk. App Connect in containers and App Connect Enterprise as a Service
Refresh token The refresh token that is generated from the application client ID and client secret. For more information, see http://ibm.biz/acboxoauth2nosdk.
Client ID The unique identifier that is generated after you create an application in the Box developer console. You can find this value on the Configuration page of your application.
Client secret The application client secret that is generated after you create an application in the Box developer console. You can find this value on the Configuration page of your application.
OAUTH 2.0 AUTH CODE
Tip: Authorize connection to Box by signing in to your account.
   App Connect Enterprise as a Service

To connect to Box from the App Connect Designer Connect > Applications and APIs page (previously the 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. These steps create an account in App Connect. For more information, see Managing accounts.

To obtain the connection values for Box, see Obtaining connection values for Box.

Tip:
  • If you're already logged in to Box in the same browser window as App Connect Enterprise as a Service, 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 of 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 Applications and APIs page, select the account, open its options menu (⋮), then click Rename Account.

What to 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 Applications and APIs page of the App Connect Designer.

    For some applications, the events and actions depend on the environment 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.

Post connection considerations

  • When you use the Create file action to add a file to Box, the following points apply.
    • Specify a parent folder for the file that you want to create. This folder must 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: To specify a dynamic value (that a previous event or action returns) for a folder instead of a static value from the populated list, switch to advanced mode. The 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.
    • Use the Type of file field to indicate whether the file content must be treated as plain text (Text), or whether Base64 encoding (Binary) must be applied for file formats such as PDF and Microsoft Word.
  • When you use the Create folder action to create a Box folder, the folder is created at the root level by default. When a folder is created at the root level, 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 that is being created, overwrite the default ID of 0 with a hardcoded value or a mapped value. The parent folder must 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 https://app.box.com/folder/31234567893, 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 you retrieve or transfer the contents of a file, if the file content needs to be parsed or transformed by using JSONata functions, the maximum file size is 10 MB. 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 you map to content, specify only a single mapped value, and do not append or add a prefix of 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. 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 https://app.box.com/file/File_ID).
  • When you use a Retrieve action containing Fields parameter (for example, the Retrieve trashed file action), the response schema includes many properties that are not returned by default from the Box API. Even though these properties appear in the mapping editor, their values are not populated unless you explicitly request them.

    Retrieve trashed file action in Box

    To retrieve values for these properties, you must specify their names in the Fields parameter as a comma-separated list. If you do not include the property names in the Fields parameter, the response will not contain values for those properties, even if you map them. For example, if you want to retrieve name, file_version, and description, enter name,file_version,description in the Fields input. The response will then include values for these properties.

Troubleshooting tips

When added to a flow, some Box actions immediately make an API call to Box to retrieve the set of existing objects that the action can be completed 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 don't see this error for other Box actions (which typically make a call only when the flow runs), the connection between App Connect and Box might be broken.

Box / Create file action showing 'Not connected' message

To reestablish a broken connection, you must reauthorize your Box account by updating the connection details for that account.

Events and actions

Box events

These events are for changes in this application that trigger a flow to start completing 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

Your flow completes these actions on this application.

Object Action Description
Bookmarks Create bookmark Creates a bookmark in Box
Delete bookmarks Deletes a web link from a Box account
Retrieve bookmarks Gets information about a web link
Update bookmarks Updates a web link
Collaborations Create collaboration Creates a collaboration in Box
Delete collaborations Deletes a collaboration from Box account
Retrieve collaborations Gets information about collaborations
Update collaborations Updates a collaboration
Comments Create comment Creates a comment in Box
Delete comments Deletes a comment from a Box account
Retrieve comments Gets information about comments
Update comments Updates a comment
Files Copy file Creates a copy of a file in another folder. The original version of the file will not be altered.
Create file Creates a file in a specified folder in your Box account
Delete files Deletes a file from your Box account
Retrieve file content Downloads a file from your Box account
Retrieve file metadata Gets information about files in your Box account
Update files Updates the contents for a specific file
Retrieve file versions Retrieves a list of the past versions for a file
Retrieve trashed file Retrieves a file that has been moved to the trash
Folder items Retrieve folder items Gets all folder items
Folders Copy folder Creates copy of a folder in another folder
Create folder Adds a new folder in Box
Delete folders Deletes a folder from a Box account
Retrieve folders Gets information about folders
Update folders Updates the settings for a specific folder
Group memberships Create group membership Creates a group membership on a group
Delete group memberships Deletes a group membership from a group of Box account
Retrieve group memberships Gets information about group memberships
Update group memberships Updates a group membership
Shared links Create or update shared link Creates or updates a shared link
Retrieve shared links Gets information about shared links
Task assignments Create task assignment Creates a task assignment for a task in Box
Delete task assignments Deletes a Task Assignment for a task in Box account
Retrieve task assignments Retrieves task assignments for a task in Box
Update task assignments Updates a Task Assignment for a task in Box account
Tasks Create task Creates a task on a file
Delete tasks Deletes a task from a Box account
Retrieve tasks Gets information about tasks
Update tasks Updates a task

More items are available after you connect App Connect to Box.

Examples

Dashboard tile for a template that uses Box
Dashboard tile for a template that uses Box
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 complete actions on Box. For example, open Discover, and then search for Box.

Learn more

Dashboard tile for a template that uses Box