Entity behavior: views, validations, actions, mappings, filters and dependencies

Every xMatix entity carries six configurable behavior surfaces beyond its fields: saved list views, save-blocking validations, action buttons, field mappings that copy values from a looked-up record, lookup filters that narrow a picker, and field dependencies that narrow one picklist by another. You configure all six on the entity itself in Setup → Design Studio → Entities, without code. They sit between the data model (the entity and its fields, which come first) and the heavier automation — business rules, workflows and scripts — that you reach for when a surface here is not enough.

Overview

When to use it

• A list should open with the right columns and records — a view.
• A record must not be saved in a certain state and a condition plus a message says it all — a validation.
• Users need a button to open a form, print, or run server logic — an action.
• Picking a record should fill in other fields (pick an item, get its price) — a field mapping.
• A picker offers too many records (inactive accounts, other regions) — a lookup filter.
• One picklist's values only make sense for some values of another (Category → Subcategory) — a field dependency.

Use a business rule instead when you need a trigger (only on create, only when a field changes), conditionally required or read-only fields, derived values or follow-up work after the save.

How xMatix handles it

When a record is saved, the server applies these surfaces in a fixed order (see what runs when you save a record):

1. Field mappings fill values while a new record's defaults are loaded.
2. Validations are checked. Any violated validation rejects the save.
3. Business rules run.
4. Field dependencies are enforced last, so they judge the values the business rules left behind.

Views and lookup filters act when data is read: a view's filter is combined with whatever the user filters by, and a lookup filter is applied each time the picker searches. Actions run when a user presses the button.

Because validations run before business rules, a validation cannot be satisfied by a value a business rule is about to set in the same save.

Prerequisites

• The Entities page under Setup → Design Studio, and every page described here, needs the setup.metadata.model.manage capability (see the security model).
• The entity and the fields you will use already exist — see create an entity.
• Know the stored values of any picklist you compare in a condition. Conditions compare stored values, not display labels.

Procedure

Step 1 — Open the entity

Go to Setup → Design Studio → Entities and open the entity. Its left menu groups the pages under 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, Email templates).

Step 2 — Create a view

Open Experience → Views and choose New in the page header. Enter Label (the Name fills itself from it) and Description, choose a View Type, optionally a Record Type, and add a Filter Condition under Data Source. Choose Create. The view appears in the All Views table.

Step 3 — Choose the view's columns and sort

On the view's row, choose Manage Columns. The Configure Columns drawer lets you pick the columns, put them in order and set the sort. Save the drawer. To make the view the entity's default list, bind it under Experience → Defaults (or switch on Is Default on the view).

Step 4 — Add a validation

Open Logic → Validations and choose New. Enter Label, choose Severity and Error Location (and Target Field if the location is Field), build the Condition so that it is true when the record is wrong, and write the Message. Leave Active on and choose Create. Test it by saving a record that breaks the rule: the save is rejected with your message.

Step 5 — Add an action

Open Logic → Actions and choose New. Enter Label, choose Action Type and Host Page, and fill the fields the type asks for (for a Server Action, the Server Action Name and Execution; for Preview or Print, the Print layout). Optionally switch on Enable confirm dialog. Choose Create. The button appears on the chosen surface; drag rows in the All Actions table to change the order.

Step 6 — Add a field mapping

Open Schema → Field Mappings. On the Copied into this record tab, choose New. Pick How the value arrives, the Destination Field, the Source Entity, the lookup that points at it, and the Source Field. Leave Apply when a record is created on for the usual copy-at-creation, and choose Create. The How it works? button in the page header opens a guide with worked examples.

Step 7 — Add a lookup filter

Open Schema → Lookup Filters and choose New. Enter Label, pick the Lookup Field, optionally a Record Type and Target Record Type, and choose Open Filter Builder to build the Filter Condition. In the builder's Advanced tab, choose Validate before you apply. Choose Create, then open a form with that lookup and check that the picker offers the right records.

Step 8 — Add a field dependency

Open Schema → Field Dependencies and choose Create Field Dependency (the same button is on the Fields page). Choose On a picklist field or On a condition, pick the fields, then map the values or write the rules. Save. The table shows the dependent field, its type and the On Save behavior.

Step 9 — Change, clone, switch off or delete

Every table offers Edit and Delete as row actions; views, validations, actions, field mappings and lookup filters can also be cloned, and views, validations and actions can be activated or deactivated from the row. Delete asks for confirmation ("This action cannot be undone. Continue?"). Prefer Deactivate for anything you may want back. Rows marked Standard in the Source column come with the platform or an installed package; see Common problems for how to change them.

