Logeinträge mit Functional Logging erstellen

Zum Protokollieren der fachlichen Daten wird die Methode Functional Logging genutzt. Diese bietet eine vordefinierte XML-Struktur im Modul BPC_Assign_hook im Workflow BPC_299_PM_Configuration, welche die Tabellenstruktur für die protokollierten Daten in der Logging-Datenbank und die Einstellungen des Process Monitors im Portal festlegt. Der Workflow Connector BPC_PM_doFunctionalLogging (im Workflow BPC_PM_LogDB_Administration) greift bei der Weitergabe von protokollierten Daten an die Workflows des INUBIT Process Monitor auf die Logging-Konfiguration im Modul BPC_Assign_hook zurück.

Grundprinzip

Grundsätzlich nutzen Sie für das Functional Logging die im Modul BPC_Assign_hook im Workflow BPC_PM_Configuration vordefinierte Datenbankstruktur mit den entsprechenden Spalten.

Wenn Sie zusätzlich zu den vordefinierten Informationen weitere protokollieren möchten, müssen Sie die vordefinierte Datenbankstruktur um geeignete Spalten erweitern. Die Spalten definieren Sie im Workflow BPC_PM_Configuration in der XSLT-Variable des Moduls BPC_Assign_hook, das zu Ihrem Process Monitor-Grid gehört. Die neuen Tabellenspalten werden erzeugt, wenn Sie im Workflow BPC_PM_LogDB_Administration das Modul BPC_PM_startWFHere im Rahmen create log table zum Erzeugen der Datenbanktabellen starten.

Siehe XML-Konfiguration für das Logging zentral verwalten

Wenn Sie die Datenbankstruktur geändert haben, indem Sie z.B. Spaltendefinitionen in der XSLT-Variablen des Moduls BPC_Assign_hook gelöscht haben, müssen Sie dafür sorgen, dass diese Änderungen in die Logging-Datenbank übernommen werden. Dazu starten Sie im Workflow BPC_PM_LogDB_Administration zuerst das Modul BPC_PM_startWFHere im Rahmen delete log table und anschließend das Modul BPC_PM_startWFHere im Rahmen create log table.

Prinzipielles Vorgehen

Beim Functional Logging schreiben Sie die zu protokollierenden Informationen in eine vorgegebene XML-Struktur. Mit dieser XML-Struktur füllen Sie die Variable logEntry im Variablen-Mapping an dem Workflow Connector, der Ihren fachlichen Technical Workflow mit den Workflows des INUBIT Process Monitor verbindet. Auf Basis der übergebenen logEntry-Variablen erstellt der INUBIT Process Monitor einen Log-Eintrag in der Logging-Datenbank.

Sie können beim Functional Logging die vorgegebene XML-Struktur im Modul BPC_Assign_hook nach Ihren Wünschen erweitern: So können Sie z.B. nicht nur zusätzliche Informationen in die Logging-Datenbank schreiben und im Process Monitor-Grid anzeigen lassen, sondern auch bei jeder Ausführung eines Workflow Connectors, der einen Logeintrag schreibt, mehrere Child-Logeinträge erzeugen lassen.

Beispiel-Logging

Um beispielhaft Logeinträge zu erzeugen und sich so die vorkonfigurierte Struktur der Tabellenspalten im Portal anzeigen zu lassen, starten Sie im mitgelieferten Workflow BPC_PM_LogDB_Administration das Modul BPC_PM_startWFHere im Rahmen create test data. Sie sehen im BPC Portal im Process Monitor die erzeugten Logeinträge im Grid.

Functional Logging einbinden

Um fachliche Daten aus Ihrer konkreten Anwendung heraus mit dem INUBIT Process Monitor zu protokollieren, müssen Sie das Functional Logging in Ihr System einbinden:

So gehen Sie vor

