How to use IBM App Connect with Box

Connecting to Box

• 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.

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.
    
    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.

    
  • 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.
  

  In the Box UI, you can find this ID in your 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 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.
    
• 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

• 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 https://app.box.com/file/File_ID).

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.

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 https://firefly-actions-catalog-prod.appconnect.ibmcloud.com/api/connectors/configuration/box/CREATE/File/actions?apiConnectionID=a48a4c00-c5b0-11e9-a71f-c7543a2c72ec 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.

Box actions

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

Bookmarks

Create bookmark

Retrieve bookmarks

Update bookmarks

Delete bookmarks

Collaborations

Create collaboration

Retrieve collaborations

Update collaborations

Delete collaborations

Comments

Create comment

Retrieve comments

Update comments

Delete comments

Files

Create file

Retrieve file metadata

Update files

Delete files

Retrieve file content

Copy file

Folder items

Retrieve folder items

Folders

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

Tasks

Create task

Retrieve tasks

Update tasks

Delete tasks

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