Zum Hauptinhalt springen
Version: 4.0 (2026 H1)

Formulare (Forms)

Über diese Dokumentfunktion können Eigenschaften über ein Formular abgefragt werden, indem man Textboxen, Checkboxen, Dropdowns etc. — sogenannte Elemente — konfiguriert.

warnung

Diese Funktion steht in "classic" Vorlagen nicht in vollem Funktionsumfang zur Verfügung.

Grundaufbau

<FormsConfiguration>
<Elements>
<!-- Formularelemente und Gruppen hier einfügen -->
</Elements>
</FormsConfiguration>

Designer

Öffnet man Forms im Vorlageneditor, landet man automatisch auf der einfachen Ansicht. Via Klick auf die Vorschau gelangt man in den Forms-Designer, der das Formular in einer Benutzeroberfläche zusammenstellt.

Ein Formular besteht aus verschiedenen Elementen: Strukturelementen, die zur Übersichtlichkeit beitragen, sowie Formularelementen, deren vom Benutzer eingegebene Werte schlussendlich im Dokument landen. Hinter der Benutzeroberfläche steht für jedes Element eine XML-Konfiguration, die über den Button «Erweiterte Ansicht» sichtbar wird.

Beispiel

<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>

Übersicht

Folgende Forms-Elemente sind möglich:

Strukturelemente

  • Group
  • Info

Formularelemente

  • Text
  • Date
  • YesNo (Checkbox)
  • Choice (Dropdown)
  • AdditionalProfile
  • Object oder ObjectCollection
  • GlobalSchemaAndSummary (global abgelegte Schema/Summary-Konfiguration)
  • GlobalDataProviders (global abgelegter DataProvider)
  • GlobalElements (global abgelegte Forms-Konfiguration)

Weitere Profile in Vorlage integrieren

Die Profilfelder des Benutzers, der ein Dokument generiert, werden automatisch bereitgestellt (z. B. Organisationsdaten wie Logos oder Postanschriften sowie persönliche Benutzerdaten). Mittels Profilwechsel im primedocs-Ribbon werden die Daten des ausgewählten Profils angezeigt.

Mittels AdditionalProfile können zusätzliche Profile in das Dokument integriert werden. Diese Profilauswahl zeigt die eigenen Profile des Benutzers oder ihm freigegebene Fremdprofile an. Sinnvoll ist dies z. B.:

  • bei zusätzlichen Unterschriften in einer Vorlage,
  • bei der Zusammenarbeit mit weiteren Mitarbeitenden oder Abteilungen (z. B. soll neben der Fachbereichsleiterin auch die Kostenstellenverantwortliche erwähnt werden),
  • in weiteren Anwendungsfällen.

In der Vorlage müssen entsprechend auch die Forms-Felder des AdditionalProfile eingefügt sein.

Adaptive Dateneingabemaske

Forms ermöglicht das bedingte Anzeigen von Feldern. In den Elementen YesNo und Choice kann das Erscheinen weiterer Formularelemente von einem Wert abhängig gemacht werden. Mögliche eingebettete Elemente sind: Text, Date, Choice, YesNo und Info.

Die Elemente heissen ElementsIfYes / ElementsIfNo bei YesNo (für true und false) und ElementsIfValue bei Choice (für einen spezifischen Wert).

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

Elemente

Für alle Elemente gilt: das Attribut Id (bzw. Name) wird zur Identifikation benötigt, darf keine Leerzeichen enthalten und muss eindeutig sein. Forms fügt automatisch den Präfix Forms. hinzu (aus Subject wird z. B. Forms.Subject).

Group

Gruppen sind Strukturelemente und gruppieren Formularelemente mit <Group>…</Group> für die visuelle Darstellung.

<FormsConfiguration>
<Elements>
<!-- [Formularelemente] -->
<Group Title="Telefonnummern">
<!-- [Formularelemente] -->
</Group>
<!-- [Formularelemente] -->
</Elements>
</FormsConfiguration>
warnung

