Using OAuth2 - Serverless Functions

Using OAuth2 - Serverless Functions

Introduction

Functions can be made accessible through OAuth2 protocol. OAuth2 method allows you to share specific data with any application while keeping your usernames and passwords private, by having specific scopes which grant access to specfic data.

In order to make a function available through OAuth2 method, you need to first register your client with Zoho CRM. Please take a look here to know how to register your client application.

However, there are some key points that need to be noted

The scope for the client when using the HTTP GET Method should be:
  1. ZohoCRM.functions.execute.READ
The scope for the client when using the HTTP POST Method should be:
  1. ZohoCRM.functions.execute.CREATE
Once the authentication is done, you can proceed with creating your function.

See also
  • Functions in Zoho CRM.
  • Integration tasks for Functions using the Version 2.0 of APIs.
  • Deluge Script - Reference Guide.
  • Connections - Connect your Zoho CRM with any third-party application by invoking their APIs in a function.
  • Widgets - Embeddable UI components in Zoho CRM, which allows users to utilise information from third-party applications.

There are a lot of different situations where a function which is available as an API can be put to use. For instance, a function can be set to trigger whenever a certain limit has been crossed in statistical data of the performance of a company. This document is to give you a sample function which is triggered through external sources, where the function is provided as an API.

Sample function

Scenario

Say there is a requirement to get consent from customers and have them sign up for newsletters. This is to enable security and not infringe on their privacy.

You can have a button in View Page of a Contact record. The button can open a Widget, which pulls up a Subscription form(to be filled by your Agents). To create widgets, please refer our Widgets help.

Through the widget, the subscription form is submitted. Post which an email with the consent form is sent to the customer. After the customer accepts the consent form, the information about the contact is added to the MailChimp campaign list.

Required Applications

MailChimp - for Newsletter
Google Drive - Consent Form

Requirements

  1. Create Connections For MailChimp and Google Drive.
  2. Call MailChimp and Google Drive API in this Function.
  3. Turn the Function into an API.
  4. Create a Widget and invoke the Function within it.

Making the connection

In order for the Function to make use of third-party applications and facilitate data transfer, you need to first set up a connection between Zoho CRM and the said third-party software. In this case, it would be MailChimp and Google Drive. Read more.

For MailChimp



For Google Drive


Create the Function

The steps to create the function according to the requirement is split into 2 parts.

Part 1: Write the function code

Create a standalone function with the following code.



The Function Code is
  1. string subscribeNewsletter(string listId,string emailAddress,string extraDetails){
  2.     mailChimpURL = "https://us18.api.mailchimp.com/3.0/";
  3.     if(isNull(listId))
  4.     {
  5.         //Default List
  6.         listId = "2a9a3690fd";
  7.     }
  8.     if(isNull(emailAddress))
  9.     {
  10.         return "Email Address cannot be null";
  11.     }
  12.     //Get all members
  13.     membersList = invokeurl
  14.     [
  15.         url :mailChimpURL + "/lists/" + listId + "/members"
  16.         type :GET
  17.         parameters:""
  18.         connection:<CONNECTION_LINKNAME>
  19.     ];
  20.     //Is Member already in List
  21.     for each memberInfo in membersList.get("members")
  22.     {
  23.         if(emailAddress.equals(memberInfo.get("email_address")))
  24.         {
  25.             return "The member is already subscribed to Zoho Newsletter";
  26.         }
  27.     }
  28.     //Get all Documents from Google Drive
  29.     gdriveURL = "https://www.googleapis.com/drive/v2/files";
  30.     fileList = invokeurl
  31.     [
  32.         url :gdriveURL
  33.         type :GET
  34.         parameters:""
  35.         connection:<CONNECTION_LINKNAME>
  36.     ];
  37.     //Get Download URL of Consent Form
  38.     webContentLink = null;
  39.     for each fileInfo in fileList.get("items")
  40.     {
  41.         title = fileInfo.get("title");
  42.         if(title.equals("Consent-Form.docx"))
  43.         {
  44.             webContentLink = fileInfo.get("webContentLink");
  45.             break;
  46.         }
  47.     }
  48.     if(isNull(webContentLink))
  49.     {
  50.         return "No Document Found on Drive. Docuemnt Name ::: Consent-Form.docx";
  51.     }
  52.     //Send Notification
  53.     name = "Guest";
  54.     signature = "Zoho";
  55.     if(!isNull(extraDetails))
  56.     {
  57.         if(extraDetails.contains("name"))
  58.         {
  59.             name = extraDetails.get("name");
  60.         }
  61.         if(extraDetails.contains("signature"))
  62.         {
  63.             signature = extraDetails.get("signature");
  64.         }
  65.     }
  66.     sendmail
  67.     [
  68.         from :zoho.adminuserid
  69.         to :emailAddress
  70.         subject :"consent form"
  71.         message :"Hi " + name + ",<expression></expression><div><br></div><div>Before subscribing to Zoho Newsletter, </div><br /><div>Please download the <br /><a target='_blank' href='" + webContentLink + "'>Consent Form</a> and mail it to newsletter@xyz.com</div><div><br></div><div><br></div><div>Regards,</div><div>" + signature + "<br></div>" ]
  72.         if(extraDetails.contains("mobile"))
  73.         {
  74.             sendsms
  75.             [
  76.                 to :extraDetails.get("mobile")
  77.                 message:"Consent Form has been sent to your mail id :- " + emailAddress
  78.             ];
  79.         }
  80.     return "Consent form sent successfully";
  81. }
