org.mule.modules

mule-module-boxnet

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	1.1.0
Minimum Mule Version	3.3

Module Overview

Box.net Cloud Connector Module.

Summary

Configuration
<box:config> Configure an instance of this module

Message Processors
<box:add-to-tag> This processor adds file or folder to tags list.
<box:auth-token> After the user authenticates the ticket obtained with the get-ticket processor, there're two ways to get the required auth token: You can configure box.net to make a callback returning the ticket and authToken, in which case you need to set the usesCallback and callbackPath config attributes accordingly You can use this processor to obtain the authentication token explicitly.
<box:authorize-ticket> Redirects the browser to box authorization page so that the user can enter his credentials.
<box:create-folder> Create a new folder
<box:delete> Deletes a file or folder
<box:download> Downloads a file an returns its contents as a byte[]
<box:export-tags> This processor returns all the user's tags.
<box:get-file-info> Gets information about a file
<box:get-ticket> Get and access ticket using the configured apiKey.
<box:get-tree-structure> This processor is used to get a user's files and folders tree.
<box:logout> Logs out the user associated with the authorization token
<box:move> This processor moves a file or folder to another folder.
<box:private-share> This processor privately shares a file or folder with another user(s).
<box:public-share> Makes a public share of a file or folder
<box:public-unshare> This processor unshares a public shared file or folder
<box:register-new-user> Create a new user in box.net
<box:rename> This processor renames a file or folder.
<box:set-description> This processor sets a description to a file or folder.
<box:upload-files> Receives a comma separated list of paths and uploads the corresponding files.
<box:upload-stream> Receives an input stream and uploads its content as a file
<box:verify-registration-email> This method is used to verify user registration email

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	apiKey		The API key obtained when registering a project with the Box platform.
xs:string	callbackPath	box_auth_callback	Optional. The url where box.net will direct the authentication callback.
xs:int	callbackPort	8080	Optional. The port where the authentication callback will be listening on Defaults to 8080
	httpConnector	connector.http.mule.default	Optional. The http connector to be used when serving the authorization callback.
xs:string	postAuthFlow		Optional. The name of a flow to be invoked after an authorization callback is received.
xs:string	restoreAuthTokenFlow		Optional. The name of a flow to be executed each time the authentication token needs to be used.
xs:string	saveAuthTokenFlow		Optional. The name of a flow to be executed each time an authentication token is received.
xs:boolean	usesCallback	false	Optional. If true, an http inbound endpoint will be set in place to receive a callback from box.net with the authToken once the user has authenticated.

Message Processors

<box:add-to-tag>

This processor adds file or folder to tags list.

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
message	The current mule message	MuleMessage	/
csvTags	Comma separated list of tags	String	/	UTF-8
target	Can be either 'file' or 'folder' depending on what do you want to add	Target	/
targetId	The id of a file or folder to be added	String	/	UTF-8

Returns

Return Type	Description
String	'addtotag_ok' if successful. Otherwise addtotag_error.

<box:auth-token>

After the user authenticates the ticket obtained with the get-ticket processor, there're two ways to get the required auth token:

You can configure box.net to make a callback returning the ticket and authToken, in which case you need to set the usesCallback and callbackPath config attributes accordingly
You can use this processor to obtain the authentication token explicitly.

Either way, this connector will retain the authToken in memory and will use it in all operations. For more info look at http://developers.box.net/w/page/12923915/ApiAuthentication

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
message	The current mule message	MuleMessage	/
ticket	The ticket to authenticate against.	String	/	UTF-8

Exception Payloads

Payload Class	Description
IllegalArgumentException	if the ticket does not match a logged user

<box:authorize-ticket>

Redirects the browser to box authorization page so that the user can enter his credentials. The new location will be https://www.box.net/api/1.0/auth/<<ticket>>

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
message	The current mule message	MuleMessage	/
ticket	The ticket to be authorized	String	/	UTF-8

<box:create-folder>

Create a new folder

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
message		The current mule message	MuleMessage	/
parentFolderId		The id of the parent folder	String	/	UTF-8
folderName		The name of the folder you want to create	String	/	UTF-8
share	false	Optional. Specifies if the folder is shared. This parameter is optional and defaults to false	Boolean	/

Returns

Return Type	Description
CreateFolderResponse	an instance of `CreateFolderResponse` with data about the operation status and info about the newly created folder (if successful)

<box:delete>