Fügen Sie den Workflow Connector BPC_PM_doFunctionalLogging an fachlich relevanter Stelle in Ihre Workflows ein.
Stellen Sie sicher, dass Ihr angebundenes System eine Eingangsnachricht für den Workflow Connector liefert, die der Struktur der Tabellenspalten im Modul BPC_Assign_hook entspricht.
Fügen Sie dem Workflow Connector eine XSLT-Variable analog zu der am Modul BPC_Assign_hook im Workflow BPC_299_PM_Configuration hinzu.

Stellen Sie sicher, dass im eingebauten Workflow Connector BPC_PM_doFunctionalLogging die Variable database korrekt gesetzt ist.
Erstellen Sie im Stylesheet der XSLT-Variablen eine Ihren Anforderungen entsprechende logEntry-Struktur mit den notwendigen XML-Elementen für die Eingangsnachricht ähnlich der folgenden:

XML-Elemente für das Functional Logging

Alle untenstehenden Elemente sind standardmäßig in der vordefinierten XML-Struktur der Logging-Konfiguration der XSLT-Quell-Variable im Module BPC_Assign_hook im Workflow BPC_299_PM_Configuration. enthalten. Aus der XML-Struktur werden die Tabellenspalten in der Struktur der Logging-Datenbank und die Spalten im Grid des Process Monitors generiert.

Ändern Sie die Namen der vordefinierten Elemente nicht!

Elemente für Parent-Logeinträge

Element	Erläuterung
Status	Aktueller Status des Prozesses. Sie können die Darstellung und die Bezeichner der Status ändern. Siehe Statusbezeichner und Darstellung der Status im Grid ändern
ProcessID	Pflichtangabe! Dieses XML-Element muss enthalten sein, da sonst kein Logeintrag erzeugt wird.
Timestamp	Pflichtangabe! Im Auslieferungszustand muss dieses Element mit einem Wert belegt werden, weil der Zeitstempel das initiale Sortierkriterium für die Anzeige der Statuswerte im Dashboard ist. Zeitpunkt, zu dem der Logeintrag erstellt wurde (z.B. Eingangsdatum). Die Zeitangabe wird in folgendem Format erwartet: Beispiel: 2011-02-10 00:00:02 Sie können das initiale Sortierkriterium ändern. Siehe Initiale Sortierung der Logeinträge anpassen
LastUpdate	Weitere Datumsspalte neben Timestamp, die das Aktualisierungsdatum des Logschritts enthält. Sie wird bei jedem Logschritt aktualisiert. Wird nur bei Nutzung des Distributed-Logging-Features verwendet! Siehe Distributed Logging nutzen
Process	Name des fachlichen Prozesses.
Text	Beliebiger Text.
action_test	Legt benutzerdefinierte Aktionen in einer eigenen Spalte fest, die Sie zu einem Logeintrag anbieten können, z.B. um einen Prozess neu zu starten. Siehe Aktionen konfigurieren Mehrere Aktions-Buttons zusammenfassen – MultiAction-Button
remoteFilterTest	Bietet mit einem Button die Möglichkeit, Daten in einem anderen Process Monitor-Grid dynamisch zu filtern. Siehe Daten in anderen Process Monitoren dynamisch filtern
Checkbox	Legt eine Checkbox an. Diese wird im Process Monitor-Grid mit einem Häkchen markiert angezeigt, wenn in der Datenbanktabelle ein Wert dafür existiert. Siehe Spalten mit Checkboxen anzeigen
Format	Format der Nachricht, die im Prozess verarbeitet wird.
Reffile	Datei, die als Referenz zum Logeintrag gespeichert wird. Siehe Referenzdateien zu Logeinträgen anzeigen
ReffileLastUpdate	Datumsspalte wird mit dem gleichen Wert des Aktualisierungsdatums gefüllt, der auch für das LastUpdate-Element gesetzt wird. Wird nur bei Nutzung des Distributed-Logging-Features verwendet! Siehe Distributed Logging nutzen
MimeType	Mimetype der Referenz-Datei. Siehe Referenzdateien zu Logeinträgen anzeigen
Reference	Datenbank-ID Siehe Referenzdateien zu Logeinträgen anzeigen

Element

Erläuterung

Status

