Die BPC Version 3.5 wird nicht mehr gewartet.

Sollten Sie diese BPC Version nutzen, empfehlen wir Ihnen eine Migration auf eine aktuelle Version. Die Dokumentation zur neusten BPC Version finden Sie hier. Sollten Sie Fragen haben, wenden Sie sich bitte an unseren Support.

Log Service

Dieses Modul bietet unter anderem einen REST-Endpunkt, um Monitor-Daten entgegenzunehmen und diese nach Elasticsearch und optional in eine Datenbank zu schreiben. Die betreffenden Monitor-"Clients" werden sofort per Websocket-Event über neue Daten informiert.

Soll auch in eine Datenbank geschrieben werden, dann müssen die Datenbanktabellen bereits angelegt sein. Diese werden nicht automatisch angelegt und bei Änderungen der Datenstruktur auch nicht automatisch angepasst.
Wie bereits oben erwähnt, werden die Daten des Log-Service üblicherweise über den Monitor dargestellt. Dieser verwendet einen Process-Index (= parent Daten) sowie einen History-Index (= child Daten). Wenn nun aber keine History/Child-Daten übertragen werden sollen, dann diese im übertragenden JSON einfach nicht mit angeben ('childs'-Elemente) sowie in den Konfigurationen (siehe unten) alle 'child'-Elemente weglassen.

Konfigurationsparameter Log Service Modul

Name (Key) Gruppe Pflichtparameter Beschreibung

Basic_Username
(basic_auth_username)

basicauth

ja

Der Basic Auth Benutzername. Gelten für alle angelegten Instanzen und sind zwingend.

Default: virtimo

Basic_Password
(basic_auth_password)

basicauth

ja

Das zugehörige Passwort. Gelten für alle angelegten Instanzen und sind zwingend.

Default: berlin

Konfigurationsparameter je Log Service Komponente

Fett hervorgehobene Werte sind Pflichtparameter.

Name (Key) Gruppe Beschreibung

MaintenanceEnabled
(maintenanceEnabled)

config

Wenn etwas an der Datenbank oder dem Elasticsearch Index angepasst werden muss, dann kann der Endpunkt für diese Instanz in einen Wartungsmodus gesetzt werden. In diesem Fall bekommt der Aufrufer des Endpunktes einen HTTP Status 503 (Service Unavailable) zurückgeliefert.
Default: false

Keys
(keys)

config

Hier werden die Schlüsselfelder festgelegt. Beim Schreiben in die Datenbank werden diese für das DB-Update verwendet. Bei Elasticsearch zur Festlegung der Dokumenten-IDs. Sind mehrere Felder betroffen, dann müssen diese durch Kommata voneinander getrennt werden.

Default:

{
  "parent": {
    "idColumns": "PROCESSID"
  },
  "child": {
    "idColumns": "PROCESSID,CHILDID"
  }
}

Fields
(fields)

config

Hier können unter anderem Feinjustierungen an den Datentypen vorgenommen werden (Mapping für die Elasticsearch-Indexe).

Default 
{
  "parent": {
    "fieldname": {
      "type": "binary/text/timestamp/...",
      "skipES": false,
      "skipDB": false
    }
  },
  "child": {
    "fieldname": {
      "type": "binary/text/timestamp/...",
      "skipES": false,
      "skipDB": false
    }
  }
}
Beispiel 
{
  "parent": {},
  "child": {
    "datei": {
      "type": "binary",
      "skipES": true,
      "skipDB": false
    },
    "kommentar": {
      "type": "text"
    }
  }
}

type

  • binary = werden in Elasticsearch als 'binary' angelegt

  • text = werden in Elasticsearch wie bei der Replikation mit 'raw' und 'lowercase' angelegt

  • timestamp = werden in Elasticsearch als ‘date’ angelegt. Wird in der zu loggenden Nachricht anstatt eines UTC-Datums der Platzhalter 'SYSDATE' verwendet, dann setzt der Log-Service stattdessen den aktuellen Zeitstempel.

  • date:iso8601_millis = werden in Elasticsearch als ‘date’ mit dem Format ‘strict_date_optional_time||epoch_millis’ angelegt

  • integer = werden in Elasticsearch als ‘integer’ angelegt

  • long = werden in Elasticsearch als ‘long’ angelegt

  • float = werden in Elasticsearch als ‘float’ angelegt

  • double = werden in Elasticsearch als ‘double’ angelegt

  • boolean = werden in Elasticsearch als ‘boolean’ angelegt