Gruppen dürfen keine weiteren Gruppen enthalten (keine Verschachtelung).

Attribute für Group

AttributnameBeschreibung
Title (optional)Titel, der auf der Eingabeoberfläche angezeigt wird.

Info

Zeigt einen Informationstext im Forms-Dialog an. Der Text wird als Inhalt des Info-Elements angegeben.

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

Text

Bietet dem Benutzer die Eingabe eines Textes. In der Vorlage wird ein Nur-Text-Inhaltssteuerelement (Plain Text Content Control) eingefügt.

<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>

Attribute für Text

AttributnameBeschreibung
Id (erforderlich)Identifikation (Einfügen in der Vorlage, Verwendung in Feldern).
Label (erforderlich)Beschreibung des Elements in der Eingabeoberfläche.
Value (optional)Vordefinierter Text, den der Benutzer bearbeiten kann.
MultiLine (optional)Wenn true: Zeilenumbrüche möglich.
Required (optional)Wenn true: Eingabe erforderlich (nicht leer, nicht nur Leerzeichen). Empfohlen: zusätzlich ValidationMessage.
OnlyVisibleDuringGeneration (optional)Wenn true: Das Feld wird nur beim erstmaligen Generieren angezeigt, nicht beim erneuten Öffnen des Forms-Dialogs.

Inhalte für Text

ElementnameBeschreibung
Description (optional)Zusätzliche Information, als Tooltip angezeigt.
ValidationMessage (optional)Text, der bei ungültiger Eingabe angezeigt wird.

Date

Bietet dem Benutzer die Auswahl eines Datums (Date Picker Content Control).

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

Attribute für Date

AttributnameBeschreibung
Id (erforderlich)Identifikation.
Label (erforderlich)Beschreibung in der Eingabeoberfläche.
Format (erforderlich)Datumsformat, z. B. dd.MM.yyyy für «31.12.2020» oder d. MMMM yyyy für «31. Dezember 2020». In der Basiskonfiguration stehen mehrere Formate in den globalen Übersetzungen bereit.
Required (optional)Wenn true: Datum erforderlich. Empfohlen: zusätzlich ValidationMessage.
Value (optional)Vorausgewähltes fixes Datum (Format yyyy-MM-dd). Nicht kombinierbar mit RelativeDate.
RelativeDate (optional)Vorausgewähltes Datum relativ zur Dokumenterstellung: Today, FirstDayOfMonth, FirstDayOfYear. Mit OffsetMonths/OffsetDays weiter anpassbar. Beispiele: letzter Tag des Vormonats RelativeDate="FirstDayOfMonth" OffsetDays="-1"; letzter Tag des aktuellen Monats RelativeDate="FirstDayOfMonth" OffsetMonths="1" OffsetDays="-1".
OffsetMonths (optional)Monate, die zum relativen Datum addiert werden (positiv/negativ).
OffsetDays (optional)Tage, die zum relativen Datum addiert werden (positiv/negativ).
OnlyVisibleDuringGeneration (optional)Wenn true: nur beim erstmaligen Generieren sichtbar.

Inhalte für Date: Description und ValidationMessage (analog Text).

YesNo

Bietet dem Benutzer das Aktivieren («Ja») oder Deaktivieren («Nein») einer 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>

Attribute für YesNo

AttributnameBeschreibung
Id (erforderlich)Identifikation.
Label (erforderlich)Beschreibung in der Eingabeoberfläche.
Value (optional)Wenn true: Option ist zu Beginn aktiviert.
RequiredValue (optional)Wenn true: Benutzer muss aktivieren; wenn false: Benutzer muss deaktivieren. Empfohlen: zusätzlich ValidationMessage.
OnlyVisibleDuringGeneration (optional)Wenn true: nur beim erstmaligen Generieren sichtbar.

Inhalte für YesNo

