Start

Collection Runner für die Logistik Blockchain

Collection Runner für die Logistik Blockchain

Mit der Integration von APIs gehen Integrationstests in Tools wie Postman oder SoapUI einher. Entwickler prüfen so schrittweise die API-Funktionsweise und stellen sicher, dass der Datenaustausch zwischen den Systemen inhaltlich und technisch korrekt erfolgt. Fehlerzustände können in Isolation provoziert und vor Nutzung der API abgefangen werden, ohne dass ein massenhafter Datenfluss den Blick auf kritische Stellen vernebelt. Da in modernen Unternehmensumgebungen meist mehrere Systeme am Datenaustausch beteiligt sind, müssen regelmäßig auch mehrere inhaltlich zusammenhängende Abfragen durchgeführt werden. Fehlerfreiheit lässt sich dann nur im Resultat eines End-to-End Datenflusses beurteilen. Die Automatisierung dieses mehrstufigen Request-Response-Zyklus soll mithilfe von Postman Collection Runner beispielhaft anhand der Logistikplattform TradeLens beschrieben werden.

 

TradeLens wurde vom weltweit größten Reeder Maersk ins Leben gerufen und basiert auf der Blockchain-Technologie von IBM. Kernaufgabe ist die sichere und vertrauenswürdige Protokollierung aller logistischen Ereignisse zwischen Urversender und Endemfänger im Rahmen der globalen Transportkette. So können alle Teilnehmer dieser Blockchain zuverlässig und fälschungssicher Daten in ihrem eigenen Supply-Chain-Management nutzen, um ihrerseits einen effizienten Warenfluss zu gewährleisten. Tracking und Tracing wird zum Kinderspiel. Eine einfache, skalierbare und sichere Implementierung mittels Workato haben wir bereits in einem anderen Artikel ausführlich beschrieben (siehe Kommentar). An dieser Stelle wollen wir den ebenso wichtigen, vorangehende Schritt der Testautomatisierung vor Inbetriebnahme vertiefen. Er stellt sicher, dass wir die API und deren Nutzung verstanden haben und die Automatisierung in Produktion erfolgreich sein kann.

 

 

 

Quelle:

Zur API Entwicklung gehört immer eine aussagekräftige Dokumentation, die zumeist aus einer Blog-artigen Implementierungsanleitung sowie einer technischen Beschreibung besteht; letztere wird regelmäßig mit dem Tool Swagger (heute OpenAPI) erstellt. Bei TradeLens ist beides geradezu hervorragend geschehen: Ausführlich, umfassend, verständlich, technisch ausgereizt. Die Implementierung der Einzelschritte in Postman wird dem API-Integrator gleich an die Hand gegeben, sodass wir hier keine weiteren Worte darüber verlieren müssen. Wir wollen gleich auf die Automatisierung mithilfe von sogenannten Collection Runner eingehen.

Ein Collection Runner ist eine Folge von Einzelabfragen, die dank Pre-request-Script und Test-Script zu einer Kette zusammengefügt werden. Eine Abfrage kann das Ergebnis einer vorhergehenden Abfrage nutzen und weiterverarbeiten, um es mit einem Erwartungswert zu vergleichen. Entspricht der tatsächliche Wert dem Erwartungswert, wird ein grünes Symbol angezeigt, andernfalls ein rotes. Die Abfragen sind zumeist REST-Abfragen, die ausgetauschten Inhalte zumeist JSON-Daten. So ist es auch bei TradeLens. Im konkreten Beispiel haben wir uns ein TradeLens Event herausgesucht, bei dem ein Schienentransporteur die Verladung eines Containers an die Blockchain meldet. Dafür sind drei Einzelschritte nötig: (1) Autorisierung in der IBM Cloud, (2) Autorisierung in TradeLens und (3) Übermittlung der Eventinhalte an TradeLens.

 

Quelle:

 

