Initiate User Action

Once you've identified the entry criteria, you can initiate the user action.

PUT/api/{version}/objects/{documents_or_binders}/{id}/versions/{major_version}/{minor_version}/lifecycle_actions/{name__v}

Headers

Name	Description
`Content-Type`	`application/x-www-form-urlencoded`
`Accept`	`application/json` (default) or `application/xml`

URI Path Parameters

Name	Description
`{documents_or_binders}`	Choose to retrieve values for `documents` or `binders`.
`{id}`	The document or binder `id` field value from which to retrieve available user actions.
`{major_version}`	The major version number of the document or binder.
`{minor_version}`	The minor version number of the document or binder.
`{name__v}`	The lifecycle `name__v` field value from which to retrieve entry criteria. This is retrieved from the Retrieve User Action request above.

Request Details

This request is initiating a workflow activation user action on the document. We're initiating the "Start Approval" workflow.

Recall from the discussion in the previous section that the two entry criteria are to assign a values to the dueDate and Approver fields.
The entry criteria Scope is set to WorkflowActivation ("scope": "WorkflowActivation"), meaning the values can be included as a name-value pairs with the request.
Format the dueDate value as shown above. To assign users and/or groups to the Approver role, include a comma-separated list of user and group id field values.

On submitting this request, Vault will evaluate whether all the entry criteria have been met and, if so, initiate the user action.

Request

curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "dueDate=2015-12-25" \
-d "Approver=user:12021,user:12022,group:10030003" \
https://myvault.veevavault.com/api/v18.2/objects/documents/222/versions/0/1/lifecycle_actions/startApproval

Response

{
  "responseStatus": "SUCCESS",
  "id": 222,
  "workflow_id__v": "115"
}

Request

curl -X PUT -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v18.2/objects/documents/222/versions/0/1/lifecycle_actions/approve

Response

{
  "responseStatus": "SUCCESS",
  "id": 222
}

Response Details

On SUCCESS, Vault returns the document id field value of the document on which the user action has been initiated and the workflow workflow_id__v field value of the workflow. This document ("id": 222) is now in the "Start Approval" workflow ("workflow_id__v": "115"). On FAILURE, Vault returns an error type and message describing the reason for the error. The user action will not be initiated until all errors have been corrected.

Request Details

This request is initiating a state change user action on the document. We're changing the state from "Draft" to "Approved".

Recall from the discussion in the previous section that the only entry criteria is to assign a value to the document's country__v field.
The entry criteria Scope is set to Document ("scope": "Document"), meaning the country field value cannot be included as a name-value pair with the request.
Instead, before submitting this request, we used a separate Update Document request to update the country field on the document. This fulfilled the entry criteria.
Therefore, we do not need to specify the input format (there is no input requirement) and the request can be submitted as shown in this example.

Request

curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "dueDate=2015-12-25" \
-d "Approver=user:12021,user:12022,group:10030003" \
https://myvault.veevavault.com/api/v18.2/objects/documents/222/versions/0/1/lifecycle_actions/startApproval

Response

{
  "responseStatus": "SUCCESS",
  "id": 222,
  "workflow_id__v": "115"
}

Request

curl -X PUT -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v18.2/objects/documents/222/versions/0/1/lifecycle_actions/approve

Response

{
  "responseStatus": "SUCCESS",
  "id": 222
}

Response Details

On SUCCESS, Vault returns the document id field value of the document on which the user action has been initiated. This document ("id": 222) was previously version 0.1 (Draft State). It is now version 1.0 (Approved/Steady State). On FAILURE, Vault returns an error type and message describing the reason for the error. The user action will not be initiated until all errors have been corrected.