Log Service

Among other things, this module provides a REST endpoint to receive monitor data and write it to OpenSearch and, optionally, to a database. The relevant monitor "clients" are immediately notified of new data via a WebSocket event.

If data is also to be written to a database, the database tables must already be created. These are not created automatically and are not automatically updated if the data structure changes.

If data is being written to a database, the database data is written first via a DB transaction (which is typically more prone to errors), and only then is the data written to OpenSearch. When writing to the database, a DB update (see the keys setting) is performed first, and if that fails, a DB insert is performed.

As mentioned above, the Log Service data is typically displayed via the monitor. This uses a process index (= parent data) and a history index (= child data).
However, if you do not want to transmit any history/child data, simply omit these elements from the JSON being transmitted (the 'child' elements) and leave out all 'child' elements in the configurations (see below).

Configuration parameters for the Log Service module

Module

General module settings

Name (ID) Description

Name (`ID`)	Description
Module Without GUI (`noGui`)	Indicator for the front end that there is no user interface for loading this module. Should not be changed.
Icon (`module_iconCls`)	Individually selectable icon that is displayed before the title. If no icon is to be displayed, e.g. "none" can be entered. If the field is empty, a standard icon is selected.

Module Without GUI
(noGui)

Indicator for the front end that there is no user interface for loading this module. Should not be changed.

Icon
(module_iconCls)

Individually selectable icon that is displayed before the title.
If no icon is to be displayed, e.g. "none" can be entered. If the field is empty, a standard icon is selected.

OpenSearch

Settings for accessing OpenSearch

Name (ID) Description

Name (`ID`)	Description
Data View Limit (`openSearchDataViewLimit`)	Queries can query data up to this limit. If in doubt, the query should filter the data more specifically. A very high value can have a negative impact on performance.
Data Count Limit (`openSearchDataCountLimit`)	When querying or searching via an index, the number of data records that match the current query is only counted up to this value. A very high value can have a negative impact on performance.

Data View Limit
(openSearchDataViewLimit)

Queries can query data up to this limit. If in doubt, the query should filter the data more specifically. A very high value can have a negative impact on performance.

Data Count Limit
(openSearchDataCountLimit)

When querying or searching via an index, the number of data records that match the current query is only counted up to this value. A very high value can have a negative impact on performance.

Security

Name (ID) Description

Name (`ID`)	Description
mTLS Authentication (`clientCertificateAuthMandatory`)	Authentication only via mutual TLS (client certificate authentication).

mTLS Authentication
(clientCertificateAuthMandatory)

Authentication only via mutual TLS (client certificate authentication).

Configuration parameters for each Log Service component

Module

General module settings

Name (ID) Description

Name (`ID`)	Description
Icon (`module_iconCls`)	Individually selectable icon that is displayed before the title. If no icon is to be displayed, e.g. "none" can be entered. If the field is empty, a standard icon is selected.

Icon
(module_iconCls)

Individually selectable icon that is displayed before the title.
If no icon is to be displayed, e.g. "none" can be entered. If the field is empty, a standard icon is selected.

OpenSearch

Module-specific settings

Name (ID) Description

Name (`ID`)	Description
OpenSearch Logging (`openSearchLoggingEnabled`)	If activated, incoming data is written to OpenSearch.
Parent Index (`openSearchParentIndex`)	Name of the target index in which the parent/main/parent data is written.
Child Index (`openSearchChildIndex`)	Name of the index in which the child/detail data is written. This is created automatically if required.

OpenSearch Logging
(openSearchLoggingEnabled)

If activated, incoming data is written to OpenSearch.

Parent Index
(openSearchParentIndex)

Name of the target index in which the parent/main/parent data is written.

Child Index
(openSearchChildIndex)

Name of the index in which the child/detail data is written. This is created automatically if required.

Relational Database

Name (ID) Description

Name (`ID`)	Description
Database Logging (`rdmsLoggingEnabled`)	The data is only written to the database when activated.
Database Connection (`rdmsDataSourceName`)	Database connection (Backend Connection of type Data Source) that is used for writing to the relational database.
Time Zone (`rdmsTimeZone`)	If a time zone is defined and the database field does not contain any time zone information, the date is converted to the specified time zone. Format corresponds to the IANA Time Zone Database. Example: "Europe/Berlin"
Parent Table (`rdmsParentTable`)	Name of the table in which the parent/main/parent data is written. This table is not created automatically by the BPC.
Child Table (`rdmsChildTable`)	Name of the table in which the child/detail data is written. This table is not created automatically by the BPC.

