Deleted items

Open Apps → UndoTrail → Deleted items. The tab needs an active subscription, and appears for people allowed to use the Deleted work items feature on the admin page.

How capture works

Jira does not keep deleted work items. This app keeps its own copy, in two steps:

1. Snapshot on change. Whenever a work item is created or updated, the app reads it and stores a snapshot in Forge storage on your site. Each new snapshot replaces the last, so the stored copy matches the item as it was at its most recent change.
2. Capture on delete. When a work item is deleted, Jira sends a delete event. The app moves the stored snapshot into the deleted list, merges in the few fields the delete event carries, and records who deleted it and when.

Capture is on from the moment the app is installed. There is no webhook to create and no setting to switch on. It keeps working even if the subscription lapses.

Nothing deleted before the app was installed can be recovered. There is no source to recover it from.

What a snapshot contains

Custom field values are kept within a size budget: a single value over 20,000 characters of JSON is dropped (rich-text values may be up to 100,000), and if the whole set is over about 150,000 characters the largest values are dropped until it fits. Anything dropped for size is listed in the restore preview as Too large to keep in the snapshot. If a description alone is too large to store, it is replaced with a note saying so, and everything else is kept. Jira-internal values, such as development-panel summaries and service-desk SLA data, are never stored, because they cannot be written back. The same goes for the fields Jira Product Discovery works out for itself (Insights, Comments and Linked items counts, Delivery progress and status, Score): Product Discovery works them out again for the restored idea. The fields people set on an idea, such as Impact and Effort, are kept and restored.

Full and partial capture

Each row in the list shows its capture quality.

A row is partial when the work item was never created or edited after the app was installed, so no snapshot was ever taken. Restoring one brings back only what the delete event carried. Jira’s delete event doesn’t say which security level the work item was in, so a partial row is shown only to Jira administrators. The fix is a backfill (see below), which takes a full snapshot of every existing work item the app can read. A work item at a security level that leaves out the app can’t be snapshotted, so if it is deleted it may not be captured at all, or only partly. A partial capture is shown only to Jira administrators.

Retention

Deleted-item records expire automatically.

Expiry is applied when the item is captured, so a change to the setting applies to items deleted from then on. Records already stored keep the expiry they were given. Once a record expires it is gone, and restoring is no longer possible.

Finding a deleted item

The list shows everything deleted in projects you can browse, newest first, apart from secured items Jira can’t confirm you may see (see Limitations). You get:

• Filters for Projects, Deleted by, Deleted from and Deleted to dates, and a Search box over key and summary.
• A Hide already restored tick, and Clear filters.
• Sorting by deleted date, work item key or summary. Whatever the sort, a subtask whose parent is also in the list sits just under that parent, indented.
• Export CSV and Export Excel of the filtered list.
• Deleted by shows the person’s name. Where Jira will not give a name for an account, the account ID is shown instead.

Dates are compared on the calendar day you see, in your own time zone.

The restore preview

Press Restore on a row. Nothing is written yet. The preview card shows:

• A warning that the restored work item gets a new key.
• A table of what will come back: one row per field, with the stored value. The status is listed when the work item was anywhere but the workflow’s first status (it’s moved back after creation, if the workflow allows), and so are captured comments.
• One line, Not restored: …, naming what won’t come back (the key, attachments, links, time tracking, the created date, history, and any field that no longer fits). Open it for the reason next to each.
• Also restore n subtasks, for any subtasks that were deleted with the item and are still in the list. Ticked by default.
• Also restore n comments this app captured, when comment history captured any. Ticked by default. See Restoring comments.
• Edit before restoring…, to change a few values for this restore. See Editing before you restore.

Press Restore now to go ahead, or Cancel.

The preview is built against the target project and work item type’s create screen, so it reflects your real Jira configuration. A custom field that no longer exists on that screen is listed as Not on the create screen for this project/type. An option that has since been removed is listed as no longer available.

What is restored

What is not restored, and why

These are limits of Jira’s API. Any product that recreates a deleted work item through the Jira API has the same constraints.

Restoring comments

Jira deletes a work item’s comments along with it. If comment history was on for that project, the app has its own copy of each comment’s text, and the restore can bring the conversation back:

• Tick Also restore n comments this app captured in the preview. It is ticked whenever there are comments to restore.
• Each captured comment’s latest text is posted on the new work item, oldest comment first.
• Jira cannot post a comment as someone else, or with a past date. So each comment is posted by you, now, and starts with a line naming the original author and the date it was first written, and noting when it was edited later.
• A comment that was restricted to a project role or group is posted with the same restriction. If you are not in that role or group, Jira refuses it, and it is counted as refused.
• Up to 40 comments are posted per restore. The result screen says how many were re-posted, how many Jira refused, and how many were not attempted.

