Update a Connected Workflow

Purpose

To update the metadata and structural configuration of a connected workflow.

With this API, you can:

Rename the workflow
Update the workflow description
Add module nodes
Remove existing module nodes from the workflow
Add connections between nodes

You cannot modify rules, trigger conditions, or actions configured within the workflow using this API.

Endpoints

PUT /settings/connected_workflows/{connected_workflow_ID}

Request Details

Request URL

{api-domain}/crm/{version}/settings/connected_workflows/{connected_workflow_ID}

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.connected_workflows.UPDATE
(or)
ZohoCRM.settings.connected_workflows.ALL
(or)
ZohoCRM.settings.ALL

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/connected_workflows/4876876000019209007" 
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf" 
-d "@input.json" 
-X PUT

Note

Connected workflows are supported in Standard, Professional, Enterprise, and Ultimate editions.
The user must have Manage Automations or Manage Connected Workflow permission enabled to access this API.
Only one connected workflow can be updated per API call.
You can add or delete only one node in a single request.
A connected workflow can contain up to 50 nodes. However, nodes must be deleted one at a time using separate API requests.
You cannot delete and add nodes in the same request. For that, you must use separate sequential requests.
All existing nodes and connections are automatically preserved unless explicitly deleted.
When a node is deleted, all its connections are automatically removed.
reference_id is temporary and only valid within the same request. reference_id used in connections must exactly match the reference_id defined in the nodes array. After adding a node, fetch the workflow to get the permanent node ID before referencing it in subsequent requests.

Input JSON

The request body must be a JSON object containing one connected_workflows array with the following keys:

namestring, optional
Specify the new name for the connected workflow.
descriptionstring, optional
Specify the new description of the connected workflow process.
nodesJSON array, optional
Specify the nodes to add or delete. You can add or delete only ONE node per request. Please note that you cannot ADD and DELETE nodes in the same request. The root node cannot be deleted.
- idstring, mandatory when deleting a node
  Specify the node ID if you want to delete the node.
- reference_idstring, mandatory when adding a node
  A temporary unique identifier assigned to a new node. This ID allows the node to be referenced within the connections array in the same API request. The value must match exactly wherever it is referenced in the request payload. It is valid only within the scope of the current request.
  Allowed characters: alphanumeric only.
  Maximum length: 50 characters.
- moduleJSON object, mandatory
  Specify the module details for the node. The specified module must not already be present as a node in the workflow.
  - idstring, mandatory
    Specify the unique module ID.
  - api_namestring, mandatory if id is not specified
    Specify the module API name.
- _deleteJSON object, optional
  Set the node object to null to delete the node. Please refer to the sample input for more details.
connectionsJSON array, optional
Specify the connections between nodes in the workflow. Both from and to nodes must exist or be created within the same request. Please note that circular dependencies are not permitted.
- fromJSON object, mandatory
  Specify the details of the from node of the connection.
  - idstring, mandatory
    Specify the ID of the node.
toJSON object, mandatory
Specify the details of the to node of the connection. You must provide either id OR reference_id, and not both.
- idstring, mandatory for an existing node
  Specify the ID of the node.
- reference_idstring, mandatory for a newly added node
  Specify the reference_id used to create the node. The value must match a reference_id provided in the nodes array within the same request. You cannot reference nodes created in previous requests.

Sample input to delete a node and update the name and description

Copied{
    "connected_workflows": [
        {
            "name": "Enhanced Zylker Lead Process",
            "description": "Updated lead cycle process with improved automation",
            "nodes": [
                {
                    "id": "4876876000020278010",
                    "module": {
                        "id": "4876876000000002179"
                    },
                    "_delete": null
                }
            ],
            "connections": [
                {
                    "from": {
                        "id": "4876876000019209009"
                    },
                    "to": {
                        "id": "4876876000020278038"
                    }
                }
            ]
        }
    ]
}

Sample input to add a node and connections

Copied{
    "connected_workflows": [
        {
          
            "nodes": [
                {
                    "reference_id": "{{accounts_node}}",
                    "module": {
                        "id": "4876876000000002177"
                    }
                }
            ],
            "connections": [
                
                {
                    "from": {
                        "id": "4876876000020278038"
                    },
                    "to": {
                        "reference_id": "{{accounts_node}}"
                    }
                }
            ]
        }
    ]
}

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.
DEPENDENT_FIELD_MISSINGHTTP 400
Dependent field is missing
Resolution: The id field is missing from the node object when _delete is set. Provide the id of the node you intend to delete. The id field is mandatory when _delete is present in the node object.
EXPECTED_FIELD_MISSINGHTTP 400
- Either id or reference_id must be provided for each node object, but neither was found.
  Resolution: Provide either the id of an existing node (when deleting) or a reference_id (when adding a new node) in each node object.
