Box Connector

Introduction

The Anypoint Connector for Box is a closed-source, SDK-based connector that provides synchronization of data and automation of processes between Box and third party CRM, CMS, mobile and social applications.

Release Notes: Box Connector Release Notes
Exchange: Box Connector
Technical Reference: Mule Box Connector

Before You Begin

This document assumes that you are familiar with Mule, Anypoint Connectors, and Anypoint Studio Essentials. To increase your familiarity with Studio, consider completing the Basic Studio Tutorial. Further, this page assumes that you have a basic understanding of Mule Flows and Global Elements.

To use the Box connector, you must have the following:

Anypoint Studio: if you don’t use Anypoint Studio for development, follow the instructions about specifying Maven dependencies in your pom.xml file.
A Developer account or other valid Box instance. You can obtain one from the Box Developer Platform.

Hardware and Software Requirements

For hardware and software requirements, please visit the Hardware and Software Requirements page.

Compatibility

See the Box connector release notes for Mule compatibility information.

Install the Connector

To install the Box connector in Anypoint Studio, follow the steps below:

Open Anypoint Studio and go to Help > Install New Software
- Select Anypoint Connectors Update Site or http://repository.mulesoft.org/connectors/releases/3.5.0.
Locate the Box connector.
Click Next and accept the license agreement.
Restart Studio when prompted.

For more information on how to install a connector click here.

After installing the connector, your studio palette should contain the following. It would be useful at this point to filter your palette to show only message processors relating to the Box connector.

Upgrade from an Older Version

If you’re currently using an older version of the connector, a small popup appears in the bottom right corner of Anypoint Studio with an "Updates Available" message.

Click the popup and check for available updates.
Click the Connector version checkbox and click Next and follow the instructions provided by the user interface.
Restart Studio when prompted.
After restarting, when creating a flow using the Box connector, if you have several versions of the connector installed, you may be asked which version you would like to use. Choose the version you would like to use.

Additionally, we recommend that you keep Studio up to date with its latest version.

Configure the Connector Global Element

To use the Box connector in your Mule application, you must configure a global Box element that can be used by the Box connector (read more about Global Elements).

The Box connector offers the following global configuration options:

These represent the three different authentication methods to access the Box API, depending on the type of application the user is building. From Box documentation:

	Build a Box Integration	Build on Box Platform
Description	Integrate Box Partner application or power backend processes using our APIs	Securely access and store content in your custom application using Box Platform
Authentication Mechanism	OAuth 2.0 (3-legged)	OAuth 2.0 with JSON Web Tokens
Users	Managed Users	Application Users

Build a Box Integration

Build on Box Platform

Description

Integrate Box Partner application or power backend processes using our APIs

Securely access and store content in your custom application using Box Platform

Authentication Mechanism

OAuth 2.0 (3-legged)

OAuth 2.0 with JSON Web Tokens

Users

Managed Users

Application Users

For more information, refer to Box’s Authentication Types and Security.

OAuth 2.0

In order to use this configuration, you first have to set up your Box Application:

Create and configure a Box Application for your enterprise following the steps specified here. In this step, you should be provided with a client_id and a client_secret.

Go to the Global Element tab and click the Create button.
Inside the filter textbox enter "Box" and select the option Box: OAuth 2.0 Server to Server.

The following credentials are required:

Field Description

Field	Description
Client Id	Enter the `client_id` of the Box connected app.
Client Secret	Enter the `client_secret` for the connector to access Box.
Domain	Enter the host of the callback’s URL as specified in the `redirect_uri` in Box OAuth2 configuration.
Local Port	Enter the port of the callback’s URL.
Path	Enter the relative path of the callback’s URL.

Client Id

Enter the client_id of the Box connected app.

Client Secret

Enter the client_secret for the connector to access Box.

Domain

Enter the host of the callback’s URL as specified in the redirect_uri in Box OAuth2 configuration.

Local Port

Enter the port of the callback’s URL.

Path

Enter the relative path of the callback’s URL.

OAuth 2.0 Server to Server

In order to use this configuration, you first have to set up your Box Application:

Create, configure and authorize a Box Application for your enterprise following the steps specified here. You should be provided with a client_id and a client_secret.
Generate a RSA keypair and submit the public key as explained here. You will get a KeyId, it will be required on the connector configuration.

Go to the Global Element tab and click the Create button.
Inside the filter textbox enter "Box" and select the option Box: OAuth 2.0 Server to Server.

The following credentials are required:

Field Description

