Matify/Config Undo for Jira

Restore guide

A restore puts one object back to one captured version. It always runs in four steps: Preview → Request → Approve → Result. Nothing is written to Jira before the approval.

Before the first restore

1. Preview

Choose Restore this version on an object's version (Objects & Compare, a journal entry or a restore point). Config Undo reads the live object from Jira and builds a preview. A preview only reads Jira; it writes nothing there (it stores the live state it read as a version). Previews count toward the hourly cap for interactive work per site (Large sites); a preview nobody submits is deleted after 24 hours.

The preview shows:

If the restore can't run, the preview says This restore can't run and why (blocked cases below).

Warnings

WarningWhat it means
Used by N projectsThe object is shared; the restore changes it for every listed project. For permission schemes, project usage is checked for the first 100 company-managed projects.
Deleted children will be recreated with new IDsOptions, components or versions deleted since that version are created again, with new IDs. Issue values that pointed at the deleted ones are not restored. Statuses deleted from the site are recreated with new IDs too.
Extras keptOptions added since that version are disabled, versions added since are archived — nothing is deleted, so issue values are kept. Screen tabs added since are emptied and deleted, as listed in the write plan.
Components to remove manuallyComponents added since that version are listed with their issue counts; Config Undo never deletes components.
Referenced items no longer existThose parts are skipped (for example a grant to a deleted group). Config Undo can't create groups.
Site-wide status definitions changedA status was renamed or recategorised since the version. Statuses are shared by all workflows, so their current definition is kept.
Experimental Jira APIRestoring a notification scheme's or screen's name and description uses an experimental Jira API.
Manual action requiredDifferences Config Undo doesn't write, with guidance: project key, project type, workflow-scheme and issue-security-scheme association of a project, workflow name, custom field and context names.
No notification scheme in that versionJira can't set a project back to "no notification scheme"; the current association is kept.
Recreated as a new objectA deleted permission scheme or workflow is recreated as a new object with a new ID, not associated with any project. Associate it again in Jira, or restore the affected projects' settings.
Runs in the background as the appThe restore is too long to run directly, so Jira's audit log will show the Config Undo app as the author. The ledger records who approved it. (A restore that starts directly but can't finish within the approval request also continues in the background as the app; see below.)

Blocked cases

The preview saysWhy
Restoring this workflow scheme would require moving issues to other statusesConfig Undo doesn't migrate issue statuses. Export the version and apply it in Jira's workflow scheme editor.
The workflow is used through an active scheme and the restore would remove statusesSame reason; removing statuses issues may be in is not done.
Jira's workflow validation rejected this versionJira's own validation (including third-party rule configuration) failed; the messages are listed.
Referenced screens no longer exist and the workflow would be invalidRecreate the screens first.
Team-managed workflow, scheme or projectTeam-managed configuration isn't covered.
Read-only system workflowJira doesn't allow changing it.
Field options managed by a Connect appJira doesn't let other apps change them; history and compare only.
The project is archived / deletedUnarchive it, or restore it from Jira's trash, then preview again.
The field or context no longer existsRestore the field from Jira's trash or recreate the context, then preview again.
Deleted notification scheme, screen or workflow schemeNot recreated in this version. Download the version as JSON and recreate it in Jira.
Another scheme or workflow with that name existsA deleted permission scheme or workflow can only be recreated when its name is free. Rename the other one, then preview again.
This entry has no full previous versionIt comes from the audit log backfill.
The live object already matches this versionNothing to restore.
Field schemesHistory and compare only.

2. Request

Choose Continue under the preview, enter a reason (required, up to 1,000 characters) and Submit request. A preview older than one hour can't be submitted; preview again. Submitting writes a REQUESTED ledger entry.

3. Approve

Four-eyes (default)

Another Jira admin opens Restores → Pending approval, reads the preview and reason, and chooses Approve and restore '<object name>' or Reject (with an optional note). The requester can't approve their own request.

Single admin

For sites with one Jira admin, Settings → Approval → Single admin. The requester approves their own request by typing the object's exact name. Switching to this mode needs a confirmation and is recorded in the ledger.

What happens at approval

  1. Config Undo re-checks that the approver is a Jira admin, that the licence is active, that restore is enabled for the type and that the kill switch is off.
  2. It re-reads the live object. If it changed since the preview, the request becomes Stale and nothing is written; preview again.
  3. It records the decision. Each request takes exactly one decision: approve, reject and cancel exclude each other. If another admin rejects the request (or the requester cancels it) while the approval is running, the rejection or cancellation wins and nothing is written. An admin who clicks while another decision is being recorded sees "Another admin is deciding on this request right now".
  4. It takes a lock on the object, so two restores of the same object can't run at once.
  5. Requests that nobody approves expire after the approval window (24 hours by default, 1–72 hours in Settings) and change nothing.

The only request a requester can approve without a second admin in four-eyes mode is the guided safe test's own restore. The server checks that the object is the test scheme the current test created and that its name still starts with "Config Undo test", and the test refuses to restore the scheme if it has been added to a project.

4. Execution and result

Right before the first write, Config Undo re-reads the object once more (if it changed, nothing is written), and saves the live state as a version with the source "Before restore". Then it runs the write plan step by step.

Who Jira's audit log shows as the author:

