Creating Folder/Doc & External Share Link in Zoho WorkDrive
- Difficulty: Intermediate
- Estimated reading time: 20 mins
If you’ve ever searched for “Zoho WorkDrive API” online, you’d realize that there isn’t an official document yet. The closest thing to one is this unpublished API doc that Zoho might provide you when you request for support. While useful, it’s not very comprehensive and the explanations are not thorough.
We’re here to walk you through some of the actions that you may need to perform on WorkDrive that the documentation does not clearly spell out.
You will learn how to:
- Create a folder within another folder on WorkDrive
- Create/Merge a Writer Doc and storing in a WorkDrive folder
- Generate an External Share Link for the Folder/Document
This is part of The Workflow Academy’s Zoho training series to help you attain rockstar Zoho admin status.
Cool Ideas to use the Code
Here are some cool ways you can implement this code from Zoho CRM:- Merge CRM details into proposal/contract documents and systematically store in folders and subfolders in WorkDrive.
- Create collaborative folders/documents on WorkDrive with the external share URL populated on the CRM record. The URL can then be merged into an email template to be sent to the collaborator.
Configuration
Before we begin, the following OAuth Connections scopes are needed:- WorkDrive.Files.ALL
- ZohoWriter.documentEditor.ALL
- ZohoWriter.merge.ALL
Create a Folder within Another Folder on WorkDrive
Fortunately, Zoho has made this part easy with the createFolder function. Just input the subfolder name, parent folder ID and your WorkDrive Connection name.
Note: Folder ID can be found at the end of the WorkDrive folder URL “https://workdrive.zoho.com/home/…/folders/aeci1a880e2a09bcf4641b2ef7c60e81b7b2f”
response = zoho.workdrive.createFolder("INSERT SUBFOLDER NAME", "INSERT MAIN FOLDER ID", "INSERT_WORKDRIVE_OAUTH_CONNECTION");
Create a New Document in a Folder
This script creates a new blank Zoho Writer doc and stores in the specified WorkDrive folder.
attributes = Map();
attributes.put("filename","INSERT FILE NAME");
attributes.put("folder_id","INSERT MAIN FOLDER ID");
newDoc = invokeurl
[
url :"https://zohoapis.com/writer/api/v1/documents"
type :POST
parameters:attributes
connection:"INSERT_WRITER_OAUTH_CONNECTION"
];
Merge & Store a Document in a Folder
This function creates a document by merging fields into a Writer template, and stores in a WorkDrive folder.
values_map = Map();
values_map.put("INSERT MERGE FIELD NAME","INSERT MERGE FIELD VALUE"); //Add more accordingly
output_settings = Map();
output_settings.put("doc_name","INSERT FILE NAME HERE");
output_settings.put("folder_id","INSERT FOLDER ID");
createDoc = zoho.writer.mergeAndStore("INSERT WRITER DOC TEMPLATE ID",values_map,output_settings,"INSERT_WRITER_OAUTH_CONNECTION");
info createDoc;
Create External Share Link
To create an external share link, an API call with a header and specific parameters are needed. Header- All WorkDrive endpoints are JsonAPI compliant, thus, the framework expects a header. If it is not present, an Error Code ‘415’ will be thrown. To know more, check out https://jsonapi.org/
- Below are the parameter attribute details.
- resource_id: file or folder id to which the custom share link has to be created.
- allow_download: if set as true, this setting allows external users who access share link to download the file
- request_user_data: if set as true, external users are required to enter their details (Name, Email and Phone) before accessing the share link. It can be useful to track guest users.
- link_name: name used to identify the share link.
- expiration_date: date in which the link will expire
- role_id: permission of the share link
- 5 – External share for folder with EDIT access
- 6 – External share for folder with VIEW access
- 7 – External share for folder with UPLOAD access
- password_text: the text you set here will enable password protection for the document
- input_fields: these are the fields mentioned in the request_user_data attribute
- Note:
- No need to pass attributes like input_fields, password_text and expiration_date if the share link does not require user data, password protection and expiry date respectively.
- Mandatory attributes like resource_id, link_name, request_user_data, and allow_download are required to create a custom share link.
//Header
mp = Map();
mp.put("Accept","application/vnd.api+json");
//Parameters Map
externalLinkMap = Map();
externalLinkMap.put("resource_id","INSERT FOLDER OR WRITER DOC ID");
externalLinkMap.put("link_name","INSERT A LINK NAME");
externalLinkMap.put("request_user_data",false);
externalLinkMap.put("allow_download",true);
externalLinkMap.put("role_id","7");
attributesMap = {"attributes":externalLinkMap,"type":"links"};
dataMap = Map();
dataMap.put("data",attributesMap);
//API Call
createExternalLink = invokeurl
[
url :"https://workdrive.zoho.com/api/v1/links"
type :POST
parameters:dataMap.toString()
headers:mp
connection:"INSERT_WORKDRIVE_OAUTH_CONNECTION"
];
//Get External Share Link
shareLink = createExternalLink.get("data").get("attributes").get("link");
info shareLink;
DISCLAIMER!
If you are generating an external share link for a new blank doc that you have created via Deluge, chances are, you might run into this error:{“errors”:[{“id”:”R012″,”title”:”Resource is not in active status to process this action”}]}
For some reason, when a new blank Writer Doc is created via custom function, it is by default in a DRAFT status. Because of that, the generate external share link function cannot execute successfully. In order to overcome this, you would first need to change the document status to ACTIVE before generating the share link. Here’s how you can do it.
The script below marks the newly created Writer Doc as ready, converting it from DRAFT status to ACTIVE.
- Make sure that this script is placed above the “Generate External Share Link” script
- You can get the Writer document ID by getting info on the new Writer document creation function response.
header = Map();
header.put("Accept","application/vnd.api+json");
data = {"data":{"attributes":{"status":"1"},"type":"files"}};
markAsReady = invokeurl
[
url :"https://workdrive.zoho.com/api/v1/files/" + "INSERT_WRITER_DOC_ID"
type :PATCH
parameters:data.toString()
headers:header
connection:"INSERT_WRITER_OAUTH_CONNECTION"
];
info markAsReady;
Click here to copy the scripts. For more Zoho-wizardry, check out our GitHub page.
Contact Us!
Book a free 30-minutes consultation with a Zoho expert or send us an email
