Skip to content

Entity Manager

The Entity Manager tool is available from the Administration panel. It provides the ability to highly customize your EspoCRM instance. You are able to do the following.

  • Add new entity types.
  • Customize existing entity types: change labels, default order in list view, etc.
  • Configure fields: add new, customize existing ones.
  • Configure relationships: add new, change labels of existing ones.

All customizations made via the Entity Manager are stored in the custom directory. You can make customizations on a separate instance, then copy the custom directory to your production instance and run rebuild (from the administration panel or CLI).

In this article:

Creating new entity type

Click the Create Entity button on the Entity Manager main page (Administration > Entity Manager). Specify the name, labels and select the type. If you select the Person type, your entity will have Email, Phone, First Name, Last Name and Salutation fields. Check the Stream if you want to have a stream panel (users will be able to follow records).


  • Base – has only basic fields created by default: Name, Assigned User, Teams, Description.
  • Base Plus – like the Base type but with the Activities, History, Tasks panels.
  • Event – has the Date Start, Date End, Duration, Parent, Status fields; available in the Calendar and in the Activities panel (must be enabled at Administration > Settings).
  • Person – has the Email, Phone, First Name, Last Name, Salutation, Address fields; the Activities, History, Tasks panels.
  • Company – has the Email, Phone, Billing Address, Shipping Address fields; the Activities, History, Tasks panels.

Entity type parameters

If you click Edit on the entity view, you will be able to change parameters of that entity.

  • Labels – singular and plural names of the entity.
  • Default order in which records are sorted by in list views.
  • Stream – whether Stream feature is enabled for this entity.
  • Disabled – check if you don't need this entity in your system.
  • Text Filter Fields – what fields to search in for the main text filter and global search.
  • Status field – which field (of enum type) will be used for a record status; required for kanban view.
  • Kanban view – available only if Status Field is specified. Enables Kanban view mode.
  • Full-Text Search – see more here.
  • Disable record count – the total number won't be displayed on the list view; can decrease loading time when the DB table is big.
  • Color – a specific color for a quick recognition.
  • Icon – the picked icon will be displayed in the side navbar.


By clicking the Fields, you will be moved to a separate page. There, you will be able to create new fields or update existing ones.

More detail about fields.


After you created a new field, you may also need to put this field on layouts (Administration > Layout Manager).


You can create custom relationships between entity types. Both standard and custom entities can be related to each other.

It's possible to create a relationship between the same entity type. E.g. a Company can have a parent company and child companies.

It's possible to have multiple relationships between the same entity type pairs. E.g. a Person and an Event can be linked by two relationships: attendees and organizers.

Relationship types are listed below.


After you created the relationship, a Link field will be automatically created for the right-side entity type. You can add the link field to the Detail layout (at Administration > Entity Manager > {Entity Type} > Layouts > Detail). You can also add the relationship panel to the left entity type (at Administration > Entity Manager > {Entity Type} > Layouts > Bottom Panels).


The same as One-to-Many but vice versa.


After you created the relationship, relationship panels will be available on both sides (at Administration > Entity Manager > {Entity Type} > Layouts > Bottom Panels).

One-to-One Right

The Link field will be created in the current entity type (left), the Link-One field – in the foreign entity type (right). It does not matter which one-to-one type to choose from the user perspective.

One-to-One Left

The same as previous but vice versa. The Link field will be created in the foreign entity type.


Linking with multiple entity types through the Link-Parent field.


The parameter Link Multiple Field implies that the field of the Link-Multiple type will be created along with the relationship. You can put such a field on the layout. It's convenient for quick picking of related records. It's not a good option if your relationship is intended to have a lot of linked records that can slow down loading of the detail view screen.

Examples of link-multiple fields:

  • Teams field – most entities have this field
  • Contacts field in Opportunity
  • Contacts field in Case


If the parameter Audited is checked, then updates of the relationship will be logged in Stream.


Before-save custom script

A formula script executed before a record is saved (created or updated). Useful for setting fields that are supposed to be calculated (usually such fields are read-only).

API before-save script

As of v7.5.

A formula script called on create and update API requests before a record is saved. See more detail.

Copying to another instance

All customizations made through Entity Manager are stored in the custom/Espo/Custom folder. You need to copy contents of this folder to another instance and then run rebuild (CLI command php rebuild.php).

It's also possible to export customization to an installable extension. On the Entity Manager page, from the dropdown next to Create Entity button.