When something interrupts a restore:

After the last write Config Undo re-reads the object and compares it with the version (verification):

ResultShown asMeaning
PASSRestored and verifiedThe live object now matches the version.
PASS_WITH_NOTESRestored and verified, with notesIt matches, except extras that were kept disabled, archived or listed instead of deleted, or recreated items with new IDs. The notes list them.
PARTIALRestored with differencesSome steps were written, others not, or the result differs. The page shows what matches and what's left.
FAILEDThe restore failedNothing (or not enough) changed; the error code says why. A permission scheme is replaced in a single all-or-nothing write, so a rejected write leaves it unchanged.

A restore writes EXECUTED to the ledger right before its first write and VERIFIED, FAILED or CANCELLED when it ends, with the before and after hash of the object. The guided safe test writes TEST_RESTORE instead of VERIFIED. A restore that continues in the background writes a second EXECUTED entry for the switch. A request that stops before anything is written records STALE, EXPIRED or FAILED without an EXECUTED entry.

Retry remaining steps

After a PARTIAL result you can choose Retry remaining steps within one hour, without a new approval, as long as the object hasn't changed since, the kill switch is off and the licence is active. Config Undo plans again from the current state. Only one retry of a request can run at a time. After an hour, or if the object changed, start a new request.

Cancel

Pending requests can be cancelled. A running restore can be cancelled between steps: the current write finishes, the rest is skipped, what was written is verified, and the result is recorded as cancelled (nothing written) or partial.

Undo a restore ("rollback of the rollback")

Every restore saves the state right before it wrote anything. To undo a restore:

  1. Open the object in Objects & Compare.
  2. Find the version just before the restore (source Before restore, or the latest version captured before the restore if the live state was already stored).
  3. Restore this version: preview, request, approve as usual.

The undo is itself a restore, with its own preview, approval and ledger entries.

Restore from a restore point

Open the restore point, turn on Only objects changed since the restore point, and use Restore on each object you want back. Each object is its own request with its own preview and approval; there is no batch restore in this version. For deleted objects see the blocked cases above.

Restore incident playbook

Use this when a restore didn't do what you expected, or when someone asks what a restore changed.

  1. Stop further restores if needed. Settings → Disable all restores. New restores are blocked; a restore that is running stops before its next write step, and what it already wrote is verified (not rolled back). Recording continues.
  2. Open the request. Restores → History → the request. Note its result, error code (CUJ-…), the ref shown with any error, and the ledger entry numbers in its timeline.
  3. Read the ledger for that request. Ledger → find the entries with that request id. A normal restore reads:
    • REQUESTED (who requested, reason in the request)
    • APPROVED (who approved; "Approved by a second Jira admin" or "Approved in single-admin mode with typed confirmation")
    • EXECUTED ("Execution started as the approving admin / as the app: N write step(s)"), with the before hash; a second EXECUTED ("Continued in the background as the app …") if the restore switched to the background
    • VERIFIED with the verification result and "k of n items match", or FAILED/CANCELLED, with the after hash

    STALE, EXPIRED and REJECTED entries mean nothing was written. A FAILED entry without an EXECUTED entry before it also means nothing was written.

  4. Check the chain. Ledger → Verify integrity. It should report no broken entry. Record the chain head if you keep evidence outside Jira.
  5. See what Jira looks like now. On the object, Compare the target version with Live Jira, and the Before restore version with live. That tells you exactly what changed.
  6. Decide:
    • PARTIAL within one hour and the object unchanged: Retry remaining steps.
    • Want the previous state back: restore the Before restore version (above).
    • The difference is a documented limitation (new IDs, extras disabled or archived, manual items): follow the guidance in the result notes and Known limitations.
  7. Check Jira's own audit log for the object if you need the native record: inline restores appear under the approving admin, background restores (and the background part of a restore that switched) under the app.
  8. Contact support if anything is unexplained: download diagnostics (Coverage & Health), and send the request id, the ledger entry numbers, the error code and ref to support@matifyapps.de or through the support page. Write "restore incident" in the summary and choose the severity from the SLA. Don't post account ids or configuration content in the public tracker.
  9. Turn restores back on (Settings) when you are done.

Ledger entry types

TypeWritten when
REQUESTEDa restore request is submitted
APPROVEDa request is approved (also for a retry of remaining steps)
REJECTEDa pending request is rejected
EXPIREDthe approval window passed, or the licence was inactive before a queued restore started; nothing written
STALEthe live object changed after the preview, or between approval and the first write; nothing written
EXECUTEDthe first write is about to run; again when a restore continues in the background as the app
VERIFIEDverification finished (PASS, PASS_WITH_NOTES or PARTIAL)
FAILEDthe restore stopped (a rejected write, the kill switch, a cancel or an unknown step outcome after something was written; or, before any write, the kill switch or an approver who no longer holds Administer Jira) or verification failed
CANCELLEDa request was cancelled, or a running restore was stopped before it wrote anything
TEST_RESTOREthe guided safe test restore finished
SETTINGS_CHANGEDa setting changed
RESTORE_ENABLED / RESTORE_DISABLEDrestore was turned on or off for a type
DATA_DELETEDDelete all app data was requested
TOMBSTONEa closed Atlassian account was erased (counts only)
UNINSTALLthe app was uninstalled