Job Question and Answer system

Last modified by Thomas Mortagne on 2023/10/19 16:42

When the job is in interactive mode it can ask questions and wait for the answer. The UI is then supposed to make sure the user is going to see the question and answer it.

Job status

The general idea is that a job question is a Java POJO containing "properties" (a set of setters/getter) for each information the job would like an answer to (or a confirmation). Once those properties have been set JobStatus#answered() is called to notify the job to continue.

On the Job side it means calling JobStatus#ask which will block until the question is answered (or if the question timeout). Since 10.2 it's possible to know how much is left to answer the question using JobStatus#getQuestionTimeLeft method.

But this API is not restricted to the job itself, it can be used by a listener reacting to something a generic job has done for example. In such a use case you can use org.xwiki.job.JobContext component to access the current job and its status.

User interface

[Since 10.2]

To make easier to provide UI for your job the Job module provide generic tools to show and answer a question and allow customizing and extending it in various ways.

question.png

Enable standard question support

Standard question UI is triggered by a <div class="ui-question"> located in a <div class="job-status"> containing a <div class="ui-progress">. If these conditions are fulfilled you will automatically get a form displayed when the running job is waiting for an answer.

Customize question display

The default question UI is a form containing inputs generated from the question bean descriptor (each get/set couple producing an input based on its type).

It's possible to provide a template to customize it in one of the following locations:

  • /question/<jobType>/<className>.vm
  • /question/<jobType>/<classSimpleName>.vm
  • /question/<jobType>.vm
  • /question/<className>.vm
  • /question/<classSimpleName>.vm
  • /question/default.vm

The <jobType> is the type of the running job (rename, intall, etc.).
The <className> is the complete Java class name (for example org.xwiki.contrib.myjob.MyQuestion).
The <classSimpleName> is the last part of the Java class name (for example MyQuestion).

It's recommended to most custom question template to have the following structure:

#template('job/question/macros.vm')

#questionHeader()

## My custom question display

#questionButtons('translation.key.for.answer' 'optional.translation.key.for.cancel')

#questionFooter()

By default the UI is going to send all the <form> inputs found in the template to the standard answer service when the user click on the answer or cancel buttons. Only the property starting with qproperty_ will be taken into account by the standard answer service.

It's possible to extend this behavior in Javascript:

  • by providing custom properties
    • by using JQuery#data and the key job-answer-properties to provide a Javascript object containing pairs of key/value. Those properties will replace form inputs.
    • by using JQuery#data and the key job-answer-properties to provide a function which will return Javascript object containing pairs of key/value. Those properties will replace form inputs.
    • by using JQuery#data and the key job-answer-properties-extra to provide a Javascript object containing pairs of key/value. Those properties will extend form inputs (or job-answer-properties).
    • by using JQuery#data and the key job-answer-properties-extra to provide a function which will return a Javascript object containing pairs of key/value. Those properties will extend form inputs (or job-answer-properties).
  • by using JQuery#data and the key job-answer-createRequest to provide a function which will return a custom URL and the data to use in an ajax call. The custom service must answer with the expected job status JSON.

Customize answer

The default answer service populate all request parameters starting with qproperty_ in the question object and return the JSON expected by the UI.

It's possible to customize a bit the JSON returned after answering the question, specifically the message to display.

Like for the question you will overwrite the default answer return by providing a template in one f the following locations:

  • /answer/<jobType>/<className>.vm
  • /answer/<jobType>/<classSimpleName>.vm
  • /answer/<jobType>.vm
  • /answer/<className>.vm
  • /answer/<classSimpleName>.vm
  • /answer/default.vm

The <jobType> is the type of the running job (rename, intall, etc.).
The <className> is the complete Java class name (for example org.xwiki.contrib.myjob.MyQuestion).
The <classSimpleName> is the last part of the Java class name (for example MyQuestion).

Tags:
    

Get Connected