Kaizen #109 Record Locking Configuration APIs in Zoho CRM

Kaizen #109 Record Locking Configuration APIs in Zoho CRM

Hello everyone!

Welcome to Kaizen! In this post, we will discuss Record Locking Configuration APIs in Zoho CRM.

What is Record Locking?

Record Locking refers to the restrictions that you can apply to records of a module to prevent further changes to the data. You can either lock records manually or set conditions to lock them automatically.
   You can add record locking configuration to a module through the module builder. Go to Setup > Customization > Modules and Fields > {Module} > Record Locking Configuration. Record Locking is supported for Leads, Accounts, Contacts, Deals, Tasks, Cases, Solutions, Vendors, Price Books, Quotes, Sales Orders, Purchase Orders, Invoices and Custom modules.
Record Locking Configuration in UI
These options are available in record locking configuration:
  • You can lock all profile records or give exception to some profiles.
  • You can lock the activities you choose. The Edit option is limited by default. You can also limit delete action, adding tags, changing owner, sending emails or using custom buttons. 
  • You can have the option of editing certain fields even when the record is locked.

Automatic record locking 

Automatic record locking refers to the locking of records based on certain conditions. For instance, consider that a deal with a seller is in the closed won stage, and you want to prevent further changes to the deal record. You can achieve this using the record locking feature.
You can configure record locking for deals module to automatically lock a record when it reaches the closed won stage. You can specify rules for locking records. There can be up to five rules per module.

Manual Record Locking

Manual record locking is the intentional locking of a record by a user.  To do this, the user's profile should have adequate permission. Profile permissions can be set in Setup > Users and Control > Security Control> Profiles > {Profile Name} > Module Permissions > Tools > Lock.

Record Locking Configuration APIs

Record locking configuration APIs allows you to set up the configuration needed to lock the records in modules manually or automatically via APIs. 
The fields in Record Locking Configuration APIs are:

Name
Date Type
Description
locked_for
String
Represents whether records are locked for all profiles or some profiles. Possible value : all_profiles_except_excluded_profile or all_profiles
lock_excluded_profiles
String
Represents the profiles that are restricted from locking when  locked_for value is all_profiles_except_excluded_profile
excluded_fields
JSON Array
Represents the fields that are excluded from record locking
feature_type
String
Represents feature type, its value is record_locking for this case
locking_rules
JSON Array
Represents the details of rules added to lock the records in the module automatically. This array includes the name, id and criteria of locking rules. The field lock_existing_records indicates whether the existing record must be locked or not.
restricted_actions
JSON Array
Specifies the actions that are restricted for locked records. Possible values: update, delete, tags, change_owner
lock_for_portal_users
Boolean
Indicates whether locked records are restricted for portal users.
restricted_communications
JSON Array
Specifies types of communication that are restricted for locked records. Possible value: send_mail
system_defined
Boolean
Indicates whether the record configurations are system defined.
lock_type
String
Represents the type of the record locking configuration - manual, automatic, both
restricted_custom_buttons
JSON Array
Represents the name and id of custom buttons that are restricted for locked records.

Add Record Locking Configuration API

Using this API, you can configure record locking for the supported modules. 

Request URL:
{api-domain}/crm/{version}/settings/record_locking_configurations?module={module_API_name}
HTTP Method: POST
Let us consider the case of locking a deal automatically when it is in the closed won stage. 
Request URL to configure record locking for deals module:
{api-domain}/crm/v5/settings/record_locking_configurations?module=Deals

The below request body locks the records from editing for all profiles when the Deal Stage is Closed Won (lockings_rules).  The key lock_existing_records specify whether the rule should be applied for existing records. The record is locked for all profiles (locked_for) and the only field that is excluded from locking is the description field (excluded_fields). The record will be locked for portal users (lock_for_portal_users). Edit action is restricted for the lock record (restricted_actions). 

