Nav

Box Connector

Select

Box is an online file sharing and content management service for businesses. The Anypoint Connector for Box is a RAML based connector that provides synchronization of data and automation of processes between Box and third party CRM, CMS, mobile, and social applications.

Prerequisites

This document assumes that you are familiar with Box 2.0 API, Mule, Anypoint Connectors, Anypoint Studio, Mule concepts, elements in a Mule flow, and Global Elements.

To use this connector you need the following:

  • A developer account or other valid Box instance.

  • MuleSoft Enterprise License.

For hardware and software requirements and compatibility information, see the Connector Release Notes.

What’s New in this Connector

This version of the connector drops support for Mule 3.x and adds support for Mule 4.x.

This is a RAML based connector and only uses REST calls to interact with Box 2.0 API and only supports a subset of services available in it.

Supported Operations

The given below is a list of supported operations grouped under a category that the Box connector supports.

Category Supported Operations

Collaborations

  • Create Collaboration

  • Delete Collaboration

  • Get Collaboration

  • Get Pending Collaborations

  • Update collaboration

Comments

  • Create Comment

  • Delete Comment

  • Get Comment

  • Update Comment

Files A

* Copy File * Delete File * Get File * Get File Comments * Get File Content * Get File Tasks * Get File Thumbnail * Update File Info

File Versions A

* Delete File Version * Get File Versions * Promote File Version

Folders A

* Copy Folder * Create Folder * Delete Folder * Get Folder * Get Folder Collaborations * Get Folder Items * Update Folder

Groups A

* Create Group * Create Group Membership * Delete Group * Delete Group Membership * Get Enterprise Groups * Get Group * Get Group Membership * Get Group Memberships * Get User Group Membership * Update Group Membership

Search

  • Search

Tasks

  • Create Task

  • Create Task Assignment

  • Delete Task

  • Delete Task Assignment

  • Get Task

  • Get Task Assignment

  • Get Task Assignments

  • Update Task

  • Update Task Assignment

Trash A

* Delete Trashed File * Delete Trashed Folder * Get Trashed File * Get Trashed Folder * Get Trashed Items * Restore Trashed File * Restore Trashed Folder

Users

  • Create User

  • Delete User

  • Get Enterprise Users

  • Get User

  • Update User

  • Update User Folder

To Connect in Design Center

  1. In Design Center, click a trigger such as HTTP Listener or Scheduler.

  2. Click the Plus symbol which is right after Reusable Configurations link. And to use Box connector global element, select mule-box-connector from the Reusable Configurations.

    Configuration selector

  3. Click Create Configuration in the above screen.

    The following configuration screen for OAUTH 2.0 with Authorization Code grant type appears. This is the only configuration that Box connector supports. The configuration screen is split into three screens to show all the properties in the configuration. The properties are described following the screens.

    Basic Config 1

    Basic Config 2

    Basic Config 3

    • Configuration Name: The configuration name for the Box connector global element.

    • Host: The host where Box exposes its API.

    • Port: The port at which Box services listen for incoming requests.

    • Base Path: The base path of the Box services' base URI.

    • Protocol: The protocol which Box services follow.

    • Client Id: The client identifier as assigned by the authorization server when the client application was registered.

    • Client Secret: The client application’s client secret.

    • Local Callback Path: The local callback path.

    • Local Callback Config: The HTTP Listener configuration that is used to configure the local authorization URL.

    • External Callback Url: The redirect URL that is configured in the client application.

    • Local Authorization Url: Local authorization URL that is used to initiate an OAuth2 dance.

    • Authorization Url: The authorization URL to request for an authorization code.

    • Access Token Url: The access token URL to request for an access token.

  4. Select the plus sign in the flow to add a component.

  5. Select mule-box-connector from the list of components to get the Box connector.

    Connector select

  6. Pick an operation. For example, Get Folder.

  7. Select the box-connector-config configuration that had been created previously. And configure the fields:

    Get folder operation configuration

    • Fields: The specific comma-separated list of fields to include in the response. It is optional.

    • Folder Id: The ID of the folder for which the information is retrieved. It is required.

To Connect in Anypoint Studio 7

You can use this connector in Anypoint Studio by first downloading it from Exchange and configuring it as needed.

To Install Connector in Studio

  1. In Anypoint Studio, click the Exchange icon in the Studio taskbar.

  2. Click Login in Anypoint Exchange.

  3. Search for the Box connector and click Install.

  4. Follow the prompts to install the connector.

When Studio has an update, a message displays in the lower right corner which you can click to install the update.

To Configure in Studio

  1. Open your Mule project in Anypoint Studio.

  2. Add the connector as a dependency in the pom.xml file:

    
                 
              
    1
    2
    3
    4
    5
    6
    
    <dependency>
        <groupId>com.mulesoft.connectors</groupId>
        <artifactId>mule-box-connector</artifactId>
        <version>4.0.0</version>
        <classifier>mule-plugin</classifier>
    </dependency>

