Base64-Dateien konvertieren
In diesem Tutorial erfahren Sie, wie Sie in der X4 BPMS Dateien mit dem Adapter Base64 Converter kodieren und dekodieren.
Base64 ist ein Kodierungsschema, mit dem Binärdaten als ASCII-Text kodiert werden können. Das Schema wurde entwickelt, um Daten mit Medien zu übertragen, die nur ASCII-Formate unterstützen. Das sind z. B. E-Mails mit MIME-Type und XML-Daten.
Mit dem Base64 Converter können in der X4 BPMS in technischen Prozessen Base64-kodierte Daten kodiert und dekodiert werden. Das Ergebnis der Kodierung hängt vom MIME-Type des Dokuments ab, das als Input zur Verfügung gestellt wird. Wenn der MIME-Type text/xml oder application/xml ist, dann interpretiert der Adapter das Dokument als XML-Dokument und dekodiert den Inhalt des Wurzelelements. Bei allen anderen MIME-Types wird der gesamte Inhalt des Dokuments dekodiert.
Dieses Tutorial enthält zwei Beispiele, wie Sie den Adapter verwenden können:
- Textdatei mit Base64 kodieren
- XML-Dokument dekodieren
Inhaltsverzeichnis
Case
Arbeiten mit Adaptern
X4 BPMS-Komponenten
X4 BPMS-Adapter
Branchen
Branchenübergreifend
Sie können ein Template zu diesem Tutorial über den Button herunterladen. Entpacken Sie einfach die .zip-Datei und ziehen Sie das Template mit der Dateiendung .x4projecttemplate per Drag & Drop in den Repository Navigator des X4 Designers.
Text mit Base64 kodieren
In diesem Beispiel wollen wir eine Textdatei in einem Prozess Base64-kodieren. Dafür benötigen wir ein ESB-Projekt.
Projekt erstellen
Zunächst erstellen wir ein neues ESB-Projekt. Um ein neues ESB-Projekt zu erstellen, klicken Sie im X4 Designer auf File > New > ESB Project
- Der Project Creation Wizard öffnet sich.
Geben Sie für Project name ConvertBase64 ein.
- Ein neues ESB-Projekt wird angelegt.
Ein Projektname (Project name) darf kein Leerzeichen enthalten!
Für unseren Prozess, mit dem wir einen Text mit Base64 kodieren, benötigen wir mehrere Elemente:
- Books.csv
Aus dieser Datei lesen wir den Text aus, den wir kodieren möchten. - Adapter Base64_Encoder.fa
Mit diesem Adapter kodieren wir die Textdatei mit Base64. - Output.txt
In dieser Textdatei speichern wir den Output des Adapters.
CSV-Datei Books erstellen
Diese Elemente legen wir nun an. Wir beginnen mit der CSV-Datei Books.
Klicken Sie im X4 Repository mit der rechten Maustaste im ESB-Projekt ConvertBase64 auf den Ordner Resources, um das Kontextmenü zu öffnen.
- Das Kontextmenü öffnet sich.
Klicken Sie auf New > Text Document.
- Der File Creation Wizard öffnet sich.
Geben Sie für File name Books.csv ein.
Um die Datei zu erzeugen, klicken Sie auf Finish.
- Die CSV-Datei wird erzeugt, im X4 Repository angezeigt und im X4 Designer geöffnet.
Der Inhalt der Datei muss sein wie folgt:
"category";"title";"author";"year";"price" "Cooking";"Everyday Italian";"Giada De Laurentiis";"2005";"30.00" "Children";"Harry Potter";"J K. Rowling";"2005";"29.99" "";"BPMN 2.0 - Business Process Model and Notation";"Thomas Allweyer";"2015";"19.99" "Cooking";"The mysterious eating plan";"John "ToTo" Doe, Juergen "Black" Smith";"2019"
Speichern Sie die Datei, indem Sie in der Werkzeugleiste auf Speichern bzw. Alle Speichern klicken:
Sie können Ihre Änderungen auch mit Strg+S speichern.
Adapter Base64_Encoder erstellen
Als nächstes erstellen wir unseren Adapter.
Klicken Sie im X4 Repository mit der rechten Maustaste im ESB-Projekt ConvertBase64 auf den Ordner Adapters, um das Kontextmenü zu öffnen.
- Das Kontextmenü öffnet sich.
Klicken Sie auf New > Adapter.
- Der File Creation Wizard öffnet sich.
Wählen Sie den Adapter Base64 Converter aus.
Sie können den Adapter über das Suchfeld im oberen Bereich des File Creation Wizard suchen.
Geben Sie als File name Base64_Encoder.fa ein.
Um den Adapter anzulegen, klicken Sie auf Finish.
- Der Adapter wird angelegt und geöffnet.
Textdatei OutputBase64 erstellen
Wir benötigen noch eine Datei, in der wir den Output des Adapters speichern können.
Klicken Sie im X4 Repository mit der rechten Maustaste im ESB-Projekt ConvertBase64 auf den Ordner Resources, um das Kontextmenü zu öffnen.
- Das Kontextmenü öffnet sich.
Klicken Sie auf New > Text Document.
- Der File Creation Wizard öffnet sich.
Geben Sie für File name Output.txt ein.
Um die Datei zu erzeugen, klicken Sie auf Finish.
- Die TXT-Datei wird erzeugt, im X4 Repository angezeigt und im X4 Designer geöffnet.
Die Datei hat keinen Inhalt. Der Inhalt wird später durch den Prozess erzeugt und geschrieben.
Prozess EncodeText erstellen
Die eben erzeugen Elemente wollen wir nun in einem Prozess zusammenführen. Dafür müssen wir in unserem ESB-Projekt einen Prozess anlegen.
Klicken Sie im X4 Repository mit der rechten Maustaste im ESB-Projekt ConvertBase64 auf den Ordner Processes, um das Kontextmenü zu öffnen.
- Das Kontextmenü öffnet sich.
Klicken Sie auf New > Process.
- Der File Creation Wizard öffnet sich.
Wählen Sie ein leeres Template und geben Sie als File name EncodeText.wrf ein.
Um den Prozess zu erstellen, klicken Sie auf Finish.
- Der Prozess wird erstellt und angezeigt.
Fügen Sie die benötigten Elemente per Drag & Drop aus dem X4 Repository zum Prozess hinzu:
Books.csvBase64_Encoder.faOutputBase64.txt
Der Prozess sieht nun so aus:
Nun müssen wir die einzelnen Bausteine noch konfigurieren. Wählen Sie den linken Baustein, die CSV-Datei Books aus, indem Sie darauf klicken.
In der linken unteren Ecke werden Ihnen die Properties (Eigenschaften) dieses Bausteins angezeigt. Stellen Sie die Properties wie folgt ein. Bestätigen Sie die jeweilige Eingabe, indem Sie die Enter-Taste drücken.
| Property | Wert | Beschreibung |
|---|---|---|
| Label | Text file |
Beschriftung des Bausteins |
Wählen Sie den Adapter Base64_Encoder aus, indem Sie darauf klicken.
In der linken unteren Ecke werden Ihnen die Properties (Eigenschaften) dieses Bausteins angezeigt. Stellen Sie die Properties wie folgt ein. Bestätigen Sie die jeweilige Eingabe, indem Sie die Enter-Taste drücken.
| Property | Wert | Beschreibung |
|---|---|---|
| Label | Encode |
Beschriftung des Bausteins |
| Operation | Encode |
Operation, die durch den Adapter ausgeführt wird. |
Wählen Sie die Textdatei OutputBase64 aus, indem Sie darauf klicken.
In der linken unteren Ecke werden Ihnen die Properties (Eigenschaften) dieses Bausteins angezeigt. Stellen Sie die Properties wie folgt ein. Bestätigen Sie die jeweilige Eingabe, indem Sie die Enter-Taste drücken.
| Property | Wert | Beschreibung |
|---|---|---|
| Label | Base64 encoded Data |
Beschriftung des Bausteins |
| Operation | Write |
Bestimmt, ob die Datei geschrieben oder gelesen wird. |
Nicht erwähnte Properties müssen Sie nicht anpassen.
Wir setzen die Operation der Datei auf Write, damit wir die vom Adapter erzeugte Datei, die die Base64-kodierten Daten enthält, abspeichern können. Jedes Mal, wenn ein neuer Output durch den Adapter generiert wird, wird die Datei überschrieben.
Unser Prozess sieht nun so aus:
Prozess EncodeText testen
Jetzt möchten wir natürlich wissen, ob unser Prozess funktioniert und ob der eingegebene Text richtig umgewandelt wird.
Klicken Sie in der Werkzeugleiste des X4 Designer auf Start Debugging.
Wir können den Prozess Schritt für Schritt (1, Resume) oder auf einmal (2, Step into / Step over) ausführen lassen.
Sobald der Prozess beendet ist, können wir prüfen, ob der Adapter eine Datei ausgegeben hat, die die Base64-kodierten Daten enthält. Um die Datei zu öffnen, klicken Sie doppelt auf den Baustein OutputBase64 in unserem Prozess EncodeText.
- Die eben im Prozess erzeugte und abgespeicherte XML-Datei wird geöffnet und enthält die Base64-kodierten Daten, eine lange Folge von Ziffern und Buchstaben.
Falls etwas im Prozess nicht wie erwartet funktioniert, können wir den Prozess im Debug-Modus Schritt für Schritt überprüfen. Für jeden Schritt können wir uns die Ausgaben jedes einzelnen Prozessbausteins ansehen. Dazu müssen wir nur auf das kleine Symbol oben rechts neben dem Baustein klicken:
Base64-Code in ein XML-Dokument dekodieren
In diesem Beispiel wollen wir einen Base64-Code in ein XML-Dokument dekodieren. Dafür benötigen wir ein ESB-Projekt. Sie können entweder ein neues ESB-Projekt anlegen (siehe Projekt erstellen) oder in unserem vorhandenen Projekt ConvertBase64 weiterarbeiten.
Für unseren Prozess, mit dem wir aus eine Base64-kodierte Datei dekodieren, benötigen wir mehrere Elemente:
- Base64Data.xml
Aus dieser Datei lesen wir den Base64-Code aus, den wir dekodieren möchten. - Adapter Base64_Decoder.fa
Mit diesem Adapter dekodieren wir den Base64-Code. - Output.xml
In dieser XML-Datei speichern wir den Output des Adapters.
XML-Datei Base64Data erstellen
Diese Elemente legen wir nun an. Wir beginnen mit der XML-Datei Base64Data.
Klicken Sie im X4 Repository mit der rechten Maustaste im aktuellen ESB-Projekt auf den Ordner Resources, um das Kontextmenü zu öffnen.
- Das Kontextmenü öffnet sich.
Klicken Sie auf New > XML Document.
- Der File Creation Wizard öffnet sich.
Geben Sie für File name Base64Data.xml ein.
Um die Datei zu erzeugen, klicken Sie auf Finish.
- Die CSV-Datei wird erzeugt, im X4 Repository angezeigt und im X4 Designer geöffnet.
Der Inhalt der Datei muss sein wie folgt:
<?xml version="1.0" encoding="UTF-8"?> <Body><!-- Base64-Code --></Body>
Der Base64-Code muss in einer XML-Datei enthalten sein. Der Base64-Code befindet sich darin im Wurzelelement der XML-Datei.
Der MIME-Typ der Eingabedatei muss entweder text/xml oder application/xml sein, damit der Adapter ein XML-Dokument ausgibt.
Als Base64-Code können Sie z. B. den Output aus unserem ersten Beispiel verwenden.
Adapter Base64_Decoder erstellen
Als nächstes erstellen wir unseren Adapter.
Klicken Sie im X4 Repository mit der rechten Maustaste im aktuellen ESB-Projekt auf den Ordner Adapters, um das Kontextmenü zu öffnen.
- Das Kontextmenü öffnet sich.
Klicken Sie auf New > Adapter.
- Der File Creation Wizard öffnet sich.
Wählen Sie den Adapter Base64 Converter aus.
Sie können den Adapter über das Suchfeld im oberen Bereich des File Creation Wizard suchen.
Geben Sie als File name Base64_Decoder.fa ein.
Um den Adapter anzulegen, klicken Sie auf Finish.
- Der Adapter wird angelegt und geöffnet.
XML-Datei OutputXML erstellen
Wir benötigen noch eine Datei, in der wir den Output des Adapters speichern können.
Klicken Sie im X4 Repository mit der rechten Maustaste im aktuellen ESB-Projekt auf den Ordner Resources, um das Kontextmenü zu öffnen.
- Das Kontextmenü öffnet sich.
Klicken Sie auf New > XML Document.
- Der File Creation Wizard öffnet sich.
Geben Sie für File name OutputXML.xml ein.
Um die Datei zu erzeugen, klicken Sie auf Finish.
- Die XML-Datei wird erzeugt, im X4 Repository angezeigt und im X4 Designer geöffnet.
Die Datei hat keinen Inhalt. Der Inhalt wird später durch den Prozess erzeugt und geschrieben.
Prozess DecodeBase64Data erstellen
Die eben erzeugen Elemente wollen wir nun in einem Prozess zusammenführen. Dafür müssen wir in unserem ESB-Projekt einen Prozess anlegen.
Klicken Sie im X4 Repository mit der rechten Maustaste im aktuellen ESB-Projekt auf den Ordner Processes, um das Kontextmenü zu öffnen.
- Das Kontextmenü öffnet sich.
Klicken Sie auf New > Process.
- Der File Creation Wizard öffnet sich.
Wählen Sie ein leeres Template und geben Sie als File name DecodeBase64Data.wrf ein.
Um den Prozess zu erstellen, klicken Sie auf Finish.
- Der Prozess wird erstellt und angezeigt.
Fügen Sie die benötigten Elemente per Drag & Drop aus dem X4 Repository zum Prozess hinzu:
- Base64Data.xml
- Base64_Decoder.fa
- Output.xml
Der Prozess sieht nun so aus:
Nun müssen wir die einzelnen Bausteine noch konfigurieren. Wählen Sie den linken Baustein, die XML-Datei Base64Data aus, indem Sie darauf klicken.
In der linken unteren Ecke werden Ihnen die Properties (Eigenschaften) dieses Bausteins angezeigt. Stellen Sie die Properties wie folgt ein. Bestätigen Sie die jeweilige Eingabe, indem Sie die Enter-Taste drücken.
| Property | Wert | Beschreibung |
|---|---|---|
| Label | Base64 encoded Data |
Beschriftung des Bausteins |
Wählen Sie den Adapter Base64_Decoder aus, indem Sie darauf klicken.
In der linken unteren Ecke werden Ihnen die Properties (Eigenschaften) dieses Bausteins angezeigt. Stellen Sie die Properties wie folgt ein. Bestätigen Sie die jeweilige Eingabe, indem Sie die Enter-Taste drücken.
| Property | Wert | Beschreibung |
|---|---|---|
| Label | Decode |
Beschriftung des Bausteins |
| Operation | Decode |
Operation, die durch den Adapter ausgeführt wird. |
Wählen Sie die Textdatei OutputXML aus, indem Sie darauf klicken.
In der linken unteren Ecke werden Ihnen die Properties (Eigenschaften) dieses Bausteins angezeigt. Stellen Sie die Properties wie folgt ein. Bestätigen Sie die jeweilige Eingabe, indem Sie die Enter-Taste drücken.
| Property | Wert | Beschreibung |
|---|---|---|
| Label | XML Document |
Beschriftung des Bausteins |
| Operation | Write |
Bestimmt, ob die Datei geschrieben oder gelesen wird. |
Nicht erwähnte Properties müssen Sie nicht anpassen.
Wir setzen die Operation der Datei auf Write, damit wir die vom Adapter erzeugte Datei, die die Base64-kodierten Daten enthält, abspeichern können. Jedes Mal, wenn ein neuer Output durch den Adapter generiert wird, wird die Datei überschrieben.
Unser Prozess sieht nun so aus:
Prozess DecodeBase64Data testen
Jetzt möchten wir natürlich wissen, ob unser Prozess funktioniert und ob der eingegebene Base64-Code richtig umgewandelt wird.
Klicken Sie in der Werkzeugleiste des X4 Designer auf Start Debugging.
Wir können den Prozess Schritt für Schritt (1, Resume) oder auf einmal (2, Step into / Step over) ausführen lassen.
Sobald der Prozess beendet ist, können wir prüfen, ob der Adapter eine Datei ausgegeben hat, die die dekodierten Daten enthält. Um die Datei zu öffnen, klicken Sie doppelt auf den Baustein OutputXML in unserem Prozess DecodeBase64Data.
- Die eben im Prozess erzeugte und abgespeicherte XML-Datei wird geöffnet und enthält den dekodierten Inhalt des Base64-Codes, z. B. eine Bücherliste.
Falls etwas im Prozess nicht wie erwartet funktioniert, können wir den Prozess im Debug-Modus Schritt für Schritt überprüfen. Für jeden Schritt können wir uns die Ausgaben jedes einzelnen Prozessbausteins ansehen. Dazu müssen wir nur auf das kleine Symbol oben rechts neben dem Baustein klicken: