Skip to content
English
Customer portal
Contact us
  • There are no suggestions because the search field is empty.

01.10 Registration and Licensing

Register the instance, choose the update channel, read the Licenses page, and understand why a paid Extra you have bought can still show as Disabled — plus the one button that usually fixes it.

Why this matters

Registration and licensing sit between "SimpleRisk is installed" and "SimpleRisk does the thing you bought it for." Neither is glamorous, and both are invisible right up to the moment an Extra you are certain you paid for refuses to turn on.

Registration is also where you choose the update channel, which decides whether the instance receives releases from Production or ahead of them from Release Candidate.

The failure is quiet and it looks like a bug. You open the Extras list, find the Extra, and it reads Disabled with no explanation and nothing to click. Nothing in that view tells you the problem is a stale license cache rather than a missing entitlement, and nothing suggests where to go next. Administrators lose real time to this, usually with a support ticket in the middle of it.

There is a second reason to care. Registration is what unlocks the two Extras SimpleRisk gives you for free: the Upgrade Extra, which turns upgrades into a button rather than a maintenance window, and the Secure Controls Framework (SCF) Extra, which imports a large control catalog and its cross-framework mappings into Governance. An unregistered instance is missing both, and most operators do not realise they are entitled to them.

Before you start

  • The administrator role. Both pages live behind the Settings cog and are admin-only.
  • Outbound HTTPS to licensing.simplerisk.com. This is the load-bearing prerequisite. Registration posts there, and the license cache refreshes from there. If your egress is filtered, allow that host before anything else in this article will work. The Initial Configuration Wizard probes it as part of its connectivity check.
  • Outbound HTTPS to updates.simplerisk.com. Allow this one too. It carries the release and Extra-compatibility data SimpleRisk uses to decide which version of an Extra your release can run, and an instance that cannot reach it will refuse Extra downloads rather than risk installing a build that does not match. If you maintain an egress allowlist that was written against an older SimpleRisk release, this host may not be on it yet.
  • Outbound HTTPS to the Release Candidate hosts, only if you plan to switch the update channel (step 6). They are updates-test.simplerisk.com, licensing-test.simplerisk.com and bundles-test.simplerisk.com, and they stand in for the three production hosts while the instance is on that channel.
  • The email address your SimpleRisk subscription is under, if you have bought Extras. Licenses are issued against the instance, but the subscription is tied to your account.

Step-by-step

1. Register the instance

Settings cog → Settings Hub → Register & Upgrade opens /admin/register.php. If the instance registered itself during install, this page shows the existing registration; if the registration call failed at install time — which it does silently whenever licensing.simplerisk.com was unreachable — this is where you complete it.

Registering sends your registration details to SimpleRisk and, in return, immediately grants the Upgrade and Secure Controls Framework (SCF) Extras. SimpleRisk uses the details to notify you about releases and security updates.

If the install completed but you never saw a registration prompt, assume the install-time call failed and register here. It costs nothing to confirm.

2. Read the Licenses page

Settings cog → Settings Hub → Licenses opens /admin/licenses.php. This is the authoritative answer to "what is this instance entitled to?"

At the top sits the Instance ID — the identifier SimpleRisk licenses against. Quote it in any support conversation about entitlements. Beside it is the Refresh Licenses button, covered below.

Below that, three tabs carry counts:

  • Active — Extras licensed and in force. Each row gives the Extra's name, its description, an Active badge, and the licence's Start Date and End Date. Some entitlements, the SCF Extra among them, read Unlimited on both dates.
  • Expired — Extras whose licence has lapsed. These stop working; renew to bring them back.
  • Unlicensed — Extras this instance has no entitlement for. This is the normal state for anything you have not bought.

The Licenses page showing the Instance ID and the Refresh Licenses button at the top, the Active / Expired / Unlicensed tabs with their counts, and a table of Extras with descriptions, Active badges, and licence start and end dates

3. Refresh the licences when an Extra shows Disabled

The Licenses page does not query SimpleRisk on every page load — it reads a locally cached copy of your entitlements. That cache refreshes on its own schedule, which means it can lag reality in both directions: after you buy an Extra, and after a period where the instance could not reach the licensing service.

A stale cache shows up two ways:

  • The Extras list shows an Extra you own as Disabled, with no way to activate it.
  • A page carrying licence state shows a banner along the lines of "SimpleRisk could not reach the licensing service. License state will refresh automatically on the next check."

Refresh Licenses on the Licenses page forces the check immediately. An instance that showed every Extra as Unlicensed will typically come back with the full set Active in a few seconds. Do this before you open a support ticket — it resolves the majority of "I bought this and it will not turn on" cases.

If the counts do not change after a refresh, the problem is upstream of SimpleRisk: either the instance genuinely cannot reach licensing.simplerisk.com, or the entitlement is not on your subscription. The two are easy to tell apart — a connectivity failure surfaces the banner above, while a missing entitlement refreshes cleanly and simply leaves the Extra in Unlicensed.

4. Activate what you are now entitled to

A licence is permission, not activation. Once the Extra shows Active on the Licenses page, activate it as normal — see Installing Extras. An Extra can be licensed and still switched off; that is a perfectly ordinary state and often the one you want.

5. If the download is refused, upgrade SimpleRisk first

Downloading an Extra can fail for a reason that has nothing to do with your licence. SimpleRisk serves the newest build of every Extra, and a newer Extra will not run on an older Core — so the download is checked against your release and refused when the two do not match:

The downloaded "encryption" Extra (version 20260811-001) is not compatible with SimpleRisk 20260519-001 and was not installed. Upgrade SimpleRisk to the latest version first.

Nothing is left half-installed when this happens; an Extra you already had keeps working untouched. Upgrade Core, then install the Extra. You may also see a refusal while a database upgrade is still pending, which resolves once the upgrade finishes, or an occasional "SimpleRisk could not confirm which Extra versions this release supports" — that one means the instance could not reach updates.simplerisk.com, and retrying after connectivity returns is the fix.

The Upgrade Extra itself is the one exception, deliberately. It is never refused on compatibility grounds, whatever build you are offered and whatever release you are on — it is the tool you use to get back to a supported state, so refusing it would strand the instance that most needs it. If you ever see this refusal name the Upgrade Extra, that is a bug worth reporting, not an instruction to upgrade first.

The one-click upgrade never hits any of this, because it brings Core and the database forward before it touches the Extras.

6. Choose an update channel

The Updates card at the top of the Register & Upgrade page carries an Update channel selector with two options:

  • Production — the default. Upgrades, Extras and licensing come from the services SimpleRisk publishes to every customer.
  • Release Candidate — upgrades, Extras and licensing come from the Release Candidate services, which publish releases before they reach Production. Choose it when you want a fix or a feature ahead of the general release and you accept that you are running software that has had less time in the field.

Pick the other option and SimpleRisk asks you to confirm before it changes anything. The dialog is titled Switch the update channel to Release Candidate? or Switch the update channel to Production? and describes where upgrades, Extras and licensing will come from next. Confirm with Switch channel, or Cancel to leave things as they are. The switch is recorded in the audit trail.

Two things happen right after a switch. The "latest version" text and the up-to-date indicator on the Updates card are cleared and then read again from the new channel, so the page stops showing the other channel's newest release. The cached licence data is cleared as well, and fills again from the new channel's licensing service on the next check. If an Extra reads Disabled immediately afterwards, use Refresh Licenses as described in step 3. The Release Candidate licensing service accepts production licences, so what you own stays available on either channel.

Switching never downgrades an instance. Moving back to Production while the instance runs a release candidate that Production has not published yet leaves it on that release; the confirmation dialog says so. The instance stays where it is until Production publishes a later release, and only then is an upgrade offered.

Pinning the channel in config.php

