Apps & connections
Payloads parsen und Variablen verwenden
ONE LOOP: Datenübergaben und Variablen in Lexware-Office-Workflows prüfen. Die allgemeine Verfügbarkeit ist noch nicht bestätigt.
Teststatus
Stand 7. November 2026: Lexware Office Connector 9.2.0 ist privat live; vier Dokument-Actions und beide Trigger wurden im freigegebenen ONE LOOP Teststand geprüft. Der Zahlungstrigger 1.5 ist veröffentlicht. Version 9.3.0 befindet sich in öffentlicher Prüfung; eine allgemeine öffentliche Freigabe oder ein kostenpflichtiger Neukundenabschluss ist noch nicht bestätigt.
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 |
| In eine If/Else-Bedingung nach Rechnungszahlung empfangen | Der Abschlussweg läuft nur bei |
Die aktuelle Zahlung in einer Nachricht nennen |
| In den Nachrichtentext | Der Betrag erscheint lesbar mit Währung. |
Mit einem Betrag rechnen |
| In ein Zahlenfeld oder eine Berechnung | Der Workflow verarbeitet eine Zahl ohne Währungssymbol. |
Einen Vorgang in Lexware Office prüfen |
| In eine interne Aufgabe oder Notiz | Der Empfänger öffnet den passenden Vorgang direkt. |
Den PDF-Link weitergeben |
| 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 |
| 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 |
| In Text, E-Mail oder interne Notiz | Menschen sehen die richtige Belegnummer. |
Einen technischen Folgeprozess verknüpfen |
| In ein ID-Feld einer passenden Folgeaction | Der Workflow referenziert den eindeutigen Vorgang statt nur dessen sichtbarer Nummer. |
Nach einem Fehler sauber reagieren |
| In eine If/Else-Bedingung und eine interne Fehlermeldung | Erfolgs- und Fehlerweg bleiben getrennt und nachvollziehbar. |
Eine doppelte Folgeaktion vermeiden |
| 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. |
|
Mapping | Du setzt eine Variable in ein Eingabefeld des nächsten Schritts ein. |
|
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 |
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:
{
"data": {
"sourceMode": "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 |
|---|---|---|
| Deine fachlichen Eingaben aus den sichtbaren Action-Feldern. | Hierhin mappt die Oberfläche deine Eingaben automatisch. |
| Technische Zuordnung zum Standort, Kontakt und Workflow-Lauf. | Nicht selbst eintragen oder verändern. |
| 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 |
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 |
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 |
|
| Nummer in Nachricht, ID für Verknüpfungen. |
Angebot |
|
| Für eine Auftragsbestätigung immer |
Auftragsbestätigung |
|
| Nummer in einer Notiz, ID für technische Folgeprozesse. |
Gutschrift |
|
| Nummer für Kommunikation, ID für Abgleiche. |
Kontakt |
|
| 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 |
|---|---|---|
| partial oder final. any ist die Filterauswahl für beide Ereignisstufen. | Den Trigger auf |
|
| Als If/Else-Bedingung vor Abschlussaktionen verwenden. |
| Noch offener Betrag. | Für Teilzahlungs- oder Follow-up-Logik. |
| Betrag genau dieses Zahlungseingangs. | Für Berechnungen. |
| Derselbe Betrag als lesbarer Text. | Für eine Nachricht oder interne Notiz. |
| 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 |
|---|---|---|
| Neuer Angebotsstatus. | Den Workflow nach Annahme und Ablehnung getrennt behandeln. |
| Eindeutige Lexware-ID des Angebots. | An Auftragsbestätigung erstellen weitergeben. |
| Sichtbare Angebotsnummer. | In interne Nachrichten einsetzen. |
| Datei-Link, sofern verfügbar. | Vor Nutzung auf einen leeren Wert prüfen. |
| 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 |
|---|---|---|
|
| Erst nach |
| Ergebnisstatus des Schritts. | Für Protokolle und ergänzende Prüfungen. |
| Technische oder fachliche Fehlerkennung bei einem fehlgeschlagenen Lauf. | In einer internen Fehlermeldung speichern. |
| Verständliche Fehlerbeschreibung, sofern geliefert. | Zur Analyse in eine interne Aufgabe oder Notiz übernehmen. |
| Zeigt, ob eine Wiederholung fachlich möglich sein kann. | Ursache prüfen und nur dann bewusst wiederholen. |
| Zusätzliche Hinweise ohne zwingenden Fehler. | Im Workflow-Verlauf kontrollieren. |
| Zugeordnete Kontakt-ID in Lexware Office. | Für Abgleiche oder Folgeprozesse. |
| Wie ein bestehender Kontakt zugeordnet wurde, sofern angegeben. | Zur Prüfung einer unerwarteten Zuordnung. |
| Ob ein Kontakt angelegt oder aktualisiert wurde. | Für interne Protokolle. |
| Direkter Link zum Vorgang in Lexware Office. | In eine interne Prüfung oder Aufgabe einfügen. |
| Dateiname und Dateityp des offiziellen Dokuments. | Für Dokumentationsschritte. |
| 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:
Prüfe
success.Bei Erfolg: verwende
invoiceNumberin Texten undinvoiceFileUrlfür einen Dokumentlink.Bei Fehler: protokolliere
errorCode,errorMessageundretryable.Prüfe bei Bedarf
lexwareViewUrldirekt 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:
Enthält der Schritt bereits einzelne Variablen? Dann direkt mappen.
Enthält er nur einen JSON-Text? Zerlege ihn zuerst mit der im Workflow verfügbaren Parsing- oder Formatierungsfunktion in einzelne Werte.
Prüfe Datentyp und Format jedes Werts: Zahl, Datum, Text, Boolean oder ID.
Mappe erst danach den einzelnen Wert in das Lexware-Feld.
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
Vor Folgeaktionen immer Erfolg prüfen. Verwende
success, bevor du eine Dokumentnummer weitergibst oder einen Abschlussprozess startest.IDs und Nummern nicht verwechseln. Für Übergaben zwischen Actions benötigst du die ID, etwa
quotationId; für Texte meist die Nummer, etwaquotationNumber.Doppelte Ereignisse einplanen. Trigger werden mindestens einmal zugestellt. Sichere wichtige Folgeaktionen mit
eventIdoder einer eigenen Prüfung.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 mindestenserrorMessage.☐ 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
Zahlungs- und Angebotskontext unterscheiden
Vor der Zustellung ordnet der aktuelle Zahlungstrigger die Rechnung einem ONE-LOOP-Kontakt im richtigen Standort zu: über die bestehende sichere Zuordnung oder genau einen Treffer mit derselben E-Mail-Adresse. Er legt dabei keinen Kontakt an. Fehlt eine eindeutige Zuordnung, stoppt die Verarbeitung mit invoice_payment_contact_unresolved; wähle keinen beliebigen Kontakt als Ersatz.
Prüfe nach Neuinstallation jede Triggerinstanz, Bedingung und Variable erneut. Eine erfolgreiche Zahlungsnachricht darf keine Variablen aus einem Angebots-Action-Schritt verwenden. Bei unklarer Teilwirkung denselben Vorgang abgleichen und keine neue Geschäftsreferenz zum Umgehen der Wiederholungssperre setzen.
Filterauswahl ist kein Zahlungsstatus
Ab Zahlungstrigger 1.5 bezeichnet paymentStageFilter die gewählte Auswahl any, partial oder final. paymentStage enthält dagegen ausschließlich die tatsächliche Teil- oder Schlusszahlung. Prüfe für einen abgeschlossenen Vorgang paymentStage=final und isFullyPaid=true. Der Trigger bindet vor Zustellung den passenden ONE-LOOP-Kontakt; eine fehlende oder mehrdeutige Zuordnung wird nicht durch einen beliebigen Kontakt ersetzt.