Table of Contents:

• Required Features
• Key Terms
• Creating a Sandbox environment
• Zoho Fields
• Creating a Custom Button
• Editing Arguments
• Inserting Code
• Using your new button
• Deploying to Production
  
  

Required Features

Zoho CRM Tier:

• Zoho CRM Enterprise: The minimum requirement to build and support API integration to create custom functions behind custom Buttons. These functions include code that makes API calls to external sources such as Aurora. It also Includes a Sandbox environment for testing purposes.

• Zoho One: Encompasses Zoho CRM Enterprise features and also includes Zoho Flows, which unlocks using webhooks in the integration.

Custom fields: Zoho offers 500 custom fields across Zoho that you can use to create fields that store information from Aurora, such as design data, UUIDs, deep links, and more.

Custom Buttons: 50 custom buttons per module.

Zoho Flows: Only included in the Zoho One plan and NOT included in the Zoho CRM Enterprise plan. This plan provides flexibility beyond buttons by accepting webhooks from external sources, such as Aurora, and the ability to make API calls with less coding involved.

Sandbox: For building and testing the API integration before deploying it to Production.

 

Key Terms

Button: A clickable element that triggers a function in Zoho.

Function: The code behind a button that takes input and performs actions.

Deluge: The proprietary scripting programming language in Zoho.

Module: A type of object in Zoho — just like a Project, Design, or Agreement object in Aurora.

 

Creating a Sandbox environment

It is highly recommended to perform the first-time setup in a Sandbox environment before deploying to a Production environment.

To create a Sandbox environment:

1. Navigate to Setup > Data Administration > Sandbox
2. Under ‘Sandbox List’, click on the blue Create New Sandbox button in the top right
3. Input a Name and optional Description
   1. Upon entering a Name, the ‘Access URL’ will autofill with a similarly named URL based on available URLs. You can keep or change this Access URL as desired.
4. Under ‘Type’, choose either Configuration and Data or Configuration
   • Either option will suffice, as you will only need enough data to test the integration in Sandbox first.
5. For ‘Configurations Available In Sandbox’ you can either leave the setting as All, or choose Selected and click on the checkbox under Customization > Modules and Fields.
6. Finally, choose which user(s) will have access to this Sandbox.

Example settings for a new Sandbox environment:

 

Zoho Fields

Note: All of this setup should be done in a sandbox environment first. Your sandbox URL will appear like this: https://crmsandbox.zoho.com/crm/{sandbox_name}

Fields that are already in Zoho:

• Lead ID
• Street
• City
• State
• Zip Code
• Country
• First Name
• Last Name
• Phone
• Email

The one additional field required is “Aurora Project URL” field. This field becomes a link directly to the corresponding Project in Aurora.

1. Navigate to Setup (gear icon in the top right).
2. Under Customization, click on Modules and Fields
3. In the middle section, click on Leads and navigate to Fields tab. Any module can be used, such as Deals, depending on your workflow.
4.  
5. Note: If you use a different module than this Guide, ensure the custom field, buttons, and workflow point to that Module.
6. Click on Create and Edit Fields (the blue button in the top right).
   • If you have more than 1 layout, select a Layout before continuing
7. Click and drag a URL field from the left side to the layout on the right.
8. Name your new URL field as desired, such as “Aurora Project URL”.
9. Click the white Save and Close button in the top right.
   
   

Creating a Custom Button

1. Since you’re already in the Modules and Fields, click on the Buttons tab.
2. From the Buttons tab on the top, click the blue Create New Button to the right.
3. Button Name: “create_aurora_project” or something similar, as this is how you will find the button in Settings later. Note: cannot contain spaces, but special characters are allowed.

1. • [optional] Add Description: This does not appear for users, so it can be any additional context for other Admins.
2. Select Layout(s): The default layout is automatically selected. If you have more layouts based on different user types, select multiple here.
3. Choose a page to place the button: Choose “In Record” since a Project has only one corresponding record in the CRM.
4. Choose a position in the page: Choose “Details” (recommended) to ensure the button appears when a user navigates to the record. The other options are only when editing the entire record or when creating/cloning a record.
5. Define an action to be performed: Choose “Writing Function” as you’ll be writing a new function.
6. In the Create New Function pop-up, enter the following:
   1. Function Name: “Create Project” or something similar, as you may want to re-use this function on other custom buttons
   2. Display Name: “Create Project” or something similar, as this is how an end-user will view the button in your CRM.
   3. [optional] Description: Provide an explanation for those re-using the function later.

Upon form completion, it will appear similar to this:

 

Editing Arguments

1. Click on Edit Arguments at the top middle of the page to reveal a pop-up.
2. To input a variable, click in the Param Value box and type # to see the list of possible variables from the current module.
3. Use the empty drop-down and scroll or search for the existing Zoho field.
4. Click on the green + to add each additional argument.
5. Enter these recommended variables that map to an Aurora Project:

   Deluge field	Zoho field	Mapped Aurora field
   leadId	Leads - Lead Id	external_provider_id
   leadStreet	Leads - Street	part of the location.property_address field
   leadCity	Leads - City	part of the location.property_address field
   leadState	Leads - State	part of the location.property_address field
   leadCountry	Leads - Country	part of the location.property_address field
   leadZip	Leads - Zip Code	part of the location.property_address field
   customerFirstName	Leads - First Name	customer_first_name
   customerLastName	Leads - Last Name	customer_last_name
   customerEmail	Leads - Email	customer_email
   customerPhone	Leads - Phone	customer_phone

   When filled out, the mapped arguments will appear like this:

