What EspoCRM customization covers
EspoCRM customization means changing the shape of the application to match how your teams sell and serve customers, without modifying the core code. Most of that work happens in the admin interface: custom entities and fields in the Entity Manager, record layouts that control what each role sees, formula before-save scripts that set or validate values when a record is saved, and dashlets that put the right figures on each user's home screen. Deeper changes use custom PHP and front-end code placed in the custom directory, which keeps them separate from the core files.
Customization usually starts with one of three triggers. A new sales or service process needs stages, fields or record types that the default setup does not have. A team has outgrown its default fields and is tracking the same information in spreadsheets next to the CRM. Or the data model no longer matches the business, for example when accounts, contacts and cases are linked in a way that makes reporting unreliable. Before anyone builds, write down which trigger applies and which decisions depend on the answer, such as who owns each field and which roles must edit it.
The short answer on in-house versus partner work: small field and layout changes are often within reach of an internal administrator who has read the Entity Manager and formula documentation and can test changes in a non-production copy. Code and script design across many entities is different. Formulas and custom code interact with permissions, imports, the API and later upgrades, so an outside reviewer who has seen those interactions in other installations is usually worth the cost before the design is locked. Confirm with your own team who will maintain each change after go-live.
This section covers the customization layer only. Rule-based workflows and BPMN processes that need the Advanced Pack, single sign-on, API integrations, data migration, and version upgrades are described on their own pages, so the decisions there are not repeated here. Ask any partner to separate their estimate by these areas so that you can see which changes depend on which other work.
What the work includes
Customization touches the data model, the user interface and the code that runs behind them. Each package below produces changes that must survive the next EspoCRM upgrade, so the work is planned and recorded as it is built.
Data model design
Entities, fields, relationships, and the teams and roles that can see or edit them are designed together before anything is created in the Entity Manager. Check that every new field has a clear owner, a defined type and a reason, and that the team and role permissions are reviewed alongside the model rather than after go-live.
Layout and detail view design
Detail, list, edit and search layouts are arranged around how each role works through a record, including which panels, related lists and fields appear first. Check layouts with users from each team, since a layout that hides a required field or buries a related list causes workarounds that are hard to see later.
Formula before-save scripts
Formula Script before-save logic in the Entity Manager sets defaults, derives values and enforces rules on record save. Each script is documented with its trigger entity, the fields it reads and writes, and its failure behavior, so a reviewer can see what changes a record and in what order when several rules apply.
Dashlets and list views
Home screen dashlets and saved list views give each team its working queue and key figures. Confirm which data each dashlet exposes to each role, since a dashlet built for managers can show records a sales user is not permitted to open.
Custom PHP and front-end code
Custom server-side PHP and client-side JavaScript or templates are placed in the custom directory so they are kept apart from core files. Check that each piece has a named owner, is tested on a staging copy, and does not patch core files, because core edits are overwritten or conflict during upgrades.
Change register and upgrade checklist
Every customization is logged in a change register with its purpose, the entities and files it touches, its approver and its test status. Each entry carries an upgrade checklist, so the team knows what to retest and which core behavior it depends on before a new release is applied.
What drives cost and duration
Each row names one factor that moves EspoCRM customization effort, why it does so, and one practical way to keep it under control.
| Driver | Why it moves effort | How to keep it down |
|---|---|---|
| Custom entities and fields | Every new entity needs its own layouts, list views, roles, relationships and import mapping, so effort grows faster than the field count. | Reuse existing entities and fields where the meaning matches, and agree a fixed field list before the build starts. |
| Formula scripts and complexity | Formula logic must be written, tested against edge cases and re-checked after each change, and chained scripts are hard to trace. | Limit scripts to before-save logic on the entity, avoid chains across related records, and keep each script to one clear rule. |
| Custom PHP or front-end code | Code in the custom directory needs development, review, testing and upgrade checks, and it carries maintenance for the life of the instance. | Start with configuration, Entity Manager and layouts, and approve each custom code item individually with a stated business reason. |
| Roles and layouts per role | Each role needs its own permission set and field visibility, and every extra layout multiplies testing with each role combination. | Model access through a small set of roles and teams, and reuse one base layout with minimal per-role changes. |
| Integrations that depend on custom fields | Field names, types and API behavior become contracts with other systems, so each custom field change can break a connected system. | Freeze field names and types used by integrations early, and document which external systems read each field. |
| Environments (dev, test, production) | Changes must be built, promoted and verified in each environment, and differences between them cause rework and failed releases. | Keep one reproducible configuration path, promote changes in the same order each time, and confirm test data resembles production. |
| Compliance or audit evidence | Change records, role reviews, test evidence and access exports add documentation and review steps to every change. | Agree the evidence list at scoping, such as change logs and role exports, and generate it as part of normal delivery. |
| Edition and extensions in use | Official extensions such as the Advanced Pack add features, reports and workflow logic that need their own design, testing and upgrade checks. Confirm current extension terms with the vendor. | Decide early which extensions are in scope, and keep workflow and report logic limited to what the agreed requirements need. |
Project phases and outputs
The sequence moves from agreed requirements to a customized EspoCRM instance that your own administrators can run, upgrade and extend.
Gather requirements and field inventory
We interview the business owners of sales, service and operations to map their processes, then build a field inventory listing each entity, field, role and layout they need. The client receives the signed requirements document and field inventory, and the phase closes when the business owners approve both in writing.
Design data model and layouts on a test instance
We design entities, relationships, field types, layouts and access roles in the Entity Manager on a dedicated test instance that matches the target server configuration. The client receives a data model diagram and layout mockups, and the phase closes when the business owners walk through the test instance and confirm the design.
Build entities, fields, layouts and formula scripts
We build the approved model with entities, fields, layouts, teams and Formula Script before-save logic, recording each configuration change so it can be reviewed and reproduced. The client receives a configured build on the test instance with a change log, and the phase closes when every item in the field inventory is traceable to a built element.
Develop custom code and dashlets in version control
We write any custom PHP, front-end code and dashlets inside the custom directory, keep them in a Git repository with code review, and test them against the configured model. The client receives the repository with the code, a deployment note and test results, and the phase closes when the reviewed code runs cleanly on the test instance.
Run user acceptance testing with real scenarios
Business users run scripted scenarios drawn from their daily work, such as lead qualification, quote handling and case escalation, and we fix defects found during testing. The client receives a test log with scenario results and a list of resolved issues, and the phase closes when the sponsor signs off on the scenarios.
Hand over with an upgrade checklist
We deploy the approved build to the production instance, train the named administrators, and document the configuration, custom code and extensions that an upgrade must check. The client receives the runbook, the upgrade checklist, the repository access and a handover session record, and the phase closes when the administrators run a supervised change themselves.
In-house or partner: who does what
Each row shows who usually carries a customization task, the skill it needs, and what your team must retain after go-live.
| Work item | Usually | Skill needed and retained role |
|---|---|---|
| Business requirements | Shared: partner runs workshops, your process owners sign off | Business analysis and knowledge of your sales and service processes |
| Data model design | Shared: partner drafts entities and fields, in-house approves | Business analysis and EspoCRM administration |
| Entity Manager and layouts | In-house once an administrator is trained, partner for initial build | EspoCRM administration |
| Formula before-save scripts | Partner builds the first set, in-house maintains changes | Formula Script knowledge, EspoCRM administration and QA |
| Custom PHP and JavaScript | Partner builds in the custom directory, with source and upgrade notes handed over | PHP, front-end JavaScript and code review |
| Dashlet design | Shared: in-house defines the views, partner builds them | Business analysis and front-end JavaScript |
| Testing | Shared: in-house tests business cases, partner runs regression checks | QA and business analysis |
| Deployment and handover | Partner runs releases, in-house takes ownership of the running system | DevOps and EspoCRM administration |
| Ongoing model ownership | In-house, and the most important retained role | An internal EspoCRM administrator who changes fields, layouts and scripts after go-live |
What goes wrong and how to prevent it
Most EspoCRM customization problems come from a few repeatable habits: editing core files, adding fields without an owner, and changing logic without testing it. Each card below names one failure and the step that prevents it.
Core files edited directly
Changes made inside the EspoCRM core folders are overwritten or break when the platform is upgraded. Keep all custom PHP, front-end code and metadata overrides in the custom directory, and check that each override still loads after every upgrade in a test copy before the change reaches production.
Field sprawl in lists and reports
Every field added in the Entity Manager appears in forms, filters and reports, so unused or duplicate fields make lists slow to scan and reports hard to trust. Before adding a field, check whether an existing one fits, and review field counts per entity during each change cycle.
Formula scripts with hidden side effects
A before-save Formula Script can change related records, totals or statuses that users never see on the record they edited. Document what each script reads and writes, and test it against a copy of real data before enabling it, including records that already exist.
Layouts built per user
Layouts tailored to individual users multiply quickly, become impossible to support and hide fields from people who later need them. Design layouts per role, assign teams and roles to match, and keep individual exceptions in a short, reviewed list.
Untested edge cases
Scripts and workflows that work on a clean sample often fail on blank values, closed records, large deal values or imported history. Build a test dataset that covers these edge cases, including records from your migration, and check results after each change.
Custom code without an owner
Custom PHP, scripts and field definitions with no named owner become unsafe to change once the original builder leaves. Assign an owner to each field, script and extension, keep a change record for every modification, and confirm the handover includes these records and the test dataset.
How the work changes by starting point
A new instance gives the widest room for entity design because no records or scripts depend on earlier choices. Scope centers on modeling entities and layouts in the Entity Manager before users arrive.
- Model before building: Decide which custom entities and fields are needed so layouts and formula scripts are written once.
- Keep custom code in the custom directory: Starting there makes later upgrades easier to plan.
- Design roles and teams early: Permissions decide what each user sees, so they belong in the first design pass.
- Build test records: Without legacy data, create a sample dataset to check formulas, dashlets and before-save scripts.
- Confirm the platform requirements: Check the server configuration docs for PHP, database and cron requirements before the build starts.
An instance that has grown over years often carries unused fields, overlapping entities and undocumented formula scripts. Effort shifts from building to inventory, cleanup and regression testing, and it is hard to size until the inventory is complete.
- Inventory everything: List custom fields, layouts, formula scripts, dashlets and custom PHP, and note which ones users still rely on.
- Retire fields carefully: Removing a field can break formulas, workflows or imports that still reference it.
- Review custom code: Compare files in the custom directory against the target release before any upgrade.
- Clean the data: Old values may not match current validation rules or picklist options.
- Ask for separate estimates: Quotes should price inventory, remediation and testing as distinct items.
The EspoCRM installation script for Ubuntu, Debian and Linux Mint deploys a Docker-based stack with Nginx and MariaDB, optional Let's Encrypt certificates and command.sh for backups, restores and upgrades. Customization starts from a known layout, but the team must understand how containers, volumes and command.sh interact.
- Map the container layout: Confirm with the installation docs how the custom directory and data volumes persist across container rebuilds.
- Back up before changing anything: Use command.sh to take a backup and test a restore before editing entities or code.
- Plan for cron: Background jobs need cron or a scheduled task, so the stack must run them reliably.
- Check the operating system: The script targets Ubuntu, Debian and Linux Mint. Other distributions need a separate installation plan.
- Rehearse upgrades on a copy: Test command.sh upgrades on a copy of the instance, since UI upgrades are off by default in version 10.0.
The server configuration docs list MySQL 8.0 or newer, MariaDB 10.6 or newer and PostgreSQL 15, alongside PHP 8.3 to 8.5 and Apache, Nginx or IIS. Most customization is portable across these engines, but the database choice affects testing, query-heavy formulas and the upgrade plan.
- Confirm the exact version: Check the server configuration docs for the supported database version before design starts.
- Test against production-like data: Query behavior and data handling can differ between engines, so test on a copy of real data volumes.
- Review any custom SQL: Custom PHP that uses raw SQL needs review against the chosen engine.
- Scope engine changes separately: Moving an existing instance to a different engine is its own project with its own data validation.
- Ask which versions are tested: A quote should state the database and PHP versions the test plan covers.
Without internet access, the team cannot pull packages, extensions or updates directly, so every file must be moved in by hand through an approved transfer process. Scope grows with the number of packages, extensions and PHP dependencies that must be staged and verified.
- Stage every dependency: Collect PHP packages, official extensions and, if the Docker script is used, the container images it needs before work starts.
- Verify transferred files: Check each file against published checksums where the vendor provides them.
- Treat each release as a transfer cycle: Each update needs its own staging, testing and approval path inside the restricted network.
- Build an offline test environment: Reproduce the stack in a lab so customizations are tested before they enter the restricted network.
- Confirm offline behavior of extensions: Check how official extensions handle licensing and updates without internet access.
What you need to provide
Five inputs shorten the customization build more than anything else, and the first is a named business owner for each custom entity and each process the build touches, such as the Opportunity pipeline or service case handling. Owners answer which fields are required at each stage, which stage changes should trigger formula before-save scripts, and who signs off a layout. Without them, design questions wait in email and each late answer reopens earlier work. Send the current field list and the layouts exported from the Entity Manager, including detail, list and edit views, so the team can see what already exists before adding entities or fields.
The second input is a test instance on the same EspoCRM version as production, loaded with a copy of production data or a representative sample. The sample should include messy cases such as duplicate accounts, partial addresses and legacy picklist values. Formula scripts and workflow conditions behave differently on real records than on clean demo data, so rework often traces back to testing on an empty system. Also supply the reports and dashlets people use every day, since they show which views must survive the change. If reports depend on the Advanced Pack, confirm whether it is licensed for your deployment, because it is included in EspoCRM Cloud plans.
Third, provide admin accounts that are separate from everyday logins. EspoCRM's security guidance recommends avoiding admin accounts for daily work, and the build needs administrators who can change the Entity Manager and deploy custom code without exposing routine sessions. Fourth, provide a source control repository, such as Git, for everything in the custom directory. PHP and front-end changes then get reviewed, versioned and deployed the same way each time, and a later upgrade can be checked by comparing your code against the new release.
Finally, decide who approves changes after go-live. Name the approver for new fields, layout edits, formula changes and dashlet additions, and agree how urgent fixes are handled. Without that decision, administrators make production edits directly in the UI, bypass the test cycle and let the instance drift from the repository. That drift is one of the most common sources of rework in later upgrades, so the approval path should be written down before the build starts.
Frequently asked questions
How much effort does EspoCRM customization take, and what drives it?
Effort depends on how many entities, layouts, roles and integrations the scope covers, and on how far the logic departs from standard EspoCRM behavior. A few field and layout changes made in the Entity Manager sit at the low end. Formula before-save scripts, dashlets, custom PHP or front-end code in the custom directory, and checks against each upgrade add design, testing and documentation work. Ask for the effort split by item in the written scope, and confirm which items must be rechecked at each upgrade. No figure is given here because effort follows from the scope you agree.
Can our internal team customize EspoCRM without an external partner?
Yes, many teams can make entity, field and layout changes in the Entity Manager themselves, provided an administrator understands the data model and the roles that will see it. Work that needs formula scripting beyond simple fields, custom PHP, front-end code, SSO or integrations usually needs someone who can read the EspoCRM codebase and test upgrades. List the changes you expect in the first year, then check whether your team can build, test and document each one. A partner is useful when that capacity is missing or when you want an independent review of upgrade-safe code.
How long does it take to get a first customized EspoCRM version?
The schedule is set in the written scope before work starts, so the answer depends on the entities, layouts, roles, data import and integrations that the scope names. Your team's inputs also set the pace: named business owners to approve the data model, process descriptions, sample data for import, and a staging environment for testing. Ask for milestones that show the first version, the review cycle and the acceptance criteria. Delays in approvals on your side usually move the first version later.
Does custom code survive EspoCRM upgrades when placed in the custom directory?
Code placed in the custom directory is meant to stay separate from core files, which reduces the chance of losing it during an upgrade, but it is not automatically safe. Each release can change APIs, hooks or templates that custom code depends on. Review the release notes for every version between your current release and the target release, and test the custom code on a staging copy before production. Check extensions the same way. Confirm the upgrade procedure and the test plan in writing before the build starts.
When is a formula script enough, and when is custom PHP needed?
A formula script is usually enough when the logic reads and sets fields on one record, such as calculating a value, setting a status or copying a related field before save. Formula Script is EspoCRM's built-in language and runs in before-save scripts configured in the Entity Manager, in API before-save scripts, and in workflows and BPM. Move to custom PHP when the logic needs external calls, complex data access, new endpoints or behavior the formula language cannot express. Custom PHP adds code review, testing and upgrade checks, so the choice affects the effort in the scope.
Are Advanced Pack workflows included in this service or a separate scope?
Treat Advanced Pack workflows as their own scope item. They appear in the written scope only when they are named there, with each workflow and Business Process Management process listed so it can be planned and tested. The Advanced Pack is an official add-on that provides reports, Business Process Management and workflows, and it is included in all EspoCRM Cloud plans. For a self-hosted installation, confirm with EspoCRM how the Advanced Pack is licensed for your environment before you finalize the plan.
How DeployOpen delivers EspoCRM customization
DeployOpen scopes, builds, tests and documents EspoCRM customizations on infrastructure you control, under a written, fixed scope. We keep changes in the places EspoCRM supports for customization so the instance stays upgradable.
How we scope
- The written scope lists each custom entity, field, layout, dashlet and formula script to be built for your teams.
- We map which sales and service processes each customization supports, so every change has a named business owner.
- The scope states which customizations sit in the custom directory and which, if any, depend on official extensions.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before any build work starts.
- Ask us to confirm which EspoCRM version the scope targets and how that version will be upgraded later.
How we build
- Entities and fields are created in the Entity Manager first, so the data model is settled before layouts depend on it.
- Formula before-save scripts are written, reviewed and tested against sample records covering normal and edge-case values.
- Custom PHP and front-end code is kept in the custom directory, separate from core files, to protect future upgrades.
- Each change is tested in a non-production instance with role-based user accounts that match your permission model.
- Changes are tracked in version control so every customization can be reviewed, reverted and reproduced.
How we hand over
- You receive documentation of each entity, field, layout, formula script and custom code file delivered.
- The handover lists the customization inventory and the steps needed to check each item during a future upgrade.
- Administrator walkthroughs cover how to adjust layouts and dashlets without breaking formula logic.
- Acceptance follows the test results and checklist agreed in the written scope, before the project closes.
- Ask for the handover package format and the list of credentials and access transferred to your team.
How we support
- Ongoing support is available as a retainer and covers reviewing customizations before each EspoCRM upgrade.
- Retainer work can include testing custom code and formula scripts against new EspoCRM releases in a staging copy.
- Support requests are logged against the customization inventory so changes stay traceable over time.
- Ask the support provider which upgrade steps they run, which your team runs, and how rollback is handled.
- Confirm response expectations and what a retainer excludes before signing, since terms come from the written agreement.
