> ## Documentation Index > Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt > Use this file to discover all available pages before exploring further. # Entities > Model the records your team actually manages, give each one a clear lifecycle, and connect them without duplicating facts. ## 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. | Make it an entity when… | Keep it as a field when… | | ------------------------------------------------- | ------------------------------------------------ | | it can have several related records | it is one property of the current record | | it needs its own status or owner | it never moves through a process alone | | it needs evidence, comments, files, or history | it is a short answer or controlled choice | | it is reused by many records | duplicating it would create conflicting versions | | people need a list, dashboard, or report about it | it is only used to describe the parent record | 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. | Primary entity | Supporting entities | Why the split helps | | ---------------- | ------------------------------------------------ | ----------------------------------------------------------------- | | Service case | appointment, inspection, follow-up task | each activity has a schedule, owner, and outcome | | Work order | site, visit, asset, part request | site and asset are reused; a visit has its own evidence | | Leave request | coverage task, approval | coverage and approval may be assigned to different people | | Purchase request | quotation, approval, budget allocation | each record has different visibility and decision rules | | Project change | impact assessment, decision, implementation task | assessment, decision, and delivery should be traceable separately | 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. | Catalog symptom | Check first | Safe response | | -------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | An entity is missing | Search text, selected application/section, collapsed groups, and the entity's current ownership | Clear only the relevant filter, expand the group, and search by the stable key; do not recreate the entity. | | The section selector is unavailable or empty | Whether an application is selected and whether it owns any sections | Select the approved application first; create a section only when the information architecture owner has approved it. | | A move or inline creation fails | Current organization, builder permission, and create/update scope for the resource and destination | Ask the role owner for the narrow missing capability or have an authorized builder perform the move; do not broaden record access. | ### 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? Use [Entity fields and layouts](/build/entity-fields-and-layouts) for the detailed type 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 as `Description (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: | Capability | What it permits | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | List findings | See organization-scoped finding summaries that are available to the role. | | View evidence | See an evidence item only when the member can also list the source record and read any protected source field. Otherwise KayanOS redacts the evidence. | | Review findings | Confirm, assign, dismiss, resolve, and reopen eligible finding revisions. It does not grant policy management. | | Manage policies | Review schema-semantic proposals and manage the policy lifecycle. It does not grant source-record access. | | View operations | Inspect sanitized evaluation runs and safe failure information. It does not expose protected source content or raw provider material. | 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.” | Symptom | Check first | Safe response | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | **AI Findings** is missing or access is denied | The active organization, pilot eligibility of the organization-member account, and the role's `ai_findings` capabilities | Ask the rollout owner to confirm eligibility, then request only the smallest missing capability; do not use a direct link as a workaround. | | Evidence is hidden | Current source-record list scope, protected field access, and whether the source still exists | Review with an authorized member or restore legitimate source access; do not copy evidence around the permission boundary. | | A review action reports a conflict | Whether another reviewer or a reevaluation changed the finding revision | Refresh and review the new revision before deciding again. | | An evaluation is failed or insufficient | The sanitized Operations result, source availability, policy revision, and approved evidence scope | Correct the source/policy problem or retry through the authorized process; do not treat failure as a resolved condition. | ## Avoid common modeling mistakes | Mistake | Better design | | -------------------------------------------------------- | ------------------------------------------------------------------------------- | | Repeating an applicant name and contact on every request | Create or relate an applicant record when reuse and history matter. | | Putting inspection notes in the request description | Create an inspection entity with date, owner, result, and evidence. | | Using a text field for “current stage” | Use Status when the value drives work and reporting. | | Storing several related values in one long-text field | Use structured fields or related records. | | Creating one giant “operations” entity | Split only where items have different owners, lifecycles, or access boundaries. | ## Test the record model before adding automation Create one normal record and one exception record in a non-production workspace. For each, confirm: 1. the right person can create and find it; 2. the required data can be entered without unnecessary questions; 3. relations lead to the correct record; 4. the status makes the next action obvious; 5. a manager can answer the intended dashboard or report question; 6. the catalog finds the entity by key, title, and description under the intended application/section; 7. a test move refreshes the catalog and application navigation without changing a limited user's record access. If this manual path is unclear, automation will only make the confusion happen faster. ## Next steps * Choose detailed types and layouts in [Entity fields and layouts](/build/entity-fields-and-layouts). * Build a staff or public entry experience in [Forms](/build/forms). * Use [Expressions in the builder](/build/expressions-in-builder) only after source fields and relations are stable. * Grant the smallest findings capabilities needed in [Roles and scopes](/admin/roles-and-scopes). ![KayanOS entity list](https://kayanos.app/docs-images/en/build/entities.png)