ElementnameBeschreibung
ElementsIfYes (optional)Adaptive Dateneingabe: bei Wert true werden die enthaltenen Elemente angezeigt.
ElementsIfNo (optional)Adaptive Dateneingabe: bei Wert false werden die enthaltenen Elemente angezeigt.
Description (optional)Zusätzliche Information, als Tooltip angezeigt.
ValidationMessage (optional)Text bei ungültiger Eingabe.

Choice

Bietet dem Benutzer die Auswahl zwischen mehreren Optionen (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>

Attribute für Choice

AttributnameBeschreibung
Id (erforderlich)Identifikation.
Label (erforderlich)Beschreibung in der Eingabeoberfläche.
Required (optional)Wenn true: Auswahl erforderlich. Empfohlen: zusätzlich ValidationMessage.
SelectedValue (optional)Vorausgewählte Option (Wert aus dem Value-Attribut der gewünschten Option).
EmptyOptionLabel (optional)Beschriftung der Option, die «nichts ausgewählt» symbolisiert.
OnlyVisibleDuringGeneration (optional)Wenn true: nur beim erstmaligen Generieren sichtbar.

Inhalte für Choice

ElementnameBeschreibung
Option (erforderlich, mehrere möglich)Mögliche Auswahl. Attribute: Value und Label.
ElementsIfValue (optional)Adaptive Dateneingabe: bei Übereinstimmung mit SelectedValue werden die enthaltenen Elemente angezeigt.
Description (optional)Zusätzliche Information, als Tooltip angezeigt.
ValidationMessage (optional)Text bei ungültiger Eingabe.

AdditionalProfile

Ermöglicht das Auswählen eines zusätzlichen Profils. Angezeigt werden die eigenen Profile des Benutzers sowie ihm freigegebene Fremdprofile. Da ein Profil verschiedene Benutzerfelder hat (Vorname, Telefonnummer, Funktion, Signaturbild etc.), werden in der Vorlage alle Benutzerfelder zum Einfügen angeboten.

AdditionalProfiles können nur über die XML-Konfiguration definiert werden (nicht im Designer).

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

Attribute für AdditionalProfile

AttributnameBeschreibung
Id (erforderlich)Identifikation.
Label (erforderlich)Beschreibung in der Eingabeoberfläche.
PreselectByIndex (optional)Ganze Zahl (1, 2, …, n): Bei 1 wird das im Unterschriftsprofil erste hinterlegte Profil vorselektiert, bei n das n-te (sofern vorhanden).

Inhalte für AdditionalProfile: Description (optional) — als Tooltip angezeigt.

Objects und ObjectCollections

warnung

Diese Funktion steht nicht in "classic" Vorlagen zur Verfügung.

Object bzw. ObjectCollection bilden Objekte in der Vorlage ab — z. B. einen Empfänger, Rechnungspositionen oder beliebige andere Datenobjekte. Für ein Objekt nimmt man Object, für mehrere ObjectCollection.

Attribute für Object

AttributnameBeschreibung
Id (erforderlich)Identifikation.
Label (erforderlich)Beschreibung in der Eingabeoberfläche.
Required (optional)Wenn true: Der Benutzer muss ein Objekt anlegen/auswählen. Mit Required="true" konfigurierte Objekte können in der Vorlage direkt als Feld genutzt werden.

Attribute für ObjectCollection

AttributnameBeschreibung
Id (erforderlich)Identifikation.
Label (erforderlich)Beschreibung in der Eingabeoberfläche.
SelectedObjectId (optional)Es wird automatisch ein Object mit dieser Id erstellt.

Serienerstellung über SelectedObjectId

Wird eine ObjectCollection mit SelectedObjectId ausgestattet, wird automatisch ein Object mit dieser Id erstellt. In der Oberfläche kann ein Element selektiert werden, das den Inhalt des Objekts repräsentiert; zudem werden Optionen zur Serienerstellung des Dokuments sichtbar. Es darf pro Konfiguration nur eine ObjectCollection mit SelectedObjectId geben.

Inhalte für Object bzw. ObjectCollection

ElementnameBeschreibung
SchemaDefiniert alle Daten, die in einer Vorlage verwendet werden können.
SummaryDefiniert, welche Felder in der Listenansicht angezeigt werden.
DataProviders (optional)Definiert Datenquellen, um Objekte z. B. aus einem CRM, einer Web-API oder anderen Quellen zu laden.

Objects, ObjectCollections und DataProviders können nur über die XML-Konfiguration definiert werden. Mehr dazu auf der Seite Datenschnittstelle.

<FormsConfiguration>
<Elements>
<ObjectCollection Id="data" Label="Teilnehmende">
<!-- Definiert die Elemente der ObjectCollection für die Verwendung 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>
<!-- Definiert, welche Felder in der Listenansicht angezeigt werden -->
<Summary>
<Field Id="FirstName" />
<Field Id="LastName" />
<Field Id="Alias" />
</Summary>
<!-- Definiert die DataProviders -->
<DataProviders>
[...]
</DataProviders>
</ObjectCollection>
</Elements>
</FormsConfiguration>

Zugriff auf global abgelegte Einträge

Folgende Typen globaler Einträge können in einer Forms-Konfiguration referenziert werden:

  • GlobalSchemaAndSummary → eine global abgelegte Konfiguration mit den Elementen Schema und Summary.
  • GlobalDataProviders → eine global abgelegte Konfiguration mit CsvDataProvider, ExcelDataProvider, GlobalDataProviders, HttpDataProvider oder SqlDataProvider.
  • GlobalElements → alle anderen Elemente (z. B. Text oder YesNo), exklusive Group.

Die Referenz erfolgt bei allen Typen über das Key-Attribut (erforderlich) — die ID des globalen Eintrags.

<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

Holt einen Eintrag aus den Globalen Konfigurationen vom Typ FormsGlobalSchemaAndSummary, um ein Object oder eine ObjectCollection zu konfigurieren.

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

GlobalDataProviders

Holt einen Eintrag aus den Globalen Konfigurationen vom Typ FormsGlobalDataProviders, um ein Object oder eine ObjectCollection zu konfigurieren.

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

GlobalElements

Holt einen Eintrag aus den Globalen Konfigurationen vom Typ FormsGlobalElements.

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

Übersetzungen

Alle Elemente können übersetzt angezeigt werden. Wird ein Attribut mit dem Präfix translate- verwendet, muss das entsprechende Attribut ohne Präfix nicht zusätzlich konfiguriert werden; stattdessen wird die ID eines Eintrags der Globalen Übersetzungen angegeben.

AttributnameBeschreibung
translate-Label (optional)Übersetzte Beschreibung des Elements.
translate-Description (optional)Übersetzte zusätzliche Information.
translate-ValidationMessage (optional)Übersetzter Text bei ungültiger Eingabe.
translate-Value (optional)Übersetzter, vordefinierter Wert.
<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>

Glossar

DeutschEnglischBeschreibung
FormsFormsName der Dokumentfunktion; Gegenstück in classic-Vorlagen: «Dokument-Parameter».
Forms-DialogForms dialogDer Dialog; Gegenstück in classic: «Dokument-Parameter-Dialog».
FormularelementForm elementEin Input-Element im Forms-Dialog, z. B. Text oder Choice.
StrukturelementStructural elementElemente, die angezeigt werden, aber keinen Input anfordern (landen nicht im Document Part).
FeldFieldAlle Formularelemente, die schlussendlich im Document Part landen.
ObjektObjectÜber ein Schema definiert; manuell oder über DataProvider befüllbar.
ObjektlisteObjectCollectionEine Ansammlung von Objekten desselben Typs.
DataProviderDataProviderDefiniert eine Quelle für Objekte.

Ausführliches Beispiel

Die Reihenfolge der Formularelemente im Forms-XML bestimmt die Reihenfolge im 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 = Spaltenname 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>

Felder

<FieldsConfiguration>
<Fields>
<!-- Funktion definiert, wie die einzelnen Felder des Feldes "RecipientAddressData"
im Dokument ausgegeben werden (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>