migration-doctor-snapshot

Free, open-source, read-only snapshot of Jira Data Center configuration, for the Migration Doctor app on Jira Cloud by Nox Development.

You run one script on a machine that can reach your Jira Data Center. It reads configuration through the Jira REST API (HTTP GET only) and writes one JSON file. You then upload that file into Migration Doctor on your own Jira Cloud site, which compares it with the migrated configuration and reports what JCMA left broken: filters that reference DC usernames, filters and dashboards that did not arrive, empty workflow conditions and validators, permission schemes that point at missing groups.

Two equivalent editions, same output:

The snapshot is useful on its own as a record of the DC configuration before a migration.

Contents

• What it collects and what it never collects
• Privacy
• Requirements
• Usage
• Read-only SQL exports (filters, dashboards, workflow rules)
• Output format
• REST endpoints used
• Jira versions: 8.20, 9.x, 10.x, 11.x
• Troubleshooting
• Development and tests

What it collects and what it never collects

Collects (configuration only):

Never collects: issues, issue fields or values, comments, attachments, worklogs, issue history, passwords, tokens, API keys, avatars, application properties, licences, audit logs, or anything from other Atlassian products.

Never does: any request other than HTTP GET; any change to Jira; any network call to anything other than the Jira base URL you give it. It does not follow HTTP redirects, so credentials are never sent to another host. It does not run SQL: the optional SQL queries are run by you, with your own database client and a read-only database account.

Privacy

The snapshot file contains personal data: usernames, display names and e-mail addresses of all users (active and inactive), plus filter names and JQL, which can contain names of people and projects.

• The file stays on the machine where you run the script. The script sends it nowhere.
• Keep it on that machine until you upload it into the Migration Doctor app on your own Jira Cloud site. Migration Doctor runs on Atlassian (Forge, no egress): the snapshot is stored inside Atlassian's platform for your site and is not sent to Nox Development or any third party.
• In the app you can delete an uploaded snapshot at any time. Delete the local file when the migration review is finished.
• On Linux and macOS the bash edition creates the file readable by your user only (mode 600).
• Credentials are read from environment variables, are sent only in the Authorization header to your Jira, and are never written to the output, the console or a log. The bash edition passes them to curl on standard input, so they do not appear in the process list.

Requirements

• A Jira Data Center (or Server) instance, version 8.20 to 11.x. 9.x is the primary target.
• A Jira System Administrator account. Workflows, permission schemes and the user list need admin rights.
• A personal access token (recommended, Jira 8.14+): profile picture, Profile, Personal Access Tokens, Create token. Give it a short expiry and revoke it after the snapshot. Basic authentication with username and password also works.
• Network access from where you run the script to the Jira base URL.
• PowerShell edition: Windows PowerShell 5.1 or PowerShell 7+. Nothing to install.
• bash edition: bash 3.2+, curl, jq 1.6+ (apt install jq, dnf install jq, brew install jq, winget install jqlang.jq).

Usage

Credentials come only from environment variables. The scripts reject any secret passed as an argument.

PowerShell

# PowerShell 7: prompt without echo
$env:JIRA_PAT = Read-Host 'Jira personal access token' -MaskInput
# Windows PowerShell 5.1: prompt without echo
$env:JIRA_PAT = [System.Net.NetworkCredential]::new('', (Read-Host 'Jira personal access token' -AsSecureString)).Password

.\snapshot.ps1 -BaseUrl https://jira.example.com
.\snapshot.ps1 -BaseUrl https://example.com/jira -Out C:\temp\acme-snapshot.json -Projects ACME,OPS
.\snapshot.ps1 -BaseUrl https://jira.example.com -SqlExportDir .\export

Remove-Item Env:\JIRA_PAT

If the execution policy blocks the script: powershell -ExecutionPolicy Bypass -File .\snapshot.ps1 -BaseUrl ..., or Unblock-File .\snapshot.ps1 after downloading.

bash

read -rsp 'Jira personal access token: ' JIRA_PAT && export JIRA_PAT && echo

./snapshot.sh --base-url https://jira.example.com
./snapshot.sh --base-url https://example.com/jira --out /tmp/acme-snapshot.json --projects ACME,OPS
./snapshot.sh --base-url https://jira.example.com --sql-export-dir ./export

unset JIRA_PAT

