Overview
A relationship score is only useful if it is current when somebody looks at it, without recalculating every customer constantly. Three mechanisms cover that between them.
The three routes
Route | When it runs | Why it exists |
Batch | On a schedule you set, or on demand from Settings. | Keeps history complete, including for customers nobody opened that day, so trends and previous scores are real. |
On opening a record | When the stored score is older than your freshness window. | Makes the score effectively live for whoever is looking, at no standing cost. |
Refresh | Immediately, when a user clicks it on the panel. | Confirms the effect of answering a check or changing a setting. |
The freshness window
Set Stale after (minutes) in Settings. The default is 1440, which is a day. The minimum is 5. A setting of 15 reads as real time to anyone opening a record while keeping recalculation rare.
Running it from Settings
Score all records now on the Record Scoring page runs a full sweep for your company in the background, with progress shown. It is safe to run again, and a large company will not tie up your session. Use it after a significant configuration change or at go live.
Scheduling the nightly run
For unattended runs, call the Record Scoring API from your scheduler, per company and per enabled metric.
Endpoint | Purpose |
| Starts the sweep. Returns immediately and runs in the background. One run per company per metric at a time, and safe to repeat. |
| Scores every customer, not only those already scored. Use once at go live. |
| Progress of the last run: running, done or failed, and how many records were processed. |
| One record's score, band, effective band, trend and override facts. |
| Query by score: filter by band or score range, paged, highest first. |
The company is taken from the authenticated token, never from anything you pass in, so a token can only ever touch its own company's data.
Permissions
These endpoints accept a token holding api-all, or the narrower api-record-scoring role. Give your scheduler the narrow one so a routine job cannot do anything else. The role is created by a database update; if it is not available to grant yet, that update has not been applied on your environment.
What a run does
Recalculates each customer and stores the score, band and per check evidence.
Writes one history snapshot per customer per day, which is what the previous score and the trend arrow read.
Updates the six customer fields used by grids and reporting.
Skips excluded customers, and skips linked accounts where you score parent accounts only.
Never removes a manual override.
Choosing a schedule
Nightly outside business hours suits most companies: it keeps history complete, and the freshness window handles everything during the day. If you want fresher trend data for reporting, run it more often rather than shortening the freshness window, which only affects records people open.
Support
Support page: thelayer.com/support
Email: [email protected]
Telephone: 03333 222 000