Dokumentation

3.2.1. Scopes

Die Grundlage eines Templates bildet der Datenkontext, welcher durch "Scopes" definiert wird. Scopes sind die Datenquellen deiner Salesforce Organisation. Sie können verschiedene Ebenen haben und erlauben den Zugriff auf die gesamte Datenstruktur in Salesforce.

Zuerst muss eine Primary Scope angelegt werden. Klicke dafür entweder auf 'Add Scope' in der oberen Leiste oder auf 'New' im Bereich der Scopes, und wähle 'Primary'.

X

In diesem Beispiel wählen wir das Salesforce-Objekt 'Invoice' als Primary Scope. Zusätzlich zu der Primary Scope kannst du hier per Klick auf den Button “Create Child Scope” innerhalb der Primary Scope sogenannte Field Scopes und List Scopes erstellen. Diese sind sogenannte “Children” der Primary Scope, d.h. dass sie sich auf Daten innerhalb des Objektes der Primary Scope beziehen. Per Klick auf den Button “New” im Scope Datensatz kannst du außerdem eine Free Scope erstellen.

X

• Field Scopes beziehen sich auf Lookup Felder des Objektes und die Daten der Objekte, auf die das Lookup zeigt (Bsp. Ein Account).
• List Scopes beziehen sich auf Daten aus den Listen des Objekts (Bsp. Alle Kontakte unterhalb des im Field Scope definierten Accounts).
• Free Scopes beziehen sich auf alle Datensätze in Salesforce und müssen keine Verbindung zu einer Field- oder List Scope haben (Bsp. Alle Produkte in Salesforce).

Record Rules

Für List und Free Scopes lassen sich sogenannte Record Rules erstellen, durch welche konfiguriert werden kann, welche und wie viele Einträge der Liste tatsächlich in der Scope berücksichtigt werden.

Es gibt drei Arten von Record Rules:

• Filter Record Rule
• Limit Record Rule
• Order Record Rule

Filter Record Rule

Mit einer Filter Record Rule lassen sich Einträge der Liste basierend auf dem Wert eines Feldes des Objekts filtern. Hier werden 'Field Name' und 'Value' durch den 'Operator' verglichen, und lediglich Einträge der Liste, für welche diese Kondition wahr ist, werden weiterhin in der Scope berücksichtigt.

X

Limit Record Rule

Mit einer Limit Record Rule lässt sich eine numerische Grenze festlegen, wie viele der Einträge berücksichtigt werden sollen. Erstelle dafür einfach eine Limit Record Rule und trage den gewünschten Wert in 'Value' ein.

X

Order Record Rule

Mit einer Order Record Rule können die Einträge der Liste basierend auf einem Wert des Objekts sowohl aufsteigend als auch absteigend sortiert werden. XRSF erlaubt außerdem die Erstellung mehrerer Order Record Rules, welche in sich durch das Feld 'Priority' priorisiert werden können. Basierend auf diesem Feld werden aufsteigend die einzelnen Order Record Rules angewendet.

X

3.2.2. Data Configurations

Nachdem die Scopes festgelegt sind, kann mit der Konfiguration der Data Configurations begonnen werden. Hier wird definiert, welche Felder der E-Rechnung mit welche Daten aus deiner Salesforce Organisation, also aus deinen Scopes, befüllt werden sollen. Um solche Konfigurationen vorzunehmen, klicke den Button 'Configure' in der oberen Leiste.

X

Nun öffnet sich ein Feld, in welchem du Konfigurationen vornehmen kannst.

X

Im Bereich Configure children kannst du nun eine Konfiguration hinzufügen. Dafür müssen die Felder 'Attribute' und 'Scope' gewählt werden.

'Attribute' definiert, wo in deiner Rechnung die Daten stehen sollen. Dabei ist die Struktur der Attribute in dieser Oberfläche die gleiche Struktur wie im zugehörigen Standard definiert. Liegt der Wert (Value), welcher gewünscht ist, in einer Node, wähle hier die zugehörige Node, und klicke dann auf 'Add'. Nodes können nicht mit Daten befüllt werden, allerdings kannst du nun auf den Inhalt der Node zugreifen, indem du innerhalb der Node auf 'Configure' klickst. Es öffnet sich ein neues Fenster, in welchem du dich nun eine Ebene tiefer im XML-Pfad befindest und hier weitere Konfigurationen vornehmen kannst.

