Package com.veeva.vault.sdk.api.workflow

This package provides interfaces to create custom actions for workflows and update entities within workflow processing.

See: Description

Interface Summary

Interface	Description
AvailableWorkflowMetadata	Holds basic metadata of an available workflow.
AvailableWorkflowMetadataCollectionRequest	Request to retrieve a list of AvailableWorkflowMetadata for the given list of documents or record ids.
AvailableWorkflowMetadataCollectionRequest.Builder
AvailableWorkflowMetadataCollectionResponse	Holds a list of AvailableWorkflowMetadata.
RecordWorkflowAction	Executes custom logic on a record during workflow events; takes a RecordWorkflowActionContext as input.
RecordWorkflowActionContext	Contains contextual information about an active workflow during execution.
RecordWorkflowActionTaskContext	Provides methods to update and retrieve information for tasks of an active workflow.
WorkflowActionError	Represents an error encountered during a workflow action such as an WorkflowCancelOperation.
WorkflowActionResponse	Contains methods to retrieve information about the workflow action.
WorkflowCancelOperation	A sequence of instructions that can be chained together, building a workflow cancel execution operation that can be executed with WorkflowCancelOperation.execute().
WorkflowCancelRequest	A workflow cancel request containing an active workflow instance and cancellation comment, if required.
WorkflowCancelRequest.Builder	Builds a WorkflowCancelRequest.
WorkflowConfiguration	Represents the configured workflow definition.
WorkflowInputValueType<T>	Type of data supported by WorkflowParameterMetadata.
WorkflowInstance	Represents a runtime instance of a workflow.
WorkflowInstanceCollectionRequest	Request to retrieve a list of WorkflowInstance for the given list of document or record or workflow ids.
WorkflowInstanceCollectionRequest.Builder
WorkflowInstanceCollectionResponse	Holds a list of WorkflowInstance.
WorkflowInstanceRequest	Returns a WorkflowInstance once a request is given for a workflow ID.
WorkflowInstanceRequest.Builder
WorkflowInstanceService	Provides methods to retrieve information for and update workflow instances.
WorkflowItem	Represents an item that a workflow is executing on.
WorkflowItemDocument	Provides methods to retrieve metadata information of a document item in a workflow.
WorkflowItemRecord	Provides methods to retrieve metadata information of a record item in a workflow.
WorkflowItemsResponse	Response from a call to WorkflowInstanceService.getWorkflowItems(String)
WorkflowMetadataService	Provides methods to interact with workflow metadata.
WorkflowParameterMetadata	Holds the info for a parameter metadata needed to interact with the workflow.
WorkflowParticipantGroup	Provides methods to retrieve information for a participant group of an active workflow.
WorkflowParticipantGroupResponse	Response from a call to WorkflowInstanceService.getWorkflowParticipantGroups(String)
WorkflowParticipantGroupUpdate	Sets the information needed to perform updates for a WorkflowParticipantGroup of an active workflow.
WorkflowParticipantInputParameter	Container for a Workflow participant input parameter.
WorkflowParticipantInputParameter.Builder
WorkflowRequestExecutionContext	Contains metadata about the current workflow request.
WorkflowStartInstanceError	Represents an error encountered during a WorkflowStartInstanceOperation.
WorkflowStartInstanceOperation<T>	A sequence of instructions that can be chained together, building a workflow start execution operation that can be executed with WorkflowStartInstanceOperation.execute().
WorkflowStartInstanceRequest	Request to start a workflow with the given workflow name and list of documents or record ids and input parameters.
WorkflowStartInstanceRequest.Builder
WorkflowStartInstanceResponse	Contains methods to retrieve information about the result of the workflow start action.
WorkflowStartMetadataRequest	Request to get metadata to start a workflow with the given workflow name and list of documents or record ids.
WorkflowStartMetadataRequest.Builder
WorkflowStartMetadataResponse	Holds the basic info for the specified workflow and the list of WorkflowStartStepMetadata needed to start the workflow.
WorkflowStartStepMetadata	Holds the basic info of the Start Step metadata and a list of WorkflowParameterMetadata.
WorkflowTaskChange	Represents a workflow task that is bring modified.
WorkflowTaskConfiguration	Contains information about the workflow task step configuration.
WorkflowTaskInstance	Represents a workflow task instance created from execution of a task step.
WorkflowTaskQueryParameters	Provides a mechanism to filter workflow task instances.
WorkflowTaskService	Provides methods to retrieve and perform updates for tasks of an active workflow.

