BPC Anbindung Tutorial

Um Daten der BPC-Instanz verarbeiten zu können, müssen diese zunächst an IGUASU übergeben werden.
Hierbei ermöglicht der ListenBPCFlowStarter-Prozessor als Schnittstelle den Empfang und die weitere Verarbeitung der übermittelten Informationen. Um eine Verbindung zum BPC zu ermöglichen, muss dieser Prozessor dementsprechend zunächst als Startpunkt eingefügt werden.

Unter den Prozessor Properties müssen im Anschluss die Einstellungen konfiguriert werden, damit Daten vom BPC an IGUASU übertragen werden können.
Für diesen Zweck wird zunächst ein BPC Listener Base Path hinterlegt, unter dem der Prozessor im späteren Verlauf zu erreichen sein wird. Darüber hinaus muss ein Name unter Flow Starter Name und eine Beschreibung unter Flow Starter Desc. hinzugefügt werden, die gemeinsam mit dem Base Path ebenfalls im BPC ersichtlich sein werden. Insbesondere bei der Arbeit mit multiplen Listenern sollte daher stets darauf geachtet werden, angemessene Namen und Beschreibungen zur Unterscheidung im BPC zu nutzen.

In diesem Beispiel soll es möglich sein, Kundendaten im BPC einzugeben, die in IGUASU verarbeitet und zurück an das BPC übermittelt werden, um eine Übersicht über die angelegten Kunden zu ermöglichen. Daher wählen wir für die Konfiguration distinkte Angaben, die den Listener mit der geplanten Funktion von zukünftigen weiteren Listenern unterscheidet. Zusätzlich sollen Informationen zur BPC-Session verarbeitet werden, in der die Daten erstellt wurden. Daher muss die Option Load the BPC Session angewählt werden.

Im nächsten Schritt muss ein BPCController-Service angelegt werden. Ähnlich wie bei den Services der vorangegangenen Tutorials wird der BPCController für die aktuelle Prozessgruppe erstellt.
Zur Konfiguration des BPCControllers muss zunächst die BPC URL eingetragen werden. Wenn IGUASU und das BPC sich in derselben Cloud-Umgebung befinden, lautet die URL standardmäßig “https://bpc-karaf:8282”;. Darüber hinaus muss der API Key hinterlegt werden, welcher in der BPC Instanz erstellt wurde.
Die Anleitung zur Erstellung eines API Keys kann der BPC-Dokumentation entnommen werden.

Um eine sichere Kommunikation zu ermöglichen, sollte zudem ein SSL Context Service ausgewählt werden. Falls keiner hinterlegt wird, muss dies für das Protokoll in der hinterlegten URL im BPC berücksichtigt werden und die TargetURL muss mit http:// beginnen.

Durch die anderen Einstellungsmöglichkeiten wäre es zudem möglich, Timeout-Kriterien oder Optionen zur Authentifikation zu definieren. Diese Einstellungen werden im Rahmen des Tutorials jedoch nicht benötigt und können daher auf dem Standardwert belassen werden.

Zusätzlich zu dem BPCController wird ein BPCListenerController-Service benötigt, der als REST-Endpunkt für die Anwendung fungiert. Ähnlich wie beim BPCController wird dieser als Service für die Prozessgruppe erstellt.

Zur Konfiguration werden hierbei ein Listening Port und Angaben zur Authentifikation benötigt. Als Port kann beispielsweise 9010 eingetragen werden, während der Authentication Username und das Passwort beliebig gewählt werden können.

Die gewählten Angaben müssen im Anschluss im BPC hinterlegt werden, um die Verbindung zum IGUASU zu ermöglichen. Eine Anleitung zur Konfiguration der Verbindung im BPC befindet sich in der BPC-Dokumentation.

Die erstellten BPCController- und BPCListenerController-Services können nach abgeschlossener Konfiguration im ListenBPCFlowStarter-Prozessor ausgewählt werden. Ein Beispiel der finalen Konfiguration kann dem folgenden Screenshot entnommen werden.

Damit sind alle benötigten Einstellungen für das Empfangen der Daten aus dem BPC abgeschlossen.
Sobald der Prozessor auf "Running" gesetzt wird, werden alle Eingaben empfangen und können in IGUASU verarbeitet werden.

Damit neu angelegte Kunden im IGUASU empfangen und verarbeitet werden können, muss allerdings zunächst das entsprechende Formular im BPC konfiguriert werden.