To Configure the Box Connector Global Element

To use the Box connector in a Mule application, configure a global Box configuration element that can be used by as many Box connectors as you require for your application.

  1. Click the Global Elements tab at the base of the canvas.

  2. In the Global Configuration Elements screen, click Create.

    Global Element Configuration Wizard

  3. In the Choose Global Type wizard, expand Connector Configuration and select Mule-box-connector Config and click Ok. The configuration screen for OAUTH 2.0 with Authorization Code grant type appears. This is the only configuration that Box connector supports.

    Global Element Properties

  4. Configure the properties as per the image above. Given below has the description for the properties.

    Parameter Description

    clientId

    The client identifier as assigned by the authorization server when the client application was registered

    clientSecret

    The client application’s client secret

    host

    The host where Box exposes its API

    port

    The port at which Box services listen for incoming requests. Default: 443

    basePath

    The base path of the Box services' base URI

    protocol

    The protocol which Box services follow. Default: HTTPS

    localCallbackPath

    The local callback path. Default: /callback

    localCallbackConfig

    The HTTP Listener configuration that is used to configure the local authorization URL

    externalCallbackUrl

    The redirect URL that is configured in the client application

    localAuthorizationUrl

    Local authorization URL that is used to initiate an OAuth2 dance

    authorizationUrl

    The authorization URL to request for an authorization code

    accessTokenUrl

    The access token URL to request for an access token

    In the OAUTH 2.0 configuration screen above, the placeholder values refer to a configuration file mule-artifact.properties placed in the src/main/resources folder of your project.

    You can either enter your credentials into the global configuration properties, or reference a configuration file that contains these values. For simpler maintenance and better re-usability of your project, Mule recommends that you use a configuration file. Keeping these values in a separate file is useful if you need to deploy to different environments, such as production, development, and QA, where your access credentials differ.

  5. Click OK to save the global connector configurations.

Use Case: Create Folder, Retrieve Folder, and Delete Folder

Use case to demonstrate Create Folder, Retrieve Folder, and Delete Folder operations.

Create Retrieve Delete Folder Flow

  1. Create a new Mule Project in Anypoint Studio.

  2. Add the below properties to the mule-artifact.properties file to hold your Box credentials and place it in the project’s src/main/resources directory.

    
                
             
    1
    2
    
    config.clientId=<Client ID>
    config.clientSecret=<Client Secret>
  3. Configure the HTTP Listener by adding a new HTTP Global Element. Click the plus sign next to the Connector configuration field.

  4. Configure the global element according to the table below:

    Parameter Value

    Name

    HTTP_Listener_config

    Protocol

    HTTP

    Host

    localhost

    Port

    8081

  5. Drag an HTTP Listener onto the canvas and configure the following parameters:

    Parameter Value

    Display Name

    HTTP Listener

    Connector configuration

    Select the HTTP Listener Configuration that had been created previously

    Path

    /boxdemo

  6. Now set the folder properties for the folder we are going to create using a DataWeave component. Drag the DataWeave component next to the HTTP Listener and use the script below.

    
                
             
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    
    %dw 2.0
    output application/json
    ---
    {
            parent: {
                    id: 0
            },
            "type": "folder",
            name: "SampleFolder"
    }
  7. Drag Create folder operation of the Box connector next to the DataWeave component to create a folder.

  8. Configure the Box connector by adding a new Box Global Element. Click the plus sign next to the Connector configuration field.

  9. Configure the global element according to the table below:

    Parameter Value Comments

    clientId

    ${config.clientId}

    The client identifier as assigned by the authorization server when the client application was registered

    clientSecret

    ${config.clientSecret}

    The client application’s client secret

    host

    api.box.com

    This is the default value. Leave as is.

    port

    443

    This is the default value. Leave as is.

    basePath

    /2.0

    This is the default value. Leave as is.

    protocol

    HTTPS

    This is the default value. Leave as is.

    localCallbackPath

    /callback

    This is the default value. Leave as is.

    localCallbackConfig

    HTTP_Listener_config

    Select the HTTP Listener configuration created earlier

    externalCallbackUrl

    http://localhost:8081/callback

    Give the redirect URL that is configured in the client application

    localAuthorizationUrl

    http://localhost:8081/authorize

    This URL needs to be hit after deploying the mule application to initiate OAUTH2 dance

    authorizationUrl

    https://account.box.com/api/oauth2/authorize

    The authorization URL to request for an authorization code

    accessTokenUrl

    https://api.box.com/oauth2/token

    The access token URL to request for an access token

    The corresponding XML configuration should be as follows:

    
                
             
    1
    2
    3
    4
    5
    6
    
    <mule-box-connector:config name="Mule_box_connector_Config"
     doc:name="Mule-box-connector Config"
     property_clientId="#{config.clientId}"
     property_clientSecret="#{config.clientSecret}"
     property_localCallbackConfig="HTTP_Listener_config"
     property_externalCallbackUrl="http://localhost:8081/callback" />
  10. Back in the properties editor of the Box connector, configure the parameters required for the Create folder operation:

    Parameter Value

    Display Name

    Create folder

    Basic Settings

    Connector configuration

    Select the global Box connector element that you had created.

    General

    Create folder request data

    #[payload]

  11. Drag a Logger component to log the newly created folder ID and configure the following properties.

    Parameter Value

    Display Name

    Logger to log the created Folder ID

    Generic

    Message

    Folder created with ID : #[payload.id]

  12. Drag Get folder operation of the Box connector next to the Logger component to retrieve the folder information and configure the following properties.

    Parameter Value

    Display Name

    Get folder

    Basic Settings

    Connector configuration

    Select the global Box connector element that you had created.

    General

    Folder id

    #[payload.id]

  13. Drag a Logger component to log the retrieved folder information and configure the following properties

    Parameter Value

    Display Name

    Logger to log the retrieved folder info

    Generic

    Message

    #[payload]

  14. Drag Delete folder operation of the Box connector to delete the folder that is just created and configure the following properties.

    Parameter Value

    Display Name

    Delete folder

    Basic Settings

    Connector configuration

    Select the global Box connector element that you had created.

    General

    Folder id

    #[payload.id]

  15. Finally drag the DataWeave component to set the payload to display the result of the flow to the user and use the script below.

    
                
             
    1
    2
    3
    4
    5
    6
    
    %dw 2.0
    output application/json
    ---
    {
            result : "Folder got created, retrieved and deleted successfully"
    }
  16. Save and run the project as a Mule Application.

  17. Hit the URL http://localhost:8081/authorize from a browser which you had given for localAuthorizationUrl in global Box configuration element to initiate OAUTH2 dance.

    This would display the following page asking the Box user to either grant or deny access to the client application to read and write all files and folders stored in Box.

    Box OAuth 2 Dance

  18. Click Grant access to Box to grant the read and write permissions.

  19. Open a web browser and access the URL http://localhost:8081/boxdemo.

    You should get a JSON response with the following content.

    Result: "Folder created, retrieved, and deleted successfully"

