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
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
- If your space has no work type for risks, add one in Space settings, Work types, for example a type called Risk.
- Open Space settings, then Apps, then Risk register. You need to be a space admin.
- Under Risk work types, select the work types that hold risks. You can select up to 20. Subtasks are not offered.
- 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
| Screen | Where | Who sees it |
|---|---|---|
| Risk panel | On every risk work item | Everyone who can see the work item |
| Risk register page | In the space, next to its other pages | Everyone who can see the space |
| Risk register settings | Space settings, Apps, Risk register | Space admins |
| Stepwise Risk Register admin page | Jira settings, Apps | Jira 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
- Pick a step on the Probability row and a step on the Impact row. Each button shows its number and its name.
- Until both are picked nothing is saved, and the panel asks for the other one.
- 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
| Model | Scale |
|---|---|
| Classic 5×5 (the default) | Five steps on each axis: probability and impact |
| Simple 3×3 | Three steps on each axis |
| Information security 5×5 | Five steps on each axis, with categories for information security |
| Severity × likelihood 4×4 | Four 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.
| Validator | The transition passes when |
|---|---|
| Stepwise: risk is assessed | The risk has a probability and an impact |
| Stepwise: risk is assessed and has a measure | The 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
- Open the workflow of the risk work type in Jira’s workflow editor.
- Select the transition, for example Accept or Close.
- Open the transition’s validators and choose to add one.
- Pick Stepwise: risk is assessed or Stepwise: risk is assessed and has a measure.
- 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.
| Field | What it holds |
|---|---|
riskScore | The score of the risk before measures |
riskLevel | The level name before measures |
riskLevelRank | The level as a number, so you can ask for “this level or higher” |
residualRiskScore | The score after measures |
residualRiskLevel | The level name after measures |
residualRiskLevelRank | The level after measures as a number |
riskStrategy | The strategy: avoid, reduce, transfer or accept |
riskCategory | The category |
riskReviewDate | The review date |
riskMeasures | The 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.
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:
| Permission | Why the app needs it |
|---|---|
read:jira-work | To read work items, their risk data, spaces and search results, and to ask Jira what the current person may do |
write:jira-work | To save the risk data of a work item, and to create a work item for a measure as the person who asked |
storage:app | To 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
| Action | Who |
|---|---|
| See a risk and the register page | Everyone who can see the work item or the space |
| Assess a risk, add measures | People who can edit the work item |
| Choose risk work types, edit the model, update stored scores | Space admins |
| Add a validator to a workflow | Whoever may edit that workflow in Jira |
| Shared library, overview of all spaces (Premium) | Jira admins |
More detail: Security.
Limits
| Item | Limit |
|---|---|
| Risk work types per space | 20 |
| Steps on an axis | 3 to 6 |
| Levels in a model | 2 to 5 |
| Categories in a model | 20 |
| Measures per risk | 30 |
| Risks loaded on the register page | 500 most recently changed |
| Risks recalculated by Update risks now | 500 |
| 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,riskReviewDateandriskMeasures. 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.