Rich Text Fields using Zoho CRM APIs

Rich Text Fields using Zoho CRM APIs

 Hello everyone!

Last week, we discussed Deciding on the type of applications: Self-client or Server-based? This week, we will discuss the Rich Text Field (RTF) and how we can manipulate RTF using Zoho CRM APIs.
In this post, 
  1. What is a Rich Text Field (RTF)?
  2. Use case
  3. Rich Text Field creation in a module using the Create Custom Field API
  4. Adding values to the RTF using the Insert Records API 

  5. Fetch complete data of RTF using the GET - Rich Text Field API 
  6. Updating Rich Text Field using the Update Records API 
  7. Deleting RTF using the Delete Custom Field API
  8. RTF using the COQL API
  9.  RTF using Bulk APIs

1. What is a Rich Text Field?

The Rich Text field is the preferred choice when there is a need for formatted text and a larger character limit. It can accommodate up to 50,000 characters, including HTML elements that are generated when the text is formatted, making it ideal for entries that require styling and organization, such as product descriptions or detailed client communications. Although tooltips can be added to improve user interaction, the rich text field does not support encryption or mandatory input settings.

Using rich text can improve the visual appeal of your information by providing different font styles, colors, and highlights. This allows for effective communication of important details. Bullet points and numbered lists can enhance readability, while bold, italics, or underlined texts can emphasize crucial information. Increased and decreased indents can help organize data, and the strikethrough feature can easily indicate changes or updates.

2. Use case

Consider Zylker, an org that uses Zoho CRM as their sales management system to store reports or feedback on its employees' sales performance report, total revenue, sales breakdown by product, key achievement, challenges faced, action plan, and to-do lists. These are stored in the multi-line field's rich text format type for better visuals and to identify the important information easily.

Let us see how to create RTFs using APIs, and how to access or update RTF using different available APIs. Note that the Rich Text type of multi-line field is supported from version 6.

3. Rich Text Field creation in a module using the Create Custom Field API

To create a rich text field in a module, first know the module's API name using the GET - Modules Metadata API, then create a custom RTF field in that module.

Request URL to create Rich Text Field : 
{api-domain}/crm/v6/settings/fields?module=Employees

Request Method : POST

Sample Input :
{
    "fields": [
        {
            "field_label": "Feedback",
            "data_type": "textarea",
            "length": 50000,
            "textarea": {
                "type": "rich_text"
            },
            "tooltip": {
                "name": "static_text",
                "value": "employee's feedback"
            }
        }
    ]
}


4. Adding values to the RTF using the Insert Records API 

To add values to the created rich text field, you should know its API name. 
Using the api_name of the Employees module, make a GET - Fields metadata API call to get the list of fields (along with their api_name) in the Employees module. Search for the field in which you need to add values to the Rich Text Field. In our case, it is Feedback.

Request URL : {api-domain}/crm/v6/Employees
Request Method : POST

Sample Input :

