Vault Object Record User Actions

As of v14.0, the API supports retrieval and initiation of user actions on Vault object records.

Article Contents

The following sections provide detailed information and examples:

Vault Help Resources

Learn about Object Lifecycles
Learn about Configuring Object Lifecycles
Learn about Fields & Objects

Vault API Resources

See the Vault Objects API

Overview of Steps

Step 1: Retrieve User Actions

  • Retrieve a list of available user actions that can be initiated on a specific Vault object record.
  • The response includes the name of each user action.

Step 2: Retrieve User Action Details

  • Before initiating a user action, you need to ensure that the object record meets certain conditions (required fields are populated, etc.).
  • For example, you don't need to assign a user to the "Approver" role when an object record is first created, but you do need to when initiating the "Start Approval" workflow.
  • The values can be specified as name-value pairs with the lifecycle initiation request.

Step 3: Initiate User Action

  • Once you've retrieved the details, specify values in the input and initiate the user action.
  • Vault will evaluate whether all of the requirements have been met and, if so, will initiate the user action on the specified object record.

Retrieve User Actions

Retrieve all available user actions that can be initiated on a specific object record.

Request

Send GET to /api/{version}/vobjects/{object_name}/{object_record_id}/actions

Headers

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

Parameters

{object_name} - The object name__v field value.
{object_record_id} - The object record id field value.

Retrieve Localized Strings

When available, you can retrieve localized (translated) strings for the label field by adding loc=true to the request endpoint.

For example: /api/{version}/vobjects/{object_name}/{object_record_id}/actions?loc=true

Example

$ curl -X GET -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v14.0/vobjects/product__v/0PR0771/actions

Response

{
  "responseStatus": "SUCCESS",
  "data": [
    {
      "type": "workflow",
      "name": "start_approval__v",
      "label": "Start Approval"
    },
    {
      "type": "state_change",
      "name": "change_state_to_inactive__c",
      "label": "Change State to Inactive"
    }    
  ]
}

Details

On SUCCESS, the response lists all available user actions that can be initiated on the specified object record.

  • type - The type of user action. This can be workflow or state_change.
  • name - The user action name. This is the lifecycle_action_name parameter used in the two requests below.
  • label - The user action label as seen in the UI.

When localized strings are requested (loc=true), the response includes an additional localized_data field containing translated fields and field values on each object field for which localized strings have been configured. This data is only available at the object and field level and only if localized strings have been configured.

Errors

On FAILURE, the response displays an error type and message describing the error.

Error Type Error Message Description
INSUFFICIENT_ACCESS User does not have sufficient privileges to perform the action. The logged-in API user must be assigned the appropriate privileges.
METHOD_NOT_SUPPORTED The requested method {METHOD} is not supported. Use the HTTP GET method for this request.
MALFORMED_URL The resource {RESOURCE} does not exist. The specified object_name or object_record_id could not be found in your vault.

History

Since v14

Top

Retrieve User Action Details

Once you've retrieved the available user actions, use this request to retrieve the details for a specific user action.

Request

Send GET to /api/{version}/vobjects/{object_name}/{object_record_id}/actions/{lifecycle_action_name}

Headers

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

Parameters

object_name - The object name__v field value.
object_record_id - The object record id field value from which to retrieve user actions.
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 POST -H "Authorization: {SESSION_ID}" \ 
https://myvault.veevavault.com/api/v14.0/vobjects/product__v/0PR0771/actions/start_approval__v

In this example, we're retrieving the requirements to initiate a "Start Approval" workflow on the product object record.

Response

