Datamap Designer

Pflege der Datamap

• Bearbeiten (auch per Doppelklick)
• Löschen einzelner Operationen oder kompletter Datenquellen mit dem Minus Symbol.
• Duplizieren von Datenquellen oder Konfigurationen

Wichtige Hinweise & Best Practices

• Berechtigungen und Lizenzstatus frühzeitig prüfen
• Nur benötigte Felder laden (Performance & Übersichtlichkeit)
• Views, Filter und dynamische Filterfelder gezielt einsetzen
• Datenquelle und Rückgabestruktur vor Weiterverarbeitung testen
• Datenquellen und Doc-Gen-Quellen klar und eindeutig benennen, da sie häufig referenziert werden
• Komplexe Szenarien sauber und logisch in der Datamap strukturieren
• Template-Pfade eindeutig und konsistent definieren (ideal mit DocPath und alles im selben Folder aufbewahren)

Culture Handling: Where can culture be set, how they affect numbers & datetimes

Culture controls the interpretation of Number & Datetime data. Specifically, the culture decides what characters are used to seperate sections of a number or datetime. Examples for Number:

32.500,65 = formatted in culture “de-de” 32,500.65 = formatted in culture “en-us” 32 500,65 = formatted in culture “fr” 32’500.65 = formatted in culture “de-ch”

The culture of datafields can be configured two ways in dox42:

• At the bottom right when choosing the Datafield type “Number” or “DateTime”
• In the Field Formatter configured in the Datamap

When only one Culture Code is defined in the Culture field, it will only affect the Output Culture i.e. how the number should be displayed in the generated document. If two Cultures are defined in the Culture field with a syntax as such: ”en-us => en-us” the left value will define the Input Culture i.e. how the number should be interpreted, the right value will define the output culture.

If the input culture is not defined as described above, the input culture will automatically be taken from the local region settings of the generating device. Meaning if the template is generated locally with the Addin, the input culture will be based on the region settings of the local PC. If it is generated on a dox42 Server, it will depend on the settings of the server.

When calculating numbers with a Group Calculator function, a Culture field can be filled out to define, in what culture the incoming values should be calculated in. In this field, an output culture cannot be defined, therefor only one culture code should be given here.

Eingabeparameter

1. Zweck und Einordnung

• Manuelle Übergabe von Werten
• Startpunkt für Logik und weitere Datenquellen
• Besonders relevant für Add-in-Generierungen

2. Unterstützte Datentypen

Beschreibung, welche Arten von Eingaben möglich sind.

• Text
• Zahlen
• Datumswerte
• JSON
• Dateien

Hinweis: Der Eingabeparameter ist flexibel nutzbar.

3. Eingabetyp (Add-in-Darstellung)

3.1 Bedeutung des Eingabeparameter

• Die manuelle Eingabe des Eingabeparameter ist besonders wichtig für die Darstellung im Add-in
• Im Server muss der Eingabeparameter vordefiniert werden. z.B. Transaction ID

3.2 Verfügbare Darstellungsoptionen

• Freie Texteingabe
• Auswahl aus definierten Werten
• Auswahl aus Datenfeldern anderer Datenquellen
• Dateiauswahl
• Verzeichnisauswahl
• Maskierte Eingabe (z. B. Passwort)
• Querverweis zu request body CE

4. Lookup-Link

4.1 Beschreibung

Optionaler Link zur Unterstützung des Benutzers beim Ausfüllen des Eingabeparameters.

4.2 Mögliche Zieltypen

• Dokument
• Website
• Applikation

4.3 Hinweis

• Feature ist neu
• Dient primär der Orientierung und dem Testen von komplexen Templates.

5. Beispielwert (Default Value)

5.1 Zweck des Beispielwerts

• Automatische Vorbelegung beim Generieren im Add-in
• Erleichtert lokales Testen
• Wird von anderen Datenquellen als Input verwendet

5.2 Einschränkungen

• Beispielwert wird nicht bei Servergenerierungen verwendet

6. Verwendung durch andere Datenquellen

Beschreibung, wie Eingabeparameter von anderen Datenquellen genutzt werden können.

• Filterbedingungen
• Lookups
• Query-Parameter
• Logiksteuerung

Besonderheit:

• Beim Add-in-Testen wird der Default-Wert herangezogen

7. Add-in-Generierung vs. Servergenerierung

7.1 Vergleich

Aspekt	Add-in Generierung	Servergenerierung
Eingabetyp	relevant	irrelevant
Beispielwert	relevant	nicht verwendet
Übergabeformat	typabhängig	immer Text

7.2 Wichtige Klarstellung

Bei Servergenerierungen müssen alle Werte explizit über Inputparameter im DOX42-Aufruf übergeben werden, welche genauso wie im Template vordefiniert heißen.

