Document & Binder User Actions

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 cannot be initiated through the Vault API.

Entry Criteria

Before users can initiate a user action, the document or binder must satisfy certain entry criteria. Entry requirements are dynamic and depend on the lifecycle configuration, entry criteria defined for the lifecycle state, and/or the workflow activation requirements defined in the Start Step of the workflow.

Property Scope

The API specifies the scope for the each requirement:

Document scope means that the property is document-level and must be updated on the document before initiating the user action.
Binder scope means that the property is binder-level and must be updated on the binder before initiating the user action.
Workflow scope means that the property is workflow-level and must be specified at the time of action initiation.
Controlled Copy scope means that the property is controlled copy specific and must be specified at the time of action initiation.

Typical Implementation

In a typical implementation, the client requests the available user actions using the Get User Actions endpoint. The response to this call lists user actions that the current user can initiate on a document or a binder specified by its ID and version.

Overview of Steps

Step 1: Retrieve User Actions

Retrieve a list of available user actions on a specific version of a document or binder.
The response includes the name of each user action used to initiate the action and the endpoint to retrieve the entry criteria.

Step 2: Retrieve Entry Criteria

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 criteria. In these cases, you can simply proceed with initiation of the user action.
When the entry criteria "scope": "WorkflowActivation", the values can be specified as name-value pairs with the lifecycle initiation request.
When the entry criteria "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 criteria and completed those which must be configured separately, you can initiate the user action.
Vault will evaluate whether all the entry criteria have been met and, if so, will initiate the user action on the specified version of the document or binder.