Update Workflow Definition

Endpoint: PUT /api/metadata/workflow

Updates an existing workflow definition.

Query parameters

Parameter	Description	Type	Required/ Optional
overwrite	Whether to overwrite the existing definition with the same name. Default is true.	boolean	Optional.
newVersion	Whether to create a new version for the workflow definition. Default is false. Set to true to create a new version.	boolean	Optional.

Request body

Parameter	Description	Type	Required/ Optional
name	The name of the workflow definition to be updated. For v4.0.1 and prior: Only letters, digits, hyphens (-), and underscores (_) are allowed. For v4.0.2 and later: Only letters, digits, spaces, hyphens (-), underscores (_), and certain special characters (<, >, {, }, #) are allowed. Note: It is recommended to use alphanumeric characters for workflow names. While special characters are allowed for backward compatibility, they are not fully supported and may cause unexpected behavior.	string	Required.
description	A description of the workflow.	string	Optional.
version	The version of the workflow definition. Defaults to 0 if not specified.	integer	Optional.
tasks	The task configurations to be included in the workflow.	array of objects	Required.
inputParameters	The input keys for the workflow.	array of strings	Optional.
outputParameters	The JSON template used to generate the workflow output. If unspecified, the workflow output is defined as the output of the last executed task.	object	Optional.
enforceSchema	Whether to enforce input schema validation. Set to true to enable validation or false to disable.	boolean	Optional.
inputSchema	The schema parameters to be used as input schema for the workflow definition. Learn more about creating and using schemas.	object	Required if enforceSchema is set to true.
schemaVersion	The current version of the Conductor schema. Must be 2.	integer	Required.
restartable	Whether the workflow can be restarted after completion. Set to false if restarting could impact workflow functionality.	boolean	Optional.
timeoutSeconds	Time (in seconds), after which the workflow will be set as TIMED_OUT if it hasn't reached a terminal state. No timeout occurs if the value is set to 0.	integer	Required.
timeoutPolicy	The policy for handling workflow timeout. Supported values: **TIME_OUT_WF–**The workflow is set to TIMED_OUT and is terminated. **ALERT_ONLY–**Increments the counter to check the workflow status when it times out and logs relevant messages.	string	Optional.
rateLimitConfig	A map of the workflow rate limit configuration.	object	Optional.
rateLimitConfig. rateLimitKey	A unique identifier to group workflow executions for rate limiting. Can be a fixed value (for example, "max") or a dynamic variable from the workflow input (for example, ${workflow.input.correlationId}).	string	Optional.
rateLimitConfig. concurrentExecLimit	The number of workflow executions that can run concurrently for a given key.	integer	Optional.
workflowStatusListenerEnabled	Whether to enable status callback for workflow state changes. Learn more about enabling CDC.	boolean	Optional.
workflowStatusListenerSink	The sink where workflow state changes are sent.	string	Required if workflowStatusListener is set to true.
failureWorkflow	The compensation workflow to trigger upon failure of the current workflow execution.	string	Optional.
tags	A key-value map to add tags to the workflow definition. Each tag consists of a key associated with a corresponding value.	object	Optional.
ownerEmail	The email address of the user updating the workflow definition.	string	Required.

Examples

Update an existing workflow definition

Request

curl -X 'PUT' \
  'https://<YOUR_CLUSTER>/api/metadata/workflow?overwrite=true&newVersion=false' \
  -H 'accept: */*' \
  -H 'X-Authorization: <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "createTime": 1735802320196,
  "updateTime": 1735812484172,
  "name": "api-test",
  "description": "Sample workflow created using API",
  "version": 2,
  "tasks": [
    {
      "name": "event",
      "taskReferenceName": "event_ref",
      "inputParameters": {},
      "type": "EVENT",
      "decisionCases": {},
      "defaultCase": [],
      "forkTasks": [],
      "startDelay": 0,
      "joinOn": [],
      "sink": "ibm_mq:internal_event_name",
      "optional": false,
      "defaultExclusiveJoinTask": [],
      "asyncComplete": false,
      "loopOver": [],
      "onStateChange": {},
      "permissive": false
    }
  ],
  "inputParameters": [],
  "outputParameters": {},
  "failureWorkflow": "",
  "schemaVersion": 2,
  "restartable": false,
  "workflowStatusListenerEnabled": false,
  "ownerEmail": "john.doe@acme.com",
  "timeoutPolicy": "ALERT_ONLY",
  "timeoutSeconds": 0,
  "variables": {},
  "inputTemplate": {},
  "rateLimitConfig":
  {
    "rateLimitKey": "12",
    "concurrentExecLimit": 33
  },
  "enforceSchema": true
}'

Response

Returns 200 OK, indicating that the workflow definition has been updated successfully.