Database Logging
(rdmsLoggingEnabled)

The data is only written to the database when activated.

Database Connection
(rdmsDataSourceName)

Database connection (Backend Connection of type Data Source) that is used for writing to the relational database.

Time Zone
(rdmsTimeZone)

If a time zone is defined and the database field does not contain any time zone information, the date is converted to the specified time zone. Format corresponds to the IANA Time Zone Database. Example: "Europe/Berlin"

Parent Table
(rdmsParentTable)

Name of the table in which the parent/main/parent data is written. This table is not created automatically by the BPC.

Child Table
(rdmsChildTable)

Name of the table in which the child/detail data is written. This table is not created automatically by the BPC.

Configuration

Module-specific settings

Name (ID) Description

Name (`ID`)	Description
Active (`enabled`)	Allows you to deactivate this log service. If, for example, something needs to be adjusted in the database or the OpenSearch index, the endpoint can be deactivated. In this case, the caller of the endpoint receives an HTTP status 503 (Service Unavailable).
Parent Fields (`parentFields`)	Describes the fields and their data types of the "parent data records". See Configuration of `ParentFields` and `ChildFields`
Child Fields (`childFields`)	Describes the fields and their data types of the "child data records". See Configuration of `ParentFields` and `ChildFields`
Primary Key (`parentKeyFields`)	The primary key field for the data is defined here.
Primary Key for Child Data (`childKeyFields`)	The fields that form the primary key for the child data are specified here, separated by commas.
OpenSearch Joins (`joins`)	Can be used to automatically enrich logging documents with additional data, e.g. if the data to be logged only contains an ID and further associated data can be loaded via an existing index.
JSON Schema Validation (`jsonSchemaValidation`)	Defines whether and how the data to be written should be validated against an automatically generated JSON schema.
Enable File Storage Access (`filestorageUploadEnabled`)	If enabled, fields of type 'file-storage' can be transmitted as base64-encoded text or as a reference to a file at the cloud storage provider. These are then stored in the File Storage by the Log Service.
File Storage Backend Connection (`filestorageBackendConnection`)	The File Storage backend connection used for the upload or for cloud storage references.
File Storage Bucket (`filestorageBucket`)	Defines the designated bucket/container for uploaded files. If a default bucket has already been configured in the file storage connection, this field can be left empty.
Read Restriction (`filestorageReadRestriction`)	The read restriction for the stored files.
Write Restriction (`filestorageWriteRestriction`)	The write restriction for the stored files.

Active
(enabled)

Allows you to deactivate this log service. If, for example, something needs to be adjusted in the database or the OpenSearch index, the endpoint can be deactivated. In this case, the caller of the endpoint receives an HTTP status 503 (Service Unavailable).

Parent Fields
(parentFields)

Describes the fields and their data types of the "parent data records".

See Configuration of ParentFields and ChildFields

Child Fields
(childFields)

Describes the fields and their data types of the "child data records".

See Configuration of ParentFields and ChildFields

Primary Key
(parentKeyFields)

The primary key field for the data is defined here.

Primary Key for Child Data
(childKeyFields)

The fields that form the primary key for the child data are specified here, separated by commas.

OpenSearch Joins
(joins)

Can be used to automatically enrich logging documents with additional data, e.g. if the data to be logged only contains an ID and further associated data can be loaded via an existing index.

JSON Schema Validation
(jsonSchemaValidation)

Defines whether and how the data to be written should be validated against an automatically generated JSON schema.

Enable File Storage Access
(filestorageUploadEnabled)

If enabled, fields of type 'file-storage' can be transmitted as base64-encoded text or as a reference to a file at the cloud storage provider. These are then stored in the File Storage by the Log Service.

File Storage Backend Connection
(filestorageBackendConnection)

The File Storage backend connection used for the upload or for cloud storage references.

File Storage Bucket
(filestorageBucket)

Defines the designated bucket/container for uploaded files. If a default bucket has already been configured in the file storage connection, this field can be left empty.

Read Restriction
(filestorageReadRestriction)

The read restriction for the stored files.

Write Restriction
(filestorageWriteRestriction)

The write restriction for the stored files.

Endpoints

To use the endpoints, a logged-in user or API key with the appropriate roles/permissions is required.

