Flows for APEX v25.1: Working even Better with APEX Human Tasks

Oracle introduced the APEX Approval Task in APEX 22.1, extended it to non-approval Human Tasks with Action Tasks in APEX 23.2, and has enhanced the overall functionality of APEX Human Tasks in each APEX release. Flows for APEX, the BPMN process modelling and workflow engine for Oracle APEX, has supported APEX Approval Tasks as a task step in a BPMN-based workflow since 2022, but in the 25.1 release, we’ve refreshed our integration with APEX Human Tasks, fixing some difficulties and adding extra capabilities.

When would you use APEX Human Tasks in a Flows for APEX Workflow?

Sometimes, your workflow is really simple - you just need a simple approval from a manager, and you don’t need to control your business process from a workflow engine. But there are other cases when you have a more complex business process that includes management approvals, sometimes going up to 4 or 5 levels of management, and sometimes going up multiple management hierarchies in parallel before everyone approves!

APEX Human Tasks as part of a BPMN workflow in Flows for APEX gives you the best of both worlds. You get to use the rapid generation features of APEX tasks, including visually appealing, auto-generated Task List and Task Detail pages while being able to include these in a BPMN-based workflow that allows parallel execution of approval chains modelled with the industry standard BPMN 2.0 that your business analysts and managers already know.

How are APEX Human Tasks integrated into a Flows for APEX workflow?

At its simplest, a BPMN workflow breaks a business process down into tasks, events, and gateways. Tasks can be performed by a human at a computer (a user task), a script ( a script task), by calling some service (a service task), etc.. Processes either trigger or wait for various Events to occur, such as sending a message, waiting for and receiving a message, detecting a process error, etc. And Gateways control the flow of the process between tasks and events, allowing the process to change direction (an Exclusive Gateway), go in multiple parallel paths (a Parallel Gateway), or conditional parallel paths (an Inclusive Gateway), or react to the first of several events occurring.

The BPMN User Task is used for Human Tasks. In Flows for APEX, a user task can be implemented in your application by calling an APEX page that you have built ( an APEX Page Task), by calling an APEX Human Task (an APEX Approval or Action Task), or using our development-less option using a dynamic Simple Form, where the items to be collected from the user are defined as a simple JSON definition, and the input form is dynamically created by the application at run time without having to define an APEX page.

You can test drive our Expense Claim Demo App that contains all types of user tasks. The Expense Claim Demo App is shipped with the Flows for APEX Community Edition v25.1 software distribution - meaning it can be installed in under a minute.

So what’s new in Flows for APEX 25.1?

We’ve added several enhancements to our integration with APEX Human Tasks. Here’s the list of new features, and we’ll then take these one by one to show what they do.

• Task Assignment from the Flows for APEX Workflow.

• Business Admin assignment from Flows for APEX.

• Better cleanup when tasks are cancelled.

• New Task Action plugin to return task state and approval outcomes.

• Support for ‘Originator can Approve’.

• Visibility of APEX task information from the Flow Monitor.

• Removed Group Assignment for APEX Tasks until supported.

In addition, we’ve revised and extended the documentation on how to configure the generated APEX Task List to combine tasks from Flows for APEX, APEX Workflow, and APEX Human Tasks. This is the subject of another blog post Unifying all Tasks: Integrating Flows for APEX into the APEX Task List

Let’s look at these improvements in more detail.

Task Assignment from the Flows for APEX Workflow.

If a task forms part of a larger business process, it’s likely that the workflow engine may often have a better understanding of who should be assigned the task. So you want the workflow engine to be able to set the potential owners for a task, and you’d like to be able to determine this assignment in the workflow definition, rather than having a set of rules inside the task.

The APEX Human Task API doesn’t allow us to pass the list of potential owners into a task when it is created, and only the task Business Admin can add or remove potential owners once it has been created. But the task can be defined to evaluate a PL/SQL expression to set potential owners (and business admins), and so we have provided a new Flows for APEX API call that allows you to ask Flows for APEX who the potential owners should be. This call is:

    flow_api_pkg.get_task_potential_owners ( p_process   in flow_processes.prcs_id%type,
                                             p_subflow   in flow_subflows.sbfl_id%type,
                                             p_step_key  in flow_subflows.sbfl_step_key%type
                                            );

This will return a list of the task’s potential owners from Flows for APEX, with the comma delimiter required for APEX Tasks.

