> For the complete documentation index, see [llms.txt](https://one-loop.gitbook.io/help/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://one-loop.gitbook.io/help/marketplace-apps/lexware-office/payloads-parsen-und-variablen-verwenden.md). # Payloads parsen und Variablen verwenden ## Teststatus Die technische Umsetzung der beschriebenen Datenübergaben liegt vor. Die allgemeine Verfügbarkeit für alle Standorte ist noch nicht bestätigt. Richte Abläufe deshalb zunächst mit kontrollierten Testvorgängen ein und prüfe jeden Lauf im Workflow-Verlauf sowie in Lexware Office. ## Schnellwahl: Welche Variable verwende ich wofür? Nutze diese Tabelle, bevor du in die Detailseiten gehst. Sie beantwortet direkt: **Welchen Wert nehme ich? Wohin setze ich ihn? Was passiert dann?** | Dein Ziel | Nimm diese Variable | Setze sie hier ein | Ergebnis | | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | Nur nach vollständiger Zahlung fortfahren | `isFullyPaid` oder der Triggerfilter `final` | In eine If/Else-Bedingung nach **Rechnungszahlung empfangen** | Der Abschlussweg läuft nur bei `true`. | | Die aktuelle Zahlung in einer Nachricht nennen | `paymentAmountFormatted` | In den Nachrichtentext | Der Betrag erscheint lesbar mit Währung. | | Mit einem Betrag rechnen | `paymentAmount`, `totalAmount`, `grossAmount` oder `refundAmount` | In ein Zahlenfeld oder eine Berechnung | Der Workflow verarbeitet eine Zahl ohne Währungssymbol. | | Einen Vorgang in Lexware Office prüfen | `invoiceUrl` oder `lexwareViewUrl` | In eine interne Aufgabe oder Notiz | Der Empfänger öffnet den passenden Vorgang direkt. | | Den PDF-Link weitergeben | `invoiceFileUrl`, `quotationFileUrl`, `orderConfirmationFileUrl` oder `creditNoteFileUrl` | In einen Link- oder Dokumentenschritt | Der offizielle Beleg kann geöffnet werden, sofern die Variable gefüllt ist. | | Aus einem angenommenen Angebot eine Auftragsbestätigung erstellen | `quotationId` | In das Feld **Quotation** der Action **Auftragsbestätigung erstellen** | Die Bestätigung wird aus genau diesem Angebot weitergeführt. | | Eine Nummer in einem Text zeigen | `invoiceNumber`, `quotationNumber`, `orderConfirmationNumber` oder `creditNoteNumber` | In Text, E-Mail oder interne Notiz | Menschen sehen die richtige Belegnummer. | | Einen technischen Folgeprozess verknüpfen | `invoiceId`, `quotationId`, `orderConfirmationId` oder `creditNoteId` | In ein ID-Feld einer passenden Folgeaction | Der Workflow referenziert den eindeutigen Vorgang statt nur dessen sichtbarer Nummer. | | Nach einem Fehler sauber reagieren | `success`, `errorCode`, `errorMessage`, `retryable` | In eine If/Else-Bedingung und eine interne Fehlermeldung | Erfolgs- und Fehlerweg bleiben getrennt und nachvollziehbar. | | Eine doppelte Folgeaktion vermeiden | `eventId` | In einer eigenen Duplikat-Prüfung speichern und vergleichen | Dasselbe Trigger-Ereignis löst nicht zweimal denselben Folgeprozess aus. | **Merkregel:** Für Texte nimmst du eine sichtbare Nummer oder einen `...Formatted`-Wert. Für Übergaben zwischen Actions nimmst du die passende `...Id`. Für Berechnungen nimmst du einen reinen Zahlenwert. ## Worum geht es auf dieser Seite? Diese Seite erklärt die Datenübergabe der Lexware-Office-Integration von Anfang bis Ende: * welche Daten ein Auslöser in einen Workflow gibt, * welche Felder du bei einer Action befüllst, * welche Werte nach einer Action zurückkommen, * wann du einen Payload wirklich parsen musst – und wann nicht, * wie du Daten sicher in Bedingungen, Texten und Folgeaktionen verwendest. Die Detailseiten enthalten anschließend jede einzelne Action und jeden Trigger mit allen Feldern und allen Rückgabevariablen. ## Die Begriffe einfach erklärt | Begriff | Einfache Bedeutung | Beispiel | | ------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | **Payload** | Das gesamte Datenpaket eines Auslösers oder einer Action. | Alle Daten zu einer Rechnungszahlung zusammen. | | **Variable** | Ein einzelner Wert aus diesem Paket. | `invoiceNumber` oder `paymentAmount`. | | **Mapping** | Du setzt eine Variable in ein Eingabefeld des nächsten Schritts ein. | `quotationId` wird in das Feld **Quotation** gemappt. | | **Parsen** | Ein umfangreicher Rohtext wird in einzelne verwendbare Werte zerlegt. | Aus einem JSON-Text wird ein eigener Wert für Rechnungsnummer, Betrag und Datum. | | **Bedingung** | Der Workflow entscheidet anhand eines Werts, welchen Weg er geht. | Nur fortfahren, wenn `isFullyPaid = true`. | ## Der Datenfluss im Workflow ``` Lexware-Ereignis oder vorheriger Workflow-Schritt ↓ Payload mit einzelnen Variablen ↓ Mapping in eine Lexware-Action ↓ Aktion erstellt oder liest einen Vorgang ↓ Ergebnis-Payload der Action ↓ Bedingungen, Nachrichten, Aufgaben oder Folgeaktion ``` Die Lexware-Trigger und -Actions liefern die Werte bereits als einzelne Workflow-Variablen. In diesen Fällen musst du keinen JSON-Text selbst parsen: Du wählst im Variablen-Auswahlfeld einfach den benötigten Wert. ## Technischer Aufbau: Was du sehen musst – und was nicht Bei einer Lexware-Action füllst du in der Oberfläche nur die sichtbaren Felder aus. Die Integration baut daraus intern ein technisches Paket auf: ```json { "data": { "source": "manual", "title": "Beratung August", "item1Name": "Beratung", "item1Quantity": 2, "item1UnitPrice": 120, "item1TaxRate": 19 }, "extras": { "locationId": "…", "contactId": "…", "executionId": "…", "workflowId": "…" }, "meta": { "key": "one_loop_lexware_create_invoice" } } ``` | Bereich | Bedeutung | Was du damit machst | | ---------- | ------------------------------------------------------------- | -------------------------------------------------------- | | `data` | Deine fachlichen Eingaben aus den sichtbaren Action-Feldern. | Hierhin mappt die Oberfläche deine Eingaben automatisch. | | `extras` | Technische Zuordnung zum Standort, Kontakt und Workflow-Lauf. | Nicht selbst eintragen oder verändern. | | `meta.key` | Kennung der auszuführenden Lexware-Action. | Nicht selbst eintragen oder verändern. | > Du musst diesen Umschlag nicht als JSON in ein Feld kopieren. Nutze für die sichtbaren Eingaben immer das normale manuelle Mapping der Action. Das gezeigte Objekt dient nur zum Verständnis, wenn du einen Workflow-Lauf technisch prüfst. ## Welche Feldtypen sicher mappen? | Feldart | So mapst du sie | Worauf achten? | | --------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Text | Textvariable direkt in ein Textfeld setzen. | Leere Werte vorher abfangen, wenn der Text fachlich notwendig ist. | | Zahl | Zahlvariable in ein Zahlenfeld setzen. | Keine Währungssymbole in Betragsfelder mappen. | | Datum | Ein Datum im erwarteten Format setzen. | Für Angebote ist das Ablaufdatum exakt `YYYY-MM-DD`. | | Auswahl | Einen der angebotenen Werte wählen oder dynamisch liefern. | Schreibweise muss zum erlaubten Wert passen. | | Wahr/Falsch | Boolean-Wert in einer Bedingung prüfen. | Nicht auf den Text `true` oder `false` prüfen, wenn die Bedingung einen Boolean erwartet. | | ID | Die Kennung eines vorherigen Vorgangs mappen. | IDs nicht mit sichtbaren Nummern verwechseln. | | Link oder Datei | Die zurückgegebene URL verwenden. | Der Wert kann fehlen; vorher prüfen. | ## Sichtbare Nummer und technische ID sind nicht dasselbe Die sichtbare Nummer ist für Menschen. Die ID wird für eine eindeutige Weiterverarbeitung benötigt. | Fachlicher Vorgang | Sichtbarer Wert | Technischer Wert | Typische Verwendung | | ------------------- | ------------------------- | --------------------- | -------------------------------------------------------- | | Rechnung | `invoiceNumber` | `invoiceId` | Nummer in Nachricht, ID für Verknüpfungen. | | Angebot | `quotationNumber` | `quotationId` | Für eine Auftragsbestätigung immer `quotationId` mappen. | | Auftragsbestätigung | `orderConfirmationNumber` | `orderConfirmationId` | Nummer in einer Notiz, ID für technische Folgeprozesse. | | Gutschrift | `creditNoteNumber` | `creditNoteId` | Nummer für Kommunikation, ID für Abgleiche. | | Kontakt | `contactName` | `lexwareContactId` | Name für Texte, ID für Verknüpfungen. | ## Auslöser richtig verwenden ### Rechnungszahlung empfangen Der Trigger liefert Rechnung, Kontakt, Beträge und Zahlungsstand. Für die Steuerung eines Prozesses sind diese Werte besonders wichtig: | Variable | Bedeutung | Sichere Verwendung | | ------------------------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `paymentStage` | `any`, `partial` oder `final`. | Den Trigger auf `final` filtern, wenn der Ablauf erst nach vollständigem Ausgleich starten soll. | | `isFullyPaid` | `true` bei vollständig ausgeglichener Rechnung. | Als If/Else-Bedingung vor Abschlussaktionen verwenden. | | `remainingAmount` | Noch offener Betrag. | Für Teilzahlungs- oder Follow-up-Logik. | | `paymentAmount` | Betrag genau dieses Zahlungseingangs. | Für Berechnungen. | | `paymentAmountFormatted` | Derselbe Betrag als lesbarer Text. | Für eine Nachricht oder interne Notiz. | | `eventId` | Eindeutige Kennung des Zahlungsereignisses. | Gegen doppelte Folgeaktionen absichern. | Beispiel: Ein Workflow startet nur bei `final`. Danach prüft eine Bedingung `isFullyPaid`. Nur im Ja-Zweig wird eine interne Bestätigung angelegt. In diese Bestätigung werden `invoiceNumber`, `totalAmountFormatted` und `invoiceUrl` gemappt. Zur vollständigen Feldliste: Rechnungszahlung empfangen. ### Angebotsstatus geändert Dieser Trigger startet bei `accepted` oder `rejected`. | Variable | Bedeutung | Sichere Verwendung | | ------------------ | -------------------------------------- | ----------------------------------------------------------- | | `quotationStatus` | Neuer Angebotsstatus. | Den Workflow nach Annahme und Ablehnung getrennt behandeln. | | `quotationId` | Eindeutige Lexware-ID des Angebots. | An **Auftragsbestätigung erstellen** weitergeben. | | `quotationNumber` | Sichtbare Angebotsnummer. | In interne Nachrichten einsetzen. | | `quotationFileUrl` | Datei-Link, sofern verfügbar. | Vor Nutzung auf einen leeren Wert prüfen. | | `eventId` | Eindeutige Kennung der Statusänderung. | Gegen doppelte Folgeaktionen absichern. | Beispiel: Ein Workflow mit Filter `accepted` mappt `quotationId` in die folgende Action **Auftragsbestätigung erstellen**. Die Angebotsnummer und der Link werden in einer internen Aufgabe dokumentiert. Zur vollständigen Feldliste: Angebotsstatus geändert. ## Ergebnisse einer Action weiterverwenden Jede Action liefert einen Ergebnis-Payload zurück. Diese Variablen sind der sichere Übergabepunkt für deinen nächsten Workflow-Schritt. ### Gemeinsame Ergebniswerte | Variable | Bedeutung | So verwenden | | ------------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------- | | `success` | `true`, wenn der Schritt erfolgreich abgeschlossen wurde. | Erst nach `success = true` mit der Folgeaktion fortfahren. | | `status` | Ergebnisstatus des Schritts. | Für Protokolle und ergänzende Prüfungen. | | `errorCode` | Technische oder fachliche Fehlerkennung bei einem fehlgeschlagenen Lauf. | In einer internen Fehlermeldung speichern. | | `errorMessage` | Verständliche Fehlerbeschreibung, sofern geliefert. | Zur Analyse in eine interne Aufgabe oder Notiz übernehmen. | | `retryable` | Zeigt, ob eine Wiederholung fachlich möglich sein kann. | Ursache prüfen und nur dann bewusst wiederholen. | | `warnings` | Zusätzliche Hinweise ohne zwingenden Fehler. | Im Workflow-Verlauf kontrollieren. | | `lexwareContactId` | Zugeordnete Kontakt-ID in Lexware Office. | Für Abgleiche oder Folgeprozesse. | | `customerMatchMethod` | Wie ein bestehender Kontakt zugeordnet wurde, sofern angegeben. | Zur Prüfung einer unerwarteten Zuordnung. | | `customerCreated` / `customerUpdated` | Ob ein Kontakt angelegt oder aktualisiert wurde. | Für interne Protokolle. | | `lexwareViewUrl` | Direkter Link zum Vorgang in Lexware Office. | In eine interne Prüfung oder Aufgabe einfügen. | | `officialDocumentFileName` / `officialDocumentMimeType` | Dateiname und Dateityp des offiziellen Dokuments. | Für Dokumentationsschritte. | | `contactDocumentStatus` | Status der Dokumentablage am Kontakt. | Bei einem fehlenden Dokument prüfen. | > Nicht jede Action liefert exakt jede gemeinsame Variable in derselben fachlichen Ausprägung. Die vollständige Liste pro Action findest du auf den verlinkten Detailseiten. ### Rechnung erstellen Nach einem erfolgreichen Lauf stehen unter anderem `invoiceId`, `invoiceNumber`, `invoiceStatus`, `invoiceDocumentId`, `invoiceFileUrl`, `invoiceFileName` und `invoiceMimeType` bereit. Robuster Ablauf: 1. Prüfe `success`. 2. Bei Erfolg: verwende `invoiceNumber` in Texten und `invoiceFileUrl` für einen Dokumentlink. 3. Bei Fehler: protokolliere `errorCode`, `errorMessage` und `retryable`. 4. Prüfe bei Bedarf `lexwareViewUrl` direkt in Lexware Office. Vollständige Action-Dokumentation: Rechnung erstellen. ### Angebot erstellen Nach Erfolg stehen unter anderem `quotationId`, `quotationNumber`, `quotationStatus`, `expirationDate`, `quotationDocumentId`, `quotationFileUrl`, `quotationFileName` und `quotationMimeType` bereit. Wichtig: `quotationId` ist der passende Wert für die spätere Auftragsbestätigung. `quotationNumber` dient dagegen für Menschen lesbare Texte. Vollständige Action-Dokumentation: Angebot erstellen. ### Auftragsbestätigung erstellen Die Action erwartet ein bereits angenommenes Angebot und nutzt dessen `quotationId`. Nach Erfolg liefert sie unter anderem `orderConfirmationId`, `orderConfirmationNumber`, `orderConfirmationStatus`, `orderConfirmationDocumentId`, `orderConfirmationFileUrl`, `orderConfirmationFileName` und `orderConfirmationMimeType`. Der Vorgang ist an die Angebots-ID gebunden. Starte denselben Übergabeschritt nicht blind mehrfach. Vollständige Action-Dokumentation: Auftragsbestätigung erstellen. ### Gutschrift erstellen Die Action verwendet Daten einer erfolgreichen Rückerstattung. Nach Erfolg liefert sie unter anderem `creditNoteId`, `creditNoteNumber`, `creditNoteStatus`, `creditNoteDocumentId`, `creditNoteFileUrl`, `creditNoteFileName` und `creditNoteMimeType`. Für die Eingabe sind die Rückerstattungswerte entscheidend: `transactionId`, `refundId`, `refundAmount`, `currencyCode`, `refundStatus` und `refundType`. Bei einer teilweise erstatteten Rechnung mit gemischten Steuersätzen wird keine Gutschrift erstellt. Vollständige Action-Dokumentation: Gutschrift erstellen. ## Wann musst du wirklich parsen? Bei den nativen Lexware-Auslösern und -Actions nicht: Die einzelnen Werte sind bereits als Variablen verfügbar. Parsen ist erst nötig, wenn ein vorheriger Workflow-Schritt einen kompletten JSON-Text oder einen unstrukturierten Text liefert. Prüfe dann diese Reihenfolge: 1. Enthält der Schritt bereits einzelne Variablen? Dann direkt mappen. 2. Enthält er nur einen JSON-Text? Zerlege ihn zuerst mit der im Workflow verfügbaren Parsing- oder Formatierungsfunktion in einzelne Werte. 3. Prüfe Datentyp und Format jedes Werts: Zahl, Datum, Text, Boolean oder ID. 4. Mappe erst danach den einzelnen Wert in das Lexware-Feld. 5. Führe einen Testlauf durch und vergleiche den Workflow-Verlauf mit Lexware Office. Ein JSON-Text darf nicht ungeprüft in ein Zahlen-, Datums- oder ID-Feld gemappt werden. Zum Beispiel ist `"refundAmount": "119,00 €"` kein passender Zahlenwert für eine Rückerstattung; benötigt wird der Betrag als Zahl, etwa `119` oder `119.00`. ## Die vier wichtigsten Schutzregeln 1. **Vor Folgeaktionen immer Erfolg prüfen.** Verwende `success`, bevor du eine Dokumentnummer weitergibst oder einen Abschlussprozess startest. 2. **IDs und Nummern nicht verwechseln.** Für Übergaben zwischen Actions benötigst du die ID, etwa `quotationId`; für Texte meist die Nummer, etwa `quotationNumber`. 3. **Doppelte Ereignisse einplanen.** Trigger werden mindestens einmal zugestellt. Sichere wichtige Folgeaktionen mit `eventId` oder einer eigenen Prüfung. 4. **Leere optionale Werte abfangen.** Datei-Links, Kontakt-E-Mail, Kundennummer und einzelne Datumswerte können fehlen. Baue vor einer Nutzung eine Bedingung ein. ## Kompakte Prüfliste vor der Veröffentlichung eines Workflows * [ ] Auslöser und Filter passen zum gewünschten fachlichen Zeitpunkt. * [ ] Jede Pflichtangabe der Action ist gemappt. * [ ] Zahlenfelder erhalten Zahlen ohne Währungssymbol. * [ ] Datumsfelder haben das erwartete Format. * [ ] Für eine Folge-Action wird die technische ID statt der sichtbaren Nummer verwendet. * [ ] Der Erfolgsweg prüft `success`; der Fehlerweg dokumentiert mindestens `errorMessage`. * [ ] Datei-Links und optionale Werte werden auf Leerwerte geprüft. * [ ] Ein Testlauf wurde im Workflow-Verlauf und in Lexware Office verglichen. ## Weiterführende Details * Übersicht Lexware Office * [Alle Workflow-Actions](/help/marketplace-apps/lexware-office/workflow-actions.md) * [Alle Workflow-Trigger](/help/marketplace-apps/lexware-office/workflow-trigger.md)