Choose where you’d like to start

Share Documents in Zoho Writer

Table of Contents

Description

The zoho.writer.shareDocument task is used to share a Zoho Writer document owned or co-owned by you with other users.

Note: On average, it takes about a minute to index a file/folder after it is created or updated. This indexing time can increase if the queue size increases.  You will not get the expected result if you execute zoho.writer.shareDocument task before the document you need to share is indexed.

Syntax

<response> = zoho.writer.shareDocument(<document_id>, <email_id>, <role>, <type>, <connection>);
where:

 

ParamsData typeDescription

<response>

KEY-VALUE

The response returned by Zoho Writer. It represents the details of the user who shares the document and with whom the document is shared, and the status of the executed task.

<document_id>

TEXT

The ID of the document that will be shared.
The document ID can be obtained from the open URL of the document that will be shared. The URL is in the following format:
https://writer.zoho.com/writer/open/<document_id>

<email_id>

TEXT/ LIST

The email address of the user with whom the document will be shared.

Note: The maximum number of email addresses that can be specified is 10.

<role>

TEXT

The role of the user with whom the document is shared.

The allowed values for this parameter are as follows:

  • viewer - Users will be able to read the document.
  • commenter - Users will be able to read and add comments in the document.
  • editor - Users will be able to read and edit the document.
  • co_owner - Users will be able to read, edit, and share the document.

<type>

TEXT

The visibility of the document.

Allowed values:

  • personal - Only the collaborators of the document can view your document.

<connection>

TEXT

The link name of the connection.

Note:

  • In view of stopping new authtoken generation, a Zoho OAuth connection with appropriate scopes is mandatory in order for new integration tasks (created after the deadline specified in the post) to work as expected. Existing integration tasks will continue to work with or without the connections parameter until you manually delete the authtoken from accounts.
  • Scopes applicable for this task: ZohoWriter.DocumentEditor
  • Refer to this post for the list of Zoho services that support the connections page.
  • Learn more about connections

Example 1: Share a document with one user

The following script shares the specified document with the user - shawn@zylker.com while assigning the role - co_owner.

response = zoho.writer.shareDocument("al296XXXXXXXXXXXXXXXXXXXXXXXXXXXa516c", "shawn@zylker.com", "co_owner", "personal", "writer_oauth_connection");

where:

response
The KEY-VALUE response returned by Zoho Writer.
"al296XXXXXXXXXXXXXXXXXXXXXXXXXXXa516c"
The TEXT that represents the ID of the document that will be shared.
"shawn@zylker.com"
The TEXT that represents the email address of the user with whom the document will be shared.
"co_owner"
The TEXT that represents the role assigned to the user with whom the document will be shared. With co_owner as the value for role parameter, the specified user can view, edit, and share the shared document.
"personal"
The TEXT that represents the visibility of the shared document. Here, only the document collaborators can view it.
"writer_oauth_connection"
The TEXT that represents the name of the connection.

Example 2: Share a document with a list of users

The following script shares the specified document with the all the users in the list - collaborators_list while assigning the role - editor.

 collaborators_list = List();
 collaborators_list.add("shawn@zylker.com");
 collaborators_list.add("mike.n@zylker.com");
 
 response = zoho.writer.shareDocument("al296XXXXXXXXXXXXXXXXXXXXXXXXXXXa516c", collaborators_list, "viewer", "personal", "writer_oauth_connection");

where:

collaborators_list
The LIST variable that holds the email addresses of all the users with whom the document will be shared.
"editor"
The TEXT that represents the role assigned to the user with whom the document will be shared. With editor as the value for role parameter, the specified user can view and edit the shared document.

Response Format

Success Response

  • The success response will be returned in the following format:

      {
      "success": [
      {
      "email_id": "shawn@zylker.com",
      "role": "viewer",
      "user_id": "53XXXX53",
      "time_ms": 1563964827313,
      "shared_by": {
      "email_id": "charlie.p@zylker.com",
      "profile_photo": "https://contacts.zoho.com/file?t=user&ID=58XXXX70&fs=thumb",
      "user_id": "58XXXX70",
      "display_name": "Charlie"
      },
      "time": "2019-07-24T10:40:27Z",
      "type": "personal",
      "status": true
      },
      {
      "email_id": "mike.n@zylker.com",
      "role": "viewer",
      "user_id": "53XXXX53",
      "time_ms": 1563964827378,
      "shared_by": {
      "email_id": "charlie.p@zylker.com",
      "profile_photo": "https://contacts.zoho.com/file?t=user&ID=58XXXX70&fs=thumb",
      "user_id": "58XXXX70",
      "display_name": "Charlie"
      },
      "time": "2019-07-24T10:40:27Z",
      "type": "personal",
      "status": true
      }
      ],
      "failure": [
      ]
      }

Failure Response

  • The failure response will be returned in the following format for improper document ID:

      {
      "error": {
      "message": "Request URL not configured properly. Please check and try again",
      "documentation_url": "https://www.zoho.com/writer/help/api/v1/general-errors.html",
      "response_generated_time": 1563961624177,
      "request_url": "https://writer.zoho.com/api/v1/documents//collaboration",
      "errorcode": "R2008"
      }

  • The failure response when you try to share a document that is not owned or co-owned by you will be returned in the following format:

      {
      "error": {   "message": "Permission denied. You are not authorized to perform this operation.",   "documentation_url": "https://www.zoho.com/writer/help/api/v1/general-errors.html",   "response_generated_time": 1563961602526,   "request_url": "https://writer.zoho.com/api/v1/documents/al296XXXXXXXXXXXXXXXXXXXXXXXX6964add/collaboration",   "errorcode": "R5010"   }   }

  • The failure response will be returned in the following format when you try to share the document with more than 10 users:

      {
      "error": {
      "message": "You seem to have used the supported parameters multiple times.",
      "documentation_url": "https://www.zoho.com/writer/help/api/v1/general-errors.html",
      "response_generated_time": 1564648109086,
      "request_url": "https://writer.zoho.com/api/v1/documents/al296XXXXXXXXXXXXXXXXXXXXXXXX6964add/collaboration",
      "errorcode": "R2004"
      }
      }

Related Links

Get Started Now

Execute