What deserves its own entity?
Create an entity when the thing has its own identity, fields, owner, lifecycle, evidence, or reporting need. A field answers a question about one record; an entity represents a thing that can be worked on independently.
For example, a permit request is an entity. Its requested category is a field. An inspection is another entity because it can be scheduled, assigned, completed, and reviewed independently.
A record map that scales
Start with a primary entity and add supporting entities only when their work is genuinely separate.
Do not create an entity simply to make the application look comprehensive. Every entity adds permissions, layouts, relations, reporting choices, and maintenance work.
Build an entity in a reliable order
1. Name the business noun
Use a clear plural name for the collection and a singular phrase for one record. “Inspections” is clearer than “Inspection data”. Use language that staff recognize; avoid implementation terms such as “table 3”.2. Define the record identity
Give the entity a stable serial reference or label strategy. A person should be able to identify a record in a conversation without opening it. Keep system IDs, human references, and external references separate.3. Assign the entity to an application section
Choose the application and section that own the entity before publishing it. Ownership determines where builders manage the resource and where authorized members discover its list in the application workspace. It does not grant list, view, create, or update access; those actions still depend on the member’s verbs and record scope. Use a section whose purpose matches the work, such as Intake, Inspections, or Decisions. Entities and forms are organized by application sections rather than legacy folders, so do not create a folder-like section merely to preserve an old builder arrangement. The Entities catalog groups cards by application and section. Use its searchable application and section selectors to narrow a large workspace, or search by the entity’s technical key, localized title, or localized description. Application and section headings show resource counts and can be collapsed. Each entity card shows its icon, title, key, and available description; open the card to edit the entity. To change ownership, use the card’s move control or drag it to a section, then confirm the destination application and section. Moving an entity changes its builder/navigation ownership and ordering context; it does not grant entity verbs, change record scope, or move the records to another organization. Review automations, saved links, and role-facing navigation after any move. When creating or editing an entity, choose the application first; the section selector then offers sections owned by that application. If the approved application or section does not exist and your role can create it, use Create new from the selector. Provide a multilingual title and description, an appropriate icon, and an intentional order. KayanOS selects and refreshes the newly created owner. Do not create a near-duplicate section to work around a missing permission or a stale filter.4. Add only essential fields
Start with the fields that answer:- What is this record?
- Who owns the next action?
- What is its current status?
- When is it due, scheduled, or completed?
- What evidence supports the decision?
Add a record file space when evidence belongs to the record
In Entity settings → Detail View → Record file spaces, add either a dedicated Files tab or a compact file list inside an existing section. You can place the same collection in both locations; they show the same record-bound folders and files. The record must be saved before its first upload, and the managed collection is created only when someone uploads. Removing a placement does not delete its files. Removing the collection configuration also retains existing files, but hides them from the record after the settings are saved. Opening or changing collection content requires both access to the entity record and the corresponding Library action permission; record access alone does not grant file access. Open in Library opens the managed location without adding it to the normal top-level spaces list.5. Create relationships deliberately
Use a Relation when two records must stay connected without copying their facts. Before creating one, decide:- Is it one-to-one, one-to-many, or many-to-many?
- Which record can exist first?
- What should happen if the related record is removed?
- Which roles may see or edit each side of the relationship?
- Does the relation need to appear in a form, table, dashboard, document, or automation?
6. Give the record a lifecycle
Most operational entities need a Status. Avoid generic stages such as “in progress” if they do not tell staff what to do. For an inspection, Scheduled, On site, Findings recorded, Awaiting review, and Completed are more useful than a single vague status.7. Design access before publishing data
Decide who can create, view, update, decide, and export records. A relation does not grant access by itself. Sensitive fields, attached files, payroll-related values, or internal notes may need a narrower layout or a separate entity.Export table data across organization languages
Use More options → Export all on an entity table to download the rows matching the active table search and filters, or select rows and use Export selected rows for a narrower workbook. Export uses the current member’s entity access and active organization; it does not grant access to records the member could not list. The downloaded Excel file leaves KayanOS controls, so confirm the scope, filters, recipient, approved storage location, and deletion date before exporting sensitive records. For each field configured as multilingual, the workbook creates one column per configured organization language and identifies it with the language code, such asDescription (en) and Description (ar). A Select field creates a stable (key) column plus one label column per configured language. Keep the key when reconciling or reusing the data: labels can be translated or renamed. A missing translation stays blank rather than borrowing text from another language, which makes localization gaps visible instead of disguising them.
Before distributing the workbook, inspect the headers and one authorized test row. Confirm every expected language is configured for the organization, multilingual fields are actually marked multilingual, Select keys match their labels, missing translations are understood, and the current filters produced the intended rows. If a language column is absent, check the organization’s configured languages and the field definition before retrying; do not fill a blank translation with an assumed value.
Review governed AI findings
AI Findings is currently a limited pilot. Its navigation item and record-level finding badges appear only when the current organization-member account is eligible for the pilot and the member has the required capabilities. Capabilities alone do not make those discovery surfaces visible to an account outside the rollout. A saved direct route may still perform its normal permission check, but it is not a substitute for rollout eligibility and should not be shared as a workaround. When the organization enables a reviewed finding policy for an eligible pilot member, KayanOS evaluates eligible records asynchronously and stores the result as an auditable finding. Open AI Findings to search findings, filter by state or severity, sort by recent update, severity, or due date, and inspect one finding’s evidence and audit history. A refined entity-record view can also show its unresolved findings; selecting one opens the same central review record. Treat a finding as a review item, not as a source-record change or final decision. Check the finding revision, source availability, evidence, and audit history before acting. Depending on the assigned capability and current state, a reviewer can confirm, assign, dismiss, resolve, or reopen a finding. Dismissal and resolution reasons become part of the history. If a linked task exists, use it for the assigned work, but verify the current source record before completing that work. AI-findings permissions are deliberately separate:
An administrator should accept a proposed field meaning only when its entity, field key, type, and current schema checksum match the reviewed schema. Create policies with the smallest necessary field scope and keep new policies in collect-only, review-required operation during calibration. Simulate the exact draft revision before activation. Pause a questionable active policy instead of deleting its findings: pausing stops new policy work while preserving findings, events, and action receipts for audit.
Validated evidence, policy approval, and current source version are required before a governed policy can create an alert or task. A confidence percentage alone is not proof. Policies never update the source entity record, and a provider or worker failure must not be interpreted as “no finding.”
Avoid common modeling mistakes
Test the record model before adding automation
Create one normal record and one exception record in a non-production workspace. For each, confirm:- the right person can create and find it;
- the required data can be entered without unnecessary questions;
- relations lead to the correct record;
- the status makes the next action obvious;
- a manager can answer the intended dashboard or report question;
- the catalog finds the entity by key, title, and description under the intended application/section;
- a test move refreshes the catalog and application navigation without changing a limited user’s record access.
Next steps
- Choose detailed types and layouts in Entity fields and layouts.
- Build a staff or public entry experience in Forms.
- Use Expressions in the builder only after source fields and relations are stable.
- Grant the smallest findings capabilities needed in Roles and scopes.
