How EspoCRM layout customization for teams and portals starts
Sales, service and partner users rarely need the same screen. A sales representative wants deal values, stage and next steps on the first view, a service agent wants case status and SLA-related fields, and a partner using a portal should see only the records and fields the business has chosen to share. In EspoCRM, layouts are how each group sees only what it needs. Before any build starts, list the user groups, the records each group works in, and the fields each group must read, edit or never see. That list becomes the specification for every layout decision that follows. The Layout Manager in the Entity Manager is where these decisions are recorded. It controls the detail layout (the record view and its panels), the list layout (the columns in list views), the side panel layout (the summary fields and panels shown beside a record), the search filter layout (the filters available in list search) and the Kanban layout (the fields shown on cards for pipeline-style views). A team or portal needs its own layout when the same entity serves groups with different tasks or different visibility, for example when a partner portal must show a reduced set of account fields. Where a difference is about who may view or edit a field, confirm whether layouts alone are enough or whether role permissions must carry part of the rule.
Plan the work around the documentation for the version you run. EspoCRM 10.0.10 was the latest release listed in the supplied facts, and layout behavior, labels and menu paths can change between major versions, so confirm each step against the docs for your exact version before you build. The core references for this page are the EspoCRM server configuration, formula, API, import and security documentation, which cover the platform prerequisites, the data and automation that feed layouts, and the access controls that must match what a layout shows. Use the EspoCRM docs: Security reference early, because a field hidden in a layout is not the same as a field protected by a role. For the first working pass, choose one entity with two user groups that genuinely differ, build each layout in a non-production instance, and test with a test user from each group. Record what each group sees, what it cannot see, and which fields appear only through a role or a portal setting. Ask your implementation partner, or your own administrator, to confirm how layouts interact with portal roles and team assignments in your version. That check decides how many layouts you need and prevents a layout from becoming the only control over sensitive data.
Which layout type answers which team need
Detail layouts control the record view that people open to read or edit a single lead, account, opportunity or case. They decide which fields appear, how fields are grouped into panels and in what order. Because a sales owner and a service agent often need different fields on the same entity, detail layouts are the most common reason teams ask for separate configurations.
- What it changes: field placement, panel grouping and field order on one record.
- What it does not change: whether a user can read or edit a field. Field-level and record-level access stays with roles and teams.
- Typical team need: sales may want deal value and forecast fields near the top, while service may want case history and open tasks first.
- Portal effect: portal users see the detail layout assigned to their portal role, so internal-only fields can be left off that layout.
- Hidden is not secure: a field removed from a layout can still be reachable through the API or another view if the role allows it.
Before you rely on a hidden field for confidentiality, check the role permissions for that field and test the record through the API with a restricted user.
List layouts define the columns a user sees when browsing records of one entity type. Teams that work from the same entity often need different columns, such as an account manager who tracks renewal dates or a support lead who tracks priority and age. Configuring list layouts per team or portal keeps those views focused without creating separate entities.
- What it changes: which columns appear in the list and their order.
- What it does not change: which records appear in the list. Record visibility follows the role's scope and team assignments.
- Typical team need: a shared list of accounts can show owner and renewal columns for account managers and industry and region columns for marketing.
- Custom list layouts for reports: the outline for this topic includes list layouts used for reports and panels. Confirm in your version how a custom list layout is selected for a report or panel, since report behavior sits with the reporting features.
- Column count: wide lists are harder to scan and slower to load, so agree a column set with each team before building it.
Set up a test user for each team and confirm that the column set, sorting and record counts match what that team expects.
Side panels are the related sections shown alongside a detail view, such as related contacts, opportunities, activities or documents. A side panel layout decides which related lists appear, whether they are shown on the detail view and in what order. This lets each team keep the context it needs next to the record without scrolling through unused relationships.
- What it changes: which related lists appear beside a record and their order.
- What it does not change: the content of a related list is still filtered by permissions. A user cannot see related records they are not allowed to read.
- Typical team need: service agents may need open cases and recent emails beside an account, while sales may need opportunities and quotes.
- Layout per audience: side panels can be set per team or portal role, so the same entity can show different context to different groups.
- Dependencies: a side panel only works if the relationship exists on the entity, so confirm the relationships with the entity design first.
Ask an administrator to open a record as each team and verify that every panel loads, shows the expected records and stays empty where no relationship data exists.
Search filters determine which filter options a user can apply when searching a list, such as status, owner or region. Kanban views present records as cards grouped by a stage or status value so teams can see flow at a glance. Both are configuration choices that shape how people find and move work, and both should be designed around a team's daily routine.
- Search filters: change which filter options are offered, so a team sees the fields it actually searches on.
- Search filters do not change: the set of records a user is permitted to find. Results still follow role scope.
- Kanban boards: group records by a field, which should be a clear stage or status field with agreed values.
- Kanban writes: moving a card changes the grouping field, so the user needs edit permission and any before-save logic on that field still runs.
- Availability: confirm which entities and field types support Kanban and search filter options in your version, since support can differ by entity.
Test each board with a user who has limited permissions, and confirm that moving a card to another stage produces the saved value and the expected follow-up logic.
Portal users and reporting readers see the same data through different lenses. A portal user should see a customer-facing layout that matches the portal role, while reporting readers often need compact lists, grouped results and panels that summarize records. Layout choices for these audiences work best when they are designed together with the roles that govern access.
- Portal layouts: portal users are assigned layouts through their portal role, so the customer view can omit internal fields and sections.
- What portal layouts do not change: the data a portal user can access. Portal roles and record ownership still decide what is visible.
- Reporting readers: list layouts and panels can summarize records for managers, but report features depend on the Advanced Pack, which is included in the cloud plans and is an add-on for self-hosted editions.
- Layout drift: each portal and team layout is a separate configuration, so changes to a shared field need to be checked in every layout that uses it.
- Upgrade impact: layout settings can change between major versions, so review them during any upgrade plan.
Before you publish a portal, sign in as a test portal user and confirm which records, fields and panels appear and which do not, then compare the result against the portal role definition.
Layout options and when each fits
This table compares the main layout choices in EspoCRM: a shared default, team or role layouts, portal layouts, list layouts for reports and panels, and Kanban or filter settings. Read each row against your teams and portal users, then check the maintenance and over-customization risk before you add a second layout. The main takeaway is that every extra layout is a separate thing to keep aligned with fields, roles and upgrades.
| Option | Fits when | Maintenance it adds | Risk of over-customizing |
|---|---|---|---|
| Shared default layout | Most users see the same fields and the team structure is small | One set of field changes to review after each new field | Low, but busy screens if every team's fields are added here |
| Team or role-specific layouts | Sales, support and finance need different fields on the same entity | Each layout must be updated when fields or dynamic logic change | Users may miss a field that exists only in another team's view |
| Separate portal layouts | External customers or partners need a reduced view of records | Portal layouts need their own review alongside portal roles | Internal fields or data may appear to portal users if the layout is copied from internal use |
| List layouts for reports and panels | Users need columns tailored to a report, a dashboard panel or a related list | Each list layout must be checked when fields are renamed or removed | Wide lists slow scanning and are hard to read on small screens |
| Kanban and search filter settings | Pipelines or queues are managed by status, stage or owner | Status and stage values must stay aligned with the Kanban grouping field | Too many saved filters make the default view hard to find for new staff |
How to set up team and portal layouts step by step
This sequence moves from knowing who sees what to a tested set of default and variant layouts, so each team and portal user sees only the fields and records their role needs.
Inventory who sees which records
Start by listing every team, role and portal user type that opens EspoCRM records, along with the entities each group works in and the actions it performs. Compare this list with the roles, teams and portal roles already configured, since layouts only control presentation and do not replace access control. The output is a written matrix of user groups, entities and needed actions that the business owner signs off. Confirm with the client's administrator which portal users exist and which records they should never see.
Map fields and panels to each group
For each entity and user group in the matrix, decide which fields belong on the detail view, which belong in the list view, which should appear in the side panel and which search filters help that group find records. Note fields that only some groups should see at all, because a layout can display a field that the role's permissions block or that a portal role should never receive. The output is a field map per group, reviewed with one representative user from each team. Mark any field whose visibility depends on a condition so it can be handled with dynamic logic later.
Build the default layout first
In the Layout Manager, create the default detail, list, side panel, search filter and Kanban layouts for the entity that all internal users share. Keep the default conservative, with the fields most users need and no team-specific content, so that every variant is a deliberate deviation from a known baseline. The output is a working default layout that a tester can open on a record and confirm reads correctly. Record which settings you changed, since this list becomes the reference for later reviews and upgrades.
Add team and portal variants
Create variant layouts only for groups whose map from step two differs from the default, assigning each one to the correct team or portal. Use a separate layout for each portal where the portal's users need a different view, and reserve custom list layouts for reports and panels that need a fixed set of columns. The output is a documented list of variants with the group each one serves and the reason it differs. Review the variants against the field map so no group is left on a layout that exposes content it should not see.
Test as each internal role
Sign in as a test user for each internal role and team, open records in each entity, and check that the detail, list, side panel, search filters and Kanban views match the field map. Also confirm that records outside the user's team do not appear in lists, which tests access control rather than layout. The output is a completed test sheet with a pass or fail result for each group and view. Fix any mismatch in the layout, then repeat the test for the changed group.
Test as portal users
Sign in as a portal user for each portal, using test accounts that match real portal roles. Confirm that restricted fields stay hidden even where a layout shows them, that portal users cannot reach records outside their scope and that list columns or panels do not reveal internal notes or related records. The output is a signed-off portal test result that records each check and its outcome. If a field appears when it should not, treat it as an access issue to fix in portal roles before changing the layout again.
Validate changes on a non-production instance
Apply the completed layouts and any related metadata changes first to a non-production copy of the EspoCRM instance, and repeat the internal and portal tests there. Export the layout configuration so the change can be reapplied to production in a controlled way, and check that the target environment runs the same EspoCRM version as the tested copy. The output is a tested change package and a rollback note. Confirm the production change window and the person who approves it before any change goes live.
Roll out and confirm in production
Apply the tested layouts to production during the agreed change window, then sign in with one test account per group and repeat a short set of checks on each detail and list view. Watch for user feedback in the first working period and log any field that users report as missing or wrongly visible. The output is a production sign-off record and a backlog of follow-up adjustments, owned by a named administrator. Schedule a review of layouts whenever the EspoCRM version or the team structure changes.
Security and operational risks of layout changes
A layout decides what users see, not what they are allowed to do. The cards below cover the places where a layout change can create exposure or break after maintenance, and the checks to run before a layout reaches production.
Layouts do not replace role permissions
A layout can hide a field from a form, but the field still exists in the data model and can be reached through the API, exports or another view if the role allows it. Field names shown in a layout can also reveal internal structure to users who should not see it. Before release, check each role's field-level and scope permissions directly, then confirm the layout matches what those permissions already allow. Hiding a field in a layout is a display choice, not an access control.
Portal users need separate review
Portal layouts are shown to external customers or partners, so they need their own review cycle. A layout that is safe for internal sales staff may expose internal notes, pricing fields or relationship panels to portal users. Review each portal layout with the portal role open, using a test portal account that represents each customer type. Repeat the review whenever a portal role or a related entity changes.
Test views with non-admin accounts
Admin accounts see fields and actions that day-to-day users do not, so a layout tested only as admin can look correct while failing for sales, support or portal staff. Use dedicated test users with the same roles and teams as production users. The EspoCRM security guidance also recommends avoiding admin accounts for daily work, which keeps the testing identity separate from the operating one.
Protect admin access with 2FA and IP limits
Layout changes are made by administrators, so admin accounts are the most valuable target for anyone who wants to alter what users see or export. The security guidance recommends requiring two-factor authentication, enforcing a password policy and restricting access by IP address. Note that EspoCRM's own 2FA is not compatible with OIDC sign-in, so confirm the identity provider's MFA policy covers admin sign-ins if you use single sign-on.
Layouts change during upgrades
Layouts are metadata, and they can change when EspoCRM core or an extension is updated. New fields, renamed fields or changed defaults can appear in layouts you customized, and extension updates can add panels or buttons that were not in your review. Keep a list of every custom layout, record the version it was tested on, and repeat the portal and role review after each upgrade. Confirm the upgrade path with your vendor or in the release notes, since upgrades through the UI are disabled by default as of version 10.0.
Questions teams ask before customizing EspoCRM layouts
How much effort does EspoCRM layout work take?
Effort depends on how many teams, portals, entity types and reports need their own layouts, so there is no single fixed amount. Each combination of entity, team or portal, and view (detail, list, side panel, search filter and Kanban) is a separate configuration that must be designed, tested and documented. The initial design is a one-time cost, while changes recur whenever teams reorganize, new fields arrive or a portal is added. Ask any quote to list the entity types, the team and portal count, the views per entity, the report layouts in scope and the number of test rounds included. DeployOpen does not publish prices. A written scope sets the fee before work starts.
Can an internal admin customize EspoCRM layouts alone?
Yes, for simple changes. An administrator can rearrange detail and list layouts, adjust side panels and edit search filters, so a single team working with a few entities is often manageable in-house. Outside help adds the most value when layouts must differ by team or portal, when they depend on field-level access, or when the business needs a repeatable test process. Before deciding, confirm that your admin has time to test each layout with real user roles, can keep a record of every change, and will own the layouts after handover.
What must we provide before layout work starts?
A partner needs a few inputs to scope layout work accurately:
- A role matrix showing which teams and portal roles should see which entities, fields and actions.
- A field list for each entity, with the owner of each field and whether it is required.
- Sample users for each team and portal, so every layout can be tested as the person who will use it.
- Screenshots or notes on the current screens, with the problems users report.
- A list of the reports and panels that depend on list layouts, since those layouts are often the hardest to get right.
Missing inputs usually become scope changes later, so settle them in the written scope.
Do EspoCRM layouts survive version upgrades?
Layouts are configuration stored in your instance, so they normally carry through an upgrade, but a new release can add fields, views or defaults that change what users see. The EspoCRM security documentation notes that upgrading through the UI is disabled by default as of version 10.0, so upgrades are run through the command line and should be rehearsed first. Plan a staging copy, retest every layout for every role and portal after the upgrade, and check the release notes for the target version. Confirm the exact upgrade steps for your version with EspoCRM before scheduling.
Will extensions break when we change EspoCRM layouts?
They can. Extensions that add fields, panels or views refer to field and layout names, so renaming or removing a field in a layout can break an extension's screens. Keep custom layouts in your own instance, separate from extension-owned definitions, and record which extension depends on which field. Before upgrading, check each extension's version range against the EspoCRM version you are moving to. Confirm the compatibility and layout dependencies with the extension's author, and retest any screen the extension adds after each layout change.
Do report list layouts need the Advanced Pack?
Report features belong to the Advanced Pack, an official add-on that EspoCRM describes as providing reports, Business Process Management and workflows. The pack is included in all EspoCRM Cloud plans. For a self-hosted instance, the open-source edition is free to download and run, but the pack is a separate add-on, so confirm its current terms before you design report-based layouts. Standard detail, list, side panel, filter and Kanban layouts do not depend on the pack. Check the Advanced Pack page and confirm with EspoCRM which features your edition includes.
How do we test layouts for each team and portal?
Test every layout as each role that will use it, in a staging copy of the instance. For each team and portal, check the detail view, list view, side panel, search filter and Kanban board, and confirm that the fields a user should see are visible and the ones they should not see are hidden. Portal users need separate checks because their access differs from internal users. Record the results, fix the gaps, and obtain written sign-off from the business owner before the layouts go to production. Ask any quote to include this test step and state how many rounds it covers.
Limits to confirm in your environment
Layout work in EspoCRM depends on details that vary by version, edition and how your teams are structured. The cards below list what to verify with the vendor documentation and a test instance before you fix a layout design, so the build plan rests on confirmed behavior rather than assumptions.
Layout types in your version
Confirm which layout types exist in the exact EspoCRM release you will run, including detail, list, side panel, search filter and Kanban layouts. Layout options and the way they are edited have changed across major versions, so check the admin documentation for that release. Record the result in a short matrix that names each entity you plan to customize, because not every entity type exposes every layout. Ask the vendor docs for the exact layout list before drafting any design.
Per-team and per-portal layout options
Confirm whether a layout can be assigned per team, per portal or per user type in your version, and whether a single entity can carry several variants at the same time. Test a sample user from each team and a portal user to see which layout actually renders. If assignment is limited, your design may need separate entities or shared layouts with dynamic logic instead of separate layouts.
Advanced Pack dependency for report lists
Confirm whether the list layouts you need for reports, grids and panels depend on the Advanced Pack. The Advanced Pack provides reports and workflows and is included in all EspoCRM Cloud plans, so cloud buyers and self-hosted buyers face different questions. Self-hosted teams should check the extension page and their installation before assuming report-based panels work without it.
Layout behavior after major upgrades
Confirm how custom layouts, extension-provided fields and layout overrides are carried through a major upgrade. EspoCRM 10.0.0 was released on July 2, 2026, after 9.0.0 on January 20, 2025, and the security docs note that UI upgrades are disabled by default as of version 10.0. Test your layouts on a copy of production with the target version before scheduling the upgrade, and keep a written list of every layout change.
Maintenance capacity for layouts
Estimate how many layouts your administrators can maintain after go-live. Each entity, team and portal variant adds a layout to review at every release, and each new field must be placed in several views. Ask your partner for a quote that lists the number of layout variants in scope, and agree who owns changes after handover. Limit variants to the teams that truly need a different view.
Test instance and rollback
Confirm that you can clone production data and configuration into a test instance and roll back layout changes if a view breaks for a team. Layout changes are configuration, so keep an export of the metadata before each release and document the steps to restore it. Without a tested rollback, a faulty Kanban or detail layout can block a sales team during working hours.
When a layout project needs outside help
A partner earns its place when layout work touches several teams with overlapping access rules. In EspoCRM, a detail layout, list layout or Kanban layout can be set per team or per portal, but the visible result also depends on role permissions, team membership and field-level access. A sales team, a service team and a partner portal may each need a different detail view of the same account, and a change made for one group can quietly hide a field another group depends on. Before any layout is built, map each team against its roles, the fields it must see or edit and the records it should never reach. Then test the combinations in a non-production instance with a test user from each group. This mapping is the step most internal projects skip, and it is where outside experience shortens the work most.
Portal layouts are the second case. A portal is only useful when its pages follow the customer service workflow it supports: which request types a customer can raise, which status fields they can read, and which attachments and replies they can see. Designing that means deciding which entities are exposed to portal users, how portal roles limit them and which list filters and search filters keep their view narrow. Confirm with your service owners which steps are in scope before any layout is drafted, and confirm whether the portal design depends on Advanced Pack features, since those are included in all EspoCRM Cloud plans and must be licensed or deployed separately for self-hosted instances.
The third case is durability. Layouts are stored as metadata, and that metadata has to survive the next upgrade and any extension packaging. Keep layout changes in a documented, repeatable form rather than as one-off edits, and record which custom fields, panels and list columns each layout depends on. Ask any partner to show how they will package and version those changes, and how they will retest the layouts after a major release. The EspoCRM releases page is the reference for version timing. Confirm with your own team who will own the layouts after handover, because a layout no one maintains tends to drift from the workflows it was built for.
