Working with Files in Box

Overview

The following operations allow you to work with files. Click an operation name to see details on how to use it.

For a sample proxy service that illustrates how to work with files, see Sample configuration.

Operation	Description
copyFile	Creates a copy of a file.
deleteFile	Discards a file.
downloadFile	Downloads a file.
getFileInformation	Retrieves file information.
listFileComments	Views a comment on a file.
shareFile	Creates a share link for a file.
updateFileInformation	Updates a file's information.
uploadFile	Uploads a file.

Operation details

This section provides details on each of the operations.

Copying a file

The copyFile operation allows you to create a copy of a file in another folder. The original version will not be altered.

copyFile

<box.copyFile>
	<fileId>{$ctx:fileId}</fileId>
    <name>{$ctx:name}</name>
    <parentId>{$ctx:parentId}</parentId>
</box.copyFile>

Properties

fileId: The file ID.
name: Optional - A new name for the file.
parentId: The ID of the parent folder, representing the new location of the file.

Sample request

Following is a sample REST request that can be handled by the copyFile operation.

Sample Request for copyFile

{
	"apiUrl":"https://api.box.com",
	"accessToken":"7EzlbaraGUYAdMCdfgZSJJZ5OdGRET2HVmT",
	"fileId":"16526877339",
	"parentId":"1879662173",
	"fields":"name"
}

Deleting a file

The deleteFile operation discards a file to trash.

deleteFile

<box.deleteFile>
	<fileId>{$ctx:fileId}</fileId>
	<ifMatch>{$ctx:ifMatch}</ifMatch>
</box.deleteFile>

Properties

fileId: Required - The file ID.
ifMatch: The ETag of the file, which is in the etag field of the file object.

Sample request

Following is a sample REST request that can be handled by the deleteFile operation.

Sample Request for deleteFile

{
	"apiUrl":"https://api.box.com",
	"accessToken":"dwIobgipf7S1YyyYjBdfgTFHuTnexfIhzz7l",
	"fileId":"16525795097"
}

Downloading a file

The downloadFile operation retrieves the actual data of the file. A previous version of a file can be downloaded by setting the optional version parameter.

downloadFile

<box.downloadFile>
	<fileId>{$ctx:fileId}</fileId>
    <version>{$ctx:version}</version>
</box.downloadFile>

Properties

fileId: Required - ID of the file to be downloaded.
version: Optional - The specific version of this file to download.

Sample request

Following is a sample REST request that can be handled by the downloadFile operation.

Sample Request for downloadFile

{
	"apiUrl":"https://api.box.com",
	"accessToken":"Q3ajlCrUEgkwC6legdfgh9rpXaRxnAK79dSSz",
	"fileId":"16809645379",
	"version":"A"
}

Retrieving file information

The getFileInformation operation retrieves the metadata for a file.

getFileInformation

<box.getFileInformation>
	<fileId>{$ctx:fileId}</fileId>
</box.getFileInformation>

Properties

fileId: Required- The ID of the file.

Sample request

Following is a sample REST request that can be handled by the getFileInformation operation.

Sample Request for getFileInformation

{
	"apiUrl":"https://api.box.com",
	"accessToken":"G0P4x7Ky6aJF38fglbghL0QADJBZbcTs6b1f",
	"fileId":"16526877339"
}

Viewing comments on a file

The listFileComments operation retrieves the comments (if any) on a particular file.

listFileComments

<box.listFileComments>
	<fileId>{$ctx:fileId}</fileId>
</box.listFileComments>

Properties

fileId: Required - The ID of the file whose comments you want to retrieve.

Sample request

Following is a sample REST request that can be handled by the listFileComments operation.

Sample Request for listFileComments

{
	"apiUrl":"https://api.box.com",
	"accessToken":"z2DFrWYYWd5StrNfgBYhf6uo6faInDMTZAbY",
	"fileId":"16840808555",
	"fields":"message"
}

Sharing a file

The shareFile operation is used to create a shared link for this particular file. Click here for more information on the permissions available for shared links. Note that currently you cannot edit passwords for shared links.

To get default shared link status, set it to an empty access level: {"shared_link": {}}

To disable a shared link, send this same type of PUT request with the value of shared_link set to null: {"shared_link": null}

shareFile

<box.shareFile>
	<sharedLink>{$ctx:sharedLink}</sharedLink>
    <fileId>{$ctx:fileId}</fileId>
</box.shareFile>

Properties

sharedLink: An object representing an item’s shared link and associated permissions. It contains the following content:
- access: The level of access required for this shared link. Can be open, company, collaborators, or {} to get the default share level.
- unshared_at: The day on which this link should be disabled. Timestamps are rounded off to the given day. This field can only be set if the user is not a free user.
- permissions: The set of permissions that apply to this link.
  - can_download: Specifies whether this link allows downloads. Valid values: open or company
  - can_preview: Specifies whether this link allows previewing. Valid values: open or company
fileId: The file ID.

Sample request

Following is a sample REST request that can be handled by the shareFile operation.

Sample Request for shareFile

{
	"apiUrl":"https://api.box.com",
	"accessToken":"HrpjqZNB4Mgsx7ZtMBfgjghfdor4HTyKDUdsNR",
	"fileId":"16526877339",
	"sharedLink":{"access": "open",
			"permissions":{"can_download":false}}
}

Updating a file's information

