collaborations.md

Collaborations

Collaborations are used to share folders between users or groups. They also define what permissions a user has for a folder.

• Add a Collaboration
• Edit a Collaboration
• Remove a Collaboration
• Get a Collaboration's Information
• Get the Collaborations on a Folder
• Get the Collaborations on a File
• Get Pending Collaborations
• Accept or Decline a Pending Collaboration

Add a Collaboration

A collaboration can be added for an existing user or group with collaborate(BoxCollaborator collaborator, BoxCollaboration.Role role). The role parameter determines what permissions the collaborator will have on the folder.

BoxCollaborator user = new BoxUser(api, "user-id")
BoxFolder folder = new BoxFolder(api, "folder-id");
folder.collaborate(user, BoxCollaboration.Role.EDITOR);

You can also add a collaboration by providing an email address with collaborate(String emailAddress, BoxCollaboration.Role role). If the recipient doesn't have a Box account, they will be asked create one.

BoxFolder folder = new BoxFile(api, "id");
folder.collaborate("gcurtis@box.com", BoxCollaboration.Role.EDITOR);

If you need to create a collaboration with a group, provide a group id.

BoxCollaborator group = new BoxGroup(api, "group-id");
BoxFolder folder = new BoxFolder(api, "folder-id");
folder.collaborate(group, BoxCollaboration.Role.EDITOR);

Edit a Collaboration

A collaboration can be edited by creating a new BoxCollaboration.Info object or updating an existing one, and then passing it to updateInfo(BoxCollaboration.Info fieldsToUpdate)

BoxCollaboration collaboration = new BoxCollaboration(api, "id");
BoxCollaboration.Info info = collaboration.new Info();
info.setStatus(BoxCollaboration.Status.ACCEPTED);
collaboration.updateInfo(info);

Remove a Collaboration

A collaboration can be removed by calling delete().

BoxCollaboration collaboration = new BoxCollaboration(api, "id");
collaboration.delete();

Get a Collaboration's Information

Calling getInfo() on a collaboration returns a snapshot of the collaboration's info.

BoxCollaboration collaboration = new BoxCollaboration(api, "id");
BoxCollaboration.Info info = collaboration.getInfo();

You can also choose to retrieve only specific fields of the collaboration by calling getInfo(String... fields) with a list of field names.

BoxCollaboration collaboration = new BoxCollaboration(api, "id");
BoxCollaboration.Info info = collaboration.getInfo(BoxCollaboration.ALL_FIELDS);

Get the Collaborations on a Folder

You can get all of the collaborations on a folder by calling getCollaborations() on the folder.

BoxFolder folder = new BoxFolder(api, "id");
Collection<BoxCollaboration.Info> collaborations = folder.getCollaborations();

Get the Collaborations on a File

You can get an iterator over all of the collaborations on a file by calling BoxFile#getAllFileCollaborations(String... fields) on the file.

BoxFile file = new BoxFile(api, "id");
Iterable<BoxCollaboration.Info> collaborations = file.getAllFileCollaborations();

Get Pending Collaborations

A collection of all the user's pending collaborations can be retrieved with getPendingCollaborations(BoxAPIConnection api).

Collection<BoxCollaboration.Info> pendingCollaborations =
    BoxCollaboration.getPendingCollaborations(api);

Accept or Decline a Pending Collaboration

To accept or decline a pending collaboration, update the info of the pending collaboration object with the desired status.

// Accept all pending collaborations
Collection<BoxCollaboration.Info> pendingCollaborations = BoxCollaboration.getPendingCollaborations(api);
for (BoxCollaboration.Info collabInfo : pendingCollaborations) {
    collabInfo.setStatus(BoxCollaboration.Status.ACCEPTED);
    collabInfo.getResource().updateInfo(collabInfo);
}