Xporter 構文: 何が動くか
Word 文書を Word テンプレートモードにアップロードしたとき、Xporter 形式のテンプレート構文がどのように扱われるかを正直にまとめたものです。アップロードのたびに実行される移行スキャナー、つまりエディターの互換性レポートに表示されるものと同じ分類に基づいています。
正直な約束
Exportelier は Xporter 互換では なく、Xporter の代替でも なく 、Xporter テンプレートを実行 しません。行うのは移行の支援です。アップロード時にスキャナーがよくある Xporter 形式の構文を認識し、構成要素ごとに、すでに動作するのか、自動変換できるのか、手動の書き換えが必要なのか、設計上対象外なのかをお伝えします。
2 つの確かな保証があります。
- 他製品の構文は認識するだけで、実行しません。 スキャナーは構成要素の形(
#{for …}、${dateformat(…)}など)を読み取るだけで、アップロードされたテンプレートの内容がコードとして評価されることはありません。 - 他社のコードは複製していません。 検出パターンとエイリアスの提案は、公開されている構文の形をもとに Exportelier が独自に作成したものです。
検出結果はすべて次の 4 分類のいずれかになります。
1. 変更なしで動作
テンプレートがすでに Exportelier の正規構文を使っていれば、そのまま動作します。警告ではなく情報として表示されます。
| 構成要素 | 例 |
|---|---|
| 値トークン | ${issue.key} |
| ループ | ${#each issue.subtasks as sub}…${/each} |
| 条件 | ${#if issue.assignee}…${#else}…${/if} |
2. 自動変換可能
安全に 1 対 1 で対応付けられる、よくある Xporter 構文です。エディターは 警告 を表示し、コピーできる置換候補を提示します。
| Xporter の構成要素 | Exportelier での対応 | 備考 |
|---|---|---|
${Key}、${Summary}、${Status} など | ${issue.key}、${issue.summary}、${issue.status} など | スカラーフィールドのエイリアス。 |
${Assignee.displayName} | ${issue.assignee.displayName} | 既知のルートエイリアス。以降のパスはそのまま保持されます。 |
#{for comments} | ${#each comments as c} | ループの開始。 |
#{if(Assignee)} | ${#if issue.assignee} | 単純な存在チェック。 |
#{else} | ${#else} | else マーカー。 |
認識されるスカラーエイリアス (16): Key、Summary、Description、Status、Priority、Resolution、Assignee、Reporter、Creator、Created、Updated、DueDate、IssueType、Type、Project、Labels。
認識されるコレクションエイリアス (5): Comments、Attachments、Subtasks、Links、Worklogs。
提案されるのは正しい形ですが、対象はトークンリファレンスに存在する実際のバインディングでなければなりません。次のエイリアスは手動での調整が必要です。
- バインドできないもの:
Creator→issue.creator、Resolution→issue.resolution、Project→issue.project、IssueType/Type→issue.issuetype。いずれも Tier A のバインディングではありません。 - 大文字小文字の不一致:
DueDateはissue.duedateと提案されますが、実際のバインディングはissue.dueDateです。 - 種別の不一致:
Labelsはスカラーとして提案されますが、issue.labelsは コレクション です。${#each issue.labels as l}…を使用してください。 - 課題リンク:
Linksはlinksと提案されますが、実際のバインディングはissue.issueLinksです。
3. 非対応だが説明可能
きれいな 1 対 1 の対応はありませんが、同じ意図を表現する明確な方法があります。エディターは書き換え方を説明します。これは 警告 であり、処理を止めるものではありません。
| Xporter の構成要素 | 理由 | 代わりに行うこと |
|---|---|---|
${Comments[0].Body} | パスは角かっこによる添字に対応していません。 | 反復します: ${#each comments as c}${c.body}${/each}。 |
#{end} | 汎用の終端子です。 | 対応する閉じ方 (${/each} または ${/if}) を使用します。 |
#{if(votes > 0)} | 条件は 1 つのパスの存在のみを判定し、演算子はありません。 | 存在を判定します: ${#if issue.votes}。 |
#{elseif(…)} | elseif は存在しません。 | 条件を入れ子にします。 |
その他の #{…} ディレクティブ | 認識されません。 | ${…} 構文に置き換えます。 |
${#each}/${/if} の不一致、誤ったパス、閉じられていない ${ | パーサーが検出します。 | トークンを修正します。レポートに正確な位置が表示されます。 |
4. 安全でない、または非対応
意図的に対象外としています。これらに対応すると、テンプレートがスクリプトエンジンになってしまうためです。Exportelier はあえてそうしていません。エディターは エラー を表示し、構成要素が実行されることはありません。
| Xporter の構成要素 | 状態 | 代わりに行うこと |
|---|---|---|
${dateformat("yyyy-MM-dd")} などの関数・フィルター呼び出し | 関数は実行されません。 | 固定のフォーマッターを使用します。例: ${issue.created | date("yyyy-MM-dd")}。 |
${jql("project = ABC")} / #{JQL: …} | テンプレートから JQL が実行されることはありません。 | エクスポートコンテキストで課題を選択します。 |
| JavaScript、Groovy、Velocity、FreeMarker、JS フィルター | スクリプト言語ではありません。 | トークン・ループ・条件・フォーマッターでレイアウトを表現します。 |
set 変数、break/continue、算術演算、式 | スクリプト言語ではありません。 | 対応している構成要素で組み直します。 |
バリデーターがこれらをどう扱うか
アップロード時、各検出結果は重大度 付きの診断になります。
- info — 変更なしで動作。対応は不要です。
- warning — 自動変換可能または説明可能。エクスポートは続行しますが、バインディングが不明な場合は値が空になることがあります。
- error — 安全でない、または非対応の構文、安全でないパス、解析エラー。
Word が保持するものの値を埋めない構成要素 (テキストボックス、脚注、コンテンツコントロール、フィールドコード、コメント、変更履歴) は、unsupported-location の警告として別途報告されます。文書内には残りますが、その中のトークンは埋められません。