Im ersten Schritt liefert die IBM Cloud im Austausch für einen gültigen API-Key, der während des Onboarding auf TradeLens erstellt wurde, einen Access und Refresh Token. Mit diesem Access und Refresh Token fordert man beim TradeLens Solution Manager einen Exchange Token an, mit dem letztlich das konkrete Event an die TradeLens Plattform gemeldet wird. Die zweistufige Token-Erstellung ermöglicht, dass der Event-Publisher, in unserem Fall das Schienentransportunternehmen, die Berechtigung für die Nutzung der TradeLens API in seinem Namen selbst in der IBM Cloud Benutzerverwaltung vergeben kann (Identity and Access Management, kurz IAM). Ist der Access und Refresh Token gültig, dann gewährt TradeLens einen Exchange Token für das Absetzen der Events (auch Bearer Token oder Onboarding Token genannt). Diese Trennung der Authentisierungsverantwortung von der Serviceverantwortung folgt dem modernen OAuth 2.0 Standard, welcher einen fortwährenden Austausch und redundaten Haltung von Passwörtern zwischen Diensten vermeiden möchte. Damit TradeLens die IBM Cloud Benutzerverwaltung als Authorisierungsinstanz akzeptiert, wurde während des Onboarding die IBM Cloud Benutzerverwaltung TradeLens bekannt gemacht, sodass TradeLens die Gültigkeit des Access und Refresh Token beurteilen kann. Interessierte finden in folgendem Video eine verständliche Einführung in die Funktionsweise von OAuth 2.0 und weitereführende Authentifizierungsmechanismen.

 

YouTube

Mit dem Laden des Videos akzeptieren Sie die Datenschutzerklärung von YouTube.
Mehr erfahren

Video laden

 

Hat der Client einen Exchange Token erhalten, so fügt er diesen als “Authentication”-Feld mit dem vorangestellten Wort “Bearer” in seinen Event-POST-Request ein: Der POST-Request teilt TradeLens so einen gültigen Zugangscode für das Absetzen des Events mit. Im folgenden Screenshot wird die URL, an welche der POST-Request geschickt wird, durch eine Variable abstrahiert, um sie aus einem Script heraus einfach parametrisieren zu können.

 

 

 

Soviel zum grundsätzlichen Ablauf. Jetzt zur Automatisierung und Validierung innerhalb des Postman Collection Runner.

 

Sobald der Postman Client den ersten POST-Request an das IBM Cloud IAM mit dem API Token im Message Body abgesetzt hat, soll der Access und Refresh Token des IBM Cloud IAM aus der zugehörigen Response in eine Collection Variable geschrieben werden. Diese soll im darauffolgenden Schritt, der Authentication bei TradeLens, weiterverwendet werden. Collection Variable haben einen Geltungsbereich für eine Collection, die nichts anderes ist als mehrere Requests, welche in einer Sammlung (ähnlich einem Ordner) zusammengefasst wurden. Sie können sich folglich jene Variablen teilen, d.h. auf sie zugreifen und verändern, die als Collection Variable definiert wurden. Daneben gibt es noch lokale Variable, Environment Variable und globale Variable, auf die wir später eingehen werden.

Postman bietet für Automatisierungen innerhalb von Collections die Möglichkeit, JavaScript Programme vor und nach einem Request auszuführen. Das geht ganz einfach, indem man im Reiter “Pre-request Script” oder “Test Script” ein entsprechendes JavaScript Programm verfasst. Postman stellt für die Interaktion auch zahlreiche Methoden und Eigenschaften zur Verfügung, die im pm-Objekt enthalten sind. Sehen wir uns das genauer an.

 

 

 

In Zeile 3 werden zwei lokale Variable mit dem JavaScript Keyword let definiert: Die Variable response nimmt die Antwort des dem Test-Skript unmittelbar vorausgehenden POST-Request im JSON-Format auf (pm.response.json()); damit erhält die Antwort eine Struktur, welche die Weiterverarbeitung in Postman erleichtert. Direkt danach wird die Variable accessRefreshToken definiert und ihr sofort die zuvor gespeicherte Variable response als String zugewiesen, was über die stringify-Methode erreicht wird. Warum das machen wird, werden wir gleich sehen.

Zuvor aber die Erklärung, weshalb wir zwei lokale Variable verwenden: Ihr Geltungsbereich (auch Scope genannt) reicht nur vom Anfang bis zum Ende dieses einzelnen Testablaufs (Collection Run). Folglich muss man sich auch keine Gedanken darüber machen, ob sie außerhalb dieses Testablaufs mit anderswo definierten Variablen kollidieren können; dies könnte nämlich zu Fehlern führen.