Aktueller Status des Prozesses.

Sie können die Darstellung und die Bezeichner der Status ändern.

Siehe Statusbezeichner und Darstellung der Status im Grid ändern

ProcessID

Pflichtangabe! Dieses XML-Element muss enthalten sein, da sonst kein Logeintrag erzeugt wird.

Timestamp

Pflichtangabe! Im Auslieferungszustand muss dieses Element mit einem Wert belegt werden, weil der Zeitstempel das initiale Sortierkriterium für die Anzeige der Statuswerte im Dashboard ist.

Zeitpunkt, zu dem der Logeintrag erstellt wurde (z.B. Eingangsdatum).

Die Zeitangabe wird in folgendem Format erwartet:

Beispiel: 2011-02-10 00:00:02 Sie können das initiale Sortierkriterium ändern.

Siehe Initiale Sortierung der Logeinträge anpassen

LastUpdate

Weitere Datumsspalte neben Timestamp, die das Aktualisierungsdatum des Logschritts enthält. Sie wird bei jedem Logschritt aktualisiert.

Wird nur bei Nutzung des Distributed-Logging-Features verwendet!

Siehe Distributed Logging nutzen

Process

Name des fachlichen Prozesses.

Text

Beliebiger Text.

action_test

Legt benutzerdefinierte Aktionen in einer eigenen Spalte fest, die Sie zu einem Logeintrag anbieten können, z.B. um einen Prozess neu zu starten.

Siehe

remoteFilterTest

Bietet mit einem Button die Möglichkeit, Daten in einem anderen Process Monitor-Grid dynamisch zu filtern.

Siehe Daten in anderen Process Monitoren dynamisch filtern

Checkbox

Legt eine Checkbox an. Diese wird im Process Monitor-Grid mit einem Häkchen markiert angezeigt, wenn in der Datenbanktabelle ein Wert dafür existiert.

Siehe Spalten mit Checkboxen anzeigen

Format

Format der Nachricht, die im Prozess verarbeitet wird.

Reffile

Datei, die als Referenz zum Logeintrag gespeichert wird.

Siehe Referenzdateien zu Logeinträgen anzeigen

ReffileLastUpdate

Datumsspalte wird mit dem gleichen Wert des Aktualisierungsdatums gefüllt, der auch für das LastUpdate-Element gesetzt wird. Wird nur bei Nutzung des Distributed-Logging-Features verwendet!

Siehe Distributed Logging nutzen

MimeType

Mimetype der Referenz-Datei.

Siehe Referenzdateien zu Logeinträgen anzeigen

Reference

Datenbank-ID

Siehe Referenzdateien zu Logeinträgen anzeigen

Elemente für Child-Logeinträge

Element	Erläuterung
ProcessID	ProcessID des Parent-Logeintrags.
Status	Sie können die Darstellung und die Bezeichner der Status ändern. Siehe Statusbezeichner und Darstellung der Status im Grid ändern
ChildID	Wird generiert, falls leer.
Timestamp	Pflichtangabe! Im Auslieferungszustand muss dieses Element mit einem Wert belegt werden, weil der Zeitstempel das initiale Sortierkriterium für die Anzeige der Statuswerte im Dashboard ist. Zeitpunkt, zu dem der Logeintrag erstellt wurde. Die Zeitangabe wird in folgendem Format erwartet: Beispiel: 2011-02-10 00:00:02 Sie können das initiale Sortierkriterium ändern. Siehe Initiale Sortierung der Logeinträge anpassen
Text	Beliebiger Text.
Reference	Absoluter Pfad zu der Referenzdatei oder Datenbank-ID. Siehe Referenzdateien zu Logeinträgen anzeigen
MimeType	Mimetype der Referenz-Datei Siehe Referenzdateien zu Logeinträgen anzeigen
Reffile	Datei, die als Referenz zum Logeintrag gespeichert wird. Siehe Referenzdateien zu Logeinträgen anzeigen

Element

Erläuterung

ProcessID

ProcessID des Parent-Logeintrags.

Status

