---
title: "Creating and Displaying Entities"
slug: "creating-and-displaying-entities"
updated: 2026-09-02T18:31:47Z
published: 2026-09-02T18:31:47Z
canonical: "knowledge.technolutions.net/creating-and-displaying-entities"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.technolutions.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating and Displaying Entities

Creating and displaying an entity for data collection takes five steps:

1. Create the entity object.
2. Create entity-scoped fields.
3. Refresh the Configurable Joins library.
4. Create an entity-widget-scoped form to collect data. Add your **Custom List Fields** in **Edit Properties** on this form.
5. 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.

> [!NOTE]
> 🔑 Required permissions
> 
> **Database**: 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.
> 
> See [Entity Permissions](/v1/docs/entity-permissions) for additional information on permissions for adding and editing entity rows.

📖 Further reading: [Entities Overview](/v1/docs/entities-overview), [System Permissions](/v1/docs/system-permissions), [Using Datasets vs. Entities](/v1/docs/using-datasets-vs-entities)

## Step 1: Create the entity

To create the entity object:

1. From the main navigation, select **Database**.
2. In the **Records and Datasets** section, select **Entities**.
3. Select **Insert**.
4. 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](/v1/docs/entities-overview) for more information.
5. Select **Save**.

[![The Insert Record in Entities popup, showing an entity named Scholarships with the Person and Application scopes.](https://cdn.us.document360.io/cd8ea7a6-07f3-4846-a554-627ac016d3e3/Images/Documentation/9989224990875.png?sv=2026-02-06&spr=https&st=2026-11-08T04%3A30%3A45Z&se=2026-11-08T05%3A30%3A45Z&sr=c&sp=r&sig=aqMzmaKTPq6z9kcipQpVTO3LKrG9AdNJ5LjoWzs4aDw%3D)](https://cdn.us.document360.io/cd8ea7a6-07f3-4846-a554-627ac016d3e3/Images/Documentation/9989224990875.png?sv=2026-02-06&spr=https&st=2026-11-08T04%3A30%3A45Z&se=2026-11-08T05%3A30%3A45Z&sr=c&sp=r&sig=aqMzmaKTPq6z9kcipQpVTO3LKrG9AdNJ5LjoWzs4aDw%3D)

## Step 2: Create the entity-scoped fields

Each data point you want to store requires its own [custom field](/v1/docs/field-editor).

To create entity-scoped fields:

1. From the main navigation, select **Database**.
2. In the **Records and Datasets** section, select **Fields**.
3. Select **New Field**.
4. Configure the following settings:
  - **Status**: Active
  - **Scope Category**: Related
  - **Scope**: Select the new entity.
5. Configure the remaining settings as needed. 📖 Further reading: [Fields Settings](/v1/docs/fields-settings)
6. Select **Save**. Repeat for each field the entity needs.

[![The Edit Field popup with Scope Category set to Related and Scope set to the Scholarships entity, creating a Scholarship Amount field.](https://cdn.us.document360.io/cd8ea7a6-07f3-4846-a554-627ac016d3e3/Images/Documentation/9989501716379.png?sv=2026-02-06&spr=https&st=2026-11-08T04%3A30%3A45Z&se=2026-11-08T05%3A30%3A45Z&sr=c&sp=r&sig=aqMzmaKTPq6z9kcipQpVTO3LKrG9AdNJ5LjoWzs4aDw%3D)](https://cdn.us.document360.io/cd8ea7a6-07f3-4846-a554-627ac016d3e3/Images/Documentation/9989501716379.png?sv=2026-02-06&spr=https&st=2026-11-08T04%3A30%3A45Z&se=2026-11-08T05%3A30%3A45Z&sr=c&sp=r&sig=aqMzmaKTPq6z9kcipQpVTO3LKrG9AdNJ5LjoWzs4aDw%3D)

### 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](/v1/docs/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](/v1/docs/updating-slate-data-with-an-exportimport-process) populates the data, you can use each row’s GUID for matching instead.

> [!CAUTION]
> 🔔 Important: Unique for merging collapses every row that shares a value
> 
> Slate 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](/v1/docs/unique-for-merging)

> [!NOTE]
> 💡 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](/v1/docs/refreshing-the-quartet).

## 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:

1. From the main navigation, select **Database**.
2. In the **Queries** section, select **Refresh Configurable Joins Library**.

## Step 4: Create an entity widget form

To create an entity widget form:

1. From the main navigation, select **Forms**.
2. 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.
3. Select **Save**.
4. Select **Edit Form**.
5. Select **Edit Properties**.
6. 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.
7. Select **Save**.
8. 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.

[![The Edit Properties popup for an entity widget form, with Scope set to Entity Widget and Entity set to Scholarships. Under Custom List Fields, three exports appear: Scholarship Name, Scholarship Amount, and Scholarship Status.](https://cdn.us.document360.io/cd8ea7a6-07f3-4846-a554-627ac016d3e3/Images/Documentation/9989625201947.png?sv=2026-02-06&spr=https&st=2026-11-08T04%3A30%3A45Z&se=2026-11-08T05%3A30%3A45Z&sr=c&sp=r&sig=aqMzmaKTPq6z9kcipQpVTO3LKrG9AdNJ5LjoWzs4aDw%3D)](https://cdn.us.document360.io/cd8ea7a6-07f3-4846-a554-627ac016d3e3/Images/Documentation/9989625201947.png?sv=2026-02-06&spr=https&st=2026-11-08T04%3A30%3A45Z&se=2026-11-08T05%3A30%3A45Z&sr=c&sp=r&sig=aqMzmaKTPq6z9kcipQpVTO3LKrG9AdNJ5LjoWzs4aDw%3D)

## 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.

> [!TIP]
> ✅ 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](/v1/docs/custom-tabs) 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.

> [!WARNING]
> 📝 Note: Identifying the owner record
> 
> Entity 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](/v1/docs/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](/v1/docs/default-information-required-fields)

### Option A (recommended): Embed an entity widget

Embed the entity widget form in a [custom tab](/v1/docs/custom-tabs) or inside a Slate application:

1. On the **Forms** summary page, open the form you want to edit.
2. Select **Edit Form**.
3. Select **Widget Table** from the form builder palette. An **Edit Field** popup appears.
4. Configure each setting as needed. 📖 Further reading: [Fields Settings](/v1/docs/fields-settings)
5. Select **Save**.

![A screenshot of the form builder interface, showing the widget table palette item and "Widget Form" setting with 'Scholarships - Scholarship Entity Widget' selected.](https://cdn.us.document360.io/cd8ea7a6-07f3-4846-a554-627ac016d3e3/Images/Documentation/image-W8KO093M.png?sv=2026-02-06&spr=https&st=2026-11-08T04%3A30%3A45Z&se=2026-11-08T05%3A30%3A45Z&sr=c&sp=r&sig=aqMzmaKTPq6z9kcipQpVTO3LKrG9AdNJ5LjoWzs4aDw%3D)

### 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:

1. Add a field from the form builder palette.
2. Select the entity in the **System Field** list and the entity-scoped field from the second **System Field** list.
3. Configure each setting as needed. 📖 Further reading: [Fields Settings](/v1/docs/fields-settings)
4. Repeat for each additional entity-scoped field you want to collect and display.

![The Edit Field popup for a mapped form field, with the two System Field lists set to the Scholarships entity and the Scholarship Name entity-scoped field.](https://cdn.us.document360.io/cd8ea7a6-07f3-4846-a554-627ac016d3e3/Images/Documentation/image-7DOHKX9E.png?sv=2026-02-06&spr=https&st=2026-11-08T04%3A30%3A45Z&se=2026-11-08T05%3A30%3A45Z&sr=c&sp=r&sig=aqMzmaKTPq6z9kcipQpVTO3LKrG9AdNJ5LjoWzs4aDw%3D)

To let a single form submission add more than one entity row, place the mapped fields inside a [replicate block](/v1/docs/replicate-blocks). 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.

A **globally-unique identifier**, or one-of-a-kind ID that can be used to identify a record or object in your Slate database.

Replicate blocks allows for ordered data to be captured on a form in a specified section.