Workflow Services

The services in the workflow package provide methods that allow custom code to interact with object and document workflows. Document workflows are object workflows on the envelope__sys object.

Key Functionality

With workflow services, you can:

Initiate workflow actions, such as starting a workflow, cancelling an in-progress workflow, or executing a record workflow action
Manage workflow task assignments, such as assigning or unassigning a workflow task
Complete workflow tasks
Update entities within workflow processing

Key Interfaces

WorkflowInstanceService: Provides methods to retrieve information for and update active workflow instances. For example, setting participants within a custom record workflow action or executing active workflow actions.
WorkflowMetadataService: Provides methods to interact with workflow metadata.
WorkflowTaskService: Provides methods to retrieve active workflow task instances and execute workflow task actions, such as cancelling a workflow task.

Workflow Action Services

The Vault Java SDK supports initiating workflow actions and workflow task actions. These actions run on active workflow instances and are available in all Vaults. If you are unfamiliar with workflow actions, you can learn more in Vault Help:

Active Workflow Actions

You can find the supported workflow actions in the WorkflowActions Enum:

ADD_PARTICIPANTS: Adds participants to an active workflow.
CANCEL_WORKFLOW: Cancels an active workflow.
REMOVE_ITEMS: Removes documents or records from an active workflow.
REPLACE_WORKFLOW_OWNER: Replaces the workflow owner of an active workflow.
UPDATE_WORKFLOW_DUE_DATE: Updates the due date of an active workflow.

Active Workflow Task Actions

You can find the supported workflow actions in the WorkflowTaskAction Enum:

ASSIGN: Assigns an available workflow task. Available workflow tasks are unassigned tasks which are valid for the requesting user to accept. For example, your organization's workflow configuration may only allow QA tasks to be assigned to users who are configured in the QA role.
CANCEL: Cancels an assigned workflow task.
REASSIGN: Reassigns a workflow task. The workflow task must be a valid task for the new task assignee to accept, for example, the new assignee cannot be configured in a restricted role. Completed or cancelled tasks cannot be reassigned.
UNASSIGN: Unassigns a workflow task. Once unassigned, the task becomes available. Tasks cannot be unassigned if they are completed, cancelled, or not configured as available tasks.
UPDATE_DUE_DATE: Updates the due date of an assigned workflow task. Vault notifies the task owner of the updated due date. If the workflow is configured to set all task due dates to the workflow due date, updates to individual task due dates will not affect the overall workflow due date. Cannot update the task due date if the due date is configured to sync with an object or document field.

How to Start a Workflow

The following is an example of a starting a workflow with the Vault Java SDK:

// Records to start Workflow with
String objectName = "object__c";
String record1 = "V5K000000001001";
String record2 = "V5K000000001002";
List<String> records = VaultCollections.asList(record1, record2);  // can also be list of documents if it's a document workflow

WorkflowMetadataService workflowMetadataService = ServiceLocator.locate(WorkflowMetadataService.class);

// 1) Get available workflows for given records
AvailableWorkflowMetadataCollectionRequest availableWorkflowsRequest = workflowMetadataService.newAvailableWorkflowMetadataCollectionRequestBuilder()
                                                                .withRecords(objectName, records)
                                                                .build();

AvailableWorkflowMetadataCollectionResponse response = workflowMetadataService.getAvailableWorkflows(availableWorkflowsRequest);

// Get list of available workflow for the given content listing
List<AvailableWorkflowMetadata> availableWorkflows = response.getWorkflows();

// Can loop over list of AvailableWorkflowMetadata to find/show all available workflows


// 2) Get Start step details to begin workflow
WorkflowStartMetadataRequest startMetadataRequest = workflowMetadataService.newWorkflowStartMetadataRequestBuilder()
                                                                    .withWorkflowName(workflowName)
                                                                    .withRecords(objectName, records)
                                                                    .build();

WorkflowStartMetadataResponse startMetadataResponse = workflowMetadataService.getWorkflowStartMetadata(startMetadataRequest);

// List of control sections in the start step
List<WorkflowStartStepMetadata> startStepMetadata = startMetadataResponse.getStartStepMetadataList();

for (WorkflowStartStepMetadata metadata : startStepMetadata){
    WorkflowStartStepType metaDataType = metadata.getType();  // Type of Start control (Participant, date, etc.)

    List<WorkflowParameterMetadata> parameters = metadata.getParameters(); // Parameters needed to start the workflow

    for (WorkflowParameterMetadata param : parameters) {
      String paramName = param.getName();                           // used in input parameter key
            WorkflowInputValueType valueType = param.getDataType();       // used to set the value of the control
        }
    }
}

