Box: Add Collaboration
Adds a collaboration with a 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

  1. Users that have already collaborated will result in an error.
  2. 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`); 
  }
}

1 thought on “Box: Add Collaboration”

  1. Pingback: Box: Delete Collaboration – Questetra Support

Comments are closed.

%d bloggers like this: