Add Record Locking Configuration

Purpose

To add record locking configuration for different modules.

Endpoints

POST /settings/record_locking_configurations?module={module_API_name}

Request Details

Request URL

{api-domain}/crm/{version}/settings/record_locking_configurations?module={module_API_name}

Supported modules

Leads, Contacts, Accounts, Deals, Quotes, Sales Orders, Purchase Orders, Invoices, Vendors, Price Books, Cases, Solutions, Tasks, Products and custom modules

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.record_locking_configurations.Create

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/record_locking_configurations?module=Leads"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-X POST
-d "@addrecordlockconfig.json"

Parameters

modulestring, mandatory
Specify the API name of the module for which you want to add record-locking configuration.

Note

For custom modules, only those created by users will support record locking. Custom modules created through extensions, integrations, or other means are not supported.

Input JSON Keys

lock_typestring, mandatory
Represents the type of the record locking configuration.
Possible values: manual, automatic, both.
When lock type is automatic, records will be locked automatically if the specified criteria are matched on creating or updating records. When lock type is manual, users with lock permissions in their profile can lock records manually.
locking_rules JSON Array, mandatory when "lock_type" is "both" or "automatic"
Specify the details of rules added to lock the records in the module automatically.
- namestring, mandatory when "lock_type" is "both" or "automatic"
  Specify the name of the record locking rule.
- lock_existing_records boolean,optional
  Specify whether the existing record must be locked or not.
- criteria JSON Object, mandatory when "lock_type" is "both" or "automatic"
  Specifies the criteria for record locking rule.
  - group_operatorstring
    Specifies the group operator used in the criteria
    Possible values: AND, OR
  - group JSON Array
    Represents the group of criteria for the record locking rule.
    comparatorstring
    Represents the comparison operator used in the criterion.
    fieldJSON Object
    Represents the field details for the criteria.
    api_namestring
    Specifies the API name of the field.
    idlong
    Specifies the ID of the field.
    value string
    Specifies the value used in the criteria.
locked_for string, optional
Specify whether records are locked for all profiles or all profiles with a few exceptions.
Possible values: all_profiles_except_excluded_profile, all_profiles.
Default value: all_profiles.
lock_excluded_profilesJSON Array,mandatory when locked_for value is "all_profiles_except_excluded_profiles"
Represents the profiles that are restricted from locking.
- api_namestring
  Represents the API name of the profiles that are restricted from locking.
- idlong
  Represents the ID of the profiles that are restricted from locking.
excluded_fields JSON Array, optional
Specify the fields that are excluded from record locking.
- api_namestring
  Specify the API name of the fields that are excluded from record locking.
- idlong
  Specify the id of the fields that are excluded from record locking.
feature_typestring, optional
Specify the feature type of record locking configuration.
Possible value: record_locking
restricted_actionsJSON Array, optional
Specify the actions that are restricted for locked records.
Possible values: update, tags, convert, delete, change_owner
Default value:update
lock_for_portal_usersboolean, optional
Indicates whether locked records are restricted for portal users.
Default value: true
restricted_communicationsJSON Array, optional
Specifies types of communication that are restricted for locked records.
Possible value: send_mail
restricted_custom_buttonsJSON Array,optional
Represents the custom buttons that are restricted for locked records.
- namestring
  Represents the API name of the custom buttons that are restricted for locked records.
- idlong
  Represents the ID of the custom buttons that are restricted for locked records.

Note

When only one of the API name or ID given in the criteria is valid, the record will be processed with the valid value.
Edit action is always restricted in record locking configuration. i.e. Restricted_actions always contains the valueupdate.

Sample Input