// 3) Start workflow with these start inputs

String participantName = "viewer__c";
Long userId = 100l;
Long groupId = 500l;
List<String> userIds = VaultCollections.asList(userId.toString());
List<String> groupIds = VaultCollections.asList(groupId.toString());

String numberInput = "number__c";
int number = 123;

WorkflowInstanceService workflowInstanceService = ServiceLocator.locate(WorkflowInstanceService.class);

// Set workflow participants input
WorkflowParticipantInputParameter workflowParticipantInputParameter = workflowInstanceService.newWorkflowParticipantInputParameterBuilder()
            .withUserIds(userIds)
            .withGroupIds(groupIds)
            .build();

// Create Start instance request with the builder
WorkflowStartInstanceRequest startRequest = workflowInstanceService.newWorkflowStartRequestBuilder()
            .withWorkflowName(workflowName)
            .withRecords(objectName, records)
            .withInputParameters(numberInput, number)
            .withInputParameters(participantName, workflowParticipantInputParameter)
            .build();

// Start workflow with start request and success and error handlers
workflowInstanceService.startWorkflow(startRequest)
            .onSuccess(startResponse -> {
                String workflowId = startResponse.getWorkflowId();
                // Developer provided success handling logic here
            })
            .onError(startResponse -> {
                // Developer provided failure handling logic here
                if (startResponse.getErrorType() == ActionErrorType.INVALID_REQUEST) {
                    throw new RuntimeException(startResponse.getMessage());
                } else {
                    // ...
                }
            })
            .execute();  // needed to execute the action

How to Complete a Workflow Task

Complete a workflow task with Vault Java SDK in the following steps:

Retrieve Metadata: Query the task instance to understand the input required to complete the task. In Vault, these requirements are called prompts. For example, a workflow task may prompt the user for a verdict. Verdicts may also include a Capacity field, which lets the user provide additional context for their task verdict. Include capacities in WorkflowTaskInput. Learn more about prompts and verdicts in Vault Help.
Construct the Completion Request: Construct the completion request. This request must have the same structure as the metadata, including all supporting task inputs and task verdict inputs.
Execute: Execute the completion request. As a best practice, include success and failure cases to handle input errors.

The following is an example of a completing a workflow task with Vault Java SDK:

// 1) Get the task metadata to understand requirements
WorkflowTaskMetadataRequest metadataRequest = workflowMetadataService.newWorkflowTaskMetadataRequestBuilder()
                 .withTaskId(taskId)
                 .build();
WorkflowTaskMetadataResponse metadataResponse = workflowMetadataService.getWorkflowTaskMetadata(metadataRequest);

// 2) Inspect metadata. This example assumes we want to approve (verdict_approve__c)
String verdictToUse = "verdict_approve__c"; // The API name of the verdict
WorkflowTaskVerdictMetadata verdictMetadata = null;
for (WorkflowTaskVerdictMetadata v : metadataResponse.getVerdicts()) {
             if (v.getName().equals(verdictToUse)) {
                 verdictMetadata = v;
                 break;
             }
         }

// 3) Build WorkflowTaskInput for task-level prompts (such as verdicts, verdict capacities, comments, or reasons)
WorkflowTaskInput.Builder inputBuilder = workflowTaskService.newWorkflowTaskInputBuilder();

// 4) If a verdict is a required parameter for the task, add that here
inputBuilder.withInputParameters("verdict_public_key__c", verdictToUse);

// 5) Iterate over verdictMetadata.getPrompts() to find parameter names
for (WorkflowTaskPromptMetadata prompt : verdictMetadata.getPrompts()) {
             for (WorkflowParameterMetadata param : prompt.getParameters()) {
                 // Example: Set a comment if required
                 if (prompt.getType() == WorkflowTaskPromptType.COMMENT) {
                     inputBuilder.withInputParameters(param.getName(), "Approved via SDK");
                 }
             }
         }

WorkflowTaskInput taskInput = inputBuilder.build();

WorkflowTaskCompleteRequest completeRequest = workflowTaskService.newTaskCompleteRequestBuilder()
                 .withTaskId(taskId)
                 .withTaskInput(taskInput)
                 .build();

// 6) Execute the completion request
workflowTaskService.completeTask(completeRequest)
                 .onSuccess(response -> {
                     // Handle success
                 })
                 .onTaskInputError(response -> {
                     // Handle general input errors
                 })
                 .execute();