Class Summary

Class	Description
WorkflowInputValueTypeImpl<T>	Implementation of a WorkflowInputValueType.

Enum Summary

Enum	Description
WorkflowEvent	Events surrounding workflow execution.
WorkflowItemType	Types of items a workflow can execute on.
WorkflowStartStepType	Start step types.
WorkflowStepType	Types of steps that can exist in a workflow.
WorkflowTaskStatus	Statuses a workflow task instance can be in.
WorkflowType	Types of workflows supported

Annotation Types Summary

Annotation Type	Description
RecordWorkflowActionInfo	Indicates a class is a RecordWorkflowAction that can be executed against a workflow for an object record.

Package com.veeva.vault.sdk.api.workflow Description

This package provides interfaces to create custom actions for workflows and update entities within workflow processing.

Record Workflow Actions

Workflows can have custom actions that perform specific instructions. You can use a custom record workflow action to automate certain business processes on an object or document workflow. Document workflows are a type of object workflow configured on the envelope__sys object. If you are unfamiliar with object or document workflows, you should learn more in Vault Help before coding a record workflow action:

• Configuring Object Workflows in Vault Help
• Configuring Document Workflows in Vault Help

You can configure a custom action for workflows on any of the following steps:

• Start step: Actions configured against a participant control which is invoked during start step events. This action can include logic to populate the workflow participants.
• Task step: Actions which are automatically invoked when a workflow task reaches a specified task event. Learn more about available events in WorkflowEvent.

A record workflow action is a Java class that implements the RecordWorkflowAction interface and has the @RecordWorkflowActionInfo annotation. The RecordWorkflowActionInfo annotation has the following elements:

• label: Label of the action
• object: If specified, the action is only available for object workflows associated to the specified object. If omitted, the action is available across all object workflows.
• stepTypes: The workflow step types that this action can be configured against.

Example: Record Workflow Action on a Start Step

The following example illustrates a custom action available for configuration on the Start step of an object workflow configured for the Product object. Once configured on an object workflow's start step participant control, the action will be invoked on all start step events during workflow execution.

This example executes custom logic on the following events:

• During the DISPLAY_PARTICIPANTS event, this action populates the workflow start dialog with two specific users.
• During the GET_PARTICIPANTS event, this action populates the participant group for the configured participant control with two specific users.
• During the AFTER_CREATE event, this action sends a notification to each participant.

  @RecordWorkflowActionInfo(label="Custom Approver", object="product__v", stepTypes={WorkflowStepType.START})
  public class CustomApprover implements RecordWorkflowAction {
          public void execute(RecordWorkflowActionContext context) {
             WorkflowEvent event = context.getEvent();
             WorkflowInstance workflowInstance = context.getWorkflowInstance();

             WorkflowInstanceService workflowInstanceService = ServiceLocator.locate(WorkflowInstanceService.class);
             WorkflowParticipantGroup participantGroup = context.getParticipantGroup();

             //DISPLAY_PARTICIPANTS only shows the users/groups provided by the RecordWorkflowAction. It's not officially saved until GET_PARTICIPANTS.
             //Generally, you would display and save the same users/groups.
             if (event == WorkflowEvent.DISPLAY_PARTICIPANTS || event == WorkflowEvent.GET_PARTICIPANTS) {
                 getParticipants(workflowInstanceService, participantGroup);
             } else if (event == WorkflowEvent.AFTER_CREATE) {
                 afterCreate(workflowInstance, participantGroup);
             }
         }
         private void getParticipants(WorkflowInstanceService workflowInstanceService,
                                      WorkflowParticipantGroup participantGroup) {
             Set<String> users = VaultCollections.newSet();
             users.add("1000000");
             users.add("1000001");
             WorkflowParticipantGroupUpdate participantGroupUpdate =
                     workflowInstanceService.newParticipantGroupUpdate(participantGroup)
                             .setUsers(users);
             workflowInstanceService.updateParticipantGroup(participantGroupUpdate);
         }
         private void afterCreate(WorkflowInstance workflowInstance,
                                  WorkflowParticipantGroup participantGroup) {
             NotificationService notificationService = ServiceLocator.locate(NotificationService.class);

             String processInstanceId = workflowInstance.getId();
             Set<String> participantUserIds = participantGroup.getUsers();
             String participantGroupLabel = participantGroup.getLabel();

             NotificationParameters parameters =
                     notificationService.newNotificationParameters()
                             .setRecipientsByUserIds(participantUserIds);
             String notificationText = "You were added to the participant group \"" + participantGroupLabel
                     + "\" of workflow " + processInstanceId;
             NotificationMessage message =
                     notificationService.newNotificationMessage()
                             .setSubject("A new workflow started")
                             .setMessage(notificationText)
                             .setNotificationText(notificationText);
             notificationService.send(parameters, message);
         }
    }
 
 

