Retrieve User Action Details

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

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

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

Headers

Name	Description
`Accept`	`application/json` (default) or `application/xml`

URI Path Parameters

Name	Description
`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.

Request

curl -X POST -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v17.2/vobjects/product__v/0PR0771/actions/start_approval__v

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__c",
                  "label": "Generic Name",
                  "required": true,
                  "mutli_value": false,
                  "current_value":
                    [
                      "0PR0771"
                    ]
                },
                {
                  "name": "product__v.internal_name__c",
                  "label": "Internal Name",
                  "required": false,
                  "mutli_value": false,
                  "current_value":
                    [
                      "0PR0771"
                    ]
                },
                {
                  "name": "product__v.compound_id__c",
                  "label": "Compound Id",
                  "required": false,
                  "mutli_value": false,
                  "current_value":
                    [
                      "0PR0771"
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }

Response 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__c - The generic name product field is required and must be set.
product__v.internal_name__c - The internal name product field is not required, but can be (optionally) set.
product__v.compound_id__c - The compound ID product field is not required, but can be (optionally) set.

See the section below for an example request with input.