Use Case: XML


         
      
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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core"
        xmlns:mule-box-connector="http://www.mulesoft.org/schema/mule/mule-box-connector"
        xmlns:http="http://www.mulesoft.org/schema/mule/http"
  xmlns="http://www.mulesoft.org/schema/mule/core"
        xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        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/http
http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/mule-box-connector
http://www.mulesoft.org/schema/mule/mule-box-connector/current/mule-mule-box-connector.xsd
http://www.mulesoft.org/schema/mule/ee/core
http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd">

        <http:listener-config name="HTTP_Listener_config"
                doc:name="HTTP Listener config">
                <http:listener-connection host="localhost"
                        port="8081" />
        </http:listener-config>

        <mule-box-connector:config name="Mule_box_connector_Config"
                doc:name="Mule-box-connector Config" property_clientId="#{config.clientId}"
                property_clientSecret="#{config.clientSecret}"
                property_localCallbackConfig="HTTP_Listener_config"
                property_externalCallbackUrl="http://localhost:8081/callback" />
        <flow name="Create-Get-Delete-Folder-Flow">
                <http:listener doc:name="HTTP Listener" path="/boxdemo"
                        config-ref="HTTP_Listener_config" />
                <ee:transform doc:name="DataWeave to set folder properties">
                        <ee:message>
                                <ee:set-payload><![CDATA[%dw 2.0
output application/json
---
{
        parent: {
                id: 0
        },
        "type": "folder",
        name: "SampleFolder"
}]]></ee:set-payload>
                        </ee:message>
                </ee:transform>
                <mule-box-connector:create-folder
                        doc:name="Create folder" config-ref="Mule_box_connector_Config" />

                <logger level="INFO" doc:name="Logger to log the created Folder ID"
                        message="Folder created with ID : #[payload.id]" />
                <mule-box-connector:get-folder doc:name="Get folder"
                        config-ref="Mule_box_connector_Config" folder-id="#[payload.id]" />
                <logger level="INFO" doc:name="Logger to log the retrieved folder info"
                        message="#[payload]" />
                <mule-box-connector:delete-folder
                        doc:name="Delete folder" config-ref="Mule_box_connector_Config"
                        folder-id="#[payload.id]" />
                <ee:transform doc:name="DataWeave to show the result">
                        <ee:message>
                                <ee:set-payload><![CDATA[%dw 2.0
output application/json
---
{
        result : "Folder got created, retrieved and deleted successfully"
}]]></ee:set-payload>
                        </ee:message>
                </ee:transform>
        </flow>
</mule>

See Also