Document & Binder User Actions

The API supports user actions such as workflows and state changes on documents and binders in your vault. This allows you to request a list of user actions available to users on a document or binder, retrieve the properties which are required to be provided before the user action can be initiated (entry requirements), and then initiate the user action.

Article Contents

The following sections provide detailed information and examples, focusing on Workflow and State Change action types:

The following User Action Types can be initiated through the API:

Overview of Steps

Step 1: Retrieve User Actions

  • Retrieve a list of available user actions that can be initiated on a specific version of a document or binder.
  • The response includes the name of each user action and the endpoint to retrieve the entry requirements.

Step 2: Retrieve Entry Requirements

  • Before initiating a user action, you need to ensure that the document or binder meets certain conditions (required fields are populated, etc.).
  • For example, you don't need to assign a user to the "Approver" role when the document is first uploaded, but you do need to when initiating the "Start Approval" workflow.
  • Not all user actions have entry requirements. In these cases, you can simply proceed with initiation of the user action.
  • When the entry requirement "scope": "WorkflowActivation", the values can be specified as name-value pairs with the lifecycle initiation request.
  • When the entry requirement "scope": "Document" or "scope": "Binder" the values must first be updated on the document or binder before initiating the request.

Step 3: Initiate User Action

  • Once you've determined the entry requirements and completed those which must be configured separately, you can initiate the user action.
  • Vault will evaluate whether all the entry requirements have been met and, if so, will initiate the user action on the specified version of the document or binder.

Top

Retrieve Document or Binder User Actions

Retrieve all available user actions that can be initiated on a specific version of a document or binder.

Request

Documents: Send GET to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions
Binders: Send GET to /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

document_id - The document id field value from which to retrieve available user actions.
binder_id - The binder id field value from which to retrieve available user actions.
major_version_number__v - The major version number of the document or binder.
minor_version_number__v - The minor version number of the document or binder.

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v14.0/objects/documents/222/versions/0/1/lifecycle_actions

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "lifecycle_actions__v": [
    {
      "name__v": "startApproval",
      "label__v": "Start Approval",
      "lifecycle_action_type__v": "workflow",
      "entry_requirements__v": "https://myvault.veevavault.com/api/v13.0/objects/documents/222/versions/0/1/lifecycle_actions/startApproval/entry_requirements"
    },
    {
      "name__v": "approve",
      "label__v": "Approve",
      "lifecycle_action_type__v": "stateChange",
      "entry_requirements__v": "https://myvault.veevavault.com/api/v13.0/objects/documents/222/versions/0/1/lifecycle_actions/approve/entry_requirements"
    }
  ]
}

Details

The response lists all available user actions (lifecycle_actions__v) that can be initiated on the specified version of the document or binder.

  • name__v - The user action name (consumed by the API). These vary from vault to vault and may be text, numeric, or alphanumeric values.
  • label__v - The user action label. This is the "User Action" label seen in the UI.
  • lifecycle_action_type__v - The workflow and stateChange types are the most commonly used and are available in all vaults. Others may exist.
  • entry_requirements__v - The endpoint to retrieve the entry requirements for each user action. If no entry requirements exist, this will be excluded from the response.

Note that user actions are not returned for documents or binders which are currently in an active workflow.

History

Since v6

Top

Retrieve Entry Requirements

Once you've retrieved the available user actions, you can retrieve the entry requirements for a specific user action.

Request

Documents: Send GET to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions/{lifecycle_action_name}/entry_requirements
Binders: Send GET to /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions/{lifecycle_action_name}/entry_requirements

Headers

Response Accept - JSON application/json (default) or XML application/xml

Parameters

document_id - The document id field value from which to retrieve available user actions.
binder_id - The binder id field value from which to retrieve available user actions.
major_version_number__v - The major version number of the document or binder.
minor_version_number__v - The minor version number of the document or binder.
lifecycle_action_name - The name of the user action to be initiated. This is obtained from the Retrieve User Actions request above.

Example

In this request, we'll retrieve the entry requirements for the "Start Approval" workflow.

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v14.0/objects/documents/222/versions/0/1/lifecycle_actions/startApproval/entry_requirements

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "properties": [
    {
      "name": "dueDate",
      "description": "Approval Due Date",
      "type": [
        "Date"
      ],
      "required": true,
      "editable": true,
      "scope": "WorkflowActivation"
    },
    {
      "name": "Approver",
      "description": "Approver",
      "type": [
        "ObjectReference"
      ],
      "objectTypeReferenced": {
        "name": "User",
        "label": "User"
      },
      "required": true,
      "editable": true,
      "repeating": true,
      "scope": "WorkflowActivation"
    }
  ]
}

