Configure an APEX Page Task

Configure an APEX Page Task

This section covers how to configure an APEX Page Task to implement a BPMN User Task.

An APEX Page Task is a BPMN UserTask that you have implememented by building an APEX page as part of an application, and which can be called from the Task List and which includes page processes to control the BPMN workflow.

To create a BPMN UserTask of type APEX Page Task, you need to:

• Build an APEX Page in your app, and include page processes to interact with the Flows for APEX engine, and
• Create and configure a BPMN UserTask in your process diagram.

This page explains how to do both of these.

1. Include Flows for APEX processes into your APEX Page

Prepare your APEX App

• Create 3 Application Items to store the workflow state during the transaction. Although you could create these as Page Items, its better to create these as Applcation Items (App Builder > Shared Components > Application Items). These should be named:
  • PROCESS_ID
  • SUBFLOW_ID
  • STEP_KEY
• Install or subscribe to the current version of Flows for APEX Plugins, ensuring that you have the following plugins available:
  • Flows for APEX - Manage Flow Instance
  • Flows for APEX - Manage Flow Instance Step
  • Flows for APEX - Manage Flow Instance Variables
  • Flows for APEX - Return APEX Human Task State and Outcome
  • Flows for APEX - Viewer (25.1)

Starting from Flows for APEX 25.1, you can subscribe to all of these Application Items and Plugins as a single APEX Component Group (Flows for APEX Components).

Add Step Control Processes into your Page.

If your APEX Page is built to implement a user task, you will need to add logic into the page to control the workflow. This includes the following items:

• Complete a Workflow Step on Task Completion. When the user saves the page and completes the workflow task, your page needs to both do its normal database update processing and step the workflow forward. In Page Processes tab, add a new Process AFTER the “Process Form '' process. Use the `Flows for APEX - Manage Flow Instance Step` plugin, and configure it to Action: Complete Step, returning Items `PROCESS_ID`, `SUBFLOW_ID`, and `STEP_KEY` that we previously defined as Application Items. Make this conditional on the SAVE button.

If your page is the first step in a workflow, and you want to start a workflow and complete the first step from your page, see the ‘How To’ on starting your workflow.

Note that the Flows for APEX flow_complete_step needs to be executed after APEX has run its default page processing step and any other database processes that are part of the step. Completing the step prepares the workflow to step forward, commits all changes for the step, and then moves the workflow forward to the next step as a database transaction.

2. Setting Up an APEX Page UserTask in your BPMN Diagram

Add a user task into your BPMN diagram by adding a task ( the symbol). Then, using the spanner tool , convert the task to a User Task ( ).

Name. On the Modeler properties panel, in the General section , give your task a descriptive name.

ID. By default, this generates a random name like ‘‘Activity_0d5gtyh”. You can change this to something more descriptive, but it should be short and not contain any spaces.

Task Type. Select APEX Page and open the APEX Page section.

APEX Page Section.

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.

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 you if you have configured APEX menus or links.

Use APEX Meta Data 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.

Application ID and Page ID. Select the Application and Page that you want the 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, when the page is called. This normally includes the 3 Flows for APEX State items PROCESS_ID, SUBFLOW_ID, and STEP_KEY which your app need to return to complete the step, plus any other items you want to pass into the page to set up the page for your user. In detail:

• 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 named PROCESS_ID, SUBFLOW_ID, and STEP_KEY, 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 can 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>. Note that&F4A$ is required to be upper case, and don’t forget 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 process 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 occurrence).
• 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 occurrence).