Log Service

Dieses Modul bietet unter anderem einen REST-Endpunkt, um Monitor-Daten entgegenzunehmen und diese nach OpenSearch 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.

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

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 geben Sie diese im übertragenden JSON einfach nicht mit an ('child'-Elemente) und lassen in den Konfigurationen (siehe unten) alle 'child'-Elemente weg.

Konfigurationsparameter Log Service Modul

Pflichtparameter sind fett hervorgehoben.

Setting (Key) Gruppe Beschreibung

Security_ClientCertificateAuthMandatory
(clientCertificateAuthMandatory)

security

Legt fest, ob die Log-Service-Endpunkte nur per Client Certificate Authentication aufgerufen werden können.
Default: false

OpenSearch_DataCountLimit
(openSearchDataCountLimit)

opensearch

Maximale Anzahl Dokumente die abgefragt werden können.
Default: 100000

OpenSearch_DataViewLimit
(openSearchDataViewLimit)

opensearch

Bis zu diesem Wert soll OpenSearch genaue Angaben über die Anzahl der Dokumente (trackTotalHitsUpTo) zurückliefern.
Default: 100000

Konfigurationsparameter je Log Service Komponente

Fett hervorgehobene Werte sind Pflichtparameter.

Setting (Key) Gruppe Beschreibung

Enabled
(enabled)

config

Wenn etwas an der Datenbank oder dem OpenSearch-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: true

ParentKeyFields
(parentKeyFields)

ChildKeyFields
(childKeyFields)

config

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

Default: PROCESSID bzw. PROCESSID, CHILDID

ParentFields
(parentFields)

ChildFields
(childFields)

config

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

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

type

  • binary = werden in OpenSearch als 'binary' angelegt

  • file-storage = werden in OpenSearch und in der Datenbank als BPC-File-Storage-URI hinterlegt. (typ: 'text') Ist die Option filestorageUploadEnabled aktiviert, kann man auch Base64-kodierte Dateien übertragen, die dann im File-Storage abgelegt werden und als BPC-File-Storage-URI nach OpenSearch und in die Datenbank geschrieben werden. Siehe auch File-Storage im Log-Service.

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

  • timestamp = werden in OpenSearch 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 OpenSearch als ‘date’ mit dem Format ‘strict_date_optional_time||epoch_millis’ angelegt

  • integer = werden in OpenSearch als ‘integer’ angelegt

  • long = werden in OpenSearch als ‘long’ angelegt

  • float = werden in OpenSearch als ‘float’ angelegt

  • double = werden in OpenSearch als ‘double’ angelegt

  • boolean = werden in OpenSearch als ‘boolean’ angelegt

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

skipOS

true = das Feld wird nicht nach OpenSearch geschrieben

false = das Feld wird nach OpenSearch geschrieben (Voreinstellung)

skipDB

true = das Feld wird nicht in die Datenbank geschrieben

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

JsonSchemaValidation
(jsonSchemaValidation)

config

Festlegung, ob bei den zu schreibenden Daten eine JSON Schema Validierung durchgeführt werden soll. Das JSON Schema wird dabei anhand der definierten Keys und Fields generiert.

  • off = es wird keine Validierung durchgeführt

  • regular = zusätzliche Felder sind erlaubt und nicht nur die unter Keys und Fields definierten

  • strict = nur die unter Keys und Fields definierten Felder sind zulässig

    Default: off

Über den Log Service Endpunkt kann das JSON Schema der Log Service Komponente geladen werden.

Enable File Storage Upload
(filestorageUploadEnabled)

config

Wenn diese Option aktiviert ist, können Felder vom Typ file-storage als Base64-kodierte Datei übertragen werden. Diese wird dann automatisch im File-Storage abgelegt.

Default: false

File Storage Backend Connection
(filestorageBackendConnection)

config

Die File-Storage-Backend-Connection, die beim Ablegen von Dateien im File-Storage genutzt wird.

File Storage Bucket
(filestorageBucket)