If you were using APEX approvals with Flows for APEX in earlier versions, we recommended passing PROCESS_ID as a parameter into your APEX task. From 25.1 onwards and to use these new functions and the new plug-in (details below) you should now pass PROCESS_ID, SUBFLOW_ID, and STEP_KEY as parameters into your APEX task. (Sorry - we need all three to be able to unambiguously refer to the task before the APEX Task ID is assigned!)

The task potential owners can de defined as part of the BPMN user task definition, and can be defined as:

• a static value

• the contents of a Flows for APEX process variable

• a SQL Query returning a single or multiple values

• a PL/SQL expression

• a PL/SQL function body

Business Admin Assignment from the Flows for APEX Workflow

Similar to the above description of how and why to set a task’s Potential Owners from Flows for APEX, we can now also set the Task’s Business Administrator from Flows for APEX, starting in Flows for APEX 25.1. The Business Admin is an important person - as only the Business Admin can add or remove potential owners, and only the Business Admin and the Task Initiator can cancel a task. Having an appropriate Business Admin set from the workflow definition allows intelligent choices of Business Admin based on the context of the task; large organisations might want to have a business admin in the same group as the task assignee, or if the approval is expected to occur quickly, it might be a duty manager or someone not on vacation.

The Business admin can now be defined in the BPMN diagram in the properties panel for a BPMN User Task that calls an APEX Human Task. Like the definition of a potential. owner, the business admin can be defined as a static value, from a process viable, or from a query, expression or function body.

It’s important that a Business Administrator is defined, and that Flows for APEX knows who it is - as we need to know in order to be able to cancel any tasks that need clearing up after a process is deleted, terminated or reset, or if it is cancelled as a result of a BPMN interruption or some other process flow issue. In order to help you ensure that there is always an admin defined, you can now also specify a process-level default business administrator in the bpmn:process definition in your process diagram. And to be extra sure, you can also define a Flows for APEX system-wide business administrator as a configuration parameter default_apex_business_admin in the configuration form on the Flows for APEX Application.

Similar to setting a task potential owner, the task business admin can be set in your APEX Task Definition to callback to Flows for APEX to get. the Business Admins, this time using the API call flows_api_pkg.get_task_business_admins. Note the extra two parameters, giving you the option to include either the diagram-level default admin or the system-wide admin from the configuration parameters. Here’s the syntax:

flow_api_pkg.get_task_business_admins ( p_process in flow_processes.prcs_id%type,
                                        p_subflow in flow_subflows.sbfl_id%type, 
                                        p_step_key in flow_subflows.sbfl_step_key%type,
                                        p_add_diagram_admin  in boolean default false,
                                        p_add_instance_admin in boolean default false);

With the Business Admin defined and known to Flows for APEX, we are now able to have our next new feature…

Better Cleanup of Cancelled Tasks

An APEX Human Task can only be cancelled by its initiator or one of its Business Administrators. So in previous releases, approval tasks were often left behind if the process that created them was deleted, reset or terminated, or if the task was cancelled due to an interruption or its parent sub process being terminated. With Flows for APEX v25.1, we should be able to clean up any of these orphan tasks.

When an APEX Human Task requires cancellation from the workflow, we first attempt to cancel it in the current user session. This only succeeds if the current user initiated the task or is a business admin for the task. If this is not successful, Flows for APEX will now user the database scheduler to run a job in a background process which creates an APEX session as a Business Admin, and cancels the task. If there is not a valid business admin defined, instead it will create an APEX session as the initiator, and cancel the task.

For. those wanting more technical detail, we create a DBMS_SCHEDULER program , named APEX_FLOW_CANCEL_APEX_TASK_P as part of installation or migration to Flows for APEX v25.1, and then run an immediate JOB using that program to do the deletion. The Flows for APEX user requires the CREATE JOB database system privilege in order to create this and to run timers.

New APEX Task Action Plugin - ‘Flows for APEX - Return APEX Human Task State and Outcome’

We’ve had an APEX Task Action Plugin available since Flows for APEX v22.1 that returns the Approval result (‘Flows for APEX - Return to Flows for APEX’) - but in Flows for APEX v25.1 we’ve created a new and enhanced plugin with slightly different interface named ‘Flows for APEX - Return APEX Human Task State and Outcome’.

Firstly, for those of you with applications using the old plugin, don’t worry! The old plugin and its interface still exist are unchanged — but we think that you should change to the new plugin sometime soon, once you have 25.1 installed and running! We’ll keep it in 25.1 and the following release, but likely remove it in a subsequent release.

Using the new plugin, your APEX Human Task should have Task Parameters that include at least the three Flows for APEX state parameters, PROCESS_ID, SUBFLOW_ID, and STEP_KEY.