Field	Description
Client Id	Enter the `client_id` of your application.
Client Secret	Enter the `client_secret` of your application.
Enterprise Id or User Id	Enter the enterprise or the user on behalf of the operations will be done.
Private Key Password	Enter if the private key of the RSA keypair is encrypted this field has to contain the key password, otherwise can be left blank.
Private Key Path	Enter the relative path of the privateKey in the project. This file needs to be in PEM format.
Connection Type	Enter the type of connection which defines the type of token used: AS_ENTERPRISE_MANAGER AS_USER. For more information about tokens and token’s constraints check this link.
Encryption Algorithm	Enter the algorithm used to verify the JWT signature. Values can only be set to: RSA_SHA_256 RSA_SHA_384 RSA_SHA_512

Client Id

Enter the client_id of your application.

Client Secret

Enter the client_secret of your application.

Enterprise Id or User Id

Enter the enterprise or the user on behalf of the operations will be done.

Private Key Password

Enter if the private key of the RSA keypair is encrypted this field has to contain the key password, otherwise can be left blank.

Private Key Path

Enter the relative path of the privateKey in the project. This file needs to be in PEM format.

Connection Type

Enter the type of connection which defines the type of token used:

AS_ENTERPRISE_MANAGER
AS_USER.

For more information about tokens and token’s constraints check this link.

Encryption Algorithm

Enter the algorithm used to verify the JWT signature. Values can only be set to:

RSA_SHA_256
RSA_SHA_384
RSA_SHA_512

EnterpriseId can be retrieved from: Box Admin console → Enterprise Settings → Account Info.
UserId can be generated with an Enterprise connection. The creation operation will return the created user’s info which includes the userId. If the ID of an existent user is required, the complete list of managed users of the enterprise can be retrieved and then filtered to get the userId.

OAuth 2.0 Developer Token

In order to use this configuration, you must first obtain a valid Developer Token from your Box Application.

Go to the Global Element tab and click the Create button.
Inside the filter textbox enter "Box" and select the option Box: OAuth 2.0 Developer Token.
The following credentials are required:

Field Description

Developer Token

Enter the client_id of your application.

Field	Description
Developer Token	Enter the `client_id` of your application.

Connection Types

The Connection Type determines the set of operations that can be performed with the connector:

Enterprise Connection	User Connection
Users Groups	Folders Files Comments Collaborations Searches Tasks

Enterprise Connection

User Connection

Users
Groups

Folders
Files
Comments
Collaborations
Searches
Tasks

Using the Connector

Connector Namespace and Schema

When designing your application in Studio, the act of dragging the connector from the palette onto the Anypoint Studio canvas should automatically populate the XML code with the connector namespace and schema location.

Namespace: http://www.mulesoft.org/schema/mule/box
Schema Location: http://www.mulesoft.org/schema/mule/box/current/mule-box.xsd

If you are manually coding the Mule application in Studio’s XML editor or other text editor, define the namespace and schema location in the header of your Configuration XML, inside the <mule> tag.

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:connector="http://www.mulesoft.org/schema/mule/connector"
      xsi:schemaLocation="
               http://www.mulesoft.org/schema/mule/core
               http://www.mulesoft.org/schema/mule/core/current/mule.xsd
               http://www.mulesoft.org/schema/mule/box
               http://www.mulesoft.org/schema/mule/box/current/mule-box.xsd">

      <!-- put your global configuration elements and flows here -->

</mule>

Using the Connector in a Mavenized Mule App

If you are coding a Mavenized Mule application, this XML snippet must be included in your pom.xml file.

<dependency>
    <groupId>org.mule.modules</groupId>
    <artifactId>mule-module-box</artifactId>
    <version>x.x.x</version>
</dependency>

Replace x.x.x with the version that corresponds to the connector you are using.

To obtain the most up-to-date pom.xml file information, access the connector in Anypoint Exchange and click Dependency Snippets.

Supported API Endpoints

The following list specifies the complete list of endpoint supported by the Box connector:

