Retrieve Entry Criteria

Retrieve the entry criteria for a user action. Entry criteria are requirements the document or binder must meet before you can initiate the action. Entry criteria are dynamic and depend on the lifecycle configuration, lifecycle state, or any workflow activation requirements defined in the Start Step of the workflow. Learn more about entry criteria in Vault Help.

To retrieve entry criteria, the authenticated user must have permission to execute the action. To check permissions, Retrieve User Actions and check for actions where executable__v is true.

GET

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

Headers

Name	Description
`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. Retrieve this value from Retrieve User Actions.

Request : Start Legacy Workflow

curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v23.2/objects/documents/17/versions/0/1/lifecycle_actions/start_approval__c/entry_requirements

Response : Start Legacy Workflow

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

Request : Change State

curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v23.2/objects/documents/17/versions/0/1/lifecycle_actions/approve__c/entry_requirements

Response : Change State

{
   "responseStatus": "SUCCESS",
   "responseMessage": "Success",
   "properties": [
       {
           "name": "country__v",
           "description": "Country",
           "type": [
               "ObjectReference"
           ],
           "objectTypeReferenced": {
               "name": "country__v",
               "label": "Country",
               "url": "/api/v23.2/metadata/vobjects/country__v",
               "label_plural": "Countries"
           },
           "required": true,
           "editable": true,
           "repeating": true,
           "scope": "Document",
           "currentSetting": [
               {
                   "name": "00C000000000109",
                   "label": "United States",
                   "value": "/api/v23.2/vobjects/country__v/00C000000000109"
               }
           ],
           "records": "/api/v23.2/vobjects/country__v"
       }
   ]
}

Response Details

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

Name	Description
`name`	The entry criteria name (used in the API). This value must be specified when starting the user action.
`description`	The entry criteria name (used in the UI).
`type`	The entry criteria 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 referenced. For example: `User`, `Product`, `Country`, etc.
`required`	Boolean value indicating whether or not the entry criteria 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 criteria 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 entry criteria property is defined. This value can be one of: `Document`: This field must be set on the document before the action can be initiated. `Binder`: This field must be set on the binder before the action can be initiated. `WorkflowActivation`: This field must be included in the body of the initiate request. `ControlledCopy`: This field must be included in the body of the initiate request. Additionally, this value may be `EmailFragment` or `CreatePresentation`.

Request : Start Legacy Workflow

curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v23.2/objects/documents/17/versions/0/1/lifecycle_actions/start_approval__c/entry_requirements

Response : Start Legacy Workflow

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

Request : Change State

curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v23.2/objects/documents/17/versions/0/1/lifecycle_actions/approve__c/entry_requirements

Response : Change State

{
   "responseStatus": "SUCCESS",
   "responseMessage": "Success",
   "properties": [
       {
           "name": "country__v",
           "description": "Country",
           "type": [
               "ObjectReference"
           ],
           "objectTypeReferenced": {
               "name": "country__v",
               "label": "Country",
               "url": "/api/v23.2/metadata/vobjects/country__v",
               "label_plural": "Countries"
           },
           "required": true,
           "editable": true,
           "repeating": true,
           "scope": "Document",
           "currentSetting": [
               {
                   "name": "00C000000000109",
                   "label": "United States",
                   "value": "/api/v23.2/vobjects/country__v/00C000000000109"
               }
           ],
           "records": "/api/v23.2/vobjects/country__v"
       }
   ]
}

Response Details: Start Legacy Workflow

This example requests entry criteria for the start_approval__c workflow on document ID 17. The properties array in the response shows there are two entry criteria:

Approver: user_control_multiple__c

Name	Description
`name`	The name of this entry criteria in the API is `user_control_multiple__c`. Use this name when referring to this field in the API.
`description`	The label of this entry criteria in the UI is Approver. This should tell you the intended usage of this field.
`type`	This field is an `ObjectReference`.
`objectTypeReferenced`	This field is an `ObjectReference` to a `User`.
`repeating`	This field can accept more than one value, meaning more than one user can be assigned as the approver.
`scope`	The scope is `WorkflowActivation`, which means you can include this data as a name-value pair in the initiate request.

Approval Due Date: date_control__c

Name	Description
`name`	The name of this entry criteria in the API is `date_control__c`. Use this name when referring to this field in the API.
`description`	The label of this entry criteria in the UI is Approval Due Date. This should tell you the intended usage of this field.
`type`	This field is a `Date`.
`scope`	The scope is `WorkflowActivation`, which means you can include this data as a name-value pair in the initiate request.

Request : Start Legacy Workflow

curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v23.2/objects/documents/17/versions/0/1/lifecycle_actions/start_approval__c/entry_requirements

Response : Start Legacy Workflow

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

Request : Change State

curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v23.2/objects/documents/17/versions/0/1/lifecycle_actions/approve__c/entry_requirements

Response : Change State

{
   "responseStatus": "SUCCESS",
   "responseMessage": "Success",
   "properties": [
       {
           "name": "country__v",
           "description": "Country",
           "type": [
               "ObjectReference"
           ],
           "objectTypeReferenced": {
               "name": "country__v",
               "label": "Country",
               "url": "/api/v23.2/metadata/vobjects/country__v",
               "label_plural": "Countries"
           },
           "required": true,
           "editable": true,
           "repeating": true,
           "scope": "Document",
           "currentSetting": [
               {
                   "name": "00C000000000109",
                   "label": "United States",
                   "value": "/api/v23.2/vobjects/country__v/00C000000000109"
               }
           ],
           "records": "/api/v23.2/vobjects/country__v"
       }
   ]
}

Response Details: Change State

This example requests entry criteria for the approve__c user action on document ID 17. The properties array in the response shows there is one entry criteria:

Retrieve Entry Criteria

Headers

URI Path Parameters

Request : Start Legacy Workflow

Response : Start Legacy Workflow

Request : Change State

Response : Change State

Response Details

Request : Start Legacy Workflow

Response : Start Legacy Workflow

Request : Change State

Response : Change State

Response Details: Start Legacy Workflow

Approver: user_control_multiple__c

Approval Due Date: date_control__c

Request : Start Legacy Workflow

Response : Start Legacy Workflow

Request : Change State

Response : Change State

Response Details: Change State

Country: country__v