add-documentation-for-signals-with-variables (#785)

* add-documentation-for-signals-with-variables

* refactor-after-code-reviews

* refactor-after-reviews

* refactor-after-reviews
Co-authored-by: Oana Schiopu <oana-schiopu@activeeon.com>

src/docs/user/ProActiveUserGuide.adoc

@@ -2618,26 +2618,33 @@ A complete example of Producer / Consumer, _ServiceDeployerConsumer_ can be down
 === Signal API
 
 The *Signal API* is a high-level API that enables users to interact with running jobs via signals (we also call them actions).
-That is, it allows a job to expose specific signals (e.g., `soft_stop` to properly finish a job) that can be triggered by users from the *Workflow Execution portal*.
+That is, it allows a job to expose specific signals (e.g., `soft_stop` to properly finish a job) that can be triggered by users from the *Workflow Execution portal* or *Scheduler portal*.
 You can try the <<_examples_2,examples>> below to better understand how it works.
 
 In summary and for simple use, just go to <<_proactive_studio, ProActive Studio>> and use the 2 predefined templates in the Controls menu: *Check_For_Signals* or *Wait_For_Signals*.
-Fill up the Task Variable *SIGNALS*, and use those templates in your own workflow to be able to receive input from, for instance, the Workflow Execution portal.
+Fill up the Task Variable *SIGNALS*, and use those templates in your own workflow to be able to receive input from, for instance, the Workflow Execution portal or Scheduler portal.
 
 At a more detailed level and advanced use, the Signal API allows jobs and users to exchange signals using a communication channel provided by the <<_task_synchronization_api,synchronization API>>.
 The typical usage scenario of the Signal API is the following:
 
-  . A job declares to be ready to handle one or more signals. The signals are then displayed in the Workflow Execution portal (e.g., display the `soft_stop` signal).
+  . Signals are defined by their name and, optionally, a list of variables. Variables attached to a signal have the same structure as <<_workflow_variables>> but are declared exclusively using the <<_task_signal_api,Signal API>>.
+
+  . If the signal has variables, then a new window will appear where the user can set the variables values and then send the signal with variables to the job. If the signal does not have variables then the window will not appear.
+    Adding variables to a signal allows to enhance the manual control of the workflow execution.
+    After receiving the signal with attached variables, the workflow will then need to process this information and react accordingly (e.g. continue a calculation with a new set of parameters, etc...)
+
+  . A job declares to be ready to handle one or more signals that can have attached variables. The signals are then displayed in the Workflow Execution portal or Scheduler portal(e.g., display the `soft_stop` signal).
 
   . The job waits to receive these signals, or check for their reception regularly.
 
-  . A user clicks on the signal displayed in the Workflow Execution portal (e.g., click on the `soft_stop` signal), which sends this signal to the job.
+  . A user clicks on the signal displayed in the Workflow Execution portal or Scheduler portal (e.g., click on the `soft_stop` signal), which sends this signal to the job.
 
   . At the signal reception, the job executes the corresponding behavior (defined in the workflow).
+    When the signal has attached variables, variables must be valid according to their model specification (see <<_variable_model,Variable Model>>). Sending a signal will not be possible unless they are validated.
 
 As already mentioned, the Signal API uses the <<_task_synchronization_api,synchronization API>> to store jobs' signals, with respect to the following specifications:
 
- * It uses a single persistent channel (called *PA_SIGNALS_CHANNEL*) to store the signals of all jobs. The signal channel contains an entry per job.
+ * It uses a single persistent channel (called *PA_SIGNALS_CHANNEL + {jobId}*) to store the signals and variables of all jobs. The signal channel contains an entry per signal.
 
  * Job signals are automatically removed when the job execution finishes (i.e., the job is in the status Finished, Cancelled, Failed or Killed).
 
@@ -2652,23 +2659,27 @@ The Signal API is available inside ProActive Tasks through the *signalapi* <<_gl
 
 It is easy to use, and offers a set of basic operations on signals summarized as follows:
 
- * *readyForSignal*: declares that the current job is ready to receive and handle one or more signals.
+ * *readyForSignal*: declares that the current job is ready to receive and handle one or more signals with or without variables.
+  Variables are passed as a list of link:../javadoc/org/ow2/proactive/scheduler/common/job/JobVariable.html[JobVariable objects]
    This operation constructs new signals (by adding the prefix `ready_` to the input signals), then adds them to job signals.
    For example, if a job declares ready for the signal `soft_stop`, the signal `ready_soft_stop` is added to the set of job signals.
    Additionally, if the input signal (e.g., `soft_stop`) already exists among the job signals (which means that it has been sent and handled previously),
     the operation ready for signal automatically removes it, thus the job is ready again to receive and handle the same signal.
 
- * *sendSignal*, *sendManySignals*: adds one or more signals given as input to the current job signals.
+ * *sendSignal*, *sendManySignals*: sends programmatically one or more signals with or without variables given as input to the current job signals.
    This operation removes the corresponding ready signals if they already exist. For instance, sending `soft_stop` removes the signal
    `ready_soft_stop` if it already exists among the job signals.
+    Though signals are meant to be sent manually by a human user through to ProActive web portals, it is also possible to use these methods to send them programmatically inside the workflow.
 
- * *checkForSignals*: verifies whether one or more signals exist among the set of job signals.
+* *checkForSignals*: verifies whether all of the signals given as input exist among the set of job signals.
 
  * *waitFor*, *waitForAny*: blocking instruction that waits until one signal (among those given as input) is added to the set of job signals.
+    The instruction _waitFor_ will return a map that represents the name and value of the signal variables.
+    _waitForAny_ instruction returns the first signal object that is received among those given as input
 
  * *removeSignal*, *removeManySignals*: removes one or more signals from the set of job signals.
 
- * *getJobSignals*: returns the current job signals.
+ * *getJobSignals*: returns the current job signals and variables.
 
 In addition to the above operations available within ProActive Tasks, users and third-party systems can send signals
 to a specific job via link:/doc/rest/#1218178377[ProActive Signals REST endpoint].
@@ -2693,13 +2704,39 @@ signalapi.readyForSignal("soft_stop")
 //Display current job signals
 println("Job signals "+ signalapi.getJobSignals())
 
-//Wait util the 'soft_stop' signal is sent (via the Workflow Execution portal or REST API)
+//Wait util the 'soft_stop' signal is sent (via the Workflow Execution portal, Scheduler portal or REST API)
 signalapi.waitFor("soft_stop")
 
 //Remove the 'soft_stop' signal from the set of job signals
 signalapi.removeSignal("soft_stop")
 ----
 
+Here is another example of a groovy code that uses some Signal API operations with signal variables.
+
+----
+import org.ow2.proactive.scheduler.common.job.JobVariable
+
+//Declare the signal variables
+List <JobVariable> signalVariables = new java.util.ArrayList<JobVariable>()
+signalVariables.add(variables.get("INTEGER_VARIABLE"))
+signalVariables.add(variables.get("BOOLEAN_VARIABLE"))
+
+//Declare that the current job is ready to receive and handle the 'soft_stop' signal with the given variables
+signalapi.readyForSignal("soft_stop", signalVariables)
+
+//Display current job signals
+println("Job signals "+ signalapi.getJobSignals())
+
+//Wait util the 'soft_stop' signal with variables is sent (via the Workflow Execution portal, Scheduler portal or REST API)
+outputParameters = signalapi.waitFor("soft_stop")
+
+//The outputParameters represent a hashmap containing the names of the variables and their values entered by the user
+println "Output parameters = " + outputParameters
+
+//Remove the 'soft_stop' signal from the set of job signals
+signalapi.removeSignal("soft_stop")
+----
+
 ===== Usage of the Signals REST endpoint
 Below, we provide an example based on link:https://curl.se/[curl], which shows how to use the link:/doc/rest/#1218178377[Signals REST endpoint] for sending a signal to a specific job:
 [source,shell,subs="verbatim,quotes"]