config

Der Bucket-Name, um Dateien im File-Storage abzulegen.

Read Restriction
(filestorageReadRestriction)

Write Restriction
(filestorageWriteRestriction)

config

Die Lese- bzw. Schreibbeschränkung, die beim Ablegen von Dateien im File-Storage genutzt wird.

Es muss entweder ein Benutzer, oder mindestens eine Rolle, Organisation oder ein Recht festgelegt werden.

Beispiel mit einem Nutzer 
{
  "user": "file_admin"
}
Beispiel mit Rollen, Organisationen und Rechten 
{
    "roles": ["bpcadmin"],
    "organisations": [],
    "rights": ["LOG_SERVICE_FILE_EXAMPLE_RIGHT"]
}

OpenSearch_LoggingEnabled
(openSearchLoggingEnabled)

opensearch

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

OpenSearch_ParentIndex
(openSearchParentIndex)

opensearch

Festlegung, in welchen Index die Parent/Haupt/Eltern-Daten geschrieben werden sollen. Der Index wird automatisch angelegt. Dabei werden die festgelegten ‘Fields’-Typen berücksichtigt.

Der Name des Index muss komplett kleingeschrieben werden.

OpenSearch_ChildIndex
(openSearchChildIndex)

opensearch

Festlegung, in welchen Index die Child/Detail/Kind-Daten geschrieben werden sollen. Der Index wird automatisch angelegt. Dabei werden die festgelegten ‘Fields’-Typen berücksichtigt.

Der Name des Index muss komplett kleingeschrieben werden.

Joins
(joins)

config

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"
    ]
  }
]

RDMS_LoggingEnabled
(rdmsLoggingEnabled)

rdms

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

RDMS_DataSourceName
(rdmsDataSourceName)

rdms

Name der Data Source (Datenbankverbindung) welche unter 'Backend Connections' bereits angelegt wurde.

RDMS_TimeZone
(rdmsTimeZone)

rdms

Optionale Ziel-Zeitzone für Datum-Felder (verwendet intern ZoneId).
Beispiel: America/Los_Angeles

RDMS_ParentTable
(rdmsParentTable)

rdms

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

Die Datenbanktabelle muss existieren und wird nicht automatisch angelegt.

RDMS_ChildTable
(rdmsChildTable)

rdms

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

Die Datenbanktabelle muss existieren und wird nicht automatisch angelegt.

Endpunkte

Zur Verwendung der Endpunkte ist ein angemeldeter Benutzer bzw. API Key mit den jeweiligen Rollen/Rechten notwendig.

Als zusätzlichen Schutz kann über die "Log Service"-Moduleinstellung Security_ClientCertificateAuthMandatory für alle Log Service Endpunkte die Client Certificate Authentication aktiviert werden.

Method Endpoint

GET

/cxf/bpc-logservice/log/instances

Description

Get a compact overview of the available log service instances.

Only the following data is returned for each instance:

  • module instance ID

  • name

  • description

  • flag whether the instance is enabled

Returns

The log service instances as JSON.

HTTP Status Code

  • 200 : OK

  • 401 : Authentication could not be performed

  • 503 : BPC is currently in maintenance mode

Content-Type

  • application/json

Required Access Rights

The logged in user or API Key must have either the following role or right.

  • Role : LOG_SERVICE_USER

  • Right : LOG_SERVICE_CONFIG_GET_INSTANCES

GET

/cxf/bpc-logservice/log/instances/{instanceIdOrName}

Description

Get the current configuration of the log service instance.

Path Parameter

instanceIdOrName

this can be either the ID or a unique name of the module instance

Returns

The requested config as JSON.

HTTP Status Code

  • 200 : OK

  • 401 : Authentication could not be performed

  • 404 : Module instance was not found

  • 503 : BPC is currently in maintenance mode

Content-Type

  • application/json

Required Access Rights