Sie können die Darstellung und die Bezeichner der Status ändern.

Siehe Statusbezeichner und Darstellung der Status im Grid ändern

ChildID

Wird generiert, falls leer.

Timestamp

Pflichtangabe! Im Auslieferungszustand muss dieses Element mit einem Wert belegt werden, weil der Zeitstempel das initiale Sortierkriterium für die Anzeige der Statuswerte im Dashboard ist.

Zeitpunkt, zu dem der Logeintrag erstellt wurde.

Die Zeitangabe wird in folgendem Format erwartet:

Beispiel: 2011-02-10 00:00:02 Sie können das initiale Sortierkriterium ändern.

Siehe Initiale Sortierung der Logeinträge anpassen

Text

Beliebiger Text.

Reference

Absoluter Pfad zu der Referenzdatei oder Datenbank-ID.

Siehe Referenzdateien zu Logeinträgen anzeigen

MimeType

Mimetype der Referenz-Datei

Siehe Referenzdateien zu Logeinträgen anzeigen

Reffile

Datei, die als Referenz zum Logeintrag gespeichert wird.

Siehe Referenzdateien zu Logeinträgen anzeigen

Funktionen der mitgelieferten Technical Workflows

Die folgende Tabelle erläutert die Funktionen der mitgelieferten Technical Workflows. Workflows, an denen in der Workbench ein Schloss-Symbol angezeigt wird, sind verschlüsselt und können nicht bearbeitet werden. In der Tabelle sind diese Workflows als nicht-editier bar gekennzeichnet.

Editierbar Workflow Funktion

Editierbar	Workflow	Funktion
	BPC_PM_Configuration	In diesem Workflow wird ein Process Monitor-Grid konfiguriert. Siehe Logging-Datenbank und -Konfiguration zentral verwalten
	BPC_PM_HTTP	Bietet eine Übersicht über alle Konnektoren, die konfiguriert werden können, um mehrere Instanzen des Process Monitors parallel zu betreiben.
	BPC_PM_Insert_Log	Bereitet das Speichern der Logeinträge in die Datenbank vor, indem er aus den XML-Elementen `logEntry` SQL-Statements erzeugt. Dann wird der Workflow `BPC_PM_Query_LogDB` aufgerufen.
	BPC_PM_LogDB_Administration	Erzeugt die benötigten Datenbanktabellen und Test-Logeinträge. Siehe Logging-Datenbank und -Konfiguration zentral verwalten
	BPC_PM_LogMonitor_Action_AJAX	In diesem Workflow konfigurieren Sie die gewünschten Aktionen der Action-Buttons, die im Grid angelegt werden können. Siehe Aktionen konfigurieren
	BPC_PM_Process Monitor_Init_Grid	Dient zum Initiieren und Konfigurieren des Process Monitor. Er konfiguriert die Web-Applikation, die im BPC Portal angezeigt wird, und ruft die Workflows `BPC_PM_Configuration` und `BPC_PM_LogMonitor_Grid` auf.
	BPC_PM_Query_LogDB	Realisiert den Zugriff auf die Datenbank. Die SQL-Statements werden an den Database Connector übergeben. Dieser holt sich die nötigen Verbindungsdaten aus dem Systemdiagramm und schreibt die Daten in die Datenbank.
	BPC_PM_Show_Reference	Lädt Nachrichten zu Logeinträgen. Siehe Referenzdateien zu Logeinträgen anzeigen

BPC_PM_Configuration

In diesem Workflow wird ein Process Monitor-Grid konfiguriert.

Siehe Logging-Datenbank und -Konfiguration zentral verwalten

BPC_PM_HTTP

Bietet eine Übersicht über alle Konnektoren, die konfiguriert werden können, um mehrere Instanzen des Process Monitors parallel zu betreiben.

BPC_PM_Insert_Log

Bereitet das Speichern der Logeinträge in die Datenbank vor, indem er aus den XML-Elementen logEntry SQL-Statements erzeugt. Dann wird der Workflow BPC_PM_Query_LogDB aufgerufen.

