EspoCRM System Guide

• Getting Oriented
• About This Guide & the CBM CRM Setup
• Signing In & the Administration Panel
• Users, Roles & Access
• Managing Users
• Roles, Teams & Permissions
• Configuration & Customization
• System Settings & the Navigation Menu
• Making Configuration Changes
• List Sort Order & Search Fields
• Managing Data
• Importing & Exporting Records
• Duplicates, Mass Updates & Cleanup
• Integrations
• Google, Email & Website Integrations
• The Documentation Site
• Operations & Maintenance
• Backups & Updates
• Routine Maintenance & Monitoring
• Change Log
• Troubleshooting, Recovery & Reference
• Troubleshooting & Recovery
• Environments & Where Things Live
• Getting Help and Next Steps

Getting Oriented

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

1. Open the CRM in your browser:
   • Production: https://crm.clevelandbusinessmentors.org
   • Sandbox: https://crm-test.clevelandbusinessmentors.org
2. Enter your administrator username and password.
3. 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 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

1. Administration → Users → Create User.
2. Enter their name, User Name, and Email Address.
3. Set the Teams and Roles that match their job — this is what controls what they can see and do (see Roles, Teams & Permissions).
4. Decide whether they're an administrator (usually no).
5. 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

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

1. Describe the change — what field/layout/record type, on which record, and why.
2. Make it in the Sandbox first (via the configuration files / implementation tool) and verify it.
3. Review with whoever requested it.
4. 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

1. Sign in to EspoCRM as an administrator.
2. Open the Administration menu (top-right).
3. Click Entity Manager.
4. Click the record type you want to change (for example, Contact).
5. Click Edit.
6. 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.
7. Click Save.
8. 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 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.

1. Choose the record type and upload your file (CSV).
2. Map each column to a field. Getting this wrong writes data into the wrong place.
3. Match by a field (often email) so existing records are updated rather than duplicated.
4. Set the options (e.g. how to treat existing values) and run the preview.
5. 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 & 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

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

Troubleshooting & Recovery

First steps for any problem

1. Is it just you? Try another browser or an incognito window, or ask a second user.
2. Which environment? Confirm you're in Production vs. Sandbox.
3. 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.