The logged in user or API Key must have either the following role or right.

  • Role : LOG_SERVICE_USER

  • Right : LOG_SERVICE_CONFIG_GET_INSTANCE

GET

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

Description

Gets the data of a log service instance.

Path Parameter

instanceIdOrName

this can be either the ID or a unique name of the module instance

Query Parameter

timezoneOffset

timezone offset like GMT+2 (optional). Is used if a date field is accessed in the parentFilter with a range operator like "gt", "gte", "lt", "lte", ">", ">=", "<", "<=". UTC is the default. timezoneName is used before timezoneOffset if both are set.

timezoneName

timezone name like Europe/Berlin (optional). Is used if a date field is accessed in the parentFilter with a range operator like "gt", "gte", "lt", "lte", ">", ">=", "<", "<=". UTC is the default. timezoneName is used before timezoneOffset if both are set.

start

first record to be read (optional, default = 0)

limit

number of records to read (optional, default = 100, max. 10.000)

parentQuery

simple search (optional). Example city:berlin. Additional information of the Lucene Query String Syntax.

parentFilter

complex filter format like done from the monitor endpoint (optional). Example: [{"property":"processid","operator":"gte","value":1000,"source":"raw","invert":false}]

parentSort

determination by which field the parent entries should be sorted (optional, default = parent key descending). Format: fieldname|[ASC|DESC]. Example: processid|DESC. Multiple sorting instructions can be specified comma separated.

addChildren

should the response contain the log service child entries?. Default is true.

addChilds

should the response contain the log service child entries? Deprecated, please use 'addChildren' instead.

childSort

determination by which field the child entries should be sorted (optional, default = child key ascending). Format: fieldname|[ASC|DESC]. Example: childid|ASC. Multiple sorting instructions can be specified comma separated.

Returns

The requested data as JSON.

HTTP Status Code

  • 200 : OK

  • 401 : Authentication could not be performed

  • 404 : Module instance was not found

  • 503 : BPC or instance are currently in maintenance mode

Content-Type

  • application/json

Required Access Rights

The logged in user or API Key must have either the following role or right.

  • Role : LOG_SERVICE_USER

  • Right : LOG_SERVICE_READ_DATA

GET

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

Description

Get the data of a log service entry with its child entries.

Path Parameter

instanceIdOrName

this can be either the ID or a unique name of the module instance

parentId

the ID of the requested log service entry

Query Parameter

timezoneOffset

timezone offset like GMT+2 (optional). Is used if a date field is accessed in the childFilter with a range operator like "gt", "gte", "lt", "lte", ">", ">=", "<", "<=". UTC is the default. timezoneName is used before timezoneOffset if both are set.

timezoneName

timezone name like Europe/Berlin (optional). Is used if a date field is accessed in the childFilter with a range operator like "gt", "gte", "lt", "lte", ">", ">=", "<", "<=". UTC is the default. timezoneName is used before timezoneOffset if both are set.

childQuery

simple search (optional). Example city:berlin. Additional information of the Lucene Query String Syntax.

childFilter

complex filter format like done from the monitor endpoint (optional). Example: [{"property":"processid","operator":"gte","value":1000,"source":"raw","invert":false}]

Returns

The requested data as JSON.

HTTP Status Code

  • 200 : OK

  • 401 : Authentication could not be performed

  • 404 : Module instance was not found

  • 503 : BPC or instance are currently in maintenance mode

Content-Type

  • application/json

Required Access Rights

The logged in user or API Key must have either the following role or right.

  • Role : LOG_SERVICE_USER

  • Right : LOG_SERVICE_READ_DATA

GET

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

Description

Get the data of a log service child entry.

Path Parameter

instanceIdOrName

this can be either the ID or a unique name of the module instance

parentId

the ID of the requested log service entry

childId

the ID of the requested child entry

Returns

The requested data as JSON.

HTTP Status Code

  • 200 : OK

  • 401 : Authentication could not be performed

  • 404 : Module instance was not found

  • 503 : BPC or instance are currently in maintenance mode