In der Voreinstellung werden alle Felder nach Elasticsearch und in die Datenbank geschrieben. Sollen einzelne Felder nicht geschrieben werden, dann können diese hier festgelegt werden.

skipES

true = das Feld wird nicht nach Elasticsearch geschrieben

false = das Feld wird nach Elasticsearch geschrieben (Voreinstellung)

skipDB

true = das Feld wird nicht in die Datenbank geschrieben

false = das Feld wird in die Datenbank geschrieben (Voreinstellung)

ES_LoggingEnabled
(esLoggingEnabled)

elasticsearch

Nur wenn aktiviert, werden die Daten nach Elasticsearch geschrieben.
Default: true

ES_Index
(es)

elasticsearch

Festlegung, in welche Indexe die Parent/Child-Daten geschrieben werden sollen. Die Indexe werden automatisch angelegt. Dabei werden die festgelegten ‘Fields’-Typen berücksichtigt.

Der Name des Index muss komplett kleingeschrieben werden.

parent.index = Name des Zielindex mit den Parent/Haupt/Eltern-Daten

child.index = Name des Zielindex mit den Child/Detail/Kind-Daten

Optional:

backup.intervalInSeconds = Intervall in dem Backups/Snapshots angelegt werden (Angabe in Sekunden)

backup.keepBackupsDurationInSeconds = Backups älter als diese Angabe werden automatisch gelöscht (Angabe in Sekunden)

Beispiel:

{
  "parent": {
    "index": "of_test_main"
  },
  "child": {
    "index": "of_test_child"
  },
  "backup": {
    "intervalInSeconds": 86400,
    "keepBackupsDurationInSeconds": 2592000
  }
}

ES_Joins
(joins)

elasticsearch

Können verwendet werden, um die loggenden Dokumente automatisch mit zusätzlichen Daten anzureichern. Wenn z.B. in den zu loggenden Daten nur eine Partner-ID steht und noch der Name des Partners etc. im Monitor benötigt wird. Ist die gleiche Konfiguration wie bei den 'Lookup Joins' des Replikationsdienstes.

Beispiel:

[
  {
    "keyField": "partner",
    "lookupIndex": "lookup-partner",
    "lookupKeyField": "ID.raw",
    "resultFieldsPrefix": "partner_",
    "resultFieldsExcluded": [
      "ID",
      "LASTUPDATE"
    ]
  }
]

DB_RDMSLoggingEnabled
(rdmsLoggingEnabled)

rdms

Nur wenn aktiviert, werden die Daten in die Datenbank geschrieben.
Default: false

DB_RDMS
(rdms)

rdms

Festlegung, in welche Datenbanktabellen die Parent/Child-Daten geschrieben werden sollen. Die Datenbanktabellen müssen existieren und werden nicht automatisch angelegt.

rdmsDataSourceName = Name der Data Source (Datenbankverbindung) welche unter 'Core Services.data_rdms' bereits angelegt wurde

parent.table = Name der Zieltabelle mit den Parent/Haupt/Eltern-Daten

child.table = Name der Zieltabelle mit den Child/Detail/Kind-Daten

rdmsTimeZone (optional) = Ziel-Zeitzone für Datum-Felder (verwendet intern ZoneId)

Beispiel:

{
  "rdmsDataSourceName": "oracle-xe-vpma",
  "rdmsTimeZone": "America/Los_Angeles",
  "parent": {
    "table": "OF_TEST_MAIN"
  },
  "child": {
    "table": "OF_TEST_CHILD"
  }
}

Endpunkt / Schnittstelle

