.. include:: ../variables.rst
.. _challenges-teams:

Teams
=====

Teams let you bundle several auditors (or units) together so they compete as a single participant.
Every observation made by *any* team member counts toward the team's score.

.. figure:: /images/challenges/lightmode/teams-list.png
   :align: center
   :width: 100 %

|br|

Why use teams
-------------

Standard scopes make one participant per facility / unit / auditor / HCP type. Teams add a fifth
scope that isn't derived from the data model:

* *"Day Shift Auditors vs. Night Shift Auditors -- first team to 500 observations wins."*
* *"Surgical Floor combined (ICU + Step-Down + OR) vs. Medical Floor combined."*
* *"Green Team and Blue Team hospital-wide competition."*

Teams are persistent. They don't have to be recreated per challenge -- once defined, any
challenge can target them by setting scope = Team (code 4).

Creating a team
---------------

Use the ``/challenges/teams`` endpoint or the Teams page.

* **Name** (required) -- shown everywhere the team appears.
* **Description** -- optional notes about the team's composition.
* **Corporation** -- defaults to the current corporation. System-level admins can create teams
  scoped to any corporation.
* **Active** -- Inactive teams are hidden from challenge-scope pickers but preserved so their
  past challenge history remains intact.

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

|br|

Roster (members)
----------------

Each team has a roster of members in ``challenge_team_members``. A member is identified by:

* **memberparticipanttype** -- usually 2 (Auditor) but 1 (Unit) is also supported.
* **memberparticipantid** -- the user UID or unit ID.

A single user can belong to multiple teams. The ``uniq_member`` index prevents the same user
from being added twice to the same team.

When a team challenge is computed, the scoring query unions all members' observations:

.. code-block:: sql

   AND s.observerid IN (
     SELECT memberparticipantid
     FROM challenge_team_members
     WHERE teamid = <team>
       AND memberparticipanttype = 2
   )

Using a team in a challenge
---------------------------

In the :ref:`challenges-detail` editor:

#. Set **Scope** = Team.
#. Leave **Scope ID** = All to compete every active team against each other, **or** set it to a
   specific team ID to score that one team in isolation.

The rest of the challenge (metric, threshold, dates, reward) works exactly as for any other
scope.

Team rewards
------------

When a team wins:

* Points are posted to the **team** as the participant (``participanttype = 4``, ``participantid =
  <teamid>``), not to individual members. This keeps the ledger clean for the case "the team
  earned X" without needing to divide by members.
* The badge is granted to the team similarly.
* Email notifications are not sent for team wins by default (there is no "team email"). Clients
  who want per-member notifications on team wins can add a post-close hook.

To see a team's running balance, use the :ref:`challenges-participant-profile` page with
``participanttype=4&participantid=<teamid>``.

Deactivating a team
-------------------

Set :blue:`Active` to off or use the DELETE endpoint (which performs a soft delete: ``active = 0``).
All past awards survive. Reactivating restores the team immediately; the roster is preserved.