Version: 4.0 (2026 H1)

Forms

This document function lets you query properties via a form by configuring text boxes, check boxes, drop-downs, etc. — so-called elements.

warning

This function is not available with its full feature set in "classic" templates.

Basic structure

<FormsConfiguration>
  <Elements>
    <!-- Insert form elements and groups here -->
  </Elements>
</FormsConfiguration>

Designer

When you open Forms in the template editor, you land on the simple view. Clicking the preview opens the Forms designer, which assembles the form in a user interface.

A form consists of various elements: structural elements that improve clarity, and form elements whose values entered by the user end up in the document. Behind the user interface there is an XML configuration for each element, accessible via the «Advanced view» button.

Example

<FormsConfiguration>
  <Elements>
    <Text Id="Subject" translate-Label="Forms.Subject" />
    <Date Id="Date" translate-Label="Forms.Date" RelativeDate="Today" translate-Format="Configuration.DateFormat.WrittenOut" />
    <AdditionalProfile Id="MainSigner" Label="Hauptunterzeichnende*r" PreselectByIndex="1" />
    <AdditionalProfile Id="CoSigner" Label="Mitunterzeichnende*r" />
    <Group Title="Weitere Einstellungen">
      <YesNo Id="ShowContact" Label="Kontakt anzeigen" Value="true">
        <ElementsIfYes>
          <Choice Id="ContactFormOption" Label="Anzeigeart" SelectedValue="0">
            <Option Value="0" Label="Unpersönlicher Kontakt" />
            <Option Value="1" Label="Persönlicher Kontakt" />
          </Choice>
        </ElementsIfYes>
      </YesNo>
    </Group>
    <GlobalElements Key="Forms.Attachments" />
  </Elements>
</FormsConfiguration>

Overview

The following Forms elements are possible:

Structural elements

Group
Info

Form elements

Text
Date
YesNo (check box)
Choice (drop-down)
AdditionalProfile
Object or ObjectCollection
GlobalSchemaAndSummary (globally stored Schema/Summary configuration)
GlobalDataProviders (globally stored DataProvider)
GlobalElements (globally stored Forms configuration)

Integrating additional profiles into a template

The profile fields of the user generating a document are provided automatically (e.g. organization data such as logos or postal addresses, as well as personal user data). A profile switch in the primedocs ribbon shows the data of the selected profile.

Using AdditionalProfile, additional profiles can be integrated into the document. This profile selection shows the user's own profiles or third-party profiles shared with them. This is useful, e.g.:

for additional signatures in a template,
for collaboration with other employees or departments (e.g. alongside the department head, the cost-centre owner should also be mentioned),
in further use cases.

The corresponding AdditionalProfile Forms fields must also be inserted into the template.

Adaptive input mask

Forms allows fields to be shown conditionally. In the YesNo and Choice elements, the appearance of further form elements can depend on a value. Possible embedded elements are: Text, Date, Choice, YesNo and Info.

The elements are called ElementsIfYes / ElementsIfNo for YesNo (for true and false) and ElementsIfValue for Choice (for a specific value).

<YesNo Id="ShowThing" Label="Muss unterzeichnet werden">
  <ElementsIfYes>
    <Info>Bitte sicherstellen, dass ein Signaturbild hinterlegt ist.</Info>
  </ElementsIfYes>
</YesNo>

Elements

For all elements: the Id (or Name) attribute is required for identification, must not contain spaces and must be unique. Forms automatically adds the Forms. prefix (e.g. Subject becomes Forms.Subject).

Group

Groups are structural elements and group form elements with <Group>…</Group> for visual presentation.

<FormsConfiguration>
  <Elements>
    <!-- [form elements] -->
    <Group Title="Telefonnummern">
      <!-- [form elements] -->
    </Group>
    <!-- [form elements] -->
  </Elements>
</FormsConfiguration>

warning

Groups must not contain other groups (no nesting).

Attributes for Group

Attribute name	Description
`Title` (optional)	Title shown in the input interface.

Info

Displays an information text in the Forms dialog. The text is given as the content of the Info element.

<Info>Wichtig: Jedes Protokoll muss auch im Teams-Kanal «Protokollfeed» gesendet werden.</Info>

Text