Es werden über eine DB-Transaktion zuerst die Datenbankdaten geschrieben (ist normalerweise fehleranfälliger) und erst danach die Daten nach Elasticsearch. Beim Schreiben in die Datenbank wird zuerst ein DB-Update (siehe keys-Einstellung) durchgeführt und wenn dies fehlschlägt, ein DB-Insert.

Methode Endpunkt

GET

/cxf/bpc-logservice/log/{instanz}

Beschreibung

Liefert die aktuelle Konfiguration der Log-Service-Instanz als JSON zurück.

  • {instanz} - dies kann entweder die ID oder ein eindeutiger Name der Modul Instanz sein

Rückantwort

  • 404 : Die Modul-Instanz wurde nicht gefunden

  • 401 : Die Basic Auth Credentials passen nicht

POST

/cxf/bpc-logservice/log/{instanz}

Beschreibung

Nimmt die zu loggenden Daten entgegen und schreibt diese nach Elasticsearch und/oder in die Datenbank.

  • {instanz} - dies kann entweder die ID oder ein eindeutiger Name der Modul Instanz sein.

  • async - Optional kann der Request-Parameter 'async=true' gesetzt werden, um das schreiben asynchron durchzuführen. Per Default wird der POST synchron abgearbeitet.

  • body - im Body müssen die zu loggenden Daten als JSON übergeben werden.

Rückantwort

  • 400 : Keins oder ein invalides JSON übergeben

  • 404 : Die Modul Instanz wurde nicht gefunden

  • 401 : Die Basic Auth Credentials passen nicht

  • 500 : Die Daten konnten nicht geschrieben werden

  • 503 : Maintenance Mode ist aktiv oder ES & DB sind nicht aktiviert

  • 200 : Die Daten wurden geschrieben

DELETE

/cxf/bpc-logservice/log/{instanz}/{parentId}

Beschreibung

Löscht Log Service Einträge und deren Childs aus Elasticsearch und der Datenbank.

  • {instanz} - dies kann entweder die ID oder ein eindeutiger Name der Modul Instanz sein

  • {parentId} - die ID des zu löschenden Eintrages, mehrere können Kommata separiert übergeben werden

Rückantwort

  • 404 : Die Modul Instanz wurde nicht gefunden

  • 401 : Die Basic Auth Credentials passen nicht

  • 500 : Die Daten konnten nicht gelöscht werden

  • 503 : Maintenance Mode ist aktiv oder ES & DB sind nicht aktiviert

  • 200 : Die Daten wurden gelöscht

DELETE

/cxf/bpc-logservice/log/{instanz}/{parentId}/{childId}

Beschreibung

Löscht einzelne Child-Einträge aus Elasticsearch und der Datenbank.

  • {instanz} - dies kann entweder die ID oder ein eindeutiger Name der Modul Instanz sein

  • {parentId} - die ID des Parents von welchem die Childs gelöscht werden sollen

  • {childId} - die ID des zu löschenden Child-Eintrages, mehrere können Kommata separiert übergeben werden

Rückantwort

  • 404 : Die Modul Instanz wurde nicht gefunden

  • 401 : Die Basic Auth Credentials passen nicht

  • 500 : Die Daten konnten nicht gelöscht werden

  • 503 : Maintenance Mode ist aktiv oder ES & DB sind nicht aktiviert

  • 200 : Die Daten wurden gelöscht

Response im Fehlerfall

Bei jedem Fehler (Status != 200) wird eine JSON mit folgendem exemplarischen Aufbau zurückgeliefert:

{
  "error": {
    "code": 301,
    "name": "MODULE_INSTANCE_NOT_FOUND",
    "message": "Did not found the instance 'of_test2' of the module 'logservice'.",
    "properties": {
      "instanceId": "of_test2",
      "moduleId": "logservice"
    }
  }
}

Die möglichen Error Codes

Error Code Error Name Info

1

UNEXPECTED

sollte nicht aufreten

20

MODULE_NOT_FOUND

das 'Log Service' Modul wurde nicht gefunden

21

MODULE_INSTANCE_NOT_FOUND

die 'Log Service' Instanz wurde nicht gefunden

10000

VALIDATION_MISSING_INPUT

