[[box-component]]
= Box Component
//THIS FILE IS COPIED: EDIT THE SOURCE FILE:
:page-source: components/camel-box/camel-box-component/src/main/docs/box-component.adoc
:docTitle: Box
:artifactId: camel-box
:description: Upload, download and manage files, folders, groups, collaborations, etc. on box.com.
:since: 2.14
:supportLevel: Stable
:component-header: Both producer and consumer are supported
include::{cq-version}@camel-quarkus:ROOT:partial$reference/components/box.adoc[opts=optional]

*Since Camel {since}*

*{component-header}*

The Box component provides access to all of the Box.com APIs accessible
using https://github.com/box/box-java-sdk/[https://github.com/box/box-java-sdk]. It
allows producing messages to upload and download files, create, edit,
and manage folders, etc. It also supports APIs that allow polling for
updates to user accounts and even changes to enterprise accounts, etc.

Box.com requires the use of OAuth2.0 for all client application
authentication. In order to use camel-box with your account, you'll need
to create a new application within Box.com at
https://developer.box.com/[https://developer.box.com].
The Box application's client id and secret will allow access to Box APIs
which require a current user. A user access token is generated and
managed by the API for an end user. 

Maven users will need to add the following dependency to their pom.xml
for this component:

[source,xml]
----
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-box</artifactId>
    <version>${camel-version}</version>
</dependency>
----

== Connection Authentication Types

The Box component supports three different types of authenticated connections.

=== Standard Authentication

*Standard Authentication* uses the *OAuth 2.0 three-legged authentication process* to authenticate its connections with Box.com. This type of authentication enables Box *managed users* and *external users* to access, edit, and save their Box content through the Box component.

=== App Enterprise Authentication

*App Enterprise Authentication* uses the *OAuth 2.0 with JSON Web Tokens (JWT)* to authenticate its connections as a *Service Account* for a *Box Application*. This type of authentication enables a service account to access, edit, and save the Box content of its *Box Application* through the Box component.

=== App User Authentication

*App User Authentication* uses the *OAuth 2.0 with JSON Web Tokens (JWT)* to authenticate its connections as an *App User* for a *Box Application*. This type of authentication enables app users to access, edit, and save their Box content in its *Box Application* through the Box component.

== Box Options

// component options: START
The Box component supports 19 options, which are listed below.



[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *clientId* (common) | Box application client ID |  | String
| *configuration* (common) | To use the shared configuration |  | BoxConfiguration
| *enterpriseId* (common) | The enterprise ID to use for an App Enterprise. |  | String
| *userId* (common) | The user ID to use for an App User. |  | String
| *bridgeErrorHandler* (consumer) | Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. | false | boolean
| *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean
| *autowiredEnabled* (advanced) | Whether autowiring is enabled. This is used for automatic autowiring options (the option must be marked as autowired) by looking up in the registry to find if there is a single instance of matching type, which then gets configured on the component. This can be used for automatic configuring JDBC data sources, JMS connection factories, AWS Clients, etc. | true | boolean
| *httpParams* (advanced) | Custom HTTP params for settings like proxy host |  | Map
| *authenticationType* (authentication) | The type of authentication for connection. Types of Authentication: STANDARD_AUTHENTICATION - OAuth 2.0 (3-legged) SERVER_AUTHENTICATION - OAuth 2.0 with JSON Web Tokens | APP_USER_AUTHENTICATION | String
| *accessTokenCache* (security) | Custom Access Token Cache for storing and retrieving access tokens. |  | IAccessTokenCache
| *clientSecret* (security) | Box application client secret |  | String
| *encryptionAlgorithm* (security) | The type of encryption algorithm for JWT. Supported Algorithms: RSA_SHA_256 RSA_SHA_384 RSA_SHA_512. There are 3 enums and the value can be one of: RSA_SHA_256, RSA_SHA_384, RSA_SHA_512 | RSA_SHA_256 | EncryptionAlgorithm
| *maxCacheEntries* (security) | The maximum number of access tokens in cache. | 100 | int
| *privateKeyFile* (security) | The private key for generating the JWT signature. |  | String
| *privateKeyPassword* (security) | The password for the private key. |  | String
| *publicKeyId* (security) | The ID for public key for validating the JWT signature. |  | String
| *sslContextParameters* (security) | To configure security using SSLContextParameters. |  | SSLContextParameters
| *userName* (security) | Box user name, MUST be provided |  | String
| *userPassword* (security) | Box user password, MUST be provided if authSecureStorage is not set, or returns null on first call |  | String
|===
// component options: END

// endpoint options: START
The Box endpoint is configured using URI syntax:

----
box:apiName/methodName
----

with the following path and query parameters:

=== Path Parameters (2 parameters):


[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *apiName* | *Required* What kind of operation to perform. There are 10 enums and the value can be one of: COLLABORATIONS, COMMENTS, EVENT_LOGS, FILES, FOLDERS, GROUPS, EVENTS, SEARCH, TASKS, USERS |  | BoxApiName
| *methodName* | *Required* What sub operation to use for the selected operation |  | String
|===


=== Query Parameters (20 parameters):


[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *clientId* (common) | Box application client ID |  | String
| *enterpriseId* (common) | The enterprise ID to use for an App Enterprise. |  | String
| *inBody* (common) | Sets the name of a parameter to be passed in the exchange In Body |  | String
| *userId* (common) | The user ID to use for an App User. |  | String
| *exceptionHandler* (consumer) | To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this option is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored. |  | ExceptionHandler
| *exchangePattern* (consumer) | Sets the exchange pattern when the consumer creates an exchange. There are 3 enums and the value can be one of: InOnly, InOut, InOptionalOut |  | ExchangePattern
| *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean
| *httpParams* (advanced) | Custom HTTP params for settings like proxy host |  | Map
| *synchronous* (advanced) | Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported). | false | boolean
| *authenticationType* (authentication) | The type of authentication for connection. Types of Authentication: STANDARD_AUTHENTICATION - OAuth 2.0 (3-legged) SERVER_AUTHENTICATION - OAuth 2.0 with JSON Web Tokens | APP_USER_AUTHENTICATION | String
| *accessTokenCache* (security) | Custom Access Token Cache for storing and retrieving access tokens. |  | IAccessTokenCache
| *clientSecret* (security) | Box application client secret |  | String
| *encryptionAlgorithm* (security) | The type of encryption algorithm for JWT. Supported Algorithms: RSA_SHA_256 RSA_SHA_384 RSA_SHA_512. There are 3 enums and the value can be one of: RSA_SHA_256, RSA_SHA_384, RSA_SHA_512 | RSA_SHA_256 | EncryptionAlgorithm
| *maxCacheEntries* (security) | The maximum number of access tokens in cache. | 100 | int
| *privateKeyFile* (security) | The private key for generating the JWT signature. |  | String
| *privateKeyPassword* (security) | The password for the private key. |  | String
| *publicKeyId* (security) | The ID for public key for validating the JWT signature. |  | String
| *sslContextParameters* (security) | To configure security using SSLContextParameters. |  | SSLContextParameters
| *userName* (security) | Box user name, MUST be provided |  | String
| *userPassword* (security) | Box user password, MUST be provided if authSecureStorage is not set, or returns null on first call |  | String
|===




=== API Parameters (10 APIs):

The Box endpoint is an API based component and has additional parameters based on which API name and API method is used.
The API name and API method is located in the endpoint URI as the apiName/methodName path parameters:

----
box:apiName/methodName
----

There are 10 API names as listed in the table below:

[width="100%",cols="2,2,6",options="header"]
|===
| API Name | Type | Description
| *collaborations* | Producer | Provides operations to manage Box collaborations
| *comments* | Producer | Provides operations to manage Box comments
| *event-logs* | Producer | Provides operations to read Box enterprise (admin) event logs
| *events* | Consumer | Provides operations to manage Box events
| *files* | Producer | Provides operations to manage Box files
| *folders* | Producer | Provides operations to manage Box folders
| *groups* | Producer | Provides operations to manage Box groups
| *search* | Producer | Provides operations to manage Box searches
| *tasks* | Producer | Provides operations to manage Box tasks
| *users* | Producer | Provides operations to manage Box users
|===

Each API is documented in the following sections to come.


==== API: collaborations

*Only producer is supported*




The collaborations API has 6 method(s) which is represented by the following method signatures
(an API method may have multiple signatures due to overloading):

[source,java]
----

com.box.sdk.BoxCollaboration addFolderCollaboration(String folderId, com.box.sdk.BoxCollaborator collaborator, com.box.sdk.BoxCollaboration.Role role);

com.box.sdk.BoxCollaboration addFolderCollaborationByEmail(String folderId, String email, com.box.sdk.BoxCollaboration.Role role);

void deleteCollaboration(String collaborationId);

com.box.sdk.BoxCollaboration.Info getCollaborationInfo(String collaborationId);

java.util.Collection<com.box.sdk.BoxCollaboration.Info> getFolderCollaborations(String folderId);

com.box.sdk.BoxCollaboration updateCollaborationInfo(String collaborationId, com.box.sdk.BoxCollaboration.Info info);

----

The collaborations API is defined in the syntax as follows:

----
box:collaborations/methodName?[parameters]
----

The 6 method(s) is listed in the table below.
(API methods can have a shorthand alias name which can be used in the syntax instead of the name)

[width="100%",cols="2,2,6",options="header"]
|===
| Method | Alias | Description
| *addFolderCollaboration* | add | Add a collaboration to this folder
| *addFolderCollaborationByEmail* | addByEmail | Add a collaboration to this folder
| *deleteCollaboration* | delete | Delete collaboration
| *getCollaborationInfo* | info | Get collaboration information
| *getFolderCollaborations* | collaborations | Get information about all of the collaborations for folder
| *updateCollaborationInfo* | updateInfo | Update collaboration information
|===

The collaborations API method(s) has the following set of parameters listed in the table below:
[width="100%",cols="2,2,4,2",options="header"]
|===
| Method | Parameter | Description | Type
| addFolderCollaboration | *collaborator* |  The collaborator to add | BoxCollaborator
| addFolderCollaboration | *folderId* |  The id of folder to add collaboration to | String
| addFolderCollaboration | *role* |  The role of the collaborator | Role
| addFolderCollaborationByEmail | *email* |  The email address of the collaborator to add | String
| addFolderCollaborationByEmail | *folderId* |  The id of folder to add collaboration to | String
| addFolderCollaborationByEmail | *role* |  The role of the collaborator | Role
| deleteCollaboration | *collaborationId* |  The id of comment to change | String
| getCollaborationInfo | *collaborationId* |  The id of collaboration | String
| getFolderCollaborations | *folderId* |  The id of folder to get collaborations information on | String
| updateCollaborationInfo | *collaborationId* |  The id of collaboration | String
| updateCollaborationInfo | *info* |  Collaboration information to update | Info
|===

In addition to the parameters above, the collaborations API can also use from the 20 endpoint query option
which is listed in the _Query Parameters_ section.

Any of the parameters can be provided in either the endpoint URI, or dynamically in a message header.
The message header name must be of the format `CamelBox.parameter`.
The `inBody` parameter overrides message header, i.e. the endpoint parameter `inBody=myParameterNameHere`
would override a `CamelBox.myParameterNameHere` header.



==== API: comments

*Only producer is supported*




The comments API has 6 method(s) which is represented by the following method signatures
(an API method may have multiple signatures due to overloading):

[source,java]
----

com.box.sdk.BoxFile addFileComment(String fileId, String message);

com.box.sdk.BoxComment changeCommentMessage(String commentId, String message);

void deleteComment(String commentId);

com.box.sdk.BoxComment.Info getCommentInfo(String commentId);

java.util.List<com.box.sdk.BoxComment.Info> getFileComments(String fileId);

com.box.sdk.BoxComment replyToComment(String commentId, String message);

----

The comments API is defined in the syntax as follows:

----
box:comments/methodName?[parameters]
----

The 6 method(s) is listed in the table below.
(API methods can have a shorthand alias name which can be used in the syntax instead of the name)

[width="100%",cols="2,2,6",options="header"]
|===
| Method | Alias | Description
| *addFileComment* | add | Add comment to file
| *changeCommentMessage* | updateMessage | Change comment message
| *deleteComment* | delete | Delete comment
| *getCommentInfo* | info | Get comment information
| *getFileComments* | comments | Get a list of any comments on this file
| *replyToComment* | reply | Reply to a comment
|===

The comments API method(s) has the following set of parameters listed in the table below:
[width="100%",cols="2,2,4,2",options="header"]
|===
| Method | Parameter | Description | Type
| addFileComment | *fileId* |  The id of file | String
| addFileComment | *message* |  The comment's message | String
| changeCommentMessage | *commentId* |  The id of comment to change | String
| changeCommentMessage | *message* |  The new message for the comment | String
| deleteComment | *commentId* |  The id of comment to delete | String
| getCommentInfo | *commentId* |  The id of comment | String
| getFileComments | *fileId* |  The id of file | String
| replyToComment | *commentId* |  The id of comment to reply to | String
| replyToComment | *message* |  The message for the reply | String
|===

In addition to the parameters above, the comments API can also use from the 20 endpoint query option
which is listed in the _Query Parameters_ section.

Any of the parameters can be provided in either the endpoint URI, or dynamically in a message header.
The message header name must be of the format `CamelBox.parameter`.
The `inBody` parameter overrides message header, i.e. the endpoint parameter `inBody=myParameterNameHere`
would override a `CamelBox.myParameterNameHere` header.



==== API: event-logs

*Only producer is supported*




The event-logs API has 1 method(s) which is represented by the following method signatures
(an API method may have multiple signatures due to overloading):

[source,java]
----

java.util.List<com.box.sdk.BoxEvent> getEnterpriseEvents(String position, java.util.Date after, java.util.Date before, com.box.sdk.BoxEvent.Type[] types);

----

The event-logs API is defined in the syntax as follows:

----
box:event-logs/methodName?[parameters]
----

The 1 method(s) is listed in the table below.
(API methods can have a shorthand alias name which can be used in the syntax instead of the name)

[width="100%",cols="2,2,6",options="header"]
|===
| Method | Alias | Description
| *getEnterpriseEvents* | events | Create an event stream with optional starting initial position and add listener that will be notified when an event is received
|===

The event-logs API method(s) has the following set of parameters listed in the table below:
[width="100%",cols="2,2,4,2",options="header"]
|===
| Method | Parameter | Description | Type
| getEnterpriseEvents | *after* |  The lower bound on the timestamp of the events returned | Date
| getEnterpriseEvents | *before* |  The upper bound on the timestamp of the events returned | Date
| getEnterpriseEvents | *position* | *Optional*  The starting position of the event stream. May be null in which case all events within bounds returned. | String
| getEnterpriseEvents | *types* | *Optional*  An optional list of event types to filter by | Type[]
|===

In addition to the parameters above, the event-logs API can also use from the 20 endpoint query option
which is listed in the _Query Parameters_ section.

Any of the parameters can be provided in either the endpoint URI, or dynamically in a message header.
The message header name must be of the format `CamelBox.parameter`.
The `inBody` parameter overrides message header, i.e. the endpoint parameter `inBody=myParameterNameHere`
would override a `CamelBox.myParameterNameHere` header.



==== API: events

*Only consumer is supported*




The events API has 1 method(s) which is represented by the following method signatures
(an API method may have multiple signatures due to overloading):

[source,java]
----

void listen(com.box.sdk.EventListener listener, Long startingPosition);

----

The events API is defined in the syntax as follows:

----
box:events/methodName?[parameters]
----

The 1 method(s) is listed in the table below.
(API methods can have a shorthand alias name which can be used in the syntax instead of the name)

[width="100%",cols="2,2,6",options="header"]
|===
| Method | Alias | Description
| *listen* |  | Create an event stream with optional starting initial position and add listener that will be notified when an event is received
|===

The events API method(s) has the following set of parameters listed in the table below:
[width="100%",cols="2,2,4,2",options="header"]
|===
| Method | Parameter | Description | Type
| listen | *startingPosition* | *Optional*  The starting position of the event stream | Long
|===

In addition to the parameters above, the events API can also use from the 20 endpoint query option
which is listed in the _Query Parameters_ section.

Any of the parameters can be provided in either the endpoint URI, or dynamically in a message header.
The message header name must be of the format `CamelBox.parameter`.
The `inBody` parameter overrides message header, i.e. the endpoint parameter `inBody=myParameterNameHere`
would override a `CamelBox.myParameterNameHere` header.



==== API: files

*Only producer is supported*




The files API has 22 method(s) which is represented by the following method signatures
(an API method may have multiple signatures due to overloading):

[source,java]
----

void checkUpload(String fileName, String parentFolderId, Long size);

com.box.sdk.BoxFile copyFile(String fileId, String destinationFolderId, String newName);

com.box.sdk.Metadata createFileMetadata(String fileId, com.box.sdk.Metadata metadata, String typeName);

com.box.sdk.BoxSharedLink createFileSharedLink(String fileId, com.box.sdk.BoxSharedLink.Access access, java.util.Date unshareDate, com.box.sdk.BoxSharedLink.Permissions permissions);

void deleteFile(String fileId);

void deleteFileMetadata(String fileId);

void deleteFileVersion(String fileId, Integer version);

java.io.OutputStream downloadFile(String fileId, java.io.OutputStream output, Long rangeStart, Long rangeEnd, com.box.sdk.ProgressListener listener);

java.io.OutputStream downloadPreviousFileVersion(String fileId, Integer version, java.io.OutputStream output, com.box.sdk.ProgressListener listener);

java.net.URL getDownloadURL(String fileId);

com.box.sdk.BoxFile.Info getFileInfo(String fileId, String[] fields);

com.box.sdk.Metadata getFileMetadata(String fileId, String typeName);

java.net.URL getFilePreviewLink(String fileId);

byte[] getFileThumbnail(String fileId, com.box.sdk.BoxFile.ThumbnailFileType fileType, Integer minWidth, Integer minHeight, Integer maxWidth, Integer maxHeight);

java.util.Collection<com.box.sdk.BoxFileVersion> getFileVersions(String fileId);

com.box.sdk.BoxFile moveFile(String fileId, String destinationFolderId, String newName);

com.box.sdk.BoxFileVersion promoteFileVersion(String fileId, Integer version);

com.box.sdk.BoxFile renameFile(String fileId, String newFileName);

com.box.sdk.BoxFile updateFileInfo(String fileId, com.box.sdk.BoxFile.Info info);

com.box.sdk.Metadata updateFileMetadata(String fileId, com.box.sdk.Metadata metadata);

com.box.sdk.BoxFile uploadFile(String parentFolderId, java.io.InputStream content, String fileName, java.util.Date created, java.util.Date modified, Long size, Boolean check, com.box.sdk.ProgressListener listener);

com.box.sdk.BoxFile uploadNewFileVersion(String fileId, java.io.InputStream fileContent, java.util.Date modified, Long fileSize, com.box.sdk.ProgressListener listener);

----

The files API is defined in the syntax as follows:

----
box:files/methodName?[parameters]
----

The 22 method(s) is listed in the table below.
(API methods can have a shorthand alias name which can be used in the syntax instead of the name)

[width="100%",cols="2,2,6",options="header"]
|===
| Method | Alias | Description
| *checkUpload* | canUpload | Does a pre-verification before upload, to check if the filename already exists or if there is permission to upload
| *copyFile* | copy | Copy file to destination folder while optionally giving it a new name
| *createFileMetadata* | createMetadata | Create metadata for file in either the global properties template or the specified template type
| *createFileSharedLink* | link | Create a shared link to file
| *deleteFile* | delete | Delete the file
| *deleteFileMetadata* | deleteMetadata | Delete the file properties metadata
| *deleteFileVersion* | deleteVersion | Delete a file version
| *downloadFile* | download | Download a file
| *downloadPreviousFileVersion* | downloadVersion | Download a previous version of file
| *getDownloadURL* | url | Get an expiring URL for downloading a file directly from Box
| *getFileInfo* | info | Get file information
| *getFileMetadata* | metadata | Gets the file properties metadata
| *getFilePreviewLink* |  | Get an expiring URL for creating an embedded preview session
| *getFileThumbnail* | thumbnail | Retrieves a thumbnail, or smaller image representation, of this file
| *getFileVersions* | versions | Get any previous versions of file
| *moveFile* | move | Move file to destination folder while optionally giving it a new name
| *promoteFileVersion* | promoteVersion | Promote a previous version of file
| *renameFile* | rename | Rename file giving it the name newName
| *updateFileInfo* | updateInfo | Update file information
| *updateFileMetadata* | updateMetadata | Update the file properties metadata
| *uploadFile* | upload | Upload a new file to parent folder
| *uploadNewFileVersion* | uploadVersion | Upload a new version of file
|===

The files API method(s) has the following set of parameters listed in the table below:
[width="100%",cols="2,2,4,2",options="header"]
|===
| Method | Parameter | Description | Type
| checkUpload | *fileName* |  The name to give the uploaded file | String
| checkUpload | *parentFolderId* |  The id of parent folder | String
| checkUpload | *size* | *Optional*  The size of the file's content used for monitoring the upload's progress | Long
| copyFile | *destinationFolderId* |  The id of the destination folder | String
| copyFile | *fileId* |  The id of file to copy | String
| copyFile | *newName* | *Optional*  The new name for copied file; if newName is null, the copied file has same name as the original. | String
| createFileMetadata | *fileId* |  The id of the file to create metadata for | String
| createFileMetadata | *metadata* |  The new metadata values | Metadata
| createFileMetadata | *typeName* | *Optional*  The metadata template type name; if null the global properties template type is used. | String
| createFileSharedLink | *access* |  The access level of the shared link | Access
| createFileSharedLink | *fileId* |  The id of the file to create shared link on | String
| createFileSharedLink | *permissions* | *Optional*  The permissions of the created link; if permissions is null then the created shared link is create with default permissions. | Permissions
| createFileSharedLink | *unshareDate* | *Optional*  The date and time at which time the created shared link will expire; if unsharedDate is null then a non-expiring link is created. | Date
| deleteFile | *fileId* |  The id of file to delete | String
| deleteFileMetadata | *fileId* |  The id of file to delete | String
| deleteFileVersion | *fileId* |  The id of file with version to delete | String
| deleteFileVersion | *version* |  The version of file to delete; initial version of file has value of 0, second version of file is 1 and so on. | Integer
| downloadFile | *fileId* |  The id of file | String
| downloadFile | *listener* | *Optional*  A listener for monitoring the download's progress; if null the download's progress will not be monitored. | ProgressListener
| downloadFile | *output* |  The stream to which the file contents will be written | OutputStream
| downloadFile | *rangeEnd* | *Optional*  The byte offset in file at which to stop the download; if null the entire contents of file will be downloaded. | Long
| downloadFile | *rangeStart* | *Optional*  The byte offset in file at which to start the download; if null the entire contents of file will be downloaded. | Long
| downloadPreviousFileVersion | *fileId* |  The id of file | String
| downloadPreviousFileVersion | *listener* | *Optional*  A listener for monitoring the download's progress; if null the download's progress will not be monitored. | ProgressListener
| downloadPreviousFileVersion | *output* |  The stream to which the version contents will be written | OutputStream
| downloadPreviousFileVersion | *version* |  The version of file to download; initial version of file has value of 0, second version of file is 1 and so on. | Integer
| getDownloadURL | *fileId* |  The id of file | String
| getFileInfo | *fields* | *Optional*  The information fields to retrieve; if null all information fields are retrieved. | String[]
| getFileInfo | *fileId* |  The id of file | String
| getFileMetadata | *fileId* |  The id of the file to retrieve metadata for | String
| getFileMetadata | *typeName* | *Optional*  The metadata template type name; if null the global properties template type is used. | String
| getFilePreviewLink | *fileId* |  The id of the file to get preview link on | String
| getFileThumbnail | *fileId* |  The id of the file to get thumbnail | String
| getFileThumbnail | *fileType* |  Either PNG of JPG | ThumbnailFileType
| getFileThumbnail | *maxHeight* |  Maximum height | Integer
| getFileThumbnail | *maxWidth* |  Maximum width | Integer
| getFileThumbnail | *minHeight* |  Minimum height | Integer
| getFileThumbnail | *minWidth* |  Minimum width | Integer
| getFileVersions | *fileId* |  The id of file | String
| moveFile | *destinationFolderId* |  The id of the destination folder | String
| moveFile | *fileId* |  The id of file to move | String
| moveFile | *newName* | *Optional*  The new name of moved file; if newName is null, the moved file has same name as the original. | String
| promoteFileVersion | *fileId* |  The id of file | String
| promoteFileVersion | *version* |  The version of file to promote; initial version of file has value of 0, second version of file is 1 and so on. | Integer
| renameFile | *fileId* |  The id of file to rename | String
| renameFile | *newFileName* |  The new name of file | String
| updateFileInfo | *fileId* |  The id of file to update | String
| updateFileInfo | *info* |  The updated information | Info
| updateFileMetadata | *fileId* |  The id of file to delete | String
| updateFileMetadata | *metadata* |  The new metadata values | Metadata
| uploadFile | *check* | *Optional*  If the file name is already used, call the uploadNewVersion instead. | Boolean
| uploadFile | *content* |  A stream containing contents of the file to upload | InputStream
| uploadFile | *created* | *Optional*  The content created date that will be given to the uploaded file | Date
| uploadFile | *fileName* |  The name to give the uploaded file | String
| uploadFile | *listener* | *Optional*  A listener for monitoring the upload's progress | ProgressListener
| uploadFile | *modified* | *Optional*  The content modified date that will be given to the uploaded file | Date
| uploadFile | *parentFolderId* |  The id of parent folder | String
| uploadFile | *size* | *Optional*  The size of the file's content used for monitoring the upload's progress | Long
| uploadNewFileVersion | *fileContent* |  A stream containing contents of the file to upload | InputStream
| uploadNewFileVersion | *fileId* |  The id of file | String
| uploadNewFileVersion | *fileSize* | *Optional*  The size of the file's content used for monitoring the upload's progress | Long
| uploadNewFileVersion | *listener* | *Optional*  A listener for monitoring the upload's progress | ProgressListener
| uploadNewFileVersion | *modified* | *Optional*  The content modified date that will be given to the uploaded file | Date
|===

In addition to the parameters above, the files API can also use from the 20 endpoint query option
which is listed in the _Query Parameters_ section.

Any of the parameters can be provided in either the endpoint URI, or dynamically in a message header.
The message header name must be of the format `CamelBox.parameter`.
The `inBody` parameter overrides message header, i.e. the endpoint parameter `inBody=myParameterNameHere`
would override a `CamelBox.myParameterNameHere` header.



==== API: folders

*Only producer is supported*




The folders API has 10 method(s) which is represented by the following method signatures
(an API method may have multiple signatures due to overloading):

[source,java]
----

com.box.sdk.BoxFolder copyFolder(String folderId, String destinationFolderId, String newName);

com.box.sdk.BoxFolder createFolder(String parentFolderId, String folderName);

com.box.sdk.BoxFolder createFolder(String parentFolderId, String[] path);

com.box.sdk.BoxSharedLink createFolderSharedLink(String folderId, com.box.sdk.BoxSharedLink.Access access, java.util.Date unshareDate, com.box.sdk.BoxSharedLink.Permissions permissions);

void deleteFolder(String folderId);

com.box.sdk.BoxFolder getFolder(String[] path);

com.box.sdk.BoxFolder.Info getFolderInfo(String folderId, String[] fields);

java.util.Collection<com.box.sdk.BoxItem.Info> getFolderItems(String folderId, Long offset, Long limit, String[] fields);

com.box.sdk.BoxFolder moveFolder(String folderId, String destinationFolderId, String newName);

com.box.sdk.BoxFolder renameFolder(String folderId, String newFolderName);

com.box.sdk.BoxFolder updateFolderInfo(String folderId, com.box.sdk.BoxFolder.Info info);

----

The folders API is defined in the syntax as follows:

----
box:folders/methodName?[parameters]
----

The 10 method(s) is listed in the table below.
(API methods can have a shorthand alias name which can be used in the syntax instead of the name)

[width="100%",cols="2,2,6",options="header"]
|===
| Method | Alias | Description
| *copyFolder* | copy | Copy folder to destination folder while optionally giving it a new name
| *createFolder* | create | Create a folder specified by path from parent folder with given parentFolderId, creating intermediate directories as required
| *createFolderSharedLink* | link | Create a shared link to folder
| *deleteFolder* | delete | Delete folder
| *getFolder* | folder | Return the Box folder referenced by path
| *getFolderInfo* | info | Get folder information
| *getFolderItems* | items | Returns a specific range of child items in folder and specifies which fields of each item to retrieve
| *moveFolder* | move | Move folder to destination folder while optionally giving it a new name
| *renameFolder* | rename | Rename folder giving it the name newName
| *updateFolderInfo* | updateInfo | Update folder information
|===

The folders API method(s) has the following set of parameters listed in the table below:
[width="100%",cols="2,2,4,2",options="header"]
|===
| Method | Parameter | Description | Type
| copyFolder | *destinationFolderId* |  The id of the destination folder | String
| copyFolder | *folderId* |  The id of folder to copy | String
| copyFolder | *newName* | *Optional*  The new name for copied folder; if newName is null, the copied folder has same name as the original. | String
| createFolder | *folderName* |  The name of created folder | String
| createFolder | *parentFolderId* |  The id of parent folder | String
| createFolder | *path* |  Sequence of Box folder names from parent folder to returned folder | String[]
| createFolderSharedLink | *access* |  The access level of the shared link | Access
| createFolderSharedLink | *folderId* |  The id of folder to create shared link on | String
| createFolderSharedLink | *permissions* |  The permissions of the created link; if permissions is null then the created shared link is create with default permissions. | Permissions
| createFolderSharedLink | *unshareDate* |  The date and time at which time the created shared link will expire; if unsharedDate is null then a non-expiring link is created. | Date
| deleteFolder | *folderId* |  The id of folder to delete | String
| getFolder | *path* |  Sequence of Box folder names from root folder to returned folder | String[]
| getFolderInfo | *fields* | *Optional*  The information fields to retrieve; if null all information fields are retrieved. | String[]
| getFolderInfo | *folderId* |  The id of folder | String
| getFolderItems | *fields* | *Optional*  The item fields to retrieve for each child item; if null all item fields are retrieved. | String[]
| getFolderItems | *folderId* |  The id of folder | String
| getFolderItems | *limit* | *Optional*  The maximum number of children to retrieve after the offset; if null all child items are retrieved. | Long
| getFolderItems | *offset* | *Optional*  The index of first child item to retrieve; if null all child items are retrieved. | Long
| moveFolder | *destinationFolderId* |  The id of the destination folder | String
| moveFolder | *folderId* |  The id of folder to move | String
| moveFolder | *newName* | *Optional*  The new name of moved folder; if newName is null, the moved folder has same name as the original. | String
| renameFolder | *folderId* |  The id of folder to rename | String
| renameFolder | *newFolderName* |  The new name of folder | String
| updateFolderInfo | *folderId* |  The id of folder to update | String
| updateFolderInfo | *info* |  The updated information | Info
|===

In addition to the parameters above, the folders API can also use from the 20 endpoint query option
which is listed in the _Query Parameters_ section.

Any of the parameters can be provided in either the endpoint URI, or dynamically in a message header.
The message header name must be of the format `CamelBox.parameter`.
The `inBody` parameter overrides message header, i.e. the endpoint parameter `inBody=myParameterNameHere`
would override a `CamelBox.myParameterNameHere` header.



==== API: groups

*Only producer is supported*




The groups API has 9 method(s) which is represented by the following method signatures
(an API method may have multiple signatures due to overloading):

[source,java]
----

com.box.sdk.BoxGroupMembership addGroupMembership(String groupId, String userId, com.box.sdk.BoxGroupMembership.Role role);

com.box.sdk.BoxGroup createGroup(String name, String provenance, String externalSyncIdentifier, String description, String invitabilityLevel, String memberViewabilityLevel);

void deleteGroup(String groupId);

void deleteGroupMembership(String groupMembershipId);

com.box.sdk.BoxGroup.Info getGroupInfo(String groupId);

com.box.sdk.BoxGroupMembership.Info getGroupMembershipInfo(String groupMembershipId);

java.util.Collection<com.box.sdk.BoxGroupMembership.Info> getGroupMemberships(String groupId);

com.box.sdk.BoxGroup updateGroupInfo(String groupId, com.box.sdk.BoxGroup.Info groupInfo);

com.box.sdk.BoxGroupMembership updateGroupMembershipInfo(String groupMembershipId, com.box.sdk.BoxGroupMembership.Info info);

----

The groups API is defined in the syntax as follows:

----
box:groups/methodName?[parameters]
----

The 9 method(s) is listed in the table below.
(API methods can have a shorthand alias name which can be used in the syntax instead of the name)

[width="100%",cols="2,2,6",options="header"]
|===
| Method | Alias | Description
| *addGroupMembership* | addMembership | Add a member to group with the specified role
| *createGroup* | create | Create a new group with a specified name and optional additional parameters
| *deleteGroup* | delete | Delete group
| *deleteGroupMembership* | deleteMembership | Delete group membership
| *getGroupInfo* | info | Get group information
| *getGroupMembershipInfo* | membershipInfo | Get group membership information
| *getGroupMemberships* | memberships | Get information about all of the group memberships for this group
| *updateGroupInfo* |  | Update group information
| *updateGroupMembershipInfo* | updateMembershipInfo | Update group membership information
|===

The groups API method(s) has the following set of parameters listed in the table below:
[width="100%",cols="2,2,4,2",options="header"]
|===
| Method | Parameter | Description | Type
| addGroupMembership | *groupId* |  The id of group | String
| addGroupMembership | *role* | *Optional*  The role of the user in this group. Can be null to assign the default role. | Role
| addGroupMembership | *userId* |  The id of user to be added to group | String
| createGroup | *description* | *Optional*  The description of the new group | String
| createGroup | *externalSyncIdentifier* | *Optional*  The external_sync_identifier of the new group | String
| createGroup | *invitabilityLevel* | *Optional*  The invitibility_level of the new group | String
| createGroup | *memberViewabilityLevel* | *Optional*  The member_viewability_level of the new group | String
| createGroup | *name* |  The name of the new group | String
| createGroup | *provenance* | *Optional*  The provenance of the new group | String
| deleteGroup | *groupId* |  The id of group to delete | String
| deleteGroupMembership | *groupMembershipId* |  The id of group membership to delete | String
| getGroupInfo | *groupId* |  The id of group | String
| getGroupMembershipInfo | *groupMembershipId* |  The id of group membership | String
| getGroupMemberships | *groupId* |  The id of group | String
| updateGroupInfo | *groupId* |  The id of group to update | String
| updateGroupInfo | *groupInfo* |  The updated information | Info
| updateGroupMembershipInfo | *groupMembershipId* |  The id of group membership to update | String
| updateGroupMembershipInfo | *info* |  The updated information | Info
|===

In addition to the parameters above, the groups API can also use from the 20 endpoint query option
which is listed in the _Query Parameters_ section.

Any of the parameters can be provided in either the endpoint URI, or dynamically in a message header.
The message header name must be of the format `CamelBox.parameter`.
The `inBody` parameter overrides message header, i.e. the endpoint parameter `inBody=myParameterNameHere`
would override a `CamelBox.myParameterNameHere` header.



==== API: search

*Only producer is supported*




The search API has 1 method(s) which is represented by the following method signatures
(an API method may have multiple signatures due to overloading):

[source,java]
----

java.util.Collection<com.box.sdk.BoxItem> searchFolder(String folderId, String query);

----

The search API is defined in the syntax as follows:

----
box:search/methodName?[parameters]
----

The 1 method(s) is listed in the table below.
(API methods can have a shorthand alias name which can be used in the syntax instead of the name)

[width="100%",cols="2,2,6",options="header"]
|===
| Method | Alias | Description
| *searchFolder* | search | Search folder and all descendant folders using the given query
|===

The search API method(s) has the following set of parameters listed in the table below:
[width="100%",cols="2,2,4,2",options="header"]
|===
| Method | Parameter | Description | Type
| searchFolder | *folderId* |  The id of folder searched | String
| searchFolder | *query* |  The search query | String
|===

In addition to the parameters above, the search API can also use from the 20 endpoint query option
which is listed in the _Query Parameters_ section.

Any of the parameters can be provided in either the endpoint URI, or dynamically in a message header.
The message header name must be of the format `CamelBox.parameter`.
The `inBody` parameter overrides message header, i.e. the endpoint parameter `inBody=myParameterNameHere`
would override a `CamelBox.myParameterNameHere` header.



==== API: tasks

*Only producer is supported*




The tasks API has 9 method(s) which is represented by the following method signatures
(an API method may have multiple signatures due to overloading):

[source,java]
----

com.box.sdk.BoxTask addAssignmentToTask(String taskId, com.box.sdk.BoxUser assignTo);

com.box.sdk.BoxTask addFileTask(String fileId, com.box.sdk.BoxTask.Action action, java.util.Date dueAt, String message);

void deleteTask(String taskId);

void deleteTaskAssignment(String taskAssignmentId);

java.util.List<com.box.sdk.BoxTask.Info> getFileTasks(String fileId);

com.box.sdk.BoxTaskAssignment.Info getTaskAssignmentInfo(String taskAssignmentId);

java.util.List<com.box.sdk.BoxTaskAssignment.Info> getTaskAssignments(String taskId);

com.box.sdk.BoxTask.Info getTaskInfo(String taskId);

com.box.sdk.BoxTask updateTaskInfo(String taskId, com.box.sdk.BoxTask.Info info);

----

The tasks API is defined in the syntax as follows:

----
box:tasks/methodName?[parameters]
----

The 9 method(s) is listed in the table below.
(API methods can have a shorthand alias name which can be used in the syntax instead of the name)

[width="100%",cols="2,2,6",options="header"]
|===
| Method | Alias | Description
| *addAssignmentToTask* | addAssignment | Add assignment for task
| *addFileTask* | add | Add task to file
| *deleteTask* | delete | Delete task
| *deleteTaskAssignment* | deleteAssignment | Delete task assignment
| *getFileTasks* | tasks | Get a list of any tasks on file
| *getTaskAssignmentInfo* | assignmentInfo | Get task assignment information
| *getTaskAssignments* | assignments | Get a list of any assignments for task
| *getTaskInfo* | info | Get task information
| *updateTaskInfo* | updateInfo | Update task information
|===

The tasks API method(s) has the following set of parameters listed in the table below:
[width="100%",cols="2,2,4,2",options="header"]
|===
| Method | Parameter | Description | Type
| addAssignmentToTask | *assignTo* |  The user to assign to task | BoxUser
| addAssignmentToTask | *taskId* |  The id of task to add assignment for | String
| addFileTask | *action* |  The action the task assignee will be prompted to do | Action
| addFileTask | *dueAt* |  The day at which this task is due | Date
| addFileTask | *fileId* |  The id of file to add task to | String
| addFileTask | *message* | *Optional*  An optional message to include with the task | String
| deleteTask | *taskId* |  The id of task to delete | String
| deleteTaskAssignment | *taskAssignmentId* |  The id of task assignment to delete | String
| getFileTasks | *fileId* |  The id of file | String
| getTaskAssignmentInfo | *taskAssignmentId* |  The id of task assignment | String
| getTaskAssignments | *taskId* |  The id of task | String
| getTaskInfo | *taskId* |  The id of task | String
| updateTaskInfo | *info* |  The updated information | Info
| updateTaskInfo | *taskId* |  The id of task | String
|===

In addition to the parameters above, the tasks API can also use from the 20 endpoint query option
which is listed in the _Query Parameters_ section.

Any of the parameters can be provided in either the endpoint URI, or dynamically in a message header.
The message header name must be of the format `CamelBox.parameter`.
The `inBody` parameter overrides message header, i.e. the endpoint parameter `inBody=myParameterNameHere`
would override a `CamelBox.myParameterNameHere` header.



==== API: users

*Only producer is supported*




The users API has 10 method(s) which is represented by the following method signatures
(an API method may have multiple signatures due to overloading):

[source,java]
----

com.box.sdk.EmailAlias addUserEmailAlias(String userId, String email);

com.box.sdk.BoxUser createAppUser(String name, com.box.sdk.CreateUserParams params);

com.box.sdk.BoxUser createEnterpriseUser(String login, String name, com.box.sdk.CreateUserParams params);

void deleteUser(String userId, boolean notifyUser, boolean force);

void deleteUserEmailAlias(String userId, String emailAliasId);

java.util.List<com.box.sdk.BoxUser.Info> getAllEnterpriseOrExternalUsers(String filterTerm, String[] fields);

java.util.Collection<com.box.sdk.EmailAlias> getUserEmailAlias(String userId);

com.box.sdk.BoxUser.Info getUserInfo(String userId);

com.box.sdk.BoxFolder.Info moveFolderToUser(String userId, String sourceUserId);

com.box.sdk.BoxUser updateUserInfo(String userId, com.box.sdk.BoxUser.Info info);

----

The users API is defined in the syntax as follows:

----
box:users/methodName?[parameters]
----

The 10 method(s) is listed in the table below.
(API methods can have a shorthand alias name which can be used in the syntax instead of the name)

[width="100%",cols="2,2,6",options="header"]
|===
| Method | Alias | Description
| *addUserEmailAlias* | addEmailAlias | Add a new email alias to user's account
| *createAppUser* | create | Provision a new app user in an enterprise with additional user information using Box Developer Edition
| *createEnterpriseUser* | create | Provision a new user in an enterprise with additional user information
| *deleteUser* | delete | Delete user from an enterprise account
| *deleteUserEmailAlias* | deleteEmailAlias | Delete an email alias from user's account
| *getAllEnterpriseOrExternalUsers* | users | Get any managed users that match the filter term as well as any external users that match the filter term
| *getUserEmailAlias* | emailAlias | Get a collection of all the email aliases for user
| *getUserInfo* | info | Get user information
| *moveFolderToUser* |  | Move root folder for specified user to current user
| *updateUserInfo* | updateInfo | Update user information
|===

The users API method(s) has the following set of parameters listed in the table below:
[width="100%",cols="2,2,4,2",options="header"]
|===
| Method | Parameter | Description | Type
| addUserEmailAlias | *email* |  The email address to add as an alias | String
| addUserEmailAlias | *userId* |  The id of user | String
| createAppUser | *name* |  The name of the user | String
| createAppUser | *params* | *Optional*  Additional user information | CreateUserParams
| createEnterpriseUser | *login* |  The email address the user will use to login | String
| createEnterpriseUser | *name* |  The name of the user | String
| createEnterpriseUser | *params* | *Optional*  Additional user information | CreateUserParams
| deleteUser | *force* |  Whether or not this user should be deleted even if they still own files | Boolean
| deleteUser | *notifyUser* |  Whether or not to send an email notification to the user that their account has been deleted | Boolean
| deleteUser | *userId* |  The id of user to delete | String
| deleteUserEmailAlias | *emailAliasId* |  The id of the email alias to delete | String
| deleteUserEmailAlias | *userId* |  The id of user | String
| getAllEnterpriseOrExternalUsers | *fields* | *Optional*  The fields to retrieve. Leave this out for the standard fields. | String[]
| getAllEnterpriseOrExternalUsers | *filterTerm* | *Optional*  The filter term to lookup users by (login for external, login or name for managed); if null all managed users are returned. | String
| getUserEmailAlias | *userId* |  The id of user | String
| getUserInfo | *userId* |  The id of user | String
| moveFolderToUser | *sourceUserId* |  The user id of the user whose files will be the source for this operation | String
| moveFolderToUser | *userId* |  The id of user | String
| updateUserInfo | *info* |  The updated information | Info
| updateUserInfo | *userId* |  The id of user to update | String
|===

In addition to the parameters above, the users API can also use from the 20 endpoint query option
which is listed in the _Query Parameters_ section.

Any of the parameters can be provided in either the endpoint URI, or dynamically in a message header.
The message header name must be of the format `CamelBox.parameter`.
The `inBody` parameter overrides message header, i.e. the endpoint parameter `inBody=myParameterNameHere`
would override a `CamelBox.myParameterNameHere` header.
// endpoint options: END

== Samples

The following route uploads new files to the user's root folder:

[source,java]
----
from("file:...")
    .to("box://files/upload/inBody=fileUploadRequest");
----

The following route polls user's account for updates:

[source,java]
----
from("box://events/listen?startingPosition=-1")
    .to("bean:blah");
----

The following route uses a producer with dynamic header options. The
*fileId* property has the Box file id and the *output* property has 
the output stream of the file contents, so they are assigned to the
*CamelBox.fileId* header and *CamelBox.output* header respectively
as follows:

[source,java]
----
from("direct:foo")
    .setHeader("CamelBox.fileId", header("fileId"))
    .setHeader("CamelBox.output", header("output"))
    .to("box://files/download")
    .to("file://...");
----

=== More information

See more details at the Box API reference: https://developer.box.com/reference

include::camel-spring-boot::page$box-starter.adoc[]