Endpoint	Covered operations
Users	Create User Get Current User Get User’s Info Get Enterprise Users Update User Delete User Move User’s Folder Get Email Aliases Add Email Alias Delete Email Alias
Groups	Create Group Get Group Delete Group Create Membership Delete Membership Update Memberships for Group Get Groups for an Enterprise Get Memberships for User
Folders	Get Folder’s Info Get Folder’s Items Create Folder Update Folder Delete Folder Copy Folder Create Shared Link Get Folder Collaborations Get Trashed Items Get Trashed Folder Permanently Delete Restore Folder
Files	Get File’s Info Update File’s Info Upload File Download File Update File Delete File View Version Promote Version Download Version Delete Old Version Copy File Get Thumbnail Get Embed Link Create Shared Link Get Trashed File Permanently Delete Restore Item View Comments Get File’s Tasks
Comments	Create Comment Get Comment Update Comment Delete Comment Reply to Comment
Tasks	Create Task Get Task Update Task Delete Task Get Assignments
Collaborations	Create Collaboration Get Collaboration Update Collaboration Delete Collaboration Get Pending Collaborations
Search	Search items by parent FolderId. NOTE: The search functionality is limited by the Box Java SDK 2.1.1 itself.

Endpoint

Covered operations

Users

Create User
Get Current User
Get User’s Info
Get Enterprise Users
Update User
Delete User
Move User’s Folder
Get Email Aliases
Add Email Alias
Delete Email Alias

Groups

Create Group
Get Group
Delete Group
Create Membership
Delete Membership
Update Memberships for Group
Get Groups for an Enterprise
Get Memberships for User

Folders

Get Folder’s Info
Get Folder’s Items
Create Folder
Update Folder
Delete Folder
Copy Folder
Create Shared Link
Get Folder Collaborations
Get Trashed Items
Get Trashed Folder
Permanently Delete
Restore Folder

Files

Get File’s Info
Update File’s Info
Upload File
Download File
Update File
Delete File
View Version
Promote Version
Download Version
Delete Old Version
Copy File
Get Thumbnail
Get Embed Link
Create Shared Link
Get Trashed File
Permanently Delete
Restore Item
View Comments
Get File’s Tasks

Comments

Create Comment
Get Comment
Update Comment
Delete Comment
Reply to Comment

Tasks

Create Task
Get Task
Update Task
Delete Task
Get Assignments

Collaborations

Create Collaboration
Get Collaboration
Update Collaboration
Delete Collaboration
Get Pending Collaborations

Search items by parent FolderId.
NOTE: The search functionality is limited by the Box Java SDK 2.1.1 itself.

Unsupported API Endpoints

Currently, version 3.0.0 of the Box connector does NOT support the following endpoints:

Endpoint	Unsupported operations
Metadata	All
Collections	All
Events	All
Devices	All
Retention Policies	All
Users	Change User’s Login Invite User
Files	Lock and Unlock Preflight check
Groups	Get Memberships for User Get Collaborations for Group

Endpoint

Unsupported operations

Metadata

All

Collections

All

Events

All

Devices

All

Retention Policies

All

Users

Files

Groups

Demo Mule Applications Using Connector

You can download fully functional demo applications using the Box connector from this link.

Example Use Case

This use case describes how to create a Mule application to add a new Folder record in Box using Developer Token Authentication.

Create a new Mule Project in Anypoint Studio.
Set your Box credentials in src/main/resources/mule-app.properties. This step may vary depending on the selected configuration. To keep things simple, the current use case we will set up the connection using a Developer Token.
```
box.developerToken=<DEVELOPER_TOKEN>
```
Drag a HTTP endpoint onto the canvas and configure the following parameters:

Parameter Value

Display Name

HTTP (default value)

Connector Configuration

HTTP_Listener_Configuration (default value)
Drag a Box Connector component next to the HTTP endpoint and configure it according to the steps below:
1. Add a new Box Global Element by clicking the plus [+] sign next to the Connector Configuration field.
2. Configure the global element according to the table below:
  
  Parameter Value
  
  Developer Token
  
  Box__OAuth_2_0_Developer_Token
  <box:config-dev-token name="Box__OAuth_2_0_Developer_Token" developerToken="${box.developerToken}" doc:name="Box: OAuth 2.0 Developer Token"/>
Click Test Connection to confirm that Mule can connect with the Box instance. If the connection is successful, click OK to save the configuration. Otherwise, review or correct any invalid parameters and test again.

Parameter	Value
Display Name	`HTTP` (default value)
Connector Configuration	`HTTP_Listener_Configuration` (default value)

Parameter	Value
Developer Token	`Box__OAuth_2_0_Developer_Token`

Back in the Properties editor, configure the remaining parameters:

Parameter Value

Parameter	Value
Display Name	`Create Folder (or any other name you prefer).`
Connector Configuration	`Box__OAuth_2_0_Developer_Token (the reference name to the global element you have created).`
Operation	`Folders \| Create Folder`
Folder Name	`#[payload.name]`
Parent Id	`#[payload.parentFolderId]`

Display Name

Create Folder (or any other name you prefer).

Connector Configuration

