EspoCRM System Guide

Getting Oriented
What this guide covers, the CBM CRM at a glance, and how to sign in as an administrator.

About This Guide & the CBM CRM Setup
Who this guide is for
This guide is for the CBM CRM administrator — the staff member(s) responsible for keeping the Cleveland Business Mentors CRM running smoothly day to day: adding and removing users, adjusting settings, importing data, and handling the occasional problem.
It assumes you're comfortable using web applications, but not that you're a server or database expert. Where a task is genuinely technical (server upgrades, recovery), this guide summarizes it and points you to the right person or runbook rather than asking you to do it yourself.
If you're a mentor or a member of the Client Administration or Mentor Administration teams, the guides on the other shelves are for you — this one is specifically about administering the system.
What the CBM CRM is
The CRM is the central system that holds CBM's people and activity — mentors, clients, the engagements that pair them, the sessions they hold, and the supporting records around them. As administrator, you don't change what the CRM tracks day to day; you keep the system healthy and help users get their work done.
Two environments: Production and Sandbox
There are two copies of the CRM, and knowing which is which is the single most important thing in this guide:
Address
What it is
Production
crm.clevelandbusinessmentors.org
The real, live system. Everyone's actual work and real data live here.
Sandbox
crm-test.clevelandbusinessmentors.org
A safe copy for trying things out. Nothing here affects real data.
The golden rule: when you're about to make a change that isn't routine — a settings change, a configuration tweak, a bulk data operation — try it in the Sandbox first, confirm it does what you expect, then do it in Production. Chapter 3 — Configuration & Customization covers this sandbox-first workflow in detail.
How the system is maintained
A few things are handled outside the CRM's own screens, so you don't have to:
Configuration (custom fields, layouts, new record types) is applied through CBM's implementation process and tooling, not hand-edited in Production. See Chapter 3 — Configuration & Customization.
The server, hosting, backups, security certificates, and software upgrades are managed at the infrastructure level. You don't log into servers; Chapter 6 — Operations & Maintenance explains what's automated and who handles the rest.
What's in this guide
Chapter 2 — Users, Roles & Access: add and remove users; manage who can see and do what.
Chapter 3 — Configuration & Customization: settings, the navigation menu, and the sandbox-first change process.
Chapter 4 — Managing Data: importing, exporting, duplicates, and cleanup.
Chapter 5 — Integrations: Google, email, the website, and this documentation site.
Chapter 6 — Operations & Maintenance: backups, updates, and routine upkeep.
Chapter 7 — Troubleshooting, Recovery & Reference: fixing problems, recovery options, and where everything lives.
When in doubt, slow down. Most administrative actions are easy to reverse, but a few (bulk deletes, resets) are not. If a task in this guide carries a warning, take it seriously — and if you're unsure, see Getting Help and Next Steps at the end of the guide.

Signing In & the Administration Panel
Signing in as an administrator
Open the CRM in your browser:
Production: 
https://crm.clevelandbusinessmentors.org
Sandbox: 
https://crm-test.clevelandbusinessmentors.org
Enter your administrator username and password.
You'll land on a dashboard like any user — your administrator access simply adds an extra Administration area.
Administrator accounts can change settings and see everyone's data. Keep your credentials secure, never share the admin login, and give each person their own account (see Chapter 2 — Users, Roles & Access) instead of sharing one.
Opening the Administration panel
Click your avatar / initials in the top-right corner, then choose Administration. (Only users with admin access see this option.)
The Administration page is a grid of labeled sections. You won't need most of them often — here are the ones this guide uses, and where each is covered.
The areas you'll use
Users and access
Users — the people who can sign in. (Chapter 2)
Teams — groups used to organize people and control visibility. (Chapter 2)
Roles — what a user or team is allowed to see and do. (Chapter 2)
System and customization
Settings — system-wide options. (Chapter 3)
User Interface — the navigation menu / tab list, including the Documentation tab. (Chapter 3)
Entity Manager / Layout Manager — the structure of records and forms. Changed through the sandbox-first process, not casually here. (Chapter 3)
Label Manager — the wording shown around the interface. (Chapter 3)
Data
Import — bring records in from a spreadsheet. (Chapter 4)
Email
Outbound Emails, Email Accounts, Email Templates — how the CRM sends mail. (Chapter 5)
Maintenance
Scheduled Jobs, Jobs, Auth Tokens — background tasks and sessions; mostly informational. (Chapter 6 – Chapter 7)
A note on the powerful areas: Entity Manager, Layout Manager, and the bulk data tools can change the CRM for everyone at once. Treat them as read-only until you've read the chapter that covers them — and remember the golden rule: Sandbox first.
Finding your way back
Wherever you are in Administration, the CBM logo (top-left) returns you to the main CRM, and the avatar menu → Administration brings you back here.