Deletes a file or folder

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
message	The current mule message	MuleMessage	/
target	The type of item to be shared. This can be set as 'file' or 'folder'. Any other value will throw a IllegalArgumentException	Target	/
targetId	The id of the item you wish to delete. If the target is a folder, this will be the folder_id. If the target is a file, this will be the file_id.	String	/	UTF-8

Returns

Return Type	Description
DeleteResponse	an instance of `DeleteResponse` with data about the operation status

<box:download>

Downloads a file an returns its contents as a byte[]

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
message	The current mule message	MuleMessage	/
fileId	The id of the file we want to download	String	/	UTF-8

Returns

Return Type	Description
byte[]	the file's contents as a byte array

<box:export-tags>

This processor returns all the user's tags. On successful you will get an xml representing the tags that looks like this: music mp3 If the result wasn't successful, status field can be: not_logged_id, application_restricted.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
message		The current mule message	MuleMessage	/
encoding	UTF-8	Optional. Encoding to use when decoding from BASE64. Optional, defaults to UTF-8	String	/	UTF-8

Returns

Return Type	Description
String	a String xml representing the tags

<box:get-file-info>

Gets information about a file

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
message	The current mule message	MuleMessage	/
fileId	The id of the file you want info about	String	/	UTF-8

Returns

Return Type	Description
GetFileInfoResponse	an instance of `GetFileInfoResponse`

<box:get-ticket>

Get and access ticket using the configured apiKey. Optionally, you can ask the connector to automatically redirect the browser to box authorization page so that the user can enter his credentials. This is done by invoking org.mule.modules.boxnet.BoxConnector.authorizeTicket(MuleMessage, String) Otherwise, the user needs to manually go to https://www.box.net/api/1.0/auth/<<ticket>> Either way, the connector WILL NOT be responsible for storing this ticket. For more info look at http://developers.box.net/w/page/12923915/ApiAuthentication

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type
config-ref		Optional. Specify which configuration to use.
message		The current mule message	MuleMessage	/
redirect	true	Optional. If true, then the browser will be automatically redirected to https://www.box.net/api/1.0/auth/<<ticket>>	Boolean	/

Returns

Return Type	Description
String	the obtained ticket

<box:get-tree-structure>

