User Task Settings

Configuring User Tasks

BPMN User Tasks are tasks that need to be performed by a computer user using the system. User Tasks, in other environments, are sometimes referred to as ‘Human Tasks’.

Flows for APEX supports three types of BPMN User Task:

1. APEX Page UserTask. This is a task that is built using a standard page in an APEX application.
2. APEX Human Tasks (APEX Approval Tasks or APEX Action Tasks). This is a task that is implemented using the APEX Human Task functionality, present in APEX v22.1 onwards, where the task is managed by APEX itself.
3. APEX Simple Form. This is a new task created for Flows for APEX v24.1 to collect simple information from the process user, where the informatio and form are specified in a simle JSON document without requiriung APEX developer skills.

This section describes how to configure each of these user task types.

Setting Up an APEX Page UserTask

APEX Page Usertasks put a link to an APEX page into the Task List when they become the current object. The page link includes page item and values to be set. The Task is managed by Flows for APEX.

APEX Page User Tasks: APEX Page userTasks are configured in the APEX Page tab of the Flows for APEX flow modeler properties panel with the information required to call an APEX page.

Task Type

Task Type should be set to APEX Page.

APEX Page

These settings control the page that is called, the APEX items that are set and their values, along with APEX cache and request settings. Most of these settings will be familiar to anyone who has configured APEX menus.

The Modeler can make use of APEX metadata already stored in the database about your application and its objects. You can toggle the Use APEX metadata switch on or off as you configure the page link.

Select the Application and Page that you want this task link to call, either from the APEX metadata or by entering an applicationID and a Page number in that app.

Page Items. Creates one or more APEX Items that should be set, along with the values to set them to.

• Press the green Generate default items to add items for PROCESS_ID, SUBFLOW_ID, and STEP_KEY. We assume in our default that you have created these as APEX application items in your application, and we want the user to set these items when starting to work on a task, because they will need to supply those values back to Flows for APEX when they complete their task.
• Use the ‘+’ button to add other items to be set in the calling page, along with the required values.

• The following items are available to be substituted into the Item Values string at runtime:

  • Flows for APEX Process Variables (of type varchar2). These are specified using the syntax &F4A$<variable_name>. &F4A$ is required to be upper case. Note the trailing period ‘.’. Note also that substitution currently only works on process variables of type varchar2, due to format translation issues on dates and numbers.
  • Flows for APEX Pseudo Variables. The current Process ID, Subflow ID, and Step Key are also available as pseudo variables. These are specified as &F4A$PROCESS_ID. , &F4A$SUBFLOW_ID. and &F4A$STEP_KEY. respectively.

Variable Expressions

A UserTask can have variable expressions that execute before the task starts and after the task completes.

Task Assignment

This is where you define who the possible users are that will perform the task. This is defined as a list of potential users, a list of potential groups, as well as a list of excluded users who cannot perform the task. Assignment can be defined with a static value, as the name of a proess variable containing the information, by a SQL Query, a PL/SQL expression or function body returning the required value.

If Lanes are being used on your diagram, the Lane is defined as mapping to an APEX Role, and no explicit task assignment is defined in this section, the task will be assigned to the lane role.

Scheduling

This controls the settings for task due date and task priority. These control how items appear in the Task List - list sorting, markings as high priority, overdue, etc.

Task Priority. Task Priority can be set from a static definition, process variable, query, expression or function body.

• If you use a DBMS Scheduler expression, the due date will be defined as the next time the scheduler expression would occur. (repeating dates will always resolve to just the next occurence).
• The process variable PROCESS_PRIORITY is available. Using this would cause the user task to run at the priority given to the process instance.
• Advanced use cases might run a complex PL/SQL expression to determine if the instance is likely to complete on schedule, and if not, assign higher priority to outstanding tasks so that the overall process completes on schedule!

Due On. Task Due Date can be set from a static definition, process variable, an Oracle DBMS Scheduler expression, query, expression or function body.

• If you use a DBMS Scheduler expression, the due date will be defined as the next time the scheduler expression would occur. (repeating dates will always resolve to just the next occurence).

Setting up an APEX Human Task (APEX Approval or APEX Action Task) UserTask

APEX Approval userTasks are configured in the Flows for APEX Flow Modeler properties panel for an Approval Task.

APEX Approvals are only supported on Oracle APEX v22.1 and above. Due Dates can only be sent to the APEX task from APEX v23.1. APEX Human Task - Return to Flows for APEX plugin needs to be installed from a file in Flows for APEX versions prior to Flows for APEX v24.1.

The Approval Task itself must first be defined inside the Shared Component section of an APEX application in your workspace. In order for the Approval Task to be called by Flows for APEX and the task outcome to be returned to Flows for APEX when the task is completed, configure the following settings in your Approval Task.

