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

02.04 Upgrading Extras

Each Extra has its own version-tracking, its own upgrade chain, and its own upgrade entry point — and Core upgrades don't bring Extras forward automatically. Here's the per-Extra upgrade workflow, the version-tracking pattern, and the catch about page-load-driven schema migration.

Why this matters

The Extras catalog (Vulnerability Management, Incident Management, Workflows, Notification, ComplianceForge SCF, UCF, AI, Authentication, Encryption, Import/Export, Customization, API, Advanced Search, Jira, Risk Assessments, Organizational Hierarchy, Team-Based Separation) is a sizable portion of the SimpleRisk surface, and each Extra has its own release cadence and its own schema-migration chain. The Core upgrade workflow (The Upgrade Process) walks the Core schema chain; it does NOT walk the Extras' schema chains. Extras have to be upgraded separately.

The honest scope to know: this catches a lot of operators. The pattern "Core just upgraded; everything's current" is only half-true. The application code for Extras comes along with the Core upgrade (the Extras live under simplerisk/extras/{name}/ in the same release tarball / image), but the per-Extra database schema doesn't migrate until the Extra's upgrade is invoked. After a Core upgrade, walk the activated Extras and verify each is at the version expected for the new Core release.

The other thing worth knowing: most Extras' schema upgrades run automatically on every page load when the Extra is enabled. The upgrade_{name}_extra_database() function checks the Extra's version stamp on each request and applies any pending migrations. This means the upgrade is implicit for most operations — you don't usually need to run the Extra upgrade explicitly because it's running every time someone hits a SimpleRisk page. The exception is when a migration takes long enough that page loads time out, or when you want to verify the upgrade ran cleanly before letting users hit the application.

The third thing: each Extra tracks its version in your instance settings with key {name}_extra_version (e.g., notification_extra_version, vulnmgmt_extra_version, ai_extra_version). The version progression is a numeric index into the Extra's ${name}_updates array — not a date-based version like Core. The first time the Extra activates, the version is 0; each subsequent migration in the chain increments it.

Before you start

Have these in hand:

  • A current SimpleRisk install with Core already upgraded to the target version (per The Upgrade Process, Upgrading via Docker, or Upgrading on Bare Metal).
  • A list of activated Extras. Visible in the Settings Hub at /admin/index.php (open it from the Settings cog in the page header, then click the Extras chip) — note which Extras show as Active.
  • The release notes for the new SimpleRisk version, especially any Extra-specific upgrade notes.
  • A current database backup — see Database Backup and Restore. The Extra upgrades modify the database; backing up first gives you the rollback path.
  • For network-dependent Extras (Vulnerability Management Extra with scanner credentials, AI Extra with provider API keys, UCF Extra with UCF API keys), confirmation that the credentials are still valid — sometimes Extra upgrades exercise the upstream connection during migration.

Step-by-step

1. Identify the activated Extras

Header: Settings cog → Settings Hub → Extras chip filters the catalog to per-Extra tiles. Each tile shows the Extra's current state. Make a list of the ones showing as Active; those are the ones that need an upgrade pass.

For programmatic identification:

SELECT name, value FROM settings WHERE name LIKE 'extra_%' AND value = 'true';

(Some Extras use the extra_{name} setting; some use {name} directly with a 'true' value — both patterns appear depending on Extra age.)

2. Run the per-Extra upgrade

For each activated Extra, the upgrade is invoked via the Extra-specific API endpoint or via the Extra's admin page.

API-based (the cleanest pattern):

curl -H "X-API-KEY: {your-api-key}" \
    https://{your-simplerisk-url}/api/{extra_name}/upgrade/app

For example:

# Upgrade the Notification Extra
curl -H "X-API-KEY: $KEY" https://simplerisk.example.com/api/notification/upgrade/app

# Upgrade the Vulnerability Management Extra
curl -H "X-API-KEY: $KEY" https://simplerisk.example.com/api/vulnmgmt/upgrade/app

# Upgrade the Incident Management Extra
curl -H "X-API-KEY: $KEY" https://simplerisk.example.com/api/im/upgrade/app

# Upgrade the AI Extra
curl -H "X-API-KEY: $KEY" https://simplerisk.example.com/api/ai/upgrade/app

The endpoint runs the Extra's upgrade_{name}_extra_database() function, which walks the Extra's ${name}_updates array of migrations and applies any pending ones.

Browser-based: open the Extra's admin page (e.g., /admin/notification.php, /admin/vulnmgmt.php, /admin/incidentmanagement.php); the page typically shows the Extra's current version and offers an Upgrade action if migrations are pending.

Implicit (page-load-driven): the Extra's upgrade_{name}_extra_database() runs on every page load when the Extra is enabled. Just navigating around SimpleRisk after a Core upgrade typically triggers the Extra upgrades implicitly. This works for most cases; explicit invocation is preferable for visibility into the migration progress and any errors.

3. Verify each Extra is at the expected version

