org.mule.modules

mule-module-box

config

Namespacehttp://www.mulesoft.org/schema/mule/box
Schema Locationhttp://www.mulesoft.org/schema/mule/box/current/mule-box.xsd  (View Schema)
Schema Version2.0
Minimum Mule Version3.5

Module Overview

Box Cloud Connector for API V2.

Summary

Configuration
<box:config>
Configure an instance of this module
Message Sources
<box:listen-events>
Message source that subscribes to the events long polling server and will trigger a new message each time an event is generated.
Message Processors
<box:change-primary-login>
Used to convert one of the user’s confirmed email aliases into the user’s primary login.
<box:comment-discussion>
Used to add a comment to a discussion.
<box:comment-file>
Used to add a comment by the user to a specific file
<box:copy-file>
Used to create a copy of a file in another folder.
<box:copy-folder>
Used to create a shared link for this particular folder
<box:create-collaboration>
Used to add a collaboration for a single user to a folder.
<box:create-discussion>
Used to create the metadata for a new discussion for a particular folder.
<box:create-email-alias>
Adds a new email alias to the given user’s account.
<box:create-folder>
Creates a new folder and returns a folder object with all its associated information
<box:create-user>
Used to provision a new user in an enterprise.
<box:delete-collaboration>
Used to delete a single collaboration.
<box:delete-comment>
Delets a comment.
<box:delete-email-alias>
Removes an email alias from a user.
<box:delete-file>
Discards a file to the trash.
<box:delete-folder>
Deletes a folder
<box:delete-user>
Deletes a user in an enterprise account.
<box:download>
Downloads a file
<box:get-collaboration>
Used to get information about a single collaboration.
<box:get-comment>
Used to retrieve the message and metadata about a specific comment.
<box:get-discussion>
Used to retrieve the metadata about a specific discussion.
<box:get-discussion-comments>
Used to retrieve all comments for a given discussion.
<box:get-email-aliases>
Retrieves all email aliases for this user.
<box:get-enterprise-events>
Retrieves events for all users in an enterprise.
<box:get-events>
Use this to get events for a given user.
<box:get-events-long-polling-server>
Requests access to a long polling server that notifies about events in real time.
<box:get-file-comments>
Retrieves the comments on a particular file, if any exist.
<box:get-file-metadata>
Used to retrieve the metadata about a file.
<box:get-file-thumbnail>
Retrieves a thumbnail, or smaller image representation, of this file.
<box:get-folder>
Retrieves information about a given folder.
<box:get-folder-by-path>
Returns the folder information for a given path
<box:get-folder-discussions>
Retrieves the discussions on a particular folder, if any exist.
<box:get-folder-item>
Traverses a given folder looking for a resource (file or folder) of a given name.
<box:get-folder-items>
Retrieves the files and/or folders contained within this folder without any other metadata about the folder in the mini format is returned for each item by default.
<box:get-item-by-path>
Returns the item information for a given path.
<box:get-pending-collaborations>
Used to retrieve all pending collaboration invites for this user.
<box:get-trashed-file>
Retrieves the metadata of a trashed file
<box:get-trashed-folder>
Retrieves a folder that has been moved to the trash.
<box:get-trashed-items>
Get the folders in the Trash.
<box:get-user>
Retrieves information about the user who is currently logged in i.e.
<box:get-users>
Returns a list of all users for the Enterprise
<box:get-versions-metadata>
If there are previous versions of this file, this method can be used to retrieve metadata about the older versions.
<box:move-folder-to-user>
Moves all of the content from within one user’s folder into a new folder in another user’s account.
<box:perm-delete-file>
Permanently deletes an item that is in the trash.
<box:perm-delete-folder>
Permanently deletes an item that is in the trash.
<box:restore-trashed-file>
Restores a file that has been moved to the trash.
<box:restore-trashed-folder>
Restores an item that has been moved to the trash.
<box:search>
The search endpoint provides a simple way of finding items that are accessible in a given user’s Box account.
<box:share-file>
Used to create a shared link for this particular file.
<box:share-folder>
Used to create a shared link for this particular folder
<box:unshare-file>
Deletes the shared link associated to a file
<box:unshare-folder>
Deletes the shared link associated to a folder
<box:update-collaboration>
Used to update an existing collaboration.
<box:update-comment>
Used to update the message of the comment.
<box:update-discussion>
Used to update the metadata for an existing discussion.
<box:update-file>
Update a file’s information.
<box:update-folder>
Used to update information about the folder.
<box:update-user>
Used to edit the settings and information about a user.
<box:upload-new-version-path>
Uploads a new version of a file by reading the contents from a path in local storage
<box:upload-new-version-stream>
Uploads a new version of a file from an input stream
<box:upload-path>
Receives the path of a file in local storage and uploads its content
<box:upload-stream>
Creates a new file with the contents of a java.io.InputStream.

Configuration

To use the this module within a flow the namespace to the module must be included. The resulting flow will look similar to the following:

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

      <!-- here goes your flows and configuration elements -->

</mule>

