Core concepts - KayanOS Documentation

KayanOS works best when people use the same words for the same things. A service request is not a task; a task is not a calendar event; a file is not a permission; and a notification is not proof of a decision. This guide defines the building blocks so your team can model a service clearly before it creates screens, forms, or reports. The examples use the Citizen Services Directorate request CSR-2026-00042. Its path is simple: a request is received, checked, assigned, inspected when necessary, decided, communicated, and closed. The same model can support permits, complaints, maintenance, licensing, project follow-up, or workforce operations.

Goal

Understand how people, records, work, evidence, and access connect so that a member can move from a notification to the correct record and know what to do next.

The shared vocabulary

Term	Meaning in KayanOS	What it is not
Organization	The workplace context that owns members, data, settings, and access rules	A generic label that grants a member access to every record
Member	A staff identity in the organization, with assignments, roles, and available actions	A citizen or applicant unless you deliberately model that person as a record
Role	A reusable set of permitted verbs for resources at an approved scope	A job title that automatically grants every capability
Scope	The bounded part of the organization, hierarchy, form, or resource where a verb applies	A visual filter that can be ignored when saving
Application and section	The organization’s navigation structure for related entities, forms, and dashboards	The data itself or a substitute for a permission check
Entity	A reusable definition of a kind of operational record, such as service requests or inspections	One individual citizen request
Record	One stored item of that entity, such as `CSR-2026-00042`	A temporary popup, toast, or dashboard card
Field	One named value on a record, such as status, owner, location, serial ID, or amount	A translated title; expressions use stable field keys rather than labels
Relation	A controlled connection between records, such as a request and its inspections	A pasted paragraph describing another record
Form	A designed way to collect or update data	The sole durable source for a decision that belongs on an entity record
Form session	One person’s in-progress or submitted interaction with a form	A replacement for the service lifecycle
Status	The approved current stage of a record or task	A free-text note with no accountable meaning
Task	A piece of accountable work with a role, due date, status, and activity	The service case itself or a legal approval by default
Event	A planned time window, meeting, inspection, or review	Evidence that the event took place or that an external invitation was delivered
Library item	A controlled file, folder, or space holding evidence or approved material	A public-access bypass or a substitute for record fields
Notification	A prompt that points to relevant work	The work, evidence, or decision it announces

Start with the durable record

The primary record is the answer to “What are we managing?” In the Citizen Services Directorate scenario, it is Citizen Service Request. It holds durable facts that staff must search, review, filter, report on, and retain:

the human reference request_id, generated by the Serial ID field;
service category, requester path, location, and submitted information;
current status and accountable owner;
requested amount, fee rate, and a calculated estimated fee where the policy requires it;
links to inspections, documents, tasks, and other related operational work; and
the final decision, decision date, and citizen-facing outcome where applicable.

Use a dedicated entity when related work has its own lifecycle. An inspection should be a related record when it needs an inspector, scheduled date, location, findings, attachments, and a status separate from the request. Do not place a series of unrelated inspection notes in one long-text request field if staff must later count, filter, assign, or audit them.

Choose the right object for each action

When designing a service, ask where a fact should survive after the interaction ends.

Need	Recommended object	Example
Collect a citizen’s initial information	Form that creates or updates the request record	Citizen intake asks for category, location, and supporting files
Give staff an issued reference	Serial ID field on the request entity	`CSR-2026-00042` appears in a letter and service conversation
Derive a repeatable value	Calculated field on the entity	`estimated_fee` derives from the requested amount and approved rate
Assign a specific next action	Task related to the request	“Check uploaded evidence by 14:00” is assigned to the Registry Officer
Reserve a time with internal colleagues	Calendar event	Field inspection at a service-center room with inspector and manager
Keep evidence in an approved place	Library file/folder or an approved record file field	Inspection report and photograph bundle in the restricted request space
Ask a quick coordination question	Internal chat	Inspector asks whether the request location was corrected
Record the authoritative finding	Request or inspection record	Inspector saves the verified address and inspection outcome
Alert someone to work	Notification	The manager receives a task-assigned notification that links to the task