This processor is used to get a user's files and folders tree. 'folderId' param defines root folder from which the tree begins. 'csvParams' is comma separated list where you can set additional parameters, which are: onelevel - make a tree of one level depth, so you will get only files and folders stored in folder which folder_id you have provided. nofiles - include folders only in result tree, no files. nozip - do not zip tree xml. On successful result you will receive 'listing_ok' as status and the tree xml. if you haven't set 'nozip' as a parameter (it's set by default), then you have to unzip it. Then you will get xml like this: (note that updatedand createdare UNIX timestamps in PST).

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
message		The current mule message	MuleMessage	/
folderId	0	Optional. The ID of the root folder from which the tree begins. If this value is "0", the user's full account tree is returned. Defaults to zero	String	/	UTF-8
csvParams	nozip	Optional. Comma separated list of params. This is optional and defaults to 'nozip'	String	/	UTF-8
encoding	UTF-8	Optional. Optional parameter to specify the encoding to use when decoding BASE64. Defaults to UTF-8	String	/	UTF-8

Returns

Return Type	Description
GetAccountTreeResponse	an instance of `GetAccountTreeResponse` with data about the operation status and info about the inspected folder (if successful)

<box:logout>

Logs out the user associated with the authorization token

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
message		The current mule message	MuleMessage	/

Returns

Return Type	Description
LogoutResponse	an instance of `LogoutResponse` with data about the operation status

<box:move>

This processor moves a file or folder to another folder. On a successful result, status will be 's_move_node'. If the result wasn't successful, status field can be: 'e_move_node', 'not_logged_in', 'application_restricted'.

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
message	The current mule message	MuleMessage	/
target	Can be either 'file' or 'folder' depending on what do you	Target	/
targetId	Is the id of a file or folder to be moved	String	/	UTF-8
destinationId	Is the destination folder id.	String	/	UTF-8

Returns

Return Type	Description
String	if successful 's_move_node'. Otherwise it can be 'e_move_node', 'not_logged_in', 'application_restricted'.

<box:private-share>

This processor privately shares a file or folder with another user(s). 'target' param, 'target_id' is . 'emails' params is an array of emails of users' to share files with. if 'notify' param is , 'message' param . Note: currently only files can be shared privately.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
muleMessage		The current mule message	MuleMessage	/
target		Should be either 'file' or 'folder'	Target	/
targetId		The id of the file or folder to be shared	String	/	UTF-8
csvMails		Comma separated list of email addresses of the users that will receive the share	String	/	UTF-8
notify	true	Optional. If true, then a notification email will be sent to users. Optional parameter, defaults to true	Boolean	/
message		Optional. Is a message to be included in the notification email. Optional parameter, defaults to an empty string	String	/	UTF-8

Returns

Return Type	Description
String	if successful will be 'private_share_ok'. Otherwise can be: 'private_share_error', 'wrong_node', 'not_logged_in', 'application_restricted'.

<box:public-share>

Makes a public share of a file or folder

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
muleMessage	The current mule message	MuleMessage	/
target	The type of item to be shared. This can be set as 'file' or 'folder'. Any other value will throw a IllegalArgumentException	Target	/
targetId	The id of the item you wish to share. If the target is a folder, this will be the folder_id. If the target is a file, this will be the file_id.	String	/	UTF-8
password	The password to protect the folder or file.	String	/	UTF-8
message	An message to be included in a notification email.	String	/	UTF-8

Returns

Return Type	Description
PublicShareResponse	an instance of `PublicShareResponse` with data about the operation status and info about the shared folder (if successful)

<box:public-unshare>

This processor unshares a public shared file or folder

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
message	The current mule message	MuleMessage	/
target	Shoud be either 'file' or 'folder'	Target	/
targetId	Is id of a file or folder to be unshared	String	/	UTF-8

Returns

Return Type	Description
String	On a successful result, the status will be 'unshare_ok'. If the result wasn't successful, the status field can be: 'unshare_error', 'wrong_node', 'not_logged_in', 'application_restricted'.

<box:register-new-user>

Create a new user in box.net

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
email	The user's email	String	/	UTF-8
password	The user's password	String	/	UTF-8

Returns

Return Type	Description
RegisterNewUserResponse	an instance of `RegisterNewUserResponse` with data about the operation status and info about the newly created user (if successful)

<box:rename>

This processor renames a file or folder.

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
message	The current mule message	MuleMessage	/
target	Can be either 'file' or 'folder' depending on what you want to rename	Target	/
targetId	Is the id of a file or folder to be renamed	String	/	UTF-8
newName	Is the new name for a file or folder	String	/	UTF-8

Returns

Return Type	Description
String	if successful will be 's_rename_node'. Otherwise it can be: 'e_rename_node', 'not_logged_in', 'application_restricted'

<box:set-description>

This processor sets a description to a file or folder.

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
message	The current mule message	MuleMessage	/
target	Can be either 'file' or 'folder'	Target	/
targetId	The id of the folder/file you want to modify	String	/	UTF-8
description	The description you want to set	String	/	UTF-8

Returns

Return Type	Description
String	's_set_description' if successful. 'e_set_description' otherwise.

<box:upload-files>

Receives a comma separated list of paths and uploads the corresponding files.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
message		The current mule message	MuleMessage	/
folderId	0	Optional. The id of the parent folder. Defaults to 0 (the root folder)	String	/	UTF-8

Child Elements

Name	Default Value	Description	Java Type
<box:paths>	#[payload]	Optional. A List of Strings with the paths where the files are. Defaults to payload	List<String>

Returns

Return Type	Description
UploadResponse	an instance of `UploadResponse` with data about the operation status and info about the newly uploaded files (if successful)

<box:upload-stream>

Receives an input stream and uploads its content as a file

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
message		The current mule message	MuleMessage	/
folderId	0	Optional. The id of the parent folder. Defaults to 0 which is the root folder	String	/	UTF-8
filename		The name we want the file to have on box.net	String	/	UTF-8
input	#[payload]	Optional. InputStream with the contents of the file. Defaults to the message payload.	InputStream	/

Returns

Return Type	Description
UploadResponse	an instance of `UploadResponse` with data about the operation status and info about the newly uploaded file (if successful)

<box:verify-registration-email>

This method is used to verify user registration email

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
message	The current mule message	MuleMessage	/
loginName	The login username of the user for which you would like to verify registration.	String	/	UTF-8

Returns

Return Type	Description
String	Upon a successful registration, the return value will be 'email_ok'. If registration was not successful, it can be: 'email_invalid' - The login provided is not a valid email address. 'email_already_registered' - The login provided is already registered by another user. 'application_restricted'- You provided an invalid api_key, or the api_key is restricted from calling this function.