8. Typische Anwendungsfälle

• Manuelle Parameter für Tests und Piloten
• Übergabe von IDs, Datumswerten oder Flags
• Steuerung von Filtern und Webservice-Aufrufen
• Lokales Testen komplexer Templates

9. Wichtige Hinweise & Best Practices

• Default-Werte nur für Tests verwenden

SharePoint-Datenquelle

1. Zweck und Einordnung

Die SharePoint-Datenquelle dient zum Auslesen von Daten aus SharePoint-Sites und stellt diese Daten innerhalb der Datamap für weitere Verarbeitung, Filterung und Dokumentgenerierung zur Verfügung.

Sie wird typischerweise verwendet, um Daten aus SharePoint- Listen zu lesen.

2. Authentifizierung und Berechtigungen

2.1 Berechtigungsmodell

Der Zugriff auf SharePoint erfolgt immer berechtigungsbasiert.

Die SharePoint Einrichtung ist auf der Help Seite.

Nach Konfiguration der Authentifizierung kann:

• die Verbindung getestet werden
• und anschließend das Laden der Daten geprüft werden

3. Auswahl der SharePoint-Quelle

3.1 SharePoint-Site

• Angabe der SharePoint-Site, aus der gelesen werden soll

Nach erfolgreicher Verbindung kann eine Liste ausgewählt werden

4. Datenauswahl und Konfiguration

4.1 Auswahl der Inhalte

Es kann detailliert festgelegt werden:

• welche Felder/Spalten ausgelesen werden
• ob Daten aus einer bestimmten View gelesen werden
• ob nur ein Teil der Daten geladen wird

4.2 Filterung über Query

Die SharePoint-Datenquelle unterstützt Filter:

• über definierte Queries
• um nur bestimmte Datensätze zurückzugeben

Dadurch können:

• Datenmengen reduziert
• relevante Datensätze gezielt geladen werden

4.3 Select Fields (Felder auswählen)

Über Select Fields können:

• benötigte Felder explizit ausgewählt
• Hintergrundfelder und technische Spalten ausgeblendet werden

Ziel:

• bessere Übersicht
• sauberere Weiterverarbeitung der Daten

5. Testen der Datenquelle

Nach der Konfiguration kann die Datenquelle getestet werden.

Das Testfenster zeigt:

• ob Daten geladen werden
• ob Felder korrekt zugeordnet sind
• ob Filter und Views korrekt greifen

Dies dient der Validierung vor der Weiterverwendung im Template.

6. Typische Anwendungsfälle

• Lesen von Stammdaten aus SharePoint-Listen
• Steuerung von Dokumentgenerierung über SharePoint-Views
• Zentrale Datenhaltung für automatisierte Templates

Excel-Datenquelle

1. Überblick

Die Excel-Datenquelle ermöglicht das Lesen und Schreiben von Daten aus Microsoft-Excel-Dateien innerhalb der Datamap. Sie stellt Excel-Inhalte als strukturierte Datenfelder zur Verfügung und unterstützt sowohl datengetriebene Dokumentgenerierung als auch die Erstellung von Excel-Outputs.

The dox42 Excel datasource always reads data from the top to the bottom, and not left to right.

Typische Einsatzbereiche sind Serien- und Massendruck, Datenverarbeitung sowie automatisierte Excel-Generierungen.

2. Datenquelle konfigurieren

Register: Datenquelle

In diesem Register wird die Excel-Datei angebunden und die grundlegende Konfiguration der Datenquelle vorgenommen.

2.1 Felder

Name Eindeutige Bezeichnung der Excel-Datenquelle. Der Name dient als Präfix für alle erzeugten Datenfelder. Beispiel:

<%Excel1.DatenfeldName%>

Culture Definiert das Culture-Format, das für Berechnungen sowie die Interpretation von Zahlen- und Datumswerten verwendet wird.

Datei Pfadangabe zur Excel-Datei.

2.2 Laden der Excel-Datei

Für das Laden der Excel-Datei stehen folgende Optionen zur Verfügung:

• DocPath Empfohlene Methode zur Verwendung relativer Pfade.
• Beispiel: <%DocPath%>../../

Bindet eine Excel-Datei ein, die zwei Verzeichnisse über dem Template liegt.

• Excel auswählen
  Auswahl einer Excel-Datei über einen statischen Pfad.
• Excel-Datei aus Datenfeld laden
  Aktiviert das dynamische Laden der Excel-Datei aus einem Datenfeld.
• Username/Password
  Optional für geschützte oder externe Speicherorte.

3. Excel Daten initialisieren (Schreiben)

Register: Excel Daten initialisieren