{
    "data": [
        {
            "Company": "Zylker",
            "Name" : "Patricia Boyle",
            "Email": "patricia@zylker.com",
            "State": "Texas",
            "Feedback": "<b>Sales Performance Report</b><br><br><span style=\"font-style:normal;\"><b>Salesperson Name: </b></span> Patricia<br><b>Reporting Period:</b>  Q1 2024<br><br><b>Total Sales Revenue Generated:</b> <i><u>$250,000</u></i><br><br><b>Sales Breakdown:</b><br><br><ul style=\"list-style-type:disc;list-style-position:inside;padding-inline-start:20px;\"><li style=\"color:rgb(51, 51, 51);\"><p style=\"display:inline;\"><span style=\"color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\">Product A:</span><span style=\"background-color:rgb(93, 195, 90);color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\"> $100,000</span></p></li><li style=\"color:rgb(51, 51, 51);\"><p style=\"display:inline;\"><span style=\"color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\">Product B:</span><span style=\"background-color:rgb(239, 177, 22);color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\"> $80,000</span></p></li><li style=\"color:rgb(51, 51, 51);\"><p style=\"display:inline;\"><span style=\"color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\">Product C: </span><span style=\"background-color:rgb(22, 208, 239);color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\">$70,000</span></p></li></ul><br><b>Key Achievements:</b><br><br><ul style=\"list-style-type:disc;list-style-position:inside;padding-inline-start:20px;\"><li><p style=\"display:inline;\"><span style=\"color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\">Exceeded sales targets for Product A by</span><span style=\"background-color:rgb(255, 255, 255);color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\">  </span><span style=\"background-color:rgb(0, 176, 80);color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\">20%.</span></p></li><li style=\"color:rgb(51, 51, 51);\"><p style=\"display:inline;\"><span style=\"color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\">Secured </span><span style=\"background-color:rgb(125, 207, 123);color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\">5 new clients for Product B</span><span style=\"color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\">, contributing to a </span><span style=\"background-color:rgb(93, 195, 90);color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\">25% increase </span><span style=\"color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\">in sales.</span></p></li><li style=\"color:rgb(51, 51, 51);\"><p style=\"display:inline;\"><span style=\"background-color:rgb(93, 195, 90);color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\">Closed a high-value deal for Product C with a revenue of $50,000.</span></p></li></ul><br><b>Challenges Faced:</b><span></span><br><ul style=\"list-style-type:disc;list-style-position:inside;padding-inline-start:20px;\"><li style=\"color:rgb(51, 51, 51);\"><p style=\"display:inline;\"><span style=\"color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\">Market competition intensified, resulting in</span><span style=\"background-color:rgb(242, 69, 69);color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\"> longer sales cycles</span><span style=\"color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\">.</span></p></li><li style=\"color:rgb(51, 51, 51);\"><p style=\"display:inline;\"><span style=\"color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\">Difficulty in accessing decision-makers for key accounts,</span><span style=\"background-color:rgb(242, 69, 69);color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\"> leading to delays in closing deals</span><span style=\"color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\">.</span></p></li><li style=\"color:rgb(51, 51, 51);\"><p style=\"display:inline;\"><span style=\"color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\">Some clients expressed concerns about pricing,</span><span style=\"background-color:rgb(242, 69, 69);color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\"> requiring additional negotiation efforts</span><span style=\"color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\">.</span></p></li></ul><br><b>Action Plan:</b><br><ol style=\"list-style-type:decimal;list-style-position:inside;padding-inline-start:20px;\"><li style=\"color:rgb(51, 51, 51);\"><p style=\"display:inline;\"><span style=\"color:rgb(51, 51, 51);font-style:normal;\"><b>Targeted Marketing Campaigns:</b></span><span style=\"color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\"> Launch targeted marketing campaigns to increase brand visibility and attract potential clients.</span></p></li><li style=\"color:rgb(51, 51, 51);\"><p style=\"display:inline;\"><span style=\"color:rgb(51, 51, 51);font-style:normal;\"><b>Enhanced Networking:</b></span><span style=\"color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\"> Strengthen networking efforts to establish connections with decision-makers and key stakeholders.</span></p></li><li style=\"color:rgb(51, 51, 51);\"><p style=\"display:inline;\"><span style=\"color:rgb(51, 51, 51);font-style:normal;\"><b>Client Retention Strategy: </b></span><span style=\"color:rgb(51, 51, 51);font-weight:normal;font-style:normal;\">Implement a client retention strategy to address pricing concerns and ensure customer satisfaction.</span></p></li></ol><br><b>To-Do Lists :</b><br>Continued focus on building strong<span style=\"background-color:rgb(255, 255, 0);\"> client relationships</span>, identifying <span style=\"background-color:rgb(255, 255, 0);\">new opportunities</span>, and leveraging resources effectively to<span style=\"background-color:rgb(255, 255, 0);\"> drive further sales growth in the upcoming quarters</span>."
        }
    ]
}


Notes:
  1. If you enter incorrect API names for fields, the system will skip them and the record will be created successfully, but the values won't be added. This rule applies to RTF too.
  2. When using the Insert Records API for bulk records creation and the Update Records API for bulk records update, you can add up to 50,000 characters to RTFs in each record.
  3. For details on supported HTML tags and their attributes, refer to the help document.

The below GIF shows the result of the above input in the UI.

 

When you add values using HTML tags to the RTF via API, the input will be transformed into formatted data.

5. Fetch complete data of RTF using the Rich Text Field API

The Rich Text Field supports up to 50000 characters. Using the GET - Records API, you can fetch only the first 500 characters of the rich text field ('Feedback' in our case) in the response. If the @has_more property in the GET- Records response is true for the Rich Text Field (RTF) value, it indicates that the RTF contains more than 500 characters.


To fetch the entire data, we have introduced the GET - Rich Text Field API in V6, enabling the retrieval of complete data from rich text fields.

Below Sample shows how to fetch full data :

Request URL : {api-domain}/crm/v6/Employees/5725767000002594018/actions/fetch_full_data
Request Method : GET

Response :


6. Updating Rich Text Field using the Update Records API 

Updating a rich text field doesn't require any special steps. It is similar to the process how we update other fields in a record, using the Update Records API.


7. Deleting RTF using the Delete Custom Field API


General notes :
  • Rich text fields are not supported in subforms, List View, Kanban View, Canvas View, Sheet View, Related Lists, Lookup popup, global search, filters and criteria, formula fields, report export, and integrations.
  • Rich text fields are not supported in the Search API.
  • Rich text fields are supported for importing and exporting records, using the Bulk APIs. The data will be exported as HTML content. For example, Patricia will be exported as <b>Patricia</b>.