- Either id or api_name must be provided in the node's module object, but neither was found.
  Resolution: Provide either the id or the api_name of the module in the node's module object.
AMBIGUITY_DURING_PROCESSINGHTTP 400
Ambiguity while processing the request
Resolution: Both id and api_name were provided in the node's module object but refer to different modules. Provide only one of id or api_name in the module object, or ensure both values refer to the same module.
INVALID_REQUEST_METHODHTTP 400
The http request method type is not a valid one
Resolution: This API supports only the PUT method. Retry the request using the PUT method.
DUPLICATE_DATAHTTP 400
Duplicate connected workflow name
Resolution: Provide a unique value for the name field and retry the request.
MANDATORY_NOT_FOUNDHTTP 400
- The from object is missing in a connection entry.
  Resolution: Provide the from object with a valid existing node id in every connection entry.
- The to object is missing in a connection entry.
  Resolution: Provide the to object with a valid node id or reference_id in every connection entry.
- The id field is missing in the from object of a connection entry.
  Resolution: The from node must always be an already-created node. Provide its permanent id in the from object.
- The module object is missing in a node entry.
  Resolution: Provide the module object with either an id or api_name for every node being added.
INVALID_DATAHTTP 400
- The given connected workflow ID in the request URL is invalid.
  Resolution: Provide a valid connected workflow ID in the request URL.
- The given module is invalid or not supported in Connected Workflow.
  Resolution: Verify the module id or api_name and ensure the module is supported for use in connected workflows.
- The from node ID provided in a connection entry is invalid.
  Resolution: Ensure the from.id value refers to a valid, existing node in the connected workflow.
- The node id provided for deletion is invalid.
  Resolution: Ensure the node id refers to a valid, existing node in the connected workflow. Fetch the workflow to retrieve the correct node IDs.
- The name field exceeds the maximum length of 50 characters.
  Resolution: Ensure the name field does not exceed 50 characters.
- The value of the name field does not match the allowed pattern.
  Resolution: Ensure the workflow name matches the regex pattern [0-9a-zA-Z_\-\\.\|\$\?\,\'\/\!\P{InBasicLatin}\s]+.
- The description field exceeds the maximum length of 500 characters.
  Resolution: Ensure the description field does not exceed 500 characters.
- Only one connected workflow can be updated per API call.
  Resolution: Ensure the connected_workflows array contains only one object per request.
LIMIT_EXCEEDEDHTTP 400
- Only one node can be added or deleted per request.
  Resolution: Ensure the nodes array contains only one node object per request. To add or delete multiple nodes, use separate sequential API requests.
- The maximum number of modules allowed in the connected workflow for your edition has been reached.
  Resolution: The number of modules that can participate in a connected workflow varies by edition. Remove an existing node before adding a new one, or upgrade your edition to increase the limit.
REQUIRED_DATA_NOT_FOUNDHTTP 400
- A reference_id was defined in the nodes array but was not referenced in any entry in the connections array.
  Resolution: Ensure every reference_id defined in the nodes array is referenced in the connections array within the same request. A newly added node must have at least one connection that uses its reference_id.
- A reference_id used in the connections array does not match any reference_id defined in the nodes array within the same request.
  Resolution: Ensure the reference_id values in the connections array exactly match those defined in the nodes array. You cannot reference nodes created in previous requests by reference_id.
NOT_ALLOWEDHTTP 400
The module specified for the new node is already present as a child node under the same parent in the workflow.
Resolution: Each module can appear only once as a child to a given parent node. Use a different module, or review the existing workflow structure using the Get Connected Workflow API before adding a new node.
OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: Client does not have the required OAuth scope. Create a new token with a valid scope. Refer to the Scope section for more details.
NO_PERMISSIONHTTP 403
Permission denied
Resolution: Ensure that the user making the API call has the Manage Automation or Manage Connected Workflow permission enabled in their CRM profile, and then retry the request.
INVALID_URL_PATTERNHTTP 404
Please check if the URL trying to access is a correct one
Resolution: The request URL specified is incorrect. Specify a valid request URL. Refer to the request URL section for more details.
INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Unexpected and unhandled exception in Server. Contact support team.

Sample Response

Copied{
    "connected_workflows": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "4876876000019209007"
            },
            "message": "connected workflow updated successfully",
            "status": "success"
        }
    ]
}