Dieses Register dient zum Schreiben von Daten in eine Excel-Datei. Dies Passiert nur im Hintergrund und wird nicht direkt in einem Excel ausgegeben. Außer man benützt die Funktion Initialisiertes Excel als Ergebnis-Datei verwenden.

3.1 Zweck

Mit Excel Daten initialisieren können:

• neue Excel-Dateien erstellt
• bestehende Excel-Dateien befüllt
• Inhalte dynamisch erweitert oder überschrieben werden

Die zu schreibenden Daten stammen aus anderen Datenquellen oder aus statischen Werten.

3.2 Spaltenbeschreibung

Zielbereich
Zielzelle oder Zielbereich im Excel-Dokument.

Zielbereich auswählen
Öffnet eine Auswahl zur direkten Definition des Zielbereichs.

Datenfeld
Referenz auf ein Datenfeld aus einer anderen Datenquelle.

Wert
Statischer Wert, der in den Zielbereich geschrieben wird.

Typ
Datentyp des einzufügenden Wertes (z. B. String, Integer).

3.3 Zielbereich erweitern

Statischer Zielbereich

• fester Bereich
• keine automatische Erweiterung

Dynamischer Zielbereich

• automatische Erweiterung
• Erweiterung erfolgt bis zum ersten leeren Wert

3.4 Schreiben unterhalb bestehender Daten

Zeilen runter schreiben

Steuert, ob neue Daten:

• unterhalb bestehender Daten eingefügt
• oder bestehende Inhalte überschreiben werden.

3.5 Tabellenblatt kopieren

Tabellenblatt kopieren Kopiert Inhalte inklusive Formatierungen:

• von einem Tabellenblatt
• in ein anderes Tabellenblatt

Diese Funktion ist insbesondere bei mehrblättrigen Excel-Generierungen relevant.

3.6 Wiederholt einfügen

Wiederholt einfügen Erlaubt das mehrfache Einfügen desselben Zielbereichs:

• gesteuert durch Iteration über eine andere Datenquelle
• geeignet für relationale oder abhängige Datensätze

4. Ergebnis Daten (Lesen)

Register: Ergebnis Daten

In diesem Register wird definiert, aus welchem Bereich der Excel-Datei Daten gelesen werden.

4.1 Output

Output

Auswahl des Outputs, z. B. Data or Charts.

4.2 Datenbereich

Datenbereich Definition des Excel-Bereichs, aus dem die Daten gelesen werden.

Erste Zeile des ausgewählten Bereichs enthält Spaltennamen Legt fest, dass die erste Zeile als Header interpretiert wird.

4.3 Lesen bis zur ersten leeren Zeile

In der Feldübersicht kann pro Datenfeld die Option gesetzt werden:

Bis zur ersten leeren Zeile

Hinweise:

• Es sollte nur ein einziges Feld mit dieser Option markiert werden
• Dieses Feld bestimmt die maximale Anzahl der gelesenen Datensätze
• Empfohlen ist ein Feld mit durchgehend gefüllten Werten (z. B. ID-Feld)

4.4 Feldübersicht

Die Ergebnisstruktur enthält folgende Spalten:

• Datenfeld Name
• Bis zur ersten leeren Zeile
• Feldtyp

5. Initialisiertes Excel als Ergebnis-Datei

Das initialisierte Excel als Ergebnis-Datei verwenden (nur für dox42 for Spreadsheets)

Ein initialisiertes Excel kann:

• gleichzeitig als Datenquelle
• und als Ergebnis-Excel (Output) verwendet werden

Einschränkung: Ein solches Excel darf nur einmal in der gesamten Datamap als Output definiert werden.

6. Testen der Excel-Datenquelle

Die Excel-Datenquelle kann getestet werden, um:

• das erfolgreiche Laden der Excel-Datei zu prüfen
• die erzeugte Feldstruktur zu kontrollieren
• sicherzustellen, dass der definierte Datenbereich korrekt gelesen wird

7. Typische Anwendungsfälle

• Serien- und Massendruck (ein Dokument pro Datensatz)
• Strukturierte Datenübergabe an Templates
• Generierung von Excel-Outputs mit berechneten Inhalten
• Erstellung von Diagrammen

8. Best Practices

• Option „Erste Zeile … enthält Spaltennamen“ korrekt setzen
• „Bis zur ersten leeren Zeile“ nur einmal setzen (z.B. ID- oder Pflichtfeld)
• Initialisiertes Excel nur einmal als Output verwenden

XML / JSON-Datenquelle

1. Zweck und Einordnung

Die XML / JSON-Datenquelle dient zum Einlesen und Strukturieren von XML- oder JSON-Daten, um diese als strukturierte Datenfelder innerhalb der Datamap weiterzuverwenden.