Es wurden keine Daten zum "loggen" übergeben

10010

VALIDATION_INVALID_INPUT

Die übergebenen Daten sind kein gültiges JSON bzw. entsprechen nicht dem hier genannten Aufbau

20000

LOG_SERVICE_UNAUTHORIZED

Die Zugangsdaten stimmen nicht mit den hinterlegten überein (Log Service Modul Einstellung)

20001

LOG_SERVICE_MAINTENANCE

Der Log-Service befindet sich derzeit im Wartungsmodus bzw. das DB und ES Logging sind deaktiviert

20002

LOG_SERVICE_MISSING_SERVICE

Ein vom Log Service benötigter Dienst steht nicht zur Verfügung

20100

LOG_SERVICE_DB_LOGGING_FAILED

Beim DB Logging ist ein Fehler aufgetreten

20101

LOG_SERVICE_DB_DELETE_FAILED

Beim Löschen von DB Einträgen ist ein Fehler aufgetreten

20102

LOG_SERVICE_DB_WRONG_TABLE_NAME

Es wurde ein ungültiger Tabellenname angegeben

20103

LOG_SERVICE_DB_TABLE_MISSING

Die verwendete Datenbank-Tabelle konnte nicht gefunden werden

20104

LOG_SERVICE_DB_COLUMN_MISSING

Die zu verwendende Datenbank-Spalte existiert nicht

20105

LOG_SERVICE_DB_GET_METADATA_FAILED

Die Metadaten der Datenbank konnten nicht ausgelesen werden

20201

LOG_SERVICE_ES_FAILURE

Beim Zugriff auf Elasticsearch ist ein Fehler aufgetreten

20202

LOG_SERVICE_ES_FIELD_MISSING

Zum Bilden des Dokument-Schlüssels fehlen die erforderlichen Daten im zu loggenden Dokument

20203

LOG_SERVICE_ES_LOGGING_FAILED

Beim Schreiben der Daten nach Elasticsearch kam es zu einem Problem

20204

LOG_SERVICE_ES_DELETE_FAILED

Beim Löschen von Dokumenten aus dem Elasticsearch Index ist ein Fehler aufgetreten

POST : Aufbau der zur übergebenden JSON Nachricht

Eintrag erstellen/aktualisieren

{
    "entries": [
        {
            "parent": {
            	"feldname1": wert1,
            	"feldname2": wert2,
                ...
            },
            "childs": [
                {
                    "feldname1": wert1,
                    "feldname2": wert2,
                    "datei_binary": base64_3,
                    ...
                },
                {
                    "feldname1": wert3,
                    "feldname2": wert4,
                    "datei_binary": base64_5,
                    ...
                },
                ...
            ]
        },
        ...
    ]
}

Einzelne Felder aktualisieren (Partial Update)

{
    "entries": [
        {
            "partialUpdate": true,
            "parent": {
                "feldname1": wert1,
                "feldname2": wert2
            },
            ...
        },
        ...
    ]
}

Infos zum Partial Update

Das Partial Update bezieht sich auf den Parent Eintrag und die Child Einträge. Das bedeutet, wenn man ein Parent Eintrag updaten möchte, sollte man keinen "neuen" Child Log im gleichen JSON Dokument erstellen. Wenn man beim Update eines Parent Eintrages einen neuen Child Log erstellen möchte, sollte es in zwei Log-Service-Calls implementiert werden. Es könnte beispielsweise wie folgt aussehen (siehe INFOBLOCK 1 und 2):

INFOBLOCK 1 - Beispiel Parent
{
  "entries" : [ {
    "partialUpdate" : true,
    "parent" : {
      "ANFRAGESTATUS" : "Offen",
      "ANFRAGENUMMER" : "16",
      "ANFRAGEDATUM" : "2018-01-23T14:35:41.884+0200"
    }
  } ]
}
INFOBLOCK 2 - Beispiel Child
{
  "entries" : [ {
    "childs" : [ {
      "ANFRAGENUMMER" : "16",
      "PROZESSBESCHREIBUNG" : "Status wurde geändert auf Offen",
      "STATUS" : "OK",
      "TIMESTAMP" : "2018-01-23T14:35:41.927+0200",
      "CHILDID" : 309
    } ]
  } ]
}

