Traditionally, related lists in Zoho CRM are created using lookup fields, which establish a direct relationship between records. However, Zoho CRM provides an alternative approach by allowing the creation of custom related lists. These lists enable you to display an filter associated data from multiple modules or sources, offering a more flexible and dynamic representation of information.
In this article, I'll take you through a step-by-step guide to building custom related lists in Zoho CRM, as well as some advanced ways to manipulate the data shown in those custom related lists. The example I'll be using in this tutorial is how to show other deals that are associated with the same account on a deal record. I will start off basic and build on it throughout the article and explain the rational behind the changes.
Configuration & Deployment
To begin we need to setup a related list function.
In settings under developer space select 'Functions'
Click 'New Function'
Enter a both function and display names and select the category to be 'Related List'
Click 'Create'
Click 'Edit Arguments'
Enter the function argument of 'dealId' and set it to type 'String'
Click 'Save'
Copy / Write your code and click 'Save'
Open any deal record and click 'Add Related List'
Click Functions
Click the 'Add Now' button next to the function you have created
Under argument mapping section next to the dealId argument press the '#' key
From the popup select Deals then Deal Id and click 'Done'
Click 'Save'
Screenshots of the steps to take
Data
Custom related lists offer a versatile way to display data from various related records, even if they are not directly linked. This is particularly useful when you need to provide additional context or related details to better understand a record's history or status.
In our example, since deals are not directly linked to each other due to the absence of a lookup field, the system does not provide a related list to display this information. We can however return all deals related to the account using deluge
XML Format Example
A custom related list function must return the data in an XML String and not just as a list of JSON maps.
This is the following XML format we need to return to display the data.
<record>
<row no="0">
<FL val="Name1">value1</FL>
<FL val="Name2">value2</FL>
<FL val="Name3">value3</FL>
</row>
<row no="1">
<FL val="Name1">value1</FL>
<FL val="Name2">value2</FL>
<FL val="Name3">value3</FL>
</row>
</record>We can also return back an message if no data is found in this format.
<error>
<message>error message</message>
</error>XML Errors
If there is an issue with your XML String you will see this error when viewing the related list on the record. When this occurs review your code and run the function inside the script builder to check for errors.
V1 Example Code
This is are V1 basic custom related list where we get all the deals associated to the account and then we convert those deals into an XML String.
V1 Example Result
In this example, we can see all deals associated with the account being displayed on the deal record. However, you may have noticed a few issues with it:
The deal we are currently viewing is included in the list
There is a 'null' value for a deal that has no closing date
The dates are formatted as yyyy-MM-dd
The amount value is not formatted
The deals listed are not ordered in any particular way
There are no links to the records listed
In the next part of the article, we will explore more advanced features to leverage the custom related lists and ensure the data is displayed exactly as desired, addressing all the issues mentioned above.
Filtering
As a custom related list is created by a custom function this allows us to manipulate the data collected before displaying it. This means we can filter out data we don't want to display or deem irrelevant at the time.
Using our example above, we can update our code to filter out the deal that we are currently viewing and while we are at it, lets also filter out closed deals so we are only showing the the accounts open deals.
V2 Example Code
V2 Example Result
Linking Data & Formatting
Now that we have the right data being displayed in the related list, it is important to create a link to open the corresponding record. This feature is crucial and can be easily achieved in a custom related list. To accomplish this, we need to modify our FL Tag in the XML to include both a link and URL attribute, as shown in the example below:
<FL link='true' url='https://www.url.com' val='Name'>Value</FL>"If your related list contains date and currency values, you will most likely want to format them from the defaulted yyyy-MM-dd. As dates and currencies differ based on country locale this can be a little tricky. If your crm users are located in one location then you can format all dates and currencies to the same format, however if those users are spread out across the globe you might want to inherit their country locale format.
Date & Time
Each user in the crm selects the country they are located in which defaults the date format for that country locale. e.g. Australia it will be dd/MM/yyyy and in the United States it will be MM/dd/yyyy. Users can also set their time preference which is either 12 or 24 hour time, this data is accessible from the users record and able to be used to format the the date/time when viewing a custom related list.
Currencies
The way currencies are formatted and displayed also varies by country, the best way to do this is by using a regular expression for the preferred format. By creating a list of the countries that format using decimals as a thousands separator we can check the users locale to the list to format the currency correctly otherwise we default to comma to separate thousands.
Comma thousands separator with decimal fractional separator: 1,234.56
amountValue.toDecimal().round(2).toString().replaceAll("(?<!\.\d)(?<=\d)(?=(?:\d\d\d)+\b)",",")Decimal thousands separator with comma fractional separator: 1.234,56
amountValue.toDecimal().round(2).toString().replaceAll("\.",",").replaceAll(("(?<!,\d)(?<=\d)(?=(?:\d\d\d)+\b)"),".");V3 Example Code
V3 Example Result
Sorting
A custom related list is displayed in the order that the record resides in the list. So we just need to sort the list by one of the data points right? Yes, however as we are writing in deluge and dealing with a list of JSON maps its not as easy as running a sort function over the list. I have created an article on how to sort a list of maps by a specific field which you can read in more detail for a more technical explanation of the way we are sorting in this example.
V4 Example Code
V4 Example Result
Dealing with Special Characters
If you use some specific special characters in fields that you want to use in your related list they can cause errors. As we are creating an XML String in our related list some special characters have a predefined meaning and syntax within the XML markup language. These special characters include <, >, ", ', &, and sometimes others, depending on the context.
So how do stop these characters from causing an error in your related list? There are a few options available:
1. You can create a validation rule inside Zoho CRM on fields that are used in the related list, such as Deal Name that restricts the use of these special characters.
2. You can use a series of .replaceAll() functions for these 5 characters and entering there corresponding escape sequence. This works on both column name and values.
Special Charater | Escaped Sequence |
& | & |
< | < |
> | > |
" | " |
' | ' |
You can do this in the formatting section of the code like this.
escapedDealName = deal.get("Deal_Name").replaceAll("&","&").replaceAll("<","<").replaceAll(">",">").replaceAll("\"",""").replaceAll("'","'");
deal.put("Deal_Name",escapedDealName);3. You can use a CDATA Section. This only works on the values that are passed through. and this is what it looks like.
<![CDATA[Special characters in the square brackets are ignored]]>Here is an example including it in the creation of the XML String.
responseXML = responseXML + "<FL val='Deal Name'><![CDATA[" + deal.get("Deal_Name") + "]]></FL>";This is my personal favourite to use, as its cleaner to read in the code.
V5 Example Code
V5 Example Result
I hope this article has equipped you with all the necessary information and practical examples you need to create the ideal custom related list for your Zoho CRM system. By implementing the strategies and techniques outlined here, you can enhance your CRM experience and optimise your data representation. Best of luck in customising your related lists to meet your specific needs!
Need Help? Contact us!
Resources
Comments