Monitoring Jobs - Display progress of SSJS Ajax requests

Abstract

ShowTable of Contents

HideTable of Contents

1 Setup Monitoring Job
2 Notify Monitoring Job about execution progress
3 Solution for Ajax request timeouts
4 Sample application

In contrast to real JavaScript background jobs which run completely separated from an XPages application and go on running even if the XPages application is closed, a Monitoring Job is a job that does nothing but monitor and visualize the progress of server-side JavaScript code, e.g. executed when a user clicks on a button in an XPage.

The purpose is both to give the user visual feedback about the execution progress, e.g. in a progress dialog, and to offer a way to cancel a long running background operation. Since your code is running in a normal Ajax request, you've got full access to the scope maps (e.g. applicationScope, sessionScope) and you can use the @formula methods that IBM provides in their JavaScript engine.

Job progress dialog

Setup Monitoring Job

You create a new Monitoring Job by calling the method createMonitoringJob(String) of the Jobs API tools class with the preferred Job name (which will be visible in the title of the progress dialog):

var conn=X2E.createConnection();
var jTools=com.x2e.JobAPI.getTools(conn);
//a monitoring job does not execute any code itself, but is used
//to display progress in the Notes client; its only purpose is
//to monitor calls on its progress monitor and pass them to Eclipse
var job=jTools.createMonitoringJob(jobName);
//optional call to display a progress dialog (otherwise, the progress
//would only be visible on the Job progress page of the Notes Client):
job.setUser(true);

There are two methods to influence the visibility of the job in the Notes Client. Calling job.setUser(true) will display a job progress dialog, otherwise the job will only be visible in the Job tab. And by calling job.setSystem(true), you can further reduce the job visibility so that it only shows up in the Job tab, when the option "Show sleeping and system operations" is checked in the Job tab preferences:

Next, you read the so called Progress Monitor from the job by calling the method job.getProgressMonitor(). The Progress Monitor will be used in your code to report the current progress to the Monitoring Job, provide a status message and to check if the user has pressed the cancel button.
As the final step before we can enter a long running code block, we launch the Monitoring Job by calling job.schedule(), which makes the job appear in the Notes client.

var progressMon=job.getProgressMonitor();
job.schedule();

Notify Monitoring Job about execution progress

Now that the Monitoring Job is running, your code can enter a long running loop. We are using the progressMon object to keep the Monitoring Job informed about the current status:

//announce a new task; -1 means that we don't know exactly how many work units need
//to be processed, which makes the progress bar flash back und forth
progressMon.beginTask("Opening view", -1);
var nrOfEntries=openView();

//change the task name and tell the progress monitor that nrOfEntries work units need
//to be processed
progressMon.beginTask("Processing entries", nrOfEntries);
for (var i=0; i<nrOfEntries; i++) {
    //check if the user has canceled the operation
    if (progressMon.isCanceled())
        break;

    //change the visible status message
    progressMon.setTaskName("Processing entry "+(i+1));
    //call method to process entry
    processViewEntry(i);
    //report 1 work unit as processed; updates the progress bar to the current progress
    progressMon.worked(1);
}
//tell the Monitoring job that we are done, so that it stops monitoring and disappears
progressMon.done();

In the code snippet above you see all of the most relevant methods in the Progress Monitor class. Further information can be found in the Eclipse documentation for IProgressMonitor

, which is the Eclipse object that XPages2Eclipse uses internally.

Solution for Ajax request timeouts

Long running Ajax requests exceed the default timeout value of Dojo in many cases. This leads to annoying timeout error dialogs in the frontend, although the server-side JavaScript keeps on running just fine.
The wiki article XSP.submitLatency - workaround for timeout messages during long running server calls provides information on how to increase the timeout value.

Sample application

Monitoring jobs are used in a couple of samples in the XPages2Eclipse product wiki. For example, in the article Program API - Read registered file extensions and launch files, a Monitoring Job visualizes the progress of reading the registered file extensions in the user's operating system.