Lets the user enter text. In the template, a Plain Text Content Control is inserted.

<Text Id="Subject" Label="Betreff" Value="Protokoll für" MultiLine="true" Required="true">
  <Description>Bitte treffenden Betreff eingeben, der das Anliegen kurz, prägnant und präzise beschreibt.</Description>
  <ValidationMessage>Bitte einen Betreff eingeben.</ValidationMessage>
</Text>

Attributes for Text

Attribute name	Description
`Id` (required)	Identification (inserting into the template, use in Fields).
`Label` (required)	Description of the element in the input interface.
`Value` (optional)	Predefined text the user can edit.
`MultiLine` (optional)	If `true`: line breaks are possible.
`Required` (optional)	If `true`: input is required (not empty, not only spaces). Recommended: also a `ValidationMessage`.
`OnlyVisibleDuringGeneration` (optional)	If `true`: the field is only shown during the first generation, not when reopening the Forms dialog.

Content for Text

Element name	Description
`Description` (optional)	Additional information, shown as a tooltip.
`ValidationMessage` (optional)	Text shown on invalid input.

Date

Lets the user select a date (Date Picker Content Control).

<Date Id="CreationDate" Label="Erstelldatum" Format="dd.MM.yyyy" RelativeDate="FirstDayOfMonth" OffsetMonths="2" OffsetDays="-1" />

Attributes for Date

Attribute name	Description
`Id` (required)	Identification.
`Label` (required)	Description in the input interface.
`Format` (required)	Date format, e.g. `dd.MM.yyyy` for "31.12.2020" or `d. MMMM yyyy` for "31 December 2020". The base configuration provides several formats in the global translations.
`Required` (optional)	If `true`: a date is required. Recommended: also a `ValidationMessage`.
`Value` (optional)	Preselected fixed date (format `yyyy-MM-dd`). Cannot be combined with `RelativeDate`.
`RelativeDate` (optional)	Preselected date relative to document creation: `Today`, `FirstDayOfMonth`, `FirstDayOfYear`. Further adjustable with `OffsetMonths`/`OffsetDays`. Examples: last day of the previous month `RelativeDate="FirstDayOfMonth" OffsetDays="-1"`; last day of the current month `RelativeDate="FirstDayOfMonth" OffsetMonths="1" OffsetDays="-1"`.
`OffsetMonths` (optional)	Months added to the relative date (positive/negative).
`OffsetDays` (optional)	Days added to the relative date (positive/negative).
`OnlyVisibleDuringGeneration` (optional)	If `true`: only visible during the first generation.

Content for Date: Description and ValidationMessage (as for Text).

YesNo

Lets the user enable ("Yes") or disable ("No") an option (Check Box Content Control).

<YesNo Id="MustBeSigned" Label="Muss unterzeichnet werden" Value="false" RequiredValue="true">
  <Description>Anwählen, wenn das Protokoll von Hand unterzeichnet werden muss</Description>
  <ValidationMessage>Protokolle müssen immer unterzeichnet werden.</ValidationMessage>
  <ElementsIfYes>
    <Info>Bitte sicherstellen, dass ein Signaturbild hinterlegt ist.</Info>
  </ElementsIfYes>
</YesNo>

Attributes for YesNo

Attribute name	Description
`Id` (required)	Identification.
`Label` (required)	Description in the input interface.
`Value` (optional)	If `true`: the option is enabled initially.
`RequiredValue` (optional)	If `true`: the user must enable it; if `false`: the user must disable it. Recommended: also a `ValidationMessage`.
`OnlyVisibleDuringGeneration` (optional)	If `true`: only visible during the first generation.

Content for YesNo

Element name	Description
`ElementsIfYes` (optional)	Adaptive input: when the value is `true`, the contained elements are shown.
`ElementsIfNo` (optional)	Adaptive input: when the value is `false`, the contained elements are shown.
`Description` (optional)	Additional information, shown as a tooltip.
`ValidationMessage` (optional)	Text shown on invalid input.

Choice

Lets the user select among several options (Combo Box Content Control).