Options are the same as in PowerShell: --base-url, --out, --projects, --sql-export-dir, --filter-scan-gap, --delay-ms, --max-retries, --no-boards, --help, --version.

What you see

Progress goes to the console (stderr), one step per section, then a summary:

Snapshot written: migration-doctor-snapshot-2026-10-11.json (16353 bytes, 20 GET requests, 14s)

  users               6
  groups              6
  projects            4
  ...
  Coverage: users=full, groups=full, ..., filters=full, dashboards=full, workflows=full, ...

Exit codes: 0 success (warnings possible), 1 the run failed (HTTP error after retries, authentication, permissions, invalid SQL export), 2 usage error.

--projects

Limits projects, the permission schemes used by those projects, the workflows in their workflow schemes, and their boards. Users, groups, fields, statuses, filters and dashboards are global in Jira and are always exported in full, because filters and dashboards often span projects.

Read-only SQL exports

Jira Data Center's REST API cannot provide three things Migration Doctor checks:

So the SQL exports are a normal part of a complete snapshot, not an emergency fallback. They are plain SELECT statements in sql/, one file per section and database:

You run them, not the script. Use a read-only database account (or a read replica). Each query returns one JSON object per line; save each result as <name>.jsonl in one directory and pass that directory with --sql-export-dir / -SqlExportDir. The script reads only these file names: users, groups, filters, share-permissions, dashboards, dashboard-gadgets, workflows, plugins (each .jsonl). All are optional, but filters and dashboards need share-permissions from the same run, and dashboards needs dashboard-gadgets.

PostgreSQL:

