Create a custom entity

A custom entity is a new kind of business record you add to xMatix — a warranty claim, a site survey, an equipment loan — with its own fields, list, forms and menu entry. Creating one is a sequence rather than a single click: the entity itself, then its fields and picklists, its links to other entities, a list view, the forms, a place in an app and access for the people who will use it. Each step is quick, but each one is needed: an entity created and abandoned after the first step shows a list with only a Name column, has no form to add records with, and appears in no user's menu. This page walks through the whole sequence with a warranty-claim tracker as the running example.

Overview

A new entity starts with a small set of built-in system fields and nothing else — no business fields, no views and no layouts. You build the rest in the entity's own setup page, which groups its configuration into Overview, Schema (Fields, Record Types, Field Mappings, Lookup Filters, Relations, Field Dependencies), Logic (Validations, Actions, Approval processes, Document settings, Execution Plan) and Experience (Views, Layouts, Defaults, Messaging templates). This page covers the parts every entity needs; the rest are covered in entity behavior and the other customization guides.

When to use it

Create a custom entity when your business tracks a kind of record that xMatix does not already have, and the record has its own life — it is created, looked up, changed and reported on independently. If you only need one or two extra values on an existing record (an order, an account), add custom fields to that entity instead. If you need several variants of one object with different forms or rules, create one entity with record types rather than several entities.

How xMatix handles it

• No publish step. A custom entity's storage is ready as soon as you save it, and the data API accepts records straight away. Metadata changes are picked up immediately.
• The name you type gets a suffix. Custom entity and field names are stored with _c appended — type WarrantyClaim and the stored name is WarrantyClaim_c. Anything that addresses the entity or a field by name (formulas, integrations, API calls) must use the stored name.
• System fields come for free. Every new entity has Id, Name, Owner, Record Type, Created By, Created On, Modified By and Updated On. You add only the business fields.
• Lookups come from relations. You cannot add a lookup field directly; creating a relation adds the lookup field for you.
• Access is an allow-list. A security profile with no permission row for the entity cannot read it, so new entities are invisible to ordinary users until a profile grants them.

Prerequisites

• The setup.metadata.model.manage capability on one of your profiles — it opens Setup → Design Studio → Entities. Shared option lists need setup.metadata.picklists.manage (Global picklists), and placing the entity in an app needs setup.metadata.apps.manage.
• Rights to edit security profiles under Setup → Access control → Profiles, or someone who has them, for step 8.
• A sketch of the fields and their types. Some type changes are refused once records exist, so a short design pass saves rework.
• If several kinds of this record need different forms or rules, decide the record types now.

Procedure

Step 1 — Create the entity

1. Go to Setup → Design Studio → Entities and select New. The New entity dialog opens.
2. Enter the Label (the singular name users see, for example "Warranty Claim"). Name fills in from the label with spaces removed — "WarrantyClaim". Keep it to letters and digits.
3. Enter the Collection label (the plural, for example "Warranty Claims") and, optionally, a Description.
4. Leave Audited on for anything with business consequence, so changes are recorded in the record history. Leave Search on so the entity can be found in search.
5. Optionally expand the collapsed sections: Visual & identity for the Color and Icon shown in navigation, Permissions & capabilities for what users can do with the entity at all (Create, Edit, Delete, List View and the others — all on except Merge), Features & tracking for Notes, Activities, Duplicate Detection and Track MRU, and AI details for a description the AI assistants can read.
6. Select Create. A confirmation shows the stored name — note it, it ends in _c.

The entity now exists, with only its system fields.

Step 2 — Add the fields

1. Open the entity and go to Schema → Fields, then select New. The New Field dialog opens.
2. Enter the Label and check the Name that fills in from it, then choose the Field Type: Text, MultiLineText, LongMultiLineText, Currency, Number, Date, DateAndTime, PickList, MultiplePickList, Calculated, Boolean, Binary, GeoLocation, TimeOnly, Percent, Decimal or Cron.
3. Fill in the settings the type asks for — String Length for text, Precision and Scale for numbers, Global Picklist for a choice field that uses a shared list, Return Type for a calculated field.
4. Set the behaviour switches you need. Active, Filtering, Sorting, In Calculated and Allow Update start on; Required, Unique, Audited and the others start off.
5. Save. Repeat for each field.

For the warranty claim: Claim Date (Date), Problem Description (MultiLineText), Claim Amount (Currency) and Claim Status (PickList).

Step 3 — Define picklist values

1. In Schema → Fields, open the row menu of the choice field and select Manage PickList Values.
2. Select Add Value for each option and fill in its Label (what users see) and Value (what is stored). Optionally add a Description, Color or Icon, and mark one value Default to preselect it on new records.
3. Drag the rows into the order users should see, then select Save Values. Import Values loads a list in one go.

Get the stored values right the first time: labels can change at any time, but records keep the stored value they were saved with. If the same options are used on several entities, create them once under Setup → Design Studio → Global picklists and choose that list in the field's Global Picklist setting. A field bound to a global list shows "Options come from a Global Picklist" and its values are edited on the global list only.