<Choice Id="Classification" Label="Klassifizierung" Required="true" SelectedValue="confidential" EmptyOptionLabel="Bitte Klassifizierung wählen...">
  <Option Value="public" Label="Öffentlich" />
  <Option Value="confidential" Label="Vertraulich" />
  <Option Value="secret" Label="Geheim" />
  <Description>Bitte beachten: Geheime Dokumente dürfen niemals per E-Mail versendet werden.</Description>
  <ValidationMessage>Bitte Klassifizierung auswählen.</ValidationMessage>
  <ElementsIfValue SelectedValue="secret">
    <Text Id="SecretId" Label="Geheimnummer" />
  </ElementsIfValue>
</Choice>

Attributes for Choice

Attribute name	Description
`Id` (required)	Identification.
`Label` (required)	Description in the input interface.
`Required` (optional)	If `true`: a selection is required. Recommended: also a `ValidationMessage`.
`SelectedValue` (optional)	Preselected option (the value from the desired option's `Value` attribute).
`EmptyOptionLabel` (optional)	Label of the option that represents "nothing selected".
`OnlyVisibleDuringGeneration` (optional)	If `true`: only visible during the first generation.

Content for Choice

Element name	Description
`Option` (required, multiple possible)	A possible choice. Attributes: `Value` and `Label`.
`ElementsIfValue` (optional)	Adaptive input: when matching `SelectedValue`, the contained elements are shown.
`Description` (optional)	Additional information, shown as a tooltip.
`ValidationMessage` (optional)	Text shown on invalid input.

AdditionalProfile

Lets the user select an additional profile. Shown are the user's own profiles and third-party profiles shared with them. Since a profile has various user fields (first name, phone number, function, signature image, etc.), all user fields are offered for insertion in the template.

AdditionalProfiles can only be defined via the XML configuration (not in the designer).

<AdditionalProfile Id="MainSigner" Label="Hauptunterzeichnende*r" PreselectByIndex="1" />
<AdditionalProfile Id="CoSigner"   Label="Mitunterzeichnende*r" />

Attributes for AdditionalProfile

Attribute name	Description
`Id` (required)	Identification.
`Label` (required)	Description in the input interface.
`PreselectByIndex` (optional)	Whole number (1, 2, …, n): at `1` the first profile stored in the signature profile is preselected, at `n` the `n`-th (if present).

Content for AdditionalProfile: Description (optional) — shown as a tooltip.

Objects and ObjectCollections

warning

This function is not available in "classic" templates.

Object and ObjectCollection represent objects in the template — e.g. a recipient, invoice items or any other data objects. For one object use Object, for several use ObjectCollection.

Attributes for Object

Attribute name	Description
`Id` (required)	Identification.
`Label` (required)	Description in the input interface.
`Required` (optional)	If `true`: the user must create/select an object. Objects configured with `Required="true"` can be used directly as a field in the template.

Attributes for ObjectCollection

Attribute name	Description
`Id` (required)	Identification.
`Label` (required)	Description in the input interface.
`SelectedObjectId` (optional)	An `Object` with this id is created automatically.

Batch creation via `SelectedObjectId`

If an ObjectCollection is given a SelectedObjectId, an Object with this id is created automatically. In the interface, an element can be selected to represent the object's content; in addition, options for batch creation of the document become visible. There may only be one ObjectCollection with SelectedObjectId per configuration.

Content for Object / ObjectCollection

Element name	Description
`Schema`	Defines all data that can ultimately be used in a template.
`Summary`	Defines which fields are shown in the list view.
`DataProviders` (optional)	Defines data sources to load objects, e.g. from a CRM, a web API or other sources.

Objects, ObjectCollections and DataProviders can only be defined via the XML configuration. See the data interface page for more.

<FormsConfiguration>
  <Elements>
    <ObjectCollection Id="data" Label="Teilnehmende">
      <!-- Defines the ObjectCollection's elements to use in JavaScript -->
      <Schema>
        <Text Id="FirstName" Label="Vorname" />
        <Text Id="LastName" Label="Name" />
        <Text Id="Alias" Label="Kürzel" />
        <YesNo Id="IsLead" Label="Hat Sitzungsleitung" />
        <YesNo Id="IsProtocol" Label="Macht Protokoll" />
      </Schema>
      <!-- Defines what fields are shown in the list view -->
      <Summary>
        <Field Id="FirstName" />
        <Field Id="LastName" />
        <Field Id="Alias" />
      </Summary>
      <!-- Defines the DataProviders -->
      <DataProviders>
        [...]
      </DataProviders>
    </ObjectCollection>
  </Elements>
</FormsConfiguration>

Accessing globally stored entries

The following types of global entries can be referenced in a Forms configuration:

GlobalSchemaAndSummary → a globally stored configuration with the Schema and Summary elements.
GlobalDataProviders → a globally stored configuration with CsvDataProvider, ExcelDataProvider, GlobalDataProviders, HttpDataProvider or SqlDataProvider.
GlobalElements → all other elements (e.g. Text or YesNo), excluding Group.

The reference is made for all types via the Key attribute (required) — the ID of the global entry.

<FormsConfiguration>
  <Elements>
    <Group Title="Empfängeradressen">
      <GlobalElements Key="Forms.Recipient" />
    </Group>
    <Group Title="Brief">
      <GlobalElements Key="Forms.ContactTypeRefNr" />
      <GlobalElements Key="Forms.DateSubject" />
      <GlobalElements Key="Forms.Signers" />
      <GlobalElements Key="Forms.CopyAttachments" />
    </Group>
  </Elements>
</FormsConfiguration>

GlobalSchemaAndSummary

Fetches an entry from the Global Configurations of type FormsGlobalSchemaAndSummary to configure an Object or ObjectCollection.

<FormsConfiguration>
  <ObjectCollection Id="Recipient" Label="Empfängeradressen">
    <GlobalSchemaAndSummary Key="Recipients.Objects.ProtocolSchema" />
  </ObjectCollection>
</FormsConfiguration>

GlobalDataProviders

Fetches an entry from the Global Configurations of type FormsGlobalDataProviders to configure an Object or ObjectCollection.

<FormsConfiguration>
  <Object Id="Recipient" Label="Empfängeradressen">
    <GlobalSchemaAndSummary Key="Recipients.Objects.DefaultSchema" />
    <DataProviders>
      <GlobalDataProviders Key="Recipients.Objects.DefaultProviders" />
    </DataProviders>
  </Object>
</FormsConfiguration>

GlobalElements

Fetches an entry from the Global Configurations of type FormsGlobalElements.

<FormsConfiguration>
  <GlobalElements Key="Forms.ReportDefault" />
</FormsConfiguration>

Translations

All elements can be displayed translated. If an attribute with the translate- prefix is used, the corresponding attribute without prefix does not need to be configured as well; instead the ID of an entry from the Global Translations is given.

Attribute name	Description
`translate-Label` (optional)	Translated description of the element.
`translate-Description` (optional)	Translated additional information.
`translate-ValidationMessage` (optional)	Translated text shown on invalid input.
`translate-Value` (optional)	Translated predefined value.

<FormsConfiguration>
  <Elements>
    <Text Id="Subject"         translate-Label="FormsTexts.Subject" />
    <Text Id="Title"           translate-Value="Texts.Memo" translate-Label="FormsTexts.Title" />
    <YesNo Id="ShowSalutation" translate-Description="FormsDescriptions.ShowSalutation" translate-Label="FormsTexts.ShowSalutation" />
    <Text Id="CopyTo"          Required="true" translate-ValidationMessage="FormsMsg.MandatoryField" translate-Label="FormsTexts.Title" />
    <Date Id="Date"            translate-Label="FormsTexts.Date" translate-Format="DateFormat.WrittenOut" />
  </Elements>
</FormsConfiguration>

Glossary

German	English	Description
Forms	Forms	Name of the document function; counterpart in classic templates: "Document parameter".
Forms-Dialog	Forms dialog	The dialog; counterpart in classic: "Document parameter dialog".
Formularelement	Form element	An input element in the Forms dialog, e.g. `Text` or `Choice`.
Strukturelement	Structural element	Elements that are shown but do not request input (do not end up in the document part).
Feld	Field	All form elements that ultimately end up in the document part.
Objekt	Object	Defined via a schema; populated manually or via `DataProvider`.
Objektliste	ObjectCollection	A collection of objects of the same type.
DataProvider	DataProvider	Defines a source for objects.

Detailed example

The order of the form elements in the Forms XML determines the order in the dialog.

Forms

<FormsConfiguration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Elements>
    <Object Id="RecipientAddressData" translate-Label="AddressData.Addresses">
      <Schema>
        <Text Id="CompanyName" translate-Label="AddressData.Company" />
        <Text Id="FirstName" translate-Label="AddressData.FirstName" />
        <Text Id="Surname" translate-Label="AddressData.Surname" />
        <Text Id="Street" translate-Label="AddressData.Street" />
        <Text Id="PostalCode" translate-Label="AddressData.PostalCode" />
        <Text Id="City" translate-Label="AddressData.City" />
        <Text Id="Country" translate-Label="AddressData.Country" />
      </Schema>
      <Summary>
        <Field Id="CompanyName" />
        <Field Id="FirstName" />
        <Field Id="Surname" />
        <Field Id="Street" />
        <Field Id="City" />
      </Summary>
      <DataProviders>
        <CsvDataProvider DisplayName="Kundenadressen">
          <Options>
            <FilePath>\\fileshare\addressdata.csv</FilePath>
            <HasHeaders>true</HasHeaders>
            <Delimiter>,</Delimiter>
          </Options>
          <SearchParameters>
            <Text Id="Vorname" translate-Label="AddressData.FirstName" />
            <Text Id="Nachname" translate-Label="AddressData.Surname" />
            <Text Id="Ort" translate-Label="AddressData.City" />
          </SearchParameters>
          <Mapping>
            <!-- Source = column name in CSV / Target = schema element id -->
            <Map Source="Vorname" Target="FirstName" />
            <Map Source="Nachname" Target="Surname" />
            <Map Source="Adresse" Target="Street" />
            <Map Source="Postleitzahl" Target="PostalCode" />
            <Map Source="Ort" Target="City" />
            <Map Source="Land" Target="Country" />
            <Map Source="Telefonnummer" Target="Phone" />
            <Map Source="E-Mail-Adresse" Target="Email" />
          </Mapping>
        </CsvDataProvider>
      </DataProviders>
    </Object>
    <Text Id="Salutation" translate-Label="Forms.Salutation" />
    <Text Id="Subject" translate-Label="Forms.Subject" />
    <Date Id="Date" translate-Label="Forms.Date" RelativeDate="Today" translate-Format="DateFormat.WrittenOut" />
  </Elements>
</FormsConfiguration>

Fields

<FieldsConfiguration>
  <Fields>
    <!-- Function defining how the individual fields of the "RecipientAddressData" field
    are output in the document (JavaScript) -->
    <Text Name="RecipientAddressBlock">
      <Code>
        function main() {
          if ($("Forms.RecipientAddressData") !== undefined){
            const firstRecipient = $("Forms.RecipientAddressData");

            var recipientBlock = $.joinNonEmpty("\n",
              firstRecipient.CompanyName != "" ? firstRecipient.CompanyName : firstRecipient.FirstName + " " + firstRecipient.Surname,
              firstRecipient.Street,
              firstRecipient.PostalCode + " " + firstRecipient.City);

            if (firstRecipient.Country != "CH"){
              recipientBlock += "\n" + firstRecipient.Country;
            }
            return recipientBlock;

          } else {
            return "";
          }
        }
      </Code>
    </Text>
  </Fields>
</FieldsConfiguration>

Basic structure​

Designer​

Example​

Overview​

Integrating additional profiles into a template​

Adaptive input mask​

Elements​

Group​

Info​

Text​

Date​

YesNo​

Choice​

AdditionalProfile​

Objects and ObjectCollections​

Batch creation via SelectedObjectId​

Accessing globally stored entries​

GlobalSchemaAndSummary​

GlobalDataProviders​

GlobalElements​

Translations​

Glossary​

Detailed example​

Forms​

Fields​

Basic structure

Designer

Example

Overview

Integrating additional profiles into a template

Adaptive input mask

Elements

Group

Info

Text

Date

YesNo

Choice

AdditionalProfile

Objects and ObjectCollections

Batch creation via `SelectedObjectId`

Accessing globally stored entries

GlobalSchemaAndSummary

GlobalDataProviders

GlobalElements

Translations

Glossary

Detailed example

Forms

Fields