BPC_PM_LogDB_Administration

Erzeugt die benötigten Datenbanktabellen und Test-Logeinträge.

Siehe Logging-Datenbank und -Konfiguration zentral verwalten

BPC_PM_LogMonitor_Action_AJAX

In diesem Workflow konfigurieren Sie die gewünschten Aktionen der Action-Buttons, die im Grid angelegt werden können.

Siehe Aktionen konfigurieren

BPC_PM_Process Monitor_Init_Grid

Dient zum Initiieren und Konfigurieren des Process Monitor. Er konfiguriert die Web-Applikation, die im BPC Portal angezeigt wird, und ruft die Workflows BPC_PM_Configuration und BPC_PM_LogMonitor_Grid auf.

BPC_PM_Query_LogDB

Realisiert den Zugriff auf die Datenbank. Die SQL-Statements werden an den Database Connector übergeben. Dieser holt sich die nötigen Verbindungsdaten aus dem Systemdiagramm und schreibt die Daten in die Datenbank.

BPC_PM_Show_Reference

Lädt Nachrichten zu Logeinträgen.

Siehe Referenzdateien zu Logeinträgen anzeigen

Distributed Logging nutzen

Neben dem standardmäßig verfügbaren Logging, können Sie optional ein weiteres Verfahren, das Distributed Logging nutzen.

Verwendung

Sie nutzen das Distributed Logging, wenn Sie aus Performancegründen das Logging parallel und/oder asynchron nutzen.

Paralleles Loggen: Ein System oder mehrere Systeme loggen unabhängig voneinander in die Datenbank des Process Monitors.
Asynchrones Loggen: Das Logging wird asynchron ausgeführt, damit eine langsame Datenbankverbindung nicht die Nachrichtenverarbeitung ausbremst bzw. im Fehlerfall stoppt.

Um zu verhindern, dass sich Logschritte bzw. Datenbank-Statements überholen und z.B. ältere Logeinträge einer langsamen Datenbankverbindung neue Logeinträge, die über eine schnelle Verbindung kommen, überschreiben, aktivieren Sie Distributed Logging. Um das Verfahren zu nutzen, müssen Sie in Ihrer logEntry-Struktur das entsprechende Attribut neu hinzufügen und bestimmte Regeln zum Übergeben der Logschritte einhalten bzw. umsetzen.

Voraussetzungen

Wenn Sie von verschiedenen Systemen aus in den gleichen Process Monitor loggen wollen, müssen die Uhren der Systeme synchronisiert sein.
Der loggende Prozess muss synchron sein, d.h., Sie loggen nicht aus verschiedenen asynchronen Prozessen zur gleichen ProcessID.

Distributed Logging aktivieren

Um das Distributed Logging-Verfahren zu nutzen, müssen Sie Ihre logEntry-Struktur anpassen.

So gehen Sie vor

Machen Sie Ihre logEntry-Struktur zur Bearbeitung verfügbar und nutzen Sie dafür ggf. einen XSLT Converter.
Fügen Sie in die bestehende Struktur ein neues Attribut distributedLogging an das Root-Element logEntry ein.
Setzen Sie den Wert des neuen Attributs auf true.

Falls das Attribut distributedLogging nicht bzw. auf false gesetzt ist, ist das Distributed Logging nicht aktiviert.

Regeln im LogEntry umsetzen

Zur Übergabe der Logschritte müssen Sie bestimmte Regeln in Ihrer logEntry-Struktur einhalten, um sicherzustellen

dass sich beim Loggen der Log-Einträge Datenbank-Statements nicht überholen bzw. überschreiben.
dass beim Loggen der Child-Logeinträge alle übernommen und später in der richtigen Reihenfolge wiedergegeben werden.
Dateien zu Log-Einträgen (über das Reffile-Element) nicht unnötig mitgeführt werden.

Ziel ist es, dass in einem neueren logEntry alle nötigen Informationen des vorherigen enthalten sind.

So gehen Sie vor