Details

The response above shows two entry requirements to start the approval workflow on this document: dueDate and Approver.

  • You must assign an Approval Due Date and users/groups to the Approver role on the document when initiating the user action.
  • Unlike the response from the next example, the Scope for these fields is set to WorkflowActivation ("scope": "WorkflowActivation").
  • This scope means that you can initiate the user action by including these entry requirements as name-value pairs with the request.

See the Initiate User Action section below for more information.

Example

In this request, we'll retrieve the entry requirements to change the state of a document from "Draft" to "Approved".

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v14.0/objects/documents/222/versions/0/1/lifecycle_actions/approve/entry_requirements

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "properties": [
    {
      "name": "country__v",
      "description": "Country",
      "type": [
        "ObjectReference"
      ],
      "objectTypeReferenced": {
        "name": "country__v",
        "label": "Country",
        "url": "/api/v14.0/metadata/vobjects/country__v",
        "label_plural": "Countries"
      },
      "editable": true,
      "repeating": true,
      "scope": "Document",
      "records": "/api/v14.0/vobjects/country__v"
    }
  ]
}

Details

The response above shows one entry requirement to change the state of this document from "Draft" to "Approved": country__v.

  • You must assign a value to the Country document field before initiating the user action.
  • Unlike the response from the previous example, the Scope for this field is set to Document ("scope": "Document").
  • This scope means that you must first update this field on the document before initiating the user action.

See the Initiate User Action section below for more information.

The response may include the following metadata elements describing the properties for which values need to be specified:

Property Description
name The entry requirement name (used in the API). This value must be specified when starting the user action.
description The entry requirement name (used in the UI).
type The entry requirement data type. This value can be one of String, Number, Date, Boolean, Picklist, or ObjectReference.
objectTypeReferenced When type is ObjectReference, this is the object being reference. For example: User, Product, Country, etc.
required Boolean value indicating whether or not the entry requirement must be specified when initiating a user action.
editable Boolean value indicating whether or not the value can be edited by the user.
repeating Boolean value indicating whether or not the entry requirement can have multiple values.
minValue Indicates the minimum character length for the value.
maxValue Indicates the maximum character length for the value.
values When type is Picklist, this provides a list of possible values that can be used.
currentSetting When a value has already been set, this shows the value.
scope Indicates where the property is defined. This value can be one of Document, Binder, WorkflowActivation, EmailFragment, ControlledCopy, or CreatePresentation.

History

Since v6

Top

Initiate Document or Binder User Action

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

Method & Endpoint

Documents: Send PUT to /api/{version}/objects/documents/{document_id}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions/{lifecycle_action_name}
Binders: Send PUT to /api/{version}/objects/binders/{binder_id}/versions/{major_version_number__v}/{minor_version_number__v}/lifecycle_actions/{lifecycle_action_name}

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

document_id - The document id field value from which to retrieve available user actions.
binder_id - The binder id field value from which to retrieve available user actions.
major_version_number__v - The major version number of the document or binder.
minor_version_number__v - The minor version number of the document or binder.
lifecycle_action_name - The name of the user action to be initiated. This is obtained from the Retrieve User Actions request above.

Example

$ 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/v14.0/objects/documents/222/versions/0/1/lifecycle_actions/startApproval

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 requirements are to assign a values to the dueDate and Approver fields.
  • The entry requirement 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 requirements have been met and, if so, initiate the user action.

Response

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

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.

Example

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

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 requirement is to assign a value to the document's country__v field.
  • The entry requirement 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 requirement.
  • 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.

Response

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

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.

History

Since v6

Top

User Action Types

The API supports initiation of the following user action types:

  • Workflow
  • State Change
  • Controlled Copy
  • Create Presentation

Your vault may include other user action types, all of which must be initiated through the Vault UI.

Note: The API does not support initiation of user actions requiring eSignatures.

Learn about Lifecycles & Workflows in Vault Help.

Workflow User Action

This action allows users to start a specified workflow. Only workflows that are already configured and active for the selected lifecycle are available.

The detailed examples in the first section of this article describe retrieval and initiation of the Workflow user action type.

Note: The Workflow user action is available in API v6.0 or later.

Learn about Creating & Editing Workflows in Vault Help.

State Change User Action

This action allows the user to manually move a document into a different lifecycle state. Vault enforces entry criteria and entry actions for the state change.

The detailed examples in the first section of this article describe retrieval and initiation of the State Change user action type.