In Zeile 6 wird die zu einem String konvertierte response als Collection Variable gespeichert; sie steht folglich auch den beiden anderen POST Requests zur Verfügung. Relevant ist das nur für den unmittelbar auf Schritt 1 folgenden Request, da er auf diese Collection Variable zurückgreift, um einen Exchange Token (Bearer Token) von TradeLens zu erhalten.

Letztlich werden in Zeile 9 bis 17 noch drei Tests ausgeführt: Stellt die response eine Erfolgsmeldung dar (d.h. 200 Code gemäß HTTP-Standard), enthält sie einen Abschnitt namens “access_token” und einen namens “refresh_token“. Wenn alle drei Bedingungen erfüllt sind, war dieser erste POST-Request erfolgreich. Postman quitiert dies mit einem grünen Symbol.

2. Authentication gegenüber dem TradeLens Solution Manager

Nachdem der Access und Refresh Token in einer Collection Variable gespeichert wurde, kann auf diesen im zweiten POST-Request direkt zugegriffen werden, hier im Body des zweiten Schrittes. Dies geht in Postman über zwei geschwungene Klammern mit dem Variablennamen als Bezeichner {{AccessRefreshToken}}.

Analog zum ersten Schritt speichern wir die Response dieses zweiten POST-Requests wieder in einer Collection Variable für die weitere Verwendung. Diesmal handelt es sich um den Exchange Token, den TradeLens im JSON Dokument als “onboarding_token” bezeichnet. Er wird abermals in einer Collection Variable abgelegt. Zudem wird im Tests-Skript geprüft, ob es sich erneut um eine positive 200 HTTP-Antwort handelt und diesmal im Body der Response das Wort “onboarding_token” enthalten ist. Sind beide Kriterien erfüllt, gilt der Test als erfolgreich – grünen Haken dran.

3. Event mit logistischen Daten an TradeLens übermitteln

Nach diesen zwei sicherheitstechnisch vorbereitenden Schritten, der Authentication gegenüber der eigenen Benutzerdatenbank sowie gegenüber TradeLens, kommen wir letztlich zum wesentlichen Punkt: der Übermittlung des für den Benutzer relevanten Transportereignisses an TradeLens.

Im Gegensatz zu den beiden vorangegangenen Schritten müssen drei Automatisierungsschritte vorgenommen werden: Erstens muss im Pre-request Skript der Onboarding Token als Authentication Header Feld eingefügt werden; zweitens soll der Body dynamisch aus einer JSON Datei geladen werden, sodass auch Postman-unvertraute Mitarbeiter neue Testdaten in einen Testlauf einbringen können bzw. dem Tester Testdaten in Form von einfach zu erstellenden JSON Dateien zukommen lassen können; drittens soll die Response dieses POST-Request auf ihren Erfolg hin geprüft werden. Fangen wir mit der ersten Maßnahme an, der Übermittlung des Onboarding Token als Header Feld.

 

 

 

In Zeile 2 wird eine lokale Variable namens “bearerToken” erzeugt, welcher der Wert “Bearer ” gefolgt vom Inhalt, d.h. dem Onboarding Token, der entsprechenden Collection Variable zugewiesen wird. In Zeile 3 fügen wir diese lokale Variable als Header Element “Authorization” dem anstehenden POST-Request bei bzw. aktualisieren den Wert dieses Header Elements, sofern es schon besteht. Die aus der Datenbankentwicklung stammende Methode “upsert” kommt dafür auch in der JavaScript Erweiterung von Postman zum Einsatz. Zudem rufen wir in Zeile 6 und 7 die aktuelle ISO 8601 konforme Zeit in der Zeitzone Europa/Berlin von einem externen Zeitdienst ab, um diese in einer globalen Variablen namens “TimeStamp” im Zeitformat (datetime) zu speichern. Diese globale Variable soll in die zu übermittelenden Transportdaten eingespeist werden, da TradeLens den Übermittelungszeitpunkt wissen möchte. Selbstverständlich hätte man statt einer globalen Variable auch eine Collection oder Environment Variable nutzen können; wir haben uns für eine globale entschieden, um deren Verwendung exemplarisch zu zeigen. Letztlich soll in Zeile 11 die Collection Variable “IterationData” mit allen Testdaten bestückt werden – erneut als String, wie Postman das bei Variableninhalten fordert. Die Testdaten stammen dabei aus dem vorbesagten separaten JSON-Dokument, welches der Collection Runner in Postman hineinlädt. Dieses “Sideloading” von Testdaten in Postman ist ein sehr willkommenes Feature, um die Erstellung von Automatisierungen durch einen Testautomatisierer von der Verwendung der Testautomatisierung bzw. der Bereitstellung von realen Testdaten durch einen Fachbereichsmitarbeiter zu trennen.

