Case number from the business application in the header
A business application, for example a records management system, starts document generation via Connect and passes the case number. It appears in the header of every page as «Case no. 2026-0417». The user does not see the number in the Forms dialog and cannot change it.
Result
- Header of every page:
Case no. 2026-0417, with the label in the document language. - Forms dialog: unchanged; the number is not requested.
- If the template is created without a Connect call, the spot in the header stays empty.
Building blocks
| Building block | Task in this example | Reference |
|---|---|---|
| Connect call of the business application | passes CaseNumber in the Data element | Connect: Structure |
| Data (content template) | declares CaseNumber as Text | Data |
| Fields (content template) | builds the header text from label and number | Fields |
| Placeholder Mapping (content template) | maps the field to the layout's placeholder | Placeholder Mapping |
| Placeholder Definition (layout template) | defines the CaseNumber placeholder in the header | Placeholder Definition |
| Global translation | Header.CaseNumber: «Geschäft Nr.», «Dossier n°», «Case no.» | Global Translations |
Data flow
Step 1: Define the placeholder in the layout
Activate the Placeholder Definition document function on the layout template:
<PlaceholderDefinitionConfiguration>
<Definitions>
<Text Name="CaseNumber" />
</Definitions>
</PlaceholderDefinitionConfiguration>
Then open the layout template in the editor and insert the CaseNumber placeholder at the desired position in the header.
Why in the layout: Headers and footers belong to the layout template. With the placeholder, the layout only promises that a text will appear here. Each content template decides where it comes from.
Step 2: Data schema in the content template
Activate the Data document function on the content template:
<DataConfiguration>
<Schema>
<Text Id="CaseNumber" />
</Schema>
</DataConfiguration>
Why: Only values declared in the schema are available in the template. A Data value does not appear in the Forms dialog. This distinguishes it from a Forms field prefilled via Connect, which the user could see and change.
Step 3: Field for the header text
Activate the Fields document function on the content template:
<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 values are available in code as Data.<Id>, in the same way as Forms.<Id> and Profile.<…>.
The global translation Header.CaseNumber must exist before testing, with a value for every document language. If the key is missing, generation aborts with an error. See Global Translations.
Why a field and not the Data value directly: Label, language and the empty case belong in code. Without a Connect call, Data.CaseNumber is an empty text and primedocs logs a warning for it; the field then returns an empty text as well.
Step 4: Map the field to the placeholder
Activate the Placeholder Mapping document function on the content template:
<PlaceholderMappingConfiguration>
<Mappings>
<Text Name="CaseNumber" SourceField="CaseNumberHeader" />
</Mappings>
</PlaceholderMappingConfiguration>
Name is the placeholder from step 1, SourceField the field from step 3.
Step 5: Connect call of the business application
<primedocsConnect>
<Template Id="30b55516-80b5-41d7-801b-b31d6da376ac" Version="Draft" />
<Data>
<Value Key="CaseNumber">2026-0417</Value>
</Data>
</primedocsConnect>
Key must match the Id in the Data schema exactly. Version="Draft" addresses the draft version of the template used while testing; omit the attribute for the productive call. How to issue the call is described in Start document generation.
Testing
- Without Connect: Test the template in the template editor. The spot in the header stays empty, which verifies the empty case from step 3.
- With Connect: Issue the call from step 5. The header shows «Case no. 2026-0417».
- Language: Switch the document language. The label follows the global translation, the number stays.
Variants
Number in the content as well: Insert the field CaseNumberHeader directly into the content template via «Bind field», for example in the subject line. See Accessing primedocs fields.
Number as a formatted part of a paragraph: If the number is to appear within a paragraph («We refer to your case 2026-0417») with centrally maintained formatting, create a WordContent snippet CaseReference with exactly one paragraph and a Snippet Placeholder CaseNumber, and insert it via an InlineWordContent field:
<InlineWordContent Name="CaseReference">
<Code>
$.inlineWordContent.from(
$.snippets.getWordContent("CaseReference", { CaseNumber: $("Data.CaseNumber") })
)
</Code>
</InlineWordContent>
$.inlineWordContent.from(…) detects the type of its argument; fromWordContent and extractParagraphContentFromWordContent are aliases of the same function. The snippet must consist of exactly one paragraph, otherwise generation aborts with an error. Set word-UpdateBehavior="Disable" only if the user is meant to edit the inserted text afterwards; otherwise a later profile or language change would overwrite those edits. Details: Placeholders in a WordContent snippet.
Number optionally from the Forms dialog: If the template is also created manually, offer CaseNumber as a Forms text field as well and evaluate the Data value first, then the Forms value: const caseNumber = $("Data.CaseNumber") || $("Forms.CaseNumber");
Pitfalls
| Symptom | Cause | Solution |
|---|---|---|
| Header stays empty despite the Connect call | Key in the Connect XML and Id in the Data schema do not match; the comparison is case-sensitive | Compare the spelling |
Generation aborts: references 'Data.CaseNumber' which is missing | Data is not activated on the content template, or CaseNumber is missing from the schema | Activate the Data document function and check the schema |
| Generation aborts with a translation error | The key Header.CaseNumber is missing from the global translations | Create the translation for all document languages |
| Validation error in the content template | Layout placeholder not mapped | Add the mapping; Taking over placeholders from the layout |
Fields configuration reports Invalid name | The field name contains a dot or another special character | Use letters, digits and _ only; grouping is reserved for objects |
| Formatted content is needed in the header | Placeholder Mapping only knows Text, Picture and YesNo | Design the formatting in the layout; use WordContent and InlineWordContent in the content |