Sharing items

The owner of a file or folder (i.e. an item), including a collaborator with the Manage permission set on an item (explained in more detail below) can share this item with other people. These people could be other Cocoon Data users or those who do not yet have a user account on the Cocoon Data Platform.

A person who has been shared an item is referred to as a collaborator. If a collaborator did not have a Cocoon Data user account when they were shared an item, the act of sharing the item with this person (via their email address) automatically creates them a user account with this email address on the Cocoon Data Platform (with the Ad hoc role).

When sharing an item, the item's owner (or an existing collaborator with the Manage permission set on the item) can apply one of up to five permission sets to any collaborator being added/modified on the item. Therefore, each collaborator on an item is associated with their own permission set. A permission set grants the collaborator one or more individual permissions, each of which allows that collaborator to perform various actions on that item and its contents. For more information about permission sets and the individual permissions they grant, see <access-service>/api/v1/permissions/sets.

All collaborators and their respective permission sets on a folder are implicitly propagated down through that folder's item hierarchy. Therefore, if a folder has been shared with a collaborator and a given permission set, then that collaborator can access and perform specific actions (granted by the permission set's individual permissions) on this folder, as well as on every item contained within this folder and its subfolders.

If, however, one of the following had been conducted on a sub-item within this folder:

• a collaborator was removed from the sub-item, or
• a collaborator's permission set on this sub-item was changed,

then such a modification is made explicitly to this collaborator on this sub-item, which has the following implications:

• Any implicit sharing this collaborator had to this sub-item (inherited implicitly from the closest ancestral folder) is overridden by this explicit modification.
• If the sub-item is a folder, then the explicit modification on this subfolder is implicitly propagated down through this subfolder's item hierarchy.

This page describes how to use the Cocoon Data API to:

• Share a file with collaborators,
• Share a folder with collaborators,
• Determine existing collaborators on an item and
• Modify existing collaborators on an item

Notes:

• Before sharing a file or a folder, your application must have a valid access token obtained by authenticating and authorizing a Cocoon Data user to the Cocoon Data Platform, where this user has the appropriate role to create items and/or permissions to share them.
  For more information about authenticating and authorizing Cocoon Data users to the Cocoon Data Platform, see Initiating authentication and authorization on the Authentication and authorization page of this guide and the Configuring client applications page of the SafeShare Administrator's Guide.
• The Supported roles (and conditions) section of each API endpoint page (accessible from the relevant procedures throughout this Developer's Guide) contains details about the roles a Cocoon Data user requires and the conditions they must meet, for requests to these endpoints (which would include a valid access token representing the user's authenticated session) to succeed.

Sharing a file with collaborators

A file can be shared with collaborators when the file object is either initialized or subsequently modified (the latter approach being the recommended one ^* ).

To share a file object with collaborators, do one of the following:

• If sharing a file object at the time of its creation/initialization, make a POST request to the API endpoint for creating a new file object:
  • <access-service>/api/v1/organisations/{orgGroupId}/objects
  with a JSON object in the body of the request that contains the collaborators parameter, which in turn contains a list array whose elements each relate to a collaborator and the collaborator's permission set that will be applied to the new file object. See Optional POST-request parameters (of <access-service>/api/v1/organisations/{orgGroupId}/objects) for more information.
  The keyId parameter (name/value pair) whose value is the ID of the key (obtained earlier) must also be specified in this request.
  The value of {orgGroupId} in the URL path of the request is the ID of the organisation in which the file object will be created and shared.
  If the request was successful, a JSON object is returned in the response containing information about the newly initialized file object.
• ( Recommended ^* ) If sharing an existing file object (i.e. after its creation), make a PUT request to this API endpoint:
  • <access-service>/api/v1/objects/{objectId}
  with a JSON object in the body of the request that contains the collaborators parameter, which in turn contains a list array whose elements each relate to a collaborator and the collaborator's permission set that will be applied to the file object. See Optional PUT-request parameters (of <access-service>/api/v1/objects/{objectId}) for more information.
  The value of {objectId} in the URL path of the request is the ID of the file object being shared.
  If the request was successful, a JSON object is returned in the response containing an extensive set of information about the updated file object.