Sie wird eingesetzt, wenn:

• strukturierte Daten aus Dateien oder Webservices vorliegen
• komplexe Datenstrukturen verarbeitet werden müssen
• externe Systeme XML- oder JSON-Payloads liefern

2. Quelle der Daten

2.1 Herkunft der XML / JSON-Daten

Die Daten können aus unterschiedlichen Quellen stammen:

• Dateipfad (lokale oder angebundene Datei)
• Webservice (z. B. REST-Service)
• anderes Datenfeld (z. B. Request Body aus einer anderen Datenquelle)

2.2 Authentifizierung bei Webservices

Wenn die XML- oder JSON-Daten über einen Webservice bezogen werden:

• können zusätzliche Authentifizierungsinformationen erforderlich sein
• diese werden über HTTP-Header konfiguriert (z. B. Token, Credentials)

3. Initialisierung und Felder

3.1 Grundprinzip

Die Struktur der XML- oder JSON-Daten wird nicht automatisch angenommen, sondern explizit definiert.

Die Konfiguration erfolgt im Bereich:

• Initialisierung und Felder

3.2 Initialisieren (Init-Funktion)

Der empfohlene Standard-Workflow ist:

• Klick auf Initialisieren (Init)
• Auswahl der XML- oder JSON-Quelle
• Anzeige des gesamten Schemas
• Auswahl der Elementebene, ab der Daten gelesen werden sollen
• Bestätigung → automatische Erstellung aller darunterliegenden Felder

Empfehlung:

• Die Init-Funktion verwenden, da eine manuelle Definition aufwendiger ist

3.3 Manuelle Initialisierung

Alternativ können alle Felder und die Struktur auch manuell definiert werden.

4. Datenstruktur und Ausleselogik

4.1 Elementebene

Beim Initialisieren wird festgelegt:

• von welchem XML-/JSON-Element ausgelesen wird
• alle darunterliegenden Elemente werden als Felder verfügbar gemacht

Dies ist entscheidend für:

• Iterationen
• Gruppierungen
• korrekte Datenzuordnung

4.2 Mehrwertige Felder / vordefinierte Szenarien

Es existieren vordefinierte Initialisierungsoptionen für spezielle Szenarien:

• sogenannte Multi-Value-Field-Apps
• nützliche vorbereitete Templates für:
  • SharePoint-App-Szenarien
  • CE-Szenarien (z. B. Request Body)

Diese Optionen helfen, gängige Strukturen schneller korrekt zu initialisieren.

5. Verwendung als Request Body

Die XML / JSON-Datenquelle kann:

• als Request Body für andere Datenquellen dienen
• insbesondere in Kombination mit Webservices

Dabei wird:

• die Struktur einmal sauber definiert
• und anschließend wiederverwendet

6. Testen der XML / JSON-Datenquelle

Nach der Initialisierung kann geprüft werden:

• ob die Struktur korrekt erkannt wurde
• ob alle benötigten Felder vorhanden sind
• ob die Daten erwartungsgemäß gelesen werden

7. Typische Anwendungsfälle

• Verarbeitung von REST-API-Antworten
• Strukturierung von komplexen JSON-Payloads
• Auslesen von XML-Dateien
• Übergabe von Request Bodies an Webservices
• Dynamische Steuerung von Dokumentgenerierung

8. Wichtige Hinweise & Best Practices

• Immer Init-Funktion bevorzugen
• Elementebene bewusst wählen
• Tiefe Strukturen frühzeitig testen

Datenbank-Datenquelle

1. Zweck und Einordnung

Die Datenbank-Datenquelle dient zum Auslesen von Daten aus relationalen Datenbanken und stellt diese Daten als strukturierte Datenfelder innerhalb der Datamap zur Verfügung.

Sie wird verwendet, wenn:

• Daten direkt aus einer Datenbank benötigt werden
• SQL-basierte Abfragen eingesetzt werden sollen
• Daten für weitere Verarbeitung, Filterung oder Dokumentgenerierung bereitgestellt werden
• On-Prem Szenarien vorliegen

2. Unterstützte Verbindungstypen

2.1 Datenbank-Provider

Die Datenbank-Datenquelle unterstützt folgende Verbindungstypen:

• OLE DB
• ODBC

Der jeweilige Provider bestimmt:

• den Aufbau des Connection Strings
• ob bestimmte Zusatzfunktionen (z. B. Query Designer) verwendbar sind.

3. Verbindung zur Datenbank

3.1 Connection String

Die Verbindung zur Datenbank wird über einen Connection String definiert.

Der Connection String enthält:

• Server-Informationen
• Datenbank-Name
• Authentifizierungsinformationen
• Provider-spezifische Parameter

