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!




    • Recent Topics

    • How to get fields centered in a form?

      Is it possible to center fields in a form? Some of my forms do some don't and it is really not aestheticly pleasing?  Any help would be greatly appricated. Thanks, Michael McNeill 

    • Make Packages from multiple sales order of a single customer

      Our customers sends orders to us very frequently, some times what customer wants is to ship items from 5 to 6 sales orders in a single shipment. it will be very nice if, zoho can implement this function, in which we can select items from other sales orders of the customer.

    • Webhooks and Integration

      Hey, I was looking to create automation using webhooks or something equivalent of a trigger based mechanism, to connect it as an integration. But I don't find any relevant APIs to setup these webhooks/notifcations for the "Zoho Books". Can anyone please

    • Zoho Books X Zoho Expense

      Hello there, Please can you tell me if it is possible to sync from Books to Expense? I much prefer the Expense reports to that of Books and the Credit Card feeds work via expense and not Books for me. However I find books is much better to deal with the

    • ABILITY TO LOG INTO CUSTOMER PORTAL

      I think it would be very helpful to have a button in Zoho Books to be able to see the customer portal so we can see what they see to help them navigate through the portal. Many times, the customer will call about the portal, but without visibility into

    • Sort, filter & save views for BOOKS PROJECTS

      Thanks for all the updates. Our firm uses the module for simple internal project accountancy. This means we do everything from the Projects Section but this isn't user friendly at all. You can't do anything with customized your own fields which basically

    • edit input format in custom field - sales order

      hi, I want to integrate a custom field (multi line text box) in our sales order. It needs to show upper case and lower case letters, numbers, spaces, hyphens and "/". What do I need to put in the custom format to configure these signs? Thanks, Tina

    • This transaction type cannot be matched with a line on the statement.

      When using the books API https://www.zohoapis.com/books/v3/banktransactions/uncategorized/${transaction.transaction_id}/match I get this error "This transaction type cannot be matched with a line on the statement." What I'm doing is for the uncategorized

    • Full Text Customization & Translation in SalesIQ Chat Widget Settings

      Dear Zoho SalesIQ Team, Greetings, We would like to request an important enhancement to the chat widget customization options in Zoho SalesIQ. Current Limitation: At the moment, only some of the text shown in the chat widget is editable or translatable

    • Timesheets

      I wanted to create the timesheets remainder for our team mates who miss out the weekly timesheet entries. While creating the email templates, I couldn't see anything related to timesheets. Since it shows projects Can you help me find and build a one

    • Can we embed a Kanban Type of report using iframe too?

      I tried embedding a report as iFrame but it only appear as List View. It would be helpful if can also embed a Kanban Type of report.

    • Weekly Tips : Save Time with Saved Search

      Let's assume your work requires you to regularly check emails from important clients that have attachments and were sent within a specific time period. Instead of entering the same conditions every time—like sender, date range, and attachments included—you

    • Big Things Just Dropped in the SalesIQ Universe: Top Upgrades You’ll Love in Nova’25

      Nova'25 has landed, and it’s packed with meaningful upgrades to help you engage smarter, work faster, and scale with ease. Whether you're into proactive messaging, smarter automation, or better admin control, there's something here for everyone. Here's

    • Hidden Fields with Data Pre-Population and Notification Integration in Zoho Bookings Forms

      Dear Zoho Bookings Support Team, We'd like to propose a feature enhancement for Zoho Bookings forms that would improve data management and workflow efficiency: the ability to create hidden fields with pre-populated data. Current Functionality: Zoho Bookings

    • Tip #37 – How to ensure compliance and accountability using Advanced Session Audit – ‘Insider Insights’

      Hello Zoho Assist Community! This week we will be discussing how to strengthen your remote support operations with better visibility and control. Let’s say your support team handles a growing number of remote sessions each day. At the end of the week,

    • Replace an existing zoho show file with an uploaded one.

      For Zoho WorkDrive Upload API method, I have override-name-exist option, which I can use like this: curl https://www.zohoapis.eu/workdrive/api/v1/upload \ -F "filename=mypres.pptx" \ -F "parent_id=j3tzq1ae09c0cd91540df8d01670af05b657e" \ -F "override-name-exist=true"

    • Tip of the Week #66– Use internal comments to collaborate and resolve issues faster!

      Ever found yourself stuck on a customer query because you needed inputs from your teammate? Or sent a reply too soon and realized later that someone else on your team had a better context? When you rely on back-and-forth messages in external chats or

    • Using Zoho One to manage two (or more) businesses

      We are one company that operates two business, a scenario that Zoho One doesn't really seem to handle very well, and one which I can't imagine is at all unique to us! (It is basically designed to facilitate branding and use for one business only per subscription).

    • Skip order confirmation step in commerce?

      We have a store to sell products that are not shipped to a customer. Right now, when the order is placed, we have to manually 'confirm' the order so the sales order can convert to an invoice and charge the customer.  Is there a way to skip the manual

    • Free Shipping Coupon - Zoho Commerce

      I love the Zoho platform. Zoho Commerce is no exception; however, I'm struggling with a few common features I cannot find or are missing that I hope someone can help me with. Is there a way to create a coupon code for free shipping?

    • Is there a way to link an item to a liability account?

      I collect customer deposits for certain services and hold them in a liability account. However, Zoho Books doesn't let you create an item and assign it to a liability account so how do I create an invoice with an item that records it as a deposit into

    • Select a balance sheet account when creating an invoice

      Hi, it would be very helpfull to be able to select a balance sheet account when invoicing clients. We bill 30% of the job at signing and we would like to add to deferred revenues.  I have to create a transit revenue account and then tranfer to the right

    • How to work out commission in zoho commerce based on coupons

      HI There Is there any way to produce report based on coupon name in zoho commerce We need to pay commission to various channels who are helping us to increase the online sales so we have number dedicated coupons assigned to the above mentioned channels

    • Request for Subform Styling Feature in Zoho CRM Canvas

      Dear Zoho CRM Team, We have observed that in the Zoho CRM Canvas view, it is currently not possible to set presets or manage the styles of subform fields. Additionally, the ability to edit subform data directly within the Canvas view appears to be limited

    • How to Delete Old Tasks/Streams Assigned by Deactivated Users? 'Operation Not Permitted' Error

      Hello, I’m using Zoho Mail and have several old tasks assigned to me in Tasks and Streams. These tasks were created by former employees whose accounts are now deactivated. When I try to delete these tasks, I get an "Operation Not Permitted" error. These

    • Zoho Books - Sales Person Contact Details on Quotes

      Hi Zoho Books Team, I've had various clients ask me about showing the phone number and email of the sales person on Quotes to help eliminate any barriers to closing sales. When I tell them that it is not possible they are always surprised and say something

    • Related products category instead recommended products.

      Hi there, It is possible to show related products of the same category (as it works in the rest of the ecommerce) instead of showing recommended products.

    • Uploading PDF files

      How do I upload a PDF file to my ZOHO site?

    • How to send invoices to 2 emails?

      Hi! We are sending invoices to the "Customer email" field that is defined Zoho Books and is obtained/synced from a custom email field in Zoho CRM. But in some clientes, the invoices have to be sent to 2 emails and we are wondering how this could be accomplished.

    • It returns 1 record

      Var1= Tools_Request[Liability_Receipt == input.Liability_No]; for each rec in Var1.Tool_Request_Description { Var2= (ET_Inventory[SKU == rec.Tools_SKU].SKU).getAll(); } info call for Var2 It only fetch 1 record On record file

    • Narrative 5: The essential role of SLAs

      Behind the scenes of a successful ticketing system - BTS Series Narrative 5: The essential role of SLAs Every organization that interacts with customers establishes a timeframe within which agents should respond to queries as part of a service level agreement

    • Nextdoor Integration

      Does Zoho social work with Nextdoor? www.nextdoor.com? Are there any plans for an integration?

    • My email sending has beed blocked due to high bounce rate. NEED HELP

      User ID: 886739811 Dear Zoho Team, I hope this message finds you well. My account (User ID: 886739811) was blocked from sending emails last week due to an unusually high bounce rate. This spike was caused by a bot attack on our platform, which led to

    • Can Zoho CRM Emails be used in Zoho Analytics in any capacity?

      We're wanting to display details about Lead Activity in regular reports through Zoho Analytics but we're having difficulty integrating Emails at all. We'd like to be able to note when an email is received and when it is sent somewhere other than just

    • IF Statement in Zoho CRM Formula Field

      Hi, I am attempting to write a formula field that will give me one result if one statement AND another statement are true, then a different value if the first statement AND a different statement are true, else 0. Stated differently: if account = destination

    • Scheduled Maintenances

      Hi, Why is adding scheduled maintenance so arduous. It should be a simple process and take very little time for basically a recurring job. Creating 3 records with similar data seems crazy to me. Is there a easy way to do this? I have to create hundreds

    • Subform Fields for Form Rules & Subform Fields as a Condition with Form Fields as the Action

      Hi, The Subform in Field Rules is great, but it is missing completley from Form Rules and it lacks being able to have Subform Fields in the Condition while having Form Fields in the Action, it works the other way around. Thanks Dan

    • Power of Automation :: Implementing Deadline-Based Task Scoring with Custom Fields

      Hello Everyone, A custom function is a software code that can be used to automate a process and this allows you to automate a notification, call a webhook, or perform logic immediately after a workflow rule is triggered. This feature helps to automate

    • Zoho Forms - Subform Integration with Zoho CRM?

      I created a form in Zoho Forms that includes a sub-form for information that I want to integrate with the CONTACTS module. I am unable to find a way integrate/map the fields in the sub-form with the Contacts module in Zoho CRM. Is there a way to do this

    • Filter by user in Pivot Chart

      I have a Pivot chart where the data should be filtered by user. The user enters the system and should see only the data that correspond to it. Can anyone help me?

    • Next Page