Skip to content

Initiate Multi-Record Workflow

Initiate a multi-record workflow on a set of records. If any record is not in the relevant state or does not meet configured field conditions, the API returns INVALID_DATA for the invalid records and the workflow does not start.

POST/api/{version}/objects/objectworkflows/actions/{workflow_name}
NameDescription
Content-Typeapplication/x-www-form-urlencoded
Acceptapplication/json (default) or application/xml
NameDescription
{workflow_name}The workflow name value.
NameDescription
entrycriteriaSet to true to receive a structured evaluation of entry criteria violations in the response. If omitted, defaults to false. Learn more about the entry criteria evaluation response.

The following parameters are required, but an Admin may set other fields as required in your Vault. To find which fields are required to start this workflow, Retrieve Multi-Record Workflow Details.

NameDescription
contents__sys
required
Input a comma-separated list of records, in the format Object:{objectname}.{record_ID}. For example, Object:product__c.V3O000000005001. Maximum 100 records.
description__sys
required
Description of the workflow. Maximum 128 characters.

To add participants to a workflow, add the name of the participant control to the body of the request. The value should be a comma-separated list of user and group IDs in the format {user_or_group}:{id}. For example, approvers__c: user:123,group:234. Use Retrieve Document Workflow Details to get the names of all participant controls for the workflow.

Required fields cannot be omitted, set as blank, or defaulted to their existing value.

To preserve the existing value of a required field prompt in a workflow on a single record, submit the existing value as the new value.

For a workflow on multiple records, there is no way to preserve existing values in a field if that field is a required prompt. Setting a value for a prompt updates all records to the same single value.

curl -X POST -H "Authorization: {AUTH_VALUE}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "contents__sys: Object:feature_record__c.V3O000000005001,Object:feature_record__c.V3O000000005002" \
-d "description__sys: CSR Approval" \
-d "exec_approver__c: user:10081" \
https://myvault.veevavault.com/api/v26.3/objects/objectworkflows/actions/Objectworkflow.approval__c
{
   "responseStatus": "SUCCESS",
   "data": {
       "record_url": "/api/v26.3/vobjects/envelope__sys/0ER000000009003",
       "record_id__v": "0ER000000009003",
       "workflow_id": "8703"
   }
}

Request: Entry Criteria Evaluation

Section link for Request: Entry Criteria Evaluation
curl -X POST -H "Authorization: {AUTH_VALUE}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "contents__sys: Object:feature_record__c.V99000000001005" \
-d "description__sys: CSR Approval" \
-d "exec_approver__c: user:10081" \
https://myvault.veevavault.com/api/v26.3/objects/objectworkflows/actions/Objectworkflow.approval__c?entrycriteria=true

Response: Entry Criteria Evaluation

Section link for Response: Entry Criteria Evaluation
{
  "responseStatus": "FAILURE",
  "errors": [
    {
      "type": "OPERATION_NOT_ALLOWED",
      "message": "Record cannot be updated: Entry criteria requirement for state [in_review_state__c] failed : Payment Terms required before approving this contract"
    }
  ],
  "source_context": {
    "is_nested": false,
    "type": "object",
    "object_name": "task__c",
    "record_id": "V99000000001005",
    "lifecycle": "contract_management_lifecycle__c",
    "target_state": "in_review_state__c"
  },
  "entry_criteria": [
    {
      "type": "field",
      "message": "Payment Terms required before approving this contract.",
      "field": {
        "name": "payment_terms__c",
        "url": "/api/v26.3/metadata/vobjects/contract__c/fields/payment_terms__c"
      }
    }
  ]
}

On SUCCESS, the response includes the following:

NameDescription
record_id__vThe id value of the envelope__sys record.
workflow_idThe workflow id field value.

If the request results in FAILURE due to unmet entry criteria and entrycriteria=true, the response includes a structured evaluation of entry criteria violations for the affected records. Learn more about the entry criteria evaluation response.

Manage Multi-record Workflow Tasks

Section link for Manage Multi-record Workflow Tasks

Multi-record workflows are configured on the envelope__sys object. You can use the Workflow Task endpoints to retrieve workflow tasks, details, and initiate tasks.

You can remove one or more records from an envelope__sys object using the removecontent action in the Initiate Workflow Action endpoint.