New in 24.1- APEX Workflow Dashboard, Diagram and Debugging...

June 17, 2024 | 7 minute read
Ananya Chatterjee
Consulting Member of Technical Staff
Text Size 100%:

Recap

The APEX 23.2 release introduced the Workflow component in the Application building paradigm. Take a quick look at these blogs for a quick recap of the APEX Workflow capabilities and examples. 
With 24.1 we have made some enhancements to the Workflow functionality in APEX to improve the developer as well as the end user experience.

Enhancing the Expense Reimbursement App

In this blog, we will be using the Expense Reimbursement Multi-level Approval App that I had blogged about earlier. 

Regenerate the Workflow Console Pages

In App Builder, open the Expense Reimbursement App.
Click on the pages Monitor Expense Workflows and Expense Reimbursement Details and delete them one by one.

Remove Existing Workflow Console Pages

On the Application home page, Click on Create Page. 

  1. Under Components, select Workflow Console.
  2. Select the Report Context as Initiated By Me.
  3. For the Page Name enter Monitor Workflows
  4. For the Form page, set the name as Workflow Details
  5. Turn On the Include Dashboard Page switch
  6. Fill the Dashboard Page name as Workflow Dashboard
  7. Click on Create Page.

Regenerate WF Console pages

 

Tech Tips : The Dashboard page is optional but a convenient out of the box page that contains charts showing the overall health of the workflows in your application. You can customize the page to enrich the experience just like for the Workflow Console and the Workflow Details generated pages. 

Run the app

From the application Home Page, click on Run Application.
Log in as STEVE . Clck on Submit Expense to submit a new Expense Reimbursement Requests for ANANYA. 

Submit Expense

Click on Submit.
Now click on Monitor Workflows and then click on the entry- Expense Reimbursement for ANANYA to open the Workflow Details Page.
Scroll to the bottom of the Details page. Notice that there is a new region - Workflow Diagram. Expand this to get the live visual representation of the workflow instance.
Note that the activities that have been already completed, are bordered with green while the current activity is bordered with blue

Audit Diagram in Workflow Details

Log In as Jane and go to Pending Expense Approvals and click on Reject for the Level 1 of Reimbursement Request.
Log back in as Steve and open the Completed Workflow from Monitor Workflows.
Note that the diagram now shows the workflow has completed and highlights the route traversed by the workflow instance in green.

Completed Workflow Diagram

Tech Tips: The Workflow Details generated page will automatically contain the Workflow Diagram.
Did you know that you can now embed a workflow diagram region in any of your existing pages? To do this, use the new region type Workflow Diagram in your existing page. Note that this region expects a mandatory attribute Workflow Id which should be a valid workflow instance ID for which the diagram will render when your page is run.

Create more workflow instances

Repeat the above step with different amounts and expense reasons:

  1. Requests 2, 3 and 4 - Amounts between 1000 and 2000 (1 level needed)
  2. Requests 5 and 6 - Amounts between 2000 and 5000 (2 levels needed)
  3. For all the requests, Log In as Jane and go to Pending Expense Approvals to Approve the Level 1 of Reimbursement Request
  4. For the 5th Request, log in as STEVE. Navigate to Monitor Workflow and Suspend the Workflow.
  5. At this point delete data from the APPROVAL_LEVELS table to deliberately fault the next workflow you create.
  6. Navigate to SQL Workshop and click SQL Commands
  7. Enter this command: truncate table approval_levels;  and click Run.
  8. In your running application, log in as STEVE and submit one more reimbursement request with amount between 1000 and 2000.
  9. Go to Monitor Workflows. You will find this workflow to be in Faulted state. Click on Workflow Details, expand the Workflow Diagram . Note that the Create Approval Task is highlighted in Red to indicate the fault point. 

Faulted Workflow Details.           Faulted Workflow Diagram

Viewing the Dashboard page

Now that we have quite a few workflow instances at different states, navigate to the Workflow Dashboard page
The Workflow Dashboard is divided into four regions

States By Workflow Region

The pie chart on the top left gives a state-wise distribution of all the workflow instances. When you click on a particular color on the chart, the Details section on the right, shows the number of workflow instances belonging to that particular state.

Completed State Workflows

Faulted Workflows

Active Workflows

Navigate to the Active Workflows to see how many workflows are there in active or waiting state. Clicking on a workflow on the left (Overview) section, will show the number of workflow instances that are waiting at a particular activity, on the right.

Active Workflows

Faulted Workflows

Navigate to the Faulted Workflows region to see how many workflows are there in faulted state. Clicking on a workflow on the left (Overview) section, will show the number of workflow instances that have faulted at a particular activity of that workflow, on the right.

Performance

Finally, the Performance region shows the average completion time for the instances of a particular workflow.

Average Time

Add more workflows to your application, and run them to see how they reflect in the Workflow Dashboard. The Workflow Dashboard, is a generated page. You can customize it to add more regions, or change the style of a particular chart, or remove regions that you don't prefer showing in the dashboard,

Human Tasks and Workflow Termination 

In APEX 23.2, when a workflow was terminated, if there was a human task activity that was still waiting to be completed this human task stayed assigned in spite of the termination of the workflow. The initiator of the task could manually cancel it of course, but the workflow termination did not take care of canceling these tasks automatically.

This has been addressed now. Try the following steps:

  1. Go to Monitor Workflows and Terminate one of the Expense Reimbursement Workflows in Active State. Note the Workflow Instance ID from the Details section.
  2. Check the state of the human task by performing the following query in SQL Workshop -> SQL Commands
Copied to Clipboard
Error: Could not Copy
Copied to Clipboard
Error: Could not Copy
select state from apex_tasks where workflow_id = <provide the workflow instance ID here >;

The state will Canceled.

Tech Tips: Termination Functions can now be defined similar to Completion Functions in Custom Process Type Plugins that you use in Workflow Activities. Termination Functions are called when a Workflow is terminated. Typically these functions can be used to perform clean up of custom data in the event of workflow termination. Check out our previous blog that talks about custom plugin usage in APEX Workflow.

Finally, a note on debugging 

As an end user, to further debug into a faulted workflow, or a workflow that unexpectedly completed, we can use the Debug Message Data more effectively now.

  1. Log in as STEVE, and go to Monitor Workflows. Click on a Expense Reimbursement Workflow entry in Faulted state.
  2. On the details page, click on the Dev Toolbar >  View Debug.

Debug Workflow

Click on Actions > Columns. You will find a new column Workflow Instance. Bring it to the right to include it in the report.

Workflow Instance in Debug Report

The debug report will now show the workflow instance ID and  you can use it to filter debug messages for the  workflow instance you are interested in. Makes debugging a lot simpler!

Hope you enjoyed learning about these simple but super effective workflow enhancements in APEX 24.1 which could further enrich your application building experience!

Ananya Chatterjee

Consulting Member of Technical Staff

Ananya hails from Kolkata and has been associated with Oracle for the past 2 decades. For many years, she was working for Oracle Integration Cloud and Oracle Process Automation Service, leading multiple teams. She now works as part of the Oracle APEX team and has co-designed and developed the APEX  Approvals Component and APEX Workflow features.

She is also a bilingual poet with five published poetry collections in English and Bengali.

Show more

Previous Post

Announcing Oracle APEX 24.1 General Availability

Ashish Mohindroo | 7 min read

Next Post


Oracle APEX 24.1: Date Picker for Faceted Search and Smart Filters

Monica Godoy | 3 min read
Oracle Chatbot
Disconnected