Switching from Xporter

Exportelier offers guided migration, not Xporter compatibility. It recognizes a limited set of common Xporter-style placeholder shapes to explain or suggest safe rewrites, but never executes Xporter functions, filters, JQL or scripts.

Choose the target mode

Migration goal Recommended mode
Keep an existing branded .docx, including native headers, footers, page numbers, styles and section setup Word Template Mode
Maintain one layout that exports to PDF, Markdown and DOCX Visual designer
Preserve scripting or arbitrary expressions No direct target; redesign with safe bindings and fixed constructs

Construct map

Xporter-style intent Exportelier equivalent
Scalar placeholders such as ${Key} or ${Summary} Canonical paths such as ${issue.key} and ${issue.summary}
Repeated issue collections ${#each collection as item}…${/each} in Word mode, or a purpose-built designer component
Presence checks ${#if path}…${#else}…${/if} in Word mode
Date, number, user or duration formatting Fixed, named Word formatters
JQL inside a template Select issues through the single-issue, search, board, sprint, release or backlog export context
Function calls, JavaScript, Groovy, Velocity or FreeMarker No execution; rewrite with safe tokens or precomputed Jira fields
PDF-only layout/signing behavior Visual designer PDF projection and PDF export settings

The exact scanner classifications, recognized aliases and unsupported constructs are documented in Migrating from Xporter — What Works and What Doesn't. The canonical grammar and bindings are in Word Template Mode and the token reference.

Batch compatibility scan

Before rebuilding, copy the customer's .docx files into an isolated working directory and run:

cd forge-app
npm run migration:batch -- /path/to/templates --output ../test-artifacts/migration-report.md

Use --format json for machine-readable output. The report is deterministic and groups every file into the most severe applicable class:

The scanner is advisory. A passing report does not replace package security validation, binding validation or a real export test.