Create Rule in a Connected Workflow
Purpose
To configure an automation rule for a node in a connected workflow. With this API, you can define trigger conditions and configure actions when the rule is triggered.
Endpoints
- POST /settings/connected_workflows/{connected_workflow_ID}/rules
Request Details
Request URL
{api-domain}/crm/{version}/settings/connected_workflows/{connected_workflow_ID}/rules
Header
Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
Scope
ZohoCRM.settings.connected_workflows.CREATE
(or)
ZohoCRM.settings.connected_workflows.ALL
(or)
ZohoCRM.settings.ALL
Sample Request
Copiedcurl "https://www.zohoapis.com/crm/v8/settings/connected_workflows/4876876000020317001/rules"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@input.json"
-X POSTNote
Before configuring a rule for a connected workflow:
- Create a connected workflow using the Create Connected Workflow API.
- Get the workflow details to obtain the node ID where the rule should be added.
Input JSON
The request body must be a JSON object containing a rules array with exactly one object. The rules object must contain the following:
- execute_whenJSON object, mandatory
Specify the conditions under which the rule should be triggered.
- typestring, mandatory
Specify the type of event that triggers the rule.
Possible values:
create - Trigger when a new record is created
edit - Trigger when an existing record is edited
create_or_edit - Trigger on both creation and edit
field_update - Trigger when a specific field value changes. - detailsJSON object, mandatory
Specify the details of the trigger.
- trigger_moduleJSON object, mandatory
Specify the details of the module that triggers this rule. Provide either the api_name or the unique id of the module.
- criteriaJSON object, mandatory for field_update trigger
Specify the field conditions for field update triggers.
- comparatorstring, mandatory
Define the comparator operator.
- fieldJSON object, mandatory
Specify the field details, which includes the field API name and the unique ID of the field.
- typestring, mandatory
Represents the type of value.
Possible values:
value - To compare against a static value.
field_reference - To compareagainst the value of another field. - valuestring, mandatory
Specify the value to compare against.
- repeatBoolean, optional
Define whether the rule should trigger repeatedly for subsequent updates. The default value is false.
- moduleJSON object, mandatory
Specify the module for which the rule is configured. Provide either the api_name or the unique id of the module. The specified module must already be configured as a node in the connected workflow.
- _nodeJSON object, mandatory for create_connected_record action
Specify the node in the connected workflow where the rule is being configured. This is required when the rule includes a create_connected_record action. The node ID must correspond to the module specified in the rule. Get this from the workflow's nodes array using the GET workflow API.
- idstring, mandatory
Specify the unique ID of the node.
- conditionsJSON array, mandatory
An array containing one condition object that defines the actions to execute. Only one condition is supported per rule.
- instant_actionsJSON object, mandatory
Define the list of instant actions to be executed when the rule is triggered.
- actionsJSON array, mandatory
Define the list of action items. You can add up to 11 actions per condition.
- namestring, mandatory
Specify a name for the action.
- typestring, mandatory
Specify the type of action.
Possible values:create_connected_record, field_updates, email_notifications. - idstring, mandatory for associative actions
If the action is an associative action (field_updates or email_notifications), specify the ID of the preconfigured action to associate it with the rule. Use the Create Field Update API or Create Email Notification API with feature_type set to connected_workflows to create these actions. Use the corresponding Get Field Update API or Get Email Notifications API to retrieve the action ID.
- related_detailsJSON object, optional
Specify additional configuration details for associative actions (field_updates or email_notifications). This object defines which connected records the action should be applied to.
- record_selection_typestring, mandatory
Specify the scope of records to apply the action to.
Possible values:
all - Apply to all connected records.
current - Apply only to the current triggering record.
selected - Apply to records that match specific criteria defined in the criteria object. - criteriaJSON object, mandatory if record_selection_type is selected
Define the filtering logic for selecting records to apply the action to. The criteria object must include the field details, the comparator, type, and value for comparison.
- detailsJSON object, mandatory for create_connected_record
Specify the action-specific configuration details for the create_connected_record action.
- moduleJSON object, mandatory
Specify the target module in which the connected record will be created. Provide the api_name and the unique id of the module.
- layoutJSON object, mandatory
Specify the layout in which the new record should be created. Provide the name and the unique id of the layout.
- field_mappingsJSON array, mandatory
Define the field value mappings for the new record.
- fieldJSON object, mandatory
Specify the target field details. You must provide both the api_name and the unique id of the field.
- typestring, mandatory
Specify the type of value.
Possible values:static, merge_field. - valuestring, mandatory
Specify the value for the mapped field. For static type, provide a direct value. For merge_field type, provide a merge field expression.
- criteria_detailsJSON object, optional
Specify the filter conditions for the records. If specified, the actions will be performed only when the given criteria are satisfied.
- relational_criteriaJSON object, optional
Define additional trigger conditions based on related modules. These multi-module trigger criteria allow the rule to execute actions when records in related modules satisfy the specified conditions.
- criteria_groupingsJSON array, mandatory
Specify a list of independent criteria groups, each checking a condition in a specific related module. Up to three criteria groupings are supported. The logical combination of these groups is defined by the pattern key.
- sequence_numberinteger, mandatory
Specify the order number of this criteria group. This value is referenced in the logical pattern expression.
- criteriaJSON object, mandatory
Specify the condition details. The criteria object must contain the field, the comparator, the type, and the value to compare the field against.
- moduleJSON object, mandatory
Specify the related module to evaluate. Provide either the api_name or the unique id of the module.
- match_typestring, mandatory
Define whether any or all connected records in the specified module must meet the condition for this grouping to evaluate as true.
- patternstring, mandatory
Specify the logical expression used to combine multiple criteria groupings using operators such as and and or, based on their sequence_number. If there is only one criteria grouping, the pattern value must match its sequence number (for example, "(1)").
- criteriaJSON object, optional
Specify the trigger criteria for the primary module. The actions will execute only when these conditions are satisfied. The criteria object must contain the field, the comparator, the type, and the value to compare against.
- fieldJSON object, mandatory
Specify the field to be evaluated. Provide the api_name and the unique id of the field.
- comparatorstring, mandatory
Specify the comparison operator used in the condition.
- typestring, mandatory
Specify the type of value used for comparison.
- valuestring, mandatory
Specify the value against which the field is evaluated.
Note:
- You can only create one rule per API request. Multiple rules require multiple API calls.
- The _node.id field must be obtained from the connected workflow's nodes array by calling the GET workflow API first. It is required only when the rule includes a create_connected_record action.
- The module specified in the rule configuration must match the module of the node where the rule is being created.
- A maximum of 11 actions can be added to a single condition's instant_actions array.
- Actions created for standard workflows (feature_type = workflow) cannot be associated with connected workflows.
- An associative action can be associated with only one rule and cannot be reused across multiple rules.
Sample Input
Copied{
"rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Contacts",
"id": "4876876000000002179"
}
},
"type": "create"
},
"module": {
"api_name": "Contacts",
"id": "4876876000000002179"
},
"_node": {
"id": "4876876000020317003"
},
"conditions": [
{
"instant_actions": {
"actions": [
{
"name": "Customer Onboarding",
"details": {
"layout": {
"name": "Standard",
"id": "4876876000019056016"
},
"field_mappings": [
{
"display_value": "${CURRENTUSER}",
"field": {
"api_name": "Owner",
"id": "4876876000019056061"
},
"type": "static",
"value": {
"name": "${CURRENTUSER}"
}
}
],
"module": {
"api_name": "Customer_Onboarding",
"id": "4876876000019056017"
}
},
"type": "create_connected_record"
}
]
},
"criteria_details": {
"relational_criteria": {
"criteria_groupings": [
{
"sequence_number": 1,
"criteria": {
"comparator": "equal",
"field": {
"api_name": "Account_Name.Account_Name",
"id": "4876876000000002425"
},
"type": "value",
"value": "ABC"
},
"module": {
"api_name": "Contacts",
"id": "4876876000000002179"
},
"match_type": "any"
},
{
"sequence_number": 2,
"criteria": {
"comparator": "equal",
"field": {
"api_name": "Mailing_Country",
"id": "4876876000000002549"
},
"type": "value",
"value": "India"
},
"module": {
"api_name": "Contacts",
"id": "4876876000000002179"
},
"match_type": "all"
}
],
"pattern": "(1and2)"
},
"criteria": {
"group_operator": "AND",
"group": [
{
"comparator": "equal",
"field": {
"api_name": "Data_Source",
"id": "4876876000000338211"
},
"type": "value",
"value": "Manual (Mobile)"
},
{
"comparator": "equal",
"field": {
"api_name": "Data_Source",
"id": "4876876000000338211"
},
"type": "value",
"value": "Manual (Mobile)"
}
]
}
}
}
]
}
]
}
Possible Errors
- FEATURE_NOT_SUPPORTEDHTTP 400
Your edition doesn't support this feature
Resolution: Upgrade the account to Standard, Professional, Enterprise, or Ultimate edition and then retry the request. - INVALID_REQUEST_METHODHTTP 400
The http request method type is not a valid one
Resolution: This API supports only the POST method. Retry the request using the POST method. - MANDATORY_NOT_FOUNDHTTP 400
Required field not found
Resolution: One or more mandatory fields are missing in the input JSON. The name of the missing field and its location can be found in the message and json_path keys of the error response. Add all the mandatory fields and try again. - INVALID_DATAHTTP 400
Invalid data
Resolution: You have provided an invalid data for one or more fields. Additional information can be found in the details key in the error response. - INVALID_DATAHTTP 400
- The given module does not exist.
Resolution: Specify a valid module id or api_name. - The given module is not configured as a node in the connected workflow.
Resolution: Ensure that the module specified in the rule configuration is already added as a node in the connected workflow. - You have added more than object in the rules array.
Resolution: Make sure the length of the rules array is one. - The given trigger module is invalid.
Resolution: Provide a valid module id or api_name in the execute_when.details.trigger_module object. - Action is already configured in some other rules
Resolution: The action is already associated with another rule. Create another action and associate it with the rule. - The given node ID is invalid.
Resolution: Provide a valid _node.id obtained from the connected workflow's nodes array. - The given action ID is invalid.
Resolution: Ensure that the action ID provided corresponds to a valid automation action created using the appropriate API. - The specified relational criteria pattern is invalid.
Resolution: Ensure that the pattern value correctly references the defined sequence_number values and uses valid logical operators. - The specified sequence number in criteria grouping is invalid.
Resolution: Ensure that the sequence_number value corresponds to an existing criteria group. - Other feature_type action cannot be associated to Connected workflow Rules
Resolution: Ensure that the action is created with feature_type = connected_workflows before associating it with the rule. - Encrypted Field is not supported for given operator
Resolution: Use a supported comparator for encrypted fields in the criteria. - The given tag is not available
Resolution: Provide a valid tag that exists in the module.
- The given module does not exist.
- EXPECTED_FIELD_MISSINGHTTP 400
Required field not found
Resolution: Refer to the details.expected_fields key in the error response to identify the missing field(s) and their corresponding JSON path. - DUPLICATE_DATAHTTP 400
Duplicate action found
Resolution: Ensure that the same action is not added multiple times in the instant_actions.actions array for the rule. Each action associated with a rule must be unique. - NOT_ALLOWEDHTTP 400
The unsupported action is given
Resolution: The action type specified in instant_actions.actions is not supported for connected workflow rules. Ensure the type is one of the supported values: create_connected_record, field_updates, or email_notifications. - AMBIGUITY_DURING_PROCESSINGHTTP 400
- The id and api_name provided in the module object refer to different modules.
Resolution: Ensure that the id and api_name both refer to the same module, or provide only one of them. - The id and api_name provided in the trigger_module object refer to different modules.
Resolution: Ensure that the id and api_name in execute_when.details.trigger_module both refer to the same module, or provide only one of them.
- The id and api_name provided in the module object refer to different modules.
- DEPENDENT_MISMATCHHTTP 400
- Module and trigger module should be same
Resolution: Ensure that the module and trigger_module refer to the same module. - When repeat is disabled current record criteria should be given
Resolution: Provide criteria_details.criteria when repeat is false. - Repeat not supported for this trigger
Resolution: Remove repeat or use a supported trigger type. - For current record field_update module and trigger module should be same
Resolution: Ensure both modules match.
- Module and trigger module should be same
- NOT_ALLOWEDHTTP 400
- An unsupported action is given
Resolution: Invalid action type provided or action type not supported for connected workflows. Use only supported action types: create_connected_record, field_updates, email_notifications
- An unsupported action is given
- LIMIT_EXCEEDEDHTTP 400
- More modules cannot be used in the connected workflow.
Resolution: Ensure that the number of modules configured does not exceed the maximum permitted value. For more details on the limits for your CRM edition, please refer to our Features List page. - Actions limit exceeded
Resolution: More than the allowed number of actions are included. Reduce the number of actions to the allowed limit. Check the limit value in error details for your edition's limit. - Conditions Limit Exceeds
Resolution: More than one condition block is included in the request. Include only one condition block per rule. - criteria_groupings in criteria has exceeded the limit
Resolution: More than three relational criteria groupings are included. Reduce criteria groupings to a maximum of three.
- More modules cannot be used in the connected workflow.
- DEPENDENT_FIELD_MISSINGHTTP 400
Dependent Field missing
Resolution:- When associating field_updates or email_notifications actions, the action id field is required. Include the existing action ID in your request.
- For create_connected_record actions, the details object is mandatory. Include the complete details configuration with module, layout, and field mappings.
- CRITERIA_LIMIT_EXCEEDEDHTTP 400
Number of fields in execute_when has exceeded the limit
Resolution: Ensure that only one criteria field is provided. - LOOKUP_LIMIT_EXCEEDEDHTTP 400
Lookups count exceeded the limit
Resolution: Ensure that lookup fields used in criteria do not exceed five. - OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: Client does not have the required OAUTH SCOPE. Create a new token with valid scope. - NO_PERMISSIONHTTP 403
Permission denied
Resolution: Ensure that the user has Connected Workflow permissions enabled. - INVALID_URL_PATTERNHTTP 404
Please check if the URL trying to access is a correct one
Resolution: Specify a valid request URL. - INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Contact support team.
Sample Response
Copied{
"rules": [
{
"code": "SUCCESS",
"details": {
"id": "4876876000020318001"
},
"message": "connected workflow rule created successfully",
"status": "success"
}
]
}