Content-Type

  • application/json

Required Access Rights

The logged in user or API Key must have either the following role or right.

  • Role : LOG_SERVICE_USER

  • Right : LOG_SERVICE_READ_DATA

POST

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

Description

Writes the data provided in the body to OpenSearch and/or the database.

For calls from Iguasu the following HTTP headers are used and their values written to the following 'externalReference' object fields of all 'parent' related documents:

HTTP Header 'externalReference' field

IGUASU-System-ID

externalReference.system

IGUASU-Instance-ID

externalReference.instance

IGUASU-Processor-ID

externalReference.processor

IGUASU-Service-ID

externalReference.service

Consumes

  • application/json

Path Parameter

instanceIdOrName

this can be either the ID or a unique name of the module instance

Query Parameter

async

'true' to perform the log asynchronously. 'false' to perform synchronously. Default is false.

validation

the optional JSON schema validation mode to be used. If not set the related Log Service instance setting gets used. Valid values are 'Off', 'Regular' and 'Strict'.

Returns

HTTP Status Code

  • 200 : Data has been written

  • 400 : None or invalid data to log given

  • 401 : Authentication could not be performed

  • 404 : Module instance was not found

  • 500 : Failed to write the data

  • 503 : Maintenance mode is active or OpenSearch and database are not activated

Content-Type

  • application/json

Required Access Rights

The logged in user or API Key must have either the following role or right.

  • Role : LOG_SERVICE_USER

  • Right : LOG_SERVICE_WRITE_DATA

DELETE

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

Description

Deletes log service entries and their child entries from OpenSearch and the database. Attention: When you use 'childQuery' and/or 'childFilter' only those children get deleted, not the parent itself.

Path Parameter

instanceIdOrName

this can be either the ID or a unique name of the module instance

parentId

the ID of the log service entry to delete, multiple entries can be provided and must be separated by comma

Query Parameter

timezoneOffset

timezone offset like GMT+2 (optional). Is used if a date field is accessed in the childFilter with a range operator like "gt", "gte", "lt", "lte", ">", ">=", "<", "<=". UTC is the default. timezoneName is used before timezoneOffset if both are set.

timezoneName

timezone name like Europe/Berlin (optional). Is used if a date field is accessed in the childFilter with a range operator like "gt", "gte", "lt", "lte", ">", ">=", "<", "<=". UTC is the default. timezoneName is used before timezoneOffset if both are set.

childQuery

simple search (optional). Example city:berlin. Additional information of the Lucene Query String Syntax.

childFilter

complex filter format like done from the monitor endpoint (optional). Example: [{"property":"processid","operator":"gte","value":1000,"source":"raw","invert":false}]

Returns

HTTP Status Code

  • 200 : Data has been deleted

  • 401 : Authentication could not be performed

  • 404 : Module instance was not found

  • 500 : Delete failed

  • 503 : Maintenance mode is active or OpenSearch and database are not activated

Content-Type

  • application/json

Required Access Rights

The logged in user or API Key must have either the following role or right.

  • Role : LOG_SERVICE_USER

  • Right : LOG_SERVICE_DELETE_DATA

DELETE

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

Description

Deletes log service child entries from OpenSearch and the database.

Path Parameter

instanceIdOrName

this can be either the ID or a unique name of the module instance

parentId

the ID of the log service entry to delete the child entries from

childId

the ID of the child entry to delete, multiple entries can be provided and must be separated by comma

Returns

HTTP Status Code

  • 200 : Data has been deleted

  • 401 : Authentication could not be performed

  • 404 : Module instance was not found

  • 500 : Delete failed

  • 503 : Maintenance mode is active or OpenSearch and database are not activated

Content-Type

  • application/json

Required Access Rights

The logged in user or API Key must have either the following role or right.

  • Role : LOG_SERVICE_USER

  • Right : LOG_SERVICE_DELETE_DATA

DELETE

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

Description

Deletes log service entries and their child entries from OpenSearch by query. Deletion from database is not supported.

