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.

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.

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

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 aupported 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 aupported 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.

The Vault Java SDK does not support completing workflow tasks.