Skip to content

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.

PUT/api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/lifecycle_actions/{name__v}
NameDescription
Content-Typeapplication/x-www-form-urlencoded
Acceptapplication/json (default) or application/xml
NameDescription
{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.
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.

Request Details: Start Legacy Workflow

Section link for Request Details: Start Legacy Workflow

This 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%3A10001400 is an ObjectReference to a User.
  • date_control__c=2019-10-31 is a Date.
curl -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__c
{
   "responseStatus": "SUCCESS",
   "id": 17,
   "workflow_id__v": "401"
}

This 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.

curl -X PUT -H "Authorization: {AUTH_VALUE}" \
https://myvault.veevavault.com/api/v26.3/objects/documents/17/versions/0/1/lifecycle_actions/approve__vs
{
   "responseStatus": "SUCCESS",
   "id": 17
}

Request Details: Entry Criteria Evaluation

Section link for Request Details: Entry Criteria Evaluation

In 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 Evaluation
curl -X PUT -H "Authorization: {AUTH_VALUE}" \
https://myvault.veevavault.com/api/v26.3/objects/documents/17/versions/0/1/lifecycle_actions/approve__c?entrycriteria=true

Response: 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."
    }
  ]
}

On 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.