Consumes

  • application/json

Path Parameter

instanceIdOrName

this can be either the ID or a unique name of the module instance

Query Parameter

timezoneOffset

timezone offset like GMT+2 (optional). Is used if a date field is accessed in the parentFilter with a range operator like "gt", "gte", "lt", "lte", ">", ">=", "<", "<=". UTC is the default. timezoneName is used before timezoneOffset if both are set.

timezoneName

timezone name like Europe/Berlin (optional). Is used if a date field is accessed in the parentFilter with a range operator like "gt", "gte", "lt", "lte", ">", ">=", "<", "<=". UTC is the default. timezoneName is used before timezoneOffset if both are set.

parentQuery

simple search (optional). Example city:berlin. Additional information of the Lucene Query String Syntax.

parentFilter

complex filter format like done from the monitor endpoint (optional). Example: [{"property":"processid","operator":"gte","value":1000,"source":"raw","invert":false}]

Returns

HTTP Status Code

  • 200 : Data has been deleted

  • 401 : Authentication could not be performed

  • 404 : Module instance was not found

  • 500 : Delete failed

  • 503 : Maintenance mode is active or OpenSearch and database are not activated

Content-Type

  • application/json

Required Access Rights

The logged in user or API Key must have either the following role or right.

  • Role : LOG_SERVICE_USER

  • Right : LOG_SERVICE_DELETE_DATA

DELETE

/cxf/bpc-logservice/log/{instanceIdOrName}/children

Description

Deletes only log service child entries from OpenSearch by query. Deletion from database is not supported.

Consumes

  • application/json

Path Parameter

instanceIdOrName

this can be either the ID or a unique name of the module instance

Query Parameter

timezoneOffset

timezone offset like GMT+2 (optional). Is used if a date field is accessed in the childFilter with a range operator like "gt", "gte", "lt", "lte", ">", ">=", "<", "<=". UTC is the default. timezoneName is used before timezoneOffset if both are set.

timezoneName

timezone name like Europe/Berlin (optional). Is used if a date field is accessed in the childFilter with a range operator like "gt", "gte", "lt", "lte", ">", ">=", "<", "<=". UTC is the default. timezoneName is used before timezoneOffset if both are set.

childQuery

simple search (optional). Example city:berlin. Additional information of the Lucene Query String Syntax.

childFilter

complex filter format like done from the monitor endpoint (optional). Example: [{"property":"processid","operator":"gte","value":1000,"source":"raw","invert":false}]

Returns

HTTP Status Code

  • 200 : Data has been deleted

  • 401 : Authentication could not be performed

  • 404 : Module instance was not found

  • 500 : Delete failed

  • 503 : Maintenance mode is active or OpenSearch and database are not activated

Content-Type

  • application/json

Required Access Rights

The logged in user or API Key must have either the following role or right.

  • Role : LOG_SERVICE_USER

  • Right : LOG_SERVICE_DELETE_DATA

DELETE

/cxf/bpc-logservice/log/drop/indices/{instanceIdOrName}

Description

Deletes/drops the parent and child indices of a log service instance.

Path Parameter

instanceIdOrName

this can be either the ID or a unique name of the module instance

Returns

HTTP Status Code

  • 200 : Indices deleted

  • 401 : Authentication could not be performed

  • 404 : Module instance was not found

  • 500 : Delete failed

  • 503 : Maintenance mode is active or OpenSearch and database are not activated

Content-Type

  • application/json

Required Access Rights

The logged in user or API Key must have either the following role or right.

  • Role : LOG_SERVICE_USER

  • Right : LOG_SERVICE_DROP_INDICES

GET

/cxf/bpc-logservice/{instanceIdOrName}/open/logservice

Description

Creates a BPC deeplink to redirect the caller to the admin page of a log service instance.

Path Parameter

instanceIdOrName

this can be either the ID or a unique name of the log service module instance

Returns

The requested data as JSON.