X

In 'Scope' kannst du die Scope wählen, aus welcher die Daten kommen sollen. Wählst du hier keine Scope, kannst du Mergefelder verwenden, statische Werte definieren oder auf vordefinierte Variablen zugreifen (z. B. Current Date, Current User ID).

X

In diesem Beispiel befüllen wir das Attribut "ID" mit dem Wert des Feldes "Account ID" aus der Scope "OrderAccount". Außerdem möchten wir für das Attribut "DueDate" keine Scope verwenden, sondern einen statischen Wert aus der Variablenliste unter 'Pick Variable' festlegen.

Nachdem alle gewünschten Konfigurationen vorgenommen wurden, klicke auf 'Save', um die Konfiguration zu speichern.

3.2.3. Field Updates

Neben den Data Configurations können in einem Template Field Updates definiert werden, mit denen Felder in deiner Salesforce Organisation Quelldatensatz nach der Erstellung einer E-Rechnung automatisch aktualisiert werden, z. B. eine Variable "Send Date" auf "CurrentDay" setzen. Field Updates können an eine Bedingung geknüpft werden, welche erfüllt sein muss, damit das Field Update tatsächlich ausgeführt wird. Soll das Field Update immer ausgeführt werden, lasse die Felder 'Condition Value' und 'Operator' einfach leer.

In diesem Beispiel möchten wir ein Field Update erstellen, welches das Feld 'Status' unserer Scope 'Invoice' auf "Created" setzt, allerdings nur, wenn das Feld vorher auf "Draft" gesetzt war.

X

3.2.4. Weitere Konfiguration von Embedded Templates

Bei der Nutzung von "Embedded" Templates gibt es weitere Konfigurationsmöglichkeiten, welche lediglich der Erstellung des PDF Dokuments dienen und dementsprechend für "XML" Templates überflüssig sind.

XMP Requirements

Ein essentielles Feld für "Embedded" Templates sind die XMP Metadaten. Dieses Feld ist entscheidend, um sicherzustellen, dass das generierte PDF-Dokument den Standards PDF/A-3B und Factur-X/ZUGFeRD entspricht. XMP (Extensible Metadata Platform) ist ein standardisiertes XML-Format zum Einbetten von Metadaten in PDF-Dateien, welche Informationen über Struktur, Herkunft und Konformitätsstufe des Dokuments liefern und von Verbrauchern und Validierungstools zur Bewertung der Konformität genutzt werden.

Um verschiedene Metadatenkonfigurationen zu unterstützen, gibt es die Picklist „XMP Requirements”, in der zwischen „Custom” und „ZUGFeRD” gewählt werden kann. Die Option "ZUGFeRD" setzt die Metadaten automatisch auf einen vordefinierten, standardkonformen Wert gesetzt, während bei "Custom" eigene Metadaten implementiert werden können.

XMP Requirements können bereits bei der Template-Erstellung im Erstellungsfenster definiert werden, oder später über das Feld 'XMP Requirements' auf der Template-Oberfläche.

X

Der Metadatenblock ist in die PDF-Datei eingebettet und ermöglicht es Tools (z. B. KOSIT- oder ZUGFeRD-Validatoren), die PDF-Datei als strukturierte Hybridrechnung zu interpretieren, wobei die visuelle Darstellung mit einem maschinenlesbaren XML-Code innerhalb der PDF-Datei verknüpft ist.

WICHTIG: Die Korrektheit und Vollständigkeit des XMP-Blocks sind entscheidend für die Interoperabilität und die Einhaltung gesetzlicher Vorschriften, insbesondere in Länden (wie Deutschland), die Standardformate wie XRechnung oder ZUGFeRD vorschreiben.

Dokumentenerstellung

