Anweisungsart: HTTP Befehl senden

Über die Anweisungsart "HTTP Befehl senden" senden Sie aus einer Regel heraus eine HTTP-Anfrage an eine externe oder interne URL. Die Antwort des Servers können Sie anschließend in Feldern des aktuellen Datensatzes weiterverarbeiten.

XL Gen. 24 Core & Enterprise

Konfiguration in der Software

PARAMETER - (Auswahl des Regel-Bereichs) - REGELN - Schaltfläche: NEU - Bereich: ANWEISUNGEN - Anweisungsart: HTTP BEFEHL SENDEN

Typische Einsatzgebiete sind z. B. die Anbindung externer Web-Schnittstellen: Login auf einer Partner-Website, Übergabe von Daten (z. B. Name, Anschrift) oder das Abfragen von Informationen zu einem Datensatz.

Voraussetzungen

Eingeschränkte Verfügbarkeit nach Auswertungsposition

Die Anweisungsart "HTTP Befehl senden" steht nicht bei jeder Auswertungsposition zur Verfügung.

Auswertungsposition	HTTP-Befehl senden verfügbar
Vor dem Speichern nach Neuanlage / Änderung	✓
Für das Klicken auf ein Feld innerhalb der Übersicht	✓
Nach dem Buchen / Stornieren von Vorgängen	✓
Vor dem Buchen von Vorgängen	—
Beim Buchen / Stornieren (Adressen, Artikel, Projekte)	—
Farbdarstellung	—
QuickInfo	—

Vor der Konfiguration prüfen

Prüfen Sie vor der Konfiguration, ob die gewählte Auswertungsposition die Anweisungsart "HTTP Befehl senden" unterstützt. Verwenden Sie dazu die Analyse-Funktion im Regelmodul.

Einsatzbereiche

Die Anweisungsart wird typischerweise in folgenden Zusammenhängen eingesetzt:

Klicken auf ein Feld innerhalb der Übersicht (Hyperlink-Unterstützung): Über eine Regel mit dieser Auswertungsposition lösen Sie beim Klick auf ein Feld einen HTTP-Request aus - z. B. um einen Login auf einer Partner-Website durchzuführen und dabei mehrere Parameter zu übergeben.
Bereichs-Aktionen ausführen: Als Regelanweisung innerhalb einer Bereichs-Aktion senden Sie einen HTTP-Request und speichern die Antwort z. B. in einem Selektionsfeld. Bereichs-Aktionen lassen sich zusätzlich automatisieren.
Eigene Abläufe: Über einen "Eigenen Ablauf" stellen Sie die Regelanweisung als eigene Schaltfläche bereit, mit der Anwender den HTTP-Request gezielt auslösen können - z. B. um in der Kasse eine externe Verkaufsseite aufzurufen.

Felder für den HTTP-Request

URL

