Replace Participants on Active Workflow

Replace the entire membership of one or more participant groups on a single active workflow with a new, complete set of members. This action is synchronous and returns per-group outcomes immediately. To replace participants across many workflows at once, it is best practice to use Replace Participants on Multiple Workflows.

For each group, Vault atomically removes the members not in your new set and adds the members that are new. The operation is all-or-nothing per group: if adding a new member fails, that group is left unchanged. Members that appear in both the current membership and your new set are unchanged and are not listed in the response.

Replace applies only to manually-managed or custom SDK participant groups. When a group is configured with role constraints, every member you add must satisfy those constraints, otherwise the group returns a FAILURE. Learn more about Roles Allowed to Participate in Configuring Object Workflows.

Replace updates participant-group membership only, it does not move or reassign in-progress work. A task already assigned to (or accepted by) the replaced-out user stays assigned to that user; it is not cancelled or transferred to the new participant. If the group has active tasks, the newly added participant receives a new task. To hand off an in-progress task to another user, use Reassign Task. Or, once a new task is assigned to your newly added participant, you can cancel the previous already-assigned task with Cancel Workflow Task. Initiate a reassign or cancel task with Initiate Workflow Action.

POST/api/{version}/objects/objectworkflows/{workflow_id}/actions/replaceparticipants

Headers

Name	Description
`Content-Type`	`application/json`
`Accept`	`application/json`

URI Path Parameters

Name	Description
`{workflow_id}`	The ID of the active workflow instance.

Body Parameters

Name	Description
`participant_groups` required	An array of one or more participant-group replacement requests to apply to this workflow. Each item targets one participant group. Order does not matter, and at least one item is required.
`participant_groups.participant_group_name` required	The name of the participant group to update, for example `approvers__c`. Must exist on the workflow and cannot be repeated within the request.
`participant_groups.user_ids` conditional	The Vault user IDs that make up the new, complete membership for this group. Required if `group_ids` is omitted or empty.
`participant_groups.group_ids` conditional	The Vault user group IDs that make up the new, complete membership for this group. Required if `user_ids` is omitted or empty.

Request

curl -X POST -H "Authorization: {AUTH_VALUE}" \
  -H "Content-Type: application/json" \
https://myvault.veevavault.com/api/v26.3/objects/objectworkflows/2903/actions/replaceparticipants \
  --data '{
    "participant_groups": [
      { "participant_group_name": "approvers__c", "user_ids": [1024, 1090] }
    ]
  }'

Response

{
  "responseStatus": "SUCCESS",
  "data": [
    {
      "participant_group_name": "approvers__c",
      "responseStatus": "SUCCESS",
      "added":   { "user_ids": [1090], "group_ids": [] },
      "removed": { "user_ids": [2055], "group_ids": [] }
    }
  ]
}

Response Details

On SUCCESS, the response includes a list of added and removed user and group IDs, reflecting the actual membership change. If your new set is identical to the current membership, Vault applies no change and returns NO_DATA_CHANGES for that group.