Working with Folders in Box

Overview

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

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

Operation details

This section provides details on each of the operations.

 Copying a folder

The copyFolder operation creates a copy of a folder in another folder. The original version of the folder will remain as it is.

<box.copyFolder>
	<name>{$ctx:name}</name>
    <parentId>{$ctx:parentId}</parentId>
    <folderId>{$ctx:folderId}</folderId>
</box.copyFolder>

Properties

• name: Optional - New name for the folder.
• parentId: Required - The ID of the parent folder where this folder will be copied.
• folderId: Required - The ID of the folder to be copied.

Sample request

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

{
	"apiUrl":"https://api.box.com",
	"accessToken":"I8wSCQRps3qwoBrARzffghfy9HmPehSB6r9",
	"folderId":"1883251845",
	"parentId":"1879662173",
	"name":"TestFolder"
}

Related Box documentation

http://developers.box.com/docs/#folders-copy-a-folder

 Creating a new folder

The createFolder operation creates a new empty folder inside the specified parent folder.

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

Properties

• name: Required - The name of the new folder. It supports folder names of 255 characters or less. Names cannot contain non-printable ASCII characters, slashes or backslashes (/ or \), names with leading or trailing spaces, or the special names “.” and “..”.
• parentId: Required - ID of the parent folder where the new folder will be created.

Sample request

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

{
	"apiUrl":"https://api.box.com",
	"accessToken":"j4s7JVmm2OXadsGXpmxsdfCXaTEJbP0ZKEB",
	"name":"newFolder",
	"parentId":"0"
}

Related Box documentation

http://developers.box.com/docs/#folders-create-a-new-folder

 Deleting a folder

The deleteFolder operation deletes a folder. You use the recursive parameter to specify whether to delete folders that are not empty. You can include the optional If-Match header to delete the folder only if it knows about the latest version.

<box.deleteFolder>
	<recursive>{$ctx:recursive}</recursive>
    <ifMatch>{$ctx:ifMatch}</ifMatch>
    <folderId>{$ctx:folderId}</folderId>
</box.deleteFolder>

Properties

• recursive: Specifies whether to delete this folder if it has items inside it.
• ifMatch: This is in the "etag" field of the folder object.
• folderId: Required- The ID of the folder to delete.

Sample request

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

{
	"apiUrl":"https://api.box.com",
	"accessToken":"DP8puyb45zQMvcDftXhsdfyMZU0g0LVV8jy",
	"folderId":"1918855767",
	"ifMatch":"0",
	"recursive":"true"
}

Related Box documentation

http://developers.box.com/docs/#folders-delete-a-folder

 Retrieving folder information

The getFolderInformation operation retrieves the full metadata about a folder such as information about when it was last updated as well as the files and folders contained in it. The root folder of a Box account is always represented by the ID “0″.

<box.getFolderInformation>
	<folderId>{$ctx:folderId}</folderId>
</box.getFolderInformation>

Properties

• folderId: Required - The folder ID.

Sample request

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

{
	"apiUrl":"https://api.box.com",
	"accessToken":"j4s7JVmm2OXadsGXpmxCXaTEJbP0ZKEB",
	"folderId":"1878741077"
}

Related Box documentation

http://developers.box.com/docs/#folders-get-information-about-a-folder

 Sharing a folder

The shareFolder operation creates a shared link for the specified folder. Click here for more information on the permissions available for shared links. Note that you cannot edit passwords with this operation. To disable a shared link, send this same type of PUT request with the value of shared_link set to null: {"shared_link": null}

<box.shareFolder>
	<sharedLink>{$ctx:sharedLink}</sharedLink>
    <folderId>{$ctx:folderId}</folderId>
</box.shareFolder>

Properties

• sharedLink: An object representing the item’s shared link and associated permissions. It contains the following content:
  • access: The level of access required for this shared link. Valid values are 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 are open and company.
      • can_preview: Specifies whether this link allows previewing. Valid values are open and company.