• If not already installed, install the Flows for APEX - Return to Flows for APEX process plugin` into your application. From Flows for APEX v24.1 onwards, this can be copied or subscribed from the Flows for APEX application – installation from a separate file is no longer required. For earlier releases, see Instructions.
• Add a task parameter PROCESS_ID to hold the Flows for APEX Process ID.
• Define a task Action to return the task outcome to Flows for APEX at task completion.

That’s created the Approval Task in APEX. Now you have to define how the task fits into your Flows for APEX process flow.

Approvals are added as BPMN UserTasks of sub-type APEX Approval.

In the Flow Modeler, select your UserTask and configure its settings in the properties panel.

Task Type

Select APEX Approval.

APEX Approval

These settings control the APEX Approval Task that is called, the Task Parameters that are set and their values, and the Flows for APEX process variable to return the task outcome into.

Use APEX meta data. The Modeler can make use of APEX metadata already stored in the database about your application and its defined tasks. You can toggle the Use APEX metadata switch on or off as you configure the task.

Application. If you are using APEX meta data, pick the application containing the Task Definition from the pull down menu. If you are using manual input, specify the Application ID.

Task Definition. If you are using APEX Meta data, select the Task Definition from the pull down menu. If you are using manual entry, enter the task’s static ID.

Subject. This will create the subject heading for the approval in the Unified Task List. If you leave this empty, the heading specified in the Task Definition will be used. If specified in Flows for APEX, the subject can contain items that are substituted by Flows for APEX (using the &F4A$var_name. syntax), as well as Task Definition parameters (using the &parameter. syntax).

Business Reference. This can be used ie. to pass the primary key of the subject record from Flows for APEX to the approval task in APEX. In Flows for APEX, the subject primary key is normally kept in the BUSINESS_REF process variable to link a process instance to its systems of record. In APEX Tasks, this becomes the APEX$TaskPK.

Parameters: This is where you specify the input parameters to be passed into the APEX Task. If you click on the green Load Parameters button, Flows for APEX will get the required parameter names and definitions from the APEX meta data; you then need to map these to Flows for APEX process variables. The parameter list should include PROCESS_ID, containing the Flows for APEX Process ID.

Result Variable. This contains the nae of a Flows for APEX Process Variable that the task outcome should be returned into. For an Approval Task, this will be ‘APPROVED’ or ‘REJECTED’ fter the task has completed. An Action Task has no outcome.

Variable Expressions

A UserTask can have variable expressions that execute before the task starts and after the task completes.

Task Assignment

For Flows for APEX v23.1 and APEX 22.1 to 23.2, task assignment should be managed in the APEX Task definition.

If you want to manage it from your Flows for APEX process diagram, you will need to pass the potential users to APEX inside a Task Parameter.

Scheduling

This controls the settings for task due date and task priority. These control how items appear in the Task List - list sorting, markings as high priority, overdue, etc.

Task Priority. Task Priority can be set from a static definition, process variable, query, expression or function body.

In both Flows for APEX and APEX, priority is a number from 1 (Higest) to 5 (lowest).

• If you use a DBMS Scheduler expression, the due date will be defined as the next time the scheduler expression would occur. (repeating dates will always resolve to just the next occurence).
• The process variable PROCESS_PRIORITY is available. Using this would cause the user task to run at the priority given to the process instance.
• Advanced use cases might run a complex PL/SQL expression to determine if the instance is likely to complete on schedule, and if not, assign higher priority to outstanding tasks so that the overall process completes on schedule!

Due On. Task Due Date can be set from a static definition, process variable, an Oracle DBMS Scheduler expression, query, expression or function body.

• If you use a DBMS Scheduler expression, the due date will be defined as the next time the scheduler expression would occur. (repeating dates will always resolve to just the next occurence).

APEX Task ID

In previous versions (prior to Flows for APEX 24.1), the APEX Task ID would be stored in Flows for APEX in a process variable named :task_id. From Flows for APEX 24.1, this is now stored in the internal Flows for APEX tables (flow_subflows).

Setting up an APEX Simple Form UserTask

APEX Simple Form User Tasks provide a way to integrate user input into your process models without the need to build the associated APEX form pages.

This functionality is provided by utilizing the JSON region plug-in (oracle-apex-json-region) by Uwe Simon [Github Link ] which generates form pages based on a defined JSON syntax that can be easily shared and reused.

To create and manage form templates use the new page in the Flows for APEX engine app called Simple Form Templates. After defining the templates here you can use them in the modeler when working on process models.

<Screenshot Simple Form Templates Page?>

Task Type

Task Type should be set to APEX Simple Form

(Screenshot Task Type Attribute)

APEX Simple Form

The settings for an APEX Simple Form User Task are similar to the APEX Page configuration. You can think of it as a special case of an APEX Page task with specific attributes that are needed to drive the JSON region plugin.

The easiest way to start with the Simple Form User Tasks is by installing the Process Starter App from the Flows for APEX 24.1 distribution folder. This application is intended to provide a central entry point for users to start available processes and work on tasks by retaining a generic approach that can be used with multiple process models.

The Process Starter App’s page 7 is already containing a pre-configured JSON region plug-in that can be used with Simple Form User Tasks.

After installing the app, select Application and Page in the dropdown lists and generate all needed application item settings by pressing the green Generate default items . In addition, you need to specify which form template you want to use for this task after you defined it in the Flows for APEX app (see above). You also need to specify the page item which will contain the reference to that template, so the engine can generate the proper link to the form page for you.

(Screenshot Simple Form Attributes)

When using the Process Starter App, select the page item FORM_TEMPLATE_ITEM here.

If you run this process model now, the Simple Form User Task will point to the form page in the Process Starter app showing the defined fields. All data entered there will be stored in a universal table as JSON objects. If you want to add model-related processing, you can start by integrating the JSON-region plug-in from the Process Starter App in your own application and configure it likewise.

Task Assignment

Be sure to set up the assignment parameters on the task if you want the user task to be clickable inside the viewer for eligible users.