3.2 Authentifizierung

Die Authentifizierung ist:

• abhängig vom verwendeten Provider
• Bestandteil des Connection Strings
• Ohne gültige Verbindung können keine Daten gelesen werden.

4. Abfrage der Daten

4.1 SQL-Statement

Die Datenabfrage erfolgt primär über:

• SQL-Statements

Dabei können:

• eigene SQL-Queries formuliert
• Daten gezielt eingeschränkt und strukturiert abgefragt werden

4.2 Datenfelder einfügen

Innerhalb eines SQL-Statements können:

• Datenfelder aus anderen Datenquellen eingefügt werden

Dies ermöglicht:

• dynamische Abfragen
• Filterung basierend auf vorherigen Datenquellen oder Eingabeparametern

5. Query Designer

5.1 Zweck

Der Query Designer ermöglicht:

• das visuelle Erstellen von Abfragen
• ohne vollständige manuelle SQL-Schreibarbeit

5.2 Einschränkung

• Der Query Designer funktioniert nur mit OLE DB
• Für ODBC muss die query reinkopiert werden

6. Testen der Datenabfrage

Über den Test-Button kann:

• das SQL-Statement ausgeführt
• und das Ergebnis der Abfrage angezeigt werden

Der Test dient dazu:

• die Korrektheit der Abfrage zu prüfen
• sicherzustellen, dass die erwarteten Daten zurückgeliefert werden

10. Wichtige Hinweise & Best Practices

• SQL-Statements gezielt und performant halten
• Abfragen immer über den Test-Button validieren

Webservice-Datenquelle

1. Zweck und Einordnung

Die Webservice-Datenquelle dient zum Abrufen von Daten aus externen Webservices und stellt deren Rückgabewerte als strukturierte Datenfelder innerhalb der Datamap zur Verfügung.

Sie wird eingesetzt, wenn:

• Daten von externen Systemen benötigt werden
• REST- oder vergleichbare Webservice-Aufrufe erfolgen sollen
• dynamische Inhalte zur Laufzeit geladen werden müssen

2. Art des Webservices

2.1 Allgemeines

Die Webservice-Datenquelle ist nicht auf einen bestimmten Servicetyp beschränkt.

Sie kann verwendet werden für:

• REST-Services
• sonstige Webservices, die strukturierte Outputs liefern

Die konkrete Funktionalität hängt vom jeweiligen Webservice ab.

3. Konfiguration des Webservice-Aufrufs

3.1 Webservice-Adresse

Es wird definiert:

• welcher Webservice aufgerufen wird
• welcher Endpoint verwendet wird

3.2 Security / Authentifizierung

Falls der Webservice abgesichert ist, können:

• Security-Header
• Authentifizierungsinformationen (z. B. Tokens, Credentials)

mitgegeben werden.

Diese sind erforderlich, damit:

• der Webservice den Aufruf akzeptiert
• Daten erfolgreich zurückgegeben werden

3.3 Übergabe von Eingabewerten

Wenn der Webservice:

• Inputparameter erwartet
• oder unterschiedliche Ergebnisse je nach Anfrage liefern soll

können diese Werte:

• aus Eingabeparametern
• oder aus anderen Datenquellen

an den Webservice übergeben werden.

4. Rückgabedaten (Output)

4.1 Verarbeitung der Antwort

Der Output des Webservice-Aufrufs wird als Datenquelle zurückgegeben und kann anschließend, wie jede andere Datenquelle, weiterverwendet werden

Die zurückgelieferten Daten stehen für Filter, Logik und Generierung zur Verfügung

4.2 Weiterverwendung

Die Rückgabewerte können:

• direkt im Template verwendet werden
• als Grundlage für weitere Datenquellen dienen
• für Iterationen, Filter oder Berechnungen herangezogen werden

5. Kombination mit XML / JSON

In der Praxis wird die Webservice-Datenquelle häufig:

• gemeinsam mit der XML / JSON-Datenquelle verwendet

Typischer Ablauf:

1. Webservice liefert XML oder JSON
2. XML / JSON-Datenquelle strukturiert die Antwort
3. Strukturierte Felder werden weiterverwendet

6. Testen der Webservice-Datenquelle

Nach der Konfiguration kann geprüft werden:

• ob der Webservice erreichbar ist
• ob Authentifizierung korrekt ist
• ob ein gültiger Output zurückgegeben wird

Das Testen ist essenziell, um:

• Fehler frühzeitig zu erkennen
• korrekte Datenstrukturen sicherzustellen

7. Typische Anwendungsfälle

• Abruf von Daten aus externen Systemen
• Dynamische Datenanreicherung
• Steuerung von Dokumentinhalten über APIs
• Kombination externer und interner Datenquellen

