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.

• 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.

1. In the data source section, select an active integration.
   • If there is only one active integration, it may be auto-selected.
2. Optional: select No Integration to build filters without an integration.
3. 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.

If you selected an integration, you can sync it.

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

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.

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.”

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

1. Click Change Columns.
2. In the sheet titled Select Columns, pick which fields you want available.
3. 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.

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

1. Open the sheet titled Assign UPN.
2. 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.

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

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).

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

• 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).

For each group:

1. Click Add Rule.
2. Choose a field (shown as a column selector with placeholder Select column).
3. Choose a comparator (placeholder Select comparator).
4. 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.”

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

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

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.”

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

• Integration required — “Select an active cohort integration first.”

1. Click Save Filter.
2. Enter a name in Filter Name (placeholder: e.g., Year 7 pupils).
3. 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.”

1. Click Load Filters.
2. 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.

If deletion succeeds:

• Filter deleted

If deletion fails:

• Delete failed — “Failed to delete filter.”

• 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.