Der Body des anstehenden POST-Requests sieht dann auch unspektakulär aus. Er enthält lediglich die Collection Variable “IterationData“, welche wiederum den unten gezeigten beispielhaften Testdatensatz umfasst. Die roten Pfeile zeigen, wo die im JavaScript definierte Collection Variable zum Einsatz kommt und seitens Postman im Hintergrund durch konkrete Werte ersetzt wird. Für Testzwecke wurde der Zeitpunkt des Transportevents mit dem der Eventübermittlung gleichgesetzt; in der produktiven Automatisierung wird ersterer Zeitpunkt vom Transport Management System übergeben und muss nicht ergänzt werden.

 

 

 

 

 

Im Testdatenbeispiel wird auch ein anderer Vorteil des “Sideloading” in Postman deutlich: die Lieferung von mehreren Testdatensätzen, welche Postman anschließend sequenziell abarbeitet, ohne dass der Anwender die Testautomatisierung erneut starten muss. Die verschwommenen Felder enthalten potenziell vertrauliche Testdaten, sodass sie hier entfernt wurden. Die übrigen Felder sind künstliche Testdaten ohne Realitätsbezug.

Als letzter Schritt in diesem dritten POST-Request soll noch der Erfolg des Posts überprüft werden. Dieser ist gewährleistet, wenn entweder eine 201 oder 202 HTTP-Response von TradeLens kommt, welche im Body den Text “Event submitted” enthält. Damit sind wir am Ende unserer Testautomatisierung mit Postman angekommen. Startet man den Collection Runner, dann laufen alle Schritte je Iteration, d.h. je eingelesenem Datensatz, durch und deren Testergebnisse werden übersichtlich in Postman mit roten oder grünen Symbolen angezeigt. Der Erfolg kann zudem in der Web-Oberfläche von TradeLens verifiziert werden. In ihr sieht man sämtliche Events, auf welche die eigene Organisation Zugriff hat – auch die selbst publizierten. Dies würde uns hier jedoch zu weit führen.

 

 

 

Postman stellt ein wunderbares Tool zum Verständnis von APIs und zu deren ersten, schrittweisen Implementierung und Testautomatisierung dar. Hat man diese erste Hürde genommen, so steht der Automatisierung und Integration in die Produktionssysteme nichts mehr im Weg. Hier kommen dann aber mächtigere Tools wie die cloudbasierte Low-Code Integrations- und Automatisierungsplattform Workato zum Einsatz, die sich auch hervorragend für die Testautomatisierung von APIs eignet. Für eine oberflächenorientierte Testautomatisierung und ein kontinuierliches operatives Monitoring greifen wir sodann auf No-Code RPA Tools wie Leapwork zurück. Sie ermöglichen automatisierte Tests von Programmen mit Benutzeroberflächen wie Webanwendungen, Citrix-Anwendungen oder auch installierten Programmen und Apps. Wir werden uns in einem eigenen Beitrag diesem hocheffizienten Tool widmen und seine Stärken anhand eines konkreten Beispiels präsentieren.

 

Über Business Automatica GmbH:

Business Automatica senkt Prozesskosten durch Automatisierung manueller Tätigkeiten, hebt die Qualität beim Datenaustausch in komplexen Systemarchitekturen und verbindet On-premise Systeme mit modernen Cloud- und SaaS-Architekturen.