Request body:
{
  "record_locking_configurations": [
    {
      "locked_for": "all_profiles",
      "excluded_fields": [
        {
          "api_name": "Description"
        }
      ],
      "feature_type": "record_locking",
      "locking_rules": [
        {
          "name": "Closed Won",
          "lock_existing_records": true,
          "criteria": {
            "comparator": "equal",
            "field": {
              "api_name": "Stage"
            },
            "value": "Closed Won"
          }
        }
      ],
      "restricted_actions": [
        "update"
      ],
      "lock_for_portal_users": true,
      "restricted_communications": null,
      "system_defined": false,
      "lock_type": "automatic",
      "restricted_custom_buttons": null,
      "lock_excluded_profiles": null
    }
  ]
}

From the response of this API you will get the id of the record locking configuration.

The criteria JSON object inside the locking_rules JSON array consists of the comparator, field and value of the fields that form the locking rule of the configuration. If you want to give multiple conditions in one locking rule, you can use group_operator and group keys. The possible values for group_operator are AND, OR. For example, consider that you want to add a locking rule for Closed Lost deals which includes deals with Stage Closed Lost and Closed - Lost to Competition. This can be achieved by giving the locking_rules as shown below:
.
.
"locking_rules": [
                {
                    "name": "Closed Lost",
                    "lock_existing_records": true,
                    "criteria": {
                        "group_operator": "OR",
                        "group": [
                            {
                                "comparator": "equal",
                                "field": {
                                    "api_name": "Stage"
                                },
                                "value": "Closed Lost"
                            },
                            {
                                "comparator": "equal",
                                "field": {
                                    "api_name": "Stage"
                                },
                                "value": "Closed-Lost to Competition"
                            }
                        ]
                    }
                }
]
.
.

Get Record Locking Configuration API

Use this API to retrieve the details of record locking configuration for a particular module.
Request URL:
{api-domain}/crm/{version}/settings/record_locking_configurations?module={module_API_name}
HTTP Method: GET
Request URL to  retrieve the record locking configuration for deals module:
{api-domain}/crm/v5/settings/record_locking_configurations?module=Deals
{
    "record_locking_configurations": [
        {
            "created_time": "2023-10-23T03:25:06-04:00",
            "locked_for": "all_profiles",
            "excluded_fields": [
                {
                    "api_name": "Description",
                    "id": "5843104000000002587"
                }
            ],
            "created_by": {
                "name": "Patricia Boyle",
                "id": "5843104000000424672"
            },
            "feature_type": "record_locking",
            "locking_rules": [
                {
                    "name": "Closed Won",
                    "id": "5843104000001068052",//Locking rule ID
                    "lock_existing_records": true,
                    "criteria": {
                        "comparator": "equal",
                        "field": {
                            "api_name": "Stage",
                            "id": "5843104000000002565"// ID of Stage in fields API
                        },
                        "value": "Closed Won"
                    }
                }
            ],
            "restricted_actions": [
                "update"
            ],
            "lock_for_portal_users": true,
            "modified_time": "2023-10-23T03:42:00-04:00",
            "restricted_communications": null,
            "system_defined": false,
            "modified_by": {
                "name": "John Smith",
                "id": "5843104000000424001"
            },
            "id": "5843104000001068044",
            "lock_type": "automatic",
            "restricted_custom_buttons": null,
            "lock_excluded_profiles": null
        }
    ]
}

Update Record Locking Configuration API

Consider that you want to edit the above record locking configuration in deals module. You want to enable manual locking and also add a new rule to lock deals in stage closed lost. This can be done using the Update Record Locking Configuration API. 
Request URL:
{api-domain}/crm/{version}/settings/record_locking_configurations?module={module_API_name}
OR 
{api-domain}/crm/{version}/settings/record_locking_configurations/{record_locking_config_id}?module={module_API_name}
HTTP Method: PUT
Note that you should mention the ID of the record locking configuration inside the request body if you are using the endpoint that does not have the ID. 
When you specify a valid locking rule ID (obtained from Get Record Locking Configuration API) in the input body, the corresponding locking rule will be updated. When ID is not mentioned it will be considered as a new rule. 
In addition to adding or modifying existing locking rules in a specific record locking configuration, you can also delete locking rules using Update Record Locking API. When "_delete" key with value true is given in the input body, the locking rule will be deleted.

