Skip to main content

Keeping Relationship Health scores up to date

You do not have to schedule anything for scores to be current. Here is what you get for free, and what the nightly run adds.

Written by Nick Kewney

Why you would use it

A score that is a week old is a score nobody trusts, and the first time someone spots a stale number they stop looking at the panel.

You do not have to set anything up to avoid that. Opening a customer recalculates the score if it has gone stale, so it is already current for whoever is looking. What a scheduled nightly run adds is history: a snapshot for every customer, including the ones nobody opened, which is what makes the trend arrow and the previous score real rather than patchy.

If you read nothing else: scores are current without any scheduling. Schedule the nightly run if you want trends and previous scores to be complete.

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, and 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

POST /api/RecordScore/Process?kind=rhi

Starts the sweep. Returns immediately and runs in the background. One run per company per metric at a time, and safe to repeat.

POST /api/RecordScore/Process?kind=rhi&initialize=true

Scores every customer, not only those already scored. Use once at go live.

GET /api/RecordScore/Status?kind=rhi

Progress of the last run: running, done or failed, and how many records were processed.

GET /api/RecordScore/Get

One record's score, band, effective band, trend and override facts.

GET /api/RecordScore/List

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

Did this answer your question?