APEX Approvals and Workflow Enhancements

As part of APEX release 24.1, there are several improvements to the Approvals and Workflow functionality. My colleague, Colin Archer, wrote a blog about the Workflow Designer, first introduced in APEX 23.2, which you can read here.

In this blog, I will explain some of the new features Oracle have added to Approvals and Workflows, building on the Claims Approval application that Colin created.

Workflow Dashboard Page and Workflow Diagram

The Workflow Dashboard page can now be optionally added as an extra page as part of the Workflow Console create page wizard.

The Workflow Diagram region type allows you to embed a diagrammatic display of the status of your workflows into your applications. The diagram is included by default on the creation of a new Workflow Console page or can be added to existing pages from the region’s gallery in Page Designer.

Once the new Workflow Console, associated Workflow Details page, and Workflow Dashboard page were created in the Claims Approval application, I ran the application. I created several new claims that required the completion of a Human Task – to approve the claim. Then, either via the My Tasks (Unified Task List) page or Workflow Console page, I approved (Completed), cancelled (Faulted), Suspended or Terminated one of each of these claims.

Workflow Dashboard Page

The automatically created dashboard has four regions

• Workflows By State (see image above)
  • Pie (left) displays the distribution of workflows by state
  • Click on the state segment to display (right) Details of the number of instances of each workflow with that state.
• Active Workflows
  • The overview chart shows the number of instances of each workflow in an active or waiting state.
  • Clicking on a workflow in the Overview chart displays the number of instances that are waiting by different activities
• Faulted Workflows
  • The overview chart shows the number of instances of each workflow in a faulted state.
  • Clicking on a workflow in the Overview chart displays the number of instances that have been faulted by different activities.
• Performance
  • Shows the average instance completion time by workflow

Although it’s an APEX-generated page, the dashboard can be customised to suit your needs like any other page.

Workflow Diagram

Now, in the Workflow Console, by selecting a specific instance to open the Workflow Details page, a new Workflow Diagram region is available for display. The diagram shows the status, progress and path taken through the workflow for that instance.

The workflow diagram can be added as a region to existing pages. There is a mandatory requirement to specify a workflow ID for the region specified in the region attributes.

Active / Suspended

For active or suspended workflows, completed activities are highlighted in green, with the current activity highlighted in blue.

Completed

For active workflows, the path taken to complete the workflow is highlighted in green.

Faulted

For faulted workflows, completed activities are highlighted in green, with the current failure activity highlighted in red. Further details of the reason for the fault, if available, may be provided in the Activities region of the Workflow Details page.

Terminated

For terminated workflows, completed activities are highlighted green, with the current failure activity highlighted orange. A slight change for release 24.1 is that now, for Terminated workflows, any associated Human Task activities will be cancelled automatically.

Vacation Rules

Rules can be specified to substitute task participants when creating or delegating tasks e.g., to accommodate absences of approvers. This is done by specifying a procedure at the application level (Edit Application Definition > Workflow Settings > Task Vacation Rule Procedure) or in the task definition (Participants > Vacation Rule Procedure). Rules specified at the task level will override rules specified at the application level.

The Approve Claim workflow currently has one Human Task associated with it - the Claim Approval task. Currently, the Potential Owner participant essentially allows anyone to be the approver. So, I have created two new users:

• JOE_BLOGGS – the default Claim approver
• ANN_MANGER – the vacation stand-in approver

I also created a new Unified Task List page, ‘My Approvals’, with Report Context set to ‘My Tasks’ so that there is a page where JOE_BLOGGS and ANN_MANGER can access the Claims raised by me that need approving.

I have created a new stored procedure, ‘demo_vacn_pkg.vacation_claim_approvers’, that defines a simple vacation rule.

Procedure specification:

  -- Vacation Rule Procedure

 procedure vacation_claim_approvers(
     p_param   in apex_approval.t_vacation_rule_input,
     p_result  out apex_approval.t_vacation_rule_result
 );

