Box: Add Collaboration
This item adds a collaboration for the specified user to the specified file or folder on Box. The user is specified by the email address.
Configs: Common
- Step Name
- Note
Configs
- C1: OAuth2 Setting *
- C2: Email address of the Box user to invite *
- C3: Role to set *
- C4: Item type (file or folder) *
- C5: File/Folder ID to add a collaboration to *
Notes
- Users that have already collaborated will result in an error.
- The refresh token for Box has an expiration date. Use regularly to ensure that it does not exceed the expiration.
Capture

See also
Script (click to open)
- An XML file that contains the code below is available to download
- box-collaboration-add.xml (C) Questetra, Inc. (MIT License)
- If you are using Professional, you can modify the contents of this file and use it as your own add-on
main();
function main(){
const oauth2 = configs.get("conf_OAuth2");
const itemType = configs.get("conf_ItemType");
const fileOrFolderId = decideFileOrFolderId(itemType);
const emailAddress = decideEmailAddress();
const role = configs.get("conf_Role");
// コラボレーション追加
addCollaboration(oauth2, emailAddress, role, itemType, fileOrFolderId);
}
/**
* 指定するメールアドレスをconfigから読み出して出力する
* @return {String} emailAddress メールアドレス
*/
function decideEmailAddress(){
let emailAddress = "";
const emailAddressDef = configs.getObject("conf_EmailAddress");
if(emailAddressDef === null){
emailAddress = configs.get("conf_EmailAddress");
}else{
emailAddress = engine.findData(emailAddressDef);
}
if(emailAddress === "" || emailAddress === null) {
throw "Email address is blank";
}
return emailAddress;
}
/**
* コラボレーションするファイルもしくはフォルダのIDをconfigから読み出して出力する
* @param {String} itemType アクセス権限が付与される項目の種類 ファイル/フォルダ
* @return {String} id ファイル もしくは フォルダの ID
*/
function decideFileOrFolderId(itemType){
let id = "";
const idDef = configs.getObject("conf_ItemId");
if(idDef === null){
id = configs.get("conf_ItemId");
}else{
id = engine.findData(idDef);
}
if(id === "" || id === null) {
throw "File ID or Folder ID is blank";
}
if(itemType === "folder" && id === "0") {
throw "Root folder cannot be collaborated";
}
return id;
}
/**
* コラボレーションを追加する
* @param {String} oauth2 Oauth2設定
* @param {String} emailAddress コラボレーションするユーザのメールアドレス
* @param {String} role ロール
* @param {String} itemType アクセス権限が付与される項目の種類 ファイル/フォルダ
* @param {String} fileOrFolderId コラボレーションしたいファイル/フォルダのID
*/
function addCollaboration(oauth2, emailAddress, role, itemType, fileOrFolderId) {
const jsonReq = {};
jsonReq["item"] = {"id": fileOrFolderId, "type": itemType};
jsonReq["accessible_by"] = {"login": emailAddress };
jsonReq["role"] = role;
const url = 'https://api.box.com/2.0/collaborations';
const response = httpClient.begin()
.authSetting(oauth2)
.queryParam("fields", "invite_email,role,accessible_by")
.body(JSON.stringify(jsonReq), "application/json; charset=UTF-8")
.post(url);
const status = response.getStatusCode();
const responseTxt = response.getResponseAsString();
let jsonRes;
try {
jsonRes = JSON.parse(responseTxt);
} catch(e) {
engine.log(`${responseTxt}`);
engine.log("failed to parse as json");
throw `Failed to add collaboration. status: ${status}`;
}
if (status !== 201){
engine.log(`${responseTxt}`);
if(status === 400 && jsonRes["code"] === "user_already_collaborator"){
throw `This request is not needed, ${emailAddress} already collaborator. status: ${status}`;
}else{
throw `Failed to add collaboration. status: ${status}`;
}
}
if (jsonRes["invite_email"] === null ){
engine.log(`${jsonRes.accessible_by.login} collborated as ${jsonRes.role}`);
}else{
engine.log(`${jsonRes.invite_email} collborated as ${jsonRes.role}, and Box sends an invitation email`);
}
}
Pingback: Box: Delete Collaboration – Questetra Support