Log Service

This module offers, among other things, a REST endpoint to receive monitor data and write it to OpenSearch and optionally to a database. The relevant monitor "clients" are immediately informed of new data via a websocket event.

If you also want to write to a database, the database tables must already be created. These are not created automatically and are not automatically adjusted if the data structure changes.

If you write to a database, the database data is written first via a DB transaction (this is normally more error-prone) and only then the data is written to OpenSearch. When writing to the database, a DB update is performed first (see keys setting) and if this fails, a DB insert is performed.

As mentioned above, the Log Service data is usually displayed via the monitor. This uses a process index (= parent data) and a history index (= child data).
However, if no history/child data is to be transferred, then simply do not specify this in the transferred JSON ('child' elements) and omit all 'child' elements in the configurations (see below).

Configuration parameters Log Service module

Mandatory parameters are highlighted in bold.

Setting (Key) Group Description

Security_ClientCertificateAuthMandatory
(clientCertificateAuthMandatory)

security

Specifies whether the log service endpoints can only be called via Client Certificate Authentication.
Default: false

OpenSearch_DataCountLimit
(openSearchDataCountLimit)

opensearch

Maximum number of documents that can be queried.
Default: 100000

OpenSearch_DataViewLimit
(openSearchDataViewLimit)

opensearch

Up to this value, OpenSearch should return exact information about the number of documents (trackTotalHitsUpTo).
Default: 100000

Configuration parameters per Log Service component

Values highlighted in bold are mandatory parameters.

Setting (Key) Group Description

Enabled
(enabled)

config

If something needs to be adjusted in the database or the OpenSearch index, the endpoint for this instance can be set to maintenance mode. In this case, the caller of the endpoint is returned an HTTP status 503 (Service Unavailable).
Default: true

ParentKeyFields
(parentKeyFields)

ChildKeyFields
(childKeyFields)

config

The key fields are defined here. When writing to the database, these are used for the DB update. For OpenSearch to define the document IDs. If several fields are affected, they must be separated from each other by commas.

Default: PROCESSID or PROCESSID, CHILDID

ParentFields
(parentFields)

ChildFields
(childFields)

config

Among other things, fine adjustments can be made to the data types here (mapping for the OpenSearch indexes).

Default 
{
  "fieldname": {
    "type": "binary/text/timestamp/...",
    "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 URI. (type: 'text') If the option filestorageUploadEnabled is activated, you can also transfer Base64-encoded files, which are then stored in the file storage and written to OpenSearch and the database as BPC file storage URIs. See also File storage in the Log Service.

  • text = are created in OpenSearch as for replication with 'raw' and 'lowercase'

  • 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 created in OpenSearch as 'integer'

  • long = are created in OpenSearch as 'long'

  • float = are created as 'float' in OpenSearch

  • double = are created as 'double' in OpenSearch

  • boolean = are created as 'boolean' in OpenSearch

By default, all fields are written to OpenSearch and the database. If individual fields are not to be written, they can be defined here.

skipOS

true = the field is not written to OpenSearch

false = the field is written to OpenSearch (default setting)

skipDB

true = the field is not written to the database

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

JsonSchemaValidation
(jsonSchemaValidation)

config

Specifies whether a JSON schema validation is to be performed for the data to be written. The JSON schema is generated based on the defined Keys and Fields.

  • off = no validation is performed

  • regular = additional fields are permitted and not just those defined under Keys and Fields

  • strict = only the fields defined under Keys and Fields are permitted

    Default: off

Via the Log Service endpoint the JSON schema of the Log Service component can be loaded.

Enable File Storage Upload
(filestorageUploadEnabled)

config

If this option is activated, fields of type file-storage can be transferred as a Base64-encoded file. This is then automatically stored in the file storage.

Default: false

File Storage Backend Connection
(filestorageBackendConnection)

config

The file storage backend connection that is used when storing files in the file storage.

File Storage Bucket
(filestorageBucket)

config

The bucket name to store files in File Storage.

Read Restriction
(filestorageReadRestriction)

Write Restriction
(filestorageWriteRestriction)

config

The read or write restriction that is used when storing files in File Storage.

Either a user or at least one role, organization or permission must be specified.

Example with one user 
{
  "user": "file_admin"
}
Example with roles, organizations and rights 
{
    "roles": ["bpcadmin"],
    "organisations": [],
    "rights": ["LOG_SERVICE_FILE_EXAMPLE_RIGHT"]
}

OpenSearch_LoggingEnabled
(openSearchLoggingEnabled)

opensearch

Only if activated, the data is written to OpenSearch.
Default: true

OpenSearch_ParentIndex
(openSearchParentIndex)

opensearch

Specifies the index to which the parent/main/parent data is to be written. The index is created automatically. The specified 'Fields' types are taken into account.

The name of the index must be written completely in lower case.

OpenSearch_ChildIndex
(openSearchChildIndex)

opensearch

Specifies the index in which the child/detail/child data is to be written. The index is created automatically. The specified 'Fields' types are taken into account.

The name of the index must be written completely in lower case.

Joins
(joins)

config

Can be used to automatically enrich the logging documents with additional data. For example, if there is only a partner ID in the data to be logged and the name of the partner etc. is still required in the monitor. Is the same configuration as for the 'Lookup Joins' of the Replication service.

Example:

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

RDMS_LoggingEnabled
(rdmsLoggingEnabled)

rdms

The data is only written to the database if activated.
Default: false

RDMS_DataSourceName
(rdmsDataSourceName)

rdms

Name of the Data Source (database connection) which has already been created under 'Backend Connections'.

RDMS_TimeZone
(rdmsTimeZone)

rdms

Optional target time zone for date fields (used internally ZoneId).
Example: America/Los_Angeles

RDMS_ParentTable
(rdmsParentTable)

rdms

Name of the target table with the parent/main/parent data.

The database table must exist and is not created automatically.

RDMS_ChildTable
(rdmsChildTable)

rdms

Name of the target table with the child/detail/child data.

The database table must exist and is not created automatically.

Endpoints

To use the endpoints, a logged-in user is required logged in user or API key with the respective roles/rights is required to use the endpoints.

As additional protection, the "Log Service" module setting Security_ClientCertificateAuthMandatory can be used to activate Client Certificate Authentication for all Log Service endpoints.

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 in the event of an error

For every error (status != 200), a JSON with the following exemplary 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"
    }
  }
}

