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

07.01 The Jira Extra

The Jira Extra synchronizes risks between SimpleRisk and Atlassian Jira via Jira's REST API plus webhooks. Configure the Jira instance URL and API token, pick which risk fields sync to which Jira issue fields, and the Extra creates Jira issues for new risks and pulls Jira-side changes back into SimpleRisk.

Requires: Jira Extra

Jira integration, the Jira webhook callback, and the per-field sync logic all live in the Jira Extra at simplerisk/extras/jira/. Without the Extra activated, SimpleRisk and Jira are unaware of each other.

Why this matters

Most engineering organizations operate in Jira. When SimpleRisk produces a risk that needs engineering work (implementing a mitigation, remediating a vulnerability, building a control), the work happens in Jira tickets. Without integration, the GRC team manually files Jira tickets for each risk, watches them through to completion, and updates SimpleRisk separately. The duplicate tracking is reliable when there are five risks; for a hundred risks it falls behind, and SimpleRisk and Jira drift out of sync.

The Jira Extra closes that loop. Risks created in SimpleRisk auto-create corresponding Jira issues; status changes on either side propagate to the other; field mappings keep specific risk attributes (priority, status, owner, due date) aligned with Jira issue attributes. The result: GRC and engineering see a consistent picture without manual reconciliation.

The honest scope to know up front: the integration is opinionated and Jira-specific. It targets Jira (Server, Data Center, and Cloud) — not Azure DevOps, not GitHub Issues, not Asana. The wire protocol is Jira's REST API plus inbound webhooks; the Extra doesn't abstract over multiple ticketing systems. If your engineering team uses something other than Jira, this Extra isn't useful.

