Support and diagnostics
Where to look when something has gone wrong. Written for whoever picks up the ticket, not for whoever wrote the code.
Establish three things first
Almost every wasted hour on this platform starts with one of these being assumed rather than checked.
Which region
Every region is a separate deployment with its own database. A customer, an order and a product number can all exist in one region and not another.
Confirm the region before looking anything up, or you will conclude data is missing when it is simply somewhere else.
Which customer and which user
A user signs in; a customer is the business they act for. One user may act for several customers, and what they can see depends on which one is active.
"It works for me" almost always means a different customer was active.
When, to the minute
Async work is retried with a growing delay, and integration pushes run on a schedule. A five-minute window is the difference between "it failed" and "it has not run yet".
Get a timestamp, and get the time zone with it.
Triage — symptom to page
| The report | Most likely | Go to |
|---|---|---|
| "The order never reached the ERP" | Queued work not drained, or the ERP call failing and retrying | Async work |
| "No order confirmation arrived" | The email queued but has not sent, or sent and was not delivered | |
| "Payment was declined but the customer was charged" | Provider call succeeded, Commerce did not record it | Payments |
| "The customer cannot sign in" | No active session, no user record, or a trusted-origin problem | Access |
| "The customer cannot see a product" | Brand entitlement, a blocked product, or the search index | Access |
| "The price is wrong" | A stale or missing pricing rule | Data |
| "Stock is wrong" | An inventory push, or a stale reservation | Data |
| "A new product is not appearing" | The push landed, the search index has not | Data |
| "The site is slow, or erroring" | Application-level; start with request telemetry | Observability |
| "Nobody can do anything" | Deployment, database or migration | Observability |
What you can do without a developer
The back-office surface is the support console. Everything here is a screen, not a script.
| Inspect and retry queued work | See what is waiting, what has failed and how many times, and push an item to the front |
| Run a background task now | Trigger an engine on demand rather than waiting for its schedule |
| Read the email log | Which template went to whom, when, and the provider's message id |
| Preview an email template | Render a template against sample data without sending anything |
| Clear a cache | One named cache, or all of them |
| Revoke a session | Force a user to sign in again |
| Change a setting | Live, without a deployment |
What you cannot do, and should stop looking for
Being clear about the gaps saves more time than describing the features.
| Replay a completed message | Retry only moves a pending or failed item forward. Once an item is complete it cannot be re-run from the queue screen |
| Read payment provider logs from a screen | Every provider call is recorded, but only in the database. There is no admin page for it |
| Resend an email | The log records what was sent. There is no resend button |
| Cancel or amend an order | Not a capability of this platform. Order changes happen in the ERP |
| See an alert before a customer does | No alerting is configured from this repository |
Identify the request, not the story
Every request is given an X-Correlation-Id and returns it on the response header. Useful to have —
but it is not written into log entries and not carried into background work, so it will not
follow one action end to end.
To trace something through the platform, use the customer number, order number and a time window. See Observability.