Documentation

Stepwise Risk Register for Jira: user guide

Everything the app does, in the order you will meet it: set up the risk work type, assess a risk, read the register, shape the model, hold a transition and search with JQL.

On this page
  1. What it is
  2. Set up
  3. Assess a risk
  4. The register page
  5. Models
  6. Workflow validators
  7. JQL fields
  8. Premium features
  9. Data and privacy
  10. Limits
  11. FAQ
  12. Troubleshooting
  13. Not available yet

What it is

Stepwise Risk Register for Jira is a Jira Cloud app. A Jira admin installs it from the Atlassian Marketplace and approves its permissions (they are explained under Data and privacy).

It makes a risk an ordinary work item. You assess it by probability and impact in a Risk panel, link the work items that treat it, set a review date, and see every risk of a space on a Risk register page with a risk matrix. It helps you run and show a risk process in Jira. It does not certify anything, and it does not make anyone compliant with a standard. It is for teams that follow such processes and want them in the place where they already work.

The words used on this page:

Risk
A work item of a work type your space admin marks as a risk.
Probability and impact
The two axes of the model. Together they give a score and a level.
Risk after measures
Also called residual risk: probability and impact set again once the measures work.
Measure
A work item that treats the risk.
Model
The scales, the score formula, the levels, their colours and the categories of a space.

Set up

The app does not create work types: that needs admin rights, and the app does not ask for them. A space admin adds the work type first, then tells the app to use it.

Choose the risk work type

  1. If your space has no work type for risks, add one in Space settings, Work types, for example a type called Risk.
  2. Open Space settings, then Apps, then Risk register. You need to be a space admin.
  3. Under Risk work types, select the work types that hold risks. You can select up to 20. Subtasks are not offered.
  4. Save.

Until a work type is chosen, the Risk panel and the Risk register page explain what to do, and tell a space admin where to click. Without any other setting the space works on the ready-made model Classic 5×5, so you can start assessing at once.

Where things are

ScreenWhereWho sees it
Risk panelOn every risk work itemEveryone who can see the work item
Risk register pageIn the space, next to its other pagesEveryone who can see the space
Risk register settingsSpace settings, Apps, Risk registerSpace admins
Stepwise Risk Register admin pageJira settings, AppsJira admins

When a new work item of a risk work type is created, the app gives it an empty risk record. That is how the workflow validators can tell a risk that has not been assessed yet from a work item that is not a risk.

Assess a risk

Open a risk work item. The Risk panel shows the current level at the top, in words and colour, and a small matrix on the right when there is room.

Probability and impact

  1. Pick a step on the Probability row and a step on the Impact row. Each button shows its number and its name.
  2. Until both are picked nothing is saved, and the panel asks for the other one.
  3. Once both are set, the score and the level appear in the header.

After measures

The After measures block has the same two scales. Set it when the measures work, to see how far they bring the risk down. Same as before copies the current assessment and Clear removes the after-measures assessment. The block opens once the risk itself is assessed.

When an after-measures assessment exists, it counts as the current risk for the top risks and for the matrix view After measures. Without one, the risk stays where it was.

Strategy, category and review date

  • Strategy: avoid, reduce, transfer or accept.
  • Category: picked from the list in the model of the space.
  • Review date: a calendar date. A date in the past is called out in words, for example “Review was due …”, and the risk appears under overdue reviews on the register page.
  • Owner: the assignee of the work item. The name comes from Jira and is not stored by the app.

Measures

  • Add by key: type a key such as ENG-12.
  • Create: make a new work item in the space. You choose its work type. The work item is created as you, and Jira checks your permissions. If Jira needs a field the app does not ask for, Jira says so and you fix it there.
  • Remove a measure from the list.
  • Each measure shows its key, title and status, and the panel shows how many are done, for example “2 of 3 done”. Up to 30 measures per risk.
  • The app keeps the numeric id of each measure, not its key, so moving a work item to another space does not break the list.