Note

The entire request body will not be available inside the Function. It needs to be sent or received inside the arguments.

Configure an argument which contains the entire request body

In the function given above, you can see that we have 'extraDetails' as one of our Function argument. It is used to get name and signature from the user. This will be helpful when there is no way of knowing the number of arguments that will be passed to your Function.

Since there is no way of knowing the number of arguments present in it, you can have the function contain the entire request body within a single argument, i'e "extraDetails" in this case.

Note
  1. Value of 'listId' will be '2a9a3690fd'(in case of null).
  2. 'emailAddress' is mandatory.
  3. 'extraDetails' argument is provided to pass extra info, the one which contains the entire request body.
  4. 'listId', 'emailAddress' are of type STRING.
  5. 'extraDetails' is of type STRING and we are passing JSON in 'extraDetails'.

Part 2: Make the function available as an API

Once the function has been created, tested and saved, you can proceed to turn the function into an API.
  1. Go to Setup > Developer Space > Functions.
  2. Click the Settings icon for the corresponding function which needs to be made an API.
  3. Click REST API.



  4. Enable OAuth2 slider.
  5. Click Save.


Calling the function inside Widgets

Now comes the actual working part. Since the function has been turned into an API call, you can use the API code for the function in any widget, app or software and set it up to trigger based on your requirement.

Use the following HTML code (Consent Form of the Newsletter), to create a Widget. To learn how to create widgets, please click here.

HTML Code

  1. <h2>XYZ Newsletter</h2>
  2. <div class="container">
  3. <h2<Subscribe to our Newsletter</h2>
  4. </div>
  5. <div class="container" style="background-color:white">
  6. <input type="text" id="name" placeholder="Name" name="name" required>
  7. <input type="text" placeholder="Email address" name="mail" required id="email">
  8. <label>
  9. <input type="checkbox" checked="checked" name="subscribe">Daily Newsletter
  10. </label>
  11. </div>
  12. <div class="container">
  13. <input type="submit" value="Subscribe" id="subscribeButton">
  14. </div>
  15. <span id="res1">Click on the above button to Subscribe</span>

Script(Javascript):

  1. <script type="text/javascript">

  3. $("#subscribeButton").click(function() {
  4.     var extraDetails = {};
  5.     extraDetails.name = $("#name").val();
  6.     extraDetails.signature = "XYZ";
  7.     var arguments = {};
  8.     arguments.extraDetails = extraDetails;
  9.     arguments.emailAddress = $("#email").val();
  10.     var data = {
  11.          "arguments": JSON.stringify(arguments),
  12.     }

  14.     ZOHO.embeddedApp.init()
  15.         .then(function() {

  17.             ZOHO.CRM.FUNCTIONS.execute("subscribenewsletter", data)
  18.                 .then(function(resp) {
  19.                 $('#res1').text(JSON.stringify(resp));
  20.                 }).catch(function(resp) {
  21.                     $('#res1').text(JSON.stringify(resp));
  22.                 })
  23.          });
  24. });
Note

The above script only works for widgets placed inside the CRM.
To learn more about the Integration Tasks for Functions, click here.

The Outcome

Subscribing to the Newsletter



Getting the subscription mail



Once the Consent form is sent back to the mailer, the newsletter subscription will be enabled.

Disadvantages of not using Serverless functions

The user has to manually
  1. Register the application on MailChimp and Google Drive.
  2. Code to handle OAuth2 flow.
  3. Call Mailchimp API's to verify the user availability.
  4. Call Google Drive API, to retrieve document URL.
  5. Code to send Email and SMS to Customer.
As you can see from the above steps, there are a lot of steps involved, which requires you to manually write codes for the widget as well as the functionality of the widget. However,
this method is time consuming and requires a ton of manual effort. You can avoid them by having the function as a serverless one.

    • Related Articles

    • Authentication - Serverless Functions

      Authentication Method A serverless function within your CRM can be invoked from any third-party application or within the CRM. However, commonly not all of the applications support a single authentication method. Keeping that in mind, we have two ...

    • Overview - Serverless Functions

      Serverless architecture, also known as “Function-as-a-service”(Faas), provides a platform for developers to execute their own codes in response of various business events. In Zoho CRM, all these codes can be written through deluge scripts and can be ...

    • Using API Key - Serverless Functions

      Introduction A severless function within your CRM can be invoked from any third-party application or within the CRM using a webhook. However, generally most of the webhooks do not support OAuth2, save for a few of them. In that case, you can execute ...

    • Types of Inputs - Serverless Functions

      The input for the function can be acquired in the following types Parameters Parameters are passed in URL of query string and the data passed in the post "form-data" section in an input. The "params" in the crmAPIRequest map contains these parameters ...

    • Request and Response Object - Serverless Functions

      Request object You can get the entire Request Object within the function using the "crmAPIRequest" argument. Say you've created a function and defined 2 arguments. Now you need to use the same function in 2 different webhooks, each of which might ...