Zusätzlich muss im Bereich "Files" eine Vorlage zur Rechnungserstellung (Microsoft Word Dokument) hochgeladen werden Diese Vorlage dient als Blueprint für alle Rechnungen, welche mit diesem Template erstellt werden. Das Hochladen einer Vorlage ist obligatorisch, da sonst kein PDF-Dokument erstellt werden kann.

Um Daten aus Ihrer Salesforce-Organisation in das Word-Dokument einzubetten, können Mergefelder verwendet werden. Dabei ist zu beachten, dass die Verwendung von Mergefeldern in Microsoft Word und in Salesforce syntaktische Unterschiede fordert. Eine detaillierte Beschreibung zur Verwendung von Mergefeldern in beiden Formaten findest du im nächsten Teil dieser Dokumentation.

Außerdem lässt sich ein Benennungsmuster festlegen, das auf die zu erstellenden Dokumente angewendet werden soll. Ähnlich wie im Feld „Naming“ kann dieses Muster im Feld „Embedded Naming“ festgelegt werden.

3.2.5. Mergefelder

In XRSF muss zwischen Merge-Feldern, welche im Microsoft Word Dokument, und Merge-Feldern in Salesforce selbst syntaktisch unterschieden werden.

Mergefelder in Microsoft Word

In Microsoft Word müssen Merge-Felder in der folgenden Syntax modelliert werden:

{ MERGEFIELD ScopeName.FieldName \* MERGEFORMAT }

wobei ScopeName den API-Namen der jeweiligen Scope und FieldName den API-Namen des jeweiligen Felds darstellt. Der Zusatz MERGEFIELD ist außerdem verpflichtend, MERGEFORMAT ist optional und dient als Platzhalter für Formatspezifikationen (etwa bei Datum/Uhrzeit oder Groß- und Kleinschreibung). Mergefelder in Microsoft Word müssen mit dem Shortcut STRG + F9 eingefügt werden.

Um alle Einträge einer List Scope im Word-Dokument abzubilden, verlangt Microsoft Word eine zusätzliche, etwas andere Syntax:

{ MERGEFIELD TableStart:SectionName }

* Hier kann beliebiger Output definiert werden, welcher für jedes Element der List Scope abgebildet wird *

{ MERGEFIELD TableEnd:SectionName }

Hier bezeichnet "SectionName" den API-Namen der List Scope.

Im folgenden Beispiel fügen wir für jeden Eintrag unserer List Scope "Contacts" jeweils den Vor- und Nachnamen in unsere Rechnung ein:

X

Mergefelder in Salesforce

In Salesforce selbst können Mergefelder mit der folgenden Syntax modelliert werden:

{ !ScopeName.FieldName }

Wie auch bei Microsoft Word bezeichnet ScopeName hier den API-Namen der Scope und FieldName den API-Namen des Feldes.

Um eine List Scope vollständig einzubetten, wird in Salesforce folgende Syntax verlangt:

{ TableStart:sectionName }

* Hier kann beliebiger Output definiert werden, welcher für jedes Element der List Scope abgebildet wird *

{ TableEnd:sectionName }

Einen kleinen Unterschied gibt es allerdings bei Field Updates: Da für Field Updates bereits eine Scope definiert ist, in welcher Veränderungen vorgenommen werden sollen, reicht hier nur der API-Name des Feldes als Referenz auf das Feld (statt {!ScopeName.FieldName} reicht hier nun {!FieldName} ).

3.3.1. Mapping Condition

In den "Mapping Conditions" können Bedingungen definiert werden, welche erfüllt sein müssen, damit ein Mapping tatsächlich ausgeführt wird. Eine Mapping Condition kann entweder für ein Dokument oder für Daten aus Salesforce definiert werden. Um eine Mapping Condition zu erstellen, klicke 'Neu' im Bereich "Mapping Conditions".

X

Die Oberfläche, welche sich nach dem Klick öffnet, ist strukturell die gleiche Oberfläche wie bereits für die Field Updates in den Templates. Trage hier die gewünschte Bedingung ein und klicke dann auf 'Save'.