Saving and read-only

A change shows at once and is then saved. The app reads the latest version from Jira, applies your change to it and saves the result, so two people changing different fields do not overwrite each other. If saving fails, you see a message and the panel goes back to what is saved. A change that changes nothing writes nothing.

People who cannot edit the work item see the panel read-only.

The register page

Every space with a risk work type has a Risk register page. It shows what is in the space, and only what the viewer is allowed to see in Jira.

Tiles

The tiles at the top count and filter: open risks, highest levels (the top two levels of a model with four or more), not assessed, overdue reviews, and open risks without measures (risks you accept are not counted).

The risk matrix

  • Each cell shows how many open risks sit there. Closed risks are not in the matrix.
  • Switch between After measures and Before measures.
  • Click a cell with risks to filter the table to it. A chip names the cell, and you can remove it.
  • Each cell is a button with its full name, for example “Likely × Major: score 16, High, 3 risks”.

Top risks and overdue reviews

Top risks lists the five open risks with the highest current level. Overdue reviews lists the risks whose review date has passed, oldest first.

The table

  • Columns: key, title (with the category), risk, after measures, owner, review date and measures.
  • Sort by any column. Empty values always go last.
  • Search, and filter by level, strategy, category and state (open, closed or all).

CSV export

The export button saves what is on screen, with your filters, as risk-register-YYYY-MM-DD.csv (UTF-8). A cell that starts with =, +, - or @ gets a leading apostrophe, so Excel and Sheets do not run it as a formula.

The page loads up to the 500 most recently changed risks. If there are more, a banner says so.

Models

A model decides how a risk is scored and named. Each space has its own, set in Space settings, Apps, Risk register. The scales are for ranking your risks. They are not a claim that your process meets any standard.

Ready-made models

ModelScale
Classic 5×5 (the default)Five steps on each axis: probability and impact
Simple 3×3Three steps on each axis
Information security 5×5Five steps on each axis, with categories for information security
Severity × likelihood 4×4Four steps on each axis, severity and likelihood

What you can change

  • Name of the model and the names of the axes, for example Probability and Impact, or Likelihood and Severity.
  • Steps: from 3 to 6 on each axis, so the matrix is from 3×3 up to 6×6. The two axes can have different sizes. Every step has a name.
  • Score formula: multiply the two steps, add them, or take the higher of the two.
  • Levels: from 2 to 5. Each has a name (up to 24 characters), a colour (green, yellow, orange, red or purple) and a threshold: the score from which it starts.
  • Categories: the list people pick from on a risk, up to 20.

The editor shows a live preview of the matrix with the scores and the range of every level. The app checks the model as you edit and explains what is wrong: the first level must start at the lowest score, thresholds must rise, a level that no score can reach is not accepted, and step and level names must be filled and different. Save is off until the model is valid.

Levels and colours

Colours use Jira’s own design tokens, with a stronger shade in the light theme and a softer one in the dark theme. A level is always shown as a word too, so it does not depend on colour alone.

If you make the scale smaller

A saved step that is higher than the new scale is read as the top step of the new scale.

Update stored scores

The score and level of a risk are saved with the risk, because JQL and the workflow validators read them. After you change a model, press Update risks now in the settings to recalculate them (up to 500 risks, as you, with Jira checking your permissions). The register page always calculates from the current model, so the only place you may see an old score until you update is JQL.

Workflow validators

The app adds two validators to Jira’s workflow editors. They sit on a transition and stop it until the risk is dealt with.

ValidatorThe transition passes when
Stepwise: risk is assessedThe risk has a probability and an impact
Stepwise: risk is assessed and has a measureThe risk is assessed and has at least one measure, or its strategy is Accept (a risk you accept needs no measure)

A common use: the first validator on Accept, the second on Close. A work item that has no risk data, because it is not a risk or was created before the app was installed, passes.

