Roles and Access

MedCES uses one access model across every module. A user does not receive access simply because their job title appears in their profile. The system checks who the user is, where they work, which roles they hold, and whether they are connected to the work they are trying to complete.

How access is calculated

Membership
  + core role
  + organisational scope
  + functional role
  + current academic or operational assignment
  + record state
  = effective access

Each part answers a different question:

Part	Question answered
Membership	Which tenant or institute does this person belong to?
Core role	What is the person’s basic relationship with MedCES?
Organisational scope	Where can the role be used?
Functional role	What specific work has the person been asked to perform?
Current assignment	Is the person connected to this course, session, posting, learner, or case?
Record state	Is the record still editable, awaiting review, published, or closed?

Membership alone gives no working permissions. A functional role may be assigned to a tenant member without making that person an administrator.

Core roles

The role codes below are fixed throughout MedCES. A tenant may change the label shown to users, but the underlying meaning and permissions do not change.

System role	Normal scope	What it is for
`PLATFORM_ADMIN`	Platform	Tenant creation, platform reference data, programme-pack releases, integrations, and controlled technical support
`TENANT_ADMIN`	Tenant	Tenant settings, institutes, memberships, labels, and access administration within one tenant
`INSTITUTE_ADMIN`	Institute	Institute setup, institute users, readiness, and authorised institute-wide administration
`DEPARTMENT_ADMIN`	Department	Department setup, department faculty associations, resources, and department-level work
`UNIT_ADMIN`	Department unit	Unit membership, capacity, availability, and unit-level work
`FACULTY`	Academic assignments within an institute	Teaching, supervision, feedback, attendance, and competency work for assigned learners and activities
`STUDENT`	The student’s own enrolment	The student’s timetable, attendance, postings, submissions, logbook, feedback, and progress

Platform Admin

A Platform Admin can create tenant shells, maintain platform-owned references, release tested programme packs, and support the application. This role does not automatically provide access to candidate, student, faculty, admission, or academic records. Any support access to tenant data must be time-bound, reason-based, and audited.

Tenant Admin

A Tenant Admin works inside one tenant. The role can maintain tenant settings, create institutes, manage memberships, configure display labels, and grant authorised roles below the tenant level. It cannot grant Platform Admin, work outside the tenant, or make academic and admission decisions merely because it is an administrative role.

Institute Admin

An Institute Admin works inside one institute and its departments and units. The role can coordinate institute setup, manage institute access, and view institute-wide readiness and audit information. It does not automatically allow the user to teach, certify competencies, mark attendance, make admission decisions, or approve their own high-impact changes.

Department Admin

A Department Admin works inside one department and, for permitted actions, its units. The role can maintain department information, confirm department participation in courses and postings, and manage department-level resources. It does not provide access to sibling departments or institute-wide publication authority.

Unit Admin

A Unit Admin works inside one department unit. The role can maintain the unit team, capacity, availability, and permitted unit-level information. It does not provide access to sibling units or the ability to teach and assess unless the person also has the Faculty role and the relevant assignment.

Faculty

Faculty access is limited by current institute placement, department and unit associations, and assigned academic work. A Faculty user cannot see every student, mark attendance for an unassigned session, or certify every competency. Seniority alone does not create system access.

Student

A Student can work only with their own enrolment and assigned academic activities. A student cannot see another student’s records, change official attendance, approve their own evidence, or alter the curriculum or schedule.

Scope and inheritance

Administrative roles are granted at an entity in the institutional hierarchy:

Tenant Admin at Tenant A
  -> permitted tenant actions in Tenant A

Institute Admin at Institute A
  -> permitted institute actions in Institute A and its descendants

Department Admin at General Medicine
  -> permitted department actions in General Medicine and its units

Unit Admin at Medicine Unit 1
  -> permitted unit actions in Medicine Unit 1 only

Inheritance applies only to capabilities included in the grant. It never means unrestricted access to every record below that entity. A department grant does not include sibling departments, and an institute grant does not include another institute in the same tenant.

Faculty and Student access is not calculated from hierarchy inheritance alone. It also uses enrolment, teaching, posting, supervision, and learner assignments.

Functional roles

Functional roles give a user the specific capabilities needed for a job without granting a broad administrator role.

Examples include:

Academic Registrar;
Dean;
Principal;
Admission Officer;
Counselling Coordinator;
Facilities Officer;
Curriculum Committee Member;
Assessment Coordinator;
Progression Committee Member;
Phase Coordinator;
Course Coordinator;
Timetable Coordinator;
Clinical Posting Coordinator;
Attendance Approver;
Auditor.

For example, an admissions employee can be recorded as:

Institute membership
  + Admission Officer role at that institute
  + admission capabilities

The person does not need the broad Institute Admin role. The functional role grant has its own scope, validity dates, approval, and capability set.

