BPC Anbindung Tutorial

Um eine Verbindung mit dem BPC aus IGUASU zu ermöglichen werden zwei Services benötigt.

Damit BPC und IGUASU Nachrichten austauschen können muss auch das BPC dafür konfiguriert werden.

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. Dabei wird der Prozessor als Startpunkt eines Flows verwendet.

Um den Prozessor zu verwenden, müssen zuerst einige Properties gesetzt werden:

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.

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. Die Submit url muss auf die zuvor erstellte HttpProxy-Backendconnection verweisen, dies Erfolgt über einen Aufruf der http-proxy API. In diesem Fall ist die Entsprechende submitUrl also:

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 die Success-Relation des ListenBPCFlowStarters in einen Funnel geleitet wird.

Die zweite Möglichkeit der Datenweiterleitung an IGUASU, die im Rahmen dieses Tutorials beschrieben wird, ist der Eingabe über einen Prozessstarter. Dafür muss zuerst ein entsprechender Process-Starter im BPC konfiguriert werden. Diese erfolgt nach der Process Starter-Anleitung in der BPC-Dokumentation. Dabei müssen im der Process Monitoring Konfiguration im BPC folgende Attribute gesetzt sein:

In diesem Fall wird ein zweiter ListenBPCFlowStarter erstellt und wie zuvor beschrieben, mit einem anderen identifier konfiguriert.

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.

Aus dem BPC Process Monitoring können außerdem auch Eintrags-spezifische Prozess Aktionen ausgelöst werden und so Nachrichten an IGUASU gesendet werden. Damit diese Aktionen im IGUASU empfangen werden können müssen wiederum einige Attribute im Process Monitoring gesetzt sein:

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 Replacement Strategy Always Replace und als Evaluation Mode Entire Text 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:

Um Informationen aus IGUASU im BPC Process Monitor darstellen zu können müssen diese mittels des PutBPCProcessLog Processors an einen Logservice im BPC gesendet werden.

In der Konfiguration des Prozessors wird zunächst der zuvor konfigurierte HybridRESTClientController ausgewählt, über den eine Verbindung zum BPC hergestellt wird. Des weiteren sollte im BPC bereits ein Logservice erstellt worden sein.

Ist der Controller und der Logservice richtig konfiguriert, stehen unter BPC Logger die im BPC erstellten Logger zur Verfügung.

Durch die Property 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 HybridRESTClientController-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 bei der Konfiguration des ListenBPCFlowStarters 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.

Um eine Notification an das BPC zu senden 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.

Der Prozessor kann dann entsprechend des Use-Cases konfiguriert werden. Hierbei gibt es folgende Konfigurations-Optionen:

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 zuvor 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.

Der BPCRecordSink-Service wird wie der PutBPCProcessLog mit einem BPC Controller, um eine Verbindung mit dem BPC aufzubauen, sowie durch die Auswahl eines BPC Loggers konfiguriert.

Anders als beim PutBPCProcessLog Prozessor müssen die zu sendenden Daten nicht in die passende JSON-Struktur für den BPC Logging Service umgewandelt werden, sondern werden vom BPCRecordSink automatisch konvertiert. Dafür muss nur der Parent Key angegeben werden, der mit den Konfigurationen des BPC Logging Services übereinstimmen muss.

Zusätzlich gibt es die Möglichkeit, jedem geloggtem Record im BPC ein Datum und Zeitstempel zu geben. Dafür muss die SYSDATE field name-Property im BPCRecordSinkService mit einem entsprechendem Feldnamen konfiguriert werden, unter dem dann ein Zeitstempel mitgeschickt wird. Danach muss die Fields Configuration im BPC Log Service mit dem timestamp-Type für das Feld konfiguriert werden.