# Custom Entities

The **Custom Entities** module is where you can create and manage objects with unique identifiers and attributes. Custom entities allow you to define objects tailored to your needs, enabling you to build a data model that meets your business requirements.

<figure><img src="/files/ShHHe35rCzGuupaGSx9l" alt="Custom entities view"><figcaption><p>Custom entities view in MD</p></figcaption></figure>

## Creating a custom entity

{% stepper %}
{% step %}

#### Choose to create an entity

Go to **Settings** -> **Custom Entities** and choose **Create New Custom Entity**.
{% endstep %}

{% step %}

#### Provide the entity details

Add the **ID** and **Name** for your entity and choose **Save**.

{% hint style="warning" %}
The ID must be capitalized.
{% endhint %}

As a result, the entity is added to the custom entities list and it's also visible in the **Custom Instances** node in the Management Dashboard.

<figure><img src="/files/zTufia8wYjXAUw99Eonr" alt="Custom entities instances"><figcaption><p>Custom entities instances view</p></figcaption></figure>
{% endstep %}

{% step %}

#### Add custom schema

To add a mixin schema to the custom entity, choose **Go To Mixin** and then **Add New Mixin Schema**.
{% endstep %}

{% step %}

#### Define custom fields

Select the **Entity** for the mixin schema and add its **Name**. You can also provide the **Key** value and a JSON file for the schema. If you don't upload the JSON schema file, add the mixin values in the **Fields** tab.

<figure><img src="/files/OhvZ7PtEtVBCI4BUrqvn" alt="Adding custom entity schema" width="400"><figcaption><p>Adding custom entity schema</p></figcaption></figure>

{% hint style="success" %}
Custom entities support references to other entities. Within a custom entity, you can establish one-to-one or one-to-many relationships to any CUSTOM ENTITY, but also to Emporix types such as CART, CATEGORY, CUSTOMER, CUSTOMER\_SEGMENTS, LEGAL ENTITY, MEDIA, ORDER, PRICE\_LIST, and PRODUCT. To achieve that, you need to define a mixin schema with reference to other type.
{% endhint %}
{% endstep %}

{% step %}

#### Save your configuration

Save your changes.
{% endstep %}
{% endstepper %}

Now, you can start creating your custom instance based on the entity and the mixin schema.

{% hint style="info" %}
To learn how to work with mixins, see the [Mixin Schemas](/ce/management-dashboard/settings/mixin-schemas.md) guide and to learn about custom instances, see [Custom Instances](/ce/management-dashboard/custom-instances.md) guide.
{% endhint %}

## Importing and exporting custom entities

You can export a custom entity together with its mixin schemas and import it in another context. For example, you can import it into another tenant or use it in a Partner Library component, such as a value stream or an AI agent.

To export a single custom entity, choose the **Export** icon next to that entity. This downloads a `JSON` file with the entity definition. If the entity references another entity, the referenced entity is automatically included in the export so the data model remains consistent.

You can also export multiple custom entities at once into a single `JSON` file. Select the entities in the list and choose the **Export** icon in the top bar. This approach is recommended when importing entities into Partner Library, because using one `JSON` file helps prevent duplicate entries.

<figure><img src="/files/Ok2hyyLcByYEiFKPdz5W" alt="Exporting multiple custom entities"><figcaption><p>Exporting multiple custom entities</p></figcaption></figure>

To import a custom entity definition, in the **Custom Entities** view, choose the **Import** icon. Select or drag and drop the `JSON` file from your device to trigger its import. The custom entity or entities are automatically added to the custom entities list.

<img src="/files/LhEV7YVnCbrvPUbnvdkW" alt="Import icon" width="100">

{% hint style="warning" %}
Emporix allows importing only custom entities with a valid export data, so only the previously exported entities can be imported.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.emporix.io/ce/management-dashboard/settings/custom-entities.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.