Box for Salesforce: Developer Toolkit

Follow

·

Get Training

The Box for Salesforce Developer Toolkit allows customers to programatically customize the behavior of the Box for Salesforce integration. The Toolkit consists of several global APEX methods that can be used to trigger and extend the default behavior. The global methods update the internal record mapping and handle permission management.

Note: This functionality is part of the latest Box for Salesforce package.

What the Toolkit does NOT provide
The Toolkit is not a full-featured APEX wrapper for the BOX Content API. If this is what you are looking for, have a look at the Community APEX SDK written by Daniel Hoechst.

 

Authentication

A solution for simple Authentication: 

  • Allow API calls to user the service user credentials. 
    • This means Salesforce Admins need to restrict access to the Toolkit global APEX class.
    • Toolkit methods that take accessToken as a parameter can use the service user credentials by sending null for the accessToken value.
    • If a value is passed in accessToken, the API call to Box will be done with the access token sent. It is up to the developer to ensure the token being passed is valid and the user associated with the token has permissions to execute the operation requested.
  • Developers have a simple way to authenticate an account and user\the credentials to make API calls through the Toolkit. 

Toolkit Details

Class Name: box.Toolkit

Instance Variables

mostRecentError

  • String to indicate the most recent error that occurred when calling instance methods.
  • The presence of this string does not mean the operation failed. It is possible the error was recoverable; however, the lack of a value in this string does indicate the operation was successful.

Enum CollaborationType

  • Enum to indicate the type of collaboration.
  • Values: EDITOR, VIEWER, PREVIEWER, UPLOADER, COOWNER, OWNER, PREVIEWERUPLOADER, VIEWERUPLOADER

Static Methods

deleteServiceUserAssociation

Parameters

None

Returns

  • True if the service account existed and was deleted.
  • False if the service account was not deleted for any reason (including because it didn't exist).

deleteUserAssociation

Parameters

userId

The Id of the user whose credentials are to be cleared.
Type: Id

Returns 

  • True if the user's account existed and was deleted.
  • False if the user's account was not deleted for any reason (including because it didn't exist).

Instance Methods

Constructor/Destructors

box.Toolkit()

Parameters

None

commitChanges

  • Treat this method as a destructor for the box.Toolkit object.
  • This method is critical. It must be called after all folder/collab operations are complete. Every time. No Exceptions.
  • Since Salesforce doesn't allow callouts after database updates/inserts/deletes have occurred, the Toolkit class maintains some collections of objects to be inserted once all callout operations are complete. If this method is not called, those objects won't be in the database, and the tables that keep track of user/record/folder associations will be out of sync and will need some advanced debugging to fix.

Parameters

None

Returns

  • Void

 

File Operations

createFileFromAttachment

Note: Available in version 3.46 and above.

Parameters

att

The attachment to be converted into a File in Box.
Type: Attachment

fileNameOverride

Optional - Name of the new file. If no value is passed in, the name of the attachment is used.
Type: String

folderIdOverride

Optional - Box folder id to place this attachment in. If no value is passed in, the file will be placed in the folder associated with the record that is the parentId of the attachment. If the record-specific folder doesn't exist, it will be created.
Type: String

accessToken

Optional - if accessToken is sent, that value is used for the Box API call. Otherwise, the default account credentials are used.
Type: String

Returns

  • String returned is the id of the Box file that was created.
  • Null if there was an error. In this case, check mostRecentError.

 

getObjectFolderByRecordId 

Parameters

recordId

Salesforce record id whose root folder id you want to get.
Type: Id

Returns 

  • String returned is the Box folder id of the object root folder for the record id passed in.

 

Folder Operations

getRootFolderId

Parameters

None

Returns

  • String returned is the Box folder id of the Salesforce root folder.

getObjectFolderByRecordId 

Parameters

recordId

Salesforce record id whose root folder id you want to get.
Type: Id

Returns 

  • String returned is the Box folder id of the object root folder for the record id passed in.

getFolderUrl

  • This method gets the embed widget URL for a particular record so customers can use their own embed logic if desired.
  • This method respects seamless login settings so the URL will automatically log the user in if seamless login is enabled.

Parameters

recordId

Salesforce record Id you want to get the folder URL for.
Type: Id

isMobileContext

Boolean to indicate whether the URL should be mobile (true) or not (false).
Type: Boolean

Returns 

  • String returned is a URL that points to the folder associated with the Salesforce record Id passed. This URL is for the Box Embed Widget and can be embedded in any Visualforce page.

createObjectFolderForRecordId

Parameters

recordId

Salesforce id of the record you want to create a root folder for.
Type: Id

Returns 

  • String returned is the Box folder Id of the root folder that was created.
  • If the root folder already existed, the value returned is the Box folder id of the root folder that already existed.

createFolder

Parameters

folderName

Name of the folder to be created. Folder names are subject to some restrictions. See https://developers.box.com/docs/#folders-create-a-new-folder for more details.
Type: String

parentFolderId

Parent Box folder this folder will be created in.
Type: String

accessToken

Optional - If accessToken is sent, that value is used for the Box API call. Otherwise, the default service account credentials are used.
Type: String

Returns 

  • String returned is the Box folder id of the folder that was created.
  • null is returned if a folder is not created. In this case, check mostRecentError for details.

createFolderForRecordId

Parameters

recordId

Salesforce record id that a Box folder will be created for.
Type: Id

folderNameOverride

By default, the record's name will be the folder name. If you want to name it something else, send that value here.
Type: String

optCreateRootFolder

