Customization: How to create custom entity

Note: It’s possible to create custom entity through Admin UI. This article is outdated.

I’m going to show you how to create new entities in EspoCRM manually. We will make new simple module called PM (Project Management) with Projects and Tasks entities. Projects and Tasks will be related as one-to-many.

Create new module

You need to create new folder for your module (package) in application/Espo/Modules directory:

application/Espo/Modules/PM

Structure of our module directory:

application/Espo/Modules/PM/Controllers/
application/Espo/Modules/PM/Entities/
application/Espo/Modules/PM/Resources/

Metadata definition

We need to define new scopes: Project and ProjectTask. Just create two JSON files. application/Espo/Modules/PM/Resources/metadata/scopes/Project.json

{
'entity': true,
'layouts': true,
'tab': true,
'acl': true,
'module': 'PM',
'customizable': true,
'stream': true,
'importable': true
}

application/Espo/Modules/PM/Resources/metadata/scopes/ProjectTask.json

{
'entity': true,
'layouts': true,
'tab': false,
'acl': true,
'module': 'PM',
'customizable': true,
'stream': true,
'importable': true
}

Then we define fields and relationships for our entities. It should be done in entityDefs. application/Espo/Modules/PM/Resources/metadata/entityDefs/Project.json

{
'fields':{
'name':{
'type':'varchar',
'required':true
},
'status':{
'type':'enum',
'options':[
'Draft',
'Active',
'Completed',
'On Hold',
'Dropped'
],
'default':'Active'
},
'description':{
'type':'text'
},
'account':{
'type':'link'
},
'createdAt':{
'type':'datetime',
'readOnly':true
},
'modifiedAt':{
'type':'datetime',
'readOnly':true
},
'createdBy':{
'type':'link',
'readOnly':true
},
'modifiedBy':{
'type':'link',
'readOnly':true
},
'assignedUser':{
'type':'link',
'required':true
},
'teams':{
'type':'linkMultiple'
}
},
'links':{
'createdBy':{
'type':'belongsTo',
'entity':'User'
},
'modifiedBy':{
'type':'belongsTo',
'entity':'User'
},
'assignedUser':{
'type':'belongsTo',
'entity':'User'
},
'teams':{
'type':'hasMany',
'entity':'Team',
'relationName':'EntityTeam'
},
'account':{
'type':'belongsTo',
'entity':'Account',
'foreign':'projects'
},
'projectTasks':{
'type':'hasMany',
'entity':'ProjectTask',
'foreign':'project'
}
},
'collection':{
'sortBy':'createdAt',
'asc':false,
'boolFilters':[
'onlyMy'
]
}
}

application/Espo/Modules/PM/Resources/metadata/entityDefs/ProjectTask.json

{
'fields':{
'name':{
'type':'varchar',
'required':true
},
'status':{
'type':'enum',
'options':[
'Not Started',
'Started',
'Completed',
'Canceled'
],
'default':'Not Started'
},
'dateStart':{
'type':'date'
},
'dateEnd':{
'type':'date'
},
'estimatedEffort':{
'type':'float'
},
'actualDuration':{
'type':'float'
},
'description':{
'type':'text'
},
'project':{
'type':'link'
},
'createdAt':{
'type':'datetime',
'readOnly':true
},
'modifiedAt':{
'type':'datetime',
'readOnly':true
},
'createdBy':{
'type':'link',
'readOnly':true
},
'modifiedBy':{
'type':'link',
'readOnly':true
},
'assignedUser':{
'type':'link',
'required':true
},
'teams':{
'type':'linkMultiple'
}
},
'links':{
'createdBy':{
'type':'belongsTo',
'entity':'User'
},
'modifiedBy':{
'type':'belongsTo',
'entity':'User'
},
'assignedUser':{
'type':'belongsTo',
'entity':'User'
},
'teams':{
'type':'hasMany',
'entity':'Team',
'relationName':'EntityTeam'
},
'project':{
'type':'belongsTo',
'entity':'Project',
'foreign':'projectTasks'
}
},
'collection':{
'sortBy':'createdAt',
'asc':false,
'boolFilters':[
'onlyMy'
]
}
}

We need clientDefs definition to let the client know that we deal with records (CRUD). application/Espo/Modules/PM/Resources/metadata/clientDefs/Project.json

{
'controller': 'Controllers.Record'
}

application/Espo/Modules/PM/Resources/metadata/clientDefs/ProjectTask.json

{
'controller': 'Controllers.Record'
}

Controller classes

We need two controllers for our entities. application/Espo/Modules/PM/Controllers/Project.php

<?php

namespace Espo\Modules\PM\Controllers;

class Project extends \Espo\Core\Controllers\Record
{
}

application/Espo/Modules/PM/Controllers/ProjectTask.php

<?php

namespace Espo\Modules\PM\Controllers;

class ProjectTask extends \Espo\Core\Controllers\Record
{
}

Entity classes

application/Espo/Modules/PM/Entities/Project.php

<?php

namespace Espo\Modules\PM\Entities;

class Project extends \Espo\Core\ORM\Entity
{
}

application/Espo/Modules/PM/Entities/ProjectTask.php

<?php

namespace Espo\Modules\PM\Entities;

class ProjectTask extends \Espo\Core\ORM\Entity
{
}

Language (I18n)

We need a translation for our new scope names. application/Espo/Modules/PM/Resources/i18n/en_US/Global.json

{
'scopeNames':{
'Project':'Project',
'ProjectTask':'Project Task'
},
'scopeNamesPlural':{
'Project':'Projects',
'ProjectTask':'Project Tasks'
}
}

Translation of fields and relationships. application/Espo/Modules/PM/Resources/i18n/en_US/Project.json

{
'labels':{
'Create Project':'Create Project'
},
'fields':{
'name':'Name',
'status':'Status',
'account':'Account'
},
'links':{
'projectTasks':'Project Tasks'
}
}

application/Espo/Modules/PM/Resources/i18n/en_US/ProjectTask.json

{
'labels':{
'Create ProjectTask':'Create Project Task'
},
'fields':{
'name':'Name',
'status':'Status',
'project':'Project',
'dateStart':'Date Start',
'dateEnd':'Date End',
'estimatedEffort':'Estimated Effort (hrs)',
'actualDuration':'Actual Duration (hrs)'
}
}

Finishing touch

Rebuild EspoCRM and refresh the page. Now you can configure layouts using Layout Manager and add Project tab to the navigation bar via admin panel.

All source code available here: Project Management module.