Changes for page Job Macro

Last modified by Denis Gervalle on 2017/12/11 00:02

From version 1.2
edited by Denis Gervalle
on 2017/02/09 14:23
To version 2.1
edited by Denis Gervalle
on 2017/02/09 15:00
Change comment: There is no comment for this version

Summary

Details

ExtensionCode.ExtensionClass[0]
Description
... ... @@ -1,1 +1,51 @@
1 -Job Macro allows running asynchronous scripts with progression bar and logs
1 +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]].
2 +
3 +== Macro Parameters ==
4 +
5 +; jobid
6 +: 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}}"##.
7 +
8 +; grouppath
9 +: (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.
10 +
11 +; start
12 +: (Optional, default to false) When evaluated to true ([[Boolean#parseBoolean()>>https://docs.oracle.com/javase/7/docs/api/java/lang/Boolean.html#parseBoolean(java.lang.String)]]), 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}}"##.
13 +
14 +== Macro Content ==
15 +
16 +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.
17 +
18 +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:
19 +
20 +; (% style="color:lightgray" %)$(% %)jobId
21 +: The jobid parameter of the job macro
22 +
23 +; (% style="color:lightgray" %)$(% %)groupPath
24 +: The grouppath parameter of the job macro
25 +
26 +; (% style="color:lightgray" %)$(% %)progress
27 +: The ProgressManager which allow reporting the job progress. You may also use the ##(% style="color:lightgray" %)$(% %)services.progress## service.
28 +
29 +{{warning}}
30 +**The ##(% style="color:lightgray" %)$(% %)services.logging## and ##(% style="color:lightgray" %)$(% %)services.progress## are your ways too communicate feedback to the user.**
31 +
32 +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 ##(% style="color:lightgray" %)$(% %)services.logging##.
33 +{{/warning}}
34 +
35 +== Screenshots ==
36 +
37 +=== During execution ===
38 +
39 +{{image reference="running.png"/}}
40 +
41 +=== After successful execution ===
42 +
43 +{{image reference="succeed.png"/}}
44 +
45 +=== After failed execution (some error reported in the logs) ===
46 +
47 +{{image reference="failed.png"/}}
48 +
49 +== Additional remarks ==
50 +
51 +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 & Additional Installation Instructions
... ... @@ -1,0 +1,1 @@
1 +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.
Show installed count
... ... @@ -1,0 +1,1 @@
1 +Yes

Get Connected