Boolean to indicate whether to create the object root folder if it doesn't exist. If false is sent and the root folder does not exist, the call will fail.
Type: Boolean

Returns 

  • String returned is the Box folder id of the folder that was created.
  • null is returned if a folder is not created. In this case, check mostRecentError for details.
  • If the Salesforce record was already associated with a Box folder, the existing Box folder id is returned.

moveFolder

Parameters

folderId

Box folder Id of the folder to be moved.
Type: String

 newParentFolderId

Box folder Id of the folder that will be the new parent folder.
Type: String

 accessToken

Optional - If accessToken is sent, that value is used for the Box API call. Otherwise, the default service account credentials are used.
Type: String

Returns

  • True if the folder was moved successfully.
  • False if the folder was not moved successfully. Check mostRecentError for details.

 

Folder Association Methods

getFolderAssociationsByRecordId

Parameters

recordId

Salesforce record id that the folder mapping entries returned are related to.
Type: Id

Returns 

  • List returned is a collection of all folder mapping entries associated with this record. 
  • Generally, it will be an empty list if no folder mapping entries exist, but under some circumstances, it could be null.

getFolderIdByRecordId

Parameters

recordId

Salesforce record id whose folder id you wish to get.
Type: Id

Returns 

  • String returned is the Box folder id associated with the Salesforce record id passed in.

getRecordIdByFolderId

Parameters

folderId

Box folder id.
Type: String

Returns 

  • Id returned is the salesforce record id associated with the Box folder id passed in.

createFolderAssociation

Parameters

recordId

Salesforce record Id that is being associated with a box folder.
Type: Id

folderId

Box folder Id being associated with a Salesforce record.
Type: String

Returns 

  • box__FRUP__c object - The FRUP object returned will be null if there was an error (check mostRecentError).  Upon calling the commitChanges method, this FRUP entry will be inserted into the database. 
  • This method ensures consistency with other folder associations by not allowing the same folder to be associated with multiple records or vice versa.

 

Collaboration Methods

createCollaboration

Parameters

folderId

Box folder id to create a collaboration on.
Type: String

boxUserId

Box user id to be collaborated (either boxUserId or emailAddress is required but not both).
Type: String

emailAddress

 

Email address of the box user to be.
Type: String

collabType

Type of collaboration (see the CollaborationType enum definition).
Type: box.Toolkit.CollaborationType

accessToken

Optional - If accessToken is sent, that value is used for the Box API call. Otherwise, the default service account credentials are used.
Type: String

Returns 

  • String returned is the id of the box collaboration that was created.
  • Null if there was an error. In this case, check mostRecentError.

createCollaborationOnRecord

Parameters

userId

Salesforce user id to be collaborated.
Type: Id

recordId

Salesforce record id of the record folder to be collaborated on.
Type: Id

collabType

Type of collaboration (see the CollaborationType enum definition).
Type: box.Toolkit.CollaborationType

optCreateFolder

Boolean to indicate whether to create the Box folder associated for the salesforce record id if it does not already exist. This also creates the root folder if it did not already exist. If set to false and the folder does not already exist, the call will fail.
Type: Boolean

Returns 

  • String returned is the id of the Box collaboration that was created.
  • null returned if there was an error. In this case, check mostRecentError.

Code Samples

New Folder Association
Programatic creation and association of a new Box folder to a Salesforce record.

The following code will create a folder for a specific salesforce record Id:

//Instantiate the Toolkit object
box.Toolkit boxToolkit = new box.Toolkit();

//Create a folder and associate it with an account
Id accountId = '001j000000FBozw';
String accountFolderId = boxToolkit.createFolderForRecordId(accountId, null, true);
system.debug('new item folder id: ' + accountFolderId);

//If there was an error, accountFolderId will be null.
// mostRecentError will contain the error message
if(accountFolderId == null) {
system.debug('most recent error: ' + boxToolkit.mostRecentError);
}

//ALWAYS call this method when finished.
//Since salesforce doesn't allow http callouts after dml operations,
// we need to commit the pending database inserts/updates or we will
// lose the associations created
boxToolkit.commitChanges();


Folder Templates
When a new Box folder is created for a given record, a set of sub-folders need to get created.

The following code will create a folder for a record, create subfolders (folder template), and collaborate the current user:


//Instantiate the Toolkit object
box.Toolkit boxToolkit = new box.Toolkit();

//Create a folder and associate it with an account
Id accountId = '001j000000FBozz';
String accountFolderId = boxToolkit.createFolderForRecordId(accountId, null, true);
system.debug('new item folder id: ' + accountFolderId);

//Create two sub-folders in the newly created account folder
String legalFolderId = boxToolkit.createFolder('Legal Documents', accountFolderId, null);
system.debug('Legal Folder id: ' + legalFolderId);

String pictureFolderId = boxToolkit.createFolder('Pictures', accountFolderId, null);
system.debug('Picture Folder id: ' + pictureFolderId);

//Collaborate the current user on the account folder
//Note that we're sending false for the optCreateFolder param
// that shouldn't actually matter since the folder(s) already exists
Id userId = UserInfo.getUserId();
box.Toolkit.CollaborationType collabType = box.Toolkit.CollaborationType.EDITOR;
String collabId = boxToolkit.createCollaborationOnRecord(userId, accountId, collabType, false);
system.debug('new collaboration id: ' + collabId);

//ALWAYS call this method when finished.
//Since salesforce doesn't allow http callouts after dml operations,
// we need to commit the pending database inserts/updates or we will
// lose the associations created
boxToolkit.commitChanges();

 

 

Was this article helpful?
0 out of 0 found this helpful