8. Wichtige Hinweise & Best Practices

• Security-Header immer korrekt konfigurieren
• Eingabewerte klar definieren
• Webservice-Logik sauber von XML/JSON-Strukturierung trennen

Doc-Gen-Datenquelle

1. Zweck und Einordnung

Die Doc-Gen-Datenquelle dient dazu, andere Dokumente oder Dateien innerhalb eines Templates zu generieren und weiterzuverwenden.

Sie wird eingesetzt, wenn:

• ein Template andere Templates oder Dokumente einbettet
• Dokumente verschachtelt generiert werden sollen
• Inhalte aus externen Dateien als generierter Output benötigt werden

2. Unterstützte Dateitypen

Die Doc-Gen-Datenquelle kann folgende Dateitypen verarbeiten:

• PDF
• DOC / DOCX
• Textdateien
• Custom Formate (z.b. XML)

Diese Dateien werden nicht nur gelesen, sondern als generierter Output behandelt.

3. Grundkonzept der Doc-Generierung

3.1 Template-basierte Generierung

Die Doc-Gen-Datenquelle arbeitet template-basiert:

• Es wird ein Template-Pfad angegeben (DOCX)
• Dieses Template wird innerhalb des aktuellen Templates generiert
• Das Ergebnis kann weiterverwendet oder ausgegeben werden

3.2 Output-Format

Das Format definiert:

• in welchem Format der generierte Output vorliegt
• unabhängig davon, welches Format das ursprüngliche Template hatte

Beispiele:

• DOCX-Template → PDF-Output
• DOCX-Template → DOCX-Output

4. Rückgabewerte der Doc-Gen-Datenquelle

4.1 Base64-kodierter Output

Der generierte Inhalt liegt:

• Base64-encoded vor

Dieser Base64-Output kann:

• an andere Datenquellen übergeben werden
• für weitere Verarbeitungsschritte genutzt werden

4.2 Direkter Output im Ziel-Format

Zusätzlich steht:

• der direkte Output im gewählten Format zur Verfügung

Damit kann das generierte Dokument:

• direkt eingefügt
• weitergereicht
• oder final ausgegeben werden

5. Typische Einsatzlogik

Ein häufiger Anwendungsfall ist:

• Doc-Gen-Datenquelle generiert ein Dokument
• Ergebnis wird Base64-encoded bereitgestellt
• Das Dokument wird:
• • in ein anderes Template eingebettet
  • oder von einer weiteren Datenquelle verarbeitet

6. Verwendung in der Data Map

Die Doc-Gen-Datenquelle kann:

• als Input für weitere Datenquellen dienen
• von Output-Actions verwendet werden
• in komplexen Template-Ketten eingesetzt werden

7. Typische Anwendungsfälle

• Einbetten von Unter-Templates
• Generierung von Anhängen
• Mehrstufige Dokumentgenerierung
• Wiederverwendung von Dokumentlogik

8. Wichtige Hinweise & Best Practices

• Output-Format bewusst wählen
• Base64-Output nur verwenden, wenn nötig
• Sie wird oft für die Generierung von E Rechnungen genutzt (z.B. Zugferd).

Word-Datenquelle

• Liest:
• • gesamten Dokumentinhalt oder
  • einzelne Content Controls
• Inhalte werden als Datenfelder verfügbar gemacht
• Keine Änderung oder Generierung des Input Dokuments selbst

4. Output-Charakteristik

• Output ist:
• • Text
  • oder strukturierter Word-Inhalt
• Kein Datei-Output
• Kein Formatwechsel

Unterschied: Doc-Gen-Datenquelle vs. Word-Datenquelle

Aspekt	Word Datenquelle	Doc Gen Datenquelle
Hauptfunktion	Inhalte auslesen	Dokumente generieren
Arbeitsrichtung	Lesen	Erzeugen
Rolle	Input	Output / Zwischenschritt
Template Verwendung	nein	ja
Dokumenterstellung	nein	Ja
Base64 möglich?	Kein Base64 Output	Base64 + direkter Output

Konfigurations-Operationen

1. Zweck und Einordnung

Konfigurations-Operationen erweitern bestehende Datenquellen um Logik, Transformationen und Steuerungsmechanismen, ohne neue Daten zu laden.

Sie werden eingesetzt, um:

• Daten zu filtern, sortieren und gruppieren
• Berechnungen durchzuführen
• Relationen zwischen Datenquellen herzustellen
• Iterationen und Massengenerierungen zu steuern
• Darstellung und Verhalten von Datenfeldern zu beeinflussen

Konfigurations-Operationen werden innerhalb einer bestehenden Datenquelle definiert.

2. Filter & Sort