SELECT name, value FROM settings WHERE name LIKE '%_extra_version';

Each row shows the current version (numeric index) for an Extra. Compare against the expected version for the SimpleRisk release you upgraded to. The expected versions for each Extra are documented in the SimpleRisk release notes and in the Extra's own admin page header.

4. Test each Extra's operational paths

After the upgrade, test the Extras end-to-end:

  • Notification Extra: trigger a test event (submit a test risk) and verify the email arrives.
  • Vulnerability Management Extra: open the triage queue and verify it renders; trigger a manual sync (GET /api/v2/vulnmgmt/update/all) and verify it completes.
  • Incident Management Extra: open the Incidents page and verify the list renders; submit a test incident and verify the workflow works.
  • AI Extra: open the chat sidebar and send a test message; verify the response.
  • Workflows Extra: trigger an event that should fire a workflow and verify the workflow runs.
  • Authentication Extra (SAML/OIDC/LDAP): log out and back in via the configured identity provider; verify the round-trip works.
  • Other Extras: walk through the basic operations the Extra adds.

If a test fails, check the SimpleRisk debug log at simplerisk/logs/simplerisk.log (and the Extra's own log if it keeps one, as the Vulnerability Management Extra does for scanner syncs).

5. Handle migration failures

If an Extra's upgrade fails partway through its migration chain, the Extra's {name}_extra_version setting will be at some intermediate value, and subsequent page loads will keep retrying the failed migration (and failing).

Recovery:

  1. Check the SimpleRisk debug log for the specific error.
  2. Fix the underlying issue (often a database privilege issue, a constraint conflict, or a missing dependency).
  3. Re-run the Extra upgrade. It picks up from the {name}_extra_version and retries the failed migration.

For migrations that genuinely can't proceed (e.g., a constraint conflict that would lose data), the recovery may require restoring from the backup taken in the Before You Start section.

6. Update operational documentation

After successful upgrade, update any operational runbooks that reference Extra versions or capabilities. New Extras' versions may add features the runbooks should mention; deprecated features may need updating.

Common pitfalls

A handful of patterns recur with Extra upgrades.

  • Assuming Core upgrade upgrades the Extras. This is the single most common surprise. The Core upgrade brings the Extra's application code forward (the new Core release includes the new Extra code under simplerisk/extras/{name}/), but the per-Extra schema migrations don't run until the Extra upgrade is invoked. After every Core upgrade, walk the activated Extras and run each one's upgrade.

  • Letting page-load-driven upgrades happen on the user's first request. When the Extra upgrade runs implicitly on the first post-Core-upgrade page load, the user who happens to land that request waits for the migration to complete before getting their page. For migrations that take seconds, this is fine; for migrations that take minutes, it's a poor user experience. Run the explicit upgrade right after the Core upgrade so the migration completes during the maintenance window rather than during a user's request.

  • Forgetting an Extra exists. Long-running installations accumulate Extras over years; the operator running this quarter's upgrade may not remember every Extra that's active. Always start by listing activated Extras (SELECT name, value FROM settings WHERE name LIKE 'extra_%' AND value = 'true') so the upgrade pass covers them all.

  • Network-dependent Extras failing during upgrade. Some Extras' migrations make outbound API calls (the SCF Extra fetches new framework definitions during upgrade; the UCF Extra checks for UCF content updates). Network blocks or expired credentials cause these migrations to fail. Verify network connectivity and credential validity before running these specific Extras' upgrades.

  • Skipping the backup before the Extra upgrade. The Core backup before the Core upgrade doesn't reset for the Extra upgrades. If the Core upgrade succeeded but a subsequent Extra upgrade fails badly, restoring from the pre-Core backup undoes the Core upgrade too. Take a fresh backup between the Core upgrade and the Extra upgrades if you want a separate rollback point.

  • Running multiple Extra upgrades concurrently. Each Extra's migration writes to the database. Running multiple Extra upgrades in parallel can produce lock contention or, worse, race conditions in the version-stamp updates. Run Extra upgrades sequentially.

  • Not verifying the new Extra version after the upgrade. A migration that errors silently (the function returned without raising an exception, but didn't actually do its work) leaves the version stamp incremented but the schema in an inconsistent state. Verify each Extra's version stamp matches what the release expected; if it doesn't, investigate the debug log.

  • Treating Extras as one-time installs. Some operators activate an Extra during initial setup and never upgrade it. Years later, the Extra is at the version it was activated at, while Core has moved forward many releases. This produces version-skew problems where the Extra's expected schema doesn't match what Core's queries assume. Upgrade Extras as part of every Core upgrade pass.

  • Activating new Extras in the new release without realizing they're new. Sometimes a SimpleRisk release introduces a new Extra. After upgrading Core, the new Extra appears in the catalog but isn't activated by default. Activating it has its own implications (resource usage, configuration overhead); review the release notes for new Extras and decide whether to activate.

Related