Example: Record Workflow Action on a Task Step

The following example illustrates an action that is available for configuration on the Task step of an object workflow configured for the Product object. Once configured on an object workflow's task step, the action will be invoked on all task events for that workflow task step during workflow execution. The code in this example handles task creation, completion dialog, completion, cancellation, and reassignment/acceptance.

• During the TASK_AFTER_CREATE event, the action logs information for the created task instances.
• During the TASK_BEFORE_COMPLETE_DIALOG event, the action logs information on the items in the workflow.
• During the TASK_AFTER_COMPLETE event, the action cancels all other outstanding task instances for the current task step.
• During the TASK_AFTER_CANCEL event, the action sends a notification to the assignees of each cancelled task instance.
• During the TASK_AFTER_ASSIGN event, the action logs information for the tasks that have been either reassigned or accepted.

  @RecordWorkflowActionInfo(label="Approver Task Action", object="product__v", stepTypes={WorkflowStepType.TASK})
  public class ApproverTaskAction implements RecordWorkflowAction {
         public void execute(RecordWorkflowActionContext context) {
             WorkflowEvent taskEvent = context.getEvent();
             if (taskEvent == WorkflowEvent.TASK_AFTER_CREATE) {
                 handleCreate(context);
             } else if (taskEvent == WorkflowEvent.TASK_BEFORE_COMPLETE_DIALOG) {
                 handleCompleteDialog(context);
             } else if (taskEvent == WorkflowEvent.TASK_AFTER_COMPLETE) {
                 handleComplete(context);
             } else if (taskEvent == WorkflowEvent.TASK_AFTER_CANCEL) {
                 handleCancel(context);
             } else if (taskEvent == WorkflowEvent.TASK_AFTER_ASSIGN) {
                 handleAssign(context);
             }
         }
         private void handleCreate(RecordWorkflowActionContext context) {
             LogService logger = ServiceLocator.locate(LogService.class);
             RecordWorkflowActionTaskContext taskContext = context.getTaskContext();
             WorkflowTaskConfiguration taskConfiguration = taskContext.getTaskConfiguration();
             String participantGroupLabel = taskConfiguration.getParticipantGroupLabel();

             List<WorkflowTaskChange> createdTaskChanges = taskContext.getTaskChanges();
             logger.info(createdTaskChanges.size() + " tasks have been created for " +
                     "participant group " + participantGroupLabel);

             for (WorkflowTaskChange taskChange : createdTaskChanges) {
                 WorkflowTaskInstance createdTaskInstance = taskChange.getNew();
                 String taskId = createdTaskInstance.getId();
                 String assigneeId = createdTaskInstance.getAssigneeId();
                 logger.info("Task " + taskId + " has been created for user " + assigneeId);
             }
         }
         private void handleCompleteDialog(RecordWorkflowActionContext context) {
             LogService logger = ServiceLocator.locate(LogService.class);
             logger.info("[Task before complete dialog] The current workflow has the following items: ");
             List<WorkflowItem> workflowItems = context.getWorkflowItems();
             for(WorkflowItem item : workflowItems) {
                 if(item.getWorkflowItemType() == WorkflowItemType.RECORD) {
                     WorkflowItemRecord record = item.getTypedWorkflowItem(WorkflowItemRecord.class);
                     logger.info("Record: {}.{}", record.getObjectName(), record.getRecordId());
                 } else if(item.getWorkflowItemType() == WorkflowItemType.DOCUMENT) {
                     WorkflowItemDocument document = item.getTypedWorkflowItem(WorkflowItemDocument.class);
                     logger.info("Document Version: {}_{}_{}", document.getId(), document.getMajorVersion(), document.getMinorVersion());
                 }
             }
         }
         private void handleComplete(RecordWorkflowActionContext context) {
             WorkflowTaskService workflowTaskService = ServiceLocator.locate(WorkflowTaskService.class);
             WorkflowInstance workflowInstance = context.getWorkflowInstance();
             RecordWorkflowActionTaskContext taskContext = context.getTaskContext();
             WorkflowTaskConfiguration taskConfiguration = taskContext.getTaskConfiguration();
             WorkflowTaskInstance completedTaskInstance = taskContext.getTaskChanges().get(0).getNew();

             // Find all outstanding task instances (assigned or available) for the current task step
             WorkflowTaskQueryParameters queryParameters = workflowTaskService.newWorkflowTaskQueryParameters()
                     .setStatuses(WorkflowTaskStatus.ASSIGNED, WorkflowTaskStatus.AVAILABLE)
                     .setTaskConfigurations(taskConfiguration);
             List<WorkflowTaskInstance> openTaskInstancesForTask =
                     workflowTaskService.getTaskInstances(workflowInstance, queryParameters);

             // Cancel all other outstanding task instances for the current task step
             List<WorkflowTaskInstance> tasksToCancel = VaultCollections.newList();
             for (WorkflowTaskInstance taskInstance : openTaskInstancesForTask) {
                 if (!taskInstance.getId().equals(completedTaskInstance.getId())) {
                     tasksToCancel.add(taskInstance);
                 }
             }
             if (!tasksToCancel.isEmpty()) { workflowTaskService.cancel(workflowInstance, tasksToCancel); }
         }
         private void handleCancel(RecordWorkflowActionContext context) {
             RecordWorkflowActionTaskContext taskContext = context.getTaskContext();
             String taskLabel = taskContext.getTaskConfiguration().getLabel();
             List<WorkflowTaskChange> cancelledTaskChanges = taskContext.getTaskChanges();
             String workflowLabel = context.getWorkflowConfiguration().getLabel();

             NotificationService notificationService = ServiceLocator.locate(NotificationService.class);

             Set<String> recipients = VaultCollections.newSet();
             for (WorkflowTaskChange taskChange : cancelledTaskChanges) {
                 WorkflowTaskInstance cancelledTaskInstance = taskChange.getNew();
                 String assigneeId = cancelledTaskInstance.getAssigneeId();
                 recipients.add(assigneeId);
             }

             NotificationParameters parameters =
                     notificationService.newNotificationParameters()
                             .setRecipientsByUserIds(recipients);
             String notificationText = "Task \"" + taskLabel + "\" was cancelled for workflow \"" + workflowLabel + "\".";
             NotificationMessage message =
                     notificationService.newNotificationMessage()
                             .setSubject(notificationText)
                             .setMessage(notificationText)
                             .setNotificationText(notificationText);
             notificationService.send(parameters, message);
         }
         private void handleAssign(RecordWorkflowActionContext context) {
             RecordWorkflowActionTaskContext taskContext = context.getTaskContext();
             WorkflowTaskChange taskChange = taskContext.getTaskChanges().get(0);
             WorkflowTaskInstance newTaskInstance = taskChange.getNew();
             WorkflowTaskInstance oldTaskInstance = taskChange.getOld();
             WorkflowTaskStatus newTaskStatus = newTaskInstance.getStatus();
             WorkflowTaskStatus oldTaskStatus = oldTaskInstance.getStatus();

             String taskId = newTaskInstance.getId();
             String newAssigneeId = newTaskInstance.getAssigneeId();
             String oldAssigneeId = oldTaskInstance.getAssigneeId();

             LogService logger = ServiceLocator.locate(LogService.class);
             if ((oldTaskStatus == WorkflowTaskStatus.ASSIGNED) && (newTaskStatus == WorkflowTaskStatus.ASSIGNED)) {
                 logger.info("Task " + taskId + " has been reassigned from user " + oldAssigneeId + " to " +
                         "user " + newAssigneeId);
             } else if ((oldTaskStatus == WorkflowTaskStatus.AVAILABLE) && (newTaskStatus == WorkflowTaskStatus.ASSIGNED)) {
                 logger.info("Task " + taskId + " has been accepted by user " + newAssigneeId);
             }
         }
    }