What it does
Roles are the standardized positions people hold in programs — training levels, faculty positions, staff functions — defined once at the organization level, then enabled per program, then assigned through program membership. Bulk advancement moves a whole training cohort from one role to the next in one validated step, either now or on a set future date.
Who it's for
Organization administrators define and maintain the role catalog; institution administrators view it read-only; program directors and administrators enable roles for their program and run cohort advancements.
How it works
The role catalog. The Roles page lists every organization-standardized role with its code, user type, and internal/external designation. You can search, filter by user type or designation, sort, and export the list. At the institution level this view is read-only — role creation and editing belong to the organization's administrators. Each program chooses which roles are active for it in its own settings.
Advancing a cohort. An advancement takes everyone in a source role within a program — or a hand-picked subset — and moves them to a target role on an effective date. Before anything runs, the platform checks: both roles must exist in the same program and be internal training roles, hand-picked people must actually hold the source role, and the effective date must be today or up to a year out. People on an approved leave are flagged in the selection list, so you can decide whether to include them.
If the effective date is today, the advancement runs right away as one server-side step. If it is in the future, it saves as a pending schedule that fires on its own on that date. Pending schedules are listed for the program and can be cancelled any time before they run. Completed, failed, and cancelled runs from the last 30 days appear in the history view. The full four-step Advance Trainees wizard is covered in the trainee-advancement guide (Advancing Trainees to the Next Training Year).
Before you start
Institution administrators can only view the role catalog; only organization administrators can create or edit a role.
To run an advancement, you need a program's source and target roles already enabled, and you need advancement permission for that program.
Do this
Open the Roles page (
/users/roles) → you should see the role catalog with search and filters.Search by name or code, or use the filters for user type or designate → the list view narrows to matching roles.
Select a role's column header to sort, or select Export in the toolbar to download the filtered list → you should see the sorted list view, or a downloaded file matching your columns.
You're done when
✓ The role catalog shows only the roles matching your search or filters.
✓ An exported file contains the columns and rows you expected.
✓ A cohort advancement (see the trainee-advancement guide (Advancing Trainees to the Next Training Year)) shows the moved people under the target role.
Boundaries and limits
Only internal training roles can be advanced; external and non-training roles are excluded by validation.
Source and target roles must belong to the same program and must be different roles.
The effective date cannot be in the past and cannot be more than one year in the future.
A schedule can only be cancelled while pending. Once executing or completed, it cannot be undone from this screen.
The advancement history view shows runs from the last 30 days.
Institution administrators cannot create or edit roles from the roles page. The catalog is organization-managed; per-program enablement lives in each program's settings.
Role changes made by advancement update program memberships. They do not modify a person's user type.
Common questions
Q: Can I schedule next year's promotions in advance? A: Yes. Set a future effective date (up to one year ahead) and the advancement runs automatically on that date. You can cancel it any time before it fires.
Q: What happens to residents on leave when I advance the cohort? A: People with an approved leave covering today are flagged in the selection list. Use individual selection to exclude them if their advancement should wait.
Q: Someone was advanced by mistake — can I roll it back? A: Not from the advancement screen once it has executed. Their role can be corrected through their program membership.
Q: Why can't I add a new role at my institution? A: The role catalog is standardized at the organization level. Ask an organization administrator to add it; then enable it for your program in program settings.
GME programs
Applies to: gme. Differences from the base article only.
What it does
For residency and fellowship programs, roles are the post-graduate training levels — PGY-1, PGY-2, PGY-3, and so on, plus fellow, faculty, and staff positions. Bulk advancement is the annual PGY promotion: at the start of the academic year, the program moves each resident class from its current PGY level to the next one in a single validated run.
How it works
"Internal training roles" are your PGY levels and fellowship years; faculty and external supervisor roles are not advanceable.
A typical July 1 promotion is set up in advance: schedule one advancement per class (PGY-1 to PGY-2, PGY-2 to PGY-3, and so on) with July 1 as the effective date, and each runs automatically that day.
Residents on an approved leave of absence are flagged in the selection list. For a resident whose training is extended, use individual selection to hold them at their current PGY level and record the extension through their membership status.
Common questions
Q: A resident is off-cycle — how do I promote them alone? A: Run an advancement with individual selection, pick just that resident, and set their promotion date as the effective date.
Q: Does advancing a resident update their training history? A: Advancement changes the current PGY-level role on the program membership. Year-by-year funded training periods and prior training records are maintained separately on the resident's education record.
Related articles