Generating a Rota¶

This guide covers how to generate shifts for your practice rota using the multi-phase generation system.

Overview¶

Rota generation is the process of automatically creating shifts for clinicians across a date range you specify. The system builds the rota in six phases, each adding or adjusting a different layer of shifts. You can run phases individually, which gives you control over each step and lets you review the results as you go.

Run rota generation when you need to:

Build a new rota for an upcoming period (for example the next quarter or the next six months).
Fill gaps in an existing rota where shifts are missing.
Rebalance partner shifts to improve fairness.

For best performance, generate three to six months at a time.

The Normal Generation Run¶

For a routine generation you only need four of the six phases, run in this order:

Phase 1: Add Salaried and Partner Fixed Shifts -- with the Pin Partner Shifts option checked, so the partner must-work days it creates are protected from the later optimisation phases.
Phase 3: Fill to Minimum -- tops the rota up to minimum staffing.
Phase 5: WTE Balance Optimization -- rebalances partner shifts for fairness.
Phase 6: Add Duty Doctors -- allocates duty doctor shifts.

Phases 2 and 4 are special-case tools rather than part of the normal run: Phase 2 builds an alternating Week A / Week B pattern for one clinician, and Phase 4 tops up partner weekly minimum shifts when they still have not been met.

Before You Generate¶

Check the following before starting any generation phase.

Clinician working terms must be up to date¶

Every clinician included in generation must have an active working term covering the date range. If a clinician's term is missing or expired, the system cannot calculate their correct shift allocation. Verify working terms on the clinician management page before you begin.

Check for existing shifts¶

The generation page shows a summary of existing shifts. If shifts already exist in your target date range, you will see an "Existing Shifts Detected" warning. Decide whether to:

Preserve existing shifts and only fill gaps (leave "Confirm Overwrite" unchecked).
Replace all unpinned shifts with newly generated ones (check "Confirm Overwrite").

Pinned shifts are always preserved regardless of this setting.

Consider the fixed period boundary¶

The system protects the next six weeks of scheduled shifts from automatic changes. This fixed period gives clinicians stability in the near-term rota. Because of this, generation with a start date inside the notification window is refused while shift notifications are on and batch mode is off — the phase fails immediately with an error explaining your options (enable batch mode, pick a later start date, or disable notifications). This is a deliberate guard: without it, every regenerated shift inside the window would fire an individual email to the affected clinicians. See System Configuration — Shift Notifications for the batch-mode workflow.

Set the reporting period correctly (Phases 3, 5 and 6)¶

Phases 3, 5 and 6 ask for a Reporting Period — a Reporting Start Date and Reporting End Date — in addition to the dates you are generating shifts for. The reporting period is the window over which each clinician's target number of shifts is calculated, so it must reflect the working terms, not just the rota you are generating:

Reporting Start Date — the earliest possible date within the target working terms: the earliest point at which the current set of working terms has been in force. If it is March and everyone's terms have run since the start of the year, use 1 January. If it is October and some people joined, left, or changed working term in June, use the date those terms started — the June date.
Reporting End Date — the end of the rota generation period: the same end date you are generating shifts up to.

Starting the reporting window later than the terms began would miss shifts already owed; starting it earlier would count weeks under the previous terms. The "6 Months" and "Full Year" quick-fill buttons fill the generation dates and the reporting end date for you, but they never set the reporting start date — set that by hand following the rule above.

Starting Generation¶

Accessing the phase dashboard¶

Log in as an administrator.
From the admin dashboard, navigate to Rota Generation (under the admin navigation).
The Multi-Phase Rota Generation page appears, showing all six phases as cards.

Each card shows the phase name, a short description, and its implementation status. Implemented phases have a teal left border and an orange "Run Phase X" button. Click the button to open that phase's configuration page.

Running a phase¶

Each phase has its own configuration form. The general workflow is:

Open the phase page by clicking "Run Phase X" on the dashboard.
Review the stats summary at the top: Active Clinicians, Existing Shifts, Pinned Shifts, and Deletable Shifts.
Configure the form (select clinicians, set dates, and adjust any phase-specific options).
Click the "Run Phase X" button to submit.

The task is sent to a background worker (Celery). A success message appears confirming the task has started, and you can safely navigate away. You do not need to stay on the page while generation runs.

Common form options¶

Most phases share these form fields:

Select Clinicians -- Check or uncheck clinicians to include or exclude them. Clinicians are grouped by type (Partners, Salaried, Locums, FY Doctors, ST Doctors). A "Toggle All" button in each group lets you select or deselect the entire group at once.
Start Date and End Date -- The date range for generation. Use the "6 Months" or "Full Year" quick-fill buttons to set these quickly.
Confirm Overwrite -- When checked, all unpinned shifts in the date range are deleted before generation runs. When unchecked, only gaps are filled.
Existing Shifts Detected warning -- Appears if there are existing shifts. It tells you how many shifts exist, how many are pinned (and will be preserved), and reminds you to use "Confirm Overwrite" if you want to replace unpinned shifts.

The 6 Phases¶

The normal run is Phase 1 → Phase 3 → Phase 5 → Phase 6 (see The Normal Generation Run); the phases below are documented in numerical order. Each phase builds on the shifts created by the previous phases.

Phase 1: Add Salaried and Partner Fixed Shifts¶

What it does: Creates the baseline of fixed shifts for salaried doctors and partners based on their working terms.

What you see on the form:

Clinicians are grouped by employment type: Partners, Salaried, Locums, FY Doctors, and ST Doctors.
FY Doctors and ST Doctors are unchecked by default because they are supernumerary (they do not count toward minimum staffing).
A note under the resident doctor groups explains: "Resident doctors are supernumerary and do not count toward minimum staffing."
You set the start and end dates.
Pin Partner Shifts -- when checked, partner shifts created from must-work days are pinned, so later optimisation phases cannot remove them. Unchecked by default; salaried shifts are not affected. Check this as part of the normal generation run (see The Normal Generation Run).
Email Notification -- receive an email report when the phase finishes.
The usual Confirm Overwrite checkbox is present.

After submitting: The task runs in the background. When it finishes, shifts appear in the system for each selected clinician based on their working term pattern.

Phase 2: Alternate Week Patterns¶

What it does: Lets you create a Week A / Week B alternating pattern for an individual clinician. This is useful for clinicians who work different days on alternating weeks.

What you see on the form:

A Clinician dropdown to select one clinician at a time.
A Start Date field (the start date is adjusted to the first Monday on or after your chosen date).
A Duration Method choice: you can specify either an End Date or a number of weeks (1 to 52).
A two-week grid where you tick the working days for Week A and Week B separately. Each week shows Monday through Friday as checkboxes.

An info box on the page explains:

Shifts start from the first Monday on or after your start date.
Week A and Week B alternate throughout the period.
Bank holidays are skipped automatically.
Existing shifts prevent double-booking.
All created shifts are pinned.

After submitting: Press the Generate Pattern button. A results modal appears showing a table of created shifts (date, day, type, duration, pinned status) and a table of skipped dates with reasons (for example bank holiday, existing shift). A summary shows the number of shifts created, dates skipped, and total processed. Press Done to close the modal and return to the form, ready to run Phase 2 again for a different clinician.

Phase 3: Fill to Minimum (Deficit-Based)¶

What it does: Fills gaps in the rota to meet minimum daily staffing levels, using deficit-based allocation.

What you see on the form:

A clinicians checklist (not grouped by type).
Start Date and End Date fields.
A Reporting Period section with separate Reporting Start Date and Reporting End Date fields. The reporting period defines the window used to calculate clinician target shifts — set it following the reporting period rule. The "6 Months" and "Full Year" buttons fill the generation dates and the reporting end date, but not the reporting start date.
A Generation Mode selector with three options:
All days -- generate shifts for all days.
Mondays only -- only fill Monday slots.
Skip Mondays -- fill all days except Mondays.
The usual Confirm Overwrite checkbox and Existing Shifts warning.

After submitting: The task runs in the background. When it finishes, additional shifts are created to bring daily staffing up to the configured minimum.

Phase 4: Add Partner Minimum Shifts¶

What it does: Ensures partners meet their weekly minimum shift requirements by adding shifts where needed.

What you see on the form:

A clinicians checklist.
Start Date and End Date fields, with "6 Months" and "Full Year" quick-fill buttons.
The usual Confirm Overwrite checkbox and Existing Shifts warning.

After submitting: The task runs in the background. It checks each week in the date range and adds partner shifts where the weekly minimum has not been met.

Phase 5: WTE Balance Optimization¶

What it does: Rearranges and adds partner shifts to balance Whole Time Equivalent (WTE) fairness across clinicians. Salaried, locum, pinned, and duty shifts are untouched. Only partner shifts are adjusted.

What you see on the form:

A clinicians checklist.
Start Date and End Date fields.
A Reporting Period section (Reporting Start Date and Reporting End Date) used for calculating WTE targets — set it following the reporting period rule.
"6 Months" and "Full Year" quick-fill buttons.
An Advanced Settings section (collapsed by default). Click to expand it and you see a list of constraint weights. Each constraint has a name (for example "S7: WTE Target Deficit", "S2: Monday Fairness"), a numeric weight input, and a tooltip explaining what the constraint does. You can adjust weights to change the optimiser's priorities. A "Reset to Defaults" button restores the standard weights. Some constraints are marked as "Disabled" and shown at reduced opacity; these are legacy constraints that have been superseded.
An Email Notification checkbox. When checked, you receive an email report when optimisation completes. This is recommended for longer date ranges.
The usual Confirm Overwrite checkbox and Existing Shifts warning.

After submitting: The task runs in the background. When it finishes, partner shifts have been rearranged to improve WTE balance. If you checked Email Notification, you receive the Phase 5 email report (see the next section).

Phase 6: Add Duty Doctors¶