Views

A view is a saved list: its columns, a filter built into the definition, a sort, and optionally a grouped or tree presentation. Views can be scoped to a record type.

View fields

Columns and sort are not in this dialog: set them with the Manage Columns row action. The Design Card row action designs the card used by mobile lists and web board views.

How views behave

• Which view opens. The list opens the view bound under Experience → Defaults for the app, record type and platform; failing that, the first view marked Is Default; failing that, the first view. Nothing stops you marking more than one view as default, so keep exactly one, or use Defaults.
• Filters combine. Whatever the user filters by at run time is combined (AND) with the view's own filter.
• A view with no columns still shows the record's name column only, which users read as breakage. Always add columns.
• A filter naming a field that does not exist is not checked when you save the view. It fails when the view runs, so open the view once after creating it.
• Lookup pickers use views too. A lookup to this entity lists its candidates through the entity's Search view, else its first active All view. Only a Search view's filter narrows the picker; any other view lends only its columns. If records the lookup should offer are missing, check the target entity's Search view.

Validations

A validation is a condition that is true when the record is wrong, plus the message the user sees.

Validation fields

How validations behave

• Every violated validation rejects the save, whatever its Severity. Warning and Info are stored with the rule but do not let the record through. Leave a rule inactive, or move it to a business rule's message action, if you only want to inform.
• They run on the server, so a save from a form and a save through the data API are both checked.
• Record type. A validation scoped to a record type runs only for records of that type; a record with no record type runs only the unscoped validations.
• On edit, only relevant rules re-check. When an existing record is edited, a validation is re-checked only when a field its condition reads has changed.
• A broken condition never fires. If the condition cannot be parsed or evaluated — a misspelled field, a bad escape in a string — the rule is treated as not violated, silently. Comparing a picklist to its display label instead of its stored value has the same effect for ==. Always test a new validation by saving a violating record.
• Message placement. Field puts the message on the field; if that field is not on the current layout, the message shows in the summary banner instead.

Actions

An action puts a button on the record page, the list header or each list row.

Action fields

Submit for Approval is not created here: it appears automatically for an entity with an active approval process, and you enable it on the layout. See approvals.

How actions behave

• Server actions are the extension point. The button sends the action to the server, where a built-in handler, a bound automation script, or both (the script runs in addition) do the work.
• No handler is not an error. A server action with no built-in handler and no bound script succeeds and changes nothing. "The button does nothing" almost always means the script is bound to a different name. Scripts bind on the Server Action Name (or the Name when that is blank), so renaming either moves the binding.
• Background execution. When an action runs in the background, the user sees a processing window with the action's progress and output. Closing it does not stop the job. It ends with a link to the result, or with the error and a Retry button — retries are always manual. While the job runs the document is locked: its header shows Processing, and edits, deletes, other actions and its lines are greyed out with "Being processed". The page unlocks by itself when the job ends. A save that still reaches the server is refused with "This document is being processed (job …). Try again when it finishes." On mobile, an offline change to a locked document waits in the sync queue as "Waiting — document is being processed" and goes through once the job ends.
• One create button per list. A list without a record type shows only the New actions with no record type; a list for one record type prefers that type's New. An entity whose only New actions are type-scoped therefore shows no New on a cross-type list — add one with a blank Record Type.

Field mappings

A field mapping copies a value from a related record into this record: pick an item on a line and its price fills in, pick an account and its region lands on the claim.

Field mapping fields

The Copied from this record tab lists the reverse view: mappings that copy from this entity into a record one of its lookups points at, or into its child records. Choose New there and pick Copy into, From this record's field and Into field.

How field mappings behave

• At creation, on the server. When a record is created with the lookup set, the server loads the source record and copies the value. The mapped value overwrites whatever the creator entered, so never map onto a field users are expected to type into.
• Not again on their own. Changing the lookup on an existing record does not re-copy. To re-copy on change, add a business rule with the Apply Field Mappings action; push mappings and copies into child records run only through a Push Field Mappings rule.
• Best effort. A mapping that cannot apply — empty lookup, source record or field missing, record type not matching — is skipped without an error. A source value that is empty is copied as empty.
• On the form. Whether a New form shows mapped values before you save depends on the layout: a layout that refreshes the form from the server when the lookup changes fills them at once, filling only fields that are blank or were filled automatically. An Edit form never applies mappings.
• No loops. Mappings that would copy a field into itself, directly or through other mappings, are refused ("Circular field mapping not permitted …").