Es existieren unterschiedliche Wege, Eingaben vom BPC an IGUASU zu versenden. In diesem Tutorial wird einerseits die Möglichkeit der Eingabe über das Forms Modul und andererseits der Weg über den Prozessstarter veranschaulicht.
Für die geplante Umsetzung mit dem Forms-Modul im Rahmen dieses Tutorials genügt das Standardformular, welches bei der Erstellung eines neuen Formulars automatisch vorhanden ist.

Um eine erfolgreiche Verbindung zu ermöglichen, muss noch die submitURL angepasst werden, damit die Interaktion mit dem Submit-Button die Daten an den gewünschten Prozessor sendet. Diese Konfiguration ist in der BPC-Dokumentation im Abschnitt Forms Submit beschrieben.

Nach Abschluss der Anpassungen und der Eingabe der SubmitURL, in der die Flow-ID und Prozessor-ID enthalten sind, ist die Konfiguration des gewünschten Formulars abgeschlossen.

Wenn die Konfiguration aller Elemente erfolgreich erledigt ist, wird die Eingabe durch die Betätigung des Formular abschicken- Buttons erfolgreich an IGUASU übermittelt. Dieser Vorgang kann überprüft werden, indem ein Funnel die übermittelten Daten inspiziert.

Die zweite Möglichkeit der Datenweiterleitung an IGUASU, die im Rahmen dieses Tutorials beschrieben wird, ist der Eingabe über einen Prozessstarter. Für diesen Zweck können die vorkonfigurierte Elemente aus der Einleitung genutzt werden oder eine eigene Konfiguration mit der Process Monitoring-Anleitung in der BPC-Dokumentation erstellt werden.

Da der Input aus BPC Forms sich von den generierten Daten des Prozessstarters unterscheidet, sollen im Rahmen des Tutorials zwei Datenflüsse zur Vorverarbeitung angelegt werden. Für diesen Zweck wird ein zweiter ListenBPCFlowStarter erstellt, der für den Prozesstarter genutzt werden soll.
Die Konfiguration verläuft ähnlich wie in Abschnitt 1.1 beschrieben, wobei der Base Path und die Beschreibungen sich vom ersten Listener unterscheiden sollten.

Nachdem der ListenBPCFlowStarter-Prozessor und der Prozessstarter konfiguriert wurden, kann ebenfalls das Übermitteln der Daten ausgetestet werden. Im Anschluss sollten die Daten, wie in der folgenden Abbildung dargestellt, in IGUASU ersichtlich sein.

Wenn die Daten sowohl vom Forms als auch vom Prozessstarter erfolgreich an IGUASU übermittelt werden, können die Informationen in einem nächsten Schritt verarbeitet werden.

Als Ergebnis zur Speicherung der Eingabe soll eine benutzerdefinierte JSON-Struktur erstellt werden, in der zusätzliche Informationen eingetragen sind. Da der Content der empfangenen Forms FlowFiles in IGUASU ebenfalls bereits im JSON-Format sind, bietet sich der JsonataTransformJson-Prozessor an.

Mit dem JsonataTransformJson-Prozessor können sowohl die Attribute als auch der Content eines FlowFiles angepasst werden.
Da der Inhalt verändert werden soll, wird als Input Data Content ausgewählt. Zusätzlich muss die JSONata Transformation-Angabe ausgefüllt werden, um den Prozessor abschließend zu bearbeiten. Hierzu steht im Konfigurationsbereich die Editor-Spalte zur Verfügung, in dem die gewünschte Struktur hinterlegt werden kann.

Da die Daten im späteren Verlauf des Tutorials über einen Process Logger im BPC eingetragen werden sollen, muss für den JSON-Content die entsprechende Struktur berücksichtigt werden. Die grundlegende Struktur sieht dabei vor, dass Informationen des Parent- und Child-Elements unterteilt werden.

Für dieses Beispiel sollen die allgemeinen Informationen zu den Kunden im Parent-Element und mögliche Bearbeitungsschritte, die in zukünftigen Iterationen angepasst werden, im Child-Element gespeichert werden. Wenn dabei die JSON-Struktur der Forms-Eingabe berücksichtigt wird, ergibt sich der folgende Aufbau für die geplanten JSON-Daten:

Die vorhandenen Informationen können in der JSON-Struktur neu sortiert werden, um ein neues Objekt zu schaffen. Durch data.firstName & data.lastName können beispielsweise die ursprünglich distinkten Angaben zum Vor- und Nachnamen zu fullname kombiniert werden. Zusätzlich ist es möglich, auf Attribute zuzugreifen und diese ebenfalls in die JSON-Struktur zu integrieren. Dies wird hier für das Attribut filename angewandt, um individuelle IDs zu übernehmen, da der Dateiname in IGUASU immer einzigartig ist. Zusätzliche besteht die Möglichkeit, Funktionen wie $now() aufzurufen, was in diesem Fall für das Erstellungsdatum genutzt wird.