The rule is simple: coordinate in a message, but record the operational result in the entity or task that owns it. A chat message can create a task from its text, but the task still needs a clear owner, due date, and relationship to the request.

Fields, labels, and keys

People see field titles such as Request ID, Estimated Fee, or Inspection Date. Builders also maintain stable keys such as request_id, estimated_fee, and inspection_date. A translated title helps a user understand the screen; a key is what calculations, conditions, templates, and integrations use. Do not change a field title just to make an expression work. Do not use a translated label inside an expression. Keep the key stable, give it a clear title in every active language, and document what valid data looks like. For a full implementation guide, see Entity fields and layouts, Serial IDs, and Calculated fields.

Status, task, and decision are different controls

A record status describes the service’s approved stage: for example, Received, Under review, Inspection scheduled, Decision ready, or Closed. A task assigns work needed to move or verify that stage. A formal decision may additionally require a configured action, signature, or form response. For example:

The request is Received after intake.
A completeness task is assigned to the Registry Officer.
The officer records missing evidence and moves the request according to the approved rule.
The Service Manager schedules an inspection and creates the related inspection record.
The inspector records findings; the request can become Decision ready only when the required evidence exists.
The authorized reviewer records the decision through the configured workflow. Closing a task alone does not prove that a formal signature or policy decision happened.

Access follows the work

KayanOS permissions are based on assigned verbs and scopes. The same person may be allowed to list requests in one service center, open a specific inspection, update only their assigned work, download a file, or see a notification without being permitted to share or delete the underlying item. Design access with the service path in mind:

the Registry Officer may create and update intake data in the approved intake scope;
the Field Inspector may open assigned requests and update inspections in the field-service scope;
the Records Officer may open and share only the approved evidence space;
the Service Manager may assign work and update the service status; and
an administrator manages organization-wide setup but is not automatically the operational owner of every request.

Always test both an allowed route and a denied route. A member should not gain wider record access merely because they can see a sidebar category or receive a notification.

A practical design check

Before building the next screen, write one sentence for each question:

What is the primary record?
Which fields are facts, which are calculated, and which are evidence links?
Which related records need their own lifecycle?
Who owns the next action at every status?
Which task, event, or notification helps the owner act without duplicating the record?
Which roles can list, open, create, update, share, or delete each resource, and in what scope?
What must be visible in Arabic and English for the service to be understandable?

If a question has no answer, delay automation, documents, dashboards, and external communication until the core model is clear.

Safe testing

Create one controlled request with synthetic information. Add one inspection, one task, one event, and one evidence file. Then sign in as a non-owner test member and verify that the member can see exactly the intended records and actions. Record the result before removing the test data and temporary grants.

Troubleshooting

Problem	Check first
Staff keep putting decisions in chat	Identify the record field, status action, or task activity that should hold the durable outcome
A calculation cannot find a field	Confirm the stable field key and the calculation context; do not use a translated title
An inspection cannot be filtered or assigned	It may need to be a related entity rather than a repeated paragraph on the request
A member sees a notification but cannot open the target	Review the target record’s scope and the member’s open verb; a notification is not an access grant
A form submission is hard to report on	Confirm that important submitted values are mapped to the correct entity record fields

Build access deliberately in Roles and access.
Learn how the interface exposes available work in Navigate KayanOS.
Follow a complete service path in Explore an example workspace.
Design entities in Plan an app before building and Entities.
Configure formal form actions and signatures in Form actions, logic, and signatures.

KayanOS workspace showing representative public-service records.

​Goal

​The shared vocabulary

​Start with the durable record

​Choose the right object for each action

​Fields, labels, and keys

​Status, task, and decision are different controls

​Access follows the work

​A practical design check

​Safe testing

​Troubleshooting

​Related guides