box icon

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

Prerequisites

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

The Box connector is compatible with:

Application/Service Version

Anypoint Studio

5.4 or higher

Mule Runtime EE

3.8.x or higher

Java

1.7 or higher

Box API

2.0.0

Box Java SDK

2.1.1

Install the Connector

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

  1. Open Anypoint Studio and go to Help > Install New Software

  2. Select Anypoint Connectors Update Site - http://repository.mulesoft.org/connectors/releases/3.5.0

  3. Locate the Box connector.

  4. Click Next and accept the license agreement.

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

  1. Click the popup and check for available updates. 

  2. Click the Connector version checkbox and click Next and follow the instructions provided by the user interface. 

  3. Restart Studio when prompted. 

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

Box Configurations

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

  1. Go to the Global Element tab and click the Create button.

  2. Inside the filter textbox enter "Box" and select the option Box: OAuth 2.0 Server to Server.

  3. The following credentials are required:

    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.
Box OAuth 2.0 Config

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.

  1. Go to the Global Element tab and click the Create button.

  2. Inside the filter textbox enter "Box" and select the option Box: OAuth 2.0 Server to Server.

  3. The following credentials are required:

    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.

    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
Box OAuth 2.0 Server to Server Config

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

  1. Go to the Global Element tab and click the Create button.

  2. Inside the filter textbox enter "Box" and select the option Box: OAuth 2.0 Developer Token.

  3. The following credentials are required:

    Field

    Description

    Developer Token

    Enter the client_id of your application.
    Box OAuth 2.0 Developer Token Config

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

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.

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. 

  
1
2
3
4
5
6
7
8
9
10
11
12


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


  
1
2
3
4
5


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

Inside the <version> tags, put the desired version number, the word RELEASE for the latest release, or SNAPSHOT for the latest available version. The available versions to date are:

  • 3.0.0

  • 2.5.2

  • 2.4.1

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.

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

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 Folder Flow

  1. Create a new Mule Project in Anypoint Studio.

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

    
  
    1

    		
  
    box.developerToken=<DEVELOPER_TOKEN>

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

  4. 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"/>

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

  6. Back in the Properties editor, configure the remaining parameters:

    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]

    Create Folder UI Settings

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

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

    
  
    1
2
3
4
5
6
7

    		
  
    %dw 1.0
%output application/java
---
{
        name: inboundProperties['http.query.params'].name,
        parentId: inboundProperties['http.query.params'].id
}

  9. Add an Object to XML transformer after the Box connector element to display the response in the browser.

  10. Add a Logger scope after the transformer to display results in the Studio Console. Set its value to #[payload].

  11. Save the changes and deploy the project as a Mule Application.

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

    
  
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

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


  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


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