Recap

The Approvals Component for creation and management of human tasks was released in APEX 22.1. For reference see this blog. In the later releases of APEX, the feature was further enriched with steady enhancements like

• Non-approval Action Tasks 
• Request and Submit Information, Task Expiry and Renewal,
• Updateable task parameters , Business Administrator operations like Invite and Remove participants for an in-flight task,etc.

One of the regular requests from our customers and users has been to provide a mechanism for specifying alternate participants of a task when the original participant is absent or on leave.

This is precisely what this blog is going to talk about! We will use the Sample Workflow, Approvals and Tasks Sample Application from the Gallery as our example.

Install Sample Data

1. Navigate to Gallery > Sample Apps
2. Select Sample Workflow, Approvals and Tasks and click on the Install Button

Define Vacation Rule Procedure

Once the application is installed, navigate to SQL Workshop > Object Browser > Packages and open the EBA_DEMO_APPR package.

Add the following procedures to the specification.

   -- Vacation Rule Procedure for Salary Change
    procedure alternate_owners_for_approver(
                p_param   in apex_approval.t_vacation_rule_input,
                p_result  out apex_approval.t_vacation_rule_result);
    --            
    -- Vacation Rule Procedure Defined at Application Level
    procedure alternate_job_approvers(
                p_param   in apex_approval.t_vacation_rule_input,
                p_result  out apex_approval.t_vacation_rule_result);

Navigate to the package body and add the implementations for the procedures

procedure alternate_owners_for_approver(
                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 = 'BO' then
                l_old_participant               :=  l_participants(i);
                l_new_participant.value         := 'MARTIN';
                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     := 'Bo is out on bereavement leave';
        end if;

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

    procedure alternate_job_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 = 'JANE' then
                l_old_participant               :=  l_participants(i);
                l_new_participant.value         := 'SCOTT';
                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     := 'Jane is out on maternity leave';
        end if;

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

Click Save and Compile to save the package changes.

Note: As shown in the code snippets above, the Human Task Vacation Rule procedures must implement the following interface

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

The procedure input is of type apex_approval.t_vacation_rule_input and the result output is of type apex_approval.t_vacation_rule_output

What are the procedures doing?

The alternate_owners_for_approver() API is checking the list of participants and in case BO is specified as an owner, then the API adds MARTIN as the alternate owner, and also adds a reason for BO's absence.

The alternate_job_approvers() API adds SCOTT as an alternate approver for JANE because JANE is out on maternity leave.

Note: The apex_approval.t_vacation_rule_output.participant_changes type has three attributes: old_participant, new_participant and change_reason.

Specify the Vacation Rule Procedures in your Application

Navigate to App Builder and click on Edit Application Definition.

In the next page, click on the Workflow Settings tab.

In the Task Vacation Rule Procedure, enter eba_demo_appr.alternate_job_approvers

Click on Apply Changes.

Note: When you specify a vacation rule procedure in the Application Definition, then it automatically applies to all task definitions in that application.

Navigate to Shared Components, Workflows And Automations and Click On Task Definitions.

In the Task Definitions Report, Click on the Salary Change Task Definition.

In the Task Definition Editor, click on the Participants Tab

In the Task Vacation Rule Procedure, enter eba_demo_appr.alternate_owners_for_approver

Click on Apply Changes to save the changes.

Note: When you specify a vacation rule procedure in the Task Definition, it overrides any vacation rule procedure specified in the application definition. So, for the Salary Change approval, the alternate_owners_for_approver vacation rule will be triggered instead of the alternate_job_approvers defined at the application level.

Modifying the Task Details Pages

We will now modify the Salary Change and Job Change Task Details pages so that the Task History displays the alternate participant and the participant change reason in case a vacation rule was triggered.

Open Page 15 ( Salary Change Details) in the Page Designer and select the History report under the History Region. Modify the Report query as shown below to add the columns alternate_participants and participant_changed_reason to the query result.

select event_type,
       event_timestamp,
       event_creator,
       display_msg,
       alternate_participants,
       participant_changed_reason
  from table ( apex_approval.get_task_history (
                   p_task_id     => :P15_TASK_ID,
                   p_include_all => :P15_ALL_HISTORY ) )

Save the changes.
Repeat the same steps for Page 2 (Task Details) which is the task details page associated with the Job Change Task Definition.

Running the modified Sample

Run the application. You will be directed to the Log In Page. Select STEVE and then Click On Log In AS STEVE as shown below

Navigate to the Setup Page and check the existing Salary Change Approvers

The table shows that BO is the approver for job titles CLERK, MANAGER and PRESIDENT. Since our salary change vacation rule adds MARTIN as alternate participant for BO, we will try to verify this by requesting Salary Change for employees having these job titles.

Click on the Employees Page and click on the Edit Salary link for  MILLER who has Job code of CLERK.

Change the salary to 2000 and hit Submit.

Go to Pending Approvals to see the actual approvers for the task that got created.

You will notice that the task is assigned to both BO (original approver) and MARTIN (alternate approver). Note that the triggering of a vacation rule does not remove the original participant, it only adds the alternate participant to the list of existing participants. This way, BO is free to act on his tasks even if he is out of office if he wants to. However, MARTIN is also available to do this for him in his absence.

Go to My Requests to view the history of the salary change task that was created.

Notice that the task is Unassigned. This is because it has more than one approver (BO and MARTIN), so either of them can Claim and act upon the task.

Click on the task subject to open the Salary Change Details page. Navigate and expand the History section of the page.

Note that the Alternate Participants and Participant Changed Reason show that the vacation rule was fired at the time of task creation.

You can now log in as either MARTIN or BO to approve this task.

Summary

Here are some other steps you can try in order to familiarize yourself with the vacation rule feature of APEX Human Tasks!

1. Log In as STEVE and create a Job Change Request for ADAM from the Employees page. The original potential owners of this task are Jane, Bo and Steve.
2. Open the Pending Approvals page and check if SCOTT is shown in the list of owners in addition to JANE, BO and STEVE. The vacation rule defined at the Application level adds SCOTT as an alternate participant for JANE.
3. Go to My Requests Page and check the task history to see if SCOTT is listed as an Alternate Participant and the Participant Changed Reason shows up in the History report.
4. Log in as SCOTT and approve the task.
5. Edit the Application Definition and remove the vacation rule procedure from the Workflow Settings. Then re-do steps 1 and 2. This time you will not find SCOTT in the list of potential owners.
6. Re-edit the Application Definition and add back the eba_demo_appr.alternate_job_approvers to the Workflow Settings > Task Vacation Rule Procedure
7. Log in as BO. Claim the Task created in Step 5, and then delegate the task to JANE. You will find that the task gets delegated to SCOTT and the task history shows the Alternate Participant as JANE and the Participant Changed Reason shows up correctly.
   This is because, the vacation rules also get fired at the time of delegating a task to another potential owner, if the owner is out-of-office and has an alternate owner defined.
8. You can modify the vacation rules to also set up alternate Business Administrators in case a Business Administrator is out-of-office.

In short...

The Vacation Rules feature promises to be a powerful add-on to APEX's human task management capabilities. No more coming back from vacation to be greeted with an endless list of pending approvals!