8. Rich Text Field using the COQL API

Retrieve the Rich Text Fields from a module through a COQL query.  Note that RTFs cannot be used in the criteria. Similar to the GET - Records API, the COQL API response fetches up to 500 characters of the RTFs. To fetch its complete data, use the GET - Rich Text Field API.

Request Method : POST

Sample Input :

 {
    "select_query":"select 'Feedback' from Employees where Company is not null"
 }


Response :


9. Rich Text Field using Bulk APIs

Bulk Read API allows you to fetch a large set of data i.e., you can fetch a maximum of 200,000 records in a single API call. You can export complete data of rich text fields in a module. Note that RTFs cannot be specified in the criteria. 

Request Method: POST

Sample input :

{
    "callback": {
        "method": "post"
    },
    "query": {
        "module": {
            "api_name": "Employees"
        },
        "file_type": "ics"
    }
}


The Bulk Read API is an asynchronous API, the response will not be available instantly; the bulk read job is scheduled. Once the job is completed, it'll be notified in the callback URL. The records are available in a downloadable CSV file or ICS file (for events). 

Below is a sample downloaded CSV file:
Unlike the GET - Records API, the Bulk Read API fetched the RTF's complete data.



See our Bulk Read API documentation to know how to view the status of the scheduled job and download the file in detail, along with more sample requests and responses.

Bulk Write API allows you to insert, update, or upsert a large set of data. In the CSV file module, using the Bulk Write API, you can add up to 50000 characters to the RTFs for each record in a row.

Prepare your CSV file
The Bulk Write API only accepts a CSV file compressed into a ZIP file as input. 

Below picture represents values added to the rich text field:

Please ZIP the CSV file once you add values to the Rich Text Field.

Upload your CSV file :
This involves making a POST API call, with the ZIP file containing the required data. 

Headers
               Header Name
                                   Description
 feature
 bulk-write
 X-CRM-ORG
 Your zgid which you get from the Organization API

Request Method: POST



Create a bulk write job :
Request URL : {{api-domain}}/crm/bulk/v6/write
Request Method : POST

Sample Input for bulk insert :

{
    "operation": "insert",
    "ignore_empty": true,
    "callback": {
        "method": "post"
    },
    "resource": [
        {
            "type": "data",
            "module": {
                "api_name": "Employees"
            },
            "file_id": "5725767000002613001",
            "file_names": [
                "Rich.csv"
            ],
            "field_mappings": [
                {
                    "api_name": "Name",
                    "index": 0
                },
                {
                    "api_name": "Feedback",
                    "index": 1
                },
                {
                    "api_name": "Company",
                    "index": 2
                }
            ]
        }
    ]
}

Refer to our Bulk Write API help document and get more information on how the Bulk Write API works, how to prepare your CSV file, and how to upload your CSV file, and how to check the job status.

We trust that this post meets your needs and is helpful. Let us know your thoughts in the comment section or reach out to us at support@zohocrm.com

Stay tuned for more insights in our upcoming Kaizen posts!

Cheers!

Previous Kaizen Post :
Kaizen #133 - Deciding on the type of applications: Self-client or Server-based?                                                                              

Additional Reading :

Join us for our upcoming Zoho CRM Developer Series: Zoho CRM APIs, where you can explore more about Zoho CRM APIs. Register Now!


    Access your files securely from anywhere

        Zoho Developer Community







                                  Zoho Desk Resources

                                  • Desk Community Learning Series


                                  • Digest


                                  • Functions


                                  • Meetups


                                  • Kbase


                                  • Resources


                                  • Glossary


                                  • Desk Marketplace


                                  • MVP Corner


                                  • Word of the Day



                                      Zoho Marketing Automation


                                              Manage your brands on social media



                                                    Zoho TeamInbox Resources

                                                      Zoho DataPrep Resources



                                                        Zoho CRM Plus Resources

                                                          Zoho Books Resources


                                                            Zoho Subscriptions Resources

                                                              Zoho Projects Resources


                                                                Zoho Sprints Resources


                                                                  Qntrl Resources


                                                                    Zoho Creator Resources



                                                                        Zoho Campaigns Resources


                                                                          Zoho CRM Resources

                                                                          • CRM Community Learning Series

                                                                            CRM Community Learning Series


                                                                          • Kaizen

                                                                            Kaizen

                                                                          • Functions

                                                                            Functions

                                                                          • Meetups

                                                                            Meetups

                                                                          • Kbase

                                                                            Kbase

                                                                          • Resources

                                                                            Resources

                                                                          • Digest

                                                                            Digest

                                                                          • CRM Marketplace

                                                                            CRM Marketplace

                                                                          • MVP Corner

                                                                            MVP Corner





                                                                              Design. Discuss. Deliver.

                                                                              Create visually engaging stories with Zoho Show.

                                                                              Get Started Now