Step 4 — Link to other entities

1. Go to Schema → Relations and select New. The New Relation dialog opens.
2. Choose the Related Entity — for the claim, Account.
3. Check the generated Lookup Field Name (it defaults to the related entity's name followed by Id), Lookup Field Label, Relation Label and Relation Name.
4. Turn on Required only when a record without the link makes no sense. Turn on Copy with parent on Clone if the link should be copied when a record is cloned.
5. Save. The lookup field is added to your entity automatically, with the same Required setting.

Repeat for each link — an item, a sales order, and so on.

Step 5 — Create a list view

1. Go to Experience → Views and select New. In the New View dialog enter the Label and Name, choose the View Type (usually List), and optionally a Record Type and a Filter Condition under Data Source. Turn on Is Default for the main list.
2. Save, then use the view's row action Manage Columns. In the column drawer, add the columns users should see, put them in order and set the sort direction (Asc or Desc) on the column to sort by.
3. If the view is not yet the default, use Set as default View.

A view without columns shows only the Name column. More views ("Open Claims", "My Claims") can follow at any time.

Step 6 — Design the layouts

1. Go to Experience → Layouts and select New. In the New Layout dialog enter Label and Name, choose the Layout Type, the Platform (Web, Mobile or Both) and, if needed, a Record Type, and turn on Default Layout.
2. Create two layouts: one of type Create (data entry form) for the new-record form and one of type View (read-only / display) for the record page.
3. Open each with the row action Web Design (or Mobile Design for a mobile layout) and arrange the fields in the designer.

Without a Create layout users cannot add records from the list: the dialog shows "No form is set up for" the entity and asks an administrator to create a Create layout. The designer itself is covered in design a form layout.

Step 7 — Place the entity in an app

1. Go to Setup → Design Studio → Apps → Apps.
2. On the app that should carry the entity, use the row action Manage Items. The Manage app items dialog opens.
3. Select Add item, choose Entity and pick your entity, move it to the position you want, and select Save changes.

A new entity appears in no app menu by itself, so this is the step most often forgotten.

Step 8 — Give users access

1. Go to Setup → Access control → Profiles and open the profile your users hold.
2. On the Entity Permissions tab, find the entity and tick what the profile may do: Read, Create, Update, Delete, and where needed Share, Assign, View All or Modify All. Save.
3. On the App Permissions tab, make sure the profile may use the app from step 7.

A user's access can take up to two minutes to pick up a change.

Step 9 — Verify as a user

Sign in as (or with) a user who holds a normal, non-administrator profile. Open the app, find the entity in navigation and create a record: the Create layout should show your fields, picklists should offer the right options in the right order, lookups should find records, and the saved record should appear in the default view with the columns you chose.

Expected result: an authorized user can find the entity in the intended app, create a record with the designed form, reopen it on the View layout, and find it in the list view.

Business rules

• Names. Custom entity and field names may contain only ASCII letters and digits; the platform appends _c. Names must be unique (otherwise "Duplicate Value") and at most 100 characters, as are the label and collection label. The entity description is stored up to 255 characters.
• The entity name cannot be changed after creation — the Name box is locked on edit. Labels can change at any time.
• Field names can be changed with the field's row action Rename (update references), which updates the places that reference it.
• Changes once records exist. When the entity's table holds data:
  • a type change is refused unless it only widens the field — Text to MultiLineText, LongMultiLineText or Cron; Date to DateAndTime; and between Number, Decimal, Currency and Percent;
  • making a field Required needs a Default Value Formula in the same change;
  • making a field Unique is refused.
• Field lengths. Text holds up to 254 characters, MultiLineText up to 4,000 and LongMultiLineText up to 16,000. Scale cannot exceed precision.
• Protected changes. Deleting, renaming, retyping, shortening or deactivating a field that other metadata still uses is refused with a list of the references that would break; open Where Used, deal with them, and retry with the acknowledgement from the impact preview.
• System fields are read-only and cannot be edited.
• Deleting an entity. Delete Entity on the Entities list archives a custom entity: it is hidden at once, records can no longer be created, edited or deleted, and it is marked for permanent removal after 30 days.

Example

A service manager wants to track warranty claims. The administrator:

1. creates Warranty Claim / Warranty Claims (stored as WarrantyClaim_c) with Audited and Search on and a shield icon;
2. adds Claim Date (Date), Problem Description (MultiLineText), Claim Amount (Currency, precision 18, scale 2) and Claim Status (PickList);
3. gives Claim Status the values Submitted (default), Under Review, Approved and Rejected, in that order;
4. adds relations to Account (Required) and Item;
5. creates the view "All Warranty Claims" with columns Name, Account, Item, Claim Date, Claim Amount and Claim Status, sorted by Claim Date descending, as the default;
6. creates a Create layout and a View layout, both marked Default Layout, and arranges the fields;
7. adds the entity to the service app with Manage Items;
8. grants Read, Create and Update on the Service User profile.

A service user then opens the service app, selects Warranty Claims, adds a claim for an account and sees it at the top of the list with status Submitted.

Training

Practice exercise

In a sandbox, create an entity Equipment Loan with the fields Loan Date (Date), Return Date (Date) and Loan Status (PickList: Out, Returned), a required relation to Account, a default list view with four columns, Create and View layouts, an entry in one app, and Read/Create/Update on one test profile. Expected result: a user with that profile sees Equipment Loans in the app, can add a loan, and the loan appears in the list with status Out preselected if you marked it Default.

Quick reference

• Entities: Setup → Design Studio → Entities → New.
• The stored name ends in _c — use it in formulas and integrations.
• Fields: Schema → Fields; lookups only through Schema → Relations.
• Picklist options: field row menu → Manage PickList Values.
• List: Experience → Views, then Manage Columns.
• Forms: Experience → Layouts — one Create and one View layout, both Default Layout.
• Menu: Setup → Design Studio → Apps → Apps → Manage Items.
• Access: Setup → Access control → Profiles → Entity Permissions.
• Decide types and uniqueness before records exist.

Permissions

A user without Read on the entity does not see it at all — not in menus and not in search. The switches in the entity's Permissions & capabilities section apply to everyone: turning off Delete there, for example, removes deleting for all users regardless of profile.

Configuration

• Entity settings — Setup → Design Studio → Entities, open the entity: labels, description, color and icon, Audited, Search, the Permissions & capabilities switches and Features & tracking (Notes, Activities, Duplicate Detection, Track MRU).
• Record types — Schema → Record Types, to scope views, layouts and rules to variants.
• Validations, actions, approvals and numbering — under Logic; see entity behavior.
• Default views and layouts per slot — Experience → Defaults.
• Shared option lists — Setup → Design Studio → Global picklists.
• Menu placement — Setup → Design Studio → Apps → Apps → Manage Items.
• Access — Setup → Access control → Profiles, tabs Entity Permissions, Field Permissions and App Permissions.

Common problems

The list shows only a Name column

The view has no columns. Open Experience → Views, use Manage Columns on the default view and add the columns.

"No form is set up for" the entity when I select New

There is no Create layout. Create a layout of type Create (data entry form), mark it Default Layout, and design it (step 6).

The entity is missing from the app menu

Either the entity was never added to the app (step 7), or the user's profile has no Read permission on the entity or no access to the app (step 8). Check the app's items first, then the profile. After a permission change, allow up to two minutes.

An integration gets "entity not found"

The caller is almost certainly using the name as typed instead of the stored name with _c. Read the stored name on the entity and use exactly that.

"Custom entity names may contain only ASCII letters and digits…"

The name contains an underscore, a space or another character. Use only letters and digits; the platform adds _c itself. Fields give the matching message "Custom field names may contain only ASCII letters and digits."

"Data Type change from … is not possible when there is already data in the entity."

The entity holds records and the new type is not a widening change. Create a new field of the right type, move the values across (for example with an import), and retire the old field.

"A Fields marked required in entity already having data needs a default to be defined."

Add a Default Value Formula in the same edit as turning on Required.

"Marking an field unique if entity is already having data is not permitted."

Uniqueness can only be set while the entity has no records. Decide it before data entry starts.

"Duplicate Value"

Another entity, field or lookup already uses that name. Choose a different one.

"Lookup fields are managed by relations and cannot be created or edited here."

Lookups are created only by relations. Use Schema → Relations → New instead.

Common questions

When can users start entering data?

Technically as soon as the entity exists — there is no publish step, and the data API accepts records right away. In practice, wait until the view, layouts, app placement and profile access (steps 5–8) are in place. Until then users either cannot see the entity at all or meet a list with only a Name column and no form to add records with. Building everything first and then granting access in one go gives users a finished screen on day one.

Why is the stored name different from the name I typed?

The platform appends _c to every custom entity and field name, so that custom names can never collide with the platform's own entities and fields, including ones added in later product updates. The label users see is unaffected. After creating anything custom, read the stored name off the entity or field and use it everywhere a name is required — formulas, filters, integrations and API calls. Lookup fields created by a relation are the exception: they keep the name shown in the relation dialog.

Can I make a relation delete its child records with the parent?

No. The relation dialog shows a Cascade Delete switch, but the setting is not saved and has no effect: a relation you create never deletes the related records when the parent is deleted. If child records must not outlive the parent, plan how they are cleaned up — for example an automation, or a routine where users close or delete the children first — rather than relying on the switch.

Should I set up record types now or later?

Now, if you already know the variants. A record type is cheap to create under Schema → Record Types, and layouts, views and validations are easier to scope from the start than to split later. Adding one later is also fine: metadata that is not scoped to a record type keeps applying to all types. What to avoid is modelling variants as separate entities when they are really one object in two shapes — merging entities later means moving data and rebuilding views and layouts.

Can I undo deleting an entity?

Deleting a custom entity archives it: it disappears from setup and menus straight away and is marked for permanent removal 30 days later. Treat deletion as final, and export any records you need before you delete.

Related topics

• The data model
• Entity behavior
• Design a form layout
• Administration
• The xMatix app builder