Skip to content

Setting Up Entities and Schemas

Before You Begin

  • You need a DFC permission level that allows creating entities and editing schemas (Entity Editor or Admin) to create entities, sub-entities, and define schemas. Adding items requires at least Item Creator. See Managing DFC Permissions.
  • Plan your schema before adding items. Once items populate a field with data, the field's name and type are locked and the field can't be deleted.

Warning

In most setups, schema changes are owned by admins and technical users. Fields\ cannot be deleted or renamed while sub-entities or items exist inside the entity. Plan fields carefully\ before adding items or sub-entities.

Limits and Constraints

  • Primary key required. Each schema must define a required primary key. The first field you add to a new schema is always created as the primary key — required and locked to type String. If a schema somehow has fields but no primary key, Save Changes shows: "Every Entity needs one Primary field to save. Open a String field and turn on "Primary Key"."
  • No slash in primary key values. Primary key values must not contain a slash (/). Because DFC\ resolves paths using the format /path/to/entity/, a slash in a primary key value would be interpreted as an additional path segment, causing the query to fail.
  • Fields lock once items hold data. When existing items populate a field, the field's name and type are locked and the field can't be deleted. To rename or delete the field, remove the item data first.
  • Schemas are long-lived. Design them carefully before use.
  • Defaults fall back to null. If no defaults are configured for an entity, all fields return null when the entity is queried with a trailing slash.
  • Sub-entity depth (recommended). Limit sub-entities to no more than five levels deep to improve\ clarity, reuse, and query performance. See DFC Best Practices.
  • Import performance. A 1 MB import file typically completes in approximately two minutes; import\ time depends on file size.

Step-by-Step Instructions

Create an Entity

An entity is a top-level container for a category of data. Each entity has a name and description, a defined schema, one or more items, and can include sub-entities. Common examples of entities include:

  • Closure — Ad-hoc / emergency closures (unplanned).
  • Schedule — Weekly operating hours (hours of operation).
  • Prompts — A named set of message slots (welcome, first question, out-of-hours).
  • Language — A supported language: locale, Polly voice, and language-specific settings. A managed lookup, not a hardcoded list.
  • AI Agent Config — AI / self-service configuration: assistant, agent, and Lex bot ARNs, plus a Knowledge Base reference.
  • Holidays — Closures known in advance (Christmas, New Year, national holidays).
  • Experience Config — The reusable bundle of behaviour for a contact (language, prompts, hours, routing, AI). The hub of the model.
  • Contact Source — A channel entry point (phone number, chat widget, email address) mapped to an Experience Config.
  • Routing Destination — Where a contact is sent: a queue, external number, voicemail, contact flow, or disconnect.
  • Knowledge Base — A knowledge base pointer (id, region). The simplest entity — fields only, no references.

To create an entity:

  1. In the left panel, select Home (root).
  2. Click + Entity.
  3. Choose a starting point:
    • Start from scratch — an empty entity. You add its fields yourself in Settings.
    • A template — an entity with its fields already set up. Each template card shows its name, description, and number of fields.
  4. Click Continue.
  5. Enter an entity name and entity description. If you chose a template, its description is filled in for you, and the fields the template adds are listed below.
  6. Click Create Entity.

After creation, the entity appears in the left panel and, if the change was applied straight away (not scheduled or sent for approval), DFC opens it. A confirmation message displays: "Entity has been created successfully."

Entity names must be unique at their level. If an entity with the same name already exists, the form shows "An entity with this name already exists here." and you can't create the entity until you change the name.

Some template fields reference other entities. DFC links each one to your existing top-level entity of the same name, and the form lists which entities it linked to. If there's no matching entity yet, that field is left out — create the missing entity first, or add the field later in Settings. If templates can't be loaded, you can still start from scratch.

Note

Entities cannot be deleted until all sub-entities and items under them are removed first. Deleting an entity is permanent.

Create a Sub-Entity

1. Select a parent entity in the left panel.

2. Click + Entity (displayed next to the parent entity name).

3. Enter a entity name and entity description.

4. Click Create Sub-Entity.

Sub-entity names must be unique under the same parent. If the name is already in use, the form shows "A sub-entity with this name already exists here."

The sub-entity inherits the parent entity's schema automatically. Inherited fields cannot be modified at the sub-entity level, but you can add additional fields to the child entity.

Deleting an Entity

Delete an entity from its Entity Settings page once it's empty.

  1. Select the entity and click the Settings (gear) icon.
  2. Click the More (ellipsis) menu next to the Details header.
  3. Select Delete Entity.
  4. In the Are you sure? confirmation, confirm the deletion.

Danger

Deleting an entity is permanent. Delete Entity is disabled while the entity still has items or sub-entities — the menu explains why. Remove them first.

Define the Schema

Before adding items, configure the entity's schema. Schema edits accumulate as a draft on the Entity Settings page and are submitted together as one change request.

  1. Select the entity and click the Settings (gear) icon. The Entity Settings page opens with the DFC breadcrumb at the top, the entity's Details on the left, and the Schema field list on the right. The Details panel also lists the Roles tagged on this entity — see Managing DFC Permissions.
  2. Click Add Field — for the very first field on a new schema, this button instead reads Add Primary Key.
  3. Enter a Name. The Add button stays disabled until you do.
  4. Select a Type from the alphabetical list. For the first field, Type is locked to String — the popover explains that the primary key must be a required String and can't be changed later.
  5. Configure the field settings:
