MuleSoft DataWeave Libraries – Teilen leicht gemacht

Mit Anypoint Exchange bietet Mulesoft bereits seit langer Zeit die Möglichkeit, verschiedene Assets wie zum Beispiel Konnektoren oder APIs mit anderen zu teilen.

Was bisher gefehlt hat, war jedoch die Möglichkeit, DataWeave-Code bereitstellen zu können. Natürlich bietet Mulesoft mit den DataWeave-eigenen Bibliotheken eine große Anzahl Funktionalitäten für den täglichen Bedarf. Um jedoch businessspezifische Bibliotheken zu teilen, musste man bisher auf Domain- oder Library-Projekte zurückgreifen. Im schlechtesten Fall hatte jede Applikation ihre eigene Kopie der Logik.

Doch dies sollte bald der Vergangenheit angehören. Das Feature befindet sich zwar aktuell noch im Beta-Status, bereits jetzt kann man aber damit herumexperimentieren und testen.

Netter Nebeneffekt: Man sich so schon mal ein wenig an das Look and Feel des zukünftigen Anypoint Studios gewöhnen ...

In diesem Blogeintrag möchte ich einen kurzen Einblick geben, wie DataWeave Libraries funktionieren.

Vorbereitungen

Da es aktuell keine spezifischen Angaben über die Mindestanforderungen bei den Versionen gibt, habe ich dafür einfach die aktuelle Konfiguration meines Laptops genutzt. Daher gehe ich davon aus, dass auch abweichende Versionen funktionieren.

• Java 1.8.0_291,
• Apache Maven 3.6.3
• Visual Studio Code
• DataWeave 2.0 Plugin für Visual Studio Code

Das Projekt anlegen

Nachdem alle Vorbereitungen getroffen wurden, können wir damit beginnen, ein Projekt anzulegen.