Users, Roles & Access
Managing who can sign in and what they can see and do.

Managing Users
What a user is
Anyone who signs into the CRM has a user record. Each person should have their own account — never a shared login. Individual accounts keep the activity history accurate (who logged which session, who changed what) and let you remove someone's access cleanly when they leave.
Types of user
Type
Who it's for
Regular user
Staff and mentors who sign in and do everyday work.
Administrator
Can reach the Administration panel and change system settings. Grant this to as few people as possible.
API user
Non-human accounts used by integrations (e.g. the website or documentation tooling). You'll rarely create these.
Portal user
External people using a limited portal, if CBM uses one.
Adding a user
Administration → Users → Create User.
Enter their name, User Name, and Email Address.
Set the Teams and Roles that match their job — this is what controls what they can see and do (see Roles, Teams & Permissions).
Decide whether they're an administrator (usually no).
Save — then either set a password or have the CRM email them a setup link (recommended if email is configured).
Get teams and roles right at creation time. They govern the user's access; skip them and the person may see far too much or too little.
Resetting a password
Open the user → Actions / ⋮ menu → Change Password, or
Have the person use "Forgot password?" on the login screen (requires outbound email — see Chapter 5 — Integrations).
When someone leaves: deactivate, don't delete
Open the user and turn Is Active off. This blocks sign-in but keeps all their history intact and correctly attributed.
Avoid deleting users — deletion can orphan or reassign the records they created. Deactivating is almost always the right move.
Deactivate first. You can always reactivate; undoing a delete is far harder.

