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/ / 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_ _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 the settings table with key _extra_version (e.g., notification_extra_version, vulnmgmt_extra_version, ai_extra_version). The version progression is a numeric index into the Extra's $ _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 at /admin/extras.php — note which Extras show as Activated.
  • 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

Sidebar: Configure → Extras opens /admin/extras.php. The page shows each Extra's current state. Make a list of the ones showing as Activated; 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_ setting; some use 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: 
  
   " \ https://
   
    /api/
    
     /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_ _extra_database() function, which walks the Extra's $ _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_ _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 specific log if one exists, like vulnmgmt_log for the Vulnerability Management Extra).

5. Handle migration failures

If an Extra's upgrade fails partway through its migration chain, the Extra's _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 _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/ / ), 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

Reference

  • Permission required: check_admin for the Extra-specific admin pages; valid API key for the v2 API endpoints.
  • API endpoint(s): GET /api/ /upgrade/app (per-Extra upgrade entry; e.g., /api/notification/upgrade/app, /api/vulnmgmt/upgrade/app, /api/im/upgrade/app, /api/ai/upgrade/app, /api/assessments/upgrade/app, etc.).
  • Implementing files: simplerisk/extras/ /upgrade.php (per-Extra upgrade chain — the global $ _updates array of migration function names); the per-Extra index.php (defines upgrade_ _extra_database() ); simplerisk/extras/upgrade/includes/api.php (the v2 API surface for Extras' upgrades).
  • Database tables: settings (the _extra_version keys); per-Extra schema is what the migrations modify.
  • config_settings keys: _extra_version for each activated Extra (e.g., notification_extra_version, vulnmgmt_extra_version, ai_extra_version, incident_management_extra_version, etc.).
  • External dependencies: Per-Extra: scanner APIs for Vulnerability Management upgrades; UCF API for UCF Extra content updates; SCF content sources for SCF Extra updates.