Some operators would rather the channel never be a click away. Set it in config.php instead and the selector stops accepting changes:

define('SIMPLERISK_UPDATE_CHANNEL', 'rc');   // or 'production'

The only recognised values are production and rc. Anything else is logged as a warning and ignored, and SimpleRisk falls back to the next source in the list below.

Three further constants point one service at a specific address, which is how test and staging environments are usually built: UPDATES_URL for the release and Extra-compatibility data, LICENSING_URL for registration and licences, and BUNDLES_URL for the downloads of the SimpleRisk release itself. Each one applies to its own service only. SimpleRisk decides the channel by taking the first of these that applies:

  1. The explicit UPDATES_URL, LICENSING_URL and BUNDLES_URL constants, each for its own service.
  2. The SIMPLERISK_UPDATE_CHANNEL constant.
  3. The channel an administrator selected on the page.
  4. Production.

Any constant from the first two levels locks the selector. It is shown disabled, with a note reading Managed in config.php. This instance is pinned to Production (or Release Candidate). If you override only some of the three addresses, the others follow the channel and the selector reads Custom (set in config.php) and lists the addresses in use. To hand control back to the page, remove the constants from config.php.

What the Updates card tells you about your release

Next to the versions, the card shows where the instance stands against its channel: behind the latest release (an upgrade is offered), up to date, or ahead. The ahead case carries a message:

  • Running {version}, which this channel has not published. No upgrade is offered until it publishes a later release. The instance is on a release that its channel does not list. This is routine for a release candidate that was withdrawn and replaced, and for an instance moved to Production while it ran a candidate. SimpleRisk never says "up to date" here, because it is not. It also never moves an instance backwards: once the channel publishes a later release, the upgrade is offered, and it goes to the next published release rather than to an earlier one.

Right after a channel switch the card shows no latest-version text and no message. The cached answer from the other channel was cleared, and the card says nothing until the next version check fills it from the new channel. That is a pause, not a fault.

If you start an upgrade and the update service cannot be read, the upgrade reports The update service could not be reached, so the latest release is unknown. and installs no new application release. A database upgrade, Extra upgrade, or correction that is already pending still runs; when there is nothing else to do, the run ends as failed. Check outbound access to the hosts for the channel you are on, then run it again.

Common pitfalls

  • Reading Disabled as "not purchased." This is the pitfall that costs the most time, because the label is doing two jobs. An Extra shows Disabled when the instance has no current entitlement — which covers both "never bought" and "bought, but the cached licence data is stale or was fetched while the licensing service was unreachable." Refresh the licences before concluding anything about what you own.

  • Skipping registration because the install "worked." The install-time registration call has a short timeout and fails silently. The instance runs perfectly well without it — it is simply missing the free Upgrade and SCF Extras, and nothing on screen points that out. If you cannot remember registering, you probably have not.

  • Blocking licensing.simplerisk.com at the firewall. Understandable instinct on a hardened network, and it breaks registration, the licence refresh, and therefore every paid Extra. If egress must stay restricted, allow that one host.

  • Assuming a licence renewal takes effect immediately. It takes effect when the cache next refreshes. If you renewed this morning and the Extra still reads Expired, refresh the licences rather than waiting.

  • Switching to Release Candidate on a production system without a plan. Release candidates are published before the general release and can be withdrawn and replaced when a defect turns up. Take a backup first, and prefer a staging instance. Switching back never downgrades you, so the switch is not an undo button.

  • Setting only one of the address constants. UPDATES_URL alone leaves licensing and downloads following the channel. That is sometimes what you want, but the instance then sends some requests to your custom address and the rest to whichever channel is selected, and the selector shows the Custom state. Pin the channel with SIMPLERISK_UPDATE_CHANNEL unless you have a reason to point a single service elsewhere.

  • Treating the Instance ID as a secret. It is an identifier, not a credential, and support will ask for it. Quoting it in a ticket saves a round trip.

Related