As an additional security measure, the " Client Certificate Authentication " can be enabled for all Log Service endpoints via the "Log Service" module setting: Security_ClientCertificateAuthMandatory.

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, API Key or access token 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, API Key or access token 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, API Key or access token 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, API Key or access token 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, API Key or access token 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, API Key or access token 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, API Key or access token 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, API Key or access token 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, API Key or access token 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, API Key or access token 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, API Key or access token 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, API Key or access token must have either the following role or right.

Role : LOG_SERVICE_USER
Right : LOG_SERVICE_WRITE_DATA

Response in Case of an Error

For every error (Status != 200), a JSON response with the following sample structure is returned:

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

Possible error codes

Error Code

Error Name

Info

UNEXPECTED

should not occur

MODULE_NOT_FOUND

the 'Log Service' module was not found

MODULE_INSTANCE_NOT_FOUND

the ''Log Service' instance was not found

10000

VALIDATION_MISSING_INPUT

No data was passed for logging

10010

VALIDATION_INVALID_INPUT

The data passed is not valid JSON or does not conform to the structure specified here

20000

LOG_SERVICE_UNAUTHORIZED

The login credentials do not match the ones on file (Log Service module setting)

20001

LOG_SERVICE_MAINTENANCE

The Log Service is currently in maintenance mode, or DB and OpenSearchlogging are disabled

20002

LOG_SERVICE_MISSING_SERVICE

A service required by the Log Service is not available

20100

LOG_SERVICE_DB_LOGGING_FAILED

An error occurred during DB logging

20101

LOG_SERVICE_DB_DELETE_FAILED

An error occurred while deleting DB entries

20102

LOG_SERVICE_DB_WRONG_TABLE_NAME

An invalid table name was specified

20103

LOG_SERVICE_DB_TABLE_MISSING

The database table used could not be found

20104

LOG_SERVICE_DB_COLUMN_MISSING

The databasecolumn does not exist

20105

LOG_SERVICE_DB_GET_METADATA_FAILED

The database metadata could not be retrieved

20106

LOG_SERVICE_DB_NOT_SUPPORTED

The requested functionality is not available for relational databases

20201

LOG_SERVICE_OS_FAILURE

An error occurred while accessing OpenSearch

20202

LOG_SERVICE_OS_FIELD_MISSING

The required data for the documentkey, the required data is missing from the document to be logged

20203

LOG_SERVICE_OS_LOGGING_FAILED

A problem occurred while writing data to OpenSearch

20204

LOG_SERVICE_OS_DELETE_FAILED

An error occurred while deleting documents from the OpenSearch index

20205

LOG_SERVICE_OS_QUERY_RANGE_LIMIT

More data was requested than is available

POST: Structure of the JSON message to be sent

Create/update

{
    "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,
                    ...
                },
                ...
            ]
        },
        ...
    ]
}

Update individual fields (partial update)

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

Information about partial updates

The partial update applies to the parent entry and the child entries. This means that if you want to update a parent entry, you should not create a “new” child log in the same JSON document. If you want to create a new child log while updating a parent entry, this should be implemented using two separate log service calls. For example, it might look like this (see INFOBLOCK 1 and 2):

In the following example, the “ANFRAGENUMMER” fields correspond to “keyname_parent” and “CHILDID” to “keyname_child” from earlier.

INFOBLOCK 1 - Example Parent

{
  "entries" : [ {
    "partialUpdate" : true,
    "parent" : {
      "ANFRAGENUMMER" : "16",
      "ANFRAGESTATUS" : "Offen",
      "ANFRAGEDATUM" : "2018-01-23T14:35:41.884+0200"
    }
  } ]
}

INFOBLOCK 2 - Example Child

{
  "entries" : [ {
    "children" : [ {
      "ANFRAGENUMMER" : "16",
      "CHILDID" : 309,
      "PROZESSBESCHREIBUNG" : "Status wurde geändert auf Offen",
      "STATUS" : "OK",
      "TIMESTAMP" : "2018-01-23T14:35:41.927+0200"
    } ]
  } ]
}

In the workflow, it looks like this:

log service workflow

Values of the JSON fields

Type Value range