Im Workflow sieht das dann so aus:

log service workflow

Werte der JSON Felder

Typ Wertebereich

Boolean

true / false ohne Hochkommata

Datum

als ISO-8601 mit Hochkommata, z.B. "2017-05-17T15:28:23.181Z". In der Datenbank das Feld als java.sql.Types.TIMESTAMP

Zahlen

Wert ohne Hochkommata

Binär

Base64 encoded. In der Datenbank als java.sql.Types.BLOB anlegen.

Text

Wert mit Hochkommata

Feldnamen Konvention

Über die Modulinstanz Einstellung fields (siehe unten) können die Datentypen pro Feld festgelegt werden. Dies ist für binary-Typen nicht unbedingt notwendig und kann auch über die Feldnamen Konvention FIELDNAME_binary (_binary als Postfix) durchgeführt werden.

Hintergrund: In Elasticsearch speichern wir Binärdaten Base64 encoded ab (so müssen diese auch im übergebenen JSON stehen). Diese wollen wir aber, wie bei der Replikation unter dem speziellen Typ 'attachment' ablegen. Da beides für Elasticsearch Strings sind, müssen wir dies wissen und ein spezielles Mapping durchführen.

Beispiel: Wenn wir ein Feld mit dem Namen 'datei' haben und die Namen frei vergeben können, dann kann daraus der Name 'datei_binary' werden und Elasticsearch legt die Daten als 'attachment' ab bzw. erstellt das Mapping dafür.

Beispiel Aufruf

curl -u virtimo:berlin -H "Content-Type: application/json" -XPOST 'localhost:8181/cxf/bpc-logservice/log/of_test' -d @logservice.json

Erläuterung:

Option Beschreibung

-u virtimo:berlin

Die Basic Auth Zugangsdaten. Festgelegt in den Einstellungen des 'Log-Service'-Moduls (siehe weiter unten)

-H "Content-Type: application/json"

Der Content-Type muss auf application/json gesetzt sein

-XPOST

HTTP POST ist erforderlich

localhost:8181/cxf/bpc-logservice/log/of_test

of_test ist ein eindeutiger Instanz-Name. Stattdessen kann auch die ID der Modul Instanz verwendet werden

-d @logservice.json

das zu postende JSON (siehe unten)

logservice.json (Eintrag erstellen/aktualisieren)

{
    "entries": [
        {
            "parent": {
                "processid": 40,
                "name": "hello world",
                "city": "Berlin",
                "lastupdate": "2017-05-17T15:28:23.181Z"
            },
            "childs": [
                {
                    "processid": 40,
                    "childid": 1,
                    "ersteller": "Oliver",
                    "kommentar": "Bild und langer Text",
                    "datei": "iVBORw0KGgoAAAANSUhEUgAAAAIAAAACAQMAAABIeJ9nAAAABlBMVEUAAAD///+l2Z/dAAAADElEQVQIHWNwYGgAAAFEAMGoX3f9AAAAAElFTkSuQmCC",
                    "langertext": "Dieser Text ist aber ziemlich .................... lang. :-)",
                    "lastupdate": "2017-05-17T15:28:23.181Z"
                }
            ]
        }
    ]
}

logservice.json (Einzelne Felder aktualisieren (Partial Update))

{
    "entries": [
        {
            "parent": {
                "processid": 40,
                "name": "hello world (aktualisiert)",
                "lastupdate": "2018-01-02T14:45:18.421Z"
            }
        }
    ]
}

Konfigurationsparameter

Modul

Am Modul werden die Basic Auth Credentials des Endpunktes festgelegt. Diese gelten für alle angelegten Instanzen und sind zwingend.

log service settings module

Modulinstanz

Die empfangbaren Daten kommen als "Paket" mit den Haupt- (parent) und Detaildaten (child).

log service settings instance

Keywords:
Press Esc to exit full screen
Modal image placeholder
Press Esc to exit full screen