^* Email notifications that inform collaborators about an item being shared with them are triggered by the Cocoon Data Platform at the time when these collaborators are initially shared the item. Therefore, it is recommended that a file object be shared with collaborators only after the file object is initialized and ideally, also after the file object is completed by uploading its locally-encrypted or unencrypted data to the Cocoon Data Platform's Content Service. Otherwise, there is a risk that collaborators will receive such an email notification before the file's content becomes accessible. Furthermore, it is no longer possible to specify shareStartTime and shareEndTime parameters when using the <access-service>/api/v1/organisations/{orgGroupId}/objects API endpoint.

Sharing a folder with collaborators

A folder can be shared with collaborators when the folder is either first created or subsequently modified.

To share a folder with collaborators, do one of the following:

• If sharing a folder at the time of its creation, make a POST request to the API endpoint for creating a new folder:
  • <access-service>/api/v1/organisations/{orgId}/collections
  with a JSON object in the body of the request that contains the collaborators parameter, which in turn contains a list array whose elements each relate to a collaborator and the collaborator's permission set that will be applied to the new folder. See Optional parameters (of <access-service>/api/v1/organisations/{orgId}/collections) for more information.
  The name and parentId parameters (name/value pairs) whose values are described earlier for creating a folder must also be specified in this request.
  The value of {orgId} in the URL path of the request is the ID of the organisation in which the folder will be created and shared.
  If the request was successful, a JSON object is returned in the response containing information about the new folder.
• If sharing an existing folder (i.e. after its creation), make a PUT request to this API endpoint:
  • <access-service>/api/v1/collections/{collectionId}
  with a JSON object in the body of the request that contains the collaborators parameter, which in turn contains a list array whose elements each relate to a collaborator and the collaborator's permission set that will be applied to the folder. See Optional parameters (of <access-service>/api/v1/collections/{collectionId}) for more information.
  The value of {collectionId} in the URL path of the request is the ID of the folder being shared.
  If the request was successful, a JSON object is returned in the response, containing information about the updated folder (including the organisation in which the folder belongs).

Determining existing collaborators on an item

To determine the existing collaborators (and their respective permission sets) on a file object or folder, simply retrieve information about a subset of items from a specific organisation on the Cocoon Data Platform.

If the request was successful, a JSON object is returned in the response containing information about all collaborators on each item retrieved, as well as each collaborator's respective permission set on an item (and the individual permissions that constitute the permission set).

Note: This JSON response only reveals information about collaborators on an item if the valid access token (submitted in the request) was obtained from a successfully authenticated Cocoon Data user that either owns this item or is a collaborator on the item with the View Other permission.

Modifying existing collaborators on an item

Collaborators can be modified on a file or folder by:

• removing existing collaborators from the item,
• changing the permission sets of existing collaborators on the item, or
• adding new collaborators to the item (which is already shared with existing collaborators).

To modify existing collaborators, follow the relevant process above for sharing an existing file or folder with collaborators. However, when making the relevant PUT request, if you intend to:

• Remove existing collaborators from the item, omit these collaborators from the PUT request.
• Change the permission sets of existing collaborators on the item, re-apply these collaborators in the PUT request but modify their permission sets accordingly (i.e. specify the appropriate permissionSet / id sub-element parameter for each of these collaborators with their updated permission set ID).
• Add new collaborators to the item, add these new collaborators in the PUT request along with their permission sets (i.e. specify the appropriate permissionSet / id sub-element parameter for each of these collaborators with the appropriate permission set ID).

Additionally, in this PUT request, ensure that all existing collaborators which are not being altered are re-applied in the request (along with their existing respective permission sets).