In Visual Studio Code öffnen wir dafür die Command-Palette (Ctrl + Shift + P unter Windows oder über das Menü „View" > „Command Palette ...“) und geben dort „DataWeave“ ein. Dort finden wir dann einen Eintrag „DataWeave: Create New Library Project“.

Nachdem wir den Eintrag ausgewählt haben, bekommen wir nacheinander einige Eingabefelder zu sehen, in denen wir unser Projekt grundlegend konfigurieren können.

In meinem Fall lege ich das Projekt mit folgenden Informationen an:

• Group ID: de.codecentric (falls zu diesem Zeitpunkt bereits vorhanden, kann hier auch bereits jetzt die Organization Id aus der Anypoint Plattform eingetragen werden)
• Artifact ID: myLib
• Version: 1.0.0-SNAPSHOT
• Project Name: mylib
• Path: c:\Users\Pasquale\mylib

Wenn man nun mit der Enter-Taste bestätigt, hat man binnen weniger Sekunden ein Projekt erstellt. Die Struktur des Projekts ist dabei so, wie man sie typischerweise von Maven-Projekten kennt. Dies macht es leicht, sich zurechtzufinden.

Ebenfalls stellt uns das Projekt zwei kleine Beispieldateien (main/MyModule.dwl und test/MyMapping.dwl) bereit. Diese können wir aber erst einmal löschen (oder zumindest nicht beachten), da wir auf einer grünen Wiese anfangen wollen.

Die erste Funktion

Jetzt sind wir bereit für unsere erste Funktion. Als kleines Projekt habe ich mir überlegt, dass wir (unbedingt!) ein Skript benötigen, das uns je nach Tageszeit korrekt begrüßt. Unsere Funktion nimmt dabei den Namen einer Person und die Stunde des Tages entgegen und gibt dann, je nach Uhrzeit, eine freundliche Begrüßung aus.

Dafür können wir unter src/main/dw ein neues Modul (rechte Maustaste) mit dem Namen „GreetUtils“ anlegen. Dort können wir jetzt, wie wir es aus DataWeave kennen, eine Funktion erstellen. Diese nennen wir „greetPersonByHour“.

Nun haben wir unsere Funktion geschrieben – aber ob diese wirklich tut, was sie soll, wissen wir an dieser Stelle noch nicht, denn wir haben sie ja noch nie in Aktion gesehen.

Doch auch dafür gibt es eine Lösung. Am oberen Ende unserer Funktion sieht man den Text „Create Integration Mapping". Mit einem Klick darauf wird uns ein Vorschlag für den Namen einer Datei gemacht. Diesen können wir bestätigen. Anschließend wird eine neue Datei generiert, die unsere erstellte Funktion enthält. Diese können wir dort nun, wie wir es aus DataWeave im Anypoint Studio gewohnt sind, aufrufen und mit Testdaten füllen.

(Es lohnt sich, einmal die mit der rechten Maustaste das Submenü aufzurufen und dort „DataWeave: Enable Auto Preview“ auszuwählen, da man sonst bei jeder Veränderung im Mapping speichern und am oberen Bildrand auf den Pfeil klicken müsste, um eine Aktualisierung der Ausgabe zu erhalten – so passiert dies automatisch.)

Und schon sehen wir, dass unsere Funktion wie erwartet funktioniert, wenn wir unsere Funktion mit verschiedenen Werten aufrufen.

(Diese Mapping-Datei hat ausschließlich den Zweck, dass man damit seine Funktion visualisieren und manuell testen kann. Für den späteren Verlauf spielt diese Datei keine Rolle.)

Kommmentare

Auch kommentieren können wir unsere Methode mit einem einfach Klick auf Generate DataWeave Documentation direkt über unserer Funktion. So wird uns ein Template bereitgestellt, das wir nur noch ausfüllen müssen. Wenn wir dann mit der Maus über unsere Funktion fahren, sehen wir auch direkt, wie die Beschreibung später aussieht.

Tests

Auch Unit Tests für die von uns erstellten Funktionen sind vorgesehen. Wie bei dem zuvor erstellten Integration Mapping können wir diesmal auf den Button über unserer Funktion mit dem Text „Add Unit Test“ klicken, und schon wird uns eine Datei mit einem Template für unseren Test erstellt. Diesen können wir jetzt beliebig erweitern und für alle nötigen Szenarien entsprechende Tests schreiben.

Wenn wir den Test ausführen möchten, können wir am linken Rand auf den (Erlenmeyer-)Kolben klicken und unseren Test dort mit dem Play-Button starten. (Dies kann beim ersten Mal einige Zeit dauern, da erst alle Dependencies heruntergeladen werden müssen)

Am Ende finden wir dann (hoffentlich) ein „All test passed (ignored: 0 total: 3)“ im Terminal von Visual Studio – oder wir müssen ggf nachjustieren.

Das gleiche Ergebnis können wir natürlich auch über das Terminal mit „mvn test“ innerhalb unseres Projektverzeichnisses erreichen.

Teilen unserer Library

Nun wollen wir unsere Library natürlich auch anderen zur Verfügung stellen. Dabei gibt es allerdings einige Dinge zu beachten.

Zuert müssen wir in der pom.xml die Group ID entsprechend unserer organizationId anpassen – in meinem Fall sieht das wie folgt aus, die groupId, die bei Projekterstellung gesetzt wurde, können wir dabei überschreiben (außer es wurde bereits zu Beginn die Organization ID genutzt).

[...]

<groupId>5562b7b7-ce9a-4fa1-bb50-34beed2a622d</groupId>
<artifactId>mylib</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>dw-library</packaging>
<name>mylib</name>

[...]

Eine Anleitung, wo man die organizationId findet, gibt es hier.

Weiterhin müssen wir die beiden folgenden Abschnitte in der POM einkommentieren und unsere Organzation ID hinzufügen.

[...]
<distributionManagement>
<repository>
<id>exchange</id>
<name>Exchange Repository</name>
<url>https://maven.anypoint.mulesoft.com/api/v3/organizations/5562-34beed2a622d/maven</url>
<layout>default</layout>
</repository>
</distributionManagement>

<repositories>
<repository>
<id>exchange</id>
<name>Exchange Repository</name>
<url>https://maven.anypoint.mulesoft.com/api/v3/organizations/5562-34beed2a622d/maven</url>
<layout>default</layout>
</repository>
[...]

Nun ist es wichtig, auch die settings.xml-Datei im .m2-Verzeichnis entsprechend anzupassen.

Ein Beispiel findet man hier.

In unserem Beispiel müssen wir in der settings.xml zuletzt noch den Server-Eintrag für Exchange hinzufügen und die Credentials entpsrechend unserer eigenen anpassen.

[...]

<server>
<id>exchange</id>
<username>USER</username>
<password>PASSWORD</password>
</server>

[...]

Mit einem mvn deploy im Terminal sollte, wenn alles korrekt ausgefüllt werde, das Deyploment Richtung AnyPoint Exchange starten.

Sollte es hierbei zu einem Fehler gekommen sein, gibt es in m2-Repository des Artifacts eine Datei, die z. B. „mylib-1.0.0-SNAPSHOT-preConditions-1660907941195.json“ heißt. In dieser findet man ggf. den Hinweis auf den Grund. Dies hat mir auf jeden Fall geholfen, als ich meine Authentication falsch eingestellt hatte und die Nachricht im Terminal nicht aussagekräftig war.

Info: Für dieses Beispiel habe ich mir einen neuen Testaccount angelegt, mit den Root-Rechten gab es dabei keine Probleme, die Library nach Exchange zu laden.

In einer existierenden Organisation mit enstprechenden Rollen müssen ggf. die User mit entpsrechenden Rechten – zum Beispiel „Exchange Contributors“ – ausgestattet werden.

Nutzung

Wenn alles erfolgreich war, können wir nach kurzer Zeit unsere Library in Anypoint Exchange begutachten.

Wenn wir möchten, können wir außerdem ein prägnantes Bild, eine vernünftige Beschreibung und weitere Metainformationen hinzufügen.

Jetzt ist es so weit und wir können unsere Library das erste Mal „richtig“ in Aktion erleben. Dafür legen wir im Anypoint Studio ein neues Projekt an.

Anschließend können wir wieder zu Anypoint Exchange wechseln. Dort finden wir im rechten oberen Teil den Button Dependency Snippet.

Nach einem Klick öffnet sich ein kleines Fenster, aus dem wir die angezeigte Dependency in unsere Projekt-pom.xml kopieren.

Nachdem die Dependency runtergeladen wurde, können wir unsere Library dann in einem Transformer importieren und nutzen.

Dabei ist zu beachten, dass der Name des Imports dem Namen der Modul-Datei entspricht und nicht etwa dem Namen des importierten Projekts!

Das war es auch schon, ab sofort sind wir stolzer Besitzer einer eigenen, einfach teilbaren DataWeave Library.

Fazit

Anfangs war es etwas seltsam, in Visual Basic Studio für Mule zu entwickeln – jedoch hat sich trotz des Beta-Status nach kurzer Zeit herausgestellt, dass das Ganze wirklich gut unterstützt wird (Projekterstellung, Hinweise, Tests, Codevervollständigung, Vorschau), so dass sich bei mir schnell ein positives Gefühl eingestellt hat.

Gerne hätte ich dabei in meinen bisherigen Projekten bereits das eine oder andere Mal auf diese Möglichkeit zurückgegeriffen.

Negative Aspekte konnte ich bisher nicht feststellen – außer dass eine offizielle Dokumentation scheinbar (bisher) nicht vorhanden ist und ich etwas herumtüfteln musste, bis alles funktioniert hat.

Wie immer freue ich mich über Kritik und Anregungen.