For Student Lifecycle services, the Academic Registrar is the primary operating role. A user with the Dean or Principal role may approve sensitive transitions when the applicable policy requires it. Holding the Dean or Principal appointment alone does not grant this access; the corresponding functional role must also be assigned.

Core roles are not a compulsory first step for every employee. A tenant member may receive only a functional role when that is all their work requires. For example, an Academic Registrar may have institute membership and the Academic Registrar functional role, without holding Institute Admin.

Designations and appointments

Faculty designations describe academic rank, such as Professor, Associate Professor, or Assistant Professor. They come from a controlled master list and can be mapped to a tenant’s local display title.

Administrative and academic appointments describe positions held for a period, such as Head of Department, Unit Head, Dean, Principal, Medical Superintendent, or postgraduate guide.

Neither a designation nor an appointment silently grants system access. The required role or functional role must be assigned separately.

For competency work, the base role is Faculty. MedCES then combines the faculty member’s permitted designation with department or unit association, course or posting assignment, learner scope, effective dates, and the curriculum certification rule. A separate Competency Certifier role is not required, and designation alone is not enough.

Dr Sharma
├── Faculty role — Institute A
├── Department Admin role — General Medicine
├── Designation — Professor
└── Appointment — Head of Department, General Medicine

This separation preserves history when the person, designation, appointment, or administrator changes.

User access workspace

The operational screens are described in Users and Access Assignment. The workspace provides:

User Directory — search users, memberships, status, and current access.
Invite User — create or connect an identity and establish membership.
Role Assignment — select a core role, scope, validity, and approver.
Functional Role Assignment — assign job-specific capabilities without broad administrator access.
Access Review — show how the user’s effective access was calculated.
Suspend or Revoke — end access without deleting history.
Access History — show every grant, change, approval, use of support access, and revocation.

Access rules

A user may hold more than one role at different scopes.
Every grant has a start date, status, and optional end date.
The granting user cannot grant a role or capability they are not authorised to manage.
Tenant labels are display-only and cannot change role codes, permissions, APIs, or audit meaning.
Faculty designation does not grant administrative access.
An appointment does not grant access unless the matching core or functional role is also active.
Functional roles follow least privilege: only the capabilities needed for that work are granted.
Approval, editing, publication, viewing sensitive fields, and auditing are separate capabilities.
High-impact changes should not be approved by the same person who prepared them.
Suspended or expired access stops new work immediately but keeps history intact.
Regulatory, affiliation, examination, and counselling relationships do not grant user access.

Data model

Core records

Record	Important fields	Purpose
`identity.user`	`id`, login identity, display name, status	One person or service identity that can sign in
`iam.tenant_membership`	`user_id`, `tenant_id`, membership type, status, validity	Connects a user to a tenant without granting working permissions
`iam.role_definition`	stable role code, name, allowed scope types, status	Defines the seven core roles
`iam.role_label_override`	`tenant_id`, role code, display label	Changes only the label shown by one tenant
`iam.role_grant`	`user_id`, role code, `scope_entity_id`, validity, status, reason, approver	Grants a core role at a defined scope
`iam.capability_definition`	capability code, module, action, sensitivity	Defines one permitted action
`iam.role_capability`	role code, capability code, conditions	Defines the base capabilities included in a role
`iam.functional_role_definition`	functional role code, label, permitted scope types	Defines work such as Admission Officer or Curriculum Committee Member
`iam.functional_role_capability`	functional role code, capability code	Defines the capabilities included in a functional role
`iam.functional_role_grant`	`user_id`, functional role code, scope, target record, validity, status	Assigns specific work to a tenant member
`iam.access_review`	subject user, reviewer, review period, decision	Records periodic confirmation of continued access
`iam.access_event`	actor, subject, action, previous value, new value, reason, time	Preserves an immutable access history

Faculty designations are stored separately in people.faculty_designation_assignment. Positions such as HOD and Unit Head are stored separately in org.person_appointment. Department, unit, course, session, posting, and student assignments remain in their owning modules and are consulted when effective access is calculated.

Relationship summary

User
├── Tenant Membership
├── Role Grants
│   └── Role -> Capabilities
├── Functional Role Grants
│   └── Functional Role -> Capabilities
├── Designations and Appointments
└── Academic or Operational Assignments

Process-layer responsibilities

The access service must:

resolve the user’s active memberships, core roles, functional roles, and assignments;
expand hierarchy scope only across permitted descendant relationships;
apply tenant isolation before evaluating any business permission;
check validity dates and record state at the time of the action;
prevent duplicate or overlapping grants that mean the same thing;
prevent a user from granting authority they do not possess;
explain why an action was allowed or denied;
invalidate active sessions or permission caches when access is suspended or revoked;
record every material access change and sensitive support event.

The application screen may hide an unavailable action, but the service must repeat the permission check when the action is submitted.