Durch diesen Schritt sind die Daten des BPC Forms für den Prozesslogger umgestellt.
Das gleiche Vorgehen muss nun ebenfalls für den Prozessstarter erfolgen.

Die Daten des Prozessstarters müssen zunächst angepasst werden, da diese nicht als JSON an IGUASU übermittelt werden. Die erhaltenen Daten sind im URL-kodierten XML-Format und werden mit dem Zusatz request= eingeleitet, was ebenfalls entfernt werden muss.

Um den Zusatz zu entfernen, kann der ReplaceText-Prozessor genutzt werden. Als Search Value wird request= eingetragen und der Replacement Value kann leer gelassen werden.

Dadurch bleibt die URL-kodierte XML-Datei übrig.

Zum Dekodieren kann die NiFi Expression Language Funktion urlDecode() genutzt werden, die allerdings nur auf Attribute angewandt werden kann. Daher muss der Inhalt zunächst in ein Attribut überführt werden, um im Anschluss die Funktion zu verwenden.
Für diesen Zweck kann der ExtractText-Prozessor genutzt werden, um den Content in ein Attribut zu speichern. Hierfür muss über eine dynamische Property der Name für das Attribut (für dieses Beispiel Content) und der Wert festgelegt werden. Da der gesamte Inhalt des Contents übernommen werden soll, wird als Wert (?s)(^.*$) eingefügt.

Nun kann ein zweiter ReplaceText-Prozessor genutzt werden, um den kodierten Inhalt durch den dekodierten zu ersetzen. Da alles ersetzt werden kann, wird als Search Value (?s)(^.*$) gewählt.

Um ein Attribut als Content zu verwenden und gleichzeitig das Dekodieren durchzuführen, kann die Expression Language verwendet werden. Im Replacement Value kann damit durch die Eingabe von ${Content:urlDecode()} der dekodierte Wert des Attributs übernommen werden. Mit der abgeschlossenen Konfiguration sollte der Prozessor wie folgt aussehen:

Zuletzt muss die XML-Datei noch in JSON umgewandelt werden, um die anschließende Verarbeitung zu ermöglichen. Für diesen Zweck wird der ConvertRecord-Prozessor verwendet.

Für die Konfiguration wird ein Record Reader und ein Record Writer als Service benötigt, mit denen die gewünschten Formate gelesen und erstellt werden können. Da der Prozessor XML-Dateien in das JSON-Format konvertieren soll, wird als Reader der XMLReader-Service benötigt und als Writer der JSONRecordSetWriter-Service. Beide Services können ohne weitere Konfigurationen aktiviert und beim ConvertRecord-Prozessor verwendet werden.

Als abschließender Schritt zur Bearbeitung muss, ähnlich wie bei der Verarbeitung der BPC-Forms Daten, die JSON-Struktur angepasst werden, damit die Daten an den Prozessmonitor weitergeleitet werden können. Hierfür wird erneut der JSONataTransformJSON-Prozessor genutzt, wobei die folgende Datenstruktur verwendet werden kann:

Mit diesem abschließenden Schritt sind sowohl die Daten aus dem BPC-Forms als auch vom Prozessstarter für die Weiterleitung an das BPC vorverarbeitet. Der angelegte Flow sollte an diesem Punkt wie folgt aussehen:

Den Kern der Informationsdarstellung stellt der Prozessmonitor dar, in dem die erstellten Kunden dargestellt werden sollen. Für diesen Zweck wird der PutBPCProcessLog-Prozessor verwendet, über den der Content eines FlowFiles weitergeleitet werden kann.

Zur Konfiguration des Prozessors wird zunächst der in Abschnitt 1.2 konfigurierte BPCController-Service ausgewählt, über den eine Verbindung zum BPC hergestellt wird.

Sobald der Controller ausgewählt wurde, stehen unter Choose BPC Logger die im BPC erstellten Logger zur Verfügung, die zum Schreiben in den Prozessmonitor genutzt werden können. Ein vorkonfigurierter Process-Logger befindet sich am Anfang des Tutorials. Falls die eigene Konfiguration des Loggers gewünscht ist, befindet sich in der BPC-Dokumentation eine Beschreibung der benötigten Schritte.

