CRM Troubleshooting

This standard governs how failures in the customer record system are diagnosed and corrected. It applies to front desk staff, who work each failure in the order stated, and to managers, who take over infrastructure faults and code faults. Every entry states what the failure looks like, why it happens, and the fix in the order to try it. Staff shall work top to bottom and shall not skip to a clever explanation before ruling out the ordinary one. The standing rule is: assume the data is telling the truth about a process failure before assuming the data is corrupt. Empty means empty, $0 means the ledger proves $0, and a stuck status means the conversion missed. Nine times out of ten, the fix is in the process: obtain the email, set the status, configure the rule: not in the records. The tenth time, it is a system fault, and this standard names where it lies.

Database unavailable on every screen

Looks like: the dashboard, directory, and appointments all fail at once with a database-unavailable message.

Why: every screen in the customer record system connects to the database through a shared connection service that requires its configured connection string. If that configuration is missing or the database is unreachable, every screen fails. The audit write is protected separately, so a logging failure cannot cascade: but nothing can be read without the connection.

Fix: this is infrastructure, not data. No rows are lost; everything returns when connectivity does. Staff shall not re-enter anything, shall not "fix" records, and shall not restart the register in a panic. Confirm the scope of the outage: one person, or everyone: wait for the connection, verify the figures came back, and escalate to support@aapawz.com if it does not return.

Customer is not in the system

Looks like: staff know the customer booked, but search finds nothing. Try, in order

1. Search the email exactly. The system matches customers on email; name variants are two rows. Email first, phone second, last name third, under Global Search.
2. Check for a forgotten filter. A lifecycle, tag, or location filter left on from the last task hides rows silently. Clear all filters and search again. This is the single most common cause.
3. The booking had no email. The carry-over from the booking records requires an email, because the appointment record requires a customer. A booking without one produces no customer record at all; the record lives only in the older booking-side records. Obtain the email, add it to the record, and the carry-over brings it across, under Customers.
4. Record-set mismatch. Every query is scoped to the location's records. A record created under a different set: franchise against main: is invisible, not missing.

Appointment stuck at scheduled

Looks like: the dog is on the table but the appointment says scheduled.

Why: scheduled is the carry-over fallback, returned for anything the status conversion does not recognize. The booking side writes forms such as "Completed," "CONFIRMED," and "Checked In"; the conversion standardizes case and spacing before mapping. A past fault of exactly this kind: a spaced status falling through to scheduled: was corrected by that standardization. If it appears on a current appointment, the conversion has regressed or a new booking-side status has appeared that the conversion does not know.

Fix: set the status by hand with the in-service action, under Appointment Detail. Then flag it. A recurring stuck-at-scheduled pattern means the conversion needs the new value added; that is a system fix, not a data fix, and shall be reported to support@aapawz.com.

Booking error: appointment created, linking failed

Looks like: the booking appears to work, then an error naming the appointment identifier states that linking its pet or service failed.

Why: the appointment row was created, but the pet or service link rows failed: usually a wrong service identifier, or a service record belonging to a different record set.

Fix: do not create the appointment again. That mints a second appointment number and leaves two rows for one dog. Fix the link: verify the service exists for this record set, verify the pet record, and re-attach. The error message names the appointment identifier; use it. The full rule is in Appointments.

Lifetime value $0 and outstanding $0 everywhere

Looks like: every customer shows $0 lifetime value; every balance shows $0.

Why: lifetime value is the sum of payments that succeeded and carry that customer's identifier, and most payments do not carry one. The stored lifetime value on the customer record itself is $0 for every row; the directory ignores it and uses the ledger. Outstanding balance is genuinely $0 across the board at present.

Fix: none. This is honest, not broken. Staff shall not hand-edit the figures; they would diverge from the ledger and the next directory load would disagree with the edit. Fix the linkage going forward: payments recorded against the customer: and the figures will fill in truthfully, under Data Management.

No-show fee did not fire, or fired twice

Looks like: an appointment was marked no-show and no invoice appeared: or the customer claims double billing.

Why: the fee machinery applies once per appointment; the invoice carries a record tag, and re-firing the transition finds it and charges nothing twice. A "double bill" is almost always two separate no-show appointments, not one billed twice. A fee that did not fire usually means the location's booking rule is not configured: no stored rule, no fee; a settings form may show starting values, but only saved rules are applied: or the appointment was marked no-show, un-marked, and re-marked in a way that confused the history.

Fix: check the fee invoices for the appointment's identifier before anything else. If the invoice exists, the fee fired; show it to the customer. If it does not exist and the rule is configured, the transition needs re-firing. Get the status right the first time; un-marking to "fix" things creates the confusion. Fee rules are stated in Appointments.

Commission looks short

Looks like: a groomer's pay does not reflect the day's work. Check, in order

1. Was the appointment actually completed: the status, not just done in real life? Accrual fires on the status transition.
2. Does the groomer's staff record carry a commission rate? No rate means no accrual and no invented default. The gap is reported, not hidden.
3. Is the pay type commission-bearing: commission, salary plus commission, or hourly plus commission? Pure hourly or salary never accrues, by design.
4. Was the groomer recorded on the service line, or did it fall back to the appointment's assigned groomer? The performer is the line's groomer first.

Accrual happens once per appointment, service, and staff member, so completing twice never double-pays, and re-completing to "fix" a short commission does nothing. Find which of the four checks failed and fix that. The accrual rules are stated in Appointment Detail.

A staff member's button does nothing

Looks like: actions, or the command palette, offer nothing or fail silently for one person.

Why: every route in the customer record system is gated by administrative permission, and the finer actions are gated by module permission: customers or appointments, read or write. A silent failure is usually a permission, not a fault.

Fix: check the staff member's module permissions before touching data or code. The rebooking action, the waitlist, and the actions function all check the gate first.

Search returns nothing, but should not

Looks like: global search finds nothing for a record staff know exists.

Why: the search fields are verified, so empty now means genuinely not found, or not under that spelling. But check the type: appointment search covers numbers and notes, not customer or pet names; customer search covers name, email, and phone, not address. Searching outside the covered fields is the usual miss.

Fix: switch to the right type, strip phone queries to digits, and try the last name. For an appointment, search the appointment number exactly as given. Field coverage is stated in Global Search.

Controls

• Staff shall not re-enter, re-create, or hand-edit records to solve a failure described in this standard where the stated fix is to wait, to correct a link, or to fix a process step.
• A fault identified as a system or code fault shall be reported, not worked around with parallel records or spreadsheets, under Data Management.

Records

Troubleshooting shall not delete or alter customer, appointment, payment, commission, or fee records except by the corrective actions stated here, each of which creates its own history and audit entries under Appointment Detail.

Escalation and review

Managers review recurring failures for a pattern pointing to a system fault. Faults the store cannot resolve: database unavailability that does not clear, a regressed status conversion, search failures against verified fields: shall be reported to support@aapawz.com, identifying the screen, the record involved, and what was tried. Legal process concerning a customer, appointment, or fee record shall be directed to legal@aapawz.com.