6. Click Save in the bottom-right of the pop-up.
   
   

Inserting Code

Copy the below code and paste it into the code editor space.

// lead data
currentLeadId = if(!leadId == null,leadId,"");
// check if Aurora Project already exists
if (zoho.crm.getRecordById("Leads", currentLeadId).getJSON("Aurora_Project_URL") != NULL) {
	return "Aurora Project already exists";
}
street = leadStreet;
city = leadCity;
state = leadState;
zipCode = leadZip;
country = if(!leadCountry == null,leadCountry,"");
// customer data from lead
firstName = if(!customerFirstName == null,customerFirstName,"");
lastName = if(!customerLastName == null,customerLastName,"");
phone = if(!customerPhone == null,customerPhone,"");
email = if(!customerEmail == null,customerEmail,"");
info leadId;
// Aurora Credentials:
tenantId = "your-tenant-id";
bearerToken = "sk_sand_********";
// Map input arguments to data for Zoho to send to Aurora
locationObject = Map();
locationObject.put("property_address",street + " " + city + " " + state + " " + zipCode + " " + country);
mp = Map();
mp.put("external_provider_id",currentLeadId);
mp.put("name",firstName + " " + street);
mp.put("customer_first_name",firstName);
mp.put("customer_last_name",lastName);
mp.put("customer_email",email);
mp.put("customer_phone",phone);
mp.put("location",locationObject);
projectPayload = Map();
projectPayload.put("project",mp);
info projectPayload;
// Make the API call and store the response
response = invokeurl
[
	url :"https://api-sandbox.aurorasolar.com/tenants/" + tenantId + "/projects"
	type :POST
	parameters:projectPayload.toString()
	headers:{"Accept":"application/json","Content-Type":"application/json","Authorization":"Bearer " + bearerToken}
];
info response;
// parse through JSON response to get project_id
projectResponse = response.getJSON("project");
projectId = projectResponse.getJSON("id");
// Create the Project's deep link in Aurora to store in Zoho
projectOverviewURL = "v2-sandbox.aurorasolar.com/projects/" + projectId + "/overview/dashboard";
// Set field values in Zoho from response
leadInfo = {"Aurora_Project_URL":projectOverviewURL};
zoho.crm.updateRecord("Leads",currentLeadId,leadInfo);
info leadInfo;
// Displays a message when the button is clicked and the function completes
return "Aurora Project Created";

 

1. Replace tenantId with your sandbox Tenant ID and bearerToken with your sandbox Bearer token. These can both be found at https://v2-sandbox.aurorasolar.com/settings/api/tokens
2. Click Save and Execute at the top right to test the code directly from this code editor page. You’ll be prompted to enter Lead information for this run.
3. Once you click Save, you will be returned to the button setup screen.
   
   

Using your new button

Now that you’ve created your button, you can find it by clicking on any Lead, and it’ll appear in the top right.

Note: If you have other custom buttons, it may appear in the arrow dropdown menu of buttons

If any required fields are not filled out, you will see a warning message. Otherwise, you can close this pop-up and the page will refresh automatically. Your Aurora Project URL field will be populated with a clickable deep link into the Project Overview page in Aurora.

Note: If there is already a value in the Aurora Project URL field, you will see an error message “Aurora Project already exists”. This message can be customized by editing the code at the top:

if (zoho.crm.getRecordById("Leads", currentLeadId).getJSON("Aurora_Project_URL") != NULL) {
	return "Aurora Project already exists";
}

 

Deploying to Production

1. In Zoho CRM, go to Setup > Data Administration > Sandbox
2. Click on the Sandbox where you initially created the Button
3. Under ‘Change Set List’, click on the checkbox next to your Button
4. Click on Deploy changes to Production
   • Note:If there are conflicts, you will have to resolve conflicts, such as a Layout, Profile, or Button that doesn’t exist in Production. Once they are resolved, you will see a screen like this one:
5. Click Yes, proceed.
6. Once the deployment has completed, navigate to your Button in Setup > Customization > Modules and Fields > (Module) > Buttons
7. Click on your Button from the list
8. Next to ‘Define an action to be performed’, click on Edit
9. At the top of the pop-up, click on Edit Function
10. In the code editor, replace the Aurora sandbox values with their Aurora production values.
    • Replace api-sandbox with api
    • Replace the sandbox tenantId with your production tenantId
    • Replace the sandbox bearerToken with your production bearerToken
    • Replace “v2-sandbox” in the projectOverviewUrl with “v2”

• Click Save. Note: If you click Save and Execute, the action will cost Aurora credits as per your plan since it now points to your Production tenant.