HTTP Status Code

  • 200 : OK

  • 401 : Authentication could not be performed

  • 404 : Module instance was not found

  • 503 : BPC or instance are currently in maintenance mode

Content-Type

  • application/json

Required Access Rights

Can be used without a user session.

GET

/cxf/bpc-logservice/{instanceIdOrName}/open/monitor

Description

Redirects the user to the monitor using the OpenSearch indices of the log service instance.

All provided query params are used to build a monitor filter on fields of the 'externalReference' object.

For Iguasu the following query parameters can be used to access the HTTP header values when the entry has been created.

Query parameter HTTP header

system

IGUASU-System-ID

instance

IGUASU-Instance-ID

processor

IGUASU-Processor-ID

service

IGUASU-Service-ID

Path Parameter

instanceIdOrName

this can be either the ID or a unique name of the log service module instance

Query Parameter

title

optional URL parameter. Text or language key for window title

promptText

optional URL parameter. Text or language key for prompt text

Returns

The requested data as JSON.

HTTP Status Code

  • 200 : OK

  • 401 : Authentication could not be performed

  • 404 : Module instance was not found

  • 500 : BPC deeplink could not be created

  • 503 : BPC or instance are currently in maintenance mode

Content-Type

  • application/json

Required Access Rights

Can be used without a user session.

GET

/cxf/bpc-logservice/jsonschema/{instanceIdOrName}

Description

Get a JSON schema for the defined 'keys' and 'fields' of a log service instance. Such a JSON schema can be used to validate the JSON data POSTed to the create log service entries endpoint.

Path Parameter

instanceIdOrName

this can be either the ID or a unique name of the log service module instance

Query Parameter

strict

in case a strict JSON schema must be created, that allows only known fields. Default is false.

Returns

The requested JSON schema.

HTTP Status Code

  • 200 : OK

  • 401 : Authentication could not be performed

  • 404 : Module instance was not found

  • 503 : BPC or instance are currently in maintenance mode

Content-Type

  • application/json

Required Access Rights

The logged in user or API Key must have either the following role or right.

  • Role : LOG_SERVICE_USER

  • Right : LOG_SERVICE_WRITE_DATA

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 OpenSearch-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

20106

LOG_SERVICE_DB_NOT_SUPPORTED

Die angeforderte Funktionalität steht bei relationalen Datenbanken nicht zur Verfügung

20201

LOG_SERVICE_OS_FAILURE

Beim Zugriff auf OpenSearch ist ein Fehler aufgetreten

20202

LOG_SERVICE_OS_FIELD_MISSING

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

20203

LOG_SERVICE_OS_LOGGING_FAILED

Beim Schreiben der Daten nach OpenSearch kam es zu einem Problem

20204

LOG_SERVICE_OS_DELETE_FAILED

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

20205

LOG_SERVICE_OS_QUERY_RANGE_LIMIT

Es wurden mehr Daten angefordert als zur Verfügung stehen

POST : Aufbau der zur übergebenden JSON Nachricht

Eintrag erstellen/aktualisieren

{
    "entries": [
        {
            "parent": {
                "keyname_parent": keywertparent1,
            	"feldname1": wert1,
            	"feldname2": wert2,
                ...
            },
            "children": [
                {
                    "keyname_parent": keywertparent1,
                    "keyname_child": keywertchild1,
                    "feldname1": wert1,
                    "feldname2": wert2,
                    "datei_binary": base64_3,
                    ...
                },
                {
                    "keyname_parent": keywertparent1,
                    "keyname_child": keywertchild2,
                    "feldname1": wert3,
                    "feldname2": wert4,
                    "datei_binary": base64_5,
                    ...
                },
                ...
            ]
        },
        ...
    ]
}

Einzelne Felder aktualisieren (Partial Update)