Name The field name.
Type String, Number, Boolean, Reference, Multi-Reference, Datetime, JSON, YAML, Amazon Connect Resource, Agentic CX Application, Pick List, or Prompt.
Required Whether the field must be set for every item.
Primary Used as the item's unique identifier (required for at least one field).
Overridable Whether items or sub-entities can override the default value.
Hidden Show or hide the field in API responses.
Presentable Show or hide the field in the UI as a column.
Constraints

Type-specific constraints such as minimum and maximum length for strings.

For string fields, the maximum length must be at least 1 and greater than or equal to the minimum. Required string fields need a minimum length of at least 1; optional string fields can use a minimum length of 0.
Conditions Conditional display rules based on pick list values.
  1. Repeat steps 2–5 for each field. Edits apply to your draft automatically — there's no per-field save.
  2. (Optional) Reorder fields:\ a. Hover over a field row. A drag handle appears at its left end.\ b. Drag the row to its new position.
  3. Click Save Changes.
  4. Complete the change request modal to submit your schema changes for approval.

Once you make an edit, a "You have unsaved changes" indicator appears with a Discard Changes action that reverts every pending edit. After you submit, newly added fields stay visible in the list, marked as pending until the change request is approved.

Warning

Save Changes is disabled while a field has a validation error. The field's row flags the error, the affected input is outlined red, and the error message appears directly under that input.

Configuring a Reference Field

When you set a field's Type to Reference, specify the path to the referenced entity. The dropdown shows available items from that entity, and a preview displays the evaluated reference data. Only items (not entities) can be selected in reference fields.

Configuring a Multi-Reference Field

A Multi-Reference field works like a Reference field, but one item can link to several items instead of one. When you set a field's Type to Multi-Reference, select the base Entity in the Multi-Reference constraints panel. Any item under the selected Entity (or its children) can be referenced, and an item can reference several of them.

To fill in a Multi-Reference field on an item:

  1. Click the field's dropdown. Until you pick something, it reads Select, the field's name, and an ellipsis. After that, it shows how many items are selected (for example, 3 selected).
  2. On the All tab, check the items you want. Click a sub-entity under Sub-Entities to browse its items, and use the back button at the top of the list to return to the parent.
  3. (Optional) Open the Selected (N) tab to review your picks, and uncheck any you don't want. The search box filters whichever tab is open. Click Clear all to remove every selection.

The selected items appear as chips below the field. Click a chip's name to open that item in a new tab, so you don't lose your in-progress edit, or click its x to remove it.

A Multi-Reference field holds at most 100 items. Once 100 are selected, the remaining items can't be checked and the dropdown shows The maximum of 100 items is selected. The same item can't be selected twice, and a required Multi-Reference field needs at least one item before you can save.

In the items table, a Multi-Reference column lists the referenced items' primary keys, separated by commas. A CSV export writes the same comma-separated list. Multi-Reference fields can be filtered, sorted, and bulk edited like other fields.

Configuring an Agentic CX Application Field

An Agentic CX Application field stores the three IDs an Agentic CX flow block routes to: a Workspace ID, an Application ID, and an Alias ID. The type needs no extra configuration — its constraints panel only describes what the field stores. Copy the IDs from the Agentic CX flow block's application settings.

  • Workspace ID and Application ID must each be a UUID, for example 67898477-f36f-4b06-bdca-0d9a1f2eb9cc. Enter the ID, not an ARN — a value beginning with arn: is rejected with "must be an ID, not an ARN".
  • Alias ID must be 256 characters or fewer and cannot contain spaces.

All three IDs are needed once any one of them is filled in. Clearing all three empties the field, which saves only if the field isn't required. Each ID gets a copy button once it holds a value.

You're responsible for these IDs being correct. DFC only checks their format, and a wrong ID sends contacts down the Agentic CX flow block's Error branch. The same warning is available in the UI from the information icon beside the field's help text.

In the items table the field shows the application and alias IDs separated by a slash, falling back to the workspace ID. A CSV export writes all three on separate lines, labeled Workspace:, Application:, and Alias:.

Field types list

Available field types: Agentic CX Application, Amazon Connect Resource, Boolean, Closure, Date Time, Hours of Operation, JSON, Multi-Reference, Number, Pick List, Prompt, Reference, String, YAML.

For editing a Prompt field's SSML content, see Editing Prompt Fields.

The Amazon Connect Resource type lets you select from the following resource types:

• Queue • Contact Flow • Contact Flow Module • Prompt • Phone Number • Lex Bot

Setting defaults: For each field, you can add a default value and mark it Overridable if items are allowed to override it.

Warning

Warning: Fields lock once items hold data. When existing items populate a field, the field's Name and Type are locked (shown with a lock icon and an explanation) and Delete Field is disabled with a tip explaining why.

This locking applies only to fields that were already saved before the current editing session. A field you add in the current session — even on an entity that already has items — stays fully editable, including its Name and Type, until you save. To rename or delete a previously saved field, remove the item data first. Since schemas are long-lived, design them carefully before use. Fields added during the current editing session can always be removed — use the field's Delete Field button, or Discard Changes to revert everything.

Add Items (Records)

Once the schema is ready:

  1. Return to the entity view.
  2. Click + Item.
  3. Fill in the item fields according to the schema.
  4. Click Create Item.

Items appear in the table immediately. Opening an item's editing tray shows its Item ID next to the entity name — click it to copy the ID to your clipboard.

A Pick List field that allows multiple selections starts with nothing selected. If that field isn't required, you can leave it empty and still save the item — the item is saved with no value for the field. A required Pick List still needs at least one option selected before you can save.

Warning

Item changes are submitted as change requests and take effect once approved. Avoid creating or deleting items in shared environments unless instructed.