Type	Value range
Boolean	true / false without quotation marks
Date	as ISO-8601 with quotation marks, e.g., "2017-05-17T15:28:23.181Z". Create the field in the database as `java.sql.Types.TIMESTAMP`.
Numbers	Value without quotation marks
Binary	Base64-encoded. Create the field in the database as `java.sql.Types.BLOB`.
Text	Value with quotation marks
file-storage	Files and references can be passed in various ways in a POST request; see File Storage in the Log Service. Create the field in the database as a text column. Additionally, text columns with the suffixes `_filename` and `_contentType` must be created for each field. (Example: Field name `datei` → additional fields `datei_filename` and `datei_contentType`)

Boolean

true / false without quotation marks

Date

as ISO-8601 with quotation marks, e.g., "2017-05-17T15:28:23.181Z". Create the field in the database as java.sql.Types.TIMESTAMP.

Numbers

Value without quotation marks

Binary

Base64-encoded. Create the field in the database as java.sql.Types.BLOB.

Text

Value with quotation marks

file-storage

Files and references can be passed in various ways in a POST request; see File Storage in the Log Service. Create the field in the database as a text column. Additionally, text columns with the suffixes _filename and _contentType must be created for each field. (Example: Field name datei → additional fields datei_filename and datei_contentType)

Configuration of `ParentFields` and `ChildFields`

Here, you can make fine-tuning adjustments to the data types (mapping for the OpenSearch indexes), among other things.

Default for ParentFields

{
  "PROCESSID": {
    "type": "text",
    "skipOS": false,
    "skipDB": false
  },
  "LASTUPDATE": {
    "type"  : "timestamp",
    "skipOS": false,
    "skipDB": false
  },
  "externalReference" : {
    "type"  : "flat_object",
    "skipOS": false,
    "skipDB": false
  }
}

Default for ChildFields

{
  "CHILDID": {
    "type": "text",
    "skipOS": false,
    "skipDB": false
  }
}

Example

{
  "datei": {
    "type": "binary",
    "skipOS": true,
    "skipDB": false
  },
  "kommentar": {
    "type": "text"
  }
}

type

binary = are created in OpenSearch as 'binary'
file-storage = are stored in OpenSearch and in the database as BPC file storage URIs (type: 'text'). Additionally, two fields are automatically created for the filename and the content type. These fields are named dynamically based on the file-storage field name with the suffixes _filename or _contentType.
text = are created in OpenSearch as 'raw' and 'lowercase', just as in replication.
timestamp = are created in OpenSearch as ‘date’. If the placeholder 'SYSDATE' is used in the message to be logged instead of a UTC date, the log service sets the current timestamp instead.
date:iso8601_millis = are created in OpenSearch as ‘date’ with the format ‘strict_date_optional_time\|\|epoch_millis’
integer = are stored in OpenSearch as ‘integer’
long = are stored in OpenSearch as ‘long’
float = are stored in OpenSearch as ‘float’
double = are stored in OpenSearch as ‘double’
boolean = are stored as ‘boolean’ in OpenSearch
object = are stored as ‘object’ in OpenSearch
flat_object = are stored as ‘flat_object’ in OpenSearch

By default, all fields are written to OpenSearch and to the database. If you do not want individual fields to be written, you can specify them here.

skipOS

true = the field is not written to OpenSearch

false = the field is written to OpenSearch (default)

skipDB

true = the field is not written to the database

false = the field is written to the database (default)

Field Name Convention

The data types for each field can be specified via the module instance setting fields (see below). This is not strictly necessary for binary types and can also be achieved using the field name convention FIELDNAME_binary (with _binary as a suffix).

Background: In OpenSearch, we store binary data as Base64-encoded strings (so this is also how it must be formatted in the JSON being passed). However, as with replication, we want to store this data under the specific type 'attachment'. Since both are treated as strings by OpenSearch, we need to be aware of this and perform a special mapping.

Example: If we have a field named 'datei' and can assign names freely, this could become 'datei_binary,' and OpenSearch will store the data as 'attachment' or create the mapping for it.

Example Call

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

Explanation:

Option Description

Option	Description
`-H "X-ApiKey: 1f697af5-c147-3d94-c529-e06f3f15bb87"`	The API key with the appropriate role or permission
`-H "Content-Type: application/json"`	The Content-Type must be set to `application/json`
`-XPOST`	HTTP POST is required
`localhost:8181/cxf/bpc-logservice/log/of_test`	`of_test` is a unique instance name. Alternatively, the module instance ID can be used
`-d @logservice.json`	The JSON to be posted (see below)

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

The API key with the appropriate role or permission

-H "Content-Type: application/json"

The Content-Type must be set to application/json

-XPOST

HTTP POST is required

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