Roles, Teams & Permissions
The two halves of access
EspoCRM controls access with Roles and Teams, working together:
Roles decide what a user can do — which record types they can see, create, edit, or delete, plus any administrative abilities.
Teams decide whose records a user can see — records are shared with teams, and members of a team can see them.
A user can hold several roles and belong to several teams; their effective access is the combination.
Roles
Administration → Roles.
A role grants permissions per record type (Contacts, Engagements, Sessions, …) — typically None / View / Edit / Create / Delete — and a scope (all records, just their team's, or just their own).
CBM's roles are already set up to match job functions. Prefer assigning an existing role over inventing new ones.
Least privilege: give people the access their job needs and no more. Widening access later is easy; clawing it back after data has been over-exposed is not.
Teams
Administration → Teams.
Teams group users and act as the unit of record sharing.
Add someone to a team from either the user record or the team record.
How they combine — an example
A mentor holds the Mentor role (view/edit engagements for their team, no delete) and belongs to the team that owns their engagements → they see and update their engagements and session notes, and nothing else.
Changing roles or teams safely
A role or permission change affects everyone with that role at once.
Test in the Sandbox first (the golden rule from Signing In & the Administration Panel): confirm a typical user sees exactly what you intend, then apply in Production.
After the change, spot-check with a real user in that role.
Permission changes that broaden access can expose data unintentionally. Treat them like configuration changes (Chapter 3), not casual edits.

Configuration & Customization
System settings, the navigation menu, and the sandbox-first process for configuration changes.

System Settings & the Navigation Menu
System Settings
Administration → Settings holds system-wide options. The ones you might reasonably touch:
Application name, time zone, date & number formats, week start, default currency, language — locale and cosmetic defaults.
Outbound email basics — covered in Chapter 5 — Integrations.
Most settings apply immediately and are safe to adjust. If a setting mentions caching, performance, or "developer" options and you're unsure, leave it — and Sandbox-test anything you're uncertain about.
The Navigation Menu (Tab List)
The left sidebar is the Tab List: Administration → User Interface → Tab List.
Add or remove tabs, drag to reorder, and group them with dividers.
This is where the Documentation tab lives — a URL tab pointing at the docs site (see The Documentation Site).
To add an external link: Add → URL, set the label and URL, drag into place, Save. (CBM's external tabs are set to open in a new browser tab via a small customization.)
The Tab List you edit here is the default for everyone. Individual users can further customize their own tabs in their preferences.
Dashboards
The dashboard is the landing page of tiles ("dashlets"). You can set a sensible default layout; users can rearrange their own.
Wording (Label Manager)
Administration → Label Manager changes the words shown in the interface without changing the underlying configuration. Use it sparingly and Sandbox-test — a relabel that drifts from training or these guides confuses users.
What does not belong here
Changing fields, layouts, or record types is not done casually in this area — it follows the sandbox-first process in Making Configuration Changes.

Making Configuration Changes
Two kinds of change
Data — adding records, fixing values, importing. Everyday work; see Chapter 4 — Managing Data.
Configuration / structure — new fields, changed layouts, new record types, dropdown options, validation, relationships. This follows a defined process.
Why configuration is special
The CBM CRM's structure is defined as versioned configuration files and applied with CBM's implementation tooling, so the system can be rebuilt or moved reliably and every change is tracked. If you hand-edit structure directly in Production (via Entity Manager or Layout Manager), those changes:
aren't recorded in the configuration source, so they can be lost in a rebuild or upgrade, and
drift between Sandbox and Production.
The sandbox-first process
Describe the change — what field/layout/record type, on which record, and why.
Make it in the Sandbox first (via the configuration files / implementation tool) and verify it.
Review with whoever requested it.
Apply to Production the same way, once confirmed.
This is the golden rule in its most important form. Structural changes affect everyone at once and are the easiest way to break things — never make them straight in Production.
Safe to do in the interface
Adding and editing records (data) — Chapter 4.
Settings, the Tab List, dashboards, labels — System Settings & the Navigation Menu.
Users, roles, teams — Chapter 2.
Goes through the process (don't do casually in Production)
New or changed fields
New record types / entities
Dropdown options, validation rules, relationships between records
Who to involve
Configuration changes are made with the implementation tooling and, where needed, the CBM implementation team. If you're unsure whether something is "just data" or "configuration," treat it as configuration and check — see Getting Help and Next Steps.

List Sort Order & Search Fields
For each type of record (Contact, Account, Mentor Profile, and so on), you can set how its list is ordered by default and what its search box looks at. These are simple administrator settings — no coding involved, and they never change any of your data.
What you can set
Order By — the field the list is sorted by when you open it.
Sort Direction — Ascending (A→Z, oldest first) or Descending (Z→A, newest first).
Text Filter Fields — the fields the quick-search box searches when someone types in it.
Full-Text Search — the deeper "search everything" mode, on or off.
Full-Text Search Min Length — (optional) how many letters someone must type before full-text search starts.
How to change them
Sign in to EspoCRM as an administrator.
Open the Administration menu (top-right).
Click Entity Manager.
Click the record type you want to change (for example, Contact).
Click Edit.
Set the boxes you want:
Order By — choose the field to sort by.
Sort Direction — Ascending or Descending.
Text Filter Fields — choose the fields the search box should search.
Full-Text Search — tick to turn it on.
Full-Text Search Min Length — leave blank, or enter a number.
Click Save.
If you are prompted, go to Administration → Rebuild to finish applying the change.
How to check it worked
Open that record type's list from the navigation menu. It should now be sorted the way you chose, and typing in the search box should look at the fields you picked.
Good to know
These settings only affect ordering and searching — no records are changed.
If you are not sure, leave a box at its default.
If your CRM is maintained through the CRM Builder tool, these same five settings can be set there and published to EspoCRM automatically — check with whoever maintains the CRM.

Managing Data
Importing, exporting, and cleaning up records safely.

Importing & Exporting Records
Exporting
Open any list view (e.g. Contacts), filter if you like, select records (or all), then Export.
Choose the format (CSV or XLSX) and which fields to include.
Exports are useful for reporting, a quick safety copy before a risky change, or prepping data for re-import.
Exported files often contain personal information. Store them responsibly and delete working copies when you're done.
Importing
Administration → Import.
Choose the record type and upload your file (CSV).
Map each column to a field. Getting this wrong writes data into the wrong place.
Match by a field (often email) so existing records are updated rather than duplicated.
Set the options (e.g. how to treat existing values) and run the preview.
Import.
Always test a real import first — in the Sandbox, or with just a handful of rows in Production — before running a big one. A wrong mapping or match field can create hundreds of duplicates or overwrite good data. Keep the source file so you can correct and re-run.
Tips for clean imports
Tidy the spreadsheet first: consistent dates, phone formats, no stray columns.
Use a stable match field (email is common) to update instead of duplicate.
Import related records in dependency order — the thing being referred to before the thing that refers to it.

Duplicates, Mass Updates & Cleanup
Finding & merging duplicates
The CRM flags likely duplicates when records are created, and you can hunt for them with filtered/sorted list views (by name or email).
To merge: select two or more records in a list → Merge → choose which values to keep → confirm. Merging combines them into one and preserves their links.
Merging is not easily undone. Double-check you're merging the right records and keeping the right values.
Mass updates
Select records in a list view → Mass Update → choose the field(s) and the new value → apply to all selected.
Handy for bulk reassignment, status changes, or team changes.
A mass update changes every selected record at once. Check your filter and selection before applying. Sandbox-test anything large or unfamiliar.
Mass delete
Select records → Remove.
⚠️ Deletion is the most dangerous bulk action. Confirm the exact filter and selection. Prefer deactivating or closing records where the record type allows it. For anything beyond a few obvious junk rows, Sandbox-test the exact filter first and take an export as a backup immediately before deleting.
If you delete something by mistake
Stop making changes. Recovery usually means restoring from backup, which is time-sensitive — the sooner you raise it, the more recoverable it is. See Troubleshooting & Recovery and Getting Help and Next Steps right away.

Integrations
Google, email, the website, and this documentation site.

Google, Email & Website Integrations
Some specifics below depend on how CBM's integrations are configured. Where you see "as configured," confirm the detail for your setup (or ask — see Getting Help and Next Steps).
Configuring System Email- (Allows sending new user email, forgot password and system notifications.)
Google (Gmail, Calendar, Contacts)
The CRM connects to Google so that email, calendar, and/or contacts work together (as configured). The most common admin task is re-authorizing when the connection drops — typically after a password change or when a sign-in token expires.
Administration → Integrations → Google for the system connection; individual Gmail/Calendar links live under each user's preferences.
If users report email or calendar not syncing, check the integration status and re-authorize (sign in and approve again with the CBM Google account).
If re-authorizing keeps failing, the underlying Google API credentials may need attention — that's a technical step; see Getting Help and Next Steps.
Outbound email
Administration → Outbound Emails controls how the CRM sends mail.
Quick check: trigger a password reset or notification and confirm it arrives.
If the CRM stops sending email (resets, notifications), outbound email settings or the Google connection are the usual causes.
Inbound email
If configured, the CRM can capture incoming email under Email Accounts / Group Email Accounts.
The website
CBM's public website connects to the CRM (as configured — e.g. intake forms creating records). If website-submitted data stops arriving, that integration and its API user are where to look.
The documentation site
The Documentation tab links to this site — see The Documentation Site.

The Documentation Site
What this site is
The documentation you're reading lives on a separate documentation site at 
docs.clevelandbusinessmentors.org, independent of the CRM. It's organized as Shelves → Books → Chapters → Pages, grouped by audience:
Start Here — CRM Introduction Guide (for everyone)
Mentor Documentation — Mentor Guide
Staff & Administration — Client Administration Team Guide, Mentor Administration Team Guide
System Administration — this guide
The Documentation tab
Both the Production and Sandbox CRMs have a Documentation tab in the sidebar that opens this site in a new browser tab. See System Settings & the Navigation Menu for how that tab is set up.
Who can read it
The site is publicly readable — no login needed — so anyone with the link can reach the guides. Editing requires a login.
Editing content
Sign in to edit. Pages can be written in a visual editor or Markdown, and every page keeps a full revision history, so any change is reviewable and reversible.
Keep the guides aligned with the CRM: when a screen or process changes, update the matching page.
How it's hosted & maintained
The site runs on its own small server, separate from the CRM, with automatic HTTPS.
Full deploy and maintenance details live in the CBM repository runbook 
infrastructure/CBM-Documentation-Site.md, summarized in Chapter 6 — Operations & Maintenance.

Operations & Maintenance
Backups, updates, and routine upkeep.

Backups & Updates
Backups
The CRM's data must be backed up regularly so it can be restored after a mistake or a failure.
Know your backup status. Confirm with whoever maintains the servers what is backed up, how often, where it's kept, and — crucially — that a restore has actually been tested. A backup you've never restored is a hope, not a backup.
Before any risky operation (bulk delete, large import, configuration change), a quick export of the affected records is a personal safety net — see Chapter 4 — Managing Data.
Software updates
EspoCRM and its extensions receive updates. They are applied Sandbox first, verified, then Production — using CBM's deployment tooling, never hand-edited on the server.
Don't chase the newest release the day it ships; let it settle and update deliberately.
Updates are a technical operation. As the staff admin you generally request and coordinate an update rather than perform it. The mechanics live in the deployment runbooks (the CRM Builder tool and the CBM repository). See Getting Help and Next Steps.
Security certificates (HTTPS)
The 
https:// certificates for the CRM and the docs site renew automatically — nothing to do. The only exception: if a browser warns about an expired or invalid certificate, flag it (see Troubleshooting & Recovery).
Where the technical details live
Server / deploy / upgrade / recovery procedures → the CRM Builder tool and the CBM repository runbooks.
Documentation-site specifics → 
infrastructure/CBM-Documentation-Site.md in the CBM repository.

Routine Maintenance & Monitoring
A simple routine
A short, regular check keeps surprises away.
Weekly-ish
Confirm email is sending (a password reset or notification arrives).
Confirm Google / calendar sync is current, if CBM relies on it.
Glance at new users and access, and deactivate anyone who has left.
Monthly-ish
Skim for duplicate or junk records and tidy up — see Duplicates, Mass Updates & Cleanup.
Confirm backups are running and recent — see Backups & Updates.
Note any pending updates to schedule.
Signs something needs attention
Users report can't log in, missing records, or email not sending.
A certificate warning on the CRM or docs site.
The CRM is slow or unreachable.
For any of these, go to Troubleshooting & Recovery.
Background jobs
EspoCRM runs scheduled background jobs (notifications, email checks, cleanup) automatically. Administration → Scheduled Jobs lists them. If time-based things — reminders, scheduled emails — stop happening, that's a sign the background runner needs attention; flag it.

Change Log
A record of notable maintenance and configuration changes made to the CBM production CRM. The test/dev instance (
crm-test.clevelandbusinessmentors.org) is the source of truth for configuration; production is kept in sync with it.
2026-06-24 — Production brought into parity with test/dev
A review found several differences between the production CRM and the canonical test configuration. Production was reconciled to match. User-visible results:
Create/edit forms are complete. The Contact and Mentor Profile forms were missing fields; all fields now appear and accept input.
Field and relationship names corrected. A few custom fields and links had slightly wrong internal names (a missing or duplicated leading letter); these were corrected so data and relationships line up with test.
One-to-one relationships restored. Several links that should connect to a single record (e.g. a Mentor Profile to one Contact, an Account to one Primary Contact) had become "to-many"; they were restored to single-record links.
Mirror fields restored. Read-only fields that display a value from a linked record (e.g. a mentor's Contact City / Phone / Personal Email) were recreated.
All custom entities now match test for fields, relationships, and forms. The CRM Builder tool that deploys configuration was also corrected, so future updates carry these names and relationships faithfully and won't reintroduce the differences.
Configuration changes are made on test first, then applied to production — never directly on production except for one-off corrections like this one.

Troubleshooting, Recovery & Reference
Fixing problems, recovery options, and a quick reference of where everything lives.

Troubleshooting & Recovery
First steps for any problem
Is it just you? Try another browser or an incognito window, or ask a second user.
Which environment? Confirm you're in Production vs. Sandbox.
Recent change? If the problem began right after a change, that change is the prime suspect — and structural changes should have been Sandbox-tested first.
Common problems
Symptom
Likely cause / first fix
A user can't sign in
Account inactive or wrong password — check the user and reset it (Managing Users).
Reset / notification emails not arriving
Outbound email or the Google connection — see Chapter 5 — Integrations.
Calendar / Gmail not syncing
Google authorization expired — re-authorize (Google, Email & Website Integrations).
Someone sees too much or too little
Role or team misconfigured — Roles, Teams & Permissions.
Records "missing"
Usually a filter or permission, not deletion — clear filters and check the user's role; if truly deleted, act fast (below).
Certificate warning in the browser
Flag it — see Backups & Updates.
CRM slow or unreachable
May be the server — escalate (below).
If data was deleted or badly changed
Stop making changes. The fix is usually to restore from backup — a technical, time-sensitive operation. The sooner you raise it, the more recoverable it is. See Getting Help and Next Steps.
Recovery operations (technical — usually not you)
The deployment tooling can perform powerful recovery actions, listed here just so you know they exist:
Admin credential reset — regain admin access if locked out.
Full reset / rebuild — tears the instance down and rebuilds it. This destroys data and is only safe with a good, recent backup.
⚠️ These are destructive, technical operations run via the CRM Builder tool by whoever maintains the deployment — not routine admin tasks. Never run a "full reset" to fix an everyday problem. If you think recovery is needed, escalate.
When you escalate
Note exactly what you did, what you expected, what happened, the time, and the environment. Technical logs (server and API) are available to whoever maintains the deployment.

Environments & Where Things Live
Environments
Environment
Address
Purpose
Production CRM
crm.clevelandbusinessmentors.org
The live system
Sandbox CRM
crm-test.clevelandbusinessmentors.org
Safe testing copy
Documentation site
docs.clevelandbusinessmentors.org
These guides (public)
Where things live  (pointers — no secrets here)
Thing
Where
CRM configuration (fields/layouts/record types, as files)
The CBM repository + the CRM Builder tool
Deploy / upgrade / recovery procedures
The CRM Builder tool + CBM repository runbooks
Documentation-site deploy & maintenance
infrastructure/CBM-Documentation-Site.md (CBM repository)
Credentials & connection settings
A secure store (password manager / the deployment tool's secret storage) — never in documentation or spreadsheets
Account & recovery information
The CBM repository's secure account-information area
This guide never contains passwords, keys, or secrets — and neither should any page you add. Record where a credential lives, never what it is.
Key tools & people
CRM Builder tool — provisions, configures, upgrades, and recovers the CRM.
The CBM implementation team / deployment maintainer — for configuration changes and technical operations (see Getting Help and Next Steps).

Getting Help and Next Steps
Handle it yourself, or escalate?
Do it yourself
Adding and deactivating users; password resets
Settings, Tab List, and dashboard tweaks
Data imports and cleanup (Sandbox-tested); tidying duplicates
Escalate
Configuration / structure changes (Chapter 3)
Server or deployment issues; anything destructive (resets)
Suspected data loss
Persistent integration failures (email, Google, website)
How to get help
For configuration changes and technical / deployment issues, contact the CBM implementation team / deployment maintainer.
When you ask for help, include: what you were doing, what you expected, what happened, the time, and the environment (Production or Sandbox).
To be filled in: CBM's actual support contact(s) and any ticket/escalation path. Left generic on purpose — provide the names/addresses and they'll be slotted in here.
The other guides
CRM Introduction Guide — start here, for everyone
Mentor Guide — for mentors
Client Administration Team Guide and Mentor Administration Team Guide — for staff teams
(You're in the System Administration guide.)
Keep this guide current
When the CRM changes, update the matching page here — editing is covered in The Documentation Site. Good documentation is maintained, not written once.