+44 (203) 695-03-80

Customization: How to create custom entity

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.

18 comments on “Customization: How to create custom entity
  1. Ricardo M Guedes says:

    Hello, I would like to create a travel module as described below:

    Travel module with extensive possibilities of defining travel types, travel mode and to track the travel request from the employee. When logged in, each e mployee can request a travel and this request are sent to the administrator via e mail.
    The functiona lity of the travel module differs depending on the rights of the user. The Travel module will be described from
    the perspective of an Administrator and Employee
    The Administrator can:
     Define Travel Mode, Travel Type
     Manage the Travel request
     View Travel summary for all the employee
    The Employee can:
     Apply for the Travel
     View the persona l travel summary
    Define Travel Mode
    Travel mode has been define d by t he administrator.
    Travel Modes= Train, Bus, Car, Air.
    To edit the Travel mode click the icon from the particular Travel mode list
    To de lete the Travel mode click t he icon from the particular Travel mode list
    To add the Travel mode, you enter the na me of the travel mode in the travel mode na me f ield and t he click “Add”.
    Define TravelTtypes
    Travel type has been defined by the administrator.
    Travel Types = Local, Domestic, International.
    To edit the Travel type click the icon from the particular Travel type list
    To delete the Travel type click the icon from the particular Travel type list
    To add the Travel type, you enter the na me of the Travel type in the Travel type Na me field and the click “Add”
    Apply for Travel
    All e mployees can apply travel request from this opt ion. To apply the travel click the “Travel Apply ” menu from the travel module and enter following details,
     Travel Type – Select the Travel type from the list
     Travel Mode – Select the Travel mode from the list
     Date – Select the From date & To date from the date selector
     From Location – Enter the location that you are going to get travel from
     To Location – Enter the location that you are going to get travel to
     Note – Notes regarding your travel request / Detailed explanation to get the approval for the requested travel.
    Personal Travel Summary
    Personal travel summary provides the list of requested travel by particular employee logged in.
    Manage Travel Request
    Administrator can vie w the list of travel request from the employee to get the approval in t he dashboard itself. To manage the travel request click the “Travel Request” menu from the travel module. Click that travel request a nd change the status.
    The Statuses are,
     Pending
     Approved
     Rejected

    I tried to adapt the Projects module but it did not work, can you help me?

    Thank you.

  2. Geert says:

    Modulebuilder should be integrated for automatic module creation.

  3. Neel says:

    Hi Thanks for Great Customization !!
    ‘Project Task’ is not showing in Administration » User Interface When We are add.
    Plz Plz help me.

  4. Shruti says:

    hello dear,
    I have one Issue in ESPO crm 2.6.0 when i make any changes in my existing code or when i remove my file or code . Then their is no changes in Output means old data is not change in output.
    I remove cache and history but their is nothing happen in output.

  5. margret930 says:

    Hello. Are you aware of learning to make a website smartphone hospitable?
    I’m looking for a topic or wordpress tool that could possibly fix this matter. Please share if you have any suggestions.
    Quick problem that’s entirely away from subject.
    My website appearance odd when surfing around.

  6. Brad Nickel says:

    For those of us not writing code could you release as module?

    Thanks,
    Brad

  7. priya says:

    Could you please explain file structure

  8. worldmiros says:

    Can you do a tutorial how to create a php hook for espocrm?

  9. worldmiros says:

    Suppose to create a hook, so i calculate field names in the same entity based on the status entity changing value. How do I create a hook after the user saves the updated entity?

1 Pings/Trackbacks for "Customization: How to create custom entity"
  1. […] I will show you how to create the  extension package of Project Management (PM) module described in this post Customization: How to create custom entity. […]

Leave a Reply

Your email address will not be published. Required fields are marked *

*