The other thing worth knowing: the integration uses API token authentication, not OAuth. The Extra binds to a specific Jira user account and uses an API token (Atlassian's per-user tokens) to authenticate. The Jira-side actions taken by the integration appear as that user. Operationally: create a service-account user in Jira (e.g., "SimpleRisk Integration"), generate the API token from that account, and use those credentials in the Extra. Don't tie the integration to a real human's Jira account; it'll break the day they leave.

The third thing: Jira-side webhook setup is automated. When you activate and configure the Extra with valid credentials, it auto-registers a webhook on the Jira instance (named "[SIMPLERISK] Synchronization"). Inbound events from Jira (issue created, updated, deleted) hit the SimpleRisk callback URL with a query-token for authentication. Don't manually register the webhook on the Jira side; let the Extra do it.

Before you start

Have these in hand:

  • Admin access to Configure → Extras → Jira Extra for activation and configuration.
  • A Jira service-account user with permissions to create, edit, and watch issues in the project(s) you'll sync. Don't use a real human's account.
  • The service account's Atlassian API token. Generate at https://id.atlassian.com/manage-profile/security/api-tokens (for Cloud) or via the Jira admin (for Server/Data Center).
  • The Jira instance URL (e.g., https://your-org.atlassian.net for Cloud, https://jira.internal.example.com for Server/Data Center). Must be HTTPS for production; HTTP works in test environments but webhook authentication relies on the URL not being intercepted.
  • The project key(s) in Jira where SimpleRisk should create issues (e.g., RISK, SEC).
  • A clear field-mapping plan. Which SimpleRisk risk fields should propagate to which Jira issue fields? At minimum: SimpleRisk's risk subject → Jira's issue summary, SimpleRisk's risk description → Jira's issue description. More-elaborate mappings (status, priority, custom fields, components) need to be planned before configuration.
  • Jira version 5.2 build 810 or later for webhook support (any modern Jira Cloud or recent Server/Data Center version satisfies this; ancient on-prem Jiras don't).

Step-by-step

1. Activate the Jira Extra

Sidebar: Configure → Extras → Jira Extra → Activate. The activation:

  1. Creates the database tables: jira_issues (the risk_id ↔ issue_key mapping for synchronized risks) and jira_risk_pending_changes (per-field changes queued for sync).
  2. Surfaces the Jira configuration UI in the admin navigation.
  3. Generates JiraWebhookAuthToken (a 20-character random token used to authenticate inbound Jira webhooks).

The Extra is active but not yet configured to talk to a Jira instance.

2. Configure the Jira instance and credentials

Open the Jira Extra's settings page. Enter:

  • Jira Instance URL (JiraInstanceURL) — e.g., https://your-org.atlassian.net. Use HTTPS.
  • Jira User Email (JiraUserEmail) — the email address of the service account.
  • Jira User API Key (JiraUserAPIKey) — the Atlassian API token.

Save. The Extra validates the credentials by making a test call to Jira; if the credentials work, the Jira-side projects become visible for selection.

If the credentials fail, double-check: the email matches the Atlassian account; the API token is current (Atlassian tokens can expire or be revoked); the Jira URL is correct (no trailing slash issues); the service account has access to the API.

3. Register the webhook

After credentials validation, the Extra auto-registers the inbound webhook on Jira:

  1. The Extra makes a Jira REST API call to create a webhook named [SIMPLERISK] Synchronization.
  2. The webhook URL points at /extras/jira/callback.php?token= .
  3. The webhook subscribes to jira:issue_created, jira:issue_updated, and jira:issue_deleted events.

Verify on the Jira side:

  1. In Jira: Settings → System → Advanced → WebHooks.
  2. Confirm the [SIMPLERISK] Synchronization webhook exists, points at the correct callback URL, and is enabled.

If the webhook isn't there, the auto-registration may have failed (often due to the service account lacking webhook-creation permissions); check the SimpleRisk debug log and the Jira REST API response.

4. Map projects and fields

For each Jira project you want SimpleRisk to sync with:

  1. Select the project from the project dropdown in the Jira Extra's mapping UI.
  2. Configure the field mappings: SimpleRisk-side field ↔ Jira-side field. Common mappings: - SimpleRisk risk subject → Jira issue summary. - SimpleRisk risk description → Jira issue description. - SimpleRisk risk owner → Jira assignee (the Jira account is matched by the email field). - SimpleRisk risk status → Jira status (pick the closest workflow state). - SimpleRisk risk impact / likelihood → Jira priority (often a derived mapping). - SimpleRisk next review date → Jira due date. - Any custom fields SimpleRisk has (via the Customization Extra) can map to Jira custom fields by ID.
  3. Save the mapping.

Field mappings are per-project; different projects can have different mappings. Most installs configure one project; programs with many product teams may map to multiple.

5. Test the integration end-to-end

Verify both directions:

SimpleRisk → Jira:

  1. Submit a new risk in SimpleRisk.
  2. Wait ~5 seconds (the Extra triggers jira_synchronize_risk() after a brief debounce).
  3. Open the relevant Jira project; confirm a new issue was created with the mapped fields populated.
  4. Note the Jira issue key.

Jira → SimpleRisk:

  1. Edit the Jira issue (change status, assignee, or another mapped field).
  2. Wait a moment (the webhook fires immediately; SimpleRisk processes the callback synchronously).
  3. Open the corresponding SimpleRisk risk; confirm the mapped field updated.

If sync isn't happening:

  • For SimpleRisk → Jira: check the SimpleRisk debug log for Jira API errors (auth failures, field-validation errors).
  • For Jira → SimpleRisk: check Jira's webhook delivery log for the [SIMPLERISK] Synchronization webhook (Jira shows recent deliveries and any errors). Confirm the callback URL is reachable from Jira's network egress.

6. Configure sync triggers and field-level granularity

The Extra's settings let you configure:

  • Which risk events trigger sync (new risk, risk update, mitigation update, etc.).
  • Which fields trigger sync (some installs sync only a few fields to keep noise low; others sync everything).
  • Bidirectional vs unidirectional sync for specific fields (some fields might only sync SimpleRisk → Jira; others bidirectional).

Tune these per your operational needs. Excessive sync chatter (every minor risk edit producing a Jira ticket update notification) creates noise for Jira watchers.

7. Plan for service-account lifecycle

The Jira service account is the integration's identity. Operationally:

  • Don't share the credentials. The service account exists for SimpleRisk; nobody else should use it.
  • Rotate the API token periodically. Atlassian tokens persist until revoked; rotation policies vary by program. Update JiraUserAPIKey in SimpleRisk after each rotation.
  • Watch for token expiration / revocation. Atlassian sometimes revokes tokens during security events; the integration goes silent. Monitor sync activity for unexpected gaps.

8. Plan for deactivation or disconnection

To temporarily stop sync (without deactivating the Extra):

  • Disable the webhook on the Jira side.
  • Remove the API key from SimpleRisk (which prevents outbound calls).

To fully deactivate:

  1. Configure → Extras → Jira Extra → Deactivate.
  2. The Extra removes the inbound webhook from Jira (or the operator can manually delete it if the Extra's deactivation logic doesn't cover it).
  3. Existing jira_issues and jira_risk_pending_changes rows persist in the database (data preservation); future risks won't sync.

Common pitfalls

A handful of patterns recur with the Jira Extra.

  • Tying the integration to a real human's Jira account. The day they leave (or their account is disabled), sync breaks. Use a service account.

  • Not setting up the webhook callback URL correctly. The auto-registration usually works; when it doesn't, the manual fix is to register the webhook in Jira pointing at /extras/jira/callback.php?token= . Verify the URL is reachable from Jira's network.

  • Mapping every field. Excessive bidirectional sync creates feedback loops (a SimpleRisk update triggers a Jira update, which triggers a SimpleRisk update, which...). Map only the fields that need syncing; let the rest stay independent.

  • Mismatched workflow states. SimpleRisk's risk lifecycle (Submitted → Mitigated → Closed) doesn't map cleanly to every Jira workflow. Pick the closest mapping; document the gaps; train users on the asymmetry.

  • Forgetting that field-level changes from Jira can override SimpleRisk-side data. A Jira-side update propagates to SimpleRisk; if the Jira data is wrong, SimpleRisk gets wrong data. Train Jira users that their issue updates affect the risk register.

  • Token rotation that breaks sync silently. The integration goes quiet; nobody notices for a week. Monitor sync activity (the audit log records sync events).

  • Trying to sync to multiple Jira instances simultaneously. The Extra is configured for one Jira instance per SimpleRisk install. Multi-Jira programs need to consolidate Jira instances or accept one as the integrated one.

  • Not handling Jira-side deletions. When a Jira issue is deleted, the inbound webhook fires jira:issue_deleted. The Extra reads this and updates SimpleRisk accordingly (the exact behavior depends on the Extra version — typically the SimpleRisk record's mapping is unlinked rather than deleting the SimpleRisk risk). Verify the behavior matches your expectations.

  • Ignoring HTTPS for the SimpleRisk callback URL. The webhook query-token authenticates inbound Jira calls; HTTP exposes the token to network observers. Use HTTPS for production.

  • Treating the integration as bidirectional source-of-truth. Pick one side as authoritative for each field; SimpleRisk for risk-attribute fields, Jira for engineering-status fields, for example. Without a clear authority, conflicts on simultaneous edits produce confusing state.

  • Not coordinating with Jira admins before activation. The Extra creates a webhook on the Jira side; this is an audit-relevant change. Jira admins may have policies about external integrations; loop them in.

Related

Reference

  • Permission required: check_admin for Extra activation, configuration, and field mapping.
  • API endpoint(s): The Extra exposes a callback at /extras/jira/callback.php?token= for inbound webhooks.
  • Implementing files: simplerisk/extras/jira/index.php (the main integration logic — enable_jira_extra(), jira_synchronize_risk(), the API client, the webhook registration); simplerisk/extras/jira/callback.php (the inbound webhook handler).
  • Database tables: jira_issues (risk_id ↔ issue_key mapping for synchronized risks); jira_risk_pending_changes (per-field change queue).
  • config_settings keys: jira (Extra activation flag); JiraInstanceURL; JiraUserEmail; JiraUserAPIKey; JiraWebhookAuthToken (auto-generated 20-character random string for inbound webhook authentication).
  • External dependencies: A Jira instance (Cloud, Server, or Data Center, version 5.2 build 810 or later); a Jira service-account user with API access; an Atlassian API token for that account.