Globale Konfigurationen

Owned by Daniela Zimmermann
Last updated: Aug 02, 2024 by Dinah Bolli (Unlicensed)Version comment
8 min read

In den Globalen Konfigurationen werden alle Konfigurationen, die in mehreren Vorlagen verwendet werden, in Gruppen unterteilt abgelegt. Der Vorteil liegt darin, dass so Texte und Konfigurationen nur an einem Ort geändert werden müssen.

Würde z. B. die Konfiguration für eine Adressschnittstelle in jeder Vorlage einzeln eingebaut werden, müsste bei einer Anpassung jede Vorlage angepasst werden. Dies ist viel aufwändiger, als die Adressschnittstelle lediglich an einer Stelle in den Globalen Konfigurationen anzupassen.

Neuer Eintrag erstellen

image-20240729-105954.png

Name (ID)

Die Globalen Konfigurationen kennen zwei Ebenen: ein Eintrag ist in einer Gruppe und hat einen Namen. Beide zusammen ergeben die ID des globalen Eintrags. Diese sieht also zum Beispiel so aus: GroupName.EntryName.

Neue Gruppe erstellen: Wird der ganze Name ersetzt mit FieldsDefaults.Letter, wird eine neue Gruppe "FieldsDefaults" erstellt mit einem neuen Eintrag "Letter".

Mehr Ebenen: Man kann einen globalen Eintrag nicht “tiefer” konfigurieren als in eine Gruppe. Auch wenn das UI dies nicht visuell unterstützt, kann man die ID trotzdem mit einer weiteren Unterteilungen mittels Punkten ausstatten, wenn man das möchte: GroupName.SubGroup1Name.SubGroup2Name.EntryName

Typ

Einem globalen Eintrag muss ein Typ zugewiesen werden. Der Typ wird je nach Zielkonfiguration gewählt:

Typ

Zielkonfiguration

Typ

Zielkonfiguration

FormsGlobalElements

für Felder in der Dokumentfunktion Formulare (Forms)

Forms-Elemente vom Typ Group können nicht global abgelegt werden.

FormsGlobalDataProviders

für Datenschnittstellen in Forms

FormsGlobalSchemaAndSummary

für Datenschnittstelle | Schema und Datenschnittstelle | Summary

FieldsGlobalFields

für Felder in der Dokumentfunktion Felder (Fields)

FieldsGlobalCode

zum Abspeichern von JavaScript-Funktionen, siehe weiter unten

PlaceholderGlobalMappings

für Felder in der Dokumentfunktion Platzhalterzuordnung (PlaceholderMapping)

PlaceholderGlobalDefinitions

für Felder in der Dokumentfunktion Platzhalterdefinition (PlaceholderDefinition)

DataGlobalSchema

für Schemas für die Dokumentfunktion Data

Untyped (classic)

Für alle Dokumentfunktionen der classic-Vorlagen.

Wieso eine Typisierung?

Der Vorteil der Typisierung der globalen Einträge ist die Validierung, die damit ermöglicht wird.

  • Ist der Typ des globalen Eintrags definiert, lässt sich die XML-Konfiguration mit der entsprechenden Unterstützung von Element- und Attributvorschlägen vornehmen, als ob man sich in der entsprechenden Dokumentfunktion befänden. Ausnahme davon bleibt der Typ Untyped, der in classic Vorlagen eingesetzt wird.

  • Es ist klar, in welcher Dokumentfunktion das entsprechende Feld gefunden und referenziert werden darf. z.B. können Sie in einer Felder (Fields)-Konfiguration einer Vorlage nur globale Einträge vom Typ FieldsGlobalFields verknüpfen.

MyEntry-20240115-142003.png
Vorschläge von möglichen Feldern in einer globalen Fields-Konfiguration

Umgang mit typisierten Einträgen

Globale Einträge in den Vorlagen referenzieren

Damit ein globaler Eintrag in einer Vorlage referenziert werden kann, wird immer mit dem Element <Global... Key="GroupName.EntryName" /> gearbeitet.

  • Global... Element: Der Name des genauen Elements ist je nach Dokumentfunktion unterschiedlich (siehe Tabelle unten).

  • Key: Um einen globalen Eintrag schlussendlich zu referenzieren, wird als Key die ganze ID des globalen Eintrags benötigt (der EntryName allein oder sogar ein Feldname werden nicht funktionieren).

Hier eine Übersicht über alle <Global... />-Elemente je nach Dokumentfunktion:

Dokumentfunktion

Element, um globaler Eintrag zu holen

Dokumentfunktion

Element, um globaler Eintrag zu holen

Forms

<GlobalElements Key="GroupName.EntryName" />

