Get Documents from Zoho Writer

Table of Contents

Note:

  • Each time the zoho.writer.getDocuments integration task is executed, it triggers an API request in the back-end. This call is deducted from the external calls limit available for the service from which the task is executed, based on your pricing plan.
  • Only actual executions that receive a response (whether success or failure) are counted, not the number of times the task appears in the script. For example, if zoho.writer.getDocuments integration task is placed inside a for each task that iterates five times, the number of external calls consumed will be five, even though the task appears only once in the script. 

Description

The zoho.writer.getDocuments task is used to fetch a list of all the documents from Zoho Writer. This integration task is based on the Zoho Writer API - Get List of Documents with Specified Parameters.

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.getDocuments task before the document you need to fetch is indexed.

Syntax

<response> = zoho.writer.getDocuments(<category>, <offset>, <limit>, <sort_by>, <connection>);

where:

ParamsData typeDescription
<response>KEY-VALUEThe response returned by Zoho Writer. It represents the number of documents fetched and their metadata.
<category>TEXT

The category based on which the documents are filtered and fetched.

The possible values for the parameter - category are as follows:

  • all - Fetches a list of all documents
  • shared_to_me - Fetches a list of documents which are shared to you
  • owned_by_me - Fetches a list of documents which are created by you
<offset>NUMBERThe start index from which the documents will be fetched. The index value starts from 0.
<limit>NUMBER

The number of documents that will be fetched.

Note: The maximum number of documents that can be fetched is 100.

<sort_by>TEXT

The order in which the documents will be fetched.

The possible values for the parameter - sort_by are as follows:

  • created_time - Fetches the documents in the order in which they are created. The recently created document is fetched first.
  • modified_time - Fetches the documents in the order of the time they are modified. The recently modified document is fetched first.
  • lastopened_time - Fetches the documents in the order in which they were last opened.
<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.
  • Add relevant scopes mentioned in ​Zoho Writer API while creating the connection.
  • Refer to this post for the list of Zoho services that support the connections page.
  • Learn more about connections

Example

The following script fetches a list of first two recently created documents from Zoho Writer.

response = zoho.writer.getDocuments("all",0,2,"created_time","writer_oauth_connection");

where:

response
The KEY-VALUE response returned by Zoho Writer. It represents the number of documents fetched and their respective metadata.
0
The NUMBER that represents the start index from which the documents will be fetched.
2
The NUMBER that represents the total number of documents that will be fetched.
"created_time"
The TEXT that represents the sort_by value. Here, the documents are fetched based on the order of the time in which they are created; the recently created document is fetched first.
"writer_oauth_connection"
The TEXT that represents the name of the connection.

Response Format

Success Response

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

      {
      "offset": 0,
      "documents": [
      {
      "created_time": "2019-06-26T10:07:11Z",
      "role": "OWNER",
      "modified_time_ms": 1561543705220,
      "parent_folder_id": "folder",
      "collaboration_id": "11867XXXXXXXXX01382",
      "last_opened_time": "2019-06-26T10:07:12Z",
      "open_url": "https://writer.zoho.com/writer/open/al296XXXXXXXXXXXXXXXXXXXXXXXXXXaf66a",
      "is_favourite": false,
      "type": "document",
      "document_id": "al296XXXXXXXXXXXXXXXXXXXXXXXXXXaf66a",
      "last_opened_time_ms": 1561543632019,
      "thumbnail_url": "https://writer.zoho.com/writer/thumbnail/al296XXXXXXXXXXXXXXXXXXXXXXXXXXaf66a",
      "created_by": "John",
      "document_name": "Integration tasks list",
      "created_time_ms": 1561543631560,
      "modified_time": "2019-06-26T10:08:25Z",
      "preview_url": "https://writer.zoho.com/writer/preview/al296XXXXXXXXXXXXXXXXXXXXXXXXXaf66a",
      "creator_id": "58XXXX70",
      "download_url": "https://writer.zoho.com/api/v1/download/al296XXXXXXXXXXXXXXXXXXXXXXXXXaf66a",
      "permalink": "https://docs.zoho.com/file/al296XXXXXXXXXXXXXXXXXXXXXXXXXaf66a",
      "lastmodified_by": [
      {
      "email_id": "john@zylker.com",
      "profile_photo": "https://contacts.zoho.com/file?t=user&ID=58XXXX70&fs=thumb",
      "user_id": "58XXXX70",
      "display_name": "John"
      }
      ],
      "status": "active"
      },
      {
      "created_time": "2019-06-26T07:19:46Z",
      "role": "OWNER",
      "modified_time_ms": 1561533624688,
      "parent_folder_id": "folder",
      "collaboration_id": "11867XXXXXXXXX16931",
      "last_opened_time": "2019-06-26T07:19:46Z",
      "open_url": "https://writer.zoho.com/writer/open/al296XXXXXXXXXXXXXXXXXXXXXXXXXb4add",
      "is_favourite": false,
      "type": "document",
      "document_id": "al296XXXXXXXXXXXXXXXXXXXXXXXXXb4add",
      "last_opened_time_ms": 1561533586970,
      "thumbnail_url": "https://writer.zoho.com/writer/thumbnail/al296XXXXXXXXXXXXXXXXXXXXXXXXXb4add",
      "created_by": "John",
      "document_name": "Document name",
      "created_time_ms": 1561533586705,
      "modified_time": "2019-06-26T07:20:24Z",
      "preview_url": "https://writer.zoho.com/writer/preview/al296XXXXXXXXXXXXXXXXXXXXXXXXXb4add",
      "creator_id": "58XXXX70",
      "download_url": "https://writer.zoho.com/api/v1/download/al296XXXXXXXXXXXXXXXXXXXXXXXXXb4add",
      "permalink": "https://docs.zoho.com/file/al296XXXXXXXXXXXXXXXXXXXXXXXXXb4add",
      "lastmodified_by": [
      {
      "email_id": "john@zylker.com",
      "profile_photo": "https://contacts.zoho.com/file?t=user&ID=58XXXX70&fs=thumb",
      "user_id": "58XXXX70",
      "display_name": "John"
      }
      ],
      "status": "active"
      }
      ],
      "total_count": 10,
      "limit": 2
      }

  • The response will be returned in the following format when the offset value is higher than the number of documents present in Zoho Writer:

      {
      "offset": 10,
      "documents": [
      ],
      "total_count": 5,
      "limit": 7,
      "message": "You don't have any documents to list."
      }

Failure Response

  • The failure response will be returned in the following format when you provide the limit value greater than 100:

      {
      "error": {
      "parameter_name": "limit",
      "message": "The limit you've given exceeds the maximum allowed limit of 100 documents.",
      "documentation_url": "https://www.zoho.com/writer/help/api/v1/general-errors.html",
      "response_generated_time": 1564648842968,
      "request_url": "https://writer.zoho.com/api/v1/documents",
      "errorcode": "R3033"   
    ​  }
      }

Related Links