# 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](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/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](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/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](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/operations-maintenance) explains what's automated and who handles the rest. ## What's in this guide - **[Chapter 2 — Users, Roles & Access](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/users-roles-access):** add and remove users; manage who can see and do what. - **[Chapter 3 — Configuration & Customization](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/configuration-customization):** settings, the navigation menu, and the sandbox-first change process. - **[Chapter 4 — Managing Data](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/managing-data):** importing, exporting, duplicates, and cleanup. - **[Chapter 5 — Integrations](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/integrations):** Google, email, the website, and this documentation site. - **[Chapter 6 — Operations & Maintenance](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/operations-maintenance):** backups, updates, and routine upkeep. - **[Chapter 7 — Troubleshooting, Recovery & Reference](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/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](https://docs.clevelandbusinessmentors.org/link/60) 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](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/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](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/users-roles-access))* - **Teams** — groups used to organize people and control visibility. *([Chapter 2](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/users-roles-access))* - **Roles** — what a user or team is allowed to see and do. *([Chapter 2](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/users-roles-access))* **System and customization** - **Settings** — system-wide options. *([Chapter 3](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/configuration-customization))* - **User Interface** — the navigation menu / tab list, including the **Documentation** tab. *([Chapter 3](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/configuration-customization))* - **Entity Manager / Layout Manager** — the structure of records and forms. **Changed through the sandbox-first process, not casually here.** *([Chapter 3](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/configuration-customization))* - **Label Manager** — the wording shown around the interface. *([Chapter 3](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/configuration-customization))* **Data** - **Import** — bring records in from a spreadsheet. *([Chapter 4](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/managing-data))* **Email** - **Outbound Emails, Email Accounts, Email Templates** — how the CRM sends mail. *([Chapter 5](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/integrations))* **Maintenance** - **Scheduled Jobs, Jobs, Auth Tokens** — background tasks and sessions; mostly informational. *([Chapter 6](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/operations-maintenance) – [Chapter 7](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/troubleshooting-recovery-reference))* > **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 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](https://docs.clevelandbusinessmentors.org/link/44)). 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](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/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](https://docs.clevelandbusinessmentors.org/link/41)): 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](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/configuration-customization)), 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](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/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](https://docs.clevelandbusinessmentors.org/link/53)). - 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](https://docs.clevelandbusinessmentors.org/link/47). # Making Configuration Changes ## Two kinds of change - **Data** — adding records, fixing values, importing. Everyday work; see [Chapter 4 — Managing Data](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/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](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/managing-data). - **Settings**, the **Tab List**, **dashboards**, **labels** — [System Settings & the Navigation Menu](https://docs.clevelandbusinessmentors.org/link/46). - **Users, roles, teams** — [Chapter 2](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/users-roles-access). ## 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](https://docs.clevelandbusinessmentors.org/link/60). # 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, 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**. 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](https://docs.clevelandbusinessmentors.org/link/58) and [Getting Help and Next Steps](https://docs.clevelandbusinessmentors.org/link/60) 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](https://docs.clevelandbusinessmentors.org/link/60)). 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](https://docs.clevelandbusinessmentors.org/link/60). ## 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](https://docs.clevelandbusinessmentors.org/link/53). # 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](https://docs.clevelandbusinessmentors.org/books/crm-introduction-guide) (for everyone) - **Mentor Documentation** — [Mentor Guide](https://docs.clevelandbusinessmentors.org/books/mentor-guide) - **Staff & Administration** — [Client Administration Team Guide](https://docs.clevelandbusinessmentors.org/books/client-administration-team-guide), [Mentor Administration Team Guide](https://docs.clevelandbusinessmentors.org/books/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](https://docs.clevelandbusinessmentors.org/link/46) 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](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/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](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/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](https://docs.clevelandbusinessmentors.org/link/60). ## 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](https://docs.clevelandbusinessmentors.org/link/58)). ## 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](https://docs.clevelandbusinessmentors.org/link/50). - Confirm **backups** are running and recent — see [Backups & Updates](https://docs.clevelandbusinessmentors.org/link/55). - 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](https://docs.clevelandbusinessmentors.org/link/58). ## 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 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](https://docs.clevelandbusinessmentors.org/link/43)). | | Reset / notification emails not arriving | Outbound email or the Google connection — see [Chapter 5 — Integrations](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/integrations). | | Calendar / Gmail not syncing | Google authorization expired — re-authorize ([Google, Email & Website Integrations](https://docs.clevelandbusinessmentors.org/link/52)). | | Someone sees too much or too little | Role or team misconfigured — [Roles, Teams & Permissions](https://docs.clevelandbusinessmentors.org/link/44). | | 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](https://docs.clevelandbusinessmentors.org/link/55). | | 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](https://docs.clevelandbusinessmentors.org/link/60). ## 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](https://docs.clevelandbusinessmentors.org/link/60)). # 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](https://docs.clevelandbusinessmentors.org/books/espocrm-system-guide/chapter/configuration-customization)) - 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](https://docs.clevelandbusinessmentors.org/books/crm-introduction-guide)** — start here, for everyone - **[Mentor Guide](https://docs.clevelandbusinessmentors.org/books/mentor-guide)** — for mentors - **[Client Administration Team Guide](https://docs.clevelandbusinessmentors.org/books/client-administration-team-guide)** and **[Mentor Administration Team Guide](https://docs.clevelandbusinessmentors.org/books/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](https://docs.clevelandbusinessmentors.org/link/53). Good documentation is maintained, not written once.