Methods and Operations

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 did not succeed. 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.

Possible values: EDITOR, VIEWER, PREVIEWER, UPLOADER, COOWNER, OWNER, PREVIEWERUPLOADER, or VIEWERUPLOADER

Static Methods

deleteServiceUserAssociation

Method to clear association between Service Account and Box for Salesforce integration. This can be used to change the service account if an incorrect one is being used.

Parameters:

• None

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

deleteUserAssociation

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 - Constructors, Destructors

box.Toolkit()

Parameters:

• None

commitChanges

Treat this method as a destructor for the box.Toolkit() method.

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

commitChanges with platform event

Treat this method as a destructor for the box.Toolkit() method.

This method is very similar to the commitChanges above. However, it uses a platform event to commit changes to the database to perform DML statements in a different transaction and avoid governor limits in some scenarios.

Returns:

• Void

Generic Methods

The Box for Salesforce Developer Toolkit provides a global method that accepts an HttpRequest object as a parameter and returns an HttpResponse object. This method will utilize the authentication details of the Service Account to make callouts to Box's APIs, allowing you to focus on the business logic of your integration.

sendRequest

Returns:

• An HttpResponse object with the response details from calling Box's APIs.
• Toolkit.BoxApiException if there is any missing information from the HttpRequest input.
• null if there was an issue getting the authentication details for the Service Account. In this case, check mostRecentError.

File Operations

createFileFromAttachment

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

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

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.

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

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

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

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

Returns:

• true if the folder was moved successfully.
• false if the folder was not moved successfully. Check mostRecentError for details.

getUrlForFolder

Returns:

• pageReference object with provided URL.
• null if the parameters are incorrect.

createFolderForRecordIdFromTemplate

Returns:

• Newly created folder Id.
• null if the parameters are incorrect.

Folder Association Methods

getFolderAssociationsByRecordId

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

Returns:

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

getRecordIdByFolderId

Returns:

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

createFolderAssociation

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

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.

createCollaborationOnRecord

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.

editCollaboration

Returns:

• Boolean based on the transaction success.
• false if the parameters are incorrect.

deleteCollaboration

Returns:

• Boolean based on the transaction success.
• false if the parameters are incorrect.

Metadata

getBoxMetadataByFolderId

This method calls the get metadata instance on folder endpoint.

Returns:

• FolderMetadata record associated with this folder, scope, and template key. You can find the custom values in keyValuePairs variable of this object.

• null, if:

  • the parameters are incorrect,
  • access to the folder is missing,
  • metadata cascade policy is not found.

createBoxMetadataByFolderId

This method calls the create metadata instance on folder endpoint.

Returns:

• Newly created FolderMetadata object.

• null, if:

  • the parameters are incorrect,
  • access to the folder is missing,
  • metadata cascade policy is not found.

updateBoxMetadataByFolderId

Calls the update metadata instance on folder endpoint.

Returns:

• Updated FolderMetadata object.

• null, if:

  • the parameters are incorrect,
  • access to the folder is missing,
  • metadata cascade policy is not found.

deleteBoxMetadataFolderId

This method call the delete metadata instance from folder endpoint.

Returns:

• Boolean based on the transaction success.
• false can be returned if parameters are incorrect parameters or metadata is not found.

getMetadataCascadePolicyById

This method calls the get metadata cascade policy from folder endpoint. As it requires an ID, you need to call the getMetadataCascadePoliciesByFolderId method first.

Returns:

• MetadataCascadePolicy object retrieved from Box.

• null, if:

  • the parameters are incorrect,
  • access to the folder is missing,
  • metadata cascade policy is not found.

getMetadataCascadePoliciesByFolderId

This method retrieves the cascade policies by providing a folder ID and calling the get metadata cascade policies endpoint.

Returns:

• List of MetadataCascadePolicy objects retrieved from Box.

• null, if:

  • the parameters are incorrect,
  • access to the folder is missing,
  • metadata cascade policy is not found.

createMetadataCascadePolicy

This method creates cascade policies by providing a Box folder ID, scope, template key, and by calling the post metadata cascade policies endpoint.

Returns:

• Newly generated MetadataCascadePolicy.

• null, if:

  • the parameters are incorrect,
  • access to the folder is missing,
  • metadata cascade policy details are not found.

deleteMetadataCascadePolicy

This method deletes the cascade policies by providing a cascade policy ID and calling the delete metadata cascade policies ID endpoint.

Returns:

• Boolean based on the transaction success.
• false is returned if parameters are incorrect, access to the folder is missing, or the metadata cascade policy is not found.

enableAppActivity

This method enables the given folder for App Activities by applying metadata on the folder and cascading it down.

Returns:

• Boolean based on the transaction success.
• false in case of incorrect parameters.

Salesforce and Slack

getIntegrationMappings

This toolkit method calls the get integration mappings endpoint to get the existing mappings.

Returns:

• A list of IntegrationMapping objects,
• null is returned if there are incorrect parameters, the access is missing, or the integration mappings is not found.

createIntegrationMapping

This toolkit method calls the get integration mappings endpoint to create the mappings.

Returns:

• Boolean based on the transaction success.

deleteIntegrationMapping

This toolkit method calls the delete integration mappings endpoint to delete a mapping.

Returns:

• Boolean based on the transaction success.

mapSfdcRecordToSlackChannel

This toolkit method uses the above integration mapping methods and provides a wrapper with four different use cases:

1. If a mapping does not exist in Salesforce or Slack, it creates a folder under the Box for Salesforce folder structure, and an integration mapping to link it with the Slack channel.
2. If a mapping only exists from Salesforce, it continues to use the folder and does not change the location. Creates an integration mapping to link it with the Slack Channel.
3. If a mapping only exists from Slack, it continues to use the folder and create an FRUP record for the Salesforce record to use the existing folder. This folder is likely to be outside of the Salesforce root folder.
4. If Salesforce and Slack have existing mappings but are not related to each other, it throws an error through Toolkit.mostRecentError or within a flow action, stating that the mappings already exist.

This method/invocable is used in a flow template provided in the Box for Salesforce package Create Box Folder/Slack Channel Mapping.

Returns:

• Boolean based on the transaction success.

setSlackChannelAccessManagementDisabled

This toolkit method calls the put integration mappings endpoint to update the access management deactivated setting.

This method/invocable is used in a flow template provided in the Box for Salesforce package Create Box Folder/Slack Channel Mapping.

Returns:

• Boolean based on the transaction success.