# Custom Entities

> Build your own data models and record forms without writing code.

## Overview

Custom Entities let you define your own business objects without writing code. When you need a record type specific to your work — "Site Visit", "Customer Complaint", "Asset Request" — you create your own entity instead of waiting for a built-in module. Think of an entity as a table: you decide which fields it holds (text, date, number, choice list and more), then you start adding records to it.

Once you define an entity, the platform automatically generates a record form and a list screen for it. You can make fields required, add a uniqueness rule, link one field to another entity (for example, every "Task" belongs to a "Project"), and constrain the states a record can move through with a **status flow**. All of this data is private to your organization and fully isolated from other organizations.

If you would rather not start from scratch, apply one of the ready-made **packages** with a single click and have a working structure up in minutes.

## Who uses it

- **Organization administrators:** People allowed to define, edit and delete entities and their fields. They build the data model.
- **Team members:** People who add, update and list records against defined entities. Depending on their permissions, they can view only or also edit.
- **Process owners:** People who manage records as they move through a status flow such as "Open → In Progress → Done".

An agency can track client requests, a manufacturing team can track maintenance records, a sales team can track site visits — each defining its own fields and rules.

## Step-by-step process

1. **Create a new entity.** From the Custom Entities section, start with "New Entity". Give it a readable name (for example "Site Visit"), an icon and, optionally, a short description.
2. **Add fields.** Add the fields your entity needs. For each field you pick a type: text, long text, number, decimal, date, date-time, yes/no, email, phone, link, single select, multi select, file, currency, reference (a link to another entity) or status.
3. **Set field rules.** Make a field required or unique, enter options for choice lists, and choose the target entity for reference fields.
4. **Define a status flow (optional).** If your records follow a lifecycle, add a status field: set the initial state, the final states and which state can move to which. The platform blocks any transition that breaks these rules.
5. **Start adding records.** Once the entity is ready, you enter records through the automatically generated form. Every create, update and delete is kept in a history log (audit trail).
6. **Set permissions.** Decide who can design entities and who can create and edit records from the roles and permissions settings. View and edit rights are granted separately.

If you prefer, apply a **package** from the catalog to start with ready entities, fields and sample records. For example, the Task-Lite package sets up project, task and comment entities together with a status flow in a single step.

## Process flow

```mermaid
flowchart TD
    A[Create a new entity] --> B[Add fields and pick their type]
    B --> C{Rules}
    C --> D[Required / unique fields]
    C --> E[Reference: link to another entity]
    C --> F[Define a status flow]
    D --> G[Entity is ready]
    E --> G
    F --> G
    G --> H[Add / update / list records]
    H --> I[Access based on permissions]
    A -. quick start .-> J[Apply a package from the catalog]
    J --> G
```

## Frequently asked questions

**Can I really build my own data model without knowing how to code?**
Yes. The whole process runs through forms and choice lists. You pick a field's type and tick its rules; the platform generates the record form, the list screen and the validations for you.

**How do I link one record to another?**
Add a reference field and choose the target entity. For example, if you add a "Project" reference to a "Task" entity, each task record can select the project it belongs to, and you can view a project's tasks together.

**Can I restrict which state a record can move to?**
Yes. When you define a status field you set the initial state, the final states and the allowed transitions. For example, a record in "Done" cannot go back to "Open". The platform blocks out-of-rule transitions both in the form and in the background.

**If I delete a field later, what happens to old records?**
It is recommended to deactivate a field rather than delete it, so values in past records are preserved. A field's system name cannot be changed because records are tied to it, but you can update its display name.

**Can I see who changed a record and when?**
Yes. Every create, update and delete is stored in a history log; you can see the previous and new value of each changed field.

**Does applying a package damage my existing data?**
No. Packages are applied additively and a package is installed into an organization at most once. If you already have your own entity with the same name, the package does not take it over; in case of a conflict the operation stops safely.