2.1 Zweck

Mit Filter & Sort können Datensätze:

• eingeschränkt (gefiltert)
• und in eine definierte Reihenfolge gebracht (sortiert) werden

2.2 Filterlogik

Filter können definiert werden:

• über statische Werte
• oder dynamisch über andere Datenfelder

Unterstützte Operatoren:

• gleich
• nicht gleich
• größer
• kleiner
• größer gleich
• kleiner gleich
• like:
• not like

2.3 Sortierung

• Sortierung erfolgt getrennt vom Filter
• Sortiert wird nach einem ausgewählten Datenfeld
• Filter und Sortierung können gleichzeitig aktiv sein

3. Gruppenkalkulator

3.1 Zweck

Der Gruppenkalkulator ermöglicht Aggregationen und gruppenbasierte Berechnungen innerhalb einer Datenquelle.

3.2 Unterstützte Funktionen

• Summe
• Durchschnitt
• Minimum
• Maximum
• Count
• Row (aktuelle Zeile)
• Start Group
• End Group

3.3 Bedeutung spezieller Funktionen

• Count: Anzahl der Datensätze
• Row: aktuelle Zeilenposition in der Iteration
• Start Group: erkennt, ob sich ein Gruppenwert gegenüber der vorherigen Zeile geändert hat
• End Group: erkennt, ob sich der Gruppenwert in der nächsten Zeile ändern wird

3.4 Gruppierung

Zusätzlich kann ein Gruppierungsfeld definiert werden, um Berechnungen auf Gruppenebene durchzuführen.

Das Ergebnis wird als neues Datenfeld bereitgestellt.

Tipp: Gruppen sind aufeinanderfolgende gleichlautende Daten definiert.

4. Lookup-Konfiguration

4.1 Zweck

Die Lookup-Konfiguration ermöglicht das Nachschlagen von Werten in einer Datenquelle – vergleichbar mit VLOOKUP in Excel.

4.2 Funktionsweise

• Es wird anhand einer Bedingung gesucht
• Ein Wert aus einer anderen Datenquelle wird zurückgegeben
• Prinzipiell für alle Datenquellen nutzbar

4.3 Einsatzgebiet

• Relationen zwischen Datenquellen
• Anreicherung von Datensätzen
• Auflösung von Referenzen (IDs → Werte)

5. Dynamisches Feld

5.1 Zweck

Das dynamische Feld erlaubt die Ausführung von Code-Logik innerhalb der Data Map.

5.2 Technische Grundlage

• Umsetzung über .NET / Visual-Basic-ähnliche Funktionen
• Es kann nur eine einzelne Ausgabe pro Feld erfolgen

5.3 Nutzung

• Berechnungen
• Transformationen
• Formatänderungen
• Konvertierungen (z. B. Base64)

Das Ergebnis wird als neues Datenfeld verfügbar gemacht.

Dynamic Field functions

While dox42 is mostly a no code solution, dynamic fields are a tool to realize some specific output not realized in the core product. Dynamic fields use vb.net code, for more information about how to use this feature please refer to Visual Basic Documentation A couple of frequently used functions will be explained in the following section.

For most vb.net functions you will have to write out the full namespace of the function for it to be reached.

Base64 En/Decoder

result = System.Convert.FromBase64String(Datasource.Datafield)

Base64 is a binary-to-text encoding scheme that converts binary data into a sequence of printable ASCII characters.

What is Base64 Used For in the context of dox42?

Base64 is commonly used in various applications, including:

Embedding Data in Web Pages: Base64 can embed images or other binary data directly into HTML or CSS files, reducing the number of HTTP requests needed to load a webpage

Data Storage: It can be used to store binary data in text-based formats like JSON or XML

SubString

dim var1 as String =Datasource.Datafield

If var1.Length > 10 Then

result = var1.Substring(0,10)

Else

result = var1

End If

SubString is commonly used to reduce the length of datafields to a set number of characters for situations where the string length is limited.

Datatype conversions

' This is a comment

' All dox42 fields are interpreted as Strings by default.

' To use them as - for example - Integers try the following

dim observedMonthAsInt as Integer = Integer.Parse(months.ID_month)

In that example you would parse the dox42 field “months.ID_month“

Replace Character

result = Datasource.Datafield.Replace("/", ".")

The replace function is often used to replace or cut certain illegal or unnecessary characters from dafields.

Get Type of a Variable

Dim longValue As Long = 2 * datasource.feld3

result = longValue.GetType().Name

Returns the type of a Variable. Useful for testing and bug fixing

Looping through an array

Dim intArray() As Integer = New Integer() {2,4,datasource.feld3}

Dim accumulator = 0

For Each item As Integer In intArray

accumulator += item

Next