Note: The State Change user action is available in API v6.0 or later.

Learn about Defining Document Lifecycle States in Vault Help.

Controlled Copy User Action

This action allows users to generate and distribute a controlled copy of a document. This is only available in QualityDocs vaults and an Admin must have configured at least one controlled copy user action for the lifecycle state that that the document is in.

Note: The Controlled Copy user action is available in API v6.0 or later.

Learn about Distributing Controlled Copies (QualityDocs) in Vault Help.

Create Presentation User Action

This action allows users to create a presentation for integration with Veeva CRM. This is only available in PromoMats and MedComms vaults configured for CLM or Engage integration. An Admin must enable this feature by adding the Create Presentation user action to a lifecycle state. The action is only available on documents in that state. The retrieve and initiate examples shown below use the same endpoints and request parameters as the detailed examples in the first section of this article.

Note: The Create Presentation user action is available in API v14.0 or later.

Learn about Using Create Presentation in Vault Help.

Retrieve Create Presentation User Action Response (abridged)

Note: The Create Presentation user action name__v and label__v field values may vary from vault to vault.

{
  "lifecycle_actions__v": [
    {
      "name__v": "createPresentation",
      "label__v": "Create Presentation",
      "lifecycle_action_type__v": "createPresentation",
      "entry_requirements__v": "https://myvault.veevavault.com/api/v14.0/objects/documents/333/versions/1/0/lifecycle_actions/createPresentation/entry_requirements"
    }
  ]
}

Retrieve Create Presentation Entry Requirements Response (abridged)

Note: The Create Presentation entry requirement response varies from vault to vault and includes many more fields than those shown below.

{
  "responseStatus": "SUCCESS",
  "responseMessage": "Success",
  "properties": [
    {
      "name": "createSeparateSlides",
      "description": "Specify whether each page should be a separate Multichannel Slide document (true) or if the original document will be a single slide (false)",
      "type": [
        "Boolean"
      ],
      "editable": true,
      "scope": "WorkflowActivation"
    },
    {
      "name": "engage_presentation__v.name__v",
      "description": "Name",
      "type": [
        "String"
      ],
      "required": true,
      "editable": true,
      "scope": "WorkflowActivation"
    },
    {
      "name": "engage_presentation__v.description__v",
      "description": "Description",
      "type": [
        "String"
      ],
      "editable": true,
      "scope": "WorkflowActivation"
    },
    {
      "name": "slide__v.name__v",
      "description": "Name",
      "type": [
        "String"
      ],
      "required": true,
      "editable": true,
      "scope": "WorkflowActivation"
    },
    {
      "name": "slide__v.description__v",
      "description": "Description",
      "type": [
        "String"
      ],
      "editable": true,
      "scope": "WorkflowActivation"
    }
  ]
}

The response lists all document fields which can be configured with values when initiating the Create Presentation user action.

  • Required fields ("required": true) must be configured with values.
  • Editable fields ("editable": true) which are not required, can be (optionally) configured with values.

The createSeparateSlides field is always returned and allows you to indicate whether or not each page of the document should be split into separate slides.

  • This is not a required field and will default to true if not specified when initiating the user action.
  • If you prefer not to split the pages into separate slides, include the field name-value pair "createSeparateSlides=false" in the input.

All returned fields are editable and can be specified as name-value pairs when initiating the user action.

  • Multichannel Presentation document type fields are indicated by the engage_presentation__v prefix using dot-notation on the field name (i.e., engage_presentation__v.{FIELD_NAME}).
  • Multichannel Slide document type fields are indicated by the slide__v prefix using dot-notation on the field name (i.e., slide__v.{FIELD_NAME}).

Initiate Create Presentation Action

Note: The example request shown below includes both required and optional fields (in our vault). Your input requirements and values may be different.

$ curl -X PUT -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "engage_presentation__v.name__v=Nyaxa Presentation" \
-d "engage_presentation__v.product__v=Nyaxa" \
-d "engage_presentation__v.country__v=United States" \
-d "engage_presentation__v.language__v=en_US" \
-d "slide__v.name__v=Nyaxa Slide" \
-d "slide__v.product__v=Nyaxa" \
-d "slide__v.country__v=United States" \
-d "slide__v.language__v=en_US" \
https://myvault.veevavault.com/api/v14.0/objects/documents/830/versions/2/0/lifecycle_actions/createPresentation

On SUCCESS, the Create Presentation action is initiated on the specified document. The end result is the creation of a Multichannel Presentation and Multichannel Slides.

Top