• folderId: Required - The ID of the folder you want to share.

Sample request

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

{
	"apiUrl":"https://api.box.com",
	"accessToken":"HrpjqZNB4Mgsx7ZtMBdor4HTysdfKDUdsNR",
	"folderId":"1879662173",
	"sharedLink":{"access": "open",
				"permissions":{"can_download":false}}
}

Related Box documentation

http://developers.box.com/docs/#folders-create-a-shared-link-for-a-folder

 Updating folder information

The updateFolderInformation operation is 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 folderUploadEmailAddress property. You can include the optional If-Match header to ensure that the client updates the folder only if it knows about the latest version. Note that the root folder (0) cannot be updated, and editing of passwords is currently not supported for shared links.

<box.updateFolderInformation>
	<tags>{$ctx:tags}</tags>
    <folderUploadEmailAccess>{$ctx:folderUploadEmailAccess}</folderUploadEmailAccess>
    <sharedLink>{$ctx:sharedLink}</sharedLink>
    <syncState>{$ctx:syncState}</syncState>
    <description>{$ctx:description}</description>
    <name>{$ctx:name}</name>
    <parentId>{$ctx:parentId}</parentId>
    <ownedById>{$ctx:ownedById}</ownedById>
    <ifMatch>{$ctx:ifMatch}</ifMatch>
    <folderId>{$ctx:folderId}</folderId>
</box.updateFolderInformation>

Properties

• tags: The tags attached to this folder. To add/remove a tag to/from a folder, you can first get the folder’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 folder’s entire list of tags using this property.
• folderUploadEmailAccess: The email address where people can send files to upload them to this folder. 
• sharedLink: An object representing this item’s shared link and associated permissions. Click here for more information on the parameters that you can send with this object.
• syncState: Specifies whether Box Sync clients will sync this folder. Valid values are synced and not_synced.
• description: The description of the folder.
• name: The name of the folder.
• parentId: The ID of the parent folder.
• ownedById: The ID of the owner, which should be the user's ID. 
• ifMatch: The "etag" field of the folder object.
• folderId: Required - The folder ID.

Sample request

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

{
	"apiUrl":"https://api.box.com",
	"accessToken":"wfLnGgK6dIOwCsqf6Oi8cNusdf7QhVOqlWw",
	"folderId":"1918973727",
	"name":"updated test",
	"folderUploadEmailAccess":"",
	"ownedById":""
}

Related Box documentation

http://developers.box.com/docs/#folders-update-information-about-a-folder

Sample configuration

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

<?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns="http://ws.apache.org/ns/synapse"
       name="box_copyFolder"
       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="fields" expression="json-eval($.fields)"/>
         <property name="folderId" expression="json-eval($.folderId)"/>
         <property name="name" expression="json-eval($.name)"/>
         <property name="parentId" expression="json-eval($.parentId)"/>
         <box.init>
            <accessToken>{$ctx:accessToken}</accessToken>
            <apiUrl>{$ctx:apiUrl}</apiUrl>
            <fields>{$ctx:fields}</fields>
         </box.init>
         <box.copyFolder>
            <name>{$ctx:name}</name>
            <parentId>{$ctx:parentId}</parentId>
            <folderId>{$ctx:folderId}</folderId>
         </box.copyFolder>
         <property name="messageType" value="application/json" scope="axis2"/>
         <filter source="$axis2:HTTP_SC" regex="^[^2][0-9][0-9]">
            <then>
               <property name="ERROR_CODE" expression="$axis2:HTTP_SC"/>
               <switch source="$axis2:HTTP_SC">
                  <case regex="401">
                     <property name="ERROR_MESSAGE" value="Unauthorized"/>
                     <property name="error_description" expression="json-eval($.message)"/>
                     <sequence key="faultHandlerSeq"/>
                  </case>
               </switch>
            </then>
         </filter>
         <respond/>
      </inSequence>
      <outSequence>
        <send/>
      </outSequence>
   </target>
   <description/>
</proxy>