Initiate Document User Action
Initiate a user action. Before initiating, you should retrieve any applicable entry criteria for the action.
Only some user action types can be initiated through the API. See supported user actions.
The authenticated user must have permission to initiate this action. To check permissions, Retrieve User Actions and check for actions where executable__v is true.
/api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/lifecycle_actions/{name__v}Headers
Section link for Headers| Name | Description |
|---|---|
Content-Type | application/x-www-form-urlencoded |
Accept | application/json (default) or application/xml |
URI Path Parameters
Section link for URI Path Parameters| Name | Description |
|---|---|
{doc_id} | The document id field value on which to initiate the user action. |
{major_version} | The major version number of the document. |
{minor_version} | The minor version number of the document. |
{name__v} | The action name__v field value to initiate. Retrieve this value from Retrieve User Action. |
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. |
Request Details: Start Legacy Workflow
Section link for Request Details: Start Legacy WorkflowThis request is initiating a start_approval__c workflow. Retrieving the entry criteria told us what fields we need to add to initiate this action, and that the scope is WorkflowActivation. This scope means we can add the required entry criteria fields as name-value pairs in the body of this request.
user_control_multiple__c=user%3A10001400is anObjectReferenceto aUser.date_control__c=2019-10-31is aDate.
Request: Start Legacy Workflow
Section link for Request: Start Legacy Workflowcurl -X PUT -H "Authorization: {AUTH_VALUE}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'user_control_multiple__c=user%3A10001400&date_control__c=2019-10-31'\
https://myvault.veevavault.com/api/v26.3/objects/documents/17/versions/0/1/lifecycle_actions/start_approval__cResponse: Start Legacy Workflow
Section link for Response: Start Legacy Workflow{
"responseStatus": "SUCCESS",
"id": 17,
"workflow_id__v": "401"
}Request Details: Change State
Section link for Request Details: Change StateThis request is initiating the approve__c user action, which changes the state of the document to Approved. Retrieving the entry criteria told us what fields we need to add or update to initiate this action, and that the scope is Document. This scope means the required entry criteria must be set on the document prior to this request, so there are no additional parameters to add to this initiate request.
Request: Change State
Section link for Request: Change Statecurl -X PUT -H "Authorization: {AUTH_VALUE}" \
https://myvault.veevavault.com/api/v26.3/objects/documents/17/versions/0/1/lifecycle_actions/approve__vsResponse: Change State
Section link for Response: Change State{
"responseStatus": "SUCCESS",
"id": 17
}Request Details: Entry Criteria Evaluation
Section link for Request Details: Entry Criteria EvaluationIn this request, we're initiating the approve__c user action while also including entrycriteria=true, a query parameter to request Vault to include a structured evaluation of any entry criteria violations in the response.
Request: Entry Criteria Evaluation
Section link for Request: Entry Criteria Evaluationcurl -X PUT -H "Authorization: {AUTH_VALUE}" \
https://myvault.veevavault.com/api/v26.3/objects/documents/17/versions/0/1/lifecycle_actions/approve__c?entrycriteria=trueResponse: Entry Criteria Evaluation
Section link for Response: Entry Criteria Evaluation{
"responseStatus": "FAILURE",
"errors": [
{
"type": "OPERATION_NOT_ALLOWED",
"message": "Entry criteria requirement for state [in_review_state__c] failed : expected [payment_terms__c] is not blank"
},
{
"type": "OPERATION_NOT_ALLOWED",
"message": "Entry criteria requirement for state [in_review_state__c] failed : Formula must be TRUE"
}
],
"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 DetailsOn SUCCESS, the response includes the document id. If the request successfully initiated a legacy workflow, the response also includes the workflow_id__v.
If the request results in FAILURE due to unmet entry criteria and entrycriteria=true, the response includes a structured evaluation of entry criteria violations. Learn more about the entry criteria evaluation response.