Add new script configuration options (#13859)

Co-authored-by: Franck Nijhof <git@frenck.dev>

source/_integrations/script.markdown

@@ -16,6 +16,8 @@ The `script` integration allows users to specify a sequence of actions to be exe
 
 The sequence of actions is specified using the [Home Assistant Script Syntax](/getting-started/scripts/).
 
+{% raw %}
+ 
 ```yaml
 # Example configuration.yaml entry
 script:
@@ -24,9 +26,11 @@ script:
       # This is Home Assistant Script Syntax
       - service: notify.notify
         data_template:
-          message: Current temperature is {% raw %}{{ states('sensor.temperature') }}{% endraw %}
+          message: "Current temperature is {{ states('sensor.temperature') }}"
 ```
 
+{% endraw %}
+
 <div class='note'>
 
 Script names (e.g., `message_temperature` in the example above) are not allowed to contain capital letters, or dash (minus) characters, i.e., `-`. The preferred way to separate words for better readability is to use underscore (`_`) characters.
@@ -63,12 +67,47 @@ fields:
         example:
           description: An example value for PARAMETER_NAME.
           type: string
+mode:
+  description: "Controls what happens when script is run while it is still running from one or more previous invocations. See [Script Modes](#script-modes)."
+  required: false
+  type: string
+  default: legacy
+queue_size:
+  description: "Controls maximum number of queued runs waiting for previous run to complete. Only valid with `mode: queue`."
+  required: false
+  type: integer
+  default: 10
 sequence:
   description: The sequence of actions to be performed in the script.
   required: true
   type: list
 {% endconfiguration %}
 
+### Script Modes
+
+Mode | Description
+-|-
+`legacy` | See [below](#legacy-mode).
+`error` | Raise an error. Previous run continues normally.
+`ignore` | Do not start a new run. Previous run continues normally.
+`parallel` | Start a new, independent run in parallel with previous runs which continue normally.
+`restart` | Start a new run after first stopping previous run.
+`queue` | Start a new run after all previous runs complete. Runs are guaranteed to execute in the order they were queued.
+
+<p class='img'>
+  <img src='/images/integrations/script/script_modes.jpg'>
+</p>
+
+#### Legacy Mode
+
+<div class='note'>
+
+This mode is deprecated, and a warning to that effect will be issued at startup unless `mode: legacy` is specified.
+
+</div>
+
+This mode maintains the legacy script behavior. That is, the script will run until it executes a `delay` step, or a `wait_template` step (that actually waits), at which point the script will suspend. If the script is run while suspended, it will abort the delay/wait_template and continue immediately to the next step, or finish if there are no more steps. Also, calling a legacy script that is still running (and not suspended) will result in an error.
+
 ### Full Configuration
 
 {% raw %}
@@ -83,6 +122,8 @@ script:
       minutes:
         description: 'The amount of time to wait before turning on the living room lights'
         example: 1
+    # If called again while still running (probably in delay step), start over.
+    mode: restart
     sequence:
       # This is Home Assistant Script Syntax
       - event: LOGBOOK_ENTRY
@@ -171,8 +212,39 @@ script:
           message: "{% raw %}{{ message }}{% endraw %}"
 ```
 
+### Waiting for Script to Complete
+
+When calling a script "directly" (e.g., `script.NAME`) the calling script will wait for the called script to finish.
+
+When calling a script (or multiple scripts) via the `script.turn_on` service the calling script does _not_ wait. It starts the scripts, in the order listed, and continues as soon as the last script is started.
+
+<p class='img'>
+  <img src='/images/integrations/script/script_wait.jpg'>
+</p>
+
+Following is an example of the calling script not waiting. It performs some other operations while the called script runs "in the background." Then it later waits for the called script to complete via a `wait_template`.
+
+{% raw %}
+```yaml
+script:
+  script_1:
+    sequence:
+      - service: script.turn_on
+        entity_id: script.script_2
+      # Perform some other steps here while second script runs...
+      # Now wait for called script to complete.
+      - wait_template: "{{ is_state('script.script_2', 'off') }}"
+      # Now do some other things...
+  script_2:
+    sequence:
+      # Do some things at the same time as the first script...
+```
+{% endraw %}
+
+Note that this is only guaranteed to work if the called script uses a non-legacy mode.
+
 ### In the Overview
 
-Scripts in the Overview panel will be displayed with an **EXECUTE** button if the device has no `delay:` or `wait:` statement, and as a toggle switch if it has either of those.
+Legacy scripts in the Overview panel will be displayed with an **EXECUTE** button if the script has no `delay:` or `wait_template:` statement, and as a toggle switch if it has either of those. Scripts configured for any other mode than `legacy` will also be displayed with a toggle switch.
 
 This is to enable you to stop a running script.