mkdir -p export
for f in sql/postgresql/*.sql; do
  psql -X -q -A -t -v ON_ERROR_STOP=1 -h DBHOST -U readonly -d jiradb -f "$f" -o "export/$(basename "$f" .sql).jsonl"
done
# Tables in a non-default schema: export PGOPTIONS='-c search_path=your_schema' first.

MySQL:

mkdir -p export
for f in sql/mysql/*.sql; do
  mysql --batch --raw --skip-column-names --default-character-set=utf8mb4 -h DBHOST -u readonly -p"$DBPASS" jiradb < "$f" > "export/$(basename "$f" .sql).jsonl"
done

SQL Server (PowerShell; JIRA_SCHEMA is the schema of the Jira tables, usually jiraschema; -y 0 stops sqlcmd from truncating long values such as workflow descriptors):

New-Item -ItemType Directory -Force export | Out-Null
Get-ChildItem sql\sqlserver\*.sql | ForEach-Object {
  sqlcmd -S DBHOST -d jiradb -E -v JIRA_SCHEMA=jiraschema -y 0 -f 65001 -i $_.FullName -o "export\$($_.BaseName).jsonl"
}

In SQL Server Management Studio, enable Query, SQLCMD Mode before running a file (the files use the $(JIRA_SCHEMA) sqlcmd variable), and save results to a file; the sqlcmd loop above is simpler and does not truncate long values.

Notes:

• Lines that are not JSON objects (headers, row counts, blank lines) are ignored, so minor client output differences do not matter. A UTF-8 BOM is accepted.
• Owners and shared-with users are resolved from user keys (JIRAUSER10100) to usernames through app_user and the first active user directory, like Jira does. A deleted user's filter keeps the lower-case username from app_user, or the raw key if even that is gone.
• The system workflow jira is built into Jira and is not stored in the database, so it has no transitions in the snapshot (transitionsAvailable: false). It cannot be edited in DC either.
• plugins.sql lists installed apps (pluginversion). It lets the script attribute a workflow rule to the app that provides it (pluginKey, e.g. ScriptRunner or JSU) instead of guessing.
• The workflow descriptor XML is parsed by the script (PowerShell: .NET XML; bash: a small XML tokenizer in jq). Each transition lists its source statuses (from), target status (to), and every condition (including nested condition groups), validator and post function with its implementation class, module key and providing app. Hidden built-in post functions (create issue, fire event, reindex) are included as they are part of the transition in DC.

Filters without SQL

Without filters.jsonl the script collects your favourite filters, the filters of the boards it can read, and probes filter IDs upwards from 10000 (GET /rest/api/2/filter/{id}) until it sees --filter-scan-gap consecutive IDs that are missing or not visible, after the highest ID it already knows. This finds every filter shared with or owned by the account running the script, including other users' filters shared with a group or project you belong to. Other users' private filters are never visible through REST, not even to a system administrator: use the SQL export for them.

Output format

One UTF-8 JSON file that validates against schema/snapshot.schema.json (JSON Schema 2020-12, a copy of the schema the Migration Doctor app validates uploads with):

{
  "format": "migration-doctor-snapshot",
  "schemaVersion": 1,
  "createdAt": "2026-10-11T09:00:00Z",
  "generator": { "name": "migration-doctor-snapshot", "version": "1.0.0", "runtime": "bash" },
  "source": { "product": "jira", "deployment": "datacenter", "version": "9.12.3",
              "baseUrl": "https://jira.example.com", "serverTitle": "Acme Jira" },
  "coverage": { "users": "full", "groups": "full", "filters": "rest-partial",
                "dashboards": "rest-no-owner", "workflows": "none", "...": "..." },
  "users": [], "groups": [], "projects": [], "fields": [], "statuses": [],
  "filters": [], "dashboards": [], "workflows": [], "permissionSchemes": [], "boards": []
}

coverage tells the app which sections are complete (full), partial because of REST limits (rest-partial), missing owners (rest-no-owner) or missing entirely (none), so it can avoid false alarms. Arrays are sorted (by name, key or numeric id) so two snapshots of the same instance diff cleanly. source.deployment is always datacenter: serverInfo.deploymentType reports Server on every self-managed instance, and Server licences ended in February 2024.

Fields beyond the schema's documented properties (allowed by it) that the script adds: workflows[].transitionsAvailable (false when no descriptor was available), transitions[].looped (true for a transition that returns to the status it starts from; to is then empty), rules[].moduleKey (the full.module.key from the descriptor) and generator.runtime.

REST endpoints used

All requests are GET, sequential, with a pause between them (--delay-ms), and retried with exponential backoff on HTTP 429 (honouring Retry-After), 502, 503, 504 and network errors.

Request count for a typical instance: about 15 + one per project (two with --projects) + one per board + the filter probing range when SQL exports are not used.

Endpoints deliberately not used: /rest/api/2/filter/search (does not exist on DC), undocumented internal endpoints such as the workflow designer REST resource, the workflow XML export page (/secure/admin/workflows/ViewWorkflowXml.jspa, a web action that can require websudo), and the Universal Plugin Manager REST API.

Jira versions

The script detects user/list by calling it first and falls back to user/search on HTTP 404. If a 10.x or 11.x instance without user/list returns exactly 100 users through user/search, the script warns and you should add users.jsonl from SQL. username=. as a match-all query is the long-standing community convention for listing users on DC; it is not formally documented by Atlassian.

Jira 8.20 reached end of support; 9.x and later are the realistic migration sources. The script was tested against recorded 9.12 and 11.0 responses (see tests), not against live 8.20 or 10.x servers; reports from real instances are welcome.

Troubleshooting

Development and tests

The scripts have no dependencies beyond those listed above. The tests use Node.js 22:

npm ci
npm test                      # every runtime found locally (bash, pwsh, Windows PowerShell)
node tests/e2e.mjs --runtime bash
node tests/e2e.mjs --update   # regenerate tests/expected/ after an intended output change

• tests/mock-jira.mjs is a mock Jira DC server that serves realistic recorded responses from tests/fixtures/ by path and query (including paged responses, a 429 with Retry-After, 400/403 for invisible filters and boards, and a context path). It answers anything but GET with 405 and logs every request, so the tests prove the scripts are read-only.
• tests/e2e.mjs runs each edition against it (DC 9.12 REST only, 9.12 with SQL exports, 11.0 with --projects and basic auth, and error cases), validates the output against the schema with Ajv, compares it with the same golden files in tests/expected/ for every runtime (so the editions must produce equivalent output), and checks that no secret appears in the output or console.
• tests/sql/ holds a model of the Jira tables the queries read. In CI it seeds PostgreSQL, MySQL and SQL Server, runs every query with the real client, compares the result with tests/fixtures/sql-export/, and feeds each database's output through the script.
• CI (.github/workflows/ci.yml): shellcheck and PSScriptAnalyzer; bash on Ubuntu with jq 1.6 and the current jq; bash 3.2 on macOS; PowerShell 7, Windows PowerShell 5.1 and Git Bash on Windows with a cross-runtime equivalence check; the SQL job.

License

MIT, copyright Nox Development.