Issue Recovery for Jira documentation

How the app covers issues, what restore brings back, and how to control what it keeps.

Where to find it

A Jira site admin opens the app from Jira settings, under Apps, as Issue Recovery. A project admin opens it from that project's settings. Both land on the log of deleted issues.

Coverage: read this first

The app can only restore an issue it has saved a copy of. It saves a copy when an issue is created or changed: a field edit, a new or edited comment, an attachment, or a link. An issue with a saved copy is covered.

Issues that existed before you installed the app are not covered until they next change, or until you run a backfill. An issue that is deleted while not covered cannot be restored.

The top of every page shows how many issues are covered and how many are not. A project admin sees the numbers for the projects they administer.

If a not-covered issue is deleted, it still appears in the log with its key and the time it was deleted, marked "Not covered: no snapshot was taken before this issue was deleted". Any detail Jira did not supply is shown as "Unknown". Restore is not offered for it.

Backfill

A backfill saves a copy of every existing issue the app can read. Run one right after you install. Only a Jira site admin can start it.

Open the Coverage tab.
Select Start backfill.
The page shows progress as "X of Y issues". You can close the page. The backfill keeps running.

A backfill works through the site in small batches and saves its place after each issue. If it is interrupted, it carries on from where it stopped. If it shows no progress for ten minutes, the button changes to Resume backfill.

Archived projects are skipped, because Jira does not let apps read their issues.

The log

The Deleted issues tab lists deletions, newest first, 25 to a page. Each row shows the key, summary, project, type, who deleted the issue and when.

Filter by project, by the person who deleted the issue, and by date range. The filters combine.
Search by issue key or by words in the summary. Every word you type must appear, in any order.
Select View to open the saved copy.

Restoring an issue

Open a covered entry and select Restore as a new issue. The app creates a new issue in the same project, with the same issue type.

Restored	Not restored
Summary and description, with formatting	The original key. The new issue gets a new one.
Priority, labels, components, versions, due date, assignee	The original status. The issue starts in the workflow's first status.
Custom field values the project still accepts	Attachment files. Their names are listed in the note.
Comments, in order, each headed by its original author and date	Links to other issues. They are listed in the note.
Comment visibility limits (role or group)	History, watchers, votes, worklogs and board ranking

The app adds the restored comments itself, so Jira shows the app as their author. Each comment begins with the name of the person who wrote it and the original date.

The recovery note

The last comment on the restored issue is a note. It records the original key, reporter, creator, created date and status, who deleted the issue and when, who restored it and when, and the attachment names.

Values Jira no longer accepts

A saved value may no longer be valid: a version that was removed, an option that was deleted, a person who left. The restore still goes through. The value is left out and the note lists it as "Not restored" with the field and the value. In a list, only the values Jira refuses are left out.

If a restore fails

If the project was deleted or archived, or Jira refuses the new issue, the app tells you why and creates nothing. The log entry stays, so you can try again after fixing the cause.

Restoring twice

After a restore, the log entry reads "Restored as" with the new key. Restoring the same entry again asks you to confirm first.

Who can see what

A Jira site admin sees deleted issues from every project.
A project admin sees deleted issues from the projects they administer.
Anyone else sees "You do not have access" and no issue data.

The app asks Jira for the person's rights each time they open or restore an entry.

Retention

Records of deleted issues, and the saved copies inside them, are removed after 90 days by default. A Jira site admin can change this on the Settings tab to any whole number of days from 30 to 365. Removal runs once a day.

Saved copies of issues that still exist are kept for as long as the issue exists. When a whole project is deleted for good, its saved copies are removed within a day.

Erasing data

One person

On the Settings tab, a site admin can pick a person and erase their personal data. Their name and account ID are removed from every record the app holds, and the app shows "Removed user" in their place. The text of comments they wrote stays. The erasure runs in the background.

So that the person is not saved again the next time one of their issues changes, the app keeps a one-way hash of the erased account ID. It cannot be turned back into the ID.

When Atlassian reports that an account was closed, the app erases that account the same way without anyone asking.

Everything

A site admin can erase every saved copy and every record of a deleted issue by typing ERASE ALL DATA. This cannot be undone. Coverage drops to zero until issues change again or you run a backfill.

Uninstalling

When the app is uninstalled, the data it stored for that site is deleted by Atlassian under its retention rules for Forge apps.

Licensing

A site with an active license or trial can restore. A site without one can still see the log and the saved copies, but the restore button is switched off.

Help

See Support, or write to support@keepwellapps.com.