3.1.4.7 SetPermissions

  • Article

The SetPermissions operation is used by a protocol client to share a document with other users.

The following is the WSDL port type specification of the SetPermissions WSDL operation.

 <wsdl:operation name="SetPermissions" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
   <wsdl:input wsaw:Action="http://schemas.microsoft.com/clouddocuments/DocumentSharing/SetPermissions" message="tns:DocumentSharing_SetPermissions_InputMessage" xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"/>
   <wsdl:output wsaw:Action="http://schemas.microsoft.com/clouddocuments/DocumentSharing/SetPermissionsResponse" message="tns:DocumentSharing_SetPermissions_OutputMessage" xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"/>
   <wsdl:fault wsaw:Action="http://schemas.microsoft.com/clouddocuments/DocumentSharing/SetPermissionsSharingServerErrorFault" name="SharingServerErrorFault" message="tns:DocumentSharing_SetPermissions_SharingServerErrorFault_FaultMessage" xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"/>
 </wsdl:operation>

The protocol client sends a DocumentSharing_SetPermissions_InputMessage request message and the server responds with a DocumentSharing_SetPermissions_OutputMessage, as follows:

  1. The server validates every element in the input message, and sends a SOAP fault message with an error code 1 (section 8) if any element is not valid.

  2. If the server does not support sharing at the document location, it returns a SOAP fault message with an error code 17 (section 8).

  3. To complete the operation successfully, the calling user MUST have the permission to manage the document’s ACL. If the user does not have the permission, the server MUST return a SOAP fault with an  error code 0 (section 8).

  4. For each user in the input request, the server MUST remove the current access control entry for the user, and replace it with permissions that match the new role assigned to the user.

  5. If requested, the server creates a notification message that includes any custom messages and any tokenized sharing links or standard links, and sends the message as an email to each user who has been successfully granted its new role.

  6. If any user fails to be granted its new role, the server creates a list of failed users and failure reasons, and embeds the list in a SetPermissionsResponse element.

  7. The server returns a SetPermissionsResponse element in the DocumentSharing_SetPermissions_OutputMessage response message.