of_test is a unique instance name. Alternatively, the module instance ID can be used

-d @logservice.json

The JSON to be posted (see below)

logservice.json (Create/update entry)

{
    "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 (Update individual fields (partial update))

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

File Storage in the Log Service

The Log Service supports log entries with references to files in File Storage. There are several options:

Direct Reference: A reference (URI) to an existing file in file storage is saved.
Reference to a file in cloud storage: A reference to a file that already exists in cloud storage is passed. To do this, the log service stores the file metadata in file storage and saves a reference to it in the log entry.
Base64 Upload: The file is transmitted as a Base64-encoded string. The log service then stores this file in file storage and saves a reference to it in the log entry.

For all options, the information is passed in a field of type ` file-storage . In the OpenSearch index and the database, it is always stored as a file storage reference. Additionally, the filename and content type are stored in fields with the suffixes `_filename and _contentType.

When a log entry is deleted or overwritten, the referenced file is not automatically deleted from File Storage.

If the file is to be removed, this must be done manually via the File Storage API.

Enable File Storage Access

To log files that are transmitted as references in cloud storage or as Base64-encoded strings, file storage access must be enabled in the Logservice instance.

This is done using the following options:

filestorageUploadEnabled: must be set to true
filestorageBackendConnection: ID of the file storage backend Connection to be used
filestorageBucket: Bucket or container in which files are stored. (If this value is empty, the default bucket defined in the file storage backend Connection is used.)
filestorageReadRestriction: Read restriction for new files
filestorageWriteRestriction: Write restriction for new files

The file storage backend Connection must be configured beforehand. Additionally, the defined bucket or container must exist in File Storage.

File Storage References

File Storage References point to files managed by the File Storage Service and follow this schema:

bpc://backend-connection/FILE_STORAGE_BACKEND_CONNECTION_ID/FILE_STORAGE_ITEM_ID

Example of a POST request with a direct reference:

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

During logging, the filename and content type are automatically determined and do not need to be provided.

Cloud Storage Reference

If you want to reference a file from a cloud storage service for which no metadata yet exists in the File Storage Service, you can refer directly to the key in the cloud storage. To do this, File Storage access must first be enabled in the Log Service instance.

Then, using a POST request, the file’s ID or key can be passed in the ` filekey ` field as follows. Optionally, the file name and content type can also be specified using the ` mediatype ` and ` filename ` fields, respectively.

{
  "entries": [
    {
      "parent": {
        "id": "1",
        "file": {
          "mediatype": "text/plain",
          "filename": "test.txt",
          "filekey": "cloud_storage_file_key.txt",
          "checkFile": true
        }
      }
    }
  ]
}

If no content type is provided, it is taken from the file metadata of the cloud storage provider. If no file name is provided, the file key is used.

The optional field checkFile (default: true) can be used to control whether the existence of the file in cloud storage should be checked immediately upon logging. This is particularly helpful if the file is not uploaded until a later time. In this case, set ` checkFile ` to ` false`. However, the content type cannot then be derived from the cloud provider’s metadata and must be provided explicitly.

The Log Service stores only the reference (bpc://backend-connection/../..) in both the database table and the OpenSearch index.

Base64 Upload

If a file is to be uploaded directly, file storage access must first be enabled in the Log Service instance.

Then, the file content can be transferred as Base64-encoded text using a POST request as follows:

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

In this case, the ` file-storage` field is a JSON object with the following fields:

content: the file as a Base64-encoded string (required field)
mediatype: Media type of the file (optional, default: application/octet-stream)
filename: File name (optional, default: file)

The log service stores only the reference (bpc://backend-connection/../..) in both the database table and the OpenSearch index.

Keywords:

Log Service

Configuration parameters for the Log Service module

Module

OpenSearch

Security

Configuration parameters for each Log Service component

Module

OpenSearch

Relational Database

Configuration

Endpoints

Response in Case of an Error

POST: Structure of the JSON message to be sent

Create/update

Update individual fields (partial update)

Information about partial updates

INFOBLOCK 1 - Example Parent

INFOBLOCK 2 - Example Child

Values of the JSON fields

Configuration of ParentFields and ChildFields

Field Name Convention

Example Call

logservice.json (Create/update entry)

logservice.json (Update individual fields (partial update))

File Storage in the Log Service

File Storage References

Cloud Storage Reference

Base64 Upload

Configuration of `ParentFields` and `ChildFields`