The possible error codes

Error Code

Error Name

Info

1

UNEXPECTED

should not occur

20

MODULE_NOT_FOUND

the 'Log Service' module was not found

21

MODULE_INSTANCE_NOT_FOUND

the 'Log Service' instance was not found

10000

VALIDATION_MISSING_INPUT

No data was transferred for "logging"

10010

VALIDATION_INVALID_INPUT

The transferred data is not valid JSON or does not correspond to the structure specified here do not correspond to the structure specified here

20000

LOG_SERVICE_UNAUTHORIZED

The access data does not match the stored data (Log Service module setting)

20001

LOG_SERVICE_MAINTENANCE

The Log Service is currently in maintenance mode or the DB and OpenSearch module is not available. the DB and OpenSearchLogging are deactivated

20002

LOG_SERVICE_MISSING_SERVICE

A Service required by the Log Service is not available

20100

LOG_SERVICE_DB_LOGGING_FAILED

An error has 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 20102 An error occurred while deleting DB entriesTable could not be found

20104

LOG_SERVICE_DB_COLUMN_MISSING

The database column to be used does not existColumn does not exist

20105

LOG_SERVICE_DB_GET_METADATA_FAILED

The database metadata could not be read

20106

LOG_SERVICE_DB_NOT_SUPPORTED

The requested functionality is not available for relational databases relational databases

20201

LOG_SERVICE_OS_FAILURE

An error occurred while accessing OpenSearch

20202

LOG_SERVICE_OS_FIELD_MISSING

The data required to form the document key is missing in the databaseKey, the required data is missing in the document to be logged

20203

LOG_SERVICE_OS_LOGGING_FAILED

There was a problem writing the 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 transferred

Create/update entry

{
    "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 on the partial update

The partial update relates 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 when updating a parent entry, it should be implemented in two log service calls. For example, it could look like this (see INFOBLOCK 1 and 2):

In the following example, the fields "INQUIRY_NUMBER" correspond to "keyname_parent" and "CHILDID" to "keyname_child" from before.

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

Boolean

true / false without quotation marks

Date

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

Numbers

Value without quotation marks

Binary

Base64 encoded. In the database as java.sql.Types.BLOB.

Text

Value with quotation marks

Field name convention

The data types per field can be defined via the module instance setting fields (see below). This is not absolutely necessary for binary types and can also be done using the field name convention FIELDNAME_binary (_binary as postfix).

Background: In OpenSearch we store binary data Base64 encoded (so they must also be in the transferred JSON). However, as with replication, we want to store these under the special type 'attachment'. Since both are strings for OpenSearch, we need to know this and perform a special mapping.

Example: If we have a field with the name 'file' and can freely assign the names, then it can become the name 'file_binary' and OpenSearch stores the data as 'attachment' or creates 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

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

The API key with the appropriate role or right

-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. The ID of the module instance can also be used instead

-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 the file storage. There are two options:

  1. Direct reference: A reference (URI) to an existing file in the file storage is saved.

  2. Base64 uploadthe file is transferred as a Base64-encoded string. The log service then stores this file in the file storage and saves a reference to it in the log entry.

File storage references

The field type file-storage is used for file storage references. A reference has the following schema:

bpc://backend-connection/FILE_STORAGE_BACKEND_CONNECTION_ID/FILE_STORAGE_ITEM_ID

Example of a POST request with direct reference:

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

Base64 upload

If a file is to be uploaded directly, the file storage upload must first be activated in the log service 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

  • filestorageReadRestriction: Read restriction for new files

  • filestorageWriteRestriction: Write restriction for new files

The File-Storage-Backend-Connection must be configured beforehand. The defined bucket or container must also be present in the file storage.

Example of a POST request with Base64-encoded file:

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

In this case, the file-storage field is a JSON object. It contains:

  • content: the file as a Base64-encoded string (mandatory field)

  • mediatype: media type of the file (optional, default: application/octet-stream)

  • filename: file name (optional, default: file)

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

When deleting or overwriting a log entry, the referenced file is not deleted not automatically deleted from the file storage.

If the file is to be removed, this must be done manually via the File-Storage API file storage API.
Keywords:
Press Esc to exit full screen
Modal image placeholder
Press Esc to exit full screen