Job Macro

Last modified by Raphaƫl Jakse on 2023/05/01 00:19

cogJob Macro allows running asynchronous scripts with progression bar and logs
TypeJAR
CategoryMacro
Developed by

Denis Gervalle

Active Installs142
Rating
2 Votes
LicenseGNU Lesser General Public License 2.1

Installable with the Extension Manager

Description

The {{job}} macro allows executing some piece of wiki content in an asynchronous parallel thread, and provide visual feedback to the user with a progress bar and logs. This macro is based on the Job Module.

Macro Parameters

jobid
This is a job identifier as defined by the Job Module, however the List<String> is serialized using the '/' separator. So a typical job identifier would be of the form "jobtype/jobsubtype/uniqueid". The value if this parameter support the wiki syntax, so you can also use some dynamic value like "{{velocity}}releaseJob/$datetool.get('yyyy-MM-dd')/$datetool.get('HH:mm:ss.SSS'){{/velocity}}".
grouppath
(Optional) This is the group path of a GroupedJob as defined by the Job Module, however the List<String> is serialized using the '/' separator. It allows preventing concurrent jobs, for jobs having the same group path. If not specified, the job is considered as a single job. The value if this parameter support the wiki syntax.
start
(Optional, default to false) When evaluated to true (Boolean#parseBoolean()), a new job will be launched if none is already running. If a previous job was launched with the same job id, its logs will be overwritten. The content author of the page hosting the macro needs Programming Right to start a new job. The value if this parameter support the wiki syntax, so you can also use some dynamic value like "{{velocity}}$request.confirm{{/velocity}}".

Macro Content

The macro content is mandatory. This content will be rendered in a cloned context of the current request, and it will almost benefit of the same execution environment that if it was rendered synchronously. The resulting output will be always discarded.

If you want to execute scripts, you may use the corresponding script macro (i.e. {{velocity}} or {{groovy}}) inside this content. In addition to all normal bindings, the following bindings are available:

$jobId
The jobid of the running job (equivalent to the jobid parameter but split on '/' and forming a list of String)
$groupPath
The grouppath parameter of the job macro
$progress
The ProgressManager which allow reporting the job progress. You may also use the $services.progress service which is more script oriented, especially in Velocity.

The $services.logging and $services.progress are your ways to communicate feedback to the user.

Since the rendered content will never be display, any failure of script macro inside the content will be silently ignored. You are advised to care about such failure inside your scripting code. An easy way to do so it to catch all exception around your script (i.e. using #try() in velocity, try/catch in groovy) and ensure that you also report the captured error in the logs through $services.logging

Code sample

{{job id="{{velocity}}$!request.jobId{{/velocity}}" start="{{velocity}}$!request.confirm{{/velocity}}"}}
{{groovy}}
  import org.xwiki.logging.LogLevel;

  def log = services.logging.getLogger(doc.fullName)
  services.logging.setLevel(doc.fullName, LogLevel.INFO);
  services.progress.pushLevel(5);
  for(int i=0; i<5; i++) {
      services.progress.startStep();
      log.info('Step {}', i);
      sleep(1000);
      if (i == 3) {
        log.error("Failed");
        throw new Exception("Failure");
      }
      services.progress.endStep();
  }
  services.progress.popLevel();
{{/groovy}}
{{/job}}

{{velocity}}
#if ("$!request.jobId" == '')
  #set ($jobId = "$datetool.get('yyyy-MM-dd')/$datetool.get('HH-mm-ss-SSS')")
  [[Proceed>>$doc.fullName||queryString="jobId=$!{escapetool.url($jobId)}&confirm=true" class="btn btn-primary"]]
#elseif ($!request.confirm)
  $response.sendRedirect($doc.getURL('view',"jobId=$request.jobId"))
#end
{{/velocity}}

Screenshots

During execution

running.png

After successful execution (with logs expanded)

succeed.png

After failed execution (some error reported in the logs and logs expanded)

failed.png

Additional remarks

The current implementation is suboptimal and install a XAR dependency for displaying the job progress. This helper provide a {{jobprogress}} macro. This macro is not intended to be used directly and might be remove in future version. 

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.


For manual installation, the job-macro JAR should be deployed in WEB-INF/lib, and the job-macro-ui XAR package imported in the wiki.

Release Notes

v2.0

v1.5.1

v1.5

v1.4.1

v1.4

v1.3

v1.2

v1.1.1

v1.1

Dependencies

Dependencies for this extension (org.xwiki.contrib:macro-job 2.0):

Tags:
    

Get Connected