Copied{
    "record_locking_configurations": [
        {
            "lock_type": "both",
            "locking_rules": [
                {
                    "name": "Select leads lock",
                    "lock_existing_records": false,
                    "criteria": {
                        "group_operator": "AND",
                        "group": [
                            {
                                "comparator": "less_than",
                                "field": {
                                    "api_name": "Last_Activity_Time",
                                    "id": "5843104000000052001"
                                },
                                "value": "2018-10-01T01:00:00+05:30"
                            },
                            {
                                "comparator": "less_than",
                                "field": {
                                    "api_name": "Created_Time",
                                    "id": "5843104000000002627"
                                },
                                "value": "2018-10-01T01:00:00+05:30"
                            }
                        ]
                    }
                }
            ],
           "locked_for": "all_profiles_except_excluded_profiles",
            "lock_excluded_profiles": [
                {
                    "name": "Administrator",
                    "id": "5843104000000026011"
                }
            ],
            "excluded_fields": [
                {
                    "api_name": "Annual_Revenue",
                    "id": "5843104000000002617"
                }
            ],
            "feature_type": "record_locking",
            "restricted_actions": [
                "update",
                "delete",
                "change_owner"
            ],
            "lock_for_portal_users": true,
            "restricted_communications": [
                "send_mail"
            ],
            "system_defined": false,
            "restricted_custom_buttons": [
                {
                    "name": "Send Doc",
                    "id": "5843104000000485570"
                }
            ]
        }
    ]
}

Possible Errors

REQUIRED_PARAM_MISSINGHTTP 400
One of the expected parameters is missing.
Resolution: The "details" key in the response gives the missing param in the request. Ensure that you include the params marked "mandatory" in the "Parameters" section.
INVALID_MODULEHTTP 400
The module name given seems to be invalid.
Resolution: Specify a valid module API name.
NOT_SUPPORTEDHTTP 400
- The given module is not supported.
- The API name given in the criteria is not supported.
- The value given in the criteria is not supported.
- For task module api_name task status and value closed are the only accepted values. Any other criteria will throw this error.
- Field in criteria is not supported.
- Value in criteria is not supported.
Resolution: Specify corresponding supported values.
FEATURE_NOT_SUPPORTEDHTTP 400
Record locking configuration is not supported in the user's current edition.
INVALID_DATAHTTP 400
- The API name specified in record locking rule criteria is invalid.
- The feature_type is not record_locking.
- Value given in the request body for restricted_communications is invalid.Valid values are send_mail, send_survery, send_portal_invitation.
- Value given in the request body for restricted_actions is invalid.Valid values are convert, update, delete, change_owner, tags.
- Value given for restricted_button is invalid.
- Value given in the request body for lock_type is invalid.Valid values are manual, automatic or both.
- Value given in the request body for locked_for is invalid.Valid values are all_profiles or all_profiles_except_excluded_profiles.
- Value given for lock_excluded_profiles is invalid.
- Value given for excluded_fields is invalid.
Resolution: Specify corresponding valid values in the request
LIMIT_EXCEEDEDHTTP 400
- The maximum limit for locking rules is exceeded.
- The maximum limit for custom buttons is exceeded.
- The maximum limit for excluded fields is exceeded.
- The maximum limit for excluded profiles is exceeded.
- When you try to add locking rule configuration but it is already configured.
Resolution: Refer to the "details" key in the response to know the available_limit and modify the request body.
MANDATORY_NOT_FOUNDHTTP 400
The mandatory field lock_type is not present.
Resolution: Provide the mandatory fields in the request body.
EXPECTED_FIELD_MISSINGHTTP 400
The id or api_name of field is missing in criteria for the record locking rule.
Resolution: Give criteria with necessary fields.
AMBIGUITY_DURING_PROCESSINGHTTP 400
The id and api_name of field in criteria for the record locking rule belongs to different fields.
Resolution: Give criteria with the correct api_name and id.
DEPENDENT_FIELD_MISSINGHTTP 400
- The key 'locking_rules' is not given in the request body when "lock_type" is "both" or "automatic".
- The key "lock_excluded_profiles" is not given in the request body when locked_for value is "all_profiles_except_excluded_profiles".
Resolution: Give the dependent field in the request body.
DUPLICATE_DATAHTTP 400
- Duplicate value is found in criteria.
- Duplicate value is found in rule name.
Resolution: Give unique values for the corresponding fields.
INVALID_REQUEST_METHODHTTP 403
The http request method type is not a valid one.
Resolution: You have specified an invalid HTTP method to access the API URL. Specify a valid request method. Refer to endpoints section above.
NO_PERMISSIONHTTP 403
Permission denied to customize record lock configurations. The user do not have permission.
Resolution: Contact your system administrator.
INTERNAL_ERRORHTTP 500
Internal Server Error.
Resolution: Unexpected and unhandled exception in the server. Contact support team.

Sample Response

Copied{
    "record_locking_configurations": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "5843104000000758004"
            },
            "message": "record locking configuration created successfully",
            "status": "success"
        }
    ]
}