How to promote EspoCRM configuration from development to production without rebuilding it by hand
A team that has built roles, workflows, BPM flowcharts and customizations in a development instance does not need to retype them for production. Configuration can be exported, compared and imported, but only some of it is safe to move as-is, and the rest has to be handled by hand or kept out of the transfer entirely. The effort depends on three things: how much configuration changed since the last promotion, how many environments sit between development and production, and how much environment-specific data (users, teams, integration credentials and URLs) must stay separate from the configuration itself.
Start by sorting what you have built into two groups. Roles, workflows and BPM flowcharts are configuration that can be deployed, but each one may refer to users, teams, email accounts or external endpoints that exist only in development. The environment-specific data must be identified before any export runs, because an import that carries a development integration URL or a test user into production will fail quietly or misroute records. Confirm with your own instance which settings reference such values, and agree who owns the production values and where they are stored.
Then decide how the transfer will be run and reviewed. The Export Import extension is the documented route for moving records, settings and customizations between instances, and the EspoCRM Advanced Pack page lists the Workflows and BPM engine that many of these flowcharts depend on, so confirm the extension and license state in both environments first. Keep the exported files and your custom directory under version control so every change has a reviewable history, and compare the staging export against production before importing. Ask your implementation partner or internal team to document which comparison, approval and rollback steps are required for each release.
Which EspoCRM configuration moves cleanly between environments and which does not
This table compares common EspoCRM configuration items by how they are typically promoted from a development instance to production and what needs attention on the way. Read each row before building a pipeline, because items that reference record IDs, users or extensions usually need remapping or a manual step. Items marked as needing confirmation depend on Export Import extension behavior that should be checked in its documentation for your version.
| Configuration element | How it is typically promoted | Migration notes |
|---|---|---|
| Roles and teams | Export Import extension run, or recreated by hand in production from a reviewed definition | Role permissions are usually portable; confirm how teams and user assignments are handled before relying on an export. |
| Layouts and Entity Manager entities and fields | Export Import extension run, with the custom directory under version control | Custom entities and fields usually move with their definitions; confirm that layouts referencing field names are included in the same run. |
| Formula scripts in before-save scripts | Stored in the custom directory and deployed as files, or moved with Entity Manager definitions | Script text is portable, but any hard-coded record IDs, user IDs or team IDs must be replaced with values valid in production. |
| Workflows and BPM flowcharts (Advanced Pack) | Export Import extension run after the Advanced Pack is installed in both environments | Requires the Advanced Pack in both instances. Flowcharts that reference users, teams, or specific records need remapping. Confirm promotion behavior in the Export Import extension documentation. |
| Reports | Export Import extension run, or recreated manually in production | Reports tied to specific records, users or saved filters may need adjustment. Confirm whether reports and their panels transfer with their dependencies. |
| Integrations and extension settings | Recreated from a documented settings record in each environment, or exported where supported | Credentials and tokens should not be copied from development. Set them separately in production and confirm which settings the export includes. |
| Users and API users | Created in production, not promoted from development | User accounts and API users carry identity and credentials. Map roles to production accounts and create new API keys or HMAC secrets there. |
| Identity provider connections (OIDC or LDAP) | Configured separately in each environment | Redirect URIs, client secrets and group-to-team mappings differ per environment. Recreate them and test sign-in in production. |
| Mail settings and file storage | Configured separately in each environment | Mail servers, sender addresses and storage locations are environment-specific. Keep them out of exported configuration and confirm how they are excluded. |
Which documented tools carry configuration between EspoCRM instances
EspoCRM has no single tool that packages an entire configuration and promotes it between environments. Instead, a delivery plan combines a few documented paths, each covering different parts of the setup. Knowing what each one carries, and what it leaves behind, decides how much of the promotion is repeatable and how much remains manual.
Export Import extension runs
The Export Import extension is the documented route for moving configuration and customization data between instances as an export and import run. Confirm exactly which entity definitions, layouts, roles, workflows and BPM flowcharts it covers, and what file format it produces, in the extension's own documentation and against the EspoCRM version you run. Test each run in a staging copy before it touches production, because the export format determines what your pipeline can store and review.
The custom directory under version control
Code-level customizations such as custom entity files, hooks and extension code live in the custom directory of the EspoCRM installation. Keeping that directory in a Git repository gives you history, review and rollback for file-based changes. Check which artifacts end up there in your setup, and exclude files that hold secrets or environment-specific settings, since those should not be committed.
Admin UI for manual changes
Many settings, layouts and roles are changed directly in the administration interface, and those changes do not leave a file trail on their own. Treat every manual change as a step to record in a change log or ticket, then replay it in the target environment or capture it through an export run. Without this discipline, production drifts from the configuration you tested, and nobody can say which environment is correct.
CSV import for reference data
CSV import is suited to reference records such as lookup accounts or product lists, not to configuration itself. Its Create Only, Create and Update and Update Only modes, duplicate matching on chosen fields, and the ability to revert imported records control how data lands in the target. Decide the mode and matching fields per dataset before the run, and rehearse a revert in staging so that a bad batch can be removed cleanly.
Formula documentation for script logic
Formula Script is the built-in language used in before-save scripts, API before-save scripts, workflows and BPM. Because these scripts hold business rules, they should be reviewed as code and promoted with the workflows or entity settings that call them. Read the formula documentation for the functions and contexts available in your version, and confirm that each script behaves the same after promotion by testing it against representative records.
How to run a configuration promotion from export to production verification
This sequence moves tested EspoCRM configuration from development to production in a controlled, reversible way, so production changes match what was reviewed and verified. Each step produces a record that a named owner signs off before the next one starts.
Record the baseline in every environment
Before anything is exported, the platform owner records the EspoCRM version, the PHP and database versions, and the list of installed extensions with their versions in development, staging and production. This is the baseline that every later step is checked against. Mismatched versions or extensions are the most common reason a configuration export imports cleanly in one place and fails or misbehaves in another, so any difference must be resolved or accepted in writing before export. The step is done when the three inventories match or each difference has a named decision and owner. Sign-off: the platform owner, with the application owner confirming extension licensing for production.
Separate configuration from records and environment values
The delivery lead defines what is promoted as configuration (roles, workflows, BPM flowcharts, entity and layout customizations, and the custom directory) and what stays environment-specific (database credentials, site URL, mail server settings, API users, secrets, and live customer records). Environment values are kept out of the promoted set so that a development address or test credential never reaches production. The step is done when the promotion scope is written as a short list with each item marked configuration or environment. Sign-off: the delivery lead and the security owner, who confirms that secrets and API users are excluded.
Export configuration from development
A developer exports the agreed roles, workflows and BPM flowcharts from development using the Export Import extension, and collects the customization files from the custom directory. The export is labeled with the source version, extension versions and date so it can be traced later. The step is done when the export files open cleanly and their contents match the scope list from the previous step. Sign-off: the developer who built the change, with a second reviewer confirming the export contains nothing outside scope.
Commit the custom directory and export output to version control
The developer commits the custom directory and the export files to the team's repository in a single change, with a message that names the ticket, the source environment and the EspoCRM version. Reviewers approve the change through the normal merge process, and the approved commit becomes the only artifact that can move forward. The step is done when the commit is merged and the release is tagged or identified by its hash. Sign-off: a peer reviewer, plus the delivery lead for production-bound changes.
Compare the proposed changes against the target
Using the approved commit, the reviewer compares the export against the current staging or production configuration, reading the differences in roles, workflows and flowcharts rather than relying on the export's success message. Each change is classified as new, modified or removed, and removals receive extra scrutiny because they can silently drop access or automation. The step is done when every difference is listed and each one has an accepted or rejected decision. Sign-off: the application owner for business logic and the security owner for any role or permission change.
Rehearse the import in staging on a copy of production data
The platform team restores a recent copy of the production database and files into staging, then imports the approved configuration there. They run the same import steps planned for production and record every warning, error and manual correction. Any correction made in staging must be written back into the commit, not applied by hand. The step is done when a staging import completes with no unexplained issues and the team has a written runbook from the rehearsal. Sign-off: the platform owner, who confirms the runbook is complete.
Back up, import to production and verify with test users
Immediately before the planned production window, the platform owner takes a database backup and a file backup, confirms the backups can be read, then imports the approved configuration. Afterward, testers sign in with dedicated test users assigned to each role, and they run representative sales and service actions to confirm permissions, workflows and BPM flowcharts behave as the scope list describes. Test users are disabled or removed once verification is complete. The step is done when the verification checklist is fully signed off and the backup location is recorded. Sign-off: the platform owner for the import and backup, and the application owner for functional verification.
Freeze direct edits in production
After verification, the team declares a freeze on direct configuration changes in production, so that all further changes start in development and move through the same export, review and rehearsal path. Administrators are told in writing which changes are now prohibited and how an urgent fix is handled, with the same review and backup steps applied. The step is done when the freeze is communicated, access controls for administrator accounts are reviewed, and the next promotion is scheduled from the version-controlled baseline. Sign-off: the application owner and the security owner, who confirm that administrator access matches the freeze policy.
Promotion rules for roles, workflows and formula scripts
Roles and teams define what users can see and change, so they are usually the first configuration promoted from development. The role definitions themselves are portable, but the people, teams and API credentials attached to them are not. Plan the promotion so that role permissions travel through your pipeline while identities stay local to each environment.
- Export role definitions and teams: Capture scope and permission levels for each role, plus team structure, so the same access model exists in production.
- Portal roles: Confirm portal role scopes separately, since external users depend on them and their access is easy to widen by mistake.
- API users and permissions: Recreate API users in each environment with role-based permissions. Their credentials and any API keys or HMAC secrets are environment-specific and must never be exported from development.
- Re-enter per environment: Team membership, user accounts, API users, credentials and any IP-based access restrictions.
- Test after import: Log in as a representative user from each role, confirm record visibility, and confirm that each API user can perform only its intended operations.
Review any role change that expands access before it is imported, because a permissive role copied to production can expose customer records immediately. Confirm the final access model with the people who own the data.
Workflows and BPM flowcharts automate assignments, notifications, approvals and external calls. Both depend on the Advanced Pack, so confirm that the extension is licensed and at a matching version in every environment before importing any process definition. Process definitions usually reference fields, users and teams by identifier, so an import that works on paper can still break routing in production.
- Advanced Pack dependency: Verify the extension version in the target environment first. The Advanced Pack is included in EspoCRM Cloud plans, but self-hosted instances need it installed and licensed under your own arrangement.
- Export workflows and flowcharts: Include each workflow rule and BPM flowchart, along with the entity and field definitions they reference.
- Referenced fields, users and teams: Check that every field name, assignee and team referenced by a process exists in production, and re-map any that point to development-only users.
- Re-enter per environment: Assignees, team routing, notification addresses, webhook endpoints and any external call targets.
- Test each process path: Run each branch with a test record, including approval rejection, timeout and error paths, and confirm that each path produces the expected field changes and notifications.
Disable imported workflows in production until every path has been exercised on a test record. Keep a record of which paths were tested, because a path left untested is the most common source of unexpected behavior after release.
Formula Script is EspoCRM's built-in scripting language. It runs in before-save scripts configured in the Entity Manager, in API before-save scripts, and in workflows and BPM. Because these scripts run during save operations, a faulty script can block users or integrations from saving records at all. Treat formula changes as code changes that require a review and a controlled rollout.
- Export scripts by location: Capture before-save scripts from the Entity Manager, API before-save scripts and any formula used inside workflows or BPM, so each one is traced to its source.
- Review for side effects: Check each script for field writes, conditional logic and references to other entities, since a change in one entity can alter behavior in another.
- Re-enter per environment: Any hard-coded identifiers, team references, user references or external endpoints used inside a script should be replaced with environment values.
- Test saves for each entity: Create, update and delete records through the UI and the API, and confirm that saves succeed for normal input and fail safely for invalid input.
- Watch error logs after release: Monitor logs for script errors during the first days of use, since some errors appear only with specific data combinations found in production.
Keep formula scripts under version control with the rest of the custom directory, and record the reviewer and test evidence for each change. Confirm that a rollback path exists before importing any script that runs on every save.
What drives the effort and duration of a configuration promotion
This table lists the factors that most change how much work a promotion from development to production involves, what each factor does to effort, and what to ask for in a quote. Read it as a checklist for scoping: the more of these factors that apply to your instance, the more the quote should itemize. No duration or fee figures appear here, because the right numbers depend on your inventory and environments.
| Driver | Effect on effort | What to ask for in a quote |
|---|---|---|
| Custom entities, layouts, workflows and BPM flowcharts | Each entity, layout, workflow and flowchart is a separate artifact to export, review, import and test. Counts grow the review and test load faster than file size does. | A written inventory of entities, layouts, workflows and BPM flowcharts, with the items in scope marked |
| Number of environments | Each environment adds an import, a validation pass and environment-specific settings. Staging and production usually need the same steps repeated. | The list of environments, their purpose and who has import rights in each |
| Drift between development and production | Changes made directly in production, or not yet exported from development, must be reconciled before import. Drift often takes longer to resolve than the planned change. | A comparison of current configuration across environments and a plan for handling changes made outside the pipeline |
| Extensions and licenses across environments | Extensions such as the Advanced Pack must be present and matched in each environment for workflows and BPM to import cleanly. License checks add a step per environment. | The extensions in use, their versions per environment and confirmation of the license status for each |
| Use of version control | Without version control, the team must build a baseline and diff manually. With it, the work shifts to setting up the export and review workflow. | Whether the customization directory and exports will be stored in your repository, and who owns the branching and review rules |
| Formula scripts that reference other records | Scripts that look up related records depend on the data and entity structure being present. Testing has to cover each lookup path, which grows with the number of references. | A list of formula scripts with the records and fields each one reads or writes |
| Integration and identity connections | Connections such as OIDC sign-in, email or external APIs usually need different endpoints, secrets and redirect settings per environment. These settings are not part of a configuration export. | The integrations and identity provider connections, with the per-environment values each one needs and who supplies them |
| Testing scope agreed with business owners | The test plan sets how many cases run per promotion and how many rounds of sign-off happen. Broad scope with several approvers extends the cycle. | The test cases, acceptance criteria, sign-off roles and the number of test rounds included in the fixed scope |
What usually goes wrong when EspoCRM configuration is promoted
Most failed promotions trace back to a few predictable gaps: changes made in the wrong place, environment values carried across, versions out of step, and imports with no way back. Each card below names one failure and the single check that prevents it.
Direct production edits get overwritten
When an administrator changes a layout, role or workflow directly in production, the next import from development can overwrite that change or leave it out without any warning. The result is a production system that no longer matches the version in source control. Prevent it by making production read-only for configuration, and by requiring every change to pass through the development instance and the repository before it reaches production. Before each import, check the production instance for changes made since the last promotion.
Environment values promoted by mistake
Site URLs, API users, integration endpoints and credentials stored in exported configuration can move into production unchanged, so production starts calling development services or accepting development API keys. Treat these values as environment settings rather than promotable configuration. Prevent it by reviewing every exported file for hostnames, user IDs and secrets before commit, and by keeping secrets out of the repository entirely.
Extension and version mismatches
A configuration file exported from an instance with a different EspoCRM version or extension release can fail to import, or import in a form that behaves differently. Upgrading through the UI is disabled by default as of version 10.0, so keeping environments aligned is a deliberate step that someone has to plan and run. Prevent it by recording the EspoCRM and extension versions in each promotion and confirming they match on both sides before the import starts.
Workflows that reference missing fields or teams
Workflows and BPM flowcharts often point to specific fields, teams, users or statuses. If a development-only field or team is missing in production, the process can fail silently, route work to nobody, or stop at a step that cannot complete. Prevent it by listing every field, team and role each workflow depends on, and creating those dependencies in production first, or in the same promotion, before the process is enabled.
Formula scripts that break saves
A formula in a before-save script that works with development data can fail on production records that contain empty fields, unexpected values or older data shapes. Because the script runs on every save, the failure blocks users from editing records they need to work on. Prevent it by testing each imported formula against a copy of production data, including records with blank or legacy values, and by confirming that saves succeed before the change is opened to users.
Imports without a backup or rollback plan
An import that alters roles, workflows or layouts can be hard to undo if nobody has captured the production state first. Teams then reconstruct settings by hand under pressure. Prevent it by taking a database and file backup immediately before each import, writing down the exact steps to restore it, and running the promotion in a window where someone can verify the result and reverse it if needed.
Questions teams ask before promoting EspoCRM configuration
How much effort does promoting EspoCRM configuration from development to production involve?
Effort depends mostly on how much of the configuration lives outside the database-backed settings and how many environments must stay in step. Roles, workflows and BPM flowcharts each need to be exported, compared and reviewed before import, and every custom entity, layout and formula script that they depend on has to move with them. Cost is largely the time of the people doing the export, comparison, testing and sign-off, so the quote should list each configuration area in scope, the number of environments, and whether test runs against a copy of production are included. No figures are given here because the work varies with the size of the configuration.
What sets the timeline for moving configuration into production?
The timeline is set by the number of configuration areas, the number of rounds of testing and business sign-off, and how many change sets have accumulated since the last promotion. A small set of workflows can move quickly, while a broad change to roles, BPM flowcharts and custom entities needs more review time, especially when business owners must confirm behavior. Ask for the schedule to show separate stages for inventory, comparison, test import, user acceptance and the production window, so that delays can be traced to a specific stage.
What must our team provide before a promotion starts?
A promotion needs a complete configuration inventory, access to both environments with named administrators, a set of test users that mirror real roles, and a named business owner who signs off each change. The inventory should list the roles, teams, workflows, BPM flowcharts, custom entities and layouts in scope, along with any extensions they depend on. Without test users and sign-off, the team cannot prove that a role or workflow behaves correctly after import, so these items should be agreed in writing before work begins.
Can an internal team promote EspoCRM configuration without a partner?
Yes, an internal team with EspoCRM administration skills can run the promotion, provided it has the time, a test environment and a repeatable process. The usual gap is not the import itself but the discipline around it: keeping configuration in version control, comparing changes before each import, and testing workflows under the roles that will use them. A partner is most useful when the team lacks that experience, when the change set is large, or when the promotion must fit a regulated change process. Ask any partner to show how they would document each step so the internal team can run future promotions alone.
Is the Export Import extension required, and what happens without it?
The Export Import extension is the practical route for moving records, settings and customizations between instances, and it is the approach this topic assumes for a delivery pipeline. Without it, teams must recreate roles, workflows and BPM flowcharts by hand in production, or copy files from the custom directory and reapply database changes manually. Manual recreation is slower and makes it hard to prove that production matches the reviewed development state. Confirm the extension's availability, licensing and version alignment with your EspoCRM version before planning the work, since the Advanced Pack, which provides workflows and BPM, is included in EspoCRM Cloud plans and is a separate add-on for self-hosted installs.
How do we stop production configuration from drifting away from development?
Drift is prevented by treating production changes as forbidden outside the promotion process and by keeping customizations in the custom directory under version control. Every change should originate in development, pass review, and reach production through the same export and import path, so no administrator edits production directly. Schedule a regular comparison between environments to detect differences early, and record each promotion with its reviewer and date. Limit administrator accounts to the people who run promotions, and use the EspoCRM security controls for role changes so that unreviewed edits are visible.
How are security settings such as password policy, 2FA and IP restrictions handled across environments?
Security settings should be defined once and applied to each environment deliberately, not copied blindly. Password policy, two-factor authentication, session and token lifetime, password recovery for admins and IP allowlists are often environment-specific, so the promotion inventory should mark which values are shared and which are local. Note that EspoCRM's own 2FA is not compatible with OIDC sign-in, so the chosen sign-in method must be settled before these controls are promoted. Test each setting with a non-admin test user in the target environment, and keep a record of what was applied and why.
How DeployOpen scopes, delivers and supports an EspoCRM configuration promotion
DeployOpen plans and delivers EspoCRM configuration promotion inside infrastructure you control, with the scope agreed in writing before work starts. The work moves roles, workflows and BPM flowcharts through a repeatable path from development to production, with each step documented and handed over to your team.
How we scope
- Inventory which roles, workflows and BPM flowcharts are in scope, and which settings stay environment-specific.
- Confirm the Advanced Pack and any other extensions present in each environment, and agree how their versions are aligned.
- Agree in writing the pipeline, comparison method, deliverables and timeline before any configuration is moved.
How we build
- Place customizations in the custom directory and keep them under version control with reviewed changes.
- Set up the Export Import extension runs and a comparison step so each change is reviewed before it reaches production.
- Test each promotion in a non-production instance, recording results and rollback steps for every import.
How we hand over
- Deliver a runbook covering the promotion sequence, comparison review, import order and rollback procedure.
- Walk your administrators and developers through the repository layout, branching model and approval gates.
- Document which items must never be promoted automatically, such as credentials, user accounts and environment URLs.
How we support
- Offer ongoing support and upgrade help as a retainer, covering future promotions and extension changes.
- Review promotion logs and comparison reports with your team after each agreed release cycle.
- Plan re-testing of promoted configuration when EspoCRM or the Advanced Pack moves to a new version.
