Skip to content

Latest commit

 

History

History
180 lines (134 loc) · 7.87 KB

collaboration.md

File metadata and controls

180 lines (134 loc) · 7.87 KB

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

You can add a collaboration on a folder or a file by calling item.collaborate(accessible_by, role, can_view_path=None, notify=None, fields=None). Pass the User or Group to collaborate the item with as the accessible_by parameter. The role parameter determines what permissions the collaborator will have on the folder. This method returns a Collaboration object representing the new collaboration on the item.

from boxsdk.object.collaboration import CollaborationRole

user = client.user(user_id='11111')
collaboration = client.folder(folder_id='22222').collaborate(user, CollaborationRole.VIEWER)

collaborator = collaboration.accessible_by
item = collaboration.item
has_accepted = 'has' if collaboration.status == 'accepted' else 'has not'
print(f'{collaborator.name} {has_accepted} accepted the collaboration to folder "{item.name}"')

Alternatively, you can also invite a user with their email address.

from boxsdk.object.collaboration import CollaborationRole

email_of_invitee = '[email protected]'
collaboration = client.folder(folder_id='22222').collaborate_with_login(email_of_invitee, CollaborationRole.VIEWER)

Or, you can invite a group using the group id

from boxsdk.object.collaboration import CollaborationRole

group = client.group(group_id='11111')
collaboration = client.folder(folder_id='22222').collaborate(group, CollaborationRole.VIEWER)

collaborator = collaboration.accessible_by
item = collaboration.item
has_accepted = 'has' if collaboration.status == 'accepted' else 'has not'
print(f'{collaborator.name} {has_accepted} accepted the collaboration to folder "{item.name}"')

Note: The can_view_path parameter is currently only available for collaborations on folders.

Edit a Collaboration

A collaboration can be edited by calling collaboration.update_info(*, data=None, role=None, status=None, **kwargs). Note that role fields is always required when updating a collaboration. This method returns an updated Collaboration object, leaving the original unmodified.

from boxsdk.object.collaboration import CollaborationRole

collaboration_update = {'role': CollaborationRole.EDITOR, 'can_view_path': False}
collaboration = client.collaboration(collab_id='12345')
updated_collaboration = collaboration.update_info(data=collaboration_update)

Remove a Collaboration

A collaboration can be removed by calling collaboration.delete(). This will generally cause the user or group associated with the collaboration to lose access to the item. This method returns True to indicate that removal succeeded.

collaboration_id = '1111'
client.collaboration(collaboration_id).delete()

Get a Collaboration's Information

To get information about a specific collaboration, call collaboration.get(). This method returns a new Collaboration with fields populated by data from the API.

collaboration = client.collaboration(collab_id='12345').get()

List Collaborations on a Folder or File

To retrieve all collaborations on a specified Folder or File, call item.get_collaborations(limit=None, marker=None, fields=None). This method returns a BoxObjectCollection that you can use to iterate over all Collaboration objects in the collection.

collaborations = client.folder(folder_id='22222').get_collaborations()
for collab in collaborations:
    target = collab.accessible_by
    print(f'{target.type.capitalize()} {target.name} is collaborated on the folder')
collaborations = client.file(file_id='11111').get_collaborations()
for collab in collaborations
    target = collab.accessible_by
    print(f'{target.type.capitalize()} {target.name} is collaborated on the file')

List Pending Collaborations

To retrieve all pending collaborations for the current user, call client.get_pending_collaborations(limit=None, offset=None, fields=None). The user can accept or reject these collaborations. This method returns a BoxObjectCollection that you can use to iterate over all pending Collaboration objects in the collection.

pending_collaborations = client.get_pending_collaborations()
for pending_collaboration in pending_collaborations:
    print(f'Collaboration {pending_collaboration.id} is pending')

Accept or Reject a Pending Collaboration

To accept or reject a pending collaboration, call collaboration.accept() or collaboration.reject(). These methods both return the updated Collaboration object, leaving the original unmodified.

accepted_collab = client.collaboration(collab_id='12345').accept()

rejected_collab = client.collaboration(collab_id='98765').reject()