Initiate Document Workflow
Initiate a document workflow on a set of documents.
/api/{version}/objects/documents/actions/{workflow_name}Headers
Section link for Headers| Name | Description |
|---|---|
Content-Type | application/json (default) or application/x-www-form-urlencoded |
Accept | application/json (default) or application/xml |
URI Path Parameters
Section link for URI Path Parameters| Name | Description |
|---|---|
{workflow_name} | The document workflow name value. |
Query Parameters
Section link for Query Parameters| Name | Description |
|---|---|
entrycriteria | Set 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. |
Body Parameters
Section link for Body ParametersThe 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 Document Workflow Details.
| Name | Description |
|---|---|
contents__sysrequired | Input a comma-separated list of document id field values, in the format Document:{doc_id}. For example, Document:101,Document:102,Document:103. To indicate specific document versions, use the format DocumentVersion:{doc_version_id}. For example, DocumentVersion:115_0_1,DocumentVersion:116_0_2. Maximum 100 documents. |
description__sysrequired | Description of the workflow. Maximum 128 characters. |
Add Participants
Section link for Add ParticipantsTo 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.
Request
Section link for Requestcurl -X POST -H "Authorization: {AUTH_VALUE}" \
-H "Content-Type: application/json" \
-d "contents__sys: Document:501,Document:502" \
-d "description__sys: Content Approval" \
https://myvault.veevavault.com/api/v26.3/objects/documents/actions/Objectworkflow.content_document_workflow__cResponse: Success
Section link for Response: Success{
"responseStatus": "SUCCESS",
"data": {
"record_url": "/api/v26.3/vobjects/envelope__sys/0ER000000000501",
"record_id__v": "0ER000000000501",
"workflow_id": "1301"
}
}Response: Failure
Section link for Response: Failure{
"responseStatus": "FAILURE",
"errors": [
{
"type": "INVALID_DATA",
"message": "Invalid value [501,502] for parameter [contents__sys] specified"
}
]
}Request: Entry Criteria Evaluation
Section link for Request: Entry Criteria Evaluationcurl -X POST -H "Authorization: {AUTH_VALUE}" \
-H "Content-Type: application/x-www-form-urlencoded" \
https://myvault.veevavault.com/api/v26.3/objects/documents/actions/Objectworkflow.content_document_workflow__c?entrycriteria=trueResponse: 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": "document",
"document_id": 100,
"minor_version_number__v": 0,
"major_version_number__v": 1,
"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/objects/documents/properties"
}
},
{
"type": "message",
"message": "Formula must be TRUE."
}
]
}Response Details
Section link for Response DetailsIf any document is not in the relevant state or does not meet configured field conditions, the API returns INVALID_DATA for the invalid documents and the workflow does not start.
On SUCCESS, the response includes the following:
| Name | Description |
|---|---|
record_id__v | The id value of the envelope__sys record. |
workflow_id | The 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 documents. Learn more about the entry criteria evaluation response.
Manage Document Workflow Tasks
Section link for Manage Document Workflow TasksDocument workflows share some of the same capabilities as object workflows and are configured on the envelope__sys object. You can use the Workflow Task endpoints to retrieve document workflow tasks, task details, and initiate document workflow tasks.
Remove Documents from Envelope
Section link for Remove Documents from EnvelopeYou can remove one or more documents from an envelope__sys object using the removecontent action in the Initiate Workflow Action endpoint.