<GlobalSchemaAndSummary Key="GroupName.EntryName" />

<GlobalDataProviders Key="GroupName.EntryName" />

Fields

<GlobalFields Key="GroupName.EntryName" />

Platzhalterzuordnung

<GlobalMappings Key="GroupName.EntryName" />

Platzhalterdefinition

<GlobalDefinitions Key="GroupName.EntryName" />

Data

<GlobalSchema Key="GroupName.EntryName" />

Beim Bearbeiten der XML-Konfiguration in einer der fünf Dokumentfunktionen wird natürlich immer das richtige Element in der Liste mit den Vorschlägen angezeigt.

Referenzen in Globalen Einträgen

Globale Einträge können auch wiederum in anderen globalen Einträgen referenziert werden. So können ganze Hierarchien entstehen.

Beispiel 1

  • Vorlage “Brief”, Forms-Dokumentfunktion enthält

    • GlobalElement mit Key Forms.Recipient-Invitation. Diese Konfiguration enthält unter anderem wiederum

      • GlobalSchemaAndSummary mit Key Recipients.Objects.InternalListSchema enthält die finalen Felder.

    • GlobalDataProviders mit Key Recipients.Objects.DefaultProviders. Diese Konfiguration enthält die finalen Felder.

Beispiel 2

  • Vorlage “Formular”, Fields-Dokumentfunktion enthält

    • GlobalField mit Key Fields.Signers. Diese Konfiguration enthält wiederum

      • GlobalField mit Key Fields.Signers.Signer0. Diese Konfiguration enthält die finalen Felder.

      • GlobalField mit Key Fields.Signers.Signer1. Diese Konfiguration enthält die finalen Felder.

    • GlobalField mit Key Fields.EmptyDate. Diese Konfiguration enthält die finalen Felder.

Beispiel Vorlage “Sitzungseinladung”

Schauen wir uns ein Beispiel Vorlage “Sitzungseinladung” an, die vollends mit Referenzen aus den Globalen Konfigurationen ausgestattet ist.

Ziel ist es immer, eine Konfiguration von Feldern, die oft verwendet werden, mehrmals verwenden zu können. Folglich werden in diesem Beispiel diese Referenzen eingesetzt, weil es mehrere Einladungsvorlagen gibt, die dieselben Felder benötigen.

Inhalt Sitzungseinladung

Forms

Direkt in Vorlage

<FormsConfiguration> <Elements> <GlobalElements Key="Forms.Recipient-Invitation" /> <Date Id="Date" Label="Sitzungsdatum" RelativeDate="Today" translate-Format="Configuration.DateFormat.WrittenOut" /> </Elements> </FormsConfiguration>

Globale Einträge

Key: Forms.Recipient-Invitation

<FormsGlobalElements> <ObjectCollection Id="Participants" Label="Teilnehmende"> <GlobalSchemaAndSummary Key="Recipients.Objects.InternalListSchema"/> </ObjectCollection> </FormsGlobalElements>

↓ Globaler Eintrag enthält selber eine Referenz:

Key: Recipients.Objects.InternalListSchema

<FormsGlobalSchemaAndSummary> <Schema> <Text Id="FirstName" Label="Vorname" /> <Text Id="LastName" Label="Name" /> <Text Id="Alias" Label="Kürzel" /> <YesNo Id="IsLead" Label="Hat Sitzungsleitung" /> </Schema> <Summary> <Field Id="FirstName" /> <Field Id="LastName" /> <Field Id="Alias" /> </Summary> </FormsGlobalSchemaAndSummary>

Fields

Direkt in Vorlage

Globale Einträge

Key: Fields.Recipient.ParticipantsLine

Key: Fields.Date

Platzhalterzuordnung

Direkt in Vorlage

Globaler Eintrag

Key: Placeholders.Map.Invitation

Layout Sitzungseinladung

HINWEIS
Die Inhalt basiert immer auf einer Layout. In der Layout sind die Platzhalter für in die Kopf- oder Fusszeile definiert.

Platzhalterdefinition

Direkt in Vorlage

Globaler Eintrag

Key: Placeholders.Def.Invitation

GlobalCode

Manchmal benötigen unterschiedliche Fields in verschiedenen Vorlagen die genau gleiche Logik aber mit anderen Werten (z. B. andere Forms-Felder). GlobalCode ermöglicht es, eine Funktion in den globalen Konfigurationen abzuspeichern und in Fields-Feldern zu verwenden.

GlobalCode erstellen

GlobalCode wird in den Globalen Konfigurationen als Eintrag vom Typ FieldsGlobalCode erstellt.

Ein Beispiel:

Es ist ein GlobalCode mit Id Code.formatNumber in den Globalen Konfigurationen gespeichert. Er enthält eine Funktion formatForTable() mit den Parametern input (ein String) und isInCHF (ein Boolean).

