Work with process status

Use process status elements to keep track of a running workflow. Status elements can be retrieved and monitored. Elements might be milestones reached within a running workflow, workflow steps completed, which participants are completing these steps, and other valuable information about the workflow. The main components of process status indicators are workflow history and milestones elements:

򐂰 Workflow milestones

To track the progress of a workflow, key points (milestones) are included within a workflow definition. On each workflow map, a milestone can be placed either before or after a step. Each of these milestones is related to a message that is specified by the workflow designer. The message is written to a log file when the running workflow reaches the milestone.

򐂰 Workflow history

To track workflow activity, workflow-related historical information is extracted from the event logs, which contain specific records related to a workflow event for each PE-isolated region. This historical information is useful to track workflow-related activities, such as how long workflows take to complete and which workflows are currently running.

5.7.1 Retrieve process history

To retrieve the information about the workflow history by using the PE Java API: 1. Retrieve the work item object.

2. Get VWProcess object from the work object. 3. Get the workflow definitions from the VWProcess. 4. Get the maps for each workflow definition.

5. Get the workflow history information for each map. 6. Get the step history objects for each workflow history.

7. Get the step occurrence history objects for each step history object. 8. Get the step work object information for each step occurrence. 9. Get the participant information for each work object.

Table 5-12 Process history information

Example 5-25 shows how to retrieve information about the workflow history by using the Java API

Example 5-25 Retrieve workflow history information using the Java API

// Create session object and log onto Process Engine ...

// Get the specific work item ...

// Get VWProcess object from work object VWProcess process = stepElement.fetchProcess(); // Get workflow definitions from the VWProcess VWWorkflowDefinition workflowDefinition = process.fetchWorkflowDefinition(false); // Get maps for each workflow definition

VWMapDefinition[] workflowMaps = workflowDefinition.getMaps(); // Iterate through each map in the workflow Definition

for (int i = 0; i < workflowMaps.length; i++) { // Get map ID and map name for each map definition int mapID = workflowMaps[i].getMapId();

String mapName = workflowMaps[i].getName(); // Get workflow history information for each map VWWorkflowHistory workflowHistory =

process.fetchWorkflowHistory(mapID);

String workflowOriginator = workflowHistory.getOriginator();

Process Engine object Information to retrieve

VWProcess Status, history, child, and split work object information VWProcessHistory Launch step comments, launch date, workflow

originator, launch step response

VWStepHistory Step occurrence completion date, date participant received work, step status

VWStepOcurrenceHistory Step name

VWStepWorkObjectHistory Whether this process was completed

VWParticipantHistory Comments, responses, dates completed and received, exposed log fields, activity status, name of participant who completed, delegated, reassigned, returned, or terminated step

// Iterate through each item in the Workflow History while (workflowHistory.hasNext()) {

// Get step history objects for each workflow history VWStepHistory stepHistory = workflowHistory.next(); // Iterate through each item in the Step History while (stepHistory.hasNext()) {

// Get step occurrence history

// objects for each step history object

VWStepOccurrenceHistory stepOccurenceHistory = stepHistory.next(); Date stepOcurrenceDateReceived = stepOccurenceHistory.getDateReceived(); Date stepOcurrenceDateCompleted = stepOccurenceHistory.getCompletionDate(); while (stepOccurenceHistory.hasNext()) {

// Get step work object information // for each step occurrence

VWStepWorkObjectHistory stepWorkObjectHistory = stepOccurenceHistory.next();

stepWorkObjectHistory.resetFetch();

// Get participant information for each work object while (stepWorkObjectHistory.hasNext()) { VWParticipantHistory participantHistory = stepWorkObjectHistory.next(); Date participantDateReceived = participantHistory.getDateReceived(); String participantComments = participantHistory.getComments(); String participantUser = participantHistory.getUserName(); String participantName = participantHistory.getParticipantName(); } // while stepWorkObjectHistory } // while stepOccurenceHistory

5.7.2 Retrieve process milestones

The following steps are included to retrieve the workflow milestones history information using the PE Java and Web services APIs:

1. Retrieve the work item object.

2. Get VWProcess object from the work object.

3. Get all milestones definition from the VWProcess object. 4. Get reached milestones from the VWProcess object. 5. Get milestone element information for each milestone. 6. Handle information for each milestone element.

Each milestone that is defined within a workflow is associated with a level (1 - 99). The workflow-reached milestones are based on the milestone level that is specified. For example, if the milestone level is set to 5, reached-milestones of levels 1 - 5 are retrieved.

Example 5-26 and Example 5-27 on page 166 show how to perform the steps required to retrieve the workflow milestones history information, using both the Java API and a PEWS client.

Example 5-26 Get milestones of a workflow using the Java API

// Create session object and log onto Process Engine ...

// Get the specific work item ...

// Get VWProcess object from work object ...

// Get all milestones definition from the workflow process VWMilestoneDefinition[] milestonesDefinition =

process.getMilestoneDefinitions();

for (int i = 0; i < milestonesDefinition.length; i++) { // Milestone element information

VWMilestoneDefinition milestoneDefinition = milestonesDefinition[i]; String milestoneName = milestoneDefinition.getName();

String milestoneMessage = milestoneDefinition.getMessage(); int milestoneLevel = milestoneDefinition.getLevel();

}

// Get reached milestones from the VWProcess object int level = 99;

VWWorkflowMilestones milestones =

process.fetchReachedWorkflowMilestones(level); while (milestones.hasNext()) {

VWMilestoneElement milestoneElement = milestones.next(); String milestoneName = milestoneElement.getName(); String milestoneMessage = milestoneElement.getMessage(); Date milestoneTimeLogged = milestoneElement.getTimestamp(); }

Example 5-27 Get milestones of a workflow using PEWS

// Create the PEWS RequestSoapContext header ...

// Get milestones work object from the roster string rosterName = "DefaultRoster";

string wobnum = "5BDD567B70453C48A5388AC56ABC69E4"; peWS.GetMilestoneForRosterElementRequest query = new peWS.GetMilestoneForRosterElementRequest (); query.milestoneLevel = 99; query.rosterName = rosterName; query.queryValue = wobnum; query.queryEnum = peWS.MilestoneQueryEnum.MILESTONE_QUERY_WOBNUMBER; peWS.Milestone [] milestones = peWSServicePort.getMilestoneForRosterElement(query); if (milestones!=null) {

foreach (peWS.Milestone m in milestones) {

// Milestone element information string map = m.Map;

string milestoneMessage = m.Message; string milestoneName = m.Name; int milestoneId = m.Id;

int milestoneLevel = m.Level; int stepId = m.StepId;

DateTime milestoneDateReached = m.Reached; }