Example for deleting a record locking rule using update record locking configuration API 
Request URL: {api-domain}/crm/v5/settings/record_locking_configurations?module=Deals
HTTP Method: PUT

{
    "record_locking_configurations": [
        {
            "locking_rules": [
                {
                    "id": 5843104000001068052,//ID of record locking rule
                    "_delete": true
                }
            ],
            "id": "5843104000001068044"//ID of the record locking configuration
        }
    ]
}

Delete Record Locking Configuration API

   You can use this API to delete Record Locking Configuration for a module. Please note that deleting the record locking configuration of a module unlocks all the locked records of that module.
Request URL:
{api-domain}/crm/{version}/settings/record_locking_configurations/{record_locking_config_id}?module={module_API_name}
HTTP Method:DELETE
Request URL to  delete the record locking configuration for deals module:
 {api-domain}/crm/v5/settings/record_locking_configurations?module=Deals

We hope you found this post on the Record Locking Configuration APIs useful. In next week's Kaizen we will cover Record Locking APIs  that enable users to access locking details for locked records, to lock/unlock manually, and to edit the locked reason for manually locked records.
If you have any questions, write to us at support@zohocrm.com or let us know in the comment section.
For more such posts that are part of our Kaizen series, please refer to our Kaizen collection here.

Cheers!




    • Sticky Posts

    • Kaizen #197: Frequently Asked Questions on GraphQL APIs

      🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.
    • Kaizen #198: Using Client Script for Custom Validation in Blueprint

      Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.
    • Celebrating 200 posts of Kaizen! Share your ideas for the milestone post

      Hello Developers, We launched the Kaizen series in 2019 to share helpful content to support your Zoho CRM development journey. Staying true to its spirit—Kaizen Series: Continuous Improvement for Developer Experience—we've shared everything from FAQs
    • Kaizen #193: Creating different fields in Zoho CRM through API

      🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.
    • Client Script | Update - Introducing Commands in Client Script!

      Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands
    • Recent Topics

    • Automatic Matching from Bank Statements / Feeds

      Is it possible to have transactions from a feed or bank statement automatically match when certain criteria are met? My use case, which is pretty broadly applicable, is e-commerce transactions for merchant services accounts (clearing accounts). In these
    • Where is the desktop app for Zoho Projects???

      As a project manager, I need a desktop app for the projects I manage. Yes, there's the web app, which is AWESOME for cross browser and platform compatibility... but I need a real desktop app for Projects that allow me to enter offline information where
    • Prevent duplicate with custom fields?

      I was wondering something about custom field/custom modules in Zoho Desk. For some reason you can make a custom field mandatory but not unique? For example, if I create a custom module to manage equipment and renewal and make a field serial number no
    • How to Automate Monthly PDF Reports with Filters in Zoho Creator

      Hi everyone, I’m trying to build an automated monthly reporting process in Zoho Creator and would appreciate suggestions or best practices from anyone who has done something similar. What I’m trying to do: I have a form called New_Customer with fields
    • Feedback: Streamlining Note Management in Zoho Notebook

      Dear Team/Support, I would like to share some feedback regarding the note management system that could help improve usability and accessibility for users like myself. Notebook 1 (screenshot attached): Currently, the system does not allow selecting and
    • showing Limit exceeded

      Good afternoon...trust you're good. I've been having issues working with but it's not responding. it's showing Limit exceeded, sorry it seems like too many people are working on the sheet right now please try again later. meanwhile no one is working on
    • Converting Sales Order to Invoice via API; Problem with decimal places tax

      We are having problems converting a Sales Order to an Invoice via API Call. The cause of the issue is, that the Tax value in a Sales Order is sometimes calculated with up to 16 decimal places (e.g. 0.8730000000000001). The max decimal places allowed in
    • Sorting columns in Zoho Projects

      Hi, In project management best practice, sorting columns (ascending, descending) is an important tool. Sorting dates to see the order of tasks starting, sorting on priority or even on planned hours is a must for an efficient project control. Currently,
    • CRM : Function to add user name to text field

      I have a lookup field in a module that is linked to the CRM users so we can assign a Project Lead to the customer. Sadly Zoho Marketing Automation doesn't sync Lookup fields so I need to extract information from the lookup to text fields: Lookup field
    • Upload API

      I'm trying to use the Upload API to upload some images and attach them to comments (https://desk.zoho.com/DeskAPIDocument#Uploads#Uploads_Uploadfile) - however I can only ever get a 401 or bad request back. I'm using an OAuth token with the Desk.tickets.ALL
    • Losing description after merging tickets

      Hello, We merge tickets when they are about the same topic from the same client. It happens sometimes. We recently noticed that after the merger only the description from the master ticket is left in a thread. And the slave-ticket description is erased.
    • Option to Empty Entire Mailbox or Folder in Zoho Mail

      Hello Zoho Mail Team, How are you? We would like to request an enhancement to Zoho Mail that would allow administrators and users to quickly clear out entire folders or mailboxes, including shared mailboxes. Current Limitation: At present, Zoho Mail only
    • update linked contacts when update happens in account

      Hi, I have a custom field called Licence in the Accounts module. When someone buys a licence, I’d like to update a custom field in the related Contacts. How can I achieve this? I noticed that workflows triggered on Accounts only allow me to update fields
    • Problem Management Module

      I am looking for a Problem Management module within Zoho Desk. I saw in some training videos that this is available, and some even provided an annual price for it. I want an official confirmation on whether this is indeed available. This is not a particularly
    • Deluge sendmail in Zoho Desk schedule can't send email from a verified email address

      I am trying to add a scheduled action with ZDesk using a Deluge function that sends a weekly email to specific ticket client contacts I've already verified the email address for use in ZDesk, but sendmail won't allow it in its "from:" clause. I've attached
    • Unable to explore desk.zoho.com

      Greetings, I have an account with zoho which already has a survey subscription. I would like to explore desk.zoho.com, but when I visit it while logged in (https://desk.zoho.com/agent?action=CreatePortal) I just get a blank page. I have tried different
    • Offline support for mobile app

      Accessing your files and folders from your mobile devices is now quicker and simpler, thanks to the power of offline support. Whether on an Android or iOS device, you can use the Offline function to save files and folders, so you can review them even
    • Zoho Desk KB article embedded on another site.

      We embed KB articles from Zoho Desk on another site (our application). When opening the article in a new tab, there is no issue, but if we choose lightbox, we are getting an error "To protect your security, help.ourdomain.com will not allow Firefox to
    • Transitioning to API Credits in Zoho Desk

      At Zoho Desk, we’re always looking for ways to help keep your business operations running smoothly. This includes empowering teams that rely on APIs for essential integrations, functions and extensions. We’ve reimagined how API usage is measured to give
    • List of packaged components and if they are upgradable

      Hello, In reference to the article Components and Packaging in Zoho Vertical Studio, can you provide an overview of what these are. Can you also please provide a list of of components that are considered Packaged and also whether they are Upgradable?
    • Does Attari Messaging app have Bot option and APIB

      Hi, Does Attari also have Bot and API as we use in WhatsApp??
    • how to use validation rules in subform

      Is it possible to use validation rules for subforms? I tried the following code: entityMap = crmAPIRequest.toMap().get("record"); sum = 0; direct_billing = entityMap.get("direct_billing_details"); response = Map(); for each i in direct_billing { if(i.get("type")
    • How to add application logo

      I'm creating an application which i do not want it to show my organization logo so i have changed the setting but i cannot find where to upload/select the logo i wish to use for my application. I have seen something online about using Deluge and writing
    • Introducing Keyboard Shortcuts for Zoho CRM

      Dear Customers, We're happy to introduce keyboard shortcuts for Zoho CRM features! Until now, you might have been navigating to modules manually using the mouse, and at times, it could be tedious, especially when you had to search for specific modules
    • Empowered Custom Views: Cross-Module Criteria Now Supported in Zoho CRM

      Hello everyone, We’re excited to introduce cross-module criteria support in custom views! Custom views provide personalized perspectives on your data and that you can save for future use. You can share these views with all users or specific individuals
    • Send Automated WhatsApp Messages and Leverage the Improved WhatsApp Templates

      Greetings, I hope all of you are doing well. We're excited to announce a major upgrade to Bigin's WhatsApp integration that brings more flexibility, interactivity, and automation to your customer messaging. WhatsApp message automation You can now use
    • Verifying Zoho Mail Functionality After Switching DNS from Cloudflare to Hosting Provider

      I initially configured my domain's (https://roblaxmod.com/) email with Zoho Mail while using Cloudflare to manage my DNS records (MX, SPF, etc.). All services were working correctly. Recently, I have removed my site from Cloudflare and switched my domain's
    • Zoho Analytics Regex Support

      When can we expect full regex support in Zoho Analytics SQL such as REGEXP_REPLACE? Sometimes I need to clean the data and using regex functions is the easiest way to achieve this.
    • Change of Blog Author

      Hi, I am creating the blog post on behalf of my colleague. When I publish the post, it is showing my name as author of the post which is not intended and needs to be changed to my colleague's name. How can I change the name of the author in the blogs?? Thanks, Ramanan
    • Show Attachments in the customer portal

      Hi, is it possible to show the Attachments list in the portal for the particular module? Bests.
    • Does Zoho Docs have a Line Number function ?

      Hi, when collaborating with coding tasks, I need an online real time share document that shows line numbers. Does Zoho's docs offer this feature ? If yes, how can I show them ? Regards, Frank
    • Please make it easier to Pause syncing

      right now it takes 3 clicks to get there. sounds silly, but can you make it just 2 clicks to get it done instead? thats how dropbox does it, 2 clicks to pause instead of 3.
    • Feature Request - Insert URL Links in Folders

      I would love to see the ability to create simple URL links with titles in WorkDrive. or perhaps a WorkDrive extension to allow it. Example use case: A team is working on a project and there is project folder in WordDrive. The team uses LucidChart to create
    • Organization Emails in Email History

      How can I make received Org Emails to show up here?
    • how to differentiate if whatsapp comes from certain landing page?

      I create a Zobot in SalesIQ to create a Whatsapp bot to capture the lead. I have 2 landing pages, one is SEO optimized and the other want is optimized for leads comes from Google Ads. I want to know from which landing page this lead came through WhatsApp
    • How to sync from Zoho Projects into an existing Sprint in Zoho Sprints?

      Hi I have managed to integrate Zoho Projects with Zoho Sprints and I can see that the integration works as a project was created in Zoho Sprints. But, what I would like to do is to sync into an existing Zoho Sprints project. Is there a way to make that
    • How to record company set up fees?

      Hi all, We are starting out our company in Australia and would appreciate any help with setting up Books accounts. We paid an accountant to do company registration, TFN, company constitution, etc. I heard these all can be recorded as Incorporation Costs, which is an intangible asset account, and amortised over 5 years. Is this the correct way to do it under the current Australian tax regulations? How and when exactly should I record the initial entry and each year's amortasation in Books? Generally
    • How to create a drop down menu in Zoho Sheets

      I am trying to find out, how do I create a drop down option in Zoho sheet. I tried Data--> Data Validation --> Criteria --> Text  --> Contains. But that is not working, is there any other way to do it.  Thanks in Advance.
    • Show Payment terms in Estimates

      Hi,  we are trying to set up that estimates automatically relates payment terms for the payment terms we introduced on Edit contact (Field Payment terms).  How can it be done? Our aim is to avoid problems on payment terms introduced and do not need to introduce it manually on each client (for the moment we are introducing this information on Terms and Conditions.  Kind Regards, 
    • Rich-text fields in Zoho CRM

      Hello everyone, We're thrilled to announce an important enhancement that will significantly enhance the readability and formatting capabilities of your information: rich text options for multi-line fields. With this update, you can now enjoy a more versatile
    • Next Page