Tip: “Global” Template Variables

Template variables, aka Jinja2 variables for use in the flow.cylc file, may now be configured in the global.cylc file for automatic use in all workflows.

The intention of this feature is to allow site-specific variables to be configured to facilitate workflow portability.

This has overlap with the rose.conf[rose-stem]automatic-options=SITE Rose configuration which sets a template variable called SITE for use in rose-stem test suites. We would encourage all sites using this configuration to create a new Cylc global template variable called CYLC_SITE set to the same value to facilitate rose-stem migration and site-portability. Note the CYLC_ prefix avoids conflicts with existing workflow design patterns.

I.e, if you currently configure this:

# rose.conf

[rose-stem]
automatic-options=SITE=my-site

Then additionally configure this:

# global.cylc

[template variables]
    CYLC_SITE = "my-site"

The Cylc configuration is more generic as it can be used in all workflows (not just rose-stem suites). The Rose configuration remains supported and may be left in place for back-compatibility with rose-stem workflows running under Cylc 8.6 or until existing rose-stem workflows have migrated.

Rose-stem workflows will be encouraged to migrate from SITE to CYLC_SITE at some point in the future. Until then, for maximum portability, this Jinja2 snippet will use CYLC_SITE if defined, falling back to SITE if defined, falling back to None.

{% set CYLC_SITE = CYLC_SITE | default(SITE | default(None)) %}

Warning

The global.cylc[template variables] configuration was only added in Cylc 8.7.0 and was not present in earlier versions of Cylc where it would cause errors if defined.

To configure this only for Cylc 8.7 (to avoid errors with older versions of Cylc) place the config in <site-conf-path>/flow/8.7/global.cylc (you may want to do the same for 8.8, etc, until 8.6 is retired).

For more information, see global.cylc and cylc config --print-hierarchy.