Job Macro

Last modified by Denis Gervalle on 2017/10/09 00:03

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

Denis Gervalle

Active Installs11
0 Votes
LicenseGNU Lesser General Public License 2.1
Installable with the Extension Manager


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

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}}".
(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.
(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:

The jobid of the running job (equivalent to the jobid parameter but split on '/' and forming a list of String)
The grouppath parameter of the job macro
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 too 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="testjob/test" start="{{velocity}}$request.confirm{{/velocity}}"}}
  def log = services.logging.getLogger(doc.fullName)
  for(int i=0; i<5; i++) {
      log.warn('Step {}', i);
      if (i == 3) {
        throw new Exception("Failure");


During execution


After successful execution (with logs expanded)


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


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). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

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


  • Closed JOBMACRO-4 Request parameter are not properly retrievable from the job


  • Closed JOBMACRO-3 Provide velocity variable bindings also in the script context (groovy, ...)
  • Closed JOBMACRO-2 Provide parameters of the launching request to the job context


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

  • org.xwiki.rendering:xwiki-rendering-transformation-macro 7.1
  • org.xwiki.commons:xwiki-commons-job 7.1
  • org.xwiki.platform:xwiki-platform-rendering-signature 7.1
  • org.xwiki.platform:xwiki-platform-oldcore 7.1
  • org.xwiki.contrib:macro-job-ui 1.1.1
Created by Denis Gervalle on 2017/02/09 14:16

Get Connected