Die vollständige Ziel-URL, an die die Anfrage gesendet wird (inkl. Protokoll, z. B. https://api.beispiel.de/webhook). Pflichtfeld. Die URL kann über den Formeleditor dynamisch aus Feldwerten des aktuellen Datensatzes zusammengesetzt werden, z. B. um einen Datensatz-Schlüssel oder eine Kundennummer an den Endpunkt zu übergeben.

Unterhalb des Felds URL können Sie zusätzliche HTTP-Header angeben. Die Eingabenotation:

Jedes Paar steht in einer eigenen Zeile, getrennt durch einen Doppelpunkt gefolgt von einem optionalen Leerzeichen. Beispiel:

Test: Aus
Absender: microtech

Verhalten bei fehlerhaften Angaben

Leerzeichen am Anfang und Ende des Namens werden automatisch entfernt. Enthält der Name selbst Leerzeichen oder ist der Value leer, wird die betroffene Zeile nicht mit übertragen.

Methode

Legt fest, welche Art von HTTP-Anfrage gesendet wird:

Methode	Bedeutung
Erstellen (POST)	Sendet Daten an den Server, um eine neue Ressource zu erstellen.
Abrufen/Lesen (GET)	Fordert Daten von einer bestehenden Ressource an, ohne sie zu verändern.
Aktualisieren/Ersetzen (PUT)	Überschreibt eine bestehende Ressource vollständig mit neuen Daten.
Teilweise aktualisieren (PATCH)	Ändert nur bestimmte Felder einer bestehenden Ressource.
Löschen (DELETE)	Entfernt eine bestehende Ressource vom Server.

Unterschied zwischen GET und den übrigen Methoden

Bei POST, PUT und PATCH werden die Daten nicht als Teil der URL übertragen, sondern getrennt im Anfragekörper (Body) an den Server gesendet - dadurch bleiben sie für den Anwender unsichtbar im Hintergrund und werden nicht in einer Browser-Chronik oder ähnlichen Verläufen gespeichert. Bei GET sind die übergebenen Werte dagegen Teil der URL selbst.

Format

Legt fest, in welcher Form die Nutzdaten übertragen werden:

Parameter (x-www-form-urlencoded): einfache Key=Value-Paare, ähnlich zu Query-Parametern
Body (freier Text)
Body (Text im CSV-Format)
Body (JSON-Format)
Body (XML-Format)

Über die Body-Formate lassen sich spezifische Anfragen an den jeweiligen Webservice aufbauen und dynamisch mit den Daten des aktuellen Datensatzes befüllen.

Parameter

Ein Formelfeld, über das Sie die Nutzdaten der Anfrage definieren. Die Nutzdaten werden als Name-Wert-Paare angegeben:

Name und Wert werden durch ein Gleichheitszeichen ("=") getrennt, z. B. Name=Wert
Mehrere Parameter werden über das Kaufmanns-Und ("&") verbunden

Über den Formeleditor können Sie die Werte dynamisch aus Feldern des aktuellen Datensatzes befüllen.

Kennzeichen

Folgende Kennzeichen stehen zur Anweisung zusätzlich zur Verfügung:

Im Webbrowser ausführen: Wird dieses Kennzeichen aktiviert, wird der HTTP-Request über den aktuellen Standardbrowser des Anwenders ausgeführt.
URL-Encoding für Header benutzen: Mit Aktivierung dieses Kennzeichens wird der HTTP-Request mit URL-Encoding abgesetzt. Soll kein URL-Encoding genutzt werden, lassen Sie das Kennzeichen deaktiviert.

Ist "Im Webbrowser ausführen" aktiviert, können Sie zusätzlich einen Wert von der aufgerufenen Webseite auslesen und automatisch in ein Selektionsfeld des aktuellen Datensatzes übernehmen lassen. Legen Sie dazu bei Bedarf ein eigenes Selektionsfeld an, in das der ausgelesene Wert geschrieben werden soll. Der Anwender bestätigt die Übernahme über eine eigene Schaltfläche im Browser-Fenster, alternativ kann er den Vorgang ohne Übernahme abbrechen.

Ein Wert pro Konfiguration

Pro Regelanweisung lässt sich genau ein Wert von der Webseite auslesen und in ein einzelnes, frei wählbares Selektionsfeld übernehmen. Mehrere unterschiedliche Werte (z. B. Preis, Ticket-ID und Anzahl gleichzeitig) lassen sich nicht in einem Durchgang auslesen.

Ablauf einer HTTP-Regelanweisung

Regel wird ausgewertet
│
├─ Bedingung erfüllt? ──Nein──► Anweisung wird übersprungen
│
└─ Ja
   │
   ├─ Request nach gewähltem Format/Methode zusammenstellen
   ├─ Anfrage an URL senden
   ├─ Server-Antwort empfangen
   └─ Rückantwort in Datenfelder zurückschreiben (optional)
      │
      └─ Steuerfelder prüfen → ggf. weitere Anweisungen/Regeln abbrechen

Rückantwort in Datenfelder zurückschreiben ("Zuweisungen zum Aktualisieren")

Über die Formel-Bedingung legen Sie fest, ob die nachfolgenden Zuweisungen ausgeführt werden. Wurde keine Bedingung angegeben, wird die Zuweisung immer ausgeführt. Trifft die Bedingung zu, kann ein Feld über eine Feldzuweisung gelöscht oder mit einem Vorgabewert gefüllt werden. In der Tabelle "Zuweisungen zum Aktualisieren" legen Sie pro Zeile fest:

Spalte	Bedeutung
Feld	Das Zielfeld des aktuellen Datensatzes, das befüllt werden soll
Art der Feldzuweisung	Wie das Feld befüllt wird (z. B. mit einem Vorgabewert)
Vorgabewert	Der Wert bzw. die Formel, mit der das Feld gefüllt wird

Das befüllte Zielfeld steht nachfolgenden Regelanweisungen derselben Regel sofort zur Verfügung - z. B. als Bedingung für eine weitere Anweisung innerhalb derselben Regel.

Für die Rückantwort stehen folgende Felder zur Verfügung:

Feld	Bezeichner
Status Code	`[StsCode]`
Status Text	`[StsText]`
Response Text	`[RespText]`
Response Headers	`[RespHeaders]`

Um einen einzelnen Wert aus den Response Headers auszulesen, nutzen Sie die Funktion $DSInfo, z. B.:

$DSInfo(«RespHeaders»,Vary,Text,: )

"Vary" ist dabei der Name im Header, "Text" das Format, der Doppelpunkt das Trennzeichen.

Header komplett speichern

Nehmen Sie ein Info-Feld, um den gesamten Header zu speichern - einzelne Werte lassen sich daraus später mit $DSInfo auslesen.

Selektionsfelder als Rückantwort-Ziel

Selektionsfelder (frei belegbare Zusatzfelder) eignen sich besonders gut als Zielfeld für die Rückantwort, da sie keine Auswirkung auf den regulären Buchungsablauf haben und flexibel weitergenutzt werden können - z. B. als Bedingung in einer nachfolgenden Regel.

Beachten Sie

Zeichenlänge beachten: Überschreitet die Rückantwort die maximale Feldlänge des gewählten Zielfeldes, wird der Text abgeschnitten. Achten Sie auf ein Feld mit ausreichender Länge oder begrenzen Sie die Rückantwort bereits auf der Server-Seite.

Steuerfelder der Anweisung

Diese Felder stehen anweisungsübergreifend zur Verfügung und steuern den weiteren Ablauf der Regel:

Keine weiteren Regelanweisungen auswerten: Nach Ausführung dieser Anweisung werden keine weiteren Anweisungen der aktuellen Regel mehr ausgeführt.
Keine weiteren Regeln auswerten: Nach Ausführung dieser Anweisung werden alle nachfolgenden Regeln derselben Auswertungsposition nicht mehr geprüft.
Nur ausführen, wenn zuvor keine Regelanweisung ausgeführt wurde: Diese Anweisung wird nur dann ausgeführt, wenn innerhalb der aktuellen Regelauswertung bislang keine andere Anweisung ausgeführt wurde. Eignet sich als Fallback-Anweisung, die nur greift, wenn keine spezifischere Anweisung zuvor aktiv war.

Wie die beiden erstgenannten Kennzeichen im Detail wirken - einschließlich der Vorsicht bei "Keine weiteren Regeln auswerten" - lesen Sie unter → Regel anlegen

Typische Anwendungsfälle

Szenario	Konfiguration
Webhook auslösen (z. B. bei Neuanlage eines Vorgangs)	URL = Webhook-Endpunkt; Parameter = Vorgangsnummer, Adressnummer; keine Rückantwort-Zuweisung
Externe Prüfung mit Rückantwort (z. B. Bonitätsabfrage)	URL = API-Endpunkt; Parameter = Kundennummer; Zuweisung = Selektionsfeld "Bonitätsergebnis"
Benachrichtigung an Drittsystem bei Buchung	Auswertungsposition: Nach dem Buchen; URL = Notification-Service
Statuswert aus externer Quelle holen und speichern	Parameter = Schlüsselfelder; Zuweisung = Statusfeld; nachfolgende Bedingungsregel wertet Statusfeld aus
Wert von externer Verkaufsseite übernehmen (Kasse)	Auswertungsposition: Eigene Abläufe; Kennzeichen "Im Webbrowser ausführen" aktiv; ausgelesener Wert wird in ein Selektionsfeld der markierten Position übernommen

Protokollierung

Um HTTP-Anfragen zu protokollieren, aktivieren Sie in den PARAMETERN unter SONSTIGE - PARAMETER FÜR DAS EREIGNIS-PROTOKOLL das Kennzeichen "HTTP Anfragen protokollieren".