Creating and displaying an entity for data collection takes five steps:
Create the entity object.
Create entity-scoped fields.
Refresh the Configurable Joins library.
Create an entity-widget-scoped form to collect data. Add your Custom List Fields in Edit Properties on this form.
Embed the entity-widget-scoped form onto an Application Page, Person Page, Slate-Hosted Application Page, or Dataset Page scoped form, using the Widget Table from the form builder palette. These are the only scopes that can host an entity widget.
Before you begin
Decide which record the entity data belongs to: a person, application, or dataset record. Step 1 asks for this as the entity scope, and it determines where you can collect and display the data afterward.
🔑 Required permissionsDatabase: create the entity, create entity-scoped fields, and refresh the Configurable Joins library.
Forms: create the entity widget form and embed it on a host form.
These permissions cover building the entity. See Permissions for editing entity data before you decide where this data should live.
Step 1: Create the entity
To create the entity object:
From the main navigation, select Database.
In the Records and Datasets section, select Entities.
Select Insert.
Configure the following settings:
Status: Active
Folder: Place the entity in a folder to keep entities organized, or select Other to create a new folder.
Name: Give the entity a memorable, descriptive name.
Scope Insert: Select each scope that applies to this entity. See the Entities Overview for more information.
Select Save.
Step 2: Create the entity-scoped fields
Each data point you want to store requires its own custom field.
To create entity-scoped fields:
From the main navigation, select Database.
In the Records and Datasets section, select Fields.
Select New Field.
Configure the following settings:
Status: Active
Scope Category: Related
Scope: Select the new entity.
Configure the remaining settings as needed. 📖 Further reading: Fields Settings
Select Save. Repeat for each field the entity needs.
Use Unique for Merging to update existing rows
By default, each submission adds a new entity row. To let a submission update an existing row instead, designate a field as unique for merging, and include that field wherever you collect this data. Some examples of useful unique for merging fields include:
A unique ID (for example, from an external system)
A concatenated field (for example, data from two custom entity fields)
If only an import and export process populates the data, you can use each row’s GUID for matching instead.
🔔 Important: Unique for merging collapses every row that shares a valueSlate merges every entity row that shares the same unique for merging value. A field such as first name, class term, or satisfaction rating repeats across rows by design. Choosing one as a unique for merging field collapses those rows into a single row. Pick a field whose value belongs to exactly one row.
📖 Further reading: Unique for Merging
💡 Tip: Refresh the field cache
New fields become available on forms after the cache refreshes, about every five minutes. To use them right away, select Database → Fields, and then select the force-refresh link. See Refreshing Field and Prompt Caches.
Step 3: Refresh the Configurable Joins library
Slate generates query exports and filters for new fields during the overnight process. Refreshing the library runs that process on-demand, so the entity-scoped fields you just created are available immediately.
To refresh the Configurable Joins library:
From the main navigation, select Database.
In the Queries section, select Refresh Configurable Joins Library.
Step 4: Create an entity widget form
To create an entity widget form:
From the main navigation, select Forms.
Select New Form. Configure the following settings:
Page Title: Add a name for the form.
Status: Confirmed/Active
Configure the remaining form settings as needed.
Select Save.
Select Edit Form.
Select Edit Properties.
Configure the following settings:
Scope: Entity Widget
Entity: Select the new entity.
Custom List Fields: Select Export. Select the entity-scoped fields you created earlier. These exports define the columns that appear wherever you embed this form, such as on application pages. Add filters and sorts as needed.
Select Save.
Use the form builder palette to add the entity-scoped fields to the form. These fields hold the data you collect and store for each entity row: for example, Scholarship Name, Scholarship Account, Scholarship Approved, and Scholarship Amount.
Step 5: Embed the entity widget form
Choose a method
There are two methods to collect entity data on a form. Both methods collect entity data and display it on the record that owns it. They differ in which forms you can use them on, and in how many entity rows a single submission can add.
Use Option A on a page form, scoped to an Application Page, Person Page, Slate-Hosted Application Page, or Dataset Page. The entity widget nests a second form inside the host form, so a single submission can add several entity rows. Prefer this method wherever it's available.
✅ Best practice: Embed the entity widget in a custom tab to view its data
Follow the instructions for Option A to add your entity widget to a custom tab first. You can then view and validate entity data directly from the record that owns it, and add new rows from the same place.
Use Option B when the form has any other scope. Mapping fields directly works on a form of any scope, which is what makes it useful. It collects only one entity row per submission, unless you add a Replicate Block.
📝 Note: Identifying the owner recordEntity data attaches to the record that owns it. When someone completes the form from inside a record or a signed-in application, the submission already carries its owner record. The form doesn't have to ask for it.
When anyone can open the form and fill it out, the submission has to identify the record on its own:
Person-scoped forms: collect enough data to match a person, typically First Name, Last Name, and Email.
Dataset-scoped forms: collect a unique for merging field defined for that dataset. Datasets don’t match on name and email like person records, unless you defined those fields as unique for merging.
Without identifying criteria, the entity data typically won’t match to a record.
📖 Further reading: Default Information / Required Fields
Option A (recommended): Embed an entity widget
Embed the entity widget form in a custom tab or inside a Slate application:
On the Forms summary page, open the form you want to edit.
Select Edit Form.
Select Widget Table from the form builder palette. An Edit Field popup appears.
Configure each setting as needed. 📖 Further reading: Fields Settings
Select Save.
Option B: Map individual fields on a form without a widget
Instead of embedding the widget, map each entity-scoped field onto the form individually:
Add a field from the form builder palette.
Select the entity in the System Field list and the entity-scoped field from the second System Field list.
Configure each setting as needed. 📖 Further reading: Fields Settings
Repeat for each additional entity-scoped field you want to collect and display.
To let a single form submission add more than one entity row, place the mapped fields inside a replicate block. Option A doesn't need one because the entity widget already accepts multiple rows.
Test your work
Submit the form for a test record. Confirm that the entity data appears on the record you expected, and that each entity-scoped field holds the value you submitted.
If the submission saved but nothing appears on the record, check that the form collected enough information to identify the owner record.
Permissions for editing entity data
Different permissions govern building an entity and editing its data. The permission a user needs to add or edit an entity row depends on the entity's scope. Plan for this before you decide that a particular set of data belongs in an entity.
📝 Note: The required permission follows the entity's scope
Person-scoped and dataset-scoped entities: Person Update. Dataset Update alone doesn't let a user add or edit rows in a dataset-scoped entity.
Application-scoped entities: Application Update.
Grant the permission directly or through a role.
Population permissions don't enable entity editing at any scope.
Permissions set on the entity widget form, the host form, or the record tab don't control who can edit entity data. Users still need the Person Update or Application Update permissions.
Entity permissions add a dedicated write permission to each entity, so you can control who edits one particular entity. This permission works alongside the update permission for the entity's scope rather than replacing it: a user needs both to submit changes.
A user who lacks the required permissions can still open an entity form and change the values in it. An error appears when they try to submit.
If the people who should maintain this data shouldn't have Person Update or Application Update, an entity may be the wrong structure for it. A custom dataset stores comparable data as records with their own permissions.