What it does: Assigns duty doctor shifts, distributed to maintain balance based on each clinician's WTE.

What you see on the form:

Clinicians grouped by type (Partners, Salaried, Locums, FY Doctors, ST Doctors), all checked by default. Uncheck a clinician to exclude them from duty assignment (for example if they are off sick).
A note: "Phase 6 determines clinicians from existing shifts in the date range. Ensure you have run Phase 1-4 before running this phase."
Start Date and End Date fields.
A Reporting Period section with Reporting Start Date and Reporting End Date — set it following the reporting period rule.
"6 Months" and "Full Year" quick-fill buttons.
Email Notification -- receive an email report when the phase finishes.
Convert Pinned Shifts Override -- by default the phase leaves pinned shifts alone; check this to let it convert pinned shifts into duty shifts where needed.
The usual Confirm Overwrite checkbox.

After submitting: The task runs in the background. Duty shifts are assigned across the date range, balanced by WTE contribution.

Reviewing Results¶

After a phase completes, review the results on the calendar.

Checking the phase report¶

After you submit a phase, a waiting page shows a progress bar while the background task runs (you can navigate away — the task keeps going). When the phase finishes successfully, the waiting page is replaced by the phase report, which shows:

The phase name, a "Generation complete" message, and the task ID.
Summary cards: Shifts Created, Shifts Deleted, and the phase's status message.
A Shift Details section listing every created or deleted shift, grouped by clinician and shift type, each with a Created or Deleted badge and a Pinned badge where applicable.
Phase 2 only: a Skipped Dates table giving the reason each date was skipped (bank holiday, existing shift, and so on).
Phase 5 only: WTE Comparison and Monday Comparison tables showing each partner's target, before, after, and change.
A Back to Phase Index link to return to the phase dashboard.

If the phase fails, the waiting page is replaced by an error panel showing the error message, with a Back to Phase Index link. Common refusals — a start date inside the fixed period, or a phase already running for the same dates — are explained in the message itself.

Checking for alerts¶

After generation, the system may create alerts for days that are below minimum staffing or at warning level. Review alerts from the admin alerts page. For details on the alert system, see the technical reference documentation.

Reviewing shifts on the calendar¶

Open the Calendar from the navigation menu. Set the date range to match your generation period and check that:

Shifts are distributed as expected across the period.
No days are left unfilled that should have coverage.
Duty shifts are assigned appropriately.
Pinned shifts (shown with a "Pinned" label) are in the correct places.

The Phase 5 Email Report¶

When you enable email notification on Phase 5, you receive an automated email when optimisation finishes. The email has two main sections.

Solver summary¶

At the top, a green banner tells you whether the solver found an optimal or feasible solution, how many shifts were created and removed, and the solve time. It also shows the generation date range and the reporting period.

Partner WTE Availability comparison¶

The main section is a table titled "Partner WTE Availability -- Before vs After". For each partner clinician, it shows:

WTE% -- the clinician's whole-time equivalent percentage.
Avail Wks -- the number of available weeks in the reporting period.
Shifts Worked (Before and After) -- how many shifts the clinician has in the reporting period.
Target (Before and After) -- the target number of shifts.
Difference (Before and After) -- the gap between shifts worked and target.
Fair Diff (Before and After) -- the fairness difference metric.
Actual/Wk (Before and After) -- actual shifts per available week.

Values that improved after optimisation are highlighted in green.

Monday Balance comparison¶

A second table shows "Monday Balance -- Before vs After" for each clinician:

Actual (Before and After) -- the number of Monday shifts.
Expected (Before and After) -- the expected Monday allocation based on WTE.
Diff (Before and After) -- the difference between actual and expected.

Again, improved values are highlighted.

Failure notification¶

If Phase 5 fails, you receive a red-headed email instead. It shows the error type, the error message, and suggested actions such as checking for conflicting leave requests, verifying minimum staffing requirements, or reviewing cannot-work days for partners.

Regenerating¶

When to regenerate¶

You may need to regenerate the rota when:

A clinician's working terms have changed (new joiner, leaver, or contract change).
Leave has been approved that creates gaps.
You want to extend the rota into a new period.
You are not satisfied with the current shift distribution.

What happens to existing shifts¶

When you regenerate:

Pinned shifts are always preserved. These include shifts you manually placed and shifts created by Phase 2 alternate week patterns.
Unpinned shifts are either preserved (if "Confirm Overwrite" is unchecked) or deleted and replaced (if checked).

To completely redo a period: check "Confirm Overwrite" on the relevant phase. This removes all unpinned shifts in the date range before regenerating.

To fill gaps without disrupting existing shifts: leave "Confirm Overwrite" unchecked. The system will only create shifts where there are gaps.

Re-running individual phases¶

You can re-run any phase independently. For example, if you only need to rebalance partner shifts, you can re-run Phase 5 without re-running Phases 1 through 4. Return to the phase dashboard and click "Run Phase X" for the phase you want to repeat.