Geschäftsnummer aus der Fachanwendung in der Kopfzeile
Eine Fachanwendung, z. B. eine Geschäftsverwaltung, startet die Dokumenterstellung über Connect und übergibt die Geschäftsnummer. Sie erscheint auf jeder Seite in der Kopfzeile als «Geschäft Nr. 2026-0417». Der Sachbearbeiter sieht die Nummer im Forms-Dialog nicht und kann sie nicht ändern.
Ergebnis
- Kopfzeile jeder Seite:
Geschäft Nr. 2026-0417, Beschriftung in der Dokumentsprache. - Forms-Dialog: unverändert, die Nummer wird nicht abgefragt.
- Wird die Vorlage ohne Connect-Aufruf erstellt, bleibt die Stelle in der Kopfzeile leer.
Bausteine
| Baustein | Aufgabe in diesem Beispiel | Referenz |
|---|---|---|
| Connect-Aufruf der Fachanwendung | übergibt CaseNumber im Element Data | Connect: Struktur |
| Data (Inhaltsvorlage) | deklariert CaseNumber als Text | Data |
| Fields (Inhaltsvorlage) | baut den Kopfzeilentext aus Beschriftung und Nummer | Fields |
| Platzhalterzuordnung (Inhaltsvorlage) | ordnet das Field dem Platzhalter des Layouts zu | Platzhalterzuordnung |
| Platzhalterdefinition (Layoutvorlage) | definiert den Platzhalter CaseNumber in der Kopfzeile | Platzhalterdefinition |
| Globale Übersetzung | Header.CaseNumber: «Geschäft Nr.», «Dossier n°», «Case no.» | Globale Übersetzungen |
Datenfluss
Schritt 1: Platzhalter im Layout definieren
In der Layoutvorlage die Dokumentfunktion Platzhalterdefinition aktivieren:
<PlaceholderDefinitionConfiguration>
<Definitions>
<Text Name="CaseNumber" />
</Definitions>
</PlaceholderDefinitionConfiguration>
Anschliessend die Layoutvorlage im Editor öffnen und den Platzhalter CaseNumber an der gewünschten Stelle in der Kopfzeile einfügen.
Warum im Layout: Kopf- und Fusszeilen gehören zur Layoutvorlage. Das Layout verspricht mit dem Platzhalter nur, dass hier ein Text steht. Woher er kommt, entscheidet jede Inhaltsvorlage selbst.
Schritt 2: Data-Schema in der Inhaltsvorlage
In der Inhaltsvorlage die Dokumentfunktion Data aktivieren:
<DataConfiguration>
<Schema>
<Text Id="CaseNumber" />
</Schema>
</DataConfiguration>
Warum: Nur im Schema deklarierte Werte stehen in der Vorlage zur Verfügung. Ein Data-Wert erscheint nicht im Forms-Dialog. Das unterscheidet ihn von einem über Connect vorbefüllten Forms-Feld, das der Benutzer sehen und ändern könnte.
Schritt 3: Field für den Kopfzeilentext
In der Inhaltsvorlage die Dokumentfunktion Fields aktivieren:
<FieldsConfiguration>
<Fields>
<Text Name="CaseNumberHeader">
<Code><![CDATA[
function main() {
const caseNumber = $("Data.CaseNumber");
if (!caseNumber) {
return ""; // ohne Connect-Aufruf bleibt die Stelle leer
}
return `${$.translations.getText("Header.CaseNumber")} ${caseNumber}`;
}
]]></Code>
</Text>
</Fields>
</FieldsConfiguration>
Data-Werte stehen im Code unter Data.<Id> zur Verfügung, analog zu Forms.<Id> und Profile.<…>.
Die globale Übersetzung Header.CaseNumber muss vor dem Testen angelegt sein, mit einem Wert für jede Dokumentsprache. Fehlt der Schlüssel, bricht die Generierung mit einem Fehler ab. Siehe Globale Übersetzungen.
Warum ein Field und nicht direkt der Data-Wert: Beschriftung, Sprache und Leerfall gehören in Code. Ohne Connect-Aufruf ist Data.CaseNumber ein leerer Text, und primedocs protokolliert dafür eine Warnung; das Field gibt dann ebenfalls einen leeren Text zurück.
Schritt 4: Field dem Platzhalter zuordnen
In der Inhaltsvorlage die Dokumentfunktion Platzhalterzuordnung aktivieren:
<PlaceholderMappingConfiguration>
<Mappings>
<Text Name="CaseNumber" SourceField="CaseNumberHeader" />
</Mappings>
</PlaceholderMappingConfiguration>
Name ist der Platzhalter aus Schritt 1, SourceField das Field aus Schritt 3.
Schritt 5: Connect-Aufruf der Fachanwendung
<primedocsConnect>
<Template Id="30b55516-80b5-41d7-801b-b31d6da376ac" Version="Draft" />
<Data>
<Value Key="CaseNumber">2026-0417</Value>
</Data>
</primedocsConnect>
Key muss exakt der Id aus dem Data-Schema entsprechen. Version="Draft" spricht die Entwurfsversion der Vorlage an, mit der beim Testen gearbeitet wird; für den produktiven Aufruf das Attribut weglassen. Wie der Aufruf abgesetzt wird, beschreibt Dokumentgenerierung starten.
Testen
- Ohne Connect: Vorlage im Vorlageneditor testen. Die Stelle in der Kopfzeile bleibt leer; damit ist der Leerfall aus Schritt 3 geprüft.
- Mit Connect: Aufruf aus Schritt 5 absetzen. In der Kopfzeile steht «Geschäft Nr. 2026-0417».
- Sprache: Dokumentsprache wechseln. Die Beschriftung folgt der globalen Übersetzung, die Nummer bleibt.
Varianten
Nummer zusätzlich im Inhalt: Das Field CaseNumberHeader über «Feld binden» direkt in der Inhaltsvorlage einfügen, z. B. in der Betreffzeile. Siehe Zugriff auf primedocs-Felder.
Nummer als formatierter Textteil im Fliesstext: Soll die Nummer in einem Absatz stehen («Wir beziehen uns auf Ihr Geschäft 2026-0417») und die Formatierung zentral gepflegt werden, ein WordContent-Snippet CaseReference mit genau einem Absatz und einem Snippet Placeholder CaseNumber anlegen und über ein InlineWordContent-Field einfügen:
<InlineWordContent Name="CaseReference">
<Code>
$.inlineWordContent.from(
$.snippets.getWordContent("CaseReference", { CaseNumber: $("Data.CaseNumber") })
)
</Code>
</InlineWordContent>
$.inlineWordContent.from(…) erkennt den Typ des Arguments; fromWordContent und extractParagraphContentFromWordContent sind Aliasse derselben Funktion. Das Snippet muss aus genau einem Absatz bestehen, sonst bricht die Generierung mit einem Fehler ab. word-UpdateBehavior="Disable" nur setzen, wenn der Benutzer den eingefügten Text nachträglich bearbeiten soll; sonst würde ein späterer Profil- oder Sprachwechsel seine Änderungen überschreiben. Details: Snippets in Vorlagen verwenden.
Nummer wahlweise aus dem Forms-Dialog: Wird die Vorlage auch manuell erstellt, CaseNumber zusätzlich als Forms-Textfeld anbieten und im Field zuerst den Data-Wert, dann den Forms-Wert auswerten: const caseNumber = $("Data.CaseNumber") || $("Forms.CaseNumber");
Stolpersteine
| Symptom | Ursache | Lösung |
|---|---|---|
| Kopfzeile bleibt trotz Connect-Aufruf leer | Key im Connect-XML und Id im Data-Schema stimmen nicht überein; der Vergleich unterscheidet Gross- und Kleinschreibung | Schreibweise vergleichen |
Generierung bricht ab: references 'Data.CaseNumber' which is missing | Data ist in der Inhaltsvorlage nicht aktiviert, oder CaseNumber fehlt im Schema | Dokumentfunktion Data aktivieren und Schema prüfen |
| Generierung bricht mit einem Fehler zur Übersetzung ab | Der Schlüssel Header.CaseNumber fehlt in den globalen Übersetzungen | Übersetzung für alle Dokumentsprachen anlegen |
| Validierungsfehler in der Inhaltsvorlage | Platzhalter des Layouts nicht zugeordnet | Platzhalterzuordnung ergänzen; Platzhalter aus dem Layout übernehmen |
Fields-Konfiguration meldet Invalid name | Der Field-Name enthält einen Punkt oder ein anderes Sonderzeichen | Nur Buchstaben, Ziffern und _ verwenden; Gruppierungen sind Objekten vorbehalten |
| Formatierter Inhalt soll in die Kopfzeile | Die Platzhalterzuordnung kennt nur Text, Picture und YesNo | Formatierung im Layout gestalten; WordContent und InlineWordContent im Inhalt verwenden |