Der String input wird zuerst in eine Zahl umgewandelt und wird dann abhängig von isInCHF in einem länderspezifischen Format als String ausgegeben.

Verwendung in Fields

Nun kann diese Funktion in Fields referenziert werden.

  • GlobalCode steht allen Fields zur Verfügung, d.h. ob GlobalCode in einem Field direkt in einer Vorlage oder in den Globalen Konfigurationen referenziert wird, spielt keine Rolle.

  • GlobalCode kann für jeden Field-Typen eingesetzt werden.

Zum Beispiel: In einer Fields-Konfiguration in einer Vorlage wird zwischen Start- und End-Tag eine Referenz zum vorhin erstellten GlobalCode mit Key Code.formatNumber gemacht:

Umgang mit Untyped (classic)

Die Informationen befinden sich in Datensätzen (Data-Tag), die sich wiederum in Gruppen (Group-Tag) befinden. Der Inhalt in einem Datensatz wird in einer Konfiguration nach folgendem Muster verknüpft: {[GroupName.DataName]}

Beispiel 1 – Text

Der global abgelegte Datensatz "Config.Depth" beinhaltet den Wert 5:

Beispiel 1 - Bild

Beispiel 1 - Dahinterliegendes XML:

Der Datensatz kann nun in allen XML-Konfigurationen der Dokumentfunktionen verknüpft werden. So z. B. in der XML-Konfiguration der Dokumentfunktion Skripte:

{[Config.Depth]} wird nun jeweils mit 5 ersetzt. Die Skript-Resultate werden 5 Mal durchgerechnet. Muss dieser Wert angepasst werden, kann das einmal in den Globalen Konfigurationen vorgenommen werden. Folglich wird diese Änderung in allen Vorlagen, die {[Config.Depth]} enthalten, automatisch angepasst.

Beispiel 2 – Ganzes Skript

Der global abgelegte Datensatz "Salutation" beinhaltet ein Skript:

Beispiel 2 - Bild

Beispiel 2 - Dahinterliegendes XML

 

Das Skript "Salutation" wird in allen Kundenlösungen initial als Standardskript für die Anrede in einem Brief verwendet. Deshalb wird es in Korrespondenz-Vorlagen in der Dokumentfunktion "Skripte" verknüpft:

{[Scripts.Salutation]} wird nun jeweils mit dem Inhalt aus den Globalen Konfigurationen ersetzt. Der Inhalt ist ein Skript, das zwei Contact-Elemente anzieht. In das Dokument wird also schlussendlich die Anrede eingefügt, die vom Benutzer im Empfängerdialog ausgewählt wurde.

Beispiel 3 – Ganzes Skript mit Übersetzungen

Der global abgelegte Datensatz "Enclosures" beinhaltet ein Skript mit einer Übersetzung:

Beispiel 3 - Bild

Beispiel 3 - Dahinterliegendes XML

Das Skript "Enclosures" wird vor allem in Briefen verwendet, da so eine Liste mit allen im Dokument-Parameter eingegebenen Beilagen erstellt wird. Deshalb wird es hier in Briefvorlagen in der Dokumentfunktion "Skripte" verknüpft:

{[Scripts.Enclosures]} wird nun jeweils mit dem Inhalt aus den Globalen Konfigurationen ersetzt. Der Inhalt ist ein Skript mit einer Übersetzung und dem Verweis auf ein Dokument-Parameter-Feld. Die Übersetzung wird mittels {D[Texts.Enclosures]} aus den Globalen Übersetzungen geholt.

Beispiel 4 – Skript mit Übersetzung

Der global abgelegte Datensatz "Translations" beinhaltet mehrere Skripte mit Textinhalten:

Beispiel 4 - Bild

Beispiel 4 - Dahinterliegendes XML

Die Skripte (z. B. "Texts.Draft") enthalten Übersetzungen, die in allen Briefen dienen können. Deshalb wird der Datensatz hier in einer Layoutvorlage in der Dokumentfunktion "Skripte" verknüpft:

{[Scripts.Translations]} wird nun jeweils mit dem Inhalt aus den Globalen Konfigurationen ersetzt. In allen Vorlagen, die auf dieser Layoutvorlage basieren, können diese Übersetzungen als Textfeld in die Vorlage eingefügt werden. Muss ein Wort angepasst werden, kann das einmal in den Globalen Übersetzungen vorgenommen werden. Anschliessend wird die Änderung direkt in jeder Vorlage übernommen, die diese Übersetzung verknüpft hat.

PrimeSoft AG, Bahnhofstrasse 4, 8360 Eschlikon, Switzerland