.. include:: ../variables.rst
.. _challenges-rule-filter:

Rule Filter (Advanced Scoping)
==============================

The **Rule Filter** field on the :ref:`challenges-detail` editor lets you narrow which
observations count toward a challenge beyond what scope and HCP type filter already do. It is
optional -- leave it blank and all observations in scope are counted.

.. figure:: /images/challenges/lightmode/rule-filter-editor.png
   :align: center
   :width: 80 %

|br|

Why use it
----------

Scopes answer *who*; the rule filter answers *what counts*. Examples of the kinds of question it
can answer that scope alone cannot:

* *"Before-Patient and After-Patient only -- ignore aseptic/body-fluid/surroundings moments."*
* *"RNs and LPNs only for this challenge, everyone else for the next one."*
* *"Pre-procedure moments only."*

Syntax
------

The field stores a small **key=value** expression. Two formats are accepted interchangeably:

**Simple form** (recommended):

.. code-block:: none

   key1=value1;key2=value2

**JSON form**:

.. code-block:: json

   {"key1":"value1","key2":"value2"}

Both parsers are lenient. Whitespace is trimmed. Unknown keys are ignored silently.

Supported keys
--------------

.. list-table::
   :header-rows: 1
   :widths: 20 25 55

   * - Key
     - Value
     - Effect
   * - ``moments``
     - Comma list of integers 1-5
     - Restricts observations to the named hand-hygiene moments. ``1`` = before patient, ``2`` =
       after patient, ``3`` = before aseptic, ``4`` = after body fluid, ``5`` = after
       touching patient surroundings.
   * - ``hcptypes``
     - Comma list of integer HCP type IDs
     - Restricts observations to the listed HCP types. Ignored when the challenge's scope is
       already HCP Type (would be redundant).

Examples
--------

**"Before-patient and after-patient only":**

.. code-block:: none

   moments=1,2

**"RN (5) and LPN (6) only":**

.. code-block:: none

   hcptypes=5,6

**"Pre-procedure moments, RNs only":**

.. code-block:: none

   moments=1,3;hcptypes=5

**Same as JSON:**

.. code-block:: json

   {"moments":"1,3","hcptypes":"5"}

How it's applied
----------------

The filter is combined **into the observation WHERE clause** at every computation:

* ``moments`` becomes ``AND (d.befpat=1 OR d.aftpat=1 OR ...)`` across the selected flags.
* ``hcptypes`` becomes ``AND d.hcptype IN (5,6)``.

Because the filter is applied during ``Compute`` it affects every metric equally -- the
observation count, compliance %, improvement delta baseline, and streak all narrow to the
filtered window.

Safety
------

All inputs are sanitised to integers server-side before being inlined into SQL. Any non-numeric
token in the comma list is silently dropped, so stray quotes, brackets, or semicolons in the
rule field cannot cause SQL injection. The worst that can happen is a rule that matches fewer
observations than intended.

Limitations
-----------

This is a minimal rule engine. It deliberately does **not** support:

* Boolean combinations beyond the implicit AND between keys.
* Arithmetic (e.g. "at least 2 of the 5 moments").
* Free-form SQL.

If you need richer logic, create multiple challenges with different rules and compare the
leaderboards. Richer operators are a future enhancement.