Passen Sie die logEntry-Struktur in Ihren fachlichen Workflows gemäß folgenden Regeln an:

LastUpdate-Element Stellen Sie sicher, dass das Element LastUpdate in der XSLT-Variable des Moduls BPC_Assign_hook im Workflow BPC_299_PM_Configuration zur Erzeugung der Datumsspalte, in der das letzte Aktualisierungs-/ Bearbeitungsdatum des Eintrags erfasst wird, gesetzt ist.
Log-Eintrag
- Übernehmen Sie für jeden Logschritt das logEntry des vorherigen Schrittes.
- Fügen Sie im nachfolgenden Logschritt neue Elemente dem logEntry hinzu oder aktualisieren Sie relevante Elemente des logEntry. Belassen Sie alle anderen Elemente im logEntry.
- Setzen Sie bei jedem Logschritt den Zeitstempel von LastUpdate neu.
- Wenn Sie explizit den Wert einer Spalte auf Null setzen wollen, fügen Sie dem entsprechenden Element im logEntry das Attribut delete mit dem Wert true hinzu.
Childlog-Eintrag

Setzen Sie im nachfolgenden Logschritt alle Werte der Childlog-Einträge, insbesondere das Timestamp-Element, da es für die spätere Sortierreihenfolge der Child-Einträge in der Anzeige des Process Monitors verwendet wird.
Reffile-Datei

Best Practice: Falls bei Log-Einträgen Dateien als Reffile-Elemente mitgeführt werden, müssen Sie diese aus Performancegründen pro Logschritt setzen und anschließend wieder löschen.

Einstellungen für Logging von Child-Einträgen definieren

Child-ID für Anzeige im Grid ausblenden

Damit die Child-Logeinträge im Grid nur gemäß der Sortierung auf Basis des Zeitstempels sichtbar sind und nicht die Reihenfolge der Datenbank-Speicherung (childid), muss die Spalte mit den Child-IDs für die Anzeige im Grid ausgeblendet werden.

So gehen Sie vor

Öffnen Sie die XSLT-Variable des Moduls BPC_Assign_hook im Workflow BPC_299_PM_Configuration zum Bearbeiten.
Fügen Sie dem childid-Element, welches in seiner Darstellung als Spalte im Grid ausgeblendet werden soll, das Attribut hidden=true hinzu:
Speichern Sie die Änderungen und publizieren Sie den Workflow.

Asynchrone Ausführung definieren

Um die gewünschte asynchrone Ausführung zu definieren, müssen Sie den Workflow Connector BPC_PM_doFunctionalLogging, der die Funktionalität des Process Monitors umsetzt und den Sie an fachlich relevanter Stelle in Ihre Workflows einbinden, neu anlegen und konfigurieren.

Die parallele Ausführung des Workflows BPC_PM_Insert_Log ist bereits im Auslieferungszustand gesetzt.

So gehen Sie vor

Legen Sie einen neuen Workflow Connector analog zu BPC_PM_doFunctionalLogging (im Workflow BPC_PM_LogDB_Administration) an.
Benennen Sie den Workflow Connector und lassen Sie sich von dem Assistenten durch die Erzeugung und Konfiguration des neuen Workflow Connectors führen. Achten Sie dabei besonders auf folgende Einstellungen:
- Setzen Sie den Kommunikationsmodus auf Asynchron, damit der aufrufende Workflow nach dem Aufruf des Workflow Connectors unmittelbar fortgesetzt wird.
- Markieren Sie die Option Workflow mit neuer Prozess-ID ausführen, damit jeder Prozess, der beim Aufruf des Subworkflows entsteht, eine neue Prozess-ID erhält.
- Wählen Sie als Ziel-Workflow BPC_PM_Insert_Log.
- Wählen Sie als Ziel-Modul das zweite Assign-Modul BPC_PM_Assign als Einstiegspunkt für das Logging.
  
  Für ausführliche Informationen zum Workflow Connector siehe:
Beenden Sie die Konfiguration des Workflow Connectors mit Fertig stellen.
Publizieren Sie den Workflow Connector.