Update Record Locking Configuration

Purpose

To update the record locking configuration for different modules.

Endpoints

Request Details

Request URL

{api-domain}/crm/{version}/settings/record_locking_configurations?module={module_API_name}
To update a single record locking configuration id:
{api-domain}/crm/{version}/settings/record_locking_configurations/{record_locking_config_id}?module={module_API_name}

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

scope=ZohoCRM.settings.record_locking_configurations.Update

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v4/settings/record_locking_configurations?module=Leads"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-X PUT
Parameters
  • modulestring, mandatory

    Specify the API name of the required module to retrieve record-locking configuration with respect to that module.

Input JSON Keys

  • locked_forstring, 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.

  • excluded_fieldsJSON 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.

    • id long

      Specify the ID of the fields that are excluded from record locking.

  • feature_typestring, optional

    Specify the feature type of record locking configuration.

  • locking_rulesJSON Array, mandatory when "lock_type" is "both" or "automatic"

    Specify the details of rules added to lock the records in the module automatically.

    • namestring

      Specify the name of the record locking rule.

    • idlong

      Specify the ID of the record locking rule.

    • lock_existing_recordsboolean,optional

      Specify whether the existing record must be locked or not.

    • criteriaJSON Object,mandatory

      Specifies the criteria for record locking rule.

      • group_operator

        Specifies the group operator used in the criteria (e.g., AND, OR).

      • group JSON Array

        Represents the group of criteria for the record locking rule.

        • comparator

          Represents the comparison operator used in the criterion.

        • field JSON Object

          Represents the field details for the criteria.

          • api_namestring

            Specifies the API name of the field.

          • idlong

            Specifies the ID of the field.

        • valuestring

          Specifies the value used in the criteria.

  • restricted_actionsJSON Array, optional

    Specifies 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 as well. Default value: true

  • restricted_communicationsJSON Array, optional

    Specifies types of communication that are restricted for locked records.
    Possible value: send_mail

  • 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.

  • 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.

  • lock_excluded_profilesJSON Array,mandatory when locked_for value is "all_profiles_except_excluded_profiles"

    Represents the profiles that are restricted from locking.

    • api_name

      Represents the API name of the profiles that are restricted from locking.

    • id long

      Represents the ID of the profiles that are restricted from locking.

Note

  • When only one of the api_name or id given in the criteria is valid , the record is processed with the valid value

  • Locking rules can be added, modified or deleted using Update Record Locking API. When locking rule id is mentioned in the input body the corresponding locking rule is edited . When id is not mentioned it is considered as a new rule. When "_delete" key with value true is given the locking rule will be delete

  • Edit action is always restricted in record locking configuration. i.e. The value update in restricted_actions is always present.

Sample Input

Copied{
    "record_locking_configurations": [
        {
           
            "locked_for": "all_profiles_except_excluded_profiles",
            "excluded_fields": null,
            "locking_rules": [
                {
                    "id": "5843104000000766010",
                    "_delete": true
                },
                {
                    "name": "email rule 34",
                    "id": "5843104000000766034",
                    "lock_existing_records": false,
                    "criteria": {
                        "comparator": "equal",
                        "field": {
                            "api_name": "Email",
                            "id": "5843104000000002599"
                        },
                        "value": "test@gmail.com"
                    }
                },
                {
                    "name": "email rule 5",
                    "lock_existing_records": false,
                    "criteria": {
                        "comparator": "equal",
                        "field": {
                            "api_name": "Email",
                            "id": "5843104000000002599"
                        },
                        "value": "test5@gmail.com"
                    }
                }
            ],
            "restricted_actions": null,
            "lock_for_portal_users": true,
            "restricted_communications": [
                "send_mail"
            ],
            "system_defined": false,
            "lock_type": "both",
            "restricted_custom_buttons": [
                {
                    "name": "Send with Zoho Sign",
                    "id": "5843104000000485570"
                }
            ],
            "lock_excluded_profiles": [
                {
                    "name": "Administrator",
                    "id": "5843104000000026011"
                }
            ]
        }
    ]
}

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 give in the request body for restricted_communications is invalid.Valid values are send_mail, send_survery, send_portal_invitation.

    • Value give 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 give in the request body for lock_type is invalid.Valid values are manual, automatic or both.

    • Value give 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.

    • The mandatory field lock_reason__s 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 does 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 updated successfully",
            "status": "success"
        }
    ]
}