====== Cohorts Builder usage ======

Use **Cohorts Builder** to build one or more comparison groups ("cohorts") from your organization’s participants and synced cohort data, then run a search to return cohort sizes and results per group.

===== Before you start =====

  * Go to **Cohorts Builder** in your organization dashboard.
  * Decide how you want to build cohorts:
    * **From an integration** (recommended): select an active cohort integration and sync it.
    * **No integration**: build cohorts using participant and unit filters only.

===== Choose a data source =====

  - In the data source section, select an **active integration**.
    * If there is only one active integration, it may be auto-selected.
  - Optional: select **No Integration** to build filters without an integration.
  - Optional: click **Change Source** to start over.

If no source is selected, you will see:

  * **Select an integration or "No integration" to begin building filters.**

==== Sync your integration ====

If you selected an integration, you can sync it.

  - Click **Sync Data**.
  - Confirm when prompted:
    * Dialog title: **Start sync?**
    * Description: **This action syncs cohort data from the selected integration. Continue?**
    * Confirm: **Start sync**
    * Cancel: **Cancel**

===== If your integration is CSV =====

If you are using a CSV integration, upload your CSV configuration in the data source section.

Use **Upload CSV** for first-time setup. Use **Replace CSV** to upload a new CSV later.

==== CSV requirements ====

Use a comma-separated file with a single header row.

Your CSV must include these headers:

  * ''UPN''
  * ''Forename'' (or ''First Name'')
  * ''Surname'' (or ''Last Name'')

Optional headers include ''ID''/''External ID'', Date of Birth, Gender, and any extra fields for filtering.

If the CSV is valid, you will see:

  * **CSV uploaded** — "CSV configuration saved and synced for this integration."

If the CSV is invalid, you will see:

  * **CSV upload failed**
  * Or an error like: "CSV must include UPN, Forename (or First Name), and Surname (or Last Name) headers."

===== Choose fields (Select Columns) =====

Use **Select Columns** to control which fields appear in the filter builder.

  - Click **Change Columns**.
  - In the sheet titled **Select Columns**, pick which fields you want available.
  - If needed, change a field’s type so the right comparisons are available.

Sheet details:

  * Title: **Select Columns**
  * Description: **Choose fields shown in the new cohort filter builder.**

===== Assign UPN (match participants to students) =====

Assigning UPNs links each participant to a synced cohort student identifier so cohort filters can match correctly.

  - Open the sheet titled **Assign UPN**.
  - For each participant, assign the correct identifier.

The **Assign UPN** sheet is opened from the **Assign UPN** button in the data source section.

Sheet details:

  * Title: **Assign UPN**
  * Description: **Assign participants to synced cohort students.**

==== When Assign UPN is locked ====

If the same identifier is assigned to more than one participant, the Assign UPN sheet can become locked until you fix the duplicates.

==== If you see "Invalid identifier" ====

If the chosen identifier cannot be resolved to a synced cohort student, you will see:

  * **Invalid identifier** — "Could not resolve selected identifier to a cohort student."

Fix by selecting a valid identifier from the synced student list (or syncing again if the data is out of date).

===== Build cohort groups =====

Create one or more groups. Each group can have its own set of rules.

==== Create and manage groups ====

  * Click **Add Group**.
  * Rename the group using **Group Name** (for example, "Year 7 pupils").
  * Set a group **Color** so results are easy to read.
  * Remove groups you don’t need using **Remove Group** (at least one group must remain).

==== Add rules to a group ====

For each group:

  - Click **Add Rule**.
  - Choose a field (shown as a column selector with placeholder **Select column**).
  - Choose a comparator (placeholder **Select comparator**).
  - Choose/enter values:
    * Participant rules use **Participant Name** and the placeholder **Select values**.
    * Unit rules use **Unit** and the placeholder **Select units**.
    * Text/number fields use the placeholder **Enter value**.
    * Multi-select fields use the placeholder **Select values**.

If you try to add a rule when nothing is available, you may see:

  * **No fields available** — "No columns, participants, or units are available to build a rule."

==== Clear rules ====

If you want to rebuild a group, click **Clear Filters** and add new ones.

===== Run Search and read results =====

After you’ve built at least one group with rules, run **Search**.

==== Common messages ====

If no groups produce matches, you may see:

  * **No matches** — "No groups produced participants with the current filters."

If the search runs successfully, you will see:

  * **Analytics loaded**
    * "(N) groups loaded."
    * Or "(N) groups loaded. (M) groups had no matches."
    * Or "(N) groups returned matching cohorts."

If the search fails, you will see:

  * **Query failed** — "Failed to execute cohort query."

==== When integration is required ====

If you are not in **No integration** mode and no integration is selected, you may see:

  * **Integration required** — "Select an active cohort integration first."

===== Save and reuse your setup =====

==== Save Filter ====

  - Click **Save Filter**.
  - Enter a name in **Filter Name** (placeholder: **e.g., Year 7 pupils**).
  - Save.

If the name is missing:

  * **Name required** — "Enter a name for the filter."

If there are no rules to save:

  * **No rules** — "Add filter rules before saving."

On success:

  * **Filter saved** — ''Filter "<name>" saved.''

On failure:

  * **Save failed** — "Failed to save filter."

==== Saved Filters ====

  - Click **Load Filters**.
  - In the sheet titled **Saved Filters**, select a filter to load.

Sheet details:

  * Title: **Saved Filters**
  * Description: **Load a saved filter definition**

If you try to load a filter that is already loaded:

  * **Filter already loaded** — "Filter was already loaded."

If a saved filter is not usable:

  * **Load failed** — "Saved filter has no valid groups."
  * **Load failed** — "No active group available for loading this filter."

On success:

  * **Filter loaded** — ''Filter "<name>" loaded.''

==== Delete a saved filter ====

If deletion succeeds:

  * **Filter deleted**

If deletion fails:

  * **Delete failed** — "Failed to delete filter."

===== Troubleshooting checklist =====

  * **Select an integration or "No integration" to begin building filters.**: choose a data source first.
  * **Loading filter catalog...**: wait for fields to load after selecting an integration.
  * **CSV upload failed**: confirm the CSV includes ''UPN'', ''Forename''/''First Name'', ''Surname''/''Last Name''.
  * **Assign UPN** locked: fix duplicate identifiers assigned to multiple participants.
  * **Integration required**: select an active integration (or switch to "No integration").
  * **No rules**: add at least one rule to at least one group before searching/saving.
  * **No matches**: broaden rules or verify the data source is synced.
  * **Query failed**: retry after syncing; if it continues, verify the integration is active and data is available.