Roles and scopes - KayanOS Documentation

Roles turn an operating responsibility into controlled access. They are not job titles, menu labels, or a way to make a blocked button disappear. KayanOS evaluates a protected resource, the assigned verb, and the scope of the actual record. A person can therefore see a service category but still be unable to open a record, save a change, share a file, delete an event, or perform a formal decision. Use this guide to configure roles for the Directorate of Citizen Services. The same method applies to any organization: name the responsibility, identify the smallest set of resources and verbs, select the correct scope, assign the role, and test it as a non-owner.

Goal

Build explainable roles that let Registry, Field Inspection, Decision and Records, and organization administration teams complete their work without expanding access across unrelated Service Centres or records.

The access model

Every grant should read as a sentence:

This role may perform this verb on this resource in this scope.

Part	Question	Directorate example
Resource	What is being protected?	Citizen Service Requests, Inspections, files, forms, events, members, or roles
Verb	What may the member do?	List, open, create, update, delete, share, initiate, or a resource-specific action
Scope	Where does the verb apply?	One Service Centre, locality hierarchy, organization, form, or another assignable boundary
Assignee	Who receives the role?	A member, position, group, or approved assignment rule

The distinction matters. List does not automatically mean open; open does not mean update; update does not mean share or delete. Navigation can be generated for an entity when a member has a useful list or create path, but an entry in the menu is not a promise that every record or action is allowed.

Scope choices and inheritance

Where the selected hierarchy supports it, a role assignment can apply to the exact target, its ancestors, or its descendants.

Scope choice	Use it when	Risk to test
Exact	A Registry Officer works only in North Service Centre	The officer cannot see a legitimate record that is stored in an approved child boundary
Ancestors	A local assignment needs a documented parent-level path	Higher-level records become visible when they should remain centralized
Descendants	A regional manager is accountable for a region and all approved child centres	The selected region is too broad and exposes an unrelated locality

Do not select an inherited scope merely because it makes a missing record appear. First establish the business boundary; then test a record inside and outside that boundary. Scope is enforced against the record’s applicable scope tokens, not merely as a visual filter.

Design the service roles before opening the editor

Start with a short responsibility map. The following is a starting pattern, not a ready-made permission set:

Role	Required outcome	Minimum useful access	Do not assume
Registry Officer	Register and return incomplete requests for one Service Centre	List/open/create/update intake requests in that centre; update assigned completeness tasks	Access to other centres, organization settings, or a final decision
Field Inspector	Record an assigned inspection	Open relevant request/inspection work; create/update inspections in field scope; upload approved evidence	Permission to change the final decision or share every file
Decision and Records Officer	Review evidence and controlled documents	Open the decision packet; update approved document metadata or file actions in scope	Operational ownership of every request or unrestricted deletion
Service Manager	Allocate work and manage the service lifecycle	Open/update requests in managed scope; create tasks/events; review exceptions	Role administration simply because the person is a manager
Organization Administrator	Maintain configuration	Role, member, language, homepage, or other settings only when the corresponding verbs are assigned	Automatic operational ownership of all citizen requests

For each row, list the action that must remain denied. A role is not complete until it has an intended boundary.

Configure a role deliberately

Open Administration → Roles and scopes and verify that you have the relevant role-management permission. Opening, creating, and updating roles are separate capabilities.
Choose the role’s administration scope: organization-wide, an eligible hierarchy boundary, a form, or another supported scope. Do not use organization scope as a temporary shortcut.
Name the role after the responsibility, for example North Service Centre Registry Officer, and describe the business purpose and review owner.
In the permissions area, select only the resources the role needs. For each resource, select the actual verbs separately.
Where an assignment permits hierarchy selection, choose Exact, Ancestors, or Descendants intentionally. Record the rationale in the change record.
Assign the role to the approved member, position, group, or rule-derived recipient. Check whether an inherited assignment from a position or group will also grant it.
Save one role change at a time. Avoid copying a broad existing administrator role just to resolve one exception.
Refresh the allowed member context as required and test navigation, list, open, create, update, share/download, and delete actions that matter to the service.

The permission editor surfaces resources eligible for the selected scope. If an entity or form is absent, verify the entity/form configuration and assignable scope before trying to compensate with a broader role.

Test the Citizen Service Request boundary

Create two approved non-production requests: one in North Service Centre and one in a different locality. Give each test member only the role being evaluated. Then record the following matrix:

Test member	Must be allowed	Must be denied
Registry Officer, North	Create and update a received North request	Open or update the other locality’s restricted request
Field Inspector	Update assigned inspection findings in field scope	Change the request’s final controlled decision
Records Officer	Open/share the approved evidence folder in scope	Permanently delete a restricted folder or change unrelated service data
Service Manager	Assign a task and schedule an event	Edit role definitions unless role-management access was separately granted
Organization Administrator	Maintain the approved setting	Assume access to a citizen record outside a granted service scope

Record the route, member, resource, verb, record scope, expected outcome, actual outcome, and reviewer. A failed negative test is useful evidence: it means the boundary needs correction before publishing, not that the test member needs broader access.

Change control and review

Review a role when a staff member transfers, a position changes, a group changes, a Service Centre moves in the hierarchy, a form becomes published, or a new related entity becomes part of a service. Check both direct and inherited assignments. Before deleting or narrowing a role, inventory its active use. A role change can remove a user’s ability to complete a task, open an evidence file, or access a form that is still part of an active service path. Plan the handoff first; do not use a shared organization-owner account to bridge a gap.

Troubleshooting

Symptom	Check	Safe response
A member cannot see an application/entity entry	Published placement plus list/create/initiate verbs	Grant only the required verb in the intended scope
The list is visible but a record will not open	Open verb and the record’s actual scope tokens	Compare an allowed and denied record; do not change the whole role blindly
Save or Delete is unavailable	Update/delete verb, record scope, field/action state	Request the smallest action needed for the responsibility
A role editor Save is denied	The current member may open roles but lack role update	Use an authorized role administrator; do not share their account
A regional role sees too much	Ancestor/descendant setting and inherited assignment path	Replace it with the narrowest exact or branch scope and retest
Access remains after a transfer	Direct role, position/group assignment, and hierarchy rule	Remove every obsolete assignment and test with the member’s current context

Manage the people receiving roles in Manage members.
Learn the everyday access model in Roles and access.
Use controlled evidence access in Library.
Diagnose visibility and action failures in Permissions and availability.

KayanOS role and scope configuration for Directorate of Citizen Services staff.

​Goal

​The access model

​Scope choices and inheritance

​Design the service roles before opening the editor

​Configure a role deliberately

​Test the Citizen Service Request boundary

​Change control and review

​Troubleshooting

​Related guides