> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Pipeline tracks admin guide

> Configure multi-track service-line pipelines for the Community Engagement leads board, including default tracks, lead assignment, and reordering.

# CE-64: Pipeline Tracks — Admin Guide

**Version:** 1.0.0
**Last Updated:** 2026-05-16
**Module:** CE (Community Engagement)
**Status:** Active

> **Purpose:** Help administrators configure multi-track service-line pipelines for the CE Leads kanban board.

***

## Overview

CE-64 introduces **pipeline tracks** — org-scoped service lines (e.g. Residential, IOP, PHP, Outpatient) that group lead stages on the pipeline board. Each lead belongs to exactly one track. The board renders one horizontal row per active track, with that track's stages displayed left-to-right.

* **Spec:** [`specs/ce/specs/CE-64-multi-track-service-line-pipeline.md`](https://github.com/Encore-OS/encoreos/blob/development/specs/ce/specs/CE-64-multi-track-service-line-pipeline.md)
* **Settings URL:** `/ce/settings/pipeline-tracks`
* **Required permission:** `ce.pipeline_tracks.manage`

***

## Default Tracks

Every organization is seeded with a **General** track (marked `is_default = true`). Existing stages and leads were migrated into this track during the CE-64 rollout. The default track cannot be deleted while any lead references it.

You may add additional tracks (Residential, IOP, PHP, Outpatient, Sober Living, etc.) as needed.

***

## Creating a Track

1. Navigate to **CE → Settings → Pipeline Tracks**.
2. Click **New Track**.
3. Fill in:
   * **Name** (required) — e.g. `Residential`.
   * **Color** — optional hex value used for a thin row accent on the board.
   * **Associated Services** — comma-separated list of service strings matching the CE-58 `requested_services` picklist. Leads whose requested services overlap this list are auto-assigned to this track on creation.
   * **Active** — inactive tracks are hidden from the board and from lead creation.
   * **Default** — exactly one track per org is the fallback for leads that match no other track. Marking a new track default un-marks the previous default.
4. Click **Save**.

New tracks receive the next available `sort_order`.

***

## Reordering Tracks

Use the ▲ / ▼ buttons in the list to change row order on the board. Changes persist immediately.

***

## Editing a Track

Click **Edit** on any row to update name, color, associated services, active flag, or default flag. Changing **Associated Services** affects only newly created leads — existing leads keep their assigned track until reassigned manually from the lead detail page.

***

## Deleting a Track

Delete is blocked if any active leads still reference the track. The UI shows the lead count and prompts you to reassign first.

To reassign leads:

1. Open each affected lead's detail page.
2. Use the **Pipeline Track** selector to move it to another track.
3. Retry the delete.

The default track also cannot be deleted while it remains the org default — promote another track to default first.

***

## How Lead Track Assignment Works

* **On create:** The lead's `requested_services` are matched against active tracks' `associated_services`. A single match wins; zero or multiple matches fall back to the org's default track.
* **Manually:** Use the **Pipeline Track** card on the lead detail page. Changing the track **clears the lead's current stage** because stages belong to tracks. The change is logged to CE-60 audit (identifiers only — no PHI).

***

## Unassigned and Terminal Columns

Each track row includes its own **Unassigned** virtual column for active leads that have no stage set. A lead appears only in the Unassigned column of its own track. For example, a Recovery housing lead with no stage shows under the Recovery housing row, not under another track. If a lead's `track_id` is missing or points to an inactive track, the board shows the lead under the org's default track.

The board groups org-wide **Converted** and **Lost** virtual columns into a single **Terminal** row pinned below the active track rows. This keeps terminal leads visible without crowding any one track.

***

## Collapse State on the Board

Each user may collapse/expand individual track rows. Collapse state is stored in browser `sessionStorage` per organization and does not sync across devices.

***

## Permissions

| Permission                  | Allows                                                                                   |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| `ce.pipeline_tracks.manage` | Create, edit, reorder, and delete pipeline tracks. Required to access the settings page. |
| `ce.leads.update`           | Change a lead's pipeline track from the lead detail page.                                |

***

## References

* Spec: [CE-64 Multi-Track Service Line Pipeline](https://github.com/Encore-OS/encoreos/blob/development/specs/ce/specs/CE-64-multi-track-service-line-pipeline.md)
* Plan: [CE-64 Implementation Plan](https://github.com/Encore-OS/encoreos/blob/development/specs/ce/plans/CE-64-multi-track-service-line-pipeline-PLAN.md)
* Context: [CE-64 Implementation Context](https://github.com/Encore-OS/encoreos/blob/development/specs/ce/specs/CE-64-CONTEXT.md)
* Integration: [CE-64 Integration Contract](https://github.com/Encore-OS/encoreos/blob/development/docs/architecture/integrations/CE-64-multi-track-service-line-pipeline-INTEGRATION.md)