org.mule.modules

mule-module-box

config

Namespace	http://www.mulesoft.org/schema/mule/box
Schema Location	http://www.mulesoft.org/schema/mule/box/current/mule-box.xsd (View Schema)
Schema Version	2.0
Minimum Mule Version	3.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
Type	Name	Default Value	Description	Java Type	MIME Type	Encoding
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
Name	Default Value	Description
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:

STOP_FLOW: acts as a filter and kills the execution of the flow
EXCEPTION: throws an exception informing that the token is still not acquired

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
Name	Description
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

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

Name	Default Value	Description	Java 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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
fileId		The id of the file you want to inspect	String	/	UTF-8

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

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
folderId	0	Optional. The id of the fodler you want to get. 0 means root	String	/	UTF-8

Returns

Return Type	Description
Folder	an instance of `Folder`

<box:get-folder-by-path>

Returns the folder information for a given path

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
resourcePath		The resource to retrieve from Box	String	/	UTF-8

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 Class	Description
Exception	if case of error

<box:get-folder-discussions>

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

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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 Class	Description
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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	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-item-by-path>

Returns the item information for a given path.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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 Class	Description
Exception	if case of error

<box:get-pending-collaborations>

Used to retrieve all pending collaboration invites for this user.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
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.