---
title: "Custom entities"
slug: "custom-entities"
updated: 2025-09-30T14:37:04Z
published: 2025-10-03T07:52:57Z
canonical: "documentation.deltatre.com/custom-entities"
---

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

# Custom entities

In this article, we cover FORGE's capabilities for defining new and bespoke custom entities to build content faster.

---

## Out-of-the-box entities

FORGE provides the editorial teams with the following entities:

- **Story**: Together with photos, stories are the main building blocks to assembling content. A story is a collection of story parts, which can be either text or any other type of editorial entity.
- **Photo**: The other main building block that, with stories, makes up the content. FORGE relies on Cloudinary for photos storage: [all formats Cloudinary supports](https://cloudinary.com/documentation/image_transformations#supported_image_formats), FORGE supports. [Size limits depend on the Cloudinary paid plan](https://support.cloudinary.com/hc/en-us/articles/202520592-Do-you-have-a-file-size-limit), which is a choice of the digital project based on FORGE.
- **Album**: A collection of photos.
- **Document**: Any file. Administrators configure the allowed file formats and sizes.
- **Editorial** **selection**: A collection of entities grouped‌ into an entity, which is called *editorial selection*. Editorial selections contain different editorial entity types. E.g., they collect stories, photos, and documents together.

## Custom entities

Administrators and producers can create custom entities and use them in stories and as items in editorial selections. These custom entities are not available out-of-the-box.

The following screenshot shows a list of possible custom entities:

![](https://cdn.document360.io/2e698e3c-4773-44a4-9476-1d05bac85eee/Images/Documentation/image(44).png)

### Permission-based visibility and management

For each custom entity *C*, a permission *Wcm.View.CustomEntity.C* exists that editors must have to see and use that specific custom entity in:

- Menus
- Lists

Editors need the additional permission *CanOperateOn.Wcm.C* to create, edit, and delete the custom entity *C*.

### Editorial workflow

Custom entities are published or unpublished in all languages, but editors can select ‌visibility per language. E.g., a published document can be visible in the front-end in English but not in French.

Find more details in [Translations with language-independent workflow](/v1/docs/translations-with-language-independent-workflow).

### User interface

Each custom entity has a dedicated overview page that editors can access by selecting its menu item in the left menu. See [Searching entities](/v1/docs/searching-entities) for more information about searching through custom entities, which work like ‌built-in entities.

E.g., in the screenshot below, there's the player's overview page:

![](https://cdn.document360.io/2e698e3c-4773-44a4-9476-1d05bac85eee/Images/Documentation/image(45).png)

By selecting *New* or a custom entity from the overview page, editors enter the custom entity edit page. E.g., in the screenshot below, there's the player's edit page:

![](https://cdn.document360.io/2e698e3c-4773-44a4-9476-1d05bac85eee/Images/Documentation/image-1757585159728.png)

Custom entities are made up of

- [Custom properties](/v1/docs/custom-entities#custom-properties): Custom fields that are specific to the custom entity.
- Built-in properties: Fields that custom entities share with built-in entities.
  - [Main properties](/v1/docs/custom-entities#main-properties)
  - [History](/v1/docs/custom-entities#history)
  - [General settings](/v1/docs/custom-entities#general-settings)
  - [Context and tags](/v1/docs/custom-entities#context-and-tags)
  - [Promotion](/v1/docs/custom-entities#promotion)
  - [Relations](/v1/docs/custom-entities#relations)

#### Custom properties

In the center, editors can fill in the entity-specific fields.

![](https://cdn.document360.io/2e698e3c-4773-44a4-9476-1d05bac85eee/Images/Documentation/17546860042780.png)

#### Main properties ![](https://cdn.document360.io/2e698e3c-4773-44a4-9476-1d05bac85eee/Images/Documentation/17546860045596.png)

Custom entity's built-in main properties are:

- **Thumbnail**: By default, it's the document file type icon. Editors can replace it with any photo.
- **Entity** code: Read-only unique entity identifier.
- **Slug**: Human-readable entity identifier. If the document isn't published, editors can edit it.
- **Content date**: By default, it's the publishing date. Editors can edit it.

#### History ![](https://cdn.document360.io/2e698e3c-4773-44a4-9476-1d05bac85eee/Images/Documentation/17546868971164.png)

Like for any entity, this section lists for each change who, what, and when.

#### General settings ![](https://cdn.document360.io/2e698e3c-4773-44a4-9476-1d05bac85eee/Images/Documentation/17546868973212.png)

Editors can select:

- **Authorization group**: Select the authorization group that editors must have to edit the document.
- **List availability**: Select whether the document must be included into lists that the front-end queries. See [List Availability](/v1/docs/list-availability) for more information.

#### Context and tags ![](https://cdn.document360.io/2e698e3c-4773-44a4-9476-1d05bac85eee/Images/Documentation/17546860051740.png)

Editors can select:

- **Context**: Text that appears above an article on the front-end. It's a small, but important piece of text which highlights the key features of the content.
- **Tags**: Document's taxonomy.

#### Promotion ![](https://cdn.document360.io/2e698e3c-4773-44a4-9476-1d05bac85eee/Images/Documentation/17546868979868.png)

Editors can promote the document's visibility by leveraging:

- **Feature the content**: Flag that makes a document featured. This flag informs the front-end that the document's visibility has a higher priority than not-featured ones.
- **Add to selections**: Add the document to one or many editorial selections.

#### Relations ![](https://cdn.document360.io/2e698e3c-4773-44a4-9476-1d05bac85eee/Images/Documentation/17546860056348.png)

Editors can relate the document to other entities regardless of their type.

### User interface configuration

In *Administration->Configuration->Custom Entities*, administrators can configure the custom entity user interface within the JSON definition by

- Grouping together fields into sections
- Positioning fields

#### Grouping together fields into sections

In the custom entity JSON schema, define the list of groups to display within the *groups* array at root level. The following parameters define a group:

- **key**: It identifies the group. It's used to assign a field to this group.
- **label**(optional): It's the group label the user interface displays.
- **icon**(optional): It's the group's icon code. Refer to [Google Fonts](https://fonts.google.com/icons) to search for icons and their codes.

For example, the JSON below defines two groups. The first group (*key* = *player-basics*) uses the icon with person_outline code. The second group doesn't have an icon.

```json
{
 ...,
 "groups": [
  {
   "key": "player-basics",
   "label": "Player",
   "icon": "person_outline"
  },
  {
   "key": "player-photos",
   "label": "Photos"
  }
 ]
}
```

Then, assign custom entity fields to groups by setting their *groupby* parameter with the group key.

For example, the JSON below assigns the *firstname* field to the *player-basics* group:

```json
{
 ...,
  "firstname": {
   ...,
   "groupBy": "player-basics",
   ...
 },
 ...,
 "groups": [
  {
   "key": "player-basics",
   "label": "Player",
   "icon": "person_outline"
  },
  {
   "key": "player-photos",
   "label": "Photos"
  }
 ]
}
```

#### Positioning fields

Administrators can span custom entity fields into 12 columns per row. For each field, the *columns* parameter defines how many columns the field spans. When the sum of the columns exceeds 12, the field displays in the next row.

For example, in the JSON below, fields *firstname*, *lastname*, and *dateOfBirth* are displayed in the same row (4+4+4 = 12) of the *player-basics* group:

```json
{
 "firstname": {
  ...,
  "groupBy": "player-basics",
  "columns": 4
 },
 "lastname": {
  ...,
  "groupBy": "player-basics",
  "columns": 4
 },
 "dateOfBirth": {
  ...,
  "groupBy": "player-basics",
  "columns": 4
 },
}
```

![](https://cdn.document360.io/2e698e3c-4773-44a4-9476-1d05bac85eee/Images/Documentation/17546860058396.png)

Instead, in the JSON below, fields *firstname*and *lastname*lays in the same row (6+6=12) of the *player-basics* group. In contrast, within the same *player-basics* group, *dateOfBirth* displays in the next row and spans the first 4 columns:

```json
{
 "firstname": {
  ...,
  "groupBy": "player-basics",
  "columns": 6
 },
 "lastname": {
  ...,
  "groupBy": "player-basics",
  "columns": 6
 },
 "dateOfBirth": {
  ...,
  "groupBy": "player-basics",
  "columns": 4
 },
}
```

![](https://cdn.document360.io/2e698e3c-4773-44a4-9476-1d05bac85eee/Images/Documentation/17546860059676.png)