Procedure body:

 -- Vacation Rule Procedure
 procedure vacation_claim_approvers(
     p_param   in apex_approval.t_vacation_rule_input,
     p_result  out apex_approval.t_vacation_rule_result
 )
 is
     l_result            apex_approval.t_vacation_rule_result;
     l_changes           apex_approval.t_task_participant_changes;
     l_participants      apex_approval.t_task_participants;
     l_new_participant   apex_approval.t_task_participant;
     l_old_participant   apex_approval.t_task_participant;
     l_has_changed       boolean                             := false;
     l_index             pls_integer                         := 1;
 begin
     l_participants := p_param.original_participants;
     for i in 1..l_participants.count loop
         if l_participants(i).value = 'JOE_BLOGGS' then
             l_old_participant               :=  l_participants(i);
             l_new_participant.value         := 'ANN_MANGER';
             l_new_participant.type          := 'POTENTIAL_OWNER';
             l_new_participant.identity      := 'USER';
             l_has_changed                   := true;
         end if;
     end loop;
     if l_has_changed then
         l_participants(l_participants.count + 1) := l_new_participant;
         l_changes(l_index).old_participant   := l_old_participant;
         l_changes(l_index).new_participant   := l_new_participant;
         l_changes(l_index).change_reason     := 'Joe Bloggs is on vacation';
     end if;

     l_result.participant_changes            := l_changes;
     l_result.has_participant_changes        := l_has_changed;
     p_result                                := l_result;
 end;

Key things to note about the procedure:

• The human task vacation rules must use the following signature:

procedure my_vacation_rule (
    p_param in apex_approval.t_vacation_rule_input,
    p_result out apex_approval.t_vacation_rule_result
);

• Essentially, the ‘vacation_claim_approvers’ procedure checks the list of participants, and if JOE_BLOGGS is the potential owner, then ANN_MANGER is added as an alternate potential owner.  Also, a reason for the absence can be specified.
• ‘apex_approval.t_vacation_rule_result’ has two attributes:
  • ‘apex_approval.t_vacation_rule_result.participant_changes’ and
  • ‘apex_approval.t_vacation_rule_result.has_participant_changes’
• ‘apex_approval.t_vacation_rule_result.participant_changes’ itself has three attributes
  • ‘old_participant’
  • ‘new_participant’
  • ‘change_reason’

Then, we need to update the application or task definition to reference the procedure for setting vacation rules.  In my case, I used the task definition.

The final change we need to make is to the Task Details page so that the History report displays the alternate participant and the participant change reason in case a vacation rule is triggered. I added two new columns, ‘alternate_participants’ and ‘participant_changed_reason’, to the Task Details History report SQL.

We can now test the vacation rule. After raising a new claim that requires human approval, if I sign in as ANN_MANGER and head to the ‘My Approvals’ page, the claim is available for her approval.  It’s worth mentioning that JOE_BLOGGS is also still able to approve this claim - triggering a vacation rule does not remove the original participant, it only adds the alternate participant to the list of existing participants.

Notice that the approval task is unassigned. This is because there is more than one approver for the task, so either can Claim and act upon the task – although a task does not have to be claimed before it is approved or rejected.

On viewing the details for the task, we can see details that alternate participants and participant change reasons are displayed.

Other Enhancements

Debug

Workflow instance ID can now be included in Debug messages. Add column Workflow Instance to the displayed columns in the View Debug interactive report via the developer toolbar.

Task Initiator as Approvers

Developers can now specify whether task initiators can approve/reject a task. This can be set in the task definition (Settings > Initiator Can Complete) or in the Human Task – Create process definition (either as a page process or a Workflow Designer activity).

Summary

For APEX 24.1, Oracle has made some small but useful enhancements to enrich the Workflow and Approvals functionality. To my mind, the Workflow Diagram and Vacation Rules are most useful. The workflow diagram more clearly demonstrates the path taken through the workflow for a specific instance. The Vacation Rules provide a mechanism for temporarily substituting task participants to, for example, accommodate the absences of approvers.

For more information, check out our Oracle APEX Services, and if you liked this blog, check out our other APEX blogs here.

Subscribe to Oracle APEX Insights if you want to stay tuned for more APEX updates.