Lookup filters

A lookup filter restricts what a lookup field's picker offers: only active accounts, only items of the record's own category, only warehouses in the user's business unit.

Lookup filter fields

The Filter Builder. The Builder tab is a table of conditions (Field, Operator, Value) with an AND/OR toggle, Add Condition and Add Group. A value can be a literal, or come from Record Entity (the current record's in-form value), Related Entity (a field one relationship away from the current record) or User (the signed-in user, such as their business units). The Advanced tab shows the raw expression; its Validate button runs the same check the picker runs and names the offending part. Editing the text by hand keeps it as written.

How lookup filters behave

• Live. The filter is evaluated every time the picker searches, with the record's current values, so "accounts in the same region as this claim" follows the form as the user fills it in.
• One active filter per lookup and record type. Saving a second active filter for the same lookup and record type is refused ("Duplicate Value"). At run time a filter for the record's own type wins over one with no record type.
• The picker only. A lookup filter does not stop an API write, an import or an integration from setting any record. When the restriction is a business requirement, back it with a validation or business rule.
• Empty pickers. A reference that cannot be resolved (a misspelled field on the current record, a path deeper than one relationship) matches nothing, so the picker comes back empty with no error. Use Validate before saving and test with a record that should match.
• The target's Search view also applies (see Views). A filtered Search or All view on the target entity can hide records your lookup filter allows.

Field dependencies

A field dependency narrows a picklist's values: choose "Hardware" in Category and Subcategory offers only hardware subcategories.

Field dependency settings

How field dependencies behave

• On the form. The dependent picklist offers only the allowed values. With the picklist shape, changing the controlling field clears a dependent value that is no longer allowed; with the condition shape this happens only under Auto-clear.
• On the server, at every save. Block rejects the save with "Field: "value" is not available for the current values on this record."; Auto-clear removes the value (a multi-select keeps its allowed values); Warn lets the save through and only records it. This applies to API and import saves as well as forms.
• Existing data is left alone. On an edit, a value that was already there and that the save did not touch does not block the save, even if the dependency no longer allows it.
• After business rules. Enforcement runs after business rules, so it judges the values a rule set in the same save.

The separate Field dependencies page under Setup → Platform → Monitoring is unrelated: it reports the where-used index of fields, not dependent picklists.

Example

An operations team adds a custom Site Visit entity with a Category and a Subcategory picklist, a Customer lookup to Account and a Region field.

1. View. Under Experience → Views they create Open Site Visits, View Type List, filter Status_c != "Closed" (custom fields carry the _c suffix in conditions), then use Manage Columns to show Visit Number, Customer, Category, Visit Date (sorted newest first). They bind it under Experience → Defaults.
2. Field mapping. Destination Field Region, Source Entity Account, lookup Customer, Source Field Region. A visit created for an account in "West" gets Region "West".
3. Lookup filter. On Customer, the condition IsActive == true keeps inactive accounts out of the picker.
4. Field dependency. Subcategory depends on Category: Hardware → Printer, Laptop; Network → Router, Cabling. Changing Category from Hardware to Network on the form clears Laptop.
5. Validation. Severity Error, Error Location Field, Target Field Visit Notes, condition Status_c == "Closed" && (VisitNotes_c == null || VisitNotes_c.Trim() == ""), message "Add visit notes before closing the visit." Closing a visit with blank notes is rejected with that message under Visit Notes.
6. Action. A Print action on Entity (Detail) with the visit report as Print layout gives each visit a Print button.

Training

Practice exercise

In a sandbox, on any custom entity with a lookup to Account and a picklist field:

1. Create a lookup filter that offers only active accounts. Expected: an inactive account no longer appears in the picker.
2. Create a validation with Severity Warning whose condition is true when the picklist is blank. Expected: a save with the picklist blank is rejected with your message — confirming that Warning also blocks.
3. Create a field mapping that copies the account's phone into a text field, then create a record. Expected: the field is filled. Change the account on the saved record. Expected: the field does not change.
4. Deactivate the validation and save the blank record again. Expected: it saves.

Quick reference

• Everything lives on the entity: Setup → Design Studio → Entities → entity.
• A validation condition is true when the record is wrong.
• Any active, violated validation rejects the save — whatever the Severity.
• Save order: field mappings → validations → business rules → field dependencies.
• Mappings copy at creation; re-copy with an Apply Field Mappings rule.
• Lookup filters shape the picker only; field dependencies are enforced at save.
• One active lookup filter per lookup and record type.
• A server action with no handler and no script does nothing — check the binding.
• Columns and sort are set with Manage Columns, not in the view dialog.
• Deactivate rather than delete.

Permissions

• Configuring any of the six surfaces needs setup.metadata.model.manage. Without it, Entities does not appear under Design Studio.
• Binding a script to a server action also needs setup.automation.scripts.manage.
• Using them follows the user's data permissions: a user sees the views and actions of the entities they can read, and the New, Edit and Delete buttons follow their create, edit and delete rights on the entity. An attachments button follows the user's read right on the record.
• Running a background action's Retry from the document needs the right to run that action on the record.

Configuration

• Default list per app, record type or platform: Experience → Defaults, slot List view.
• Show a view or a list-header action in some apps only: the view's or action's Show in apps panel; a view can also limit which list-header actions show per app.
• Mobile list behavior: the view's Mobile list panel (grouping) and Design Card (card, filter pills, row indicators).
• Hide New on mobile: the New action's Show on mobile switch.
• Background threshold: the server action's Execution and Background above (lines).
• Re-copying mapped values or pushing them onward: business rules with Apply Field Mappings or Push Field Mappings — see business rules.
• Where the logic runs and in what order: Logic → Execution Plan.

Common problems

I can't edit or delete a standard view, validation or action

Rows marked Standard in the Source column come from the platform or an installed package. When standard metadata is locked for your tenant, only their active and default settings can change. Clone the row, change the copy, then deactivate the original.

My Warning validation stops the save

Every violated validation rejects the save, whatever its Severity. To inform without blocking, use a business rule instead, or deactivate the validation.

My validation never fires

The condition probably cannot be evaluated — a misspelled field name, a picklist compared with its label instead of its stored value, or an invalid string escape — and a broken condition is treated as not violated. Check field names and stored values, and on an edit remember the rule re-checks only when a field it reads changed.

The button does nothing

The server action has no built-in handler and no script bound to its Server Action Name. Bind the script to that exact name, or correct the name.

"This document is being processed"

A background action is still running on the document. Open View progress in the header, wait for it to finish, or use Retry if it failed. The document unlocks by itself.

The lookup picker is empty, or a record I expect is missing

Check the lookup filter's condition with Validate; an unresolved reference matches nothing. Then check the target entity's Search view — a filtered Search or All view hides records the lookup filter allows.

"Duplicate Value" when I save a lookup filter

Another active filter already covers the same lookup and record type. Deactivate one of them; only one can be active.

The mapped field did not fill in

The lookup was empty at creation, the source record or field was missing, the record type did not match, or the record already existed — mappings do not re-run when the lookup changes. Add an Apply Field Mappings business rule for the change path.

"Only one mapping allowed per destination field"

The destination already has a copy-in mapping. Edit that mapping instead of adding a second.

"… is not available for the current values on this record."

A field dependency set to Block rejected a dependent value that the controlling value does not allow. Pick an allowed value, or change the dependency's values or rules.

Common questions

When do I use a validation and when a business rule?

Use a validation for a self-contained check on the record being saved — a format, a range, a required combination, a forbidden change through PRIORVALUE — where a condition and a message are the whole requirement. Use a business rule when you need a trigger (only on create, only when a field changes), conditionally required or read-only fields, derived values or follow-up work. Remember that validations run before business rules, so a validation cannot rely on a value a rule sets in the same save.

Can I rely on a lookup filter or field dependency for data integrity?

A lookup filter, no: it shapes the picker, and API writes, imports and integrations can set any record. Back it with a validation or business rule. A field dependency set to Block is enforced by the server on every save, including API and import saves, so it does protect the data — but values already stored before it existed stay as they are until someone changes them.

Why did my field mapping not update the record when I changed the lookup?

Mappings copy at creation only. Re-copying when the lookup changes is left to a business rule with the Apply Field Mappings action, where you decide the trigger and whether existing values may be overwritten. Keep the mapping for the create path and add the rule for the change path when both matter.

What do these settings change in the mobile app?

Views shape the mobile lists: the view's Design Card draws the list cards, its Mobile list panel groups rows under collapsible headings, and filter pills added in the card designer appear under the list header — none of these change the web list. A list-header New action shows as the + New button unless its Show on mobile switch is off. Validations, field mappings and field dependencies run on the server, so they apply to a save from the app once it reaches the server, exactly as they do for the web.

Related topics

• The data model
• Create an entity
• Business rules
• Expressions
• What runs when you save a record
• Automation scripts
• Approvals
• Design a form layout