Configure Jira mapping

  • Public preview

Use the Mapping view to choose which findings create Jira work items and what those work items contain.

The view displays a series of sections that you can edit and save independently.

  • Saving one section does not save or discard changes in another.
  • The option to save is disabled until you make a valid change.
  • Use Reset to restore that section to the previously saved values.

While settings load, the app hides the form to avoid showing stale data. If loading fails, click Retry.

Note: The app loads options on this page from your Jira site. If the expected project or issue type is not listed, confirm that you installed the app on the correct Jira site, and that the app can access the project.

Map a finding to a work item

  1. In “Destination”, choose a Jira project key and an issue type.
  2. Click Save Destination to save your changes.
  3. In “Finding states”, select the states that will trigger creating a work item. By default, work items are only created for “Confirmed” findings that XBOW explicitly validates.
  4. If you change the selection, click Save Finding States.
  5. In “Required Jira fields”, click Check Fields.
  6. Resolve any problems with required fields. Work item creation is blocked until this section is completed and saved. The “Field output preview” shows the project, issue type, summary, description, and any outstanding required fields for the current mapping, so you can check it before you save. See Check required fields.
  7. If you update the section, click Save Required Fields.
  8. Edit the other sections as needed, saving each section you change. See Work item content, Finding details, and Priority mapping.
  9. If you enable and save bidirectional mode, configure “Status Writeback” and click Save Writeback. See Status writeback to XBOW.

After you finish mapping findings to work items, new XBOW findings with a matching state will automatically trigger new work items in Jira.

Define which findings create work items

A work item is created for a new finding only when it matches a selected state. For example, when “Confirmed” is selected, a new finding with an “Open” state does not trigger creation of a work item. If the state of the finding later changes to “Confirmed”, then a work item is created.

State Meaning
Open Not yet explicitly confirmed as valid by XBOW. Selecting this can create a large number of work items.
Challenged The finding’s validity has been challenged.
Confirmed Explicitly confirmed as valid by XBOW. Shown as “Open-confirmed” in the Console.
Invalid Marked invalid or classified as a false positive or intended behavior.
Fixed Marked fixed in XBOW.

Practical details:

  • The state choices are independent, not a minimum threshold. For example, selecting “Confirmed” does not also include “Challenged” and “Open”.
  • A delayed event uses the current configuration, not the configuration when the event was sent.
  • When you save a new selection, work items are not created for older findings immediately. Those findings are checked on a future update.
  • When a finding changes state, existing work items stay linked and a second work item is not created.

Note: New installations and upgrades from versions without a “Finding states” section use the default setting of Confirmed. Once you save your own selection, later upgrades preserve the setting.

Check required fields

The app asks Jira which fields you must cover to create the selected work item, then reports each one:

Status Meaning
Covered XBOW already sends this field.
Jira default Jira has a default value for this field, so the app does not need to send one.

When every required field is covered, the panel shows “Ready”.

The app sends the following fields itself:

  • Project
  • Issue type
  • Summary
  • Description
  • Labels
  • Priority, when you configure priority mapping and Jira accepts priority for that work item

The app can also cover required fields of these types:

  • Text
  • Textarea
  • Number
  • Date
  • Single select
  • Multi select
  • Components
  • Versions
  • Fix versions

A required field of an unsupported type blocks saving the required-fields section when Jira has no default value for it. To unblock the mapping, add a Jira default, make the field optional, remove the requirement, or choose a different project or issue type.

Configured text and selected values persist after saving and reloading. If saving succeeds but the app cannot refresh the result, it reports that separately. If the save cannot be confirmed, your entries remain on screen. Reload to check the stored values before retrying.

Before changing the destination, save or reset any required-field edits. Saving a different project or issue type clears the previous destination’s required-field mapping. Run Check Fields for the new destination and save any required values before expecting new work items.

XBOW data placement

You have full control over how the data for an XBOW finding is used to generate a Jira work item.

Work item content

  • Labels: Enter optional labels as a comma-separated list. Use them to find and filter XBOW-created work items in Jira. The app suggests a default label of xbow.

    The app also appends a severity label, such as xbow-severity-high, by default. To turn it off, in “Priority mapping” clear Append xbow-severity-*, then click Save Priority Mapping.

  • Summary template: Controls the title of the Jira work item. Use variables as placeholders for XBOW data. Default: [XBOW] {{name}}.

  • Description template: Controls the main description of the work item. Use variables as placeholders for XBOW data. Default: {{summary}}.