Like the old plugin, the new plugin can return the Outcome of an APEX Human Task that has an Outcome (that’s currently an Approval Task, which has Outcomes of APPROVED or REJECTED).

In addition, the new plugin also returns the State Code from an APEX Human Task. This allows you to use the plugin to tell its controlling Flows for APEX workflow that the APEX Human Task is COMPLETED, or that it has been CANCELLED or that it has EXPIRED*. Unfortunately, you can’t currently define an action if it has ERRORED.

Configuring each of the Task Actions in APEX is simple - we just need to select action type to use the `Flows for APEX - Return APEX Human Task State and Outcome [plug-in]’ and the default values should work for you. The Task Action configuration should look like this:

Note that EXPIRED is only relevant if you have defined an expiration policy in the APEX Human Task definition. Note also that there is an open APEX bug in 24.1 and 24.2 such that the Expiration task action does not correctly report its expired state. Until this is fixed (which we understand should be in 25.1), you can write your own PL/SQL code instead of using the plugin. Just set the Action Type to Execute PL/SQL and use the following pl/SQL code:

begin
    flow_api_pkg.return_task_state_outcome 
    ( p_process_id => :PROCESS_ID
    , p_subflow_id => :SUBFLOW_ID
    , p_step_key   => :STEP_KEY
    , p_apex_task_id => :APEX$TASK_ID
    , p_state_code => 'EXPIRED' -- have to hard code this due to APEX bug
    , p_outcome => null
    );
end;

In Flows for APEX 24.1 and earlier, a task that had been cancelled, errored, or expired meant that you had a stuck Flows for APEX process instance. Now, if you define Task Actions to pass the task state back to Flows. for APEX, the workflow engine can react appropriately as follows.

Support for ‘Initiator Can Approve’

Until APEX v24.1, the separation of duties rule that ‘a task initiator couldn’t approve his own approval request’ was strictly enforced in APEX Approval Tasks. However, Oracle changed this in APEX 24.1, allowing a task to be able to ignore this rule if it was defined in the task definition, was set at task creation time, or subsequently allowed by a business admin.

In Flows for APEX v25.1, you can now set this parameter from Flows for APEX for a specific Human Task instance, and this will be passed through to the APEX Human Task at task creation time.

Removal of (non functioning) Group Task Assignment

APEX Human Tasks can currently only to assigned to named APEX users, and can’t be assigned to a group or a role. In earlier versions of Flows for APEX, we allowed you to define group / role assignment roles — which we couldn’t process. So in Flows for APEX v25.1, we’ve taken the Group Task Assignment away for BPMN User Tasks of type APEX Human Task. I hope that we can put them back at some future date when APEX can do something with them.

Viewing Task Status and Meta-data from the Flow Viewer

In the past, once an APEX Human Task was created, it became a bit of a black hole to the Flows for APEX administrator. After giving the task to APEX to manage, we didn’t provide much information to you until the task had been completed, and control passed back to Flows for APEX. You needed to run your own queries on the APEX tasks meta data - which, being Oracle, is not difficult. But we’ve made all of this much easier in Flows for APEX v25.1! If you are looking at the status and other information about a step in the Flow Viewer (right click on the task in the Flow Viewer in Flow Monitor to get a pop-up window showing the step definition, step events, step errors, etc. Now, if the step is an APEX Human Task, you will see its Task ID in the Step Events tab; clicking on the Task ID brings up a modal window showing the task meta data, status, current task assignment, and task history — so that you can see the current status of the task right from Flows for APEX.

From using this feature while we created and ran many APEX Human Tasks during development and testing of Flows for APEX v25.1, I find that this makes APEX Human Tasks so much easier to use, and makes them feel integrated into Flows.

Editions

All of the features described above have been added to Flows for APEX v25.1, now available, in both the Community Edition (open source, free of charge on a MIT licence) and to the Enterprise Edition (supported edition with additional functionality, available from Flowquest). Development of features like this are possible because of the development resources that come from the Enterprise Edition - so please consider upgrading to the Enterprise Edition if your organisation is getting significant value from Flows for APEX or would benefit from having product support!

Summary

We hope that this set of enhancements will make APEX Human Tasks easier to use, feel much more integrated, and become more powerful than they have been to-date. We can’t wait to hear what you have been able to do by combining APEX Human Tasks into your Flows for APEX workflows.

More Information

For more information on this topic, see the product documentation.

Need advice or further information or advice - schedule an introductory chat with Richard.