This module is configured using the config element. This element must be placed outside of your flows and at the root of your Mule application. You can create as many configurations as you deem necessary as long as each carries its own name.

Each message processor, message source or transformer carries a config-ref attribute that allows the invoker to specify which configuration to use.

Attributes
TypeNameDefault ValueDescriptionJava TypeMIME TypeEncoding
xs:string name Optional. Give a name to this configuration so it can be later referenced.
xs:string baseUrl https://api.box.com/2.0/ Optional. The api's base url
xs:string clientId The OAuth2 client id
xs:string clientSecret The OAuth2 client secret
xs:string uploadUrl https://upload.box.com/api/2.0/files Optional. The url of the endpoints dedicated to file uploading operations
xs:boolean useGzip false Optional. If set to true, Box will be asked to gzip all its responses
xs:string authorizationUrl https://www.box.com/api/oauth2/authorize Optional. The URL defined by the Service Provider where the resource owner will be redirected to grant authorization to the connector
xs:string accessTokenUrl https://www.box.com/api/oauth2/token Optional. The URL defined by the Service Provider to obtain an access token

OAuth2

This connector uses OAuth2 as an authorization and authentication mechanism. All the message processors or sources that require the connector to be authorized by the service provider will throw a NotAuthorizedException until the connector is authorized properly.

Authorizing the connector is a simple process of calling:

    <box:authorize/>

The call to authorize the message processor must be made though a message coming from an HTTP inbound endpoint as the authorize process will reply with a redirect to the service provider. The following is an example of how to use it in a flow with an HTTP inbound endpoint:

    <flow name="authorizationAndAuthenticationFlow">
        <http:inbound-endpoint host="localhost" port="8080" path="oauth-authorize"/>
        <box:authorize/>
    </flow>

If you hit that endpoint via a web-browser it will initiate the OAuth dance, redirecting the user to the service provider page and creating a callback endpoint so the service provider can call us back once the user has been authenticated. Once the callback gets called then the connector will switch to an authorized state and any message processor or source that requires authentication can be called.

The authorize message processor supports the following attributes:

Authorize Attributes
NameDefault ValueDescription
authorizationUrl https://www.box.com/api/oauth2/authorize Optional. The URL defined by the Service Provider where the resource owner will be redirected to grant authorization to the connector
accessTokenUrl https://www.box.com/api/oauth2/token Optional. The URL defined by the Service Provider to obtain an access token
accessTokenId   Optional. The Id with which the obtained access token will be stored. If not provided, then it will be the config name

After Authorization

The authorize message processor is an intercepting one. If something that requires authentication is requested but the connector is not authorized yet, the authorize message processor will be triggered. It will redirect the user to the service provider so that he can authorize the connector. This is why the authorize message processor needs to be behind an http:inbound-endpoint. Once authentication and authorization are successful, the service provider will respond to the connector with a callback. The connector will extract information from this callback, set its own internal state to authorized, and then move on to executing anything that had been interrupted by the authorization method.

  <flow name="authorizationAndAuthenticationFlow">
      <http:inbound-endpoint host="localhost" port="8080" path="oauth-authorize"/>
      <box:authorize/>
      <http:response-builder status="200">
          <set-payload value="You have successfully authorized the connector"/>
      </http:response-builder>
  </flow>

In the above example we added the http:response-builder (keep in mind that this element is available only in Mule 3.3.0 and later). If the connector is not yet authorized, the execution of the response builder will be delayed until the callback is received.

On the other hand, if the connector had already been authorized before, then the flow execution will not be delayed; it will continue and the http:response-builder will get executed right away rather than after the callback.

Error Handling during Authorization

If for any reason, an error occurs while processing the callback, the exception strategy of the flow containing the authorize will be executed. So, if the callback sent the wrong information you can handle that situation by setting up an exception strategy as follows:

  <flow name="authorizationAndAuthenticationFlow">
      <http:inbound-endpoint host="localhost" port="8080" path="oauth-authorize"/>
      <box:authorize/>
      <http:response-builder status="200">
          <set-payload value="You have successfully authorized the connector"/>
      </http:response-builder>
      <catch-exception-strategy>
         <http:response-builder status="404">
             <set-payload value="An error has occurred authorizing the connector"/>
         </http:response-builder>
      </catch-exception-strategy>
  </flow>

What happens if a tenant who is not yet authorized wants to perform an OAuth protected operation? You can set this with the onNoToken property:

<box:config name="boxs" consumerKey="${consumerKey}" consumerSecret="${consumerSecret}" onNoToken="[STOP_FLOW|EXCEPTION]">
    <box:oauth-callback-config connector-ref="${oauth.http.connector}" domain="${oauth.url}" localPort="${https.port}" async="false" path="oauth2callback" />
</google-calendars:config-with-oauth>

The onNoToken property can be set to two different values:

Unauthorize

Once this connector has been authorized further calls to the authorize message processor will be no-ops. If you wish to reset the state of the connector back to a non-authorized state you must call:

    <box:unauthorize/>

Keep in mind that after the connector is unauthorized all future calls that attempt to access protected resources will fail until the connector is re-authorized.