{
  "responseStatus": "SUCCESS",
  "data": [
      {
        "name":"start_review__v",
        "label":"Start Approval Workflow",
        "type": "workflow", 
        "controls": [                
          {
            "label": "Instructions",
            "type": "instructions",
            "instructions": "Please specify the users and dates for this workflow.",
            "prompts": []
          },
          {
            "label": "Participant",
            "type": "participant",
            "prompts": 
              [
                {
                  "name": "approvers__c",
                  "label": "Approvers"
                }
              ]                    
          },
          {
            "label": "Date",
            "type": "date",
            "prompts": 
              [
                {
                  "name": "due_date__c",
                  "label": "Due Date"
                }
              ]                     
          },
          {
            "label": "Fields",
            "type": "field",
            "prompts": 
              [
                {
                  "name": "product__v.generic_name__vs",
                  "label": "Generic Name",
                  "required": true,
                  "mutli_value": false,
                  "current_value": 
                    [
                      "0PR0771"
                    ]
                },
                {
                  "name": "product__v.internal_name__vs",
                  "label": "Internal Name",
                  "required": false,
                  "mutli_value": false,
                  "current_value": 
                    [
                      "0PR0771"
                    ]
                },
                {
                  "name": "product__v.compound_id__vs",
                  "label": "Compound Id",
                  "required": false,
                  "mutli_value": false,
                  "current_value": 
                    [
                      "0PR0771"
                    ]
                }
            ]                 
        }                
    ]
}

Details

On SUCCESS, the response lists the fields that must be configured with values in order to initiate the user action. These are based on the controls configured in the workflow start step.

The following types of controls may be returned:

  • instructions - Contains static instruction text regarding workflow initiation.
  • participant - Used to specify users who will be part of the workflow.
  • date - Date selections for the workflow, such as due date.
  • field - All object fields requiring values.

For each control, the following data may be returned:

  • label - Label for the control.
  • type - Type of control (instructions, participants, date, or fields).
  • prompts - The input prompts (if any are configured) which would accept values when initiating the workflow.

Prompts of type field accept values per the metadata specified for the field in the object metadata.

The example above specifies that when initiating the workflow, the input must include (or may optionally include) the following:

  • approvers__c - The workflow approvers must be set.
  • due_date__c - The workflow due date must be set.
  • product__v.generic_name__vs - The generic name product field is required and must be set.
  • product__v.internal_name__vs - The internal name product field is not required, but can be (optionally) set.
  • product__v.compound_id__vs - The compound ID product field is not required, but can be (optionally) set.

See the section below for an example request with input.

Errors

On FAILURE, the response displays an error type and message describing the error.

Error Type Error Message Description
INSUFFICIENT_ACCESS User does not have sufficient privileges to perform the action. The logged-in API user must be assigned the appropriate privileges.
METHOD_NOT_SUPPORTED The requested method {METHOD} is not supported. Use the HTTP GET method for this request.
MALFORMED_URL The resource {RESOURCE} does not exist. The specified object_name, object_record_id, or lifecycle_action_name could not be found in your vault.

History

Since v14

Top

Initiate User Action

Once you've identified the details, use this request to initiate the user action on a specific object record.

Request

Send POST to /api/{version}/vobjects/{object_name}/{object_record_id}/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

object_name - The object name__v field value.
object_record_id - The object record id field value from which to retrieve user actions.
lifecycle_action_name - The name of the user action to be initiated. This is obtained from the Retrieve User Actions request above.

Input

Include name-value pairs for all required and optional fields returned in the Retrieve User Actions Entry Requirements request above.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \ 
-H "Content-Type: application/x-www-form-urlencoded" \
-d "approvers__c": "user:23423,user:5455,group:23421" \
-d "due_date__c": "2015-12-12T01:22:17.000Z" \
-d "product__v.generic_name__vs": "chopredol" \
-d "product__v.internal_name__vs": "CholeCap" \
-d "product__v.compound_id__vs": "CC-127" \
https://myvault.veevavault.com/api/v14.0/vobjects/product__v/0PR0771/actions/start_approval__v

In this example:

  • The Content-Type header is set to accept name-value pairs in the input.
  • We've specified the users and a group who will be part of the approval workflow.
  • We've specified the due date of the workflow in UTC.
  • We've configured the required product generic name field with a value.
  • We've configured the optional product internal name and compound ID fields with values.

Response

{
    "responseStatus": "SUCCESS"
}

On SUCCESS, the specified user action is initiated on the object record.

Errors

On FAILURE, the response displays an error type and message describing the error.

Error Type Error Message Description
INSUFFICIENT_ACCESS User does not have sufficient privileges to perform the action. The logged-in API user must be assigned the appropriate privileges.
METHOD_NOT_SUPPORTED The requested method {METHOD} is not supported. Use the HTTP POST method for this request.
MALFORMED_URL The resource {RESOURCE} does not exist. The specified object_name, object_record_id, or lifecycle_action_name could not be found in your vault.
PARAMETER_REQUIRED Missing required parameters [{PARAMETER_1, PARAMETER_2, PARAMETER_3}]. The input is missing one or more of the required parameters. The response includes the names of the missing parameters. Check the entry requirements response to ensure you have included all required fields.
INVALID_DATA Invalid value [{VALUE}] specified for parameter [{PARAMETER}]. The input includes an invalid value for one of the parameters. The response includes the specific reason for the error.
OPERATION_NOT_ALLOWED Cannot initiate action: [{ACTION}] is already running. The specified lifecycle_action_name has already been initiated on the object record.

History

Since v14

Top