Click Available variables to see the full list of variables for XBOW data. Unknown variables are left in place so typos are visible.

After making any changes to this section click Save Content.

Finding states

The default options keep the issue description short and add Evidence, Impact, Mitigations, and Recipe as separate comments. Use this area to change where each section appears.

Option Result
Separate comment Adds the section as its own Jira comment.
Description Adds the section to the Jira description in the location defined by the associated variable: {{evidence}}, {{impact}}, {{mitigations}} or {{recipe}}.
Do not include Leaves the section out of Jira.

Priority mapping

By default, the integration leaves Jira priorities blank for your own processes to set. You can map some or all XBOW finding severities to a Jira priority.

If you leave a severity unmapped, the app creates the work item without setting a priority. To clear a saved mapping, select Do not set priority for that severity and click Save Priority Mapping.

Status writeback to XBOW

Status writeback applies only after you enable and save bidirectional mode in the Configuration. In unidirectional mode the section is read-only and shows “Bidirectional off”.

Map each Jira status to one of these XBOW workflow states:

  • not-started
  • in-progress
  • completed

The app suggests a mapping for the default Jira statuses, so review the suggestions before you change them.

Use Default XBOW workflow state to set the state the app applies when it first creates a Jira issue and no Jira status is mapped yet.

Test custom Jira workflows before relying on bidirectional writeback.

Click Save Writeback after changing these settings. This saves only the writeback section.

Automatic closure

Automatic closure closes an open, linked Jira work item when the app sees its XBOW finding change to “Fixed”, including a manual change. Each closure adds a comment explaining why the work item was closed. This option is off by default and requires bidirectional mode.

  1. In Configuration, select Create Jira work items and keep XBOW updated.
  2. Click Save Mode.
  3. Open Mapping.
  4. Under Automatic Closure, select Close Jira work items when the associated XBOW finding becomes Fixed.
  5. Choose a Closing Jira status. The list shows statuses in Jira’s “Done” category for the saved project and issue type.
  6. Optionally, choose a Fallback Jira resolution from your site’s resolution values. The app includes it in the closing request only if the transition accepts that value. Jira’s workflow may set or replace the resolution.
  7. Click Save Automatic Closure.

You can leave the fallback blank, but closure fails if Jira requires a resolution and provides no default.

To remove a saved fallback:

  1. Click Clear selection.
  2. Click Save Automatic Closure.

Workflow requirements

The app needs permission to access, transition, and comment on your work items. Jira must allow a direct transition to the closing status. The app supplies a closing comment and can supply the fallback resolution. It cannot fill other required fields or bypass workflow rules.

Failures and resolution warnings appear in Events. If a workflow check blocks closure before the app sends the request, fix the problem and click Retry on the event. Saving new settings does not retry the event.

Important: Once a closing request starts, the app never repeats it for the same event, even after a failure or timeout. Retry only checks the current Jira status and updates XBOW. If the work item is still open, you may need to close it manually in Jira.

For failure messages and retry guidance, see Automatic closure failures.

Reopening and configuration changes

  • Reopened work items stay open. Their workflow state updates in XBOW according to your status mapping, while the finding remains “Fixed”. Later edits and retries of a completed closure do not close the work item again.
  • While automatic closure is enabled, the selected closing status maps to completed in XBOW, overriding its mapping in Status Writeback. Other Jira statuses keep their mappings.
  • Changing the Jira project or issue type turns off automatic closure and clears its closing settings. Switching to unidirectional mode also turns it off.

Existing findings and work items

Automatic closure requires a change from another finding state to “Fixed” that the app observes. It does not:

  • Close work items for findings already recorded as “Fixed” when you enable it.
  • Close new work items created for findings that are already “Fixed”.
  • Change the status or resolution of a work item already in Jira’s “Done” category, or add a closure comment to it.
  • Reopen work items when a finding leaves “Fixed”.

For older links with no recorded finding state, the first update records the state without closing the work item. The app does not run scheduled checks for missed changes.

Was this helpful?