.. include:: ../../variables.rst
.. _wordtemplate:


Word Template Reports
---------------------

A **Word Template** report renders live data and charts into a Word (``.docx``)
**template you control**. The template — not |APPNAME| — owns the layout,
branding, fonts and boilerplate; |APPNAME| simply fills the tagged spots when the
report runs. You can produce the report as ``Word`` or as ``PDF`` (the PDF is
generated from the Word document).

.. note::

   Word Template reports and the template tools are available on the
   **Ultimate** edition.

Each Word Template report points at **its own template**, so one account can run
many different templates — a board brief, a unit one-pager, a quarterly letter —
all from the same account template library. |APPNAME| ships a ready-to-use
default template as a starting point.

Choosing a template for a report
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In the report editor, set the **Report Type** to *Word Template*. A
**Template** tab appears with a drop-down of the templates available to your
account (your own uploads plus the shipped default). On that tab you can:

* **Select** the template this report should use.
* **Download** the selected template to edit it in Word.
* **Upload .docx** to add a new template to your account's library.
* **Delete** one of your own uploaded templates.

Use the **Scope** and **Period** tabs (as with any report) to set the facility /
unit and the date range the data covers.

How tags work
^^^^^^^^^^^^^

Inside the template, type **placeholder tags** wherever you want live data or a
chart to appear. When the report runs, each tag is replaced with the real value
for the report's account, facility/unit scope, and time period.

.. list-table::
   :widths: 30 70
   :header-rows: 1
   :align: center
   :width: 100 %

   * - Tag
     - Replaced with

   * - ``{accountname}``
     - The account (organization) name.
   * - ``{facilityname}``
     - The facility in scope, or *All Facilities*.
   * - ``{unitname}``
     - The patient care area / unit in scope, or *All Units*.
   * - ``{reportperiod}``
     - The reporting period, e.g. *June 2025 – June 2026*.
   * - ``{fromdate}`` / ``{todate}``
     - The start / end date of the period.
   * - ``{reviewdate}``
     - The review (period end) date.
   * - ``{generatedutc}``
     - When the document was generated (UTC).
   * - ``{companyname}`` / ``{productname}``
     - The product/company branding.
   * - ``{copyright}``
     - The copyright line.
   * - ``{target}``
     - The hand hygiene compliance target.
   * - ``{overallcompliance}``
     - Overall compliance for the period.
   * - ``{gap}``
     - Points below target.
   * - ``{auditcount}``
     - Number of audit sessions.
   * - ``{observationcount}``
     - Number of moment-level observations.
   * - ``{activeobservers}``
     - Number of active observers.
   * - ``{unitsmeetingtarget}`` / ``{unitsprofiled}``
     - Units at or above target / units profiled.
   * - ``{lowestunit}`` / ``{lowestunitpct}``
     - Lowest-performing unit and its compliance.
   * - ``{weakestmoment}`` / ``{weakestmomentpct}``
     - Weakest WHO moment and its compliance.
   * - ``{lowestrole}`` / ``{lowestrolepct}``
     - Lowest-performing staff role and its compliance.
   * - ``{trenddelta}``
     - Change in compliance across the period.
   * - ``{status}``
     - Status against target (*On track* / *Below* / *At risk*).
   * - ``{hawthorne:compliance}``
     - Hawthorne-adjusted overall compliance — a conservative estimate that
       discounts the observer effect.
   * - ``{stddev:overall}``
     - Overall standard deviation of session compliance (variability, in points).
   * - ``{narrative_bottomline}``
     - A written "bottom line for leadership" summary.
   * - ``{narrative_gaps}``
     - A written summary of where the gaps are.
   * - ``{narrative_reliability}``
     - A written note on audit reliability and coverage.

Chart tags
^^^^^^^^^^^

Ten chart placeholders insert live charts. Put each one on **its own line**;
the whole paragraph is replaced by the chart.

.. list-table::
   :widths: 30 70
   :header-rows: 1
   :align: center
   :width: 100 %

   * - Tag
     - Inserts

   * - ``{chart:trend}``
     - Monthly compliance trend versus target.
   * - ``{chart:byunit}``
     - Compliance by clinical unit.
   * - ``{chart:byrole}``
     - Compliance by staff role.
   * - ``{chart:bymoment}``
     - Compliance by WHO moments.
   * - ``{chart:facility_pct}``
     - Compliance **percent** by facility, with target reference line(s) —
       a single line when every visible moment shares the same target, otherwise
       one dashed line per visible moment.
   * - ``{chart:facility_count}``
     - **Compliant observations** by facility.
   * - ``{chart:facility_total}``
     - **Total observations** by facility.
   * - ``{chart:pareto}``
     - **Pareto** chart of non-compliant observations by WHO moment (bars sorted
       high-to-low) with a cumulative-% line and an 80% reference line.
   * - ``{chart:funnel}``
     - **Funnel plot** — each unit's compliance against its observation volume,
       with 95% control limits that widen for smaller samples.
   * - ``{chart:stddev}``
     - **Standard-deviation trend** — month-to-month standard deviation of
       session compliance (lower = more consistent).

.. note::

   Anything that shows WHO **moments** — ``{weakestmoment}``,
   ``{weakestmomentpct}``, ``{chart:bymoment}``, and the targets table below —
   automatically follows your account's **moment method** (2, 4, or 5 moments).
   Only your active moments appear, and they use your account's moment names and
   abbreviations (the charts use the abbreviation to keep the axis readable).

Table tags
^^^^^^^^^^

Table placeholders insert a generated table. Put each one on **its own line**;
the whole paragraph is replaced by the table.

.. list-table::
   :widths: 30 70
   :header-rows: 1
   :align: center
   :width: 100 %

   * - Tag
     - Inserts

   * - ``{table:targets}``
     - A table of the compliance **target in effect for each active moment**,
       followed by a note giving the fallback target applied to any moment
       without a specific target.
   * - ``{table:schedule_ahead}``
     - The **top 10 units at or ahead of** their audit schedule for the period
       (unit, facility, completed vs target observations, % complete).
   * - ``{table:schedule_behind}``
     - The **bottom 10 units behind** their audit schedule for the period (same
       columns). "Expected" is each unit's auditing goal scaled to the period.

.. tip::

   Type each tag as plain, unformatted text. If you change the colour or style
   of only part of a tag, Word may split it internally and it will not be
   replaced. The safest approach is to type the tag in one go, or paste it as
   plain text.

.. note::

   You do not have to use every tag, and you can mix tags with your own static
   text and design. Any tag you leave out simply does not appear; any text that
   is not a recognized tag is left untouched.