Xporter-Syntax: Was funktioniert
Eine ehrliche Übersicht, wie Vorlagensyntax im Xporter-Stil behandelt wird, wenn Sie ein Word-Dokument in den Word-Vorlagenmodus hochladen. Sie entspricht dem Migrationsscanner, der bei jedem Upload läuft — denselben Klassifizierungen, die Sie im Kompatibilitätsbericht des Editors sehen.
Das ehrliche Versprechen
Exportelier ist nicht Xporter-kompatibel, kein Xporter-Ersatz und führt Xporter-Vorlagen nicht aus. Was es tut, ist Ihnen beim Migrieren zu helfen: Beim Hochladen erkennt der Scanner verbreitete Syntax im Xporter-Stil und sagt Ihnen Konstrukt für Konstrukt, ob es bereits funktioniert, automatisch umgewandelt werden kann, eine manuelle Umschreibung braucht oder bewusst außerhalb des Funktionsumfangs liegt.
Zwei harte Zusagen:
- Fremde Syntax wird nur erkannt, nie ausgeführt. Der Scanner liest die Form eines Konstrukts —
#{for …},${dateformat(…)}— und nichts in einer hochgeladenen Vorlage wird jemals als Code ausgewertet. - Es wird kein fremder Code übernommen. Die Erkennungsmuster und Alias-Vorschläge sind von Exportelier aus öffentlich dokumentierten Syntaxformen selbst verfasst.
Jeder Befund fällt in eine von vier Klassen.
1. Funktioniert unverändert
Nutzt Ihre Vorlage bereits die kanonische Syntax von Exportelier, funktioniert sie schlicht. Das ergibt einen Hinweis, keine Warnung.
| Konstrukt | Beispiel |
|---|---|
| Werttoken | ${issue.key} |
| Schleife | ${#each issue.subtasks as sub}…${/each} |
| Bedingung | ${#if issue.assignee}…${#else}…${/if} |
2. Automatisch umwandelbar
Verbreitete Xporter-Syntax mit sicherer Eins-zu-eins-Entsprechung. Der Editor zeigt eine Warnung und bietet einen kopierbaren Ersatz an.
| Xporter-Konstrukt | Entsprechung in Exportelier | Hinweise |
|---|---|---|
${Key}, ${Summary}, ${Status}, … | ${issue.key}, ${issue.summary}, ${issue.status}, … | Skalare Feld-Aliasse. |
${Assignee.displayName} | ${issue.assignee.displayName} | Bekannter Wurzel-Alias; der übrige Pfad bleibt erhalten. |
#{for comments} | ${#each comments as c} | Schleifenbeginn. |
#{if(Assignee)} | ${#if issue.assignee} | Einfache Vorhandenseinsprüfung. |
#{else} | ${#else} | Else-Marker. |
Erkannte skalare Aliasse (16): Key, Summary, Description, Status, Priority, Resolution, Assignee, Reporter, Creator, Created, Updated, DueDate, IssueType, Type, Project, Labels.
Erkannte Sammlungs-Aliasse (5): Comments, Attachments, Subtasks, Links, Worklogs.
Ein Vorschlag hat die richtige Form, aber das Ziel muss weiterhin eine echte Bindung aus der Token-Referenz sein. Einige Aliasse brauchen eine manuelle Anpassung:
- Nicht bindbar:
Creator→issue.creator,Resolution→issue.resolution,Project→issue.project,IssueType/Type→issue.issuetype. Keines davon ist eine Tier-A-Bindung. - Groß-/Kleinschreibung:
DueDatewird alsissue.duedatevorgeschlagen; die Bindung heißtissue.dueDate. - Falsche Art:
Labelswird als Skalar vorgeschlagen,issue.labelsist aber eine Sammlung — nutzen Sie${#each issue.labels as l}…. - Vorgangsverknüpfungen:
Linkswird alslinksvorgeschlagen, die echte Bindung istissue.issueLinks.
3. Nicht unterstützt, aber erklärbar
Keine saubere Eins-zu-eins-Zuordnung, aber ein klarer Weg, dieselbe Absicht auszudrücken. Der Editor erklärt die Umschreibung; es ist eine Warnung, kein Blocker.
| Xporter-Konstrukt | Warum | Was stattdessen |
|---|---|---|
${Comments[0].Body} | Pfade kennen keine Indizierung mit Klammern. | Iterieren: ${#each comments as c}${c.body}${/each}. |
#{end} | Ein generischer Abschluss. | Den passenden Abschluss nutzen — ${/each} oder ${/if}. |
#{if(votes > 0)} | Bedingungen prüfen nur das Vorhandensein eines Pfades — keine Operatoren. | Stattdessen auf Vorhandensein prüfen: ${#if issue.votes}. |
#{elseif(…)} | Es gibt kein elseif. | Bedingungen verschachteln. |
Jede andere #{…}-Direktive | Nicht erkannt. | Durch ${…}-Syntax ersetzen. |
Unausgeglichene ${#each}/${/if}, falscher Pfad, nicht geschlossenes ${ | Wird vom Parser erkannt. | Token korrigieren; der Bericht nennt die genaue Position. |
4. Unsicher oder nicht unterstützt
Bewusst außerhalb des Funktionsumfangs — diese zu unterstützen würde die Vorlage in eine Skriptmaschine verwandeln, was Exportelier absichtlich nicht ist. Der Editor zeigt einen Fehler, und das Konstrukt wird nie ausgeführt.
| Xporter-Konstrukt | Status | Was stattdessen |
|---|---|---|
${dateformat("yyyy-MM-dd")} und andere Funktions- oder Filteraufrufe | Funktionen werden nie ausgeführt. | Den festen Formatierer-Satz nutzen, z. B. ${issue.created | date("yyyy-MM-dd")}. |
${jql("project = ABC")} / #{JQL: …} | JQL wird nie aus einer Vorlage ausgeführt. | Vorgänge über den Exportkontext wählen. |
| JavaScript, Groovy, Velocity, FreeMarker, JS-Filter | Keine Skriptsprache. | Das Layout mit Token, Schleifen, Bedingungen und Formatierern ausdrücken. |
set-Variablen, break/continue, Arithmetik, Ausdrücke | Keine Skriptsprache. | In die unterstützten Konstrukte umbauen. |
Was der Validator mit diesen Befunden macht
Beim Hochladen wird jeder Befund zu einer Diagnose mit einer Schwere:
- info — funktioniert unverändert, kein Handlungsbedarf.
- warning — automatisch umwandelbar oder erklärbar; der Export läuft weiter, ein Wert kann aber leer bleiben, wenn eine Bindung unbekannt ist.
- error — unsichere oder nicht unterstützte Syntax, ein unsicherer Pfad oder ein Parserfehler.
Konstrukte, die Word erhält, aber nicht befüllt — Textfelder, Fußnoten, Inhaltssteuerelemente, Feldfunktionen, Kommentare und Änderungsverfolgung — werden gesondert als unsupported-location-Warnungen gemeldet. Das Dokument behält sie, aber Token darin werden nicht befüllt.