Callback Customization

As mentioned earlier, once authorize gets called and before we redirect the user to the service provider, we create a callback endpoint. The callback endpoint will get called automatically by the service provider once the user is authenticated and he grants authorization to the connector to access his private information.

The callback can be customized in the config element of the this connector as follows:

    <box:config>
        <box:oauth-callback-config domain="${fullDomain}" localPort="${http.port}" remotePort="80" defaultAccessTokenId="#[message.inboundProperties['tenantId']]" />
    </box:config>

The oauth-callback-config element can be used to customize the endpoint that gets created for the callback. It features the following attributes:

OAuth Callback Config Attributes
NameDescription
connector-ref Optional. Reference to a user-defined HTTP connector.
domain Optional. The domain portion of the callback URL. This is usually something like xxx.cloudhub.io if you are deploying to CloudHub for example.
localPort Optional. The local port number that the endpoint will listen on. Normally 80, in the case of CloudHub you can use the environment variable ${http.port}.
remotePort Optional. This is the port number that we will tell the service provider we are listening on. It is usually the same as localPort but it is separated in case your deployment features port forwarding or a proxy.
path Optional. Path under which the callback should be exposed. If not specified a random path will be generated.
defaultAccessTokenId Optional. A Mule Expression to use as access token id. If provided, this expression will be evaluated for all obtained access tokens and the result will be used as their id (except in the cases in which a specific acessTokenId was provided on the authorize processor

The example shown above is what the configuration would look like if your app would be deployed to CloudHub.

Access Token Store

This connector has the capability of automatically saving and restoring access tokens. The connector will store in either the default user object store or a user-defined one the acquired access tokens, refresh tokens, and any other pertinent information using the access token identifier as the key.

The object store can be configured as follows

    <box:config>
        <box:oauth-store-config objectStore-ref="my-object-store"/>
    </box:config>

There is only a single attribute entitled objectStore-ref in the oauth-store-config element that allows the user to specify the name of the object store that he wishes to use to save and restore access tokens.

Another important aspect of the token store is the ids. This connector supports multi-tenancy, which means that each instance of this connector is capable of supporting multiple concurrent users. Therefore, each access token is given an id to identify the owning tenant.

By default, the connector's config name is used the access token id. Also, by default, at the time of using a protected operation, it's not mandatory to provide an accessTokenId since the config's name will also be used by default.

This defaults are fine for the single-tenant case or for CloudHub enabled multi-tenancy. If you are running on-premise or you are not using Cloudhub's multi-tenancy mode, there are a couple of ways in which you can easily handle your token ids manually.

First, you can specify a defaultAccessTokenId on the connector's callback element. Each time a callback is received, that expression will get evaluated and the resulting value will be used as the token id. At the same time, when using a protected operation that expression will be evaluated to obtain the id of the access token to fetch.

Another option is to use to provide an accessTokenId expression on the authorize processor. If you do so, the expression's result will be used as the token id instead. Notice that if you choose to force the token id like this, then you also need to provide a matching accessTokenId expression on each protected operation that uses that token.

Message Processors

<box:change-primary-login>

Used to convert one of the user’s confirmed email aliases into the user’s primary login.

XML Sample
<box:change-primary-login userId="#[flowVars['userId']]" login="mariano.gonzalez@mulesoft.com"/>

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
userId The id of the user being updated String */* UTF-8
login The new login String */* UTF-8
Returns
Return Type Description
User an instance of User with the modified state

<box:comment-discussion>

Used to add a comment to a discussion.

XML Sample
<box:comment-discussion discussionId="#[flowVars['discId']]" message="Hello mule!" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
discussionId The id of the discussion to comment on String */* UTF-8
message The text of the comment to be posted String */* UTF-8
Returns
Return Type Description
Comment an instance of Comment representing the created message

<box:comment-file>

Used to add a comment by the user to a specific file

XML Sample
<box:comment-file fileId="#[flowVars['fileID']]" message="hello mule!"/>

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
fileId The id of the file to be commented on String */* UTF-8
message Text of the comment to be posted String */* UTF-8
Returns
Return Type Description
Comment an instance of Comment representing the created message

<box:copy-file>

Used to create a copy of a file in another folder. The original version of the file will not be altered.

XML Sample
<box:copy-file fileId="#[flowVars['fileId']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
targetFolderId 0 Optional. The if of the target folder. Defaults to the root folder String */* UTF-8
fileId The id of the file you want to copy String */* UTF-8
Returns
Return Type Description
File and instance of File representing the copy of the file

<box:copy-folder>

Used to create a shared link for this particular folder

XML Sample
<box:share-folder folderId="#[flowVars['folderID']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
targetFolderId 0 Optional. The id of the parent folder that will hold the copy. If not provided then the root will be used String */* UTF-8
folderId The if od the folder being copied String */* UTF-8
Returns
Return Type Description
Folder an instance of Folder representing the copy

<box:create-collaboration>

Used to add a collaboration for a single user to a folder. Either an email address or a user ID can be used to create the collaboration. Transferring ownership: To transfer ownership of a folder (as the current owner of the folder), first create a collaboration for the new user with any role. Then update that collaboration with a role of ‘owner’.

XML Sample
<box:create-collaboration />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
collaboration #[payload] Optional. Object representing the collaboration to be created Collaboration */*
Returns
Return Type Description
Collaboration a new instance of Collaboration with the state of the newly created collab

<box:create-discussion>

Used to create the metadata for a new discussion for a particular folder. The parent, id and name attributes of the request object are required

XML Sample
<box:create-discussion />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
discussion #[payload] Optional. The discussion object to be created Discussion */*
Returns
Return Type Description
Discussion an instance of Discussion with the metadata of the created discussion

<box:create-email-alias>

Adds a new email alias to the given user’s account.

XML Sample
<box:create-email-alias userId="#[flowVars['userId']]" email="mariano.gonzalez@mulesoft.com"/>

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
userId The id of the user getting the alias String */* UTF-8
email The new email alias String */* UTF-8
Returns
Return Type Description
EmailAlias an instance of EmailAlias

<box:create-folder>

Creates a new folder and returns a folder object with all its associated information

XML Sample
<box:create-folder folderName="my new folder" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
parentId 0 Optional. The id of the parent folder. If not provided then the root will be used String */* UTF-8
folderName The name of the folder String */* UTF-8
Returns
Return Type Description
Folder an instance of Folder representing the newly created folder

<box:create-user>

Used to provision a new user in an enterprise. This method only works for enterprise admins.

XML Sample
<box:create-user />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
user #[payload] Optional. An instance of User representing the user to be created User */*
Returns
Return Type Description
User a new instance of User with the final state of the created object

<box:delete-collaboration>

Used to delete a single collaboration.

XML Sample
<box:delete-collaboration collaborationId="#[flowVars['collabId']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
collaborationId The id of the collaboration to be deleted String */* UTF-8

<box:delete-comment>

Delets a comment.

XML Sample
<box:delete-comment commentId="#[flowVars['commentID']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
commentId The id of the comment to be deleted String */* UTF-8

<box:delete-email-alias>

Removes an email alias from a user.

XML Sample
<box:delete-email-alias userId="#[flowVars['userId']]" emailAliasId="#[flowVars['emailAliasId']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
userId The id of the user owning the alias String */* UTF-8
emailAliasId The id of the alias being deleted String */* UTF-8

<box:delete-file>

Discards a file to the trash. The etag of the file can be included as an ‘If-Match’ header to prevent race conditions. Depending on the enterprise settings for this user, the item will either be actually deleted from Box or moved to the trash.

XML Sample
<box:delete-file fileId="#[payload.id]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
fileId The id of the file to be deleted String */* UTF-8
etag Optional. If provided, it will be used to verify that no newer version of the file is available at box String */* UTF-8

<box:delete-folder>

Deletes a folder

XML Sample
<box:delete-folder folderId="#[flowVars['folderID']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
folderId The id of the folder to be deleted String */* UTF-8
recursive true Optional. Whether to delete this folder if it has items inside of it Boolean */*

<box:delete-user>

Deletes a user in an enterprise account.

XML Sample
<box:delete-user userId="#[flowVars['userId']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
userId The id of the user being delete String */* UTF-8
notify true Optional. Determines if the destination user should receive email notification of the transfer. Boolean */*
force false Optional. Whether or not the user should be deleted even if this user still own files. Boolean */*

<box:download>

Downloads a file

XML Sample
<box:download fileId="#[flowVars['fileId']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
fileId The id of the file you want String */* UTF-8
version Optional. The ID specific version of this file to download. String */* UTF-8
Returns
Return Type Description
InputStream an input stream with the contents of the file

<box:get-collaboration>

Used to get information about a single collaboration.

XML Sample
<box:get-collaboration collaborationId="#[flowVars['collabId']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
collaborationId The id of the collaboration you want String */* UTF-8
Returns
Return Type Description
Collaboration an instance of Collaboration

<box:get-comment>

Used to retrieve the message and metadata about a specific comment. Information about the user who created the comment is also included.

XML Sample
<box:get-comment commentId="#[flowVars['commentID']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
commentId The id of the comment you want String */* UTF-8
Returns
Return Type Description
Comment an instance of Comment representing the message

<box:get-discussion>

Used to retrieve the metadata about a specific discussion. Information about the user who created the discussion is also included.

XML Sample
<box:get-discussion discussionId="#[flowVars['discId']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
discussionId The id of the discussion you wnat String */* UTF-8
Returns
Return Type Description
Discussion an instance of Discussion with the discussion metadata

<box:get-discussion-comments>

Used to retrieve all comments for a given discussion.

XML Sample
<box:get-discussion-comments discussionId="#[flowVars['discId']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
discussionId The id of the discussions which comments you want String */* UTF-8
Returns
Return Type Description
GetCommentsResponse an instance of GetCommentsResponse

<box:get-email-aliases>

Retrieves all email aliases for this user. The collection of email aliases does not include the primary login for the user

XML Sample
<box:get-email-aliases userId="#[flowVars['userId']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
userId The id of the user whose aliases you want String */* UTF-8
Returns
Return Type Description
GetEmailAliasResponse an instance of GetEmailAliasResponse

<box:get-enterprise-events>

Retrieves events for all users in an enterprise. Upper and lower bounds as well as filters can be applied to the results.

XML Sample
<box:get-events streamPosition="0" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
createdAfter Optional. A lower bound on the timestamp of the events returned String */* UTF-8
createdBefore Optional. An upper bound on the timestamp of the events returned String */* UTF-8
limit 100 Optional. Limits the number of events returned Long */*
offset 0 Optional. The item at which to start Long */*
Child Elements
NameDefault ValueDescriptionJava Type
<box:event-types> Optional. List of events to filter by List<String>
Returns
Return Type Description
GetEventsResponse an instance of GetEventsResponse

<box:get-events>

Use this to get events for a given user. A chunk of event objects is returned for the user based on the parameters passed in. Parameters indicating how many chunks are left as well as the next streamPosition are also returned.

XML Sample
<box:get-events streamPosition="0" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
streamPosition The location in the event stream at which you want to start receiving events. Can specify special case ‘now’ to get 0 events and the latest stream position for initialization. String */* UTF-8
streamType all Optional. Limits the type of events returned StreamType */*
limit 100 Optional. Limits the number of events returned Long */*
Returns
Return Type Description
GetEventsResponse an instance of GetEventsResponse

<box:get-events-long-polling-server>

Requests access to a long polling server that notifies about events in real time. This is just a request for connection details. A subscription to such topic is not made

XML Sample
<box:get-events-long-polling-server />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
Returns
Return Type Description
LongPollingServer an instance of LongPollingServer

<box:get-file-comments>

Retrieves the comments on a particular file, if any exist.

XML Sample
<box:get-file-comments fileId="#[flowVars['fileID']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
fileId The id of the while which comments you want String */* UTF-8
Returns
Return Type Description
GetCommentsResponse an instance of GetCommentsResponse

<box:get-file-metadata>

Used to retrieve the metadata about a file.

XML Sample
<box:get-file-metadata fileId="#[flowVars['fileId']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
fileId The id of the file you want to inspect String */* UTF-8
getAllAttributes false Optional. Option to retrieve all file attributes or just the default ones boolean */*
Returns
Return Type Description
File an instance of File

<box:get-file-thumbnail>

Retrieves a thumbnail, or smaller image representation, of this file. Sizes of 32x32, 64x64, 128x128, and 256x256 can be returned. Currently thumbnails are only available in .png format and will only be generated for image file formats.

XML Sample
<box:get-file-thumbnail fileId="#[flowVars['fileID']]" minSize="px32x32" maxSize="px64x64"/>

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
fileId The id of the file which thumb you want String */* UTF-8
minSize Optional. The minimum size you're interested in ThumbnailSize */*
maxSize Optional. The maximum size you're interested in ThumbnailSize */*
Returns
Return Type Description
InputStream an InputStream with the content of the thumb. Remember to close it!

<box:get-folder>

Retrieves information about a given folder. If the folderId parameter is not provided or equals 0, then the root folder will be returned.

XML Sample
<box:get-folder />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
folderId 0 Optional. The id of the folder you want to get. 0 means root String */* UTF-8
getAllAttributes false Optional. Option to retrieve all folder attributes or just the default ones boolean */*
Returns
Return Type Description
Folder an instance of Folder

<box:get-folder-by-path>

Returns the folder information for a given path

XML Sample
<box:get-folder-by-path resourcePath="/Download" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
resourcePath The resource to retrieve from Box String */* UTF-8
getAllAttributes false Optional. Option to retrieve all folder attributes or just the default ones boolean */*
Returns
Return Type Description
Folder an instance of Folder with that about the found Folder. null if the folder is not found
Exception Payloads
Payload ClassDescription
Exception if case of error

<box:get-folder-discussions>

Retrieves the discussions on a particular folder, if any exist.

XML Sample
<box:get-folder-discussions folderId="#[flowVars['folderId']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
folderId The id of the folder which discussions you want String */* UTF-8
Returns
Return Type Description
Entries an instance of Entries

<box:get-folder-item>

Traverses a given folder looking for a resource (file or folder) of a given name.

XML Sample
<box:get-folder-item resourceName="invoices" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
folderId 0 Optional. The id of the folder you want to inspect. If not provided then the root folder is assumed String */* UTF-8
resourceName The name you want to test String */* UTF-8
Returns
Return Type Description
Item an instance of Item with that about the found item. null if the item is not found
Exception Payloads
Payload ClassDescription
Exception if case of error

<box:get-folder-items>

Retrieves the files and/or folders contained within this folder without any other metadata about the folder in the mini format is returned for each item by default. Paginated results can be retrieved using the limit and offset parameters.

This operation can potentially return a large amount of records that might exceed memory capacity.

To prevent this from being a problem, the output of this operation is automatically paginated into an iterable collection of objects. Regardless of the page-size, the iterator will be pushing out registries one at a time and fetching next pages on demand. If you wish to take advantage of the pagination, you must process the output through elements that can handle collections, such as a ForEach scope or DataMapper. In this way, Mule will execute the entire set of registries one at a time, but processing only a batch at a time and thus keeping memory usage from going over limits.

XML Sample
<box:get-folder-items folderId="#[flowVars['folderID']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
folderId 0 Optional. The id of the folder you want to inspect. If not provided then the root folder is assumed String */* UTF-8
limit Optional. The maximum amount of items to be returned (default=100, max=1000) Long */*
offset 0 Optional. Pagination offset (default=0) Long */*
fetchSize 100 Specify the number of objects that will be returned in each iteration int    
Returns
Return Type Description
Iterator < Item > A collection: each index contains a list of objects, each object with its own set of properties. It is possible to process it in parts thanks to its pagination.

<box:get-item-by-path>

Returns the item information for a given path.

XML Sample
<box:get-item-by-path resourcePath="/Download/newFile.jpg" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
resourcePath The resource to retrieve from Box String */* UTF-8
Returns
Return Type Description
Item an instance of Item with that about the found item. null if the item is not found
Exception Payloads
Payload ClassDescription
Exception if case of error

<box:get-pending-collaborations>

Used to retrieve all pending collaboration invites for this user.

XML Sample
<box:get-collaboration collaborationId="#[flowVars['collabId']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
Returns
Return Type Description
GetCollaborationsResponse an instance of GetCollaborationsResponse

<box:get-trashed-file>

Retrieves the metadata of a trashed file

XML Sample
<box:get-trashed-file fileId="#[flowVars['fileId']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
fileId The id of the trashed file you want String */* UTF-8
Returns
Return Type Description
File an instance of File

<box:get-trashed-folder>

Retrieves a folder that has been moved to the trash.

XML Sample
<box:get-trashed-folder folderId="#[flowVars['folderID']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
folderId The id of the folder you want String */* UTF-8
Returns
Return Type Description
Folder an instance of Folder

<box:get-trashed-items>

Get the folders in the Trash. Retrieves the files and/or folders that have been moved to the trash using the mini format. Paginated results can be retrieved using the limit and offset parameters.

This operation can potentially return a large amount of records that might exceed memory capacity.

To prevent this from being a problem, the output of this operation is automatically paginated into an iterable collection of objects. Regardless of the page-size, the iterator will be pushing out registries one at a time and fetching next pages on demand. If you wish to take advantage of the pagination, you must process the output through elements that can handle collections, such as a ForEach scope or DataMapper. In this way, Mule will execute the entire set of registries one at a time, but processing only a batch at a time and thus keeping memory usage from going over limits.

XML Sample
<box:get-trashed-items />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
limit 100 Optional. The maximum amount of items to be returned (default=100, max=1000) Long */*
offset 0 Optional. Pagination offset (default=0) Long */*
fetchSize 100 Specify the number of objects that will be returned in each iteration int    
Returns
Return Type Description
Iterator < Item > A collection: each index contains a list of objects, each object with its own set of properties. It is possible to process it in parts thanks to its pagination.

<box:get-user>

Retrieves information about the user who is currently logged in i.e. the user for whom this auth token was generated.

XML Sample
<box:get-user />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
Returns
Return Type Description
User an instance of User

<box:get-users>

Returns a list of all users for the Enterprise

XML Sample
<box:get-users />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
filterTerm Optional. A string used to filter the results to only users starting with the filter_term in either the name or the login String */* UTF-8
limit Optional. The number of records to return. Long */*
offset Optional. The record at which to start Long */*
Returns
Return Type Description
GetUsersResponse an instance of GetUsersResponse

<box:get-versions-metadata>

If there are previous versions of this file, this method can be used to retrieve metadata about the older versions. Alert: Versions are only tracked for Box users with premium accounts.

XML Sample
<box:get-file-metadata fileId="#[flowVars['fileId']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
fileId The id of the file which versions you want to pull String */* UTF-8
Returns
Return Type Description
FileVersionResponse an instance of FileVersionResponse with the metadata about the versions

<box:move-folder-to-user>

Moves all of the content from within one user’s folder into a new folder in another user’s account. You can move folders across users as long as the you have administrative permissions. To move everything from the root folder, use 0 (zero) which always represents the root folder of a Box account

XML Sample
<box:move-folder-to-user />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
targetUser #[paylaod] Optional. An instance of User representing the user that will receive the folder User */*
folderId 0 Optional. The id of the folder to be moved String */* UTF-8
notify true Optional. Determines if the destination user should receive email notification of the transfer. Boolean */*
Returns
Return Type Description
Folder an instance of Folder representing the moved folder

<box:perm-delete-file>

Permanently deletes an item that is in the trash. The item will no longer exist in Box. This action cannot be undone.

XML Sample
<box:perm-delete-file fileId="#[flowVars['fileID']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
fileId The id of the file to be permanently deleted String */* UTF-8

<box:perm-delete-folder>

Permanently deletes an item that is in the trash. The item will no longer exist in Box. This action cannot be undone.

XML Sample
<box:perm-delete-folder folderId="#[flowVars['folderID']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
folderId The id of the folder to be permanently deleted String */* UTF-8

<box:restore-trashed-file>

Restores a file that has been moved to the trash. Default behavior is to restore the item to the folder it was in before it was moved to the trash. If that parent folder no longer exists or if there is now an item with the same name in that parent folder, the new parent folder and/or new name will need to be included in the request.

XML Sample
<box:restore-trashed-file fileId="#[flowVars['fileID']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
fileId The id of the trashed file being restored String */* UTF-8
request #[payload] Optional. An instance of RestoreTrashedItemRequest with the request parameters RestoreTrashedItemRequest */*
Returns
Return Type Description
File an instance of Folder with the restored folder new state

<box:restore-trashed-folder>

Restores an item that has been moved to the trash. Default behavior is to restore the item to the folder it was in before it was moved to the trash. If that parent folder no longer exists or if there is now an item with the same name in that parent folder, the new parent folder and/or new name will need to be included in the request.

XML Sample
<box:restore-trashed-folder folderId="#[flowVars['folderID']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
folderId The id of the trashed folder being restored String */* UTF-8
request #[payload] Optional. An instance of RestoreTrashedItemRequest with the request parameters RestoreTrashedItemRequest */*
Returns
Return Type Description
Folder an instance of Folder with the restored folder new state

<box:search>

The search endpoint provides a simple way of finding items that are accessible in a given user’s Box account.

XML Sample
<box:search query="football" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
query The string to search for; can be matched against item names, descriptions, text content of a file, and other fields of the different item types. String */* UTF-8
limit 30 Optional. Number of search results to return Long */*
offset 0 Optional. The search result at which to start the response Long */*
Returns
Return Type Description
SearchResponse an instance of SearchResponse

<box:share-file>

Used to create a shared link for this particular file.

XML Sample
<box:share-file fileId="#[flowVars['fileID']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
fileId The id of the file you want to share String */* UTF-8
sharedLink #[payload] Optional. An instance of SharedLink with the information about the share SharedLink */*
Returns
Return Type Description
File an instance of File representing the shared folder

<box:share-folder>

Used to create a shared link for this particular folder

XML Sample
<box:share-folder folderId="#[flowVars['folderID']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
folderId The id of the folder you want to share String */* UTF-8
sharedLink #[payload] Optional. An instance of SharedLink with the information about the share SharedLink */*
Returns
Return Type Description
Folder an instance of Folder representing the shared folder

<box:unshare-file>

Deletes the shared link associated to a file

XML Sample
<box:unshare-file fileId="#[flowVars['fileID']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
fileId The id of the file you want to unshare String */* UTF-8
Returns
Return Type Description
File an instance of File representing the unshared folder

<box:unshare-folder>

Deletes the shared link associated to a folder

XML Sample
<box:unshare-folder folderId="#[flowVars['folderID']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
folderId The id of the folder you want to unshare String */* UTF-8
Returns
Return Type Description
Folder an instance of Folder representing the unshared folder

<box:update-collaboration>

Used to update an existing collaboration.

XML Sample
<box:update-collaboration collaborationId="#[flowVars['collabId']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
collaboration #[payload] Optional. Object holding the new state for the collaboration Collaboration */*
collaborationId The id of the collaboration to be updated String */* UTF-8
Returns
Return Type Description
Collaboration a new instance of Collaboration with the state of the collab

<box:update-comment>

Used to update the message of the comment.

XML Sample
<box:update-comment commentId="#[flowVars['commentID']]" newMessage="Hello Again Mule!" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
commentId The id of the comment to be updated String */* UTF-8
newMessage The new message String */* UTF-8
Returns
Return Type Description
Comment an instance of Comment representing the updated message

<box:update-discussion>

Used to update the metadata for an existing discussion.

XML Sample
<box:update-discussion discussionId="#[flowVars['discId']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
discussion #[payload] Optional. Discussion object carrying the new state Discussion */*
discussionId The id of the discussion to be updated String */* UTF-8
Returns
Return Type Description
Discussion a new instance of Discussion carrying the updated state

<box:update-file>

Update a file’s information. Used to update individual or multiple fields in the file object, including renaming the file, changing it’s description, and creating a shared link for the file. To move a file, change the ID of its parent folder. An optional etag can be provided to ensure that client only updates the file if it knows about the latest version

XML Sample
<box:update-file fileId="#[payload.id]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
fileId The id of the file which metadata you want to update String */* UTF-8
request #[payload] Optional. An instance of UpdateItemRequest carrying the update parameters UpdateItemRequest */*
etag Optional. If provided, it will be used to verify that no newer version of the file is available at box String */* UTF-8
Returns
Return Type Description
File an instance of File with the updated state of the file

<box:update-folder>

Used to update information about the folder. To move a folder, update the ID of its parent. To enable an email address that can be used to upload files to this folder, update the folderUploadEmail attribute. An optional If-Match header can be included to ensure that client only updates the folder if it knows about the latest version by setting the etag attribute.

XML Sample
<box:update-folder folderId="#[flowVars['folderId']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
request #[payload] Optional. An instance of UpdateItemRequest with the attributes you want to change UpdateItemRequest */*
folderId The id of the folder to be modified String */* UTF-8
etag Optional. If provided, it will be used to verify that no newer version of the file is available at box String */* UTF-8
Returns
Return Type Description
Folder an instance of Folder that represents the updated folder

<box:update-user>

Used to edit the settings and information about a user. This method only works for enterprise admins. To roll a user out of the enterprise (and convert them to a standalone free user), update the special enterprise attribute to be null

XML Sample
<box:update-user userId="#[flowVars['userId']]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
userId The id of the user you want to update String */* UTF-8
user #[payload] Optional. The user object with the updated state User */*
notify true Optional. Whether the user should receive an email when they are rolled out of an enterprise Boolean */*
Returns
Return Type Description
User an instance of User with the updated user state

<box:upload-new-version-path>

Uploads a new version of a file by reading the contents from a path in local storage

XML Sample
<box:upload-new-version-stream fileId="#[flowVars['fileId']]" filename="myFile.txt" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
path The path of the file in local storage String */* UTF-8
fileId The id of the file to be updated String */* UTF-8
filename New name for the file String */* UTF-8
etag Optional. If provided, it will be used to verify that no newer version of the file is available at box String */* UTF-8
contentModifiedAt Optional. The time this file was modified on the user’s machine. An example of a valid date is 2012-12-12T10:55:30-08:00 String */* UTF-8
Returns
Return Type Description
File an instance of File with the information of the updated file

<box:upload-new-version-stream>

Uploads a new version of a file from an input stream

XML Sample
<box:upload-new-version-stream fileId="#[flowVars['fileId']]" filename="myFile.txt" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
content #[payload] Optional. A java.io.InputStream with the contents of the file. This stream will leave this processor in a closed state InputStream */*
fileId The id of the file to be updated String */* UTF-8
etag Optional. If provided, it will be used to verify that no newer version of the file is available at box String */* UTF-8
filename New name for the file String */* UTF-8
contentModifiedAt Optional. The time this file was modified on the user’s machine. An example of a valid date is 2012-12-12T10:55:30-08:00 String */* UTF-8
Returns
Return Type Description
File an instance of File with the information of the updated file

<box:upload-path>

Receives the path of a file in local storage and uploads its content

XML Sample
<box:upload-path path="hello.txt" filename="hello.txt" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
path The path of the file in local storage String */* UTF-8
folderId 0 Optional. The id of the target folder. String */* UTF-8
filename The name you want the file to have at box. If not provided, the name on current storage will be used String */* UTF-8
includeHash false Optional. If true a sha1 hash of the file will be calculated prior to upload. Box will use that hash to verify that the content's hasn't been corrupted. boolean */*
contentCreatedAt Optional. The time this file was created on the user’s machine. An example of a valid date is 2012-12-12T10:55:30-08:00 String */* UTF-8
contentModifiedAt Optional. The time this file was modified on the user’s machine. An example of a valid date is 2012-12-12T10:55:30-08:00 String */* UTF-8
Returns
Return Type Description
File an instance of File with the information of the created file

<box:upload-stream>

Creates a new file with the contents of a java.io.InputStream. You need to take in count that since this is a stream, using the option of including a verification hash will cause the contents of the input stream to be fully read and loaded in memory.

XML Sample
<box:upload-stream filename="hello.txt" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
folderId 0 Optional. The id of the target folder. String */* UTF-8
filename The name you want the file to have at box. String */* UTF-8
content #[payload] Optional. A java.io.InputStream with the contents of the file. This stream will leave this processor in a closed state InputStream */*
includeHash false Optional. If true a sha1 hash of the file will be calculated prior to upload. Box will use that hash to verify that the content's hasn't been corrupted. boolean */*
contentCreatedAt Optional. The time this file was created on the user’s machine. An example of a valid date is 2012-12-12T10:55:30-08:00 String */* UTF-8
contentModifiedAt Optional. The time this file was modified on the user’s machine. An example of a valid date is 2012-12-12T10:55:30-08:00 String */* UTF-8
Returns
Return Type Description
File an instance of File with the information of the created file

Message Sources

<box:listen-events>

Message source that subscribes to the events long polling server and will trigger a new message each time an event is generated. Such message will have an instance of @{link org.mule.modules.box.model.PollingEvent} as payload and an inbound property called 'boxAccessTokenId' that will carry the accessTokenId of the user that owns the event. This source will not provide the events that are generated, it's just a notification that there're new events available. You'll need to use the get-events processor to actually get them. Managing the stream position while doing so is up to you.

XML Sample
<box:listen-events />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
callback Callback to be invoked when a message arribes SourceCallback */*
Returns
Return Type Description
StopSourceCallback an instance of org.mule.api.callback.StopSourceCallback that unsubscribes the long polling server when the app is stopped.

Transformers