Box__OAuth_2_0_Developer_Token (the reference name to the global element you have created).

Operation

Folders | Create Folder

Folder Name

#[payload.name]

Parent Id

#[payload.parentFolderId]

Check that your "Create Folder" operation looks as follows in the XML:

<box:create-folder config-ref="Box__OAuth_2_0_Developer_Token" folderName="#[payload.name]" parentId="#[payload.parentId]" doc:name="Create Folder"/>

Add a DataWeave element (Transform Message) between the HTTP endpoint and the Box Connector to set the input parameters expected by the Create operation. Inside the DataWeave code, you can use a MEL expression to define a HTTP Query Param for all the fields. This way, each value can be dynamically set from the URL.
```
%dw 1.0
%output application/java
---
{
	name: inboundProperties['http.query.params'].name,
	parentId: inboundProperties['http.query.params'].id
}
```
Add an Object to XML transformer after the Box connector element to display the response in the browser.
Add a Logger scope after the transformer to display results in the Studio Console. Set its value to #[payload].
Save the changes and deploy the project as a Mule Application.

Open a web browser and make a request to the following URL (change the parameter values as desired):

http://localhost:8081/create?name=Folder01&parentId=0

If the folder was successfully created, its metadata information should be displayed in an XML format:

<com.box.sdk.BoxFolder_-Info>
<children/>
    <outer-class class="com.box.sdk.BoxFolder" defined-in="com.box.sdk.BoxResource$Info">
    <api>
        ...
    </api>
    <id>9089197613</id>
    </outer-class>
    <sequenceID>0</sequenceID>
    <etag>0</etag>
    <name>Folder01</name>
    <createdAt>2016-07-28 20:41:18.0 UTC</createdAt>
    <modifiedAt>2016-07-28 20:41:18.0 UTC</modifiedAt>
    <description/>
    <size>0</size>
    <pathCollection>...</pathCollection>
    <createdBy>...</createdBy>
    <modifiedBy>...</modifiedBy>
    <contentCreatedAt>2016-07-28 20:41:18.0 UTC</contentCreatedAt>
    <contentModifiedAt>2016-07-28 20:41:18.0 UTC</contentModifiedAt>
    <ownedBy>...</ownedBy>
    <parent>...</parent>
    <itemStatus>active</itemStatus>
    ...
</com.box.sdk.BoxFolder_-Info>

Example Use Case - XML

Paste this code into your XML Editor to quickly load the flow for this example use case into your Mule application.

<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:mulexml="http://www.mulesoft.org/schema/mule/xml" xmlns:dw="http://www.mulesoft.org/schema/mule/ee/dw" xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking" xmlns:json="http://www.mulesoft.org/schema/mule/json" xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns:box="http://www.mulesoft.org/schema/mule/box" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
	xmlns:spring="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/box http://www.mulesoft.org/schema/mule/box/current/mule-box.xsd
http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/json http://www.mulesoft.org/schema/mule/json/current/mule-json.xsd
http://www.mulesoft.org/schema/mule/ee/dw http://www.mulesoft.org/schema/mule/ee/dw/current/dw.xsd
http://www.mulesoft.org/schema/mule/ee/tracking http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd
http://www.mulesoft.org/schema/mule/xml http://www.mulesoft.org/schema/mule/xml/current/mule-xml.xsd">
    <box:config-dev-token name="Box__OAuth_2_0_Developer_Token" developerToken="${box.developerToken}" doc:name="Box: OAuth 2.0 Developer Token"/>
    <http:listener-config name="HTTP_Listener_Configuration" host="0.0.0.0" port="8081" doc:name="HTTP Listener Configuration"/>
    <flow name="Create_Folder_Flow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/create" doc:name="HTTP" />
        <dw:transform-message doc:name="Extract query params">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
{
	name: inboundProperties['http.query.params'].name,
	parentId: inboundProperties['http.query.params'].parentId
}]]></dw:set-payload>
        </dw:transform-message>
        <box:create-folder config-ref="Box__OAuth_2_0_Developer_Token" folderName="#[payload.name]"  doc:name="Create Folder" parentId="#[payload.parentId]"/>
        <mulexml:object-to-xml-transformer doc:name="Object to XML"/>
        <logger message="#[payload]" level="INFO" doc:name="Folder"/>
    </flow>
</mule>

Resources

Learn more about working with Anypoint Connectors.
Access the Box Connector Release Notes.
For additional technical information on the Box Connector, visit our technical reference documentation.
To know more about the Box API, go to the Box API documentation page.