The updateFileInformation operation allows you to update individual or multiple fields in the file object, such as renaming the file, changing its description, and creating a shared link for the file. To move a file, change the ID of its parent folder. An optional If-Match header can be included to ensure that the client only updates the file if it knows about the latest version.

updateFileInformation

<box.updateFileInformation>
	<tags>{$ctx:tags}</tags>
    <fileId>{$ctx:fileId}</fileId>
    <sharedLink>{$ctx:sharedLink}</sharedLink>
    <description>{$ctx:description}</description>
    <name>{$ctx:name}</name>
    <parentId>{$ctx:parentId}</parentId>
    <ifMatch>{$ctx:ifMatch}</ifMatch>
</box.updateFileInformation>

Properties

tags: All tags attached to this file. To add/remove a tag to/from a file, you can first get the file’s current tags (be sure to specify ?fields=tags, since the tags field is not returned by default), modify the list as required, and then set the file’s entire list of tags.
fileId: The file's ID.
sharedLink: An object representing this item’s shared link and associated permissions.
description: The new description for the file.
name: The new name for the file.
parentId: The ID of the file's parent folder.
ifMatch: the etag field of the file object.

Sample request

Following is a sample REST request that can be handled by the updateFileInformation operation.

Sample Request for updateFileInformation

{
	"apiUrl":"https://api.box.com",
	"accessToken":"HrpjqZNB4Mgsx7ZtMfgjfghBdor4HTyKDUdsNR",
	"fileId":"16526877339",
	"name":"updated file"
}

Uploading a file

The uploadFile operation allows users to add a new file. The user can then upload a file by specifying the destination folder for the file. If the user provides a file name that already exists in the destination folder, the user will receive an error.

A different Box URL, https://upload.box.com/api/2.0/files/content, handles uploads. This API uses the multipart post method to complete all upload tasks. You can optionally specify a Content-MD5 header with the SHA1 hash of the file to ensure that the file is not corrupted in transit.

Multipart Processing

Multipart/form-data cannot be processed inside the ESB. Therefore, the ESB should be in a content-unaware status. To achieve this, configure a pass-through proxy, and then build the message from the client end and send it to the proxy. Because you are constructing the endpoint inside the proxy, you do not need to call init for multipart operations.

uploadFile

<?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns="http://ws.apache.org/ns/synapse"
       name="box_uploadFile"
       transports="https,http"
       statistics="disable"
       trace="disable"
       startOnLoad="true">
   <target>
       <inSequence onError="faultHandlerSeq">
         <box.uploadFile>
            <apiUrl>https://upload.box.com</apiUrl>
            <fields>{$url:fields}</fields>
         </box.uploadFile>
         <respond/>
      </inSequence>
      <outSequence>
        <send/>
      </outSequence>
   </target>
   <description/>
</proxy>

Properties

apiUrl: The URL of the Box API. If not provided, it is set to "https://api.box.com"
fields: The fields to include.

Sample request

Following is a sample REST request that can be handled by the uploadFile operation.

Sample Request for uploadFile

 curl http://localhost:8280/services/box_uploadFile?fields=id,name \
-H "Authorization: Bearer ACCESS_TOKEN" \
-F filename=@FILE_NAME \
-F parent_id=PARENT_FOLDER_ID

Sample configuration

Following is a sample proxy service that illustrates how to connect to Box with the init operation and use the copyFile operation. The sample request for this proxy can be found in copyFile sample request. You can use this sample as a template for using other operations in this category.

As a best practice, create a separate sequence for handling the response payload for errors. In the following sample, this sequence is "faultHandlerSeq". For more information, see Configuring the Box Fault Handler Sequence.

Sample Proxy

<?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns="http://ws.apache.org/ns/synapse" name="box_copyFile" transports="https,http" statistics="disable" trace="disable" startOnLoad="true">
  <target>
     <inSequence onError="faultHandlerSeq">
      <property name="apiUrl" expression="json-eval($.apiUrl)"/>
      <property name="accessToken" expression="json-eval($.accessToken)"/>
      <property name="fileId" expression="json-eval($.fileId)"/>
	  <property name="name" expression="json-eval($.name)"/>
      <property name="parentId" expression="json-eval($.parentId)"/>
	  <property name="fields" expression="json-eval($.fields)"/>	  
	  <box.init>
	  <accessToken>{$ctx:accessToken}</accessToken>
	  <apiUrl>{$ctx:apiUrl}</apiUrl>
	  <fields>{$ctx:fields}</fields>
	  </box.init>	  
      <box.copyFile>
        <fileId>{$ctx:fileId}</fileId>
        <name>{$ctx:name}</name>
        <parentId>{$ctx:parentId}</parentId>
      </box.copyFile>  
	  <respond></respond>
    </inSequence>
    <outSequence>
     <send></send>
    </outSequence>
  </target>
</proxy>

WSO2 ESB Connectors Documentation

Working with Files in Box

Overview

Operation details

Copying a file

Properties

Sample request

Related Box documentation

Deleting a file

Properties

Sample request

Related Box documentation

Downloading a file

Properties

Sample request

Related Box documentation

Retrieving file information

Properties

Sample request

Related Box documentation

Viewing comments on a file

Properties

Sample request

Related Box documentation

Sharing a file

Properties

Sample request

Related Box documentation

Updating a file's information

Properties

Sample request

Related Box documentation

Uploading a file

Properties

Sample request

Related Box documentation

Sample configuration