Add a validator

  1. Open the workflow of the risk work type in Jira’s workflow editor.
  2. Select the transition, for example Accept or Close.
  3. Open the transition’s validators and choose to add one.
  4. Pick Stepwise: risk is assessed or Stepwise: risk is assessed and has a measure.
  5. Publish or save the workflow.

Jira renames buttons in its workflow editors from time to time. The order stays the same: workflow, transition, add a validator, pick the Stepwise validator, publish.

The validators are Jira expressions. They run inside Jira and read the risk data stored on the work item.

JQL fields

The app adds ten searchable fields, so you can build filters, boards and dashboards on risks.

FieldWhat it holds
riskScoreThe score of the risk before measures
riskLevelThe level name before measures
riskLevelRankThe level as a number, so you can ask for “this level or higher”
residualRiskScoreThe score after measures
residualRiskLevelThe level name after measures
residualRiskLevelRankThe level after measures as a number
riskStrategyThe strategy: avoid, reduce, transfer or accept
riskCategoryThe category
riskReviewDateThe review date
riskMeasuresThe number of measures

Examples

Risks at the second level or higher that are still open:

riskLevelRank >= 2 AND statusCategory != Done

Risks whose score after measures is still high:

residualRiskScore >= 15

Open risks whose review date has passed:

riskReviewDate < startOfDay() AND statusCategory != Done

Open risks with no measure yet:

riskMeasures = 0 AND statusCategory != Done

The fields come from data stored on each work item. The stored score and level are as of the last time the risk was saved, so after you change a model, press Update risks now (see Update stored scores) before you rely on a JQL filter. The right-hand side of a comparison, such as the score 15 above, depends on your model.

Premium features

Assessing, measures, the register page, models, CSV export, validators and JQL fields do not depend on Premium. These features add shared and historical views.

Shared model library

Jira admins create and edit up to 30 models for the whole Jira site, on the Stepwise Risk Register admin page. A space admin picks Use a model from the shared library, and the space follows that model: a change in the library reaches every space that uses it at once.

Overview of all spaces

The All spaces tab on the admin page covers up to 25 spaces that have a risk work type, using the 100 most recently changed risks of each. For every space it shows open risks, the highest level, not assessed, overdue and without measures, and a space opens up to show its three top risks. The search runs as the admin, and a space the admin cannot see is skipped.

History of assessments

The Risk panel has a History block that shows how the score changed: time, steps, score and level, up to 100 entries per risk. It holds no names. After each saved change the panel asks the server to add an entry; the server reads the risk itself, calculates the score from the model of the space and does not trust the number in the request.

Data and privacy

  • A risk is stored in a property of its own work item, stepwise.risk. The history (Premium) is in a second property, stepwise.risk.history, so the main one stays small.
  • Space settings and the shared model library are stored in Atlassian-hosted app storage (Forge storage).
  • A risk holds: the steps of probability and impact before and after measures, strategy, category, review date, the numeric ids of its measures, a short summary (score, level, whether it is assessed, number of measures) and when it was saved.
  • Not stored: names, emails and account IDs. The owner of a risk is the assignee of the work item; the name is read from Jira to show it. History entries hold only time and numbers.
  • Everyone who can see a work item can read its properties, so they hold nothing but numbers, dates and category names.
  • Nothing is sent to any other server. There are no external services, no analytics and no AI. Risks follow the data residency of your Jira site.

What the app is allowed to do

When the app is installed, Jira asks the admin to approve three permissions:

PermissionWhy the app needs it
read:jira-workTo read work items, their risk data, spaces and search results, and to ask Jira what the current person may do
write:jira-workTo save the risk data of a work item, and to create a work item for a measure as the person who asked
storage:appTo keep space settings and the shared model library in Atlassian-hosted app storage

What you do on screen runs with your own permissions. The app acts as itself in one place only: when a work item of a risk work type is created, it writes the empty risk record described under Where things are. Nobody is present to act in that event. The validators are Jira expressions and do not act as the app.

Who can do what