Only comments captured while the app was installed and comment history was on can come back. Comments deleted before the work item was deleted are not re-posted. Formatting, mentions and attachments inside a comment are not kept, because the app stores comment text as plain text.

Editing before you restore

Sometimes a restore cannot work as the item was: the original project has been archived, or a required field on the create screen has no value in the snapshot. Press Edit before restoring… in the preview to change:

The edits apply to this restore only. The stored snapshot keeps its original values. If a restore fails for a reason you can fix, the preview stays open with your edits, so you can correct them and press Restore now again.

Restoring subtasks with a parent

When a parent is deleted, Jira deletes its subtasks too, and the app captures each of them. If any are still in the list and not yet restored, the preview offers to restore them at the same time. It offers only the ones you could see in the list yourself: in projects you can browse, at levels you can see.

• The parent is created first, then each subtask is created against the parent’s new key.
• Each subtask is put back into its own old status where the workflow allows it.
• If one subtask fails, the others continue, and the result screen names the one that failed and why.
• Subtasks are restored from their own snapshots. Edits made with Edit before restoring… apply to the parent only.

Status restore

After the new work item is created, the app looks at the transitions available from the first status of its workflow and takes the one whose target matches the stored status name, ignoring case. If there is no such transition, the item stays in the workflow’s first status and the result screen says so plainly. Workflow conditions and validators apply, because the transition runs as you.

After a restore

The result screen tells you:

• The new key, as a link.
• Whether the status was restored.
• How many custom fields came back.
• How many comments were re-posted, if you chose to restore them.
• Which fields were skipped, each with its reason.
• What happened to each subtask.
• Whether Jira rejected the full payload. If it does, the app retries with core fields only (project, type, summary, description) so you still get the work item back, and says that only the core fields were set.

The original row stays in the list, marked Restored as NEW-123, until its retention expires. A work item can be restored once: if someone else restores it while your preview is open, the preview says Already restored as NEW-123. It can’t be restored again. and Restore now is switched off. While a restore is running, a second attempt from another tab is refused for two minutes, so two copies cannot be created by accident.

Backfill: items never edited since install

A work item only has a snapshot once it has been created or changed while the app was installed. Everything older has no snapshot, so a later deletion would only be captured partially.

A Jira administrator can fix that once, from Settings → Marketplace apps → UndoTrail → Backfill:

1. Press Snapshot every work item.
2. The job works through every work item the app can read, page by page, in the background. You can leave the page.
3. The status line shows how many items were scanned and how many were snapshotted, and refreshes while it runs.

Existing snapshots are never overwritten by a backfill, so a fresher snapshot taken from a real change always wins. Run a backfill once after installing, and again after a large import.

A backfill snapshot holds the same fields as one taken when a work item changes: the core fields, custom fields, fix and affects versions, environment, the original estimate and the security level. It reads 50 work items at a time with a short pause between pages, and waits whenever Jira asks it to slow down, so a large site’s backfill takes a while but doesn’t get in its users’ way.

Limitations

• Nothing deleted before the app was installed can be recovered.
• Restored work items always get a new key.
• Attachments, links, logged work, the created date and the change history are not restored. Comments come back only as re-posted copies of the text the app captured, up to 40 per restore, posted under your name with a line crediting the original author.
• An item in an issue security level shows only to people Jira confirms are in that level. The app counts the work items at that level in that project, leaving out ones the person reported or is assigned, once as the person looking and once as the app; the two counts must match and be above zero. If Jira can’t confirm it, for example because no other work item is left at that level, the item stays hidden, and the tab shows a short note that something at a security level was left out, without naming it. Jira administrators see every secured item. A partial item, whose level isn’t known, shows only to Jira administrators. So does an item the app could no longer read after a later change (for example, a new level that leaves out the app), because its last snapshot may be out of date.
• A secured item is restored at its security level. If you can’t set security levels when creating work items in its project, it isn’t restored at all: ask someone with the Set Issue Security permission.
• The Deleted items tab and restoring need an active subscription. Capture keeps running without one, so nothing is lost while it is renewed.
• Records expire on the retention setting, which cannot be extended beyond 365 days.
• A work item deleted while the app was uninstalled is not captured.
• Work items in a project deleted permanently are not captured either: Jira sends no deletion for each work item when a whole project goes. Their snapshots stay in the app’s storage until it is uninstalled. A project moved to the trash and restored needs nothing, because Jira brings its work items back.