From 145fbf4b3235e7183f3cdeca2b8ef35247eeabeb Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Thu, 7 Oct 2021 10:47:31 +0100
Subject: [PATCH] companion to https://github.com/cylc/cylc-flow/pull/4455

---
 src/tutorial/furthertopics/broadcast.rst         |  2 +-
 src/tutorial/furthertopics/message-triggers.rst  | 16 ++++++++--------
 .../task-implementation/job-scripts.rst          | 10 +++++-----
 src/user-guide/writing-workflows/jinja2.rst      |  1 +
 src/user-guide/writing-workflows/runtime.rst     |  5 +++--
 5 files changed, 18 insertions(+), 16 deletions(-)

diff --git a/src/tutorial/furthertopics/broadcast.rst b/src/tutorial/furthertopics/broadcast.rst
index 6085441224..d7df622855 100644
--- a/src/tutorial/furthertopics/broadcast.rst
+++ b/src/tutorial/furthertopics/broadcast.rst
@@ -113,7 +113,7 @@ Add the following runtime configuration to the ``runtime`` section:
                WORD=${WORDS[$(date +%s) % ${#WORDS[@]}]}
 
                # Broadcast random word to the announce task.
-               cylc broadcast $CYLC_WORKFLOW_NAME -n announce -s "[environment]WORD=${WORD}"
+               cylc broadcast $CYLC_WORKFLOW_ID -n announce -s "[environment]WORD=${WORD}"
            """
            [[[environment]]]
                WORDS = ni, it, ekke ekke ptang zoo boing
diff --git a/src/tutorial/furthertopics/message-triggers.rst b/src/tutorial/furthertopics/message-triggers.rst
index cd621c4ffc..a0caebc9ed 100644
--- a/src/tutorial/furthertopics/message-triggers.rst
+++ b/src/tutorial/furthertopics/message-triggers.rst
@@ -44,7 +44,7 @@ In order to get our workflow to trigger messages, we need to:
 * specify our custom message in a section called ``[[outputs]]`` within the
      ``[runtime]`` section of our workflow,
 
-* add ``cylc message -- "${CYLC_WORKFLOW_NAME}" "${CYLC_TASK_JOB}" "YOUR CHOSEN TRIGGER MESSAGE"``
+* add ``cylc message -- "${CYLC_WORKFLOW_ID}" "${CYLC_TASK_JOB}" "YOUR CHOSEN TRIGGER MESSAGE"``
      to the ``script`` section of ``[runtime]``, your chosen trigger message
      should be unique and should exactly match the message defined in
      ``[[outputs]]``.
@@ -69,7 +69,7 @@ triggers another task bar and when fully completed triggers another task, baz.
           [[foo]]
               script = """
                   sleep 5
-                  cylc message -- "${CYLC_WORKFLOW_NAME}" "${CYLC_TASK_JOB}" "file 1 done"
+                  cylc message -- "${CYLC_WORKFLOW_ID}" "${CYLC_TASK_JOB}" "file 1 done"
                   sleep 10
               """
               [[[outputs]]]
@@ -251,11 +251,11 @@ triggers another task bar and when fully completed triggers another task, baz.
                  script = """
                      sleep 2
                      random.sh
-         +           cylc message -- "${CYLC_WORKFLOW_NAME}" "${CYLC_TASK_JOB}" \
+         +           cylc message -- "${CYLC_WORKFLOW_ID}" "${CYLC_TASK_JOB}" \
                           "Task partially complete, report ready to view"
                      sleep 2
                      random.sh
-         +           cylc message -- "${CYLC_WORKFLOW_NAME}" "${CYLC_TASK_JOB}" \
+         +           cylc message -- "${CYLC_WORKFLOW_ID}" "${CYLC_TASK_JOB}" \
                           "Task partially complete, report updated"
                      sleep 2
                      random.sh
@@ -312,11 +312,11 @@ triggers another task bar and when fully completed triggers another task, baz.
                     script = """
                         sleep 2
                         random.sh
-                        cylc message -- "${CYLC_WORKFLOW_NAME}" "${CYLC_TASK_JOB}" \
+                        cylc message -- "${CYLC_WORKFLOW_ID}" "${CYLC_TASK_JOB}" \
                             "Task partially complete, report ready to view"
                         sleep 2
                         random.sh
-                        cylc message -- "${CYLC_WORKFLOW_NAME}" "${CYLC_TASK_JOB}" \
+                        cylc message -- "${CYLC_WORKFLOW_ID}" "${CYLC_TASK_JOB}" \
                             "Task partially complete, report updated"
                         sleep 2
                         random.sh
@@ -413,11 +413,11 @@ triggers another task bar and when fully completed triggers another task, baz.
                     script = """
                         sleep 2
                         random.sh
-                        cylc message -- "${CYLC_WORKFLOW_NAME}" "${CYLC_TASK_JOB}" \
+                        cylc message -- "${CYLC_WORKFLOW_ID}" "${CYLC_TASK_JOB}" \
                             "Task partially complete, report ready to view"
                         sleep 2
                         random.sh
-                        cylc message -- "${CYLC_WORKFLOW_NAME}" "${CYLC_TASK_JOB}" \
+                        cylc message -- "${CYLC_WORKFLOW_ID}" "${CYLC_TASK_JOB}" \
                             "Task partially complete, report updated"
                         sleep 2
                         random.sh
diff --git a/src/user-guide/task-implementation/job-scripts.rst b/src/user-guide/task-implementation/job-scripts.rst
index cde80d786d..a443710a87 100644
--- a/src/user-guide/task-implementation/job-scripts.rst
+++ b/src/user-guide/task-implementation/job-scripts.rst
@@ -141,7 +141,7 @@ Normal severity messages are printed to ``job.out`` and logged by the scheduler:
 
 .. code-block:: bash
 
-   cylc message -- "${CYLC_WORKFLOW_NAME}" "${CYLC_TASK_JOB}" \
+   cylc message -- "${CYLC_WORKFLOW_ID}" "${CYLC_TASK_JOB}" \
      "Hello from ${CYLC_TASK_ID}"
 
 "CUSTOM" severity messages are printed to ``job.out``, logged by the
@@ -150,7 +150,7 @@ event handlers:
 
 .. code-block:: bash
 
-   cylc message -- "${CYLC_WORKFLOW_NAME}" "${CYLC_TASK_JOB}" \
+   cylc message -- "${CYLC_WORKFLOW_ID}" "${CYLC_TASK_JOB}" \
      "CUSTOM:data available for ${CYLC_TASK_CYCLE_POINT}"
 
 These can be used to signal special events that are neither routine
@@ -162,7 +162,7 @@ file (a "data availability" event).
 
 .. code-block:: bash
 
-   cylc message -- "${CYLC_WORKFLOW_NAME}" "${CYLC_TASK_JOB}" \
+   cylc message -- "${CYLC_WORKFLOW_ID}" "${CYLC_TASK_JOB}" \
      "WARNING:Uh-oh, something's not right here."
 
 "CRITICAL" severity messages are printed to ``job.err``, logged by the
@@ -170,7 +170,7 @@ file (a "data availability" event).
 
 .. code-block:: bash
 
-   cylc message -- "${CYLC_WORKFLOW_NAME}" "${CYLC_TASK_JOB}" \
+   cylc message -- "${CYLC_WORKFLOW_ID}" "${CYLC_TASK_JOB}" \
      "CRITICAL:ERROR occurred in process X!"
 
 Task jobs no longer (since Cylc 8) attempt to resend messages if the server
@@ -226,7 +226,7 @@ before aborting, potentially triggering a *critical* task event handler:
 .. code-block:: bash
 
    if ! /bin/false; then
-     cylc message -- "${CYLC_WORKFLOW_NAME}" "${CYLC_TASK_JOB}" \
+     cylc message -- "${CYLC_WORKFLOW_ID}" "${CYLC_TASK_JOB}" \
        "CRITICAL:ERROR: /bin/false failed!"
      exit 1
    fi
diff --git a/src/user-guide/writing-workflows/jinja2.rst b/src/user-guide/writing-workflows/jinja2.rst
index 3f61c79980..7691598c2c 100644
--- a/src/user-guide/writing-workflows/jinja2.rst
+++ b/src/user-guide/writing-workflows/jinja2.rst
@@ -131,6 +131,7 @@ prior to configuration parsing to provide workflow context:
    CYLC_VERBOSE                    # Verbose mode, True or False
    CYLC_VERSION                    # Version of cylc installation used
 
+   CYLC_WORKFLOW_ID                # Workflow ID
    CYLC_WORKFLOW_NAME              # Workflow name
 
    CYLC_WORKFLOW_LOG_DIR           # Workflow log directory.
diff --git a/src/user-guide/writing-workflows/runtime.rst b/src/user-guide/writing-workflows/runtime.rst
index 245f68a4e3..ec2711786d 100644
--- a/src/user-guide/writing-workflows/runtime.rst
+++ b/src/user-guide/writing-workflows/runtime.rst
@@ -258,6 +258,7 @@ The task job script may export the following environment variables:
                                       # when in any date-time cycling mode
    CYLC_WORKFLOW_FINAL_CYCLE_POINT    # Final cycle point
    CYLC_WORKFLOW_INITIAL_CYCLE_POINT  # Initial cycle point
+   CYLC_WORKFLOW_ID                   # Workflow ID - the WORKFLOW_NAME plus the run directory
    CYLC_WORKFLOW_NAME                 # Workflow name
    CYLC_UTC                           # UTC mode, True or False
    CYLC_VERBOSE                       # Verbose mode, True or False
@@ -505,7 +506,7 @@ this case.) E.g. to send an email on (submission) failed and retry:
        [[foo]]
            script = """
                test ${CYLC_TASK_TRY_NUMBER} -eq 3
-               cylc message -- "${CYLC_WORKFLOW_NAME}" "${CYLC_TASK_JOB}" 'oopsy daisy'
+               cylc message -- "${CYLC_WORKFLOW_ID}" "${CYLC_TASK_JOB}" 'oopsy daisy'
            """
            execution retry delays = PT0S, PT30S
            [[[events]]]
@@ -611,7 +612,7 @@ event handlers using the alternate methods:
        [[foo]]
            script = """
                test ${CYLC_TASK_TRY_NUMBER} -eq 2
-               cylc message -- "${CYLC_WORKFLOW_NAME}" "${CYLC_TASK_JOB}" 'oopsy daisy'
+               cylc message -- "${CYLC_WORKFLOW_ID}" "${CYLC_TASK_JOB}" 'oopsy daisy'
            """
            execution retry delays = PT0S, PT30S
            [[[events]]]