{
    "entries": [
        {
            "partialUpdate": true,
            "parent": {
                "keyname_parent": keywertparent1,
                "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):

In dem folgenden Beispiel entsprechen die Felder "ANFRAGENUMMER" dem "keyname_parent" und "CHILDID" dem "keyname_child" von zuvor.

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

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 OpenSearch 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 OpenSearch 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 OpenSearch legt die Daten als 'attachment' ab bzw. erstellt das Mapping dafür.

Beispiel Aufruf

curl -H "X-ApiKey: 1f697af5-c147-3d94-c529-e06f3f15bb87" \
     -H "Content-Type: application/json" \
     -XPOST 'localhost:8181/cxf/bpc-logservice/log/of_test' \
     -d @logservice.json

Erläuterung:

Option

Beschreibung

-H "X-ApiKey: 1f697af5-c147-3d94-c529-e06f3f15bb87"

Der API-Key mit der passenden Rolle bzw. passendem Recht

-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"
            },
            "children": [
                {
                    "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"
            }
        }
    ]
}

File-Storage im Log-Service

Der Log-Service unterstützt Log-Einträge mit Verweisen auf Dateien im File-Storage. Dabei gibt es zwei Möglichkeiten:

  1. Direkter Verweis: Es wird ein Verweis (URI) auf eine bereits vorhandene Datei im File-Storage gespeichert.

  2. Base64-Upload: Die Datei wird als Base64-kodierter String übertragen. Der Log-Service legt diese Datei anschließend im File-Storage ab und speichert eine Referenz darauf im Log-Eintrag.

File-Storage-Referenzen

Für File-Storage-Referenzen wird der Feld-Typ file-storage verwendet. Eine Referenz hat das Schema:

bpc://backend-connection/FILE_STORAGE_BACKEND_CONNECTION_ID/FILE_STORAGE_ITEM_ID

Beispiel für eine POST-Anfrage mit direkter Referenz:

{
  "entries": [
    {
      "parent": {
        "id": "1",
        "file": "bpc://backend-connection/1752063970035/5919ea1ca9b5b8baee8b0cedc5e37c3c59c98fafefd71ed35d38bfc2aea288c7"
      }
    }
  ]
}

Base64-Upload

Soll eine Datei direkt hochgeladen werden, muss in der Log-Service-Instanz zunächst der File-Storage-Upload aktiviert werden. Dies geschieht über folgende Optionen:

  • filestorageUploadEnabled: muss auf true gesetzt werden

  • filestorageBackendConnection: ID der zu verwendenden File-Storage-Backend-Connection

  • filestorageBucket: Bucket, in dem Dateien abgelegt werden

  • filestorageReadRestriction: Lese-Beschränkung für neue Dateien

  • filestorageWriteRestriction: Schreib-Beschränkung für neue Dateien

Die File-Storage-Backend-Connection muss zuvor konfiguriert sein. Außerdem muss der definierte Bucket im File-Storage vorhanden sein.

Beispiel für eine POST-Anfrage mit Base64-kodierter Datei:

{
  "entries": [
    {
      "parent": {
        "id": "1",
        "file": {
          "mediatype": "text/plain",
          "filename": "test.txt",
          "content": "RGFzIGlzdCBlaW4gVGVzdC1UZXh0ZGF0ZWkK"
        }
      }
    }
  ]
}

In diesem Fall ist das file-storage-Feld ein JSON-Objekt. Darin enthält:

  • content: die Datei als Base64-kodierter String (Pflichtfeld)

  • mediatype: Media-Type der Datei (optional, Standard: application/octet-stream)

  • filename: Dateiname (optional, Standard: file)

Der Log-Service speichert in der Datenbanktabelle und im OpenSearch-Index jeweils nur die Referenz (bpc://backend-connection/../..) ab.

Beim Löschen oder Überschreiben eines Log-Eintrags wird die referenzierte Datei nicht automatisch im File-Storage gelöscht.

Soll die Datei entfernt werden, muss dies manuell über die File-Storage API erfolgen.
Keywords:
Press Esc to exit full screen
Modal image placeholder
Press Esc to exit full screen