Working with custom entities

Custom entities allow administrators to manage their structured datasets directly in Data Management. This makes it possible to extend the platform's data model with customer-specific data fields that are not covered by the data foundation.

As an administrator, you can create a new custom entity, define its fields and its interactions with other entities, publish it for use, upload data into it, and view that data in the Data Viewer. Worker-linked custom entities can also be used in supported configuration areas such as population-related scenarios, worker categories, snapshots, and the data modeler.

What is a custom entity?

A custom entity is essentially a custom table with its own fields and structure. It makes it possible to store, in a governed way, business data not covered out of the box by the application. It can represent an internal mapping table, an organization-specific reference dataset, a worker-related enrichment records, or additional criteria for segmentation or classification.

Unlike custom fields, which extend an existing standard entity, custom entities create an entirely new entity with its own schema.

Overview

This is a tip message.

The Custom Entities page is available under Workbench > Data Management > Field Management > Custom Entities. Access to Workbench depends on your role.

To create and use custom entities, you must have been granted the Data Foundation Admin or the Configuration professional role.

The Custom Entities page provides a centralized view of all custom entities and their current status. It consists of four main areas: summary tiles, search and filtering, the entity list, and actions.

The following picture presents the page:

Custom Entities in Data Management

At the top, four summary tiles give you a quick read on your configuration landscape, showing the total number of custom entities in the Total entities tile, as well as a breakdown by status: Active, Draft, and Deactivated (for more information, refer to the Custom entity lifecycle section.

Below the tiles, a dynamic search bar lets you filter the entity list by name as you type. The Status drop-down list complements the search, so besides the All (all entities) option, you can narrow the list to a specific state: Active (only published entities), Draft (only entities in configuration), and Deactivated (only inactive entities). This proves useful when reviewing draft configurations or focusing on active data structures only.

The main table displays all custom entities with their name, field count, and current status. Clicking an entity name opens the following details view:

Custom entity details

There, you can review:

• entity metadata:
  • Name
  • Description
  • Effective dating
  • Status
• field definitions:
  • Name: field identifier

• Type: data type (for example, Boolean or Entity reference)
• Default value: predefined value, if set
• Is required: whether the field must contain a value
• Is business key: whether the field is part of the entity’s business key

Additionally, you can scroll through pages and adjust the number of items per page using the pagination tool. For your convenience, the entities are ordered alphabetically by default.

Each table row also includes a three-dot icon. When you click it, a contextual menu is displayed, where actions depend on the current status of the entity:

Status	Actions
Draft	View Edit Delete Publish
Active	View Deactivate
Deactivated	No actions available

Custom entity lifecycle

Before creating and publishing a custom entity, it is important to understand its lifecycle, as it determines what you can do with an entity at any given point. Custom entities move through three statuses: Draft, Active, and Deactivated.

Lifecycle summary

Status	Editable	Usable	Visible in Data Viewer	Description
Draft	Yes	No	No	Initial state of every newly created custom entity. In this state, you have full flexibility to design and adjust your schema: you can edit entity properties, add, modify, or delete fields, and delete the entity entirely if needed. Publishing is also available from Draft once the configuration is ready. However, in Draft, you cannot upload data, use the entity in configurations, or view data in the Data Viewer .
Active	No	Yes	Yes	Entities in Active status have been published and are available across the application. Data can be ingested via CSV or API. The entity appears in the Data Viewer and you can use it in supported platform areas. Note that the schema becomes read-only – no changes to fields, data types, or business keys are possible. This restriction exists to ensure data consistency and the stability of any downstream processes that depend on the entity. It also prevents any breaking changes after usage.
Deactivated	No	No	Limited	Custom entities that are no longer needed can be deactivated. A Deactivated entity cannot be selected in any configuration and is removed from active workflows; it is however retained for reference. Importantly, you cannot deactivate an entity if it is currently in use. Use this status to clean up, retire unused entities, and prevent further usage without permanently deleting historical data.

Creating a custom entity

All configuration happens in the Draft state so that you can safely design your schema before making it available for use.

To create a custom entity, proceed as follows:

1. Click the Create custom entity button located above the list of entities in the Custom Entities page. The entity creation page is opened.
2. In the Entity details section of the custom entity creation form, the basic information for the entity:
   • Enter a name in the Name field. Entity names must follow system naming rules: spaces are not supported. beqom recommends that you follow camelCase or PascalCase conventions for readability. Use formats such as SalesIncentiveTier or RegionMapping. Avoid Sales Incentive Tier or Region Mapping.
   • In the Effective dating field, specify the effective dating method that you want to use for the entity. The effective dating mode determines how the entity handles data over time. Choose No effective dating for static or reference datasets, where only the current version of the data is stored. Choose Effective date if values change over time and each record has a single effective date. Choose Effective date range if data is valid within a defined time period and each record has both a start and end date. In the SalesIncentiveTier example that we describe further on in the article, No effective dating is appropriate because the dataset represents a current tier structure that does not require historical tracking.
3. In the Grid builder section of the form, define your first field for the entity (each field represents a column in your dataset):
   • Enter a name for the field in the Name,

   • In the Type,field, select the data type of the new field. Possible values are String (text values), Integer (whole number), Number (numeric value with decimals), Boolean (true/false), Date (date values), Entity reference (link to another entity) or Enum reference (predefined list of values).

     Choose the type that reflects how the data should be stored and validated.

   • If you want the field to have a default value, specify that value (corresponding to the selected type of the field) in the Default value field. If you don't specify the Default value field, a default value will be applied automatically during ingestion. This can prove useful for fallback scenarios or simplifying uploads.

4. In the Additional field attributes subsection, check the boxes that apply to the field:
   • Check the Is required box to make the field mandatory. Used for essential data points, required fields must always contain a value.
   • Check the Is business key box to indicate that this field is the business key of the entity. At least one field must be marked as Is business key. The business key uniquely identifies each record and prevents duplicate entries during data upload.
   • If you want to provide additional context, for instance to indicate the purpose of the field, check the Description box. Upon doing so, a text field is displayed at the bottom of the form.
5. If you want to add more fields to the custom entity, click Add field in the lower left corner of the page.
6. You can provide a Description for more context.
7. To add more fields, click the Add field button in the bottom-left corner of the form. A new field box is added under the first one.
8. Repeat steps 3 and 4 to configure each new field. 
9. Click Save & exit to save your entity as a draft. The new entity is saved in the system and visible in the Custom Entities page. Upon saving, the system validates that field names are unique within the entity, at least one business key is defined, all field types are valid, and any referenced entities or enums exist.

This is an note/information message.

At the moment, each custom entity can contain a maximum of 20 fields.

This is a tip message.

To delete a field, click the icon next to the field name.

You can also Collapse and Expand each field to quickly verify your setup, as illustrated in the following figure:

Collapse all, Expand, and deletion options available for fields

Example

Consider the following example: the SalesIncentiveTier entity uses two fields. The first, TierCode, is a string field marked as both required and as the business key. It acts as a unique identifier for each sales incentive tier (for instance, BRONZE, SILVER, or GOLD) and ensures no duplicate records are created during upload. The second, QuotaThreshold, is a number field marked as required with a default value of 0, representing the minimum quota threshold for each tier. It is not part of the business key because multiple tiers could theoretically share the same threshold value. Together, these fields produce a dataset structured as follows:

Tier code	Quota threshold
TierCode	QuotaThreshold
BRONZE	0
SILVER	75000
GOLD	150000

The following figures illustrate the configuration of these two fields:

Fields configured for a custom entity

Publishing the custom entity

Once you are done with your configuration, click Publish in the top-right corner of the custom entity creation form. This will move your entity from Draft to Active. The entity then becomes usable, and the schema is locked.

The publication process will fail is any of the validation checks performed by the system fails. Make sure that

• All business keys are defined
• All required fields have a default value
• All field definitions are valid
• All referenced entities or enums exist

This is an attention message.

Publishing occurs immediately with no confirmation pop-up; make sure you do it only once you fully finalize your schema. Published entities are fixed and cannot be edited; always review naming conventions, confirm the business key configuration, verify all required fields, and make sure no additional fields will be needed before publishing.

Uploading data

After publishing, upload data to populate your Active entity.

For automated workflows, data can be uploaded with API ingestion. See Uploading data into the data foundation via API for details. However, for most users, beqom recommends CSV upload. To perform a CSV upload for your custom entity, follow the procedure detailed in Working with custom entities.

A template of your new custom entity will be available in the list of templates. Once you have performed a successful upload, you will be able to view your custom entity and its details in the Data Viewer page.

Using custom entities in supported platform areas

Once you have published and populated a custom entity with data, you can use it in supported areas of the platform. Its availability depends on whether it is linked to Worker data.

Worker-linked custom entities (i.e. those that include a direct reference to the Worker and resolve to a single record per worker) can be used in Populations, In the Data Modeler, and in the Snapshot Manager. Custom entities that do not reference the Worker entity are available in the Data Viewer and usable as reference datasets, but are not available in the aforementioned three areas.

• In Populations, you can choose a worker-linked custom entity and use custom entity fields to define conditions.
• In Data Modeler, Worker-linked custom entities appear as available data sources and their fields can be selected for use in data models.
• In Snapshot Manager, Worker-linked custom entities are included in snapshot data and their fields can be used as part of snapshot outputs.