ActionWho
See a risk and the register pageEveryone who can see the work item or the space
Assess a risk, add measuresPeople who can edit the work item
Choose risk work types, edit the model, update stored scoresSpace admins
Add a validator to a workflowWhoever may edit that workflow in Jira
Shared library, overview of all spaces (Premium)Jira admins

More detail: Security.

Limits

ItemLimit
Risk work types per space20
Steps on an axis3 to 6
Levels in a model2 to 5
Categories in a model20
Measures per risk30
Risks loaded on the register page500 most recently changed
Risks recalculated by Update risks now500
Models in the shared library (Premium)30
Spaces in the overview (Premium)25, with the 100 most recently changed risks each
History entries per risk (Premium)100

FAQ

What is a risk in Stepwise Risk Register?
A work item of the type your space admin marks as a risk, for example a work type called Risk. The app adds a Risk panel to it. It does not create work types, so a space admin adds the type in Jira first.
How is the score made?
From the model of the space. Classic 5×5 multiplies probability by impact and sets levels Low, Medium, High and Critical. You can change the scale, the formula (multiply, add or take the higher), the thresholds and the colours.
What is residual risk?
The risk after your measures. Set probability and impact again once the measures work, and the panel and the matrix show both. A risk without a residual assessment stays where it was.
What are measures?
Work items that treat the risk. Add one by key or create a new one in the space. The panel shows their status, and how many are done.
Can I block a transition until the risk is handled?
Yes. Add the validator “Stepwise: risk is assessed” or “Stepwise: risk is assessed and has a measure” to a transition in the workflow editor, for example Accept or Close. See Workflow validators.
Can I search risks?
Yes. JQL fields: riskScore, riskLevel, riskLevelRank, residualRiskScore, residualRiskLevel, residualRiskLevelRank, riskStrategy, riskCategory, riskReviewDate and riskMeasures. See JQL fields.
Can I export the register?
Yes. The Risk register page exports what is on screen, with your filters, to CSV.
Does it store names or account IDs?
No. The owner of a risk is the assignee of the work item, and the name is read from Jira to show it. The app stores scores, dates, category names and work item ids.
Does it use AI?
No. Scores come from your model, and everything runs inside Atlassian.
Is it a replacement for a certified quality system?
No. It helps you run and show a risk process in Jira. It does not certify anything.
Does it support dark theme?
Yes, it follows each person’s Jira theme automatically.

Troubleshooting

The Risk panel says the risk register is not set up
A space admin has not chosen the risk work type yet. Open Space settings, Apps, Risk register and select it. See Set up.
The panel says this work type is not tracked as a risk
The work item is of a type that is not marked as a risk. A space admin can add the type in the settings. A work item that already has risk data, for example after its type was changed, still shows the panel.
I cannot change the risk
You need to be able to edit the work item. Without that, the panel is read-only.
A new measure could not be created
Jira checks the new work item as it would any other. A field that is required for that work type may be missing; Jira shows what it needs.
A JQL filter shows an old score
The stored score changes when a risk is saved. After you edit a model, press Update risks now in the space settings.
A risk is missing from the matrix
Closed risks are not in the matrix, and a risk that has not been assessed has no cell. Check the tile Not assessed. If the space has more than 500 risks, the page shows the most recently changed and says so.
A transition passes although the risk is not assessed
A work item with no risk data passes the validators. Check that its work type is marked as a risk, and that the work item was created after the work type was chosen.

Not available yet

These are not in the app today. We list them so that you know what not to look for yet. There are no dates attached.

  • A dashboard gadget with the matrix (the matrix is on the Risk register page)
  • Measures as Jira links: they are a list kept with the risk, so they do not show under Linked work items
  • A log of who assessed a risk and when
  • Automation rules, such as a reminder before a review date
  • A library of risks and standard measures, and import from Excel or CSV
  • One register over several spaces by filter (Premium has an overview of all spaces)
  • Translations of the screens

Missing something else? Tell us.