Skip to main content
Developer Portal
Mendix

Long Running Task Updates Module

Used to display updated progress messages in a long running microflow.

Documentation

Description

The purpose of this module is to allow you to display the progress of a long running microflow.

Typical Usage Scenario

Typically used when you have a microflow that takes a long time and you want to display progress messages or have a progress bar denote where in the process you are.

How This Works

Due to the nature of how microflows work, implementing a progress bar for a long running microflow is very tricky. When a microflow is executed, it opens up what is called a database transaction. As the microflow executes, this transaction will keep track of all the changes that will be made to the database as a result of this microflow. No changes are actually made to the database until the microflow has executed successfully. If the microflow is terminated, or an activity within the microflow throws an exception, all database changes in the transaction are basically thrown away.

What this module does, is it allows you to execute microflows in the background, allowing them to be executed with a separate transaction to your long running microflow. This allows the progress bar to be updated, because changes are being made to the database before your long running microflow is done executing.

The Job Object

This module has an entity called "Job." This will store the information you need for your progress bar. Understanding this entity will help you know how to update the progress bar. Note that none of the attributes , excepting JobID, are set automatically anywhere in the module. It has the following attributes:

  • CurrentStatus - This is a string that has the current progress update. e.g. "Running Unit Tests..."
  • Status - This is an enumeration that holds the status of the job. You can use these to do things like have conditional styling based on whether the job is completed, or whether it fails. It can have the following values:
  • JobID - This is an auto-incrementing number that helps sort the Job objects properly.
  • ProgressPercentage - This is where the percentage of the progress bar is stored.
  • New: A Job that was just created
  • Running: A Job that is still running.
  • Failed: A Job that didn't finish successfully.
  • Completed: A Job that has completed successfully.

How to Use

Create Progress Page

There are a few resources that you need to use in order to make this work. First of all, you'll want to create a page where you'll put your progress bar and progress updates. You will need the following:

  • A template grid widget with it's data source being the Job entity from the LongRunningMicroflowUpdates module by XPath. Here are the general settings for the template grid:

(The reason that there is no XPath, is that when using XPath, it will check the cache first for objects, and then go to the database if the object it's looking for isn't there.)

  • Then you'll need to change the sort order of the template grid so it sorts according to "JobID" in descending order. (This is important, otherwise you're progress bar will never update.)
  • Then put a progress bar or progress circle widget inside the template grid. The progress attribute should be the "ProgressPercentage" attribute of the Job object being passed in, and the maximum value should be 100. Any other values can be set as desired.
  • Then put a text widget that will print out the value in the CurrentStatus attribute of the Job object.

It should look something like this:

Create Microflow to Start Long Running Microflow

The next thing that needs to happen, is you need a microflow to do the following:

  • Create a Job object with the attributes CurrentStatus, Status, and ProgressPercentage set to some initial value of your choosing.
  • Open the progress page you created above.
  • Use the Java Action "executeMicroflowInBackground" included in the LongRunningMicroflowUpdates module. This action is found under "LongRunningMicroflowUpdates > USE_ME > Resources > executeMicroflowInBackground". The microflow input will be your long running microflow, and the context object is an object that the microflow accepts as a parameter. This is what the properties of that Java Action call will look like:

Your microflow will look something like this:

Update Progress in Long Running Microflow

First, you'll need to make sure that you have access to the Job object created in the previous microflow. The easiest way to do this is to pass in the Job object as a parameter. However, if you need to pass in a different object to the long running microflow, you can retrieve the Job object, and then just grab the Job object that has the highest JobID. That one will be the Job created in the last microflow.

Then, at various points in your long running microflow, you will need to add a call to the microflow "SUB_UpdateProgress" in the LongRunningMicroflowUpdates module. This microflow will need four parameters passed into it. The first one is a Job object. This is the Job object that will be updated. The other three are:

  • NewProgress - A number between 0 and 100 that will be the new progress percentage for your progress bar.
  • Status - The enumeration explained above that holds that status of this microflow.
  • CurrentStatus - A string that holds what the microflow is doing right now, or just some status update on what is happening.

Here's an example of what the microflow call activity properties would look like:

Then here's an example of where "SUB_UpdateProgress" would be called in a long running microflow:

Basically anywhere where you need to update the progress bar, or the status update of what is going on, call the "SUB_UpdateProgress" microflow.

Dependencies

Installation

  1. Download the module here. It will save as LongRunningMicroflowUpdates.mpk
    1. Note: If you are using Mendix Studio Pro 8.8.* or 8.9.* downloading private app store modules/widgets was turned off due to security concerns. All the BYU Private App Store content can still be downloaded from the Company Content page in the Mendix App Store and then imported into those versions of Studio Pro. Upgrading to a newer version of Mendix Studio Pro fixes the problem.
  2. After the download finishes, import Long Running Task Updates Module into your project.
    1. Right click on your Project Explorer
    2. Select Import Module Package
    3. Select the module you just downloaded and click Open

More Resources

Learn how to install a module in Mendix.

Slack

For additional help, refer to the appropriate slack channels in their respective workspaces:

  1. BYU-OIT workspace
    1. #api-management
    2. #mendix
  2. BYU-Web workspace
    1. #mendix-user-group