Bei der Angabe Input Type kann zusätzlich spezifiziert werden, welche Daten an das BPC gesendet werden sollen. Für diesen Zweck könnte die BPC Entries JSON-Property verwendet werden, oder der Content eines FlowFiles. Da in diesem Tutorial die generierten Daten im Content der FlowFiles enthalten sind, wird Letzteres für die Konfiguration genutzt.

Mit erfolgreicher Konfiguration sollten die Daten nach Durchführung des Prozessors im Prozessmonitor des BPCs angezeigt werden. Ein Beispiel für die abgeschlossene Konfiguration kann der folgenden Abbildung entnommen werden.

Um eine bessere Übersicht über die erstellten Kunden zu bieten, soll dokumentiert werden, wenn ein neuer Kunde generiert wurde. Für diesen Zweck können Audit-Logs verwendet werden, die eine Meldung im Audit Monitor des BPCs erzeugen.

Zum Erstellen von Audit-Logs kann der PutBPCAuditLogs-Prozessor verwendet werden.
Zur Konfiguration muss hierbei ebenfalls zunächst der BPCController-Service festgelegt werden, um eine Kommunikation mit dem BPC zu ermöglichen.

Zusätzlich muss angegeben werden, welche Log Level die generierten Meldungen haben sollen. Zur Auswahl stehen dabei DEBUG, INFO, WARNING und ERROR.

Um eine bessere Übersicht über die generierten Daten zu ermöglichen, soll zunächst eine INFO-Meldung hinzugefügt werden, wenn ein Nutzer einen neuen Kunden erstellt. Damit zusätzlich ersichtlich ist, welcher Nutzer den Kunden erstellt hat, kann der BPC Audit Originator definiert werden.

Dadurch, dass in Abschnitt 1.1 die Option Load the BPC Session ausgewählt wurde, befinden sich diese Information bereits in dem bpc.session-Attribut des FlowFiles. Über die NiFi Expression Language kann die Information zum Nutzer über einen JSONPath abgerufen werden. Als Originator wird daher an dieser Stelle ${bpc.session:jsonPath('$.loginName')} vermerkt, damit der Nutzer dynamisch ermittelt werden kann.

Unter den Punkten BPC Action und BPC Audit Description können im Anschluss zusätzliche Informationen definiert werden, die in der Meldung enthalten sein sollen. Eine beispielhafte Konfiguration ist in der folgenden Abbildung dargestellt.

Zusätzlich würde es sich anbieten, den Misserfolg des Prozess-Loggers in den Audit-Logs zu vermerken.
Hierfür kann ein zweiter PutBPCAuditLogs-Prozessor erstellt werden, der mit der failure-Relation an den PutBPCProcessLogger-Prozessor gebunden wird. Als Audit Level kann zudem WARNING oder ERROR ausgewählt werden, um zusätzlich auf den Misserfolg hinzudeuten.

Zusätzliche Informationen zum BPC Audit Logger befinden sich zudem in der BPC Dokumentation.

Zusätzlich zu den Audit-Logs ist es möglich, Notifications im BPC zu generieren, um alle anderen Nutzer direkt über die Erstellung eines neuen Kunden zu informieren.

Zum Erstellen von Notifications kann der PutBPCNotification-Prozessor verwendet werden.
Zur Konfiguration muss hierbei ebenfalls zunächst der BPC Controller-Service festgelegt werden, um eine Kommunikation mit dem BPC zu ermöglichen.

Als Nächstes kann die Properties als folgendes eingegeben werden, um der Inhalt, Typ und Empfänger der Notification zu setzen.

Um eine Anfrage vom BPC erfolgreich abzuschließen, muss eine Antwort vom IGUASU zurückgesandt werden. Ähnlich wie beim HandleHTTPResponse-Prozessor kann dabei ein HTTP Status Code und ein Response Header konfiguriert werden.

Sollten im Abschnitt 3.2 zwei PutBPCAuditLog-Prozessoren erstellt worden sein, kann über die ListenBPCResponder zusätzlich der Erfolg oder Misserfolg an das BPC kommuniziert werden.
Als Erfolg kann der HTTP Status 200 verwendet werden, während bei Misserfolg 400 gewählt wird. Über den Header kann zudem eine kurze Beschreibung hinzugefügt werden.

Mit erfolgreicher Konfiguration ist das BPC-Tutorial abgeschlossen und ermöglicht es, Kundendaten im BPC über Forms oder den Prozessstarter einzugeben, sodass diese im Prozessmonitor dokumentiert werden. Der fertige Datenfluss könnte wie in der folgenden Abbildung dargestellt aussehen.