= Box Component
:doctitle: Box
:shortname: box
:artifactid: camel-box
:description: Upload, download and manage files, folders, groups, collaborations, etc. on box.com.
:since: 2.14
:supportlevel: Stable
:tabs-sync-option:
:component-header: Both producer and consumer are supported
//Manually maintained attributes
:camel-spring-boot-name: box

*Since Camel {since}*

*{component-header}*

The Box component provides access to all the Box.com APIs accessible
using https://github.com/box/box-java-sdk/[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
authentications. 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>
----

// component options: START
include::partial$component-configure-options.adoc[]
include::partial$component-endpoint-options.adoc[]
include::partial$component-endpoint-headers.adoc[]
// component options: END

[NOTE]
====
This is an API-based component, so per-call parameters can be supplied through `Camel`-prefixed
exchange headers in addition to the endpoint options. If the route consumes messages from untrusted
producers, strip these internal headers at the trust boundary -- for example with
`removeHeaders("Camel*")` -- before the message reaches this component, so that a sender cannot
override the API call. See xref:manual::security-model.adoc[the Camel security model] for details.
====

== Usage

=== 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.

== Examples

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::spring-boot:partial$starter.adoc[]