result = accumulator

Creates an Array (which can also contain a dox42 field), allows you to loop through it and acts based on contents.

In this case, all elements of the Array are added (must all be integers) and returned.

Timestamp

Dim stamp As DateTime = DateTime.Now

Dim year AS String = stamp.Year

Dim month AS String = stamp.Month

Dim day AS String = stamp.Day

Dim hour AS String = stamp.Hour

Dim minute AS String = stamp.Minute

Dim millisecond AS String = stamp.Millisecond

result = year + "-" + month + "-" + day + "_" + hour + "-" + minute + "-" + millisecond

Returns the current execution timestamp. Example output would be: “2025-3-3_16-51-677“

It might be useful for performance testing.

GetValue

Needed when processing datafields with unique naming conventions, like when obtaining LinkedEntitiy fields from Dataverse using FetchXML.

return GetValue("Account.contact.fullname")

6. Massendruck

6.1 Zweck

Der Massendruck ermöglicht die Serien- bzw. Massengenerierung von Dokumenten.

Grundprinzip:

• Ein Dokument pro Datensatz (z. B. pro Excel-Zeile)

6.2 Funktionsweise

• Die Iteration erfolgt automatisch über die Datenquelle
• Alle Datenfelder im Template werden zeilenweise ersetzt
• Die Loop-Logik entsteht ausschließlich durch den Massendruck

6.3 Fehlerverhalten

Es kann konfiguriert werden:

• ob die Generierung bei einem Fehler abbricht
• oder trotz Fehler fortgesetzt wird

Relevant auch für Servergenerierungen.

Important: Save document as ist der definierte Zielpfad, DocPath kann verwendet werden und dynamische Namensgebung muss verwendet werden, sonst wird nur ein Dokument ausgegeben.

Tipp: Ausgabeformat wird auch in dem save „document as“ pfad definiert. Spezialformate können hier auch gesetzt werden (z.b. pdfform oder pdfa).

7. Feldformatierung

7.1 Zweck

Die Feldformatierung steuert:

Darstellung von Zahlen und Datumswerten

Interpretation und Ausgabeformaten

7.2 Kultur (Culture)

Die Kultur bestimmt:

Trennzeichen

Interpretation von Zahlen

Datumslogik (z. B. Tag/Monat/Jahr)

Culture controls the interpretation of Number & Datetime data. Specifically, the culture decides what characters are used to separate sections of a number or datetime. Examples for Number:

32.500,65 = formatted in culture “de-de” 32,500.65 = formatted in culture “en-us” 32 500,65 = formatted in culture “fr” 32’500.65 = formatted in culture “de-ch”

The culture of datafields can be configured in dox42:

At the bottom right when choosing the Datafield type “Number” or “DateTime”

In the Field Formatter configured in the Datamap

When only one Culture Code is defined in the Culture field, it will only affect the Output Culture i.e. how the number should be displayed in the generated document. If two Cultures are defined in the Culture field with a syntax as such: ”en-us => en-us” the left value will define the Input Culture i.e. how the number should be interpreted, the right value will define the output culture.

If the input culture is not defined as described above, the input culture will automatically be taken from the local region settings of the generating device. Meaning if the template is generated locally with the Addin, the input culture will be based on the region settings of the local PC. If it is generated on a dox42 Server, it will depend on the settings of the server. Dox42 online servers use EN-US culture by default.

When calculating numbers with a Group Calculator function, a Culture field can be filled out to define in what culture the incoming values should be calculated in. In this field, an output culture cannot be defined, therefore only one culture code should be given here.

7.3 Format String

Der Format String definiert:

• das konkrete Ausgabeformat
• Position und Darstellung der Werte

Bei Datumswerten:

• kann zusätzlich ein Input-Format-String definiert werden
• relevant bei unterschiedlicher Eingangs- und Ausgangsstruktur

Microsoft Documentation

8. Visualisierer

8.1 Zweck

Der Visualisierer dient der Übersicht und Strukturierung im Designer, nicht der Dokumentausgabe.

8.2 Funktionen

• Einfärbung von Datenquellen
• Anzeige-Icons für Datenquellen
• Ein- und Ausblenden von Datenquellen im Designer
• Ein- und Ausblenden einzelner Datenfelder
• Anpassung der Anzeigenamen im Frontend (Backend-Namen bleiben unverändert)

8.3 Abgrenzung

• Farben im Visualisierer betreffen Datenquellen und Felder
• Farben automatisierter Bereiche werden direkt im Template gesteuert

Kurz-Zusammenfassung

Konfigurations-Operationen ermöglichen Logik, Transformation und Steuerung innerhalb bestehender Datenquellen und sind essenziell für komplexe Templates und Massengenerierungen.