Hinweis: Es ist möglich, mehrere Mapping Conditions basierend auf demselben Objekt zu definieren. Achte dementsprechend darauf, Mapping Conditions so zu definieren, dass sie sich nicht gegenseitig ausschließen. Dies kann theoretisch dazu führen, dass ein Mapping niemals ausgeführt wird.

3.3.2. Weitere Konfigurationen

Viele Bereiche, welche in einem Mapping konfiguriert werden können, gleichen denen aus den Templates. Scopes, Data Configurations und Field Updates lassen sich ebenfalls genau so implementieren wie auch bereits in den Templates. Ein großer Unterschied zur Template-Oberfläche sind hier die Target Objects.

Target Objects

Target Objects können zusätzlich zu den Scopes angelegt werden. Diese sind speziell für die Verarbeitung eingehender Rechnungen konzipiert und dienen dazu, spezifische Aktionen auf Salesforce-Objekten durchzuführen. Um ein neues Target Object zu erstellen, klicke auf 'New' im Bereich "Target Objects".

X

Nun öffnet sich eine Oberfläche zur Erstellung eines Target Objects. Hier kannst du Namen des Target Objects, den API-Namen des gewünschten Objekts, und das zugehörige Mapping angeben. Außerdem kannst du wählen, welche Operation für dieses Objekt ausgeführt werden soll. Dafür gibt es vier Möglichkeiten:

• Insert: Hierbei werden neue Datensätze erstellt.
• Read: Die Daten werden lediglich gelesen, es werden aber keine Änderungen an Datensätzen vorgenommen.
• Update: Hierbei werden bestehende Datensätze aktualisiert.
• Upsert: Hierbei werden neue Datensätze eingefügt oder bestehende aktualisiert, falls ein passender Datensatz bereits existiert.

Hast du diese Felder ausgefüllt, klicke auf 'Save' und dein Target Object ist erstellt. Wie auch bei den Scopes kannst du die Operation, welche auf diesem Target Object ausgeführt werden soll, in den Data Configurations definieren.

3.3.3. Testen eines Mappings

Nachdem das Mapping konfiguriert wurde, bietet XRSF noch vor der Aktivierung die Option, das Mapping zu testen, ohne tatsächliche Änderungen an deiner Salesforce-Organisation vorzunehmen. Um ein Mapping zu testen, klicke auf den 'Test' Button im Mapping Record.

X

Nach dem Klick öffnet sich ein Fenster, in welchem du nun einen Record für den Test auswählen musst. Du kannst selbstverständlich nur einen Record wählen, welcher deiner Primary Scope entspricht. Gib dafür einfach den Namen des Records in das Suchfeld ein, oder lasse das Suchfeld leer, um alle verfügbaren Records zu sehen.

X

Wähle einen Record aus der Liste, klicke auf 'Choose' und wähle dann im nächsten Schritt ein File, welches du für den Test verwenden willst.

X

Wenn du nun auf 'Create' klickst, wird ein Job erstellt, um den Prozess zu simulieren und zu zeigen, was basierend auf deiner aktuellen Mapping-Konfiguration passieren würde. Wie bereits gesagt werden zu diesem Zeitpunkt noch keine Änderungen vorgenommen.

Willst du im Rahmen des Testes das Mapping tatsächlich ausführen und Änderungen in Salesforce vornehmen, klicke auf 'Apply' um einen Evaluation-Screen zu öffnen und klicke in diesem Screen auf 'Evaluate'. Dadurch wird die Mapping-Logik wie in einem Live-Szenario ausgeführt und Änderungen in Salesforce vorgenommen. Per Klick auf 'Visualize' siehst du außerdem den XML-Körper deiner erstellten Rechnung.

X

X

Wenn alles so funktioniert wie du es dir vorstellst, kannst du das Mapping nun über 'Activate' aktivieren. Ist ein Mapping aktiviert, wird es automatisch ausgeführt, wenn ein Dokument in einem Record vom Typ der Primary Scope hochgeladen wird, und alle Mapping Conditions erfüllt sind.