BPC API

Für den Zugriff auf die BPC API ist in den meisten Fällen ein angemeldeter Benutzer bzw. API Key notwendig. Letzterer wird empfohlen. Bitte auch die jeweils benötigte Rolle bzw. das benötigte Recht beachten.

Audit Log API

These are the endpoints of the audit log service.

Method Endpoint

POST

/cxf/bpc-auditlog/auditlog/log

Description

To create a new audit log entry, send a JSON message with the following structure:

{
    "level": "INFO",
    "originator": "[INUBIT]",
    "action": "TESTACTION",
    "description": "Only a test",
    "oldValues": "5",
    "newValues": "10",
    "externalReference": {
        "workflow": "update_units",
        "engine": "IS8"
    }
}

Hint: 'externalReference' is optional and must be a JSON object when used.

Returns

HTTP Status Code

  • 200 : OK

  • 400 : The transferred data is not valid

  • 401 : Authentication could not be performed

Required Access Rights

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

  • Role : AUDIT_LOG_USER

  • Right : AUDIT_LOG_CREATE_ENTRY

Authentication API

These are the authentication endpoints.

Method Endpoint

GET

/cxf/bpc-core/authentication

Description

Check if the user session is valid. This function check the presence of an ssoToken. If a token was found, it is checked on the identity provider. If no token is found or the check was negative 401 "UNAUTHORIZED" will be send back. If the token was confirmed by the provider 200 OK will be send.

Returns

The user session as JSON.

HTTP Status Code

  • 200 : OK

  • 401 : Unauthorized

Content-Type

  • application/json

Required Access Rights

Can be used without a user session.

DELETE

/cxf/bpc-core/authentication

Description

Destroys the current user session.

Returns

HTTP Status Code

  • 200 : OK when no user flow identity provider is in use

  • 205 : OK when a user flow identity provider is in use

Required Access Rights

Can be used without a user session.

DELETE

/cxf/bpc-core/authentication/sessions/all

Description

Destroy all user sessions.

Returns

HTTP Status Code

  • 200 : OK

Required Access Rights

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

  • Role : USER_ADMIN

  • Right : USER_DELETE_SESSIONS

DELETE

/cxf/bpc-core/authentication/sessions/{sessionId}

Description

Destroys a specific user session.

Path Parameter

sessionId

the non hijackable ID of the user session to destroy

Returns

HTTP Status Code

  • 200 : OK

Required Access Rights

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

  • Role : USER_ADMIN

  • Right : USER_DELETE_SESSIONS

POST

/cxf/bpc-core/authentication

Description

Form based login. Forwarding credentials to identity provider. If login was ok, the ssoToken will be placed as cookie in response and the information from provider will be forwarded as JSON.

Consumes

  • application/x-www-form-urlencoded

Returns

The user session as JSON.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

Can be used without a user session.

PUT

/cxf/bpc-core/authentication

Description

Form based update of an existing session with the given tenant name.

Consumes

  • application/x-www-form-urlencoded

Form Parameter

tenantname

the name of the tenant

Returns

The user session as JSON.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

PUT

/cxf/bpc-core/authentication/language/{lang}

Description

Set the provided language in the user session. When Keycloak is used as IdP, the language gets set in the Keycloak user profile (locale).

Path Parameter

lang

the language to set

Returns

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

Can be used without a user session.

POST

/cxf/bpc-core/authentication/reset

Description

Forwards the provided body to the user self service of the currently used identity provider.

Consumes

  • application/x-www-form-urlencoded

Returns

The response of the user self service

HTTP Status Code

  • 200 : OK

  • 500 : Something wrong with the identity provider settings

Content-Type

  • application/json

Required Access Rights

Can be used without a user session.

POST

/cxf/bpc-core/authentication/changepassword

Description

Form based update of the users password. In case the IdP does not support updating user passwords, the user self service is used.

Form params to provide:

  • username - the name of the user to change the password for

  • oldPassword - the old password

  • newPassword - the new password

Consumes

  • application/x-www-form-urlencoded

Returns

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

POST

/cxf/bpc-core/authentication/{userName}/impersonate

Description

Impersonate a user. Works only when Keycloak is used as identity provider.

When used with Keycloak one of these Keycloak roles are needed: admin, realm-admin, (manage-users and impersonation)

Path Parameter

userName

the name of the user to impersonate

Returns

The user session as JSON.

HTTP Status Code

  • 200 : OK

  • 500 : No username given

  • 500 : No user session provided

  • 500 : Current identity provider does not support impersonation

Content-Type

  • application/json

Required Access Rights

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

  • Role : IDENTITY_MANAGER_ADMIN

  • Right : IDENTITY_MANAGER_USER_IMPERSONATE

POST

/cxf/bpc-core/authentication/user/info/{accessTokenType}/token

Description

Get user info by access token. Can only be used with an OpenID Connect provider.

CURL example with 'bearer' as access token type
curl -X POST \
    --header 'X-ApiKey: <YourApiKey>' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'accessToken=<ValueOfTheAccessToken>'  \
    'http://localhost:8181/cxf/bpc-core/authentication/user/info/bearer/token'

Consumes

  • application/x-www-form-urlencoded

Path Parameter

accessTokenType

the type of the given access token. Can be bearer, dpop or mac. Keycloak seems to use 'bearer'.

Form Parameter

accessToken

the access token of the user to get the user info for

Returns

The requested user info as JSON.

HTTP Status Code

  • 200 : OK

  • 500 : Access token type missing or not supported

  • 500 : Access token missing

  • 500 : Current identity provider does not support token exchange

Content-Type

  • application/json

Required Access Rights

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

  • Role : USER_ADMIN

  • Right : GET_USER_INFO_BY_TOKEN

BOM API

These are the BOM endpoints. BOM stands for Bill-of-Materials and is an aggregation of all software dependencies the BPC modules/bundles have. To get listed the modules/bundles must place their BOM to the file /META-INF/bom.json.

Method Endpoint

DELETE

/cxf/bpc-core/bom

Description

Forces a re-load of the BOMs.

Returns

HTTP Status Code

  • 200 : OK

Required Access Rights

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

  • Role : BOMS_ADMIN

  • Right : BOMS_RELOAD

GET

/cxf/bpc-core/bom/all

Description

Get the BOMs of all BPC bundles.

Returns

The requested BOMs. Example response:

{
  "SYMBOLIC_NAME_BUNDLE_1": BOM_FILE_CONTENT_1,
  "SYMBOLIC_NAME_BUNDLE_2": BOM_FILE_CONTENT_2,
  "SYMBOLIC_NAME_BUNDLE_n": BOM_FILE_CONTENT_n
}

  • SYMBOLIC_NAME_BUNDLE_1 etc. is the symbolic name of the BPC bundle

  • BOM_FILE_CONTENT_1 etc. is the content of the /META-INF/bom.json file

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

GET

/cxf/bpc-core/bom/bundles

Description

Get just the symbolic names of BPC bundles with BOMs.

Returns

The requested list. Example response:

[
  "SYMBOLIC_NAME_BUNDLE_1",
  "SYMBOLIC_NAME_BUNDLE_2",
  "SYMBOLIC_NAME_BUNDLE_n"
]

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

GET

/cxf/bpc-core/bom/bundle/{symbolicNameOfBundle}

Description

Get the BOM of a specific BPC bundle by its symbolic name.

Path Parameter

symbolicNameOfBundle

the symbolic name of the bundle to get the BOM for

Returns

The content of the /META-INF/bom.json file

HTTP Status Code

  • 200 : OK

  • 404 : Requested BOM not found

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

GET

/cxf/bpc-core/bom/bundle/download/{symbolicNameOfBundle}

Description

Download the BOM of a specific BPC bundle by its symbolic name.

Path Parameter

symbolicNameOfBundle

the symbolic name of the bundle to download the BOM for

Returns

The content of the /META-INF/bom.json file

HTTP Status Code

  • 200 : OK

  • 404 : Requested BOM not found

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

Backups API

These are the backup endpoints.

Method Endpoint

GET

/cxf/bpc-core/configuration/backups

Description

Get a list of all backups/snapshots as JSON.

Returns

The requested data as JSON.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : BACKUPS_ADMIN

  • Right : BACKUPS_VIEW

POST

/cxf/bpc-core/configuration/backups/create

Description

Creates a backup/snapshot of the BPC configuration index bpc-configuration.

Returns

The backup/snapshot info as JSON.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : BACKUPS_ADMIN

  • Right : BACKUPS_CREATE

POST

/cxf/bpc-core/configuration/backups/create/{backupJobIdentifier}

Description

Creates a backup/snapshot of the indices related to a backup job.

Path Parameter

backupJobIdentifier

the identifier of the backup job

Returns

The backup/snapshot info as JSON.

HTTP Status Code

  • 200 : OK

  • 404 : Backup job not found

Content-Type

  • application/json

Required Access Rights

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

  • Role : BACKUPS_ADMIN

  • Right : BACKUPS_CREATE

GET

/cxf/bpc-core/configuration/backups/{snapshotName}

Description

Get the data of a specific backup/snapshot.

Path Parameter

snapshotName

the name of the backup/snapshot to get the infos for

Returns

The requested backup/snapshot data as JSON.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : BACKUPS_ADMIN

  • Right : BACKUPS_VIEW

DELETE

/cxf/bpc-core/configuration/backups/{snapshotName}

Description

Delete a specific backup/snapshot.

Path Parameter

snapshotName

the name of the backup/snapshot to delete

Returns

The info of the deleted backup/snapshot as JSON.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : BACKUPS_ADMIN

  • Right : BACKUPS_DELETE

PUT

/cxf/bpc-core/configuration/backups/activate/{snapshotName}

Description

Restores and activates a specific backup/snapshot.

Path Parameter

snapshotName

the name of the backup/snapshot to restore and activate

Returns

Some infos about the restored and activated backup/snapshot as JSON.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : BACKUPS_ADMIN

  • Right : BACKUPS_ACTIVATE

PUT

/cxf/bpc-core/configuration/backups/restore/{snapshotName}

Description

Restores but does not activate a specific backup/snapshot.

Path Parameter

snapshotName

the name of the snapshot to restore

Query Parameter

index-name

to give the OpenSearch index a new name (Optional; works only when the backup contains exactly one index)

Returns

Some infos about the restored backup/snapshot as JSON.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : BACKUPS_ADMIN

  • Right : BACKUPS_RESTORE

GET

/cxf/bpc-core/configuration/backups/download/{snapshotName}

Description

Download the content of a backup/snapshot.

Path Parameter

snapshotName

the name of the backup/snapshot to download

Returns

The requested data as JSON. Uses the snapshotName parameter value as the filename.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : BACKUPS_ADMIN

  • Right : BACKUPS_DOWNLOAD

GET

/cxf/bpc-core/configuration/backups/export/{snapshotName}

Description

Export the content of a bpc-configuration index backup/snapshot as GlobalConfig object.

Path Parameter

snapshotName

the name of the backup/snapshot

Returns

The requested data as JSON.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : BACKUPS_ADMIN

  • Right : BACKUPS_EXPORT

Configuration API

These are the configuration endpoints.

Method Endpoint

GET

/cxf/bpc-core/configuration

Description

Get a complete version of the BPC configuration.

It will contain all modules, instances and their settings, but restricted to the rights the user has.

Every module provides the default configuration of itself and for instances.

Additionally, some metadata like the model version and infos about the used bpc-configuration index is provided.

{
  "metadata": {
    "modelVersion": {current model version},
    "fromIndex": { settings and mappings of the bpc-configuration index }
  },
  "modules": [
    {
        "moduleId": "{id of the module}",
        "moduleName": "{name of the module}",
        "settings": [ ... ],
        "instances": [ ... ],
        "defaultConfiguration": [ ... ],
        "instancesDefaultConfiguration": [ ... ]
    },
    ...
  ]
}

Returns

The requested data as JSON

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

GET

/cxf/bpc-core/configuration/compact

Description

Get a compact version of the BPC configuration.

It will contain all modules, instances and their settings, but restricted to the rights the user has. And it will return only the settings were the _mandatoryForFrontend flag is set to true.

Additionally, the metadata about the model version is provided.

{
  "metadata": {
    "modelVersion": {current model version}
  },
  "modules": [
    {
        "moduleId": "{id of the module}",
        "moduleName": "{name of the module}",
        "settings": [ ... ],
        "instances": [ ... ]
    },
    ...
  ]
}

Returns

The requested data as JSON

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

GET

/cxf/bpc-core/configuration/init

Description

Get the base BPC configuration to initialize the frontend.

Returns

The requested data as JSON.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

Can be used without a user session.

GET

/cxf/bpc-core/configuration/uuid/generate

Description

Generates unique IDs using "SHA-256". The result is a 256bit long UUID as HEX String.

Query Parameter

count

the number of UUIDs to generate. Must be in the range 1-1000. Default is 1.

Returns

The requested UUIDs as JSON array.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

GET

/cxf/bpc-core/configuration/apikey/generate

Description

Generates a unique API key using "SHA-256" (256bit long UUID as HEX String) and the ID of the API key.

example response
{
  "apiKey": "039c969b4ec2e3d8f23cfca226c932403318d5b53e6653782f8e0e163c772e1e",
  "id": "API-34c05ef"
}

Returns

The requested data as JSON object.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

GET

/cxf/bpc-core/configuration/{moduleId}/{instanceType}/newInstanceId

Description

Get a new instance ID for the provided module and module type.

Path Parameter

moduleId

the ID of the module to get a new instance ID for

instanceType

the instance type, provide 'none' in case the module does not support different types

Returns

The requested data as JSON.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

GET

/cxf/bpc-core/configuration/{moduleId}

Description

Get the configuration of a specific module.

The result contains the settings of the module, but restricted to the rights the user has.

Additionally, the default configuration of itself and for instances is provided.

Contains a compact list of instances with the ID, type and name when it is an instantiable module.

{
  "moduleId": "{id of the module}",
  "moduleName": "{name of the related module}",
  "settings": [ ... ],
  "instancesCompact": [ ... ],
  "defaultConfiguration": [ ... ],
  "instancesDefaultConfiguration": [ ... ]
}

Path Parameter

moduleId

the ID of the module

Returns

The requested data as JSON

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

GET

/cxf/bpc-core/configuration/{moduleId}/{moduleInstanceId}

Description

Get the configuration of a specific module instance.

In case the configuration of an instance is requested, just the settings the user has access rights for are returned.

{
  "moduleId": "{moduleInstanceId}",
  "moduleName": "{name of the related module}",
  "instanceType": "none|{instance type}",
  "settings": [ ... ]
}

In case the configuration of a module is requested, it returns the same as the endpoint without the moduleInstanceId path parameter.

Path Parameter

moduleId

the ID of the related module

moduleInstanceId

the ID of the module instance, can be set to 'noinstance' to get the module configuration instead

Returns

The requested data as JSON

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

POST

/cxf/bpc-core/configuration/{moduleId}

Description

Set the module configuration provided in the body.

Consumes

  • application/json

Path Parameter

moduleId

the ID of the module to update

Query Parameter

force

true to skip the settings validation, false to perform a validation. Default is false.

Returns

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

POST

/cxf/bpc-core/configuration/{moduleId}/{moduleInstanceId}

Description

Set the module instance configuration provided in the body.

Consumes

  • application/json

Path Parameter

moduleId

the ID of the related module

moduleInstanceId

the ID of the module instance to update

Query Parameter

instanceType

the type of the module instance. Set to 'noinstance' if types are not supported by the module

force

true to skip the settings validation, false to perform a validation. Default is false.

Returns

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

DELETE

/cxf/bpc-core/configuration/{moduleId}/{moduleInstanceId}/settings/{settingName}

Description

Delete a single setting from a module instance. If this instance has a default value for this setting, the default will be restored.

Path Parameter

moduleId

the ID of the related module

moduleInstanceId

the ID of the related module instance

settingName

the name of the setting to delete

Returns

HTTP Status Code

  • 200 : OK

Required Access Rights

A logged in user or API Key is required.

DELETE

/cxf/bpc-core/configuration/{moduleId}/{moduleInstanceId}/settings

Description

Delete a list of settings (provided in the body) from a module instance.

Consumes

  • application/json

Path Parameter

moduleId

the ID of the module

moduleInstanceId

the ID of the module instance

Returns

HTTP Status Code

  • 200 : OK

Required Access Rights

A logged in user or API Key is required.

DELETE

/cxf/bpc-core/configuration/{moduleId}/{moduleInstanceId}

Description

Delete a specific module instance.

Path Parameter

moduleId

the ID of the related module

moduleInstanceId

the ID of the module instance to delete

Returns

HTTP Status Code

  • 200 : OK

Required Access Rights

A logged in user or API Key is required.

POST

/cxf/bpc-core/configuration/test/{moduleId}/{moduleInstanceId}

Description

Performs a connection test on a specific module instance. Additional data to perform can be provided in the POST body as JSON object.

Consumes

  • application/json

Path Parameter

moduleId

the ID of the related module

moduleInstanceId

the ID of the module instance to do the connection test for

Returns

The error result as JSON, nothing when successful

HTTP Status Code

  • 200 : OK

  • 404 : Module not found

  • 404 : Module instance not found

  • 406 : Module cannot have module instances

  • 500 : Connection test failed

  • 501 : No suitable connection tester implementation exists

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

GET

/cxf/bpc-core/configuration/jsonschema/{moduleId}/{setting}

Description

Get the JSON schema to validate a JSON based module setting.

Path Parameter

moduleId

the ID of the module

setting

the name of the setting

Returns

The requested data as JSON

HTTP Status Code

  • 200 : OK

  • 404 : Module not found

  • 404 : Module configuration missing

  • 404 : Setting not found

  • 500 : Setting without set JSON schema

  • 500 : JSON schema set but not found or invalid

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

GET

/cxf/bpc-core/configuration/jsonschema/{moduleId}/{instanceType}/{setting}

Description

Get the JSON schema to validate a JSON based module instance setting.

Path Parameter

moduleId

the ID of the module

instanceType

the instance type. set to 'none' when the module does not support instance types

setting

the name of the setting

Returns

The requested data as JSON

HTTP Status Code

  • 200 : OK

  • 404 : Module not found or when it is a non instantiable module

  • 404 : Module configuration missing

  • 404 : Setting not found

  • 500 : Setting without set JSON schema

  • 500 : JSON schema set but not found or invalid

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

Configuration File API

These are the endpoints to set properties in the BPC related Karaf properties file: etc/de.virtimo.bpc.core.cfg

Method Endpoint

PUT

/cxf/bpc-core/configuration/local/{propertyName}

Description

Sets a property in the local BPC related Karaf properties file: etc/de.virtimo.bpc.core.cfg.

Required Role and Right:

  • Role : SERVER_ADMIN

  • Right : SERVER_SET_LOCAL_PROPERTY

Path Parameter

propertyName

the name of the property

Query Parameter

value

the value of the property

type

the type of the property

force

by default only existing properties can be updated, set to true to add new ones

Returns

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

Can be used without a user session.

PUT

/cxf/bpc-core/configuration/server/{serverUUID}/{propertyName}

Description

Sets a property in the remote BPC related Karaf properties file: etc/de.virtimo.bpc.core.cfg.

Path Parameter

serverUUID

the UUID of the remote BPC server

propertyName

the name of the property

Query Parameter

value

the value of the property

type

the type of the property

force

by default only existing properties can be updated, set to true to add new ones

Returns

The response of the remote BPC.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : SERVER_ADMIN

  • Right : SERVER_SET_REMOTE_PROPERTY

Data Lock API

These are the data lock endpoints which are tight tied to OpenSearch (responses). Please try to use the storage endpoints instead.

Method Endpoint

GET

/cxf/bpc-core/datalock

Description

Get data lock items from the OpenSearch index bpc-datalock.

Query Parameter

start

first record to be read. Default is 0.

limit

number of records to read. Default is 1000.

Returns

The requested items as JSON (1:1 OpenSearch response)

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

GET

/cxf/bpc-core/datalock/{itemId}

Description

Get a specific data lock item from the OpenSearch index bpc-datalock.

Path Parameter

itemId

the ID of the item

Returns

The requested item as JSON (1:1 OpenSearch response)

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

POST

/cxf/bpc-core/datalock/{itemId}

Description

Sets the provided data for a specific item. The body data is written to the OpenSearch index bpc-datalock.

Consumes

  • application/json

Path Parameter

itemId

the ID of the item to set the data for

Returns

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

PUT

/cxf/bpc-core/datalock/{itemId}

Description

Updates an item with the provided data in the body. The item gets updated in the OpenSearch index bpc-datalock.

Consumes

  • application/json

Path Parameter

itemId

the ID of the item to update

Returns

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

DELETE

/cxf/bpc-core/datalock/{itemId}

Description

Deletes a specific item from the OpenSearch index bpc-datalock.

Consumes

  • application/json

Path Parameter

itemId

the ID of the item to delete

Returns

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

Deployment API

These are the deployment endpoints.

Method Endpoint

GET

/cxf/bpc-deployment/deployment/systems

Description

Get a list of all deployment systems (= backend connections of type 'deployment_system').

Returns

The requested data as JSON

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : DEPLOYMENT_USER

  • Right : DEPLOYMENT_GET_SYSTEMS

GET

/cxf/bpc-deployment/deployment/diff

Description

Get the diff of a source deployment system or snapshot and a target deployment system.

Query Parameter

source

the backend connection ID of the source deployment system. Not necessary when snapshot is used.

target

the backend connection ID of the target deployment system

snapshot

name of an OpenSearch snapshot that should be used instead of a source deployment system. Not necessary when source is used.

Returns

The requested data as JSON.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : DEPLOYMENT_USER

  • Right : DEPLOYMENT_GET_DIFF

POST

/cxf/bpc-deployment/deployment/diff/settings

Description

Get the diff of deployment source and target settings provided in the body content.

Body:

{
  "source": [ BPC settings, ... ],
  "target": [ BPC settings, ... ]
}

Returns

The diff as JSON

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : DEPLOYMENT_USER

  • Right : DEPLOYMENT_GET_SETTINGS_DIFF

POST

/cxf/bpc-deployment/deployment/deploy

Description

Deploys the body content to the target system.

Consumes

  • application/json

Query Parameter

deploymentSourceId

the backend connection ID of the deployment source system

deploymentTargetId

the backend connection ID of the deployment target system

enableMaintenanceMode

true in case the maintenance mode should be enabled on the target system, false if not. Default is false.

validate

true in case the standard settings validation should be performed on the target system, false if it should be skipped. Default is true.

Returns

The deployment processing instructions as JSON file to download when the deploymentTargetId is set to @@@JSON@@@, otherwise the deployment response.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : DEPLOYMENT_USER

  • Right : DEPLOYMENT_EXECUTE

POST

/cxf/bpc-deployment/deployment/import

Description

Processes the deployment instructions provided by the body content.

Consumes

  • application/json

Query Parameter

enableMaintenanceMode

true in case the maintenance mode should be enabled, false if not. Default is false.

validate

true in case the standard settings validation should be performed, false if it should be skipped. Default is true.

Returns

HTTP Status Code

  • 200 : Import done

Content-Type

  • application/json

Required Access Rights

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

  • Role : DEPLOYMENT_USER

  • Right : DEPLOYMENT_EXECUTE

POST

/cxf/bpc-deployment/deployment/bundles/download

Description

To download specific bundles (JAR/WAR files) by their IDs as mime multipart data.

Body:

[ IdOfBundle1, IdOfBundle2, ... ]

Consumes

  • application/json

Returns

The bundles as mime multipart data

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : DEPLOYMENT_USER

  • Right : DEPLOYMENT_EXECUTE

GET

/cxf/bpc-deployment/deployment/bundles/download/{bundleId}

Description

To download a specific bundle (JAR/WAR files) by its ID.

Path Parameter

bundleId

the ID of the bundle to download

Returns

The bundle as data stream

HTTP Status Code

  • 200 : OK

  • 404 : Bundle was not found

  • 500 : Bundle is not downloadable

Required Access Rights

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

  • Role : DEPLOYMENT_USER

  • Right : DEPLOYMENT_EXECUTE

POST

/cxf/bpc-deployment/deployment/bundles/import

Description

Imports the bundles provided by multipart form data.

curl example
curl -X POST \
     -H 'X-APIKey: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' \
     -H 'X-InitiatedByUser: inubit' \
     -H 'X-InitiatedFromServerName: localhost' \
     -H 'X-InitiatedFromServerUUID: inubit-installer' \
     -F file=@test.jar \
     -F file=@test.war \
     'http://localhost:8181/cxf/bpc-deployment/deployment/bundles/import'

Consumes

  • multipart/form-data

Returns

HTTP Status Code

  • 200 : Bundles import done

Content-Type

  • application/json

Required Access Rights

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

  • Role : DEPLOYMENT_USER

  • Right : DEPLOYMENT_EXECUTE

POST

/cxf/bpc-deployment/deployment/bundles/import/extjs

Description

Special endpoint to import a single bundle from ExtJS by using multipart form data.

Consumes

  • multipart/form-data

Returns

ExtJS conform status info with the filename

HTTP Status Code

  • 200 : OK

  • 500 : Upload not possible

Content-Type

  • application/json

Required Access Rights

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

  • Role : DEPLOYMENT_USER

  • Right : DEPLOYMENT_EXECUTE

POST

/cxf/bpc-deployment/deployment/migrate

Description

Deployment diffs can only be done when both systems use the same model version. This endpoint converts the model configurations provided in the content body to the model version of this installation.

Consumes

  • application/json

Returns

The migrated module configurations as JSON

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : DEPLOYMENT_USER

  • Right : DEPLOYMENT_GET_MIGRATED_MODULES_CONFIG

POST

/cxf/bpc-deployment/deployment/index/{index}/copy

Description

Copy an index from one deployment system to another.

Path Parameter

index

the name of the index to copy

Query Parameter

source

the backend connection ID of the deployment source system

target

the backend connection ID of the deployment target system

blocksize

the block size used to read that number of documents from the source system at once (set too high = out of memory; too low = bad performance). Default is 2500.

deleteOnTarget

true to delete an existing index on the target system, false to fail if an index exists already. Default is false.

Returns

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : DEPLOYMENT_USER

  • Right : DEPLOYMENT_COPY_INDEX

GET

/cxf/bpc-deployment/deployment/indices

Description

Get a list of OpenSearch indices.

Returns

the index infos

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : DEPLOYMENT_USER

  • Right : DEPLOYMENT_LIST_INDICES

GET

/cxf/bpc-deployment/deployment/index/{index}/info

Description

Get some infos of an index to deploy.

Path Parameter

index

the real name of the index, no alias allowed

Returns

the index info with its settings and mapping

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : DEPLOYMENT_USER

  • Right : DEPLOYMENT_DOWNLOAD_INDEX

GET

/cxf/bpc-deployment/deployment/index/{index}/download

Description

Downloads the first block of data from the given index.

Path Parameter

index

the name of the index

Query Parameter

blocksize

the block size. Default is 2500.

Returns

the requested data

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : DEPLOYMENT_USER

  • Right : DEPLOYMENT_DOWNLOAD_INDEX

GET

/cxf/bpc-deployment/deployment/index/{index}/download/{scrollid}

Description

Downloads the subsequent block of data from the given index.

Path Parameter

index

the name of the index

scrollid

the scroll identifier

Returns

the requested data

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : DEPLOYMENT_USER

  • Right : DEPLOYMENT_DOWNLOAD_INDEX

DELETE

/cxf/bpc-deployment/deployment/index/{index}/download/{scrollid}

Description

To release a no longer used scroll identifier. This helps OpenSearch to release resources much faster.

Path Parameter

index

the index name

scrollid

the scroll identifier to release

Returns

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : DEPLOYMENT_USER

  • Right : DEPLOYMENT_DOWNLOAD_INDEX

POST

/cxf/bpc-deployment/deployment/index/{index}/prepare

Description

Prepares an index for upload. Creates it with the given settings and mapping.

Body:

{
  "settings": settings as JSON object,
  "mapping": mapping as JSON object
}

Consumes

  • application/json

Path Parameter

index

the name of the index (must be an alias)

Query Parameter

delete_existing

true to delete an existing index, false to throw an error when it exists already. Default is false.

Returns

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : DEPLOYMENT_USER

  • Right : DEPLOYMENT_UPLOAD_INDEX

POST

/cxf/bpc-deployment/deployment/index/{index}/upload

Description

Feed an index with the uploaded data.

Body:

[
  {"id": document id 1, "source": JSON data 1},
  {"id": document id 2, "source": JSON data 2},
  ...
]

Consumes

  • application/json

Path Parameter

index

the name of the index (must be an alias)

Returns

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : DEPLOYMENT_USER

  • Right : DEPLOYMENT_UPLOAD_INDEX

Event API

These are the endpoints of the BPC events.

Method Endpoint

POST

/cxf/bpc-core/event

Description

To send a new event, send a JSON message with the following structure:

{
    "topic": "exampleTopic",
    "data": {
        "key1": "value1",
        "key2": "value2"
    },
    "recipients": {
        "users": [ ... ],
        "roles": [ "bpcadmin" ],
        "organizations": [ "virtimo" ]
    }
}

Fields

topic (required)

The topic of the event.

data (required)

The data of the event.

recipients (optional)

The recipients of the event. Users, roles, or organizations can be specified.

Consumes

  • application/json

Returns

HTTP Status Code

  • 201 : Created

  • 401 : Authentication could not be performed

  • 403 : No access rights

  • 500 : Internal server error

Required Access Rights

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

  • Role : EVENT_API_ADMIN

  • Right : EVENT_API_SEND

Flow API

These are the endpoints to communicate with Flow.

Method Endpoint

GET

/cxf/bpc-flow/flow/{instanceId}\{targetPath: (/.*)?}

Description

Perform an HTTP GET on the given flow instance.

Path Parameter

instanceId

the id of the flow instance

targetPath

the path to call on the Flow system

Query Parameter

targetUrl

optional URL parameter. Function equals targetPath

Returns

The response of the called Flow system

Required Access Rights

A logged in user or API Key is required.

POST

/cxf/bpc-flow/flow/{instanceId}\{targetPath: (/.*)?}

Description

Perform an HTTP POST on the given flow instance.

Path Parameter

instanceId

the id of the flow instance

targetPath

the path to call on the Flow system

Query Parameter

targetUrl

optional URL parameter. Function equals targetPath

Returns

The response of the called Flow system

Required Access Rights

A logged in user or API Key is required.

PUT

/cxf/bpc-flow/flow/{instanceId}\{targetPath: (/.*)?}

Description

Perform an HTTP PUT on the given flow instance.

Path Parameter

instanceId

the id of the flow instance

targetPath

the path to call on the Flow system

Query Parameter

targetUrl

optional URL parameter. Function equals targetPath

Returns

The response of the called Flow system

Required Access Rights

A logged in user or API Key is required.

DELETE

/cxf/bpc-flow/flow/{instanceId}\{targetPath: (/.*)?}

Description

Perform an HTTP DELETE on the given flow instance.

Path Parameter

instanceId

the id of the flow instance

targetPath

the path to call on the Flow system

Query Parameter

targetUrl

optional URL parameter. Function equals targetPath

Returns

The response of the called Flow system

Required Access Rights

A logged in user or API Key is required.

Frontend Logging API

These are the frontend logging endpoints.

Method Endpoint

POST

/cxf/bpc-core/frontendLogging/{sessionId}

Description

Saves the logs provided in the body to the OpenSearch index bpc-frontend-logging.

Path Parameter

sessionId

the id of the session

Returns

HTTP Status Code

  • 200 : OK

Required Access Rights

A logged in user or API Key is required.

Global Search API

These are the endpoints for the global search frontend.

Method Endpoint

GET

/cxf/bpc-globalsearch/search/{instanceId}/search

Description

To perform a search over multiple indices and modules.

Path Parameter

instanceId

the id of the related global search instance

Query Parameter

query

the query to perform the search for

start

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

limit

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

indices

to limit the search only to those specific indices (separate multiple values with a comma)

modules

to search only in the OpenSearch indices of these modules (separate multiple values with a comma)

adminSearch

flag to perform a search on the bpc-configuration index. Get used only for users with the 'bpcadmin' role (optional, default = false). Default is false.

Returns

The response for the global search.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

Http Proxy API

These are the endpoints for proxy http requests to other systems.

Method Endpoint

GET

/cxf/bpc-httpproxy/httpProxy/{instanceId}\{targetPath: (/.*)?}

Description

Perform an HTTP GET on the 'httpproxy' backend connection.

Path Parameter

instanceId

the id of the 'httpproxy' backend connections instance to use

targetPath

the path to call on the target system

Query Parameter

targetUrl

optional URL Parameter. Function equals targetPath

Returns

The response of the called backend connection

HTTP Status Code

  • 200 : OK

  • 404 : One of the used services is not available

  • 404 : The backend connections module is not available

  • 404 : The backend connections module instance is not available

  • 500 : General problem with the backend system

  • 503 : Connection to backend system refused

  • 504 : Connection to backend system timed out

Required Access Rights

A logged in user or API Key is required.

POST

/cxf/bpc-httpproxy/httpProxy/{instanceId}\{targetPath: (/.*)?}

Description

Perform an HTTP POST on the 'httpproxy' backend connection.

Path Parameter

instanceId

the id of the 'httpproxy' backend connections instance to use

targetPath

the path to call on the target system

Query Parameter

targetUrl

optional URL Parameter. Function equals targetPath

Returns

The response of the called backend connection

HTTP Status Code

  • 200 : OK

  • 404 : One of the used services is not available

  • 404 : The backend connections module is not available

  • 404 : The backend connections module instance is not available

  • 500 : General problem with the backend system

  • 503 : Connection to backend system refused

  • 504 : Connection to backend system timed out

Required Access Rights

A logged in user or API Key is required.

PUT

/cxf/bpc-httpproxy/httpProxy/{instanceId}\{targetPath: (/.*)?}

Description

Perform an HTTP PUT on the 'httpproxy' backend connection.

Path Parameter

instanceId

the id of the 'httpproxy' backend connections instance to use

targetPath

the path to call on the target system

Query Parameter

targetUrl

optional URL Parameter. Function equals targetPath

Returns

The response of the called backend connection

HTTP Status Code

  • 200 : OK

  • 404 : One of the used services is not available

  • 404 : The backend connections module is not available

  • 404 : The backend connections module instance is not available

  • 500 : General problem with the backend system

  • 503 : Connection to backend system refused

  • 504 : Connection to backend system timed out

Required Access Rights

A logged in user or API Key is required.

DELETE

/cxf/bpc-httpproxy/httpProxy/{instanceId}\{targetPath: (/.*)?}

Description

Perform an HTTP DELETE on the 'httpproxy' backend connection.

Path Parameter

instanceId

the id of the 'httpproxy' backend connections instance to use

targetPath

the path to call on the target system

Query Parameter

targetUrl

optional URL Parameter. Function equals targetPath

Returns

The response of the called backend connection

HTTP Status Code

  • 200 : OK

  • 404 : One of the used services is not available

  • 404 : The backend connections module is not available

  • 404 : The backend connections module instance is not available

  • 500 : General problem with the backend system

  • 503 : Connection to backend system refused

  • 504 : Connection to backend system timed out

Required Access Rights

A logged in user or API Key is required.

Identity Management API

These are the identity management endpoints. Please note, that not all functions are supported by all identity providers. In case a function is not supported, a UnsupportedOperationException gets thrown. All calls - except the GET methods - are logged in the audit log.

Method Endpoint

GET

/cxf/bpc-core/im/users

Description

Get a list of all users as JSON.

When used with Keycloak one of these Keycloak roles are needed: admin, realm-admin, manage-users, query-users

Returns

The requested data as JSON.

Example response
[
  {
    "id": "bpcadmin",
    "userName": "bpcadmin",
    "displayName": "bpcadmin",
    "firstName": "Timo",
    "lastName": "Virt",
    "email": "bpcadmin@example.com"
  },
  {
    "id": "of",
    "userName": "of",
    "displayName": "of",
    "firstName": "Oliver",
    "lastName": "Fürniß",
    "email": "of@virtimo.de"
  }
]

HTTP Status Code

  • 200 : OK

  • 500 : No identity manager found or another failure

  • 503 : Not supported by the used identity provider

Content-Type

  • application/json; charset=UTF-8

Required Access Rights

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

  • Role : IDENTITY_MANAGER_ADMIN

  • Right : IDENTITY_MANAGER_USERS_READ

POST

/cxf/bpc-core/im/users

Description

Add a user by providing the data as JSON in the body.

When used with Keycloak one of these Keycloak roles are needed: admin, realm-admin, manage-users

Example body
{
  "id": "42",
  "password": "1234567890",
  "firstName": "Hans",
  "lastName": "Schmidt",
  "email": "hans.schmidt@example.com"
}

Consumes

  • application/json

Returns

HTTP Status Code

  • 200 : OK

  • 500 : Mandatory user id not given

  • 500 : Mandatory password not given

  • 500 : No identity manager found or another failure

  • 503 : Not supported by the used identity provider

Required Access Rights

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

  • Role : IDENTITY_MANAGER_ADMIN

  • Right : IDENTITY_MANAGER_USERS_ADD

PUT

/cxf/bpc-core/im/users/{userId}

Description

Update a user by providing the data as JSON in the body.

When used with Keycloak one of these Keycloak roles are needed: admin, realm-admin, manage-users

Example body
{
  "firstName": "Hans",
  "lastName": "Test",
  "email": "hans.test@example.com"
}

Consumes

  • application/json

Path Parameter

userId

the ID of the user to update

Returns

HTTP Status Code

  • 200 : OK

  • 500 : Mandatory user id not given

  • 500 : No identity manager found or another failure

  • 503 : Not supported by the used identity provider

Required Access Rights

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

  • Role : IDENTITY_MANAGER_ADMIN

  • Right : IDENTITY_MANAGER_USERS_UPDATE

PATCH

/cxf/bpc-core/im/users/{userId}

Description

Update the password of a user.

When used with Keycloak one of these Keycloak roles are needed: admin, realm-admin, manage-users

Example form
password=<new password>

Path Parameter

userId

the ID of the user

Form Parameter

password

the users new password

Returns

HTTP Status Code

  • 200 : OK

  • 500 : Mandatory user id not given

  • 500 : Mandatory user password not given

  • 500 : No identity manager found or another failure

  • 503 : Not supported by the used identity provider

Required Access Rights

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

  • Role : IDENTITY_MANAGER_ADMIN

  • Right : IDENTITY_MANAGER_USERS_UPDATE

DELETE

/cxf/bpc-core/im/users/{userId}

Description

Delete a user.

When used with Keycloak one of these Keycloak roles are needed: admin, realm-admin, manage-users

Path Parameter

userId

the ID of the user to delete

Returns

HTTP Status Code

  • 200 : OK

  • 500 : Mandatory user id not given

  • 500 : No identity manager found or another failure

  • 503 : Not supported by the used identity provider

Required Access Rights

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

  • Role : IDENTITY_MANAGER_ADMIN

  • Right : IDENTITY_MANAGER_USERS_UPDATE

GET

/cxf/bpc-core/im/organisations

Description

Get all organisations as JSON array.

When used with Keycloak one of these Keycloak roles are needed: admin, realm-admin, manage-users, view-users, query-groups

Returns

The requested data.

Example response
[
  "virtimo",
  "users",
  "admins"
]

HTTP Status Code

  • 200 : OK

  • 500 : No identity manager found or another failure

  • 503 : Not supported by the used identity provider

Content-Type

  • application/json; charset=UTF-8

Required Access Rights

A logged in user or API Key is required.

GET

/cxf/bpc-core/im/roles

Description

Get all roles as JSON array.

When used with Keycloak one of these Keycloak roles are needed: admin, realm-admin, manage-realm, view-realm, query-clients, query-users, query-groups, query-realms, manage-clients, view-clients

Returns

The requested data.

Example response
[
  "offline_access",
  "uma_authorization",
  "uma_protection",
  "bpcadmin",
  "bpcuser"
]

HTTP Status Code

  • 200 : OK

  • 500 : No identity manager found or another failure

  • 503 : Not supported by the used identity provider

Content-Type

  • application/json; charset=UTF-8

Required Access Rights

A logged in user or API Key is required.

GET

/cxf/bpc-core/im/rights

Description

Get all rights as JSON array.

Returns

The requested data.

Example response
[
  "IDENTITY_MANAGER_USER_ORGANISATIONS_READ",
  "CUSTOM_RIGHT"
]

HTTP Status Code

  • 200 : OK

  • 500 : No identity manager found or another failure

  • 503 : Not supported by the used identity provider

Content-Type

  • application/json; charset=UTF-8

Required Access Rights

A logged in user or API Key is required.

GET

/cxf/bpc-core/im/users/{userId}/organisations

Description

Get the organisations of a user as JSON array.

When used with Keycloak one of these Keycloak roles are needed: admin, realm-admin, manage-users, (view-users AND query-users)

Path Parameter

userId

the ID of the user

Returns

The requested data.

Example response
[
  "virtimo"
]

HTTP Status Code

  • 200 : OK

  • 500 : User does not exist

  • 500 : No identity manager found or another failure

  • 503 : Not supported by the used identity provider

Content-Type

  • application/json; charset=UTF-8

Required Access Rights

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

  • Role : IDENTITY_MANAGER_ADMIN

  • Right : IDENTITY_MANAGER_USER_ORGANISATIONS_READ

POST

/cxf/bpc-core/im/users/{userId}/organisations

Description

Add an organisation to a user by providing the data as JSON in the body.

Example body
{
  "id": "virtimo"
}

Consumes

  • application/json

Path Parameter

userId

the ID of the user

Returns

HTTP Status Code

  • 200 : OK

  • 500 : Mandatory user id not given

  • 500 : Mandatory organisation not given

  • 500 : No identity manager found or another failure

  • 503 : Not supported by the used identity provider

Required Access Rights

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

  • Role : IDENTITY_MANAGER_ADMIN

  • Right : IDENTITY_MANAGER_USERS_UPDATE

DELETE

/cxf/bpc-core/im/users/{userId}/organisations/{organisationName}

Description

Delete the organisation of a user.

Path Parameter

userId

the ID of the user

organisationName

the name of the organisation to delete

Returns

HTTP Status Code

  • 200 : OK

  • 500 : Mandatory user id not given

  • 500 : Mandatory organisation not given

  • 500 : No identity manager found or another failure

  • 503 : Not supported by the used identity provider

Required Access Rights

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

  • Role : IDENTITY_MANAGER_ADMIN

  • Right : IDENTITY_MANAGER_USERS_UPDATE

GET

/cxf/bpc-core/im/users/{userId}/roles

Description

Get the roles of a user as JSON array.

When used with Keycloak one of these Keycloak roles are needed: admin, realm-admin, manage-users, (view-users AND query-users)

Path Parameter

userId

the id of the user

Returns

The requested data.

Example response
[
  "EAI Developer",
  "System Administrator"
]

HTTP Status Code

  • 200 : OK

  • 500 : User does not exist

  • 500 : No identity manager found or another failure

  • 503 : Not supported by the used identity provider

Content-Type

  • application/json; charset=UTF-8

Required Access Rights

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

  • Role : IDENTITY_MANAGER_ADMIN

  • Right : IDENTITY_MANAGER_USER_ROLES_READ

POST

/cxf/bpc-core/im/users/{userId}/roles

Description

Add a role to a user by providing the data as JSON in the body.

Example body
{
  "id": "EAI Developer"
}

Consumes

  • application/json

Path Parameter

userId

the ID of the user

Returns

HTTP Status Code

  • 200 : OK

  • 500 : Mandatory user id not given

  • 500 : Mandatory role not given

  • 500 : No identity manager found or another failure

  • 503 : Not supported by the used identity provider

Required Access Rights

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

  • Role : IDENTITY_MANAGER_ADMIN

  • Right : IDENTITY_MANAGER_USERS_UPDATE

DELETE

/cxf/bpc-core/im/users/{userId}/roles/{roleName}

Description

Delete the role of a user.

Consumes

  • application/json

Path Parameter

userId

the ID of the user

roleName

the name of the role to delete

Returns

HTTP Status Code

  • 200 : OK

  • 500 : Mandatory user id not given

  • 500 : Mandatory role not given

  • 500 : No identity manager found or another failure

  • 503 : Not supported by the used identity provider

Required Access Rights

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

  • Role : IDENTITY_MANAGER_ADMIN

  • Right : IDENTITY_MANAGER_USERS_UPDATE

GET

/cxf/bpc-core/im/users/{userId}/rights

Description

Get the rights of a user as JSON array.

Path Parameter

userId

the id of the user

Returns

The requested data.

Example response
[
  "CUSTOM_RIGHT1",
  "CUSTOM_RIGHT2"
]

HTTP Status Code

  • 200 : OK

  • 500 : User does not exist

  • 500 : No identity manager found or another failure

  • 503 : Not supported by the used identity provider

Content-Type

  • application/json; charset=UTF-8

Required Access Rights

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

  • Role : IDENTITY_MANAGER_ADMIN

  • Right : IDENTITY_MANAGER_USER_RIGHTS_READ

POST

/cxf/bpc-core/im/users/{userId}/rights

Description

Add a right to a user by providing the data as JSON in the body.

Example body
{
  "id": "CUSTOM_RIGHT3"
}

Consumes

  • application/json

Path Parameter

userId

the ID of the user

Returns

HTTP Status Code

  • 200 : OK

  • 500 : Mandatory user id not given

  • 500 : Mandatory right not given

  • 500 : No identity manager found or another failure

  • 503 : Not supported by the used identity provider

Required Access Rights

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

  • Role : IDENTITY_MANAGER_ADMIN

  • Right : IDENTITY_MANAGER_USERS_UPDATE

DELETE

/cxf/bpc-core/im/users/{userId}/rights/{rightName}

Description

Delete the right of a user.

Consumes

  • application/json

Path Parameter

userId

the ID of the user

rightName

the name of the right to delete

Returns

HTTP Status Code

  • 200 : OK

  • 500 : Mandatory user id not given

  • 500 : Mandatory right not given

  • 500 : No identity manager found or another failure

  • 503 : Not supported by the used identity provider

Required Access Rights

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

  • Role : IDENTITY_MANAGER_ADMIN

  • Right : IDENTITY_MANAGER_USERS_UPDATE

GET

/cxf/bpc-core/im/users/{userId}

Description

Get the data of a user.

When used with Keycloak one of these Keycloak roles are needed: admin, realm-admin, manage-users, (query-users and view-users)

Path Parameter

userId

the ID of the user

Returns

The requested data.

Example response
{
  "id": "66",
  "userName": "of",
  "firstName": "Oliver",
  "lastName": "Fürniß",
  "displayName": "of",
  "email": "of@virtimo.de",
  "organisations": [
    "virtimo"
  ],
  "roles": [
    "bpcadmin"
  ],
  "rights": [
    "loadModule_vam",
    "loadModule_monitor",
    "loadModule_dashboard"
  ]
}

HTTP Status Code

  • 200 : OK

  • 500 : User does not exist

  • 500 : No identity manager found or another failure

  • 503 : Not supported by the used identity provider

Content-Type

  • application/json; charset=UTF-8

Required Access Rights

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

  • Role : IDENTITY_MANAGER_ADMIN

  • Right : IDENTITY_MANAGER_USER_READ

Internationalization API

These are the internationalization endpoints.

Method Endpoint

GET

/cxf/bpc-core/i18n/languages

Description

Get the languages used by the translations.

Query Parameter

only_keys

true to get only the keys, false to get a more detailed list. Default is false.

Returns

The languages as JSON. Example response when only_keys=false

[
    {
        "nativeName": "Deutsch",
        "name": "Deutsch",
        "id": "de"
    },
    {
        "nativeName": "English",
        "name": "Englisch",
        "id": "en"
    },
    {
        "nativeName": "français",
        "name": "Französisch",
        "id": "fr"
    }
]

Example response when only_keys=true

[
  "de", "en", "fr"
]

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

Can be used without a user session.

GET

/cxf/bpc-core/i18n/languages/all

Description

Get all supported languages.

Query Parameter

only_keys

true to get only the keys, false to get a more detailed list. Default is false.

Returns

The languages as JSON. Example response when only_keys=false

[
    {
        "nativeName": "Deutsch",
        "name": "Deutsch",
        "id": "de"
    },
    {
        "nativeName": "English",
        "name": "Englisch",
        "id": "en"
    },
    ...
]

Example response when only_keys=true

[
  "de", "en", ...
]

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

Can be used without a user session.

DELETE

/cxf/bpc-core/i18n/translations

Description

Forces a re-load of the translations.

Returns

HTTP Status Code

  • 200 : OK

Required Access Rights

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

  • Role : TRANSLATIONS_ADMIN

  • Right : TRANSLATIONS_RELOAD

GET

/cxf/bpc-core/i18n/translations/{lang}

Description

Get all translations for a specific language. This is a collection of the translations found in all modules/bundles and the ones from our custom translations setting Core_CustomTranslations. In case a module/bundle does not provide translations in the requested language the translations for the default language set by the setting 'Core_TranslationsFallbackLanguage' gets used.

Path Parameter

lang

the language to get the translations for. Like 'de', 'en', 'fr' etc.

Query Parameter

ict

true to ignore the translation from the custom translations setting, false to include them. Default is false.

fallback

true to return entries in the default language as fallback when a translation key is missing in the requested language, false to return only the entries that exist in the requested language. Default is true.

Returns

JSON object with the translations. The keys are sorted in ascending order.

HTTP Status Code

  • 200 : OK

  • 404 : Language not found

Content-Type

  • application/json

Required Access Rights

Can be used without a user session.

GET

/cxf/bpc-core/i18n/language/{lang}/valid

Description

Checks if the provided language is known to the backend. Returns the default/fallback language if not.

Path Parameter

lang

the language to do the check for

Returns

The given language when valid, otherwise the default language.

Example response

{
  "language": "en"
}

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

Can be used without a user session.

Log Service API

These are the endpoints of the log service.

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 in maintenance mode

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 log service instance.

Path Parameter

instanceIdOrName

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

Query Parameter

timezoneOffset

optional

timezoneName

optional

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.

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.

addChilds

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

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

optional

timezoneName

optional

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.

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.

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

optional

timezoneName

optional

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

optional

timezoneName

optional

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

optional

timezoneName

optional

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

Loggers API

These are the endpoints to get all loggers with their log level and to set the log level.

Loggers are defined in the file: [karaf]/etc/org.ops4j.pax.logging.cfg

Method Endpoint

GET

/cxf/bpc-core/loggers/all

Description

Get all configured loggers with their currently set log level.

Returns

The requested data as JSON

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : LOGGERS_ADMIN

  • Right : LOGGERS_LIST_ALL

GET

/cxf/bpc-core/loggers/levels/valid

Description

Get a list of valid log levels.

Returns

The requested data as JSON

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : LOGGERS_ADMIN

  • Right : LOGGERS_LIST_VALID_LEVELS

POST

/cxf/bpc-core/loggers/level

Description

Set the log level a specific logger.

Form Parameter

logger

the name of the logger to set the log level for

level

the log level to set. Like INFO, WARN, ERROR, …​

Returns

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : LOGGERS_ADMIN

  • Right : LOGGERS_SET_LEVEL

Lookup Joins API

These are the lookup joins endpoints.

Method Endpoint

POST

/cxf/bpc-core/configuration/lookupjoins/refresh

Description

Refresh the lookup joins data of all replication jobs and log services related indices.

Returns

HTTP Status Code

  • 200 : OK

Required Access Rights

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

  • Role : LOOKUP_JOINS_ADMIN

  • Right : LOOKUP_JOINS_REFRESH_ALL

POST

/cxf/bpc-core/configuration/lookupjoins/refresh/replicationjob/{replicationJobId}

Description

Refresh the lookup joins data of a replication job related index.

Path Parameter

replicationJobId

the ID of the replication job

Returns

HTTP Status Code

  • 200 : OK

Required Access Rights

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

  • Role : LOOKUP_JOINS_ADMIN

  • Right : LOOKUP_JOINS_REFRESH

POST

/cxf/bpc-core/configuration/lookupjoins/refresh/logservice/{logServiceId}

Description

Refresh the lookup joins data of a log service related index.

Path Parameter

logServiceId

the ID of the log service

Returns

HTTP Status Code

  • 200 : OK

Required Access Rights

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

  • Role : LOOKUP_JOINS_ADMIN

  • Right : LOOKUP_JOINS_REFRESH

GET

/cxf/bpc-core/configuration/lookupjoins/clearcaches

Description

Clears the internally used lookup joins caches.

Returns

HTTP Status Code

  • 200 : OK

Required Access Rights

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

  • Role : LOOKUP_JOINS_ADMIN

  • Right : LOOKUP_JOINS_CLEAR_CACHE

Notification API

These are the notification endpoints.

Method Endpoint

POST

/cxf/bpc-core/notification

Description

To add a notification, send a JSON message with the following structure:

Minimal example
{
  "subject": "Replication problem",
  "message": "The database 'postgresql' is not reachable",
  "recipients": [ "bpcadmin" ],
  "recipientsType": "role"
}
More complex example
{
    "priority": 10,
    "subject": "API expires soon",
    "message": "API Key API-39e889a expires soon. Please contact your administrator.",
    "recipients": [ "bpcadmin" ],
    "recipientsType": "role",
    "icon": "fa-file-certificate",
    "type": "link",
    "typeSpecificData": {
        "targetModule": "_core",
        "route" : ["_core", "apiKeys", "api", "API-39e889a"]
    }
}

Fields

id (optional)

ID of the notification. A random UUID gets set when not given.

priority (optional)

Delivery priority of the notification. Can be one of the following values: 0 (Silent), 5 (Toast), 10 (Popup). 5 gets used when not given.

subject (required)

The subject of the notification.

message (optional)

The message of the notification.

recipients (required)

The recipients of the notification. Depends on the used recipientsType.

recipientsType (required)

The recipients type of the notification. Can be one of the following values: user, role or organisation.

originator (optional)

The originator of the notification. The login name of the user session gets used when not given.

icon (optional)

The Font Awesome icon which should be used when showing the notification.

type (optional)

The type of the notification. The type 'info' gets used when not given. Other possibility are 'warn', 'error', 'link', etc. Depending on the type, the notification is displayed accordingly in the GUI (see also Notifikationstypen und Darstellung in der Oberfläche).

typeSpecificData (optional)

The additional type specific data of the notification.

Consumes

  • application/json

Returns

The added notification as JSON. Contains additionally the 'date' and 'version' fields which get automatically set/updated.

HTTP Status Code

  • 200 : OK

  • 404 : Required service was not found

  • 500 : Unexpected backend error

  • 503 : Maintenance mode is active

Content-Type

  • application/json

Required Access Rights

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

  • Role : NOTIFICATION_ADMIN

  • Right : NOTIFICATION_ADD

PUT

/cxf/bpc-core/notification/{notificationId}

Description

To update a notification, send a JSON message with the following structure:

Minimal example
{
  "subject": "Replication problem",
  "message": "The database 'postgresql' is not reachable",
  "recipients": [ "bpcadmin" ],
  "recipientsType": "role"
}
More complex example
{
    "priority": 10,
    "subject": "API expires soon",
    "message": "API Key API-39e889a expires soon. Please contact your administrator.",
    "recipients": [ "bpcadmin" ],
    "recipientsType": "role",
    "icon": "fa-file-certificate",
    "type": "link",
    "typeSpecificData": {
        "targetModule": "_core",
        "route" : ["_core", "apiKeys", "api", "API-39e889a"]
    }
}

Fields

priority (optional)

Delivery priority of the notification. Can be one of the following values: 0 (Silent), 5 (Toast), 10 (Popup). 5 gets used when not given.

subject (required)

The subject of the notification.

message (optional)

The message of the notification.

recipients (required)

The recipients of the notification. Depends on the used recipientsType.

recipientsType (required)

The recipients type of the notification. Can be one of the following values: user, role or organisation.

originator (optional)

The originator of the notification. The login name of the user session gets used when not given.

icon (optional)

The Font Awesome icon which should be used when showing the notification.

type (optional)

The type of the notification. The type 'info' gets used when not given. Other possibility are 'warn', 'error', 'link', etc. Depending on the type, the notification is displayed accordingly in the GUI (see also Notifikationstypen und Darstellung in der Oberfläche).

typeSpecificData (optional)

The additional type specific data of the notification.

Consumes

  • application/json

Path Parameter

notificationId

the ID of the notification to update

Returns

The updated notification as JSON. Contains additionally the 'date' and 'version' fields which get automatically set/updated.

HTTP Status Code

  • 200 : OK

  • 404 : Required service was not found

  • 500 : Unexpected backend error

  • 503 : Maintenance mode is active

Content-Type

  • application/json

Required Access Rights

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

  • Role : NOTIFICATION_ADMIN

  • Right : NOTIFICATION_UPDATE

DELETE

/cxf/bpc-core/notification/{notificationId}

Description

Delete a specific notification.

Path Parameter

notificationId

the ID of the notification to delete

Returns

The deleted notification as JSON.

HTTP Status Code

  • 200 : OK

  • 404 : Required service was not found

  • 404 : Requested notification was not found

  • 500 : Unexpected backend error

  • 503 : Maintenance mode is active

Content-Type

  • application/json

Required Access Rights

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

  • Role : NOTIFICATION_ADMIN

  • Right : NOTIFICATION_DELETE

GET

/cxf/bpc-core/notification/{notificationId}

Description

Get the data of a notification.

Path Parameter

notificationId

the ID of the notification to get the data for

Returns

The data of the requested notification as JSON.

HTTP Status Code

  • 200 : OK

  • 404 : Required service was not found

  • 404 : Requested notification was not found or no access rights

  • 500 : Unexpected backend error

  • 503 : Maintenance mode is active

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

GET

/cxf/bpc-core/notification

Description

Get the notification of the requesting user.

Query Parameter

start

paging start parameter. Default is 0.

limit

number of notifications to get. Default is 1000.

Returns

The requested notifications of the user as JSON.

HTTP Status Code

  • 200 : OK

  • 404 : Required service was not found

  • 500 : Unexpected backend error

  • 503 : Maintenance mode is active

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

OpenSearch API

These are the OpenSearch endpoints.

Method Endpoint

GET

/cxf/bpc-core/opensearch/indices

Description

Get a list of all OpenSearch indices.

Returns

The requested data as JSON

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : OPENSEARCH_ADMIN

  • Right : OPENSEARCH_LIST_INDICES

GET

/cxf/bpc-core/opensearch/indices/compact

Description

Get a compact list of OpenSearch indices. Can be used for example in a combo box.

Returns

The requested data as JSON

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

GET

/cxf/bpc-core/opensearch/indices/mapping/{indexName}

Description

Get the settings and mappings of an OpenSearch index.

Path Parameter

indexName

the name of the index

Returns

The requested data as JSON

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : OPENSEARCH_ADMIN

  • Right : OPENSEARCH_GET_MAPPING

DELETE

/cxf/bpc-core/opensearch/indices/operations/{indexName}

Description

Delete an OpenSearch index.

Path Parameter

indexName

the name of the index to delete

Returns

HTTP Status Code

  • 200 : OK

Required Access Rights

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

  • Role : OPENSEARCH_ADMIN

  • Right : OPENSEARCH_DELETE_INDEX

GET

/cxf/bpc-core/opensearch/indices/reindex/{indexName}

Description

Get the information what a reindex action would do with the index settings and mappings.

Path Parameter

indexName

the name of the index

Query Parameter

copyIndexMapping

true to copy the index mapping, otherwise false. Default is true.

copyMetaData

true to copy the meta data, otherwise false. Default is true.

Returns

The old and new index settings and mappings as JSON

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : OPENSEARCH_ADMIN

  • Right : OPENSEARCH_REINDEX

POST

/cxf/bpc-core/opensearch/indices/reindex/{indexName}

Description

Perform a reindex action.

Path Parameter

indexName

the name of the index to reindex

Query Parameter

copyIndexMapping

true to copy the index mapping, otherwise false. Default is true.

copyMetaData

true to copy the meta data, otherwise false. Default is true.

deleteSourceIndexAfterwards

true to delete the source index afterwards, false to close it instead. Default is false.

Returns

HTTP Status Code

  • 200 : OK

Required Access Rights

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

  • Role : OPENSEARCH_ADMIN

  • Right : OPENSEARCH_REINDEX

Performance Measurement API

These are the performance measurement endpoints.

Method Endpoint

POST

/cxf/bpc-core/performance/{sessionId}

Description

Saves the measurements provided in the body to the OpenSearch index bpc-performance.

Path Parameter

sessionId

the id of the session

Returns

HTTP Status Code

  • 204 : No content

Required Access Rights

A logged in user or API Key is required.

Replication API

These are the replication endpoints.

Method Endpoint

GET

/cxf/bpc-core/replication/jobs/usingindex/{dataIndex}/monitor

Description

Get the replication jobs with runtime stats indexing into the given OpenSearch index. The response will be compact and used by the BPC monitor frontend.

Is without access rights check at the moment, because this endpoint gets called from the frontend monitor.

Path Parameter

dataIndex

the name of the OpenSearch index

Returns

The requested data as JSON

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

Can be used without a user session.

PUT

/cxf/bpc-core/replication/{replicationJobId}/restart

Description

Restarts a replication job.

Path Parameter

replicationJobId

the ID of the replication job

Returns

HTTP Status Code

  • 200 : OK

Required Access Rights

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

  • Role : REPLICATION_ADMIN

  • Right : REPLICATION_JOB_RESTART

PUT

/cxf/bpc-core/replication/{replicationJobId}/start

Description

Forced start of a replication job.

Path Parameter

replicationJobId

the ID of the replication job

Returns

HTTP Status Code

  • 200 : OK

Required Access Rights

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

  • Role : REPLICATION_ADMIN

  • Right : REPLICATION_JOB_FORCED_START

Server API

These are the BPC server endpoints. Please be sure that every BPC server in the cluster uses a unique UUID. This is done by the setting de.virtimo.bpc.core.karaf.uuid which can found in the config file [karaf]/etc/de.virtimo.bpc.core.cfg.

Method Endpoint

GET

/cxf/bpc-core/server/list

Description

Get the UUIDs of the BPC servers in the cluster.

Returns

The requested data as JSON.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Role : SERVER_ADMIN

  • Right : SERVER_GET_UUIDS

GET

/cxf/bpc-core/server/{uuid}/info

Description

Get detailed info of a BPC server in the cluster.

Path Parameter

uuid

the UUID of the BPC server to get the infos for

Returns

The requested data as JSON.

HTTP Status Code

  • 200 : OK

  • 404 : Requested server not found

Content-Type

  • application/json

Required Access Rights

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

  • Role : SERVER_ADMIN

  • Right : SERVER_GET_INFO

Status API

These are the status endpoints.

Method Endpoint

GET

/cxf/bpc-core/status

Description

Get the status of the local BPC server.

Returns

Depending on the user session more or less data is returned as JSON.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

Can be used without a user session.

GET

/cxf/bpc-core/status/server/{serverUUID}

Description

Get the status of a remote BPC server.

Path Parameter

serverUUID

the UUID of the BPC server to get the status for

Returns

The requested data as JSON.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

Can be used without a user session.

GET

/cxf/bpc-core/status/health

Description

Get the following health infos in one call:

  • status of loaded bundles

  • maintenance mode status

  • OpenSearch status

Returns

HTTP Status Code

  • 200 : When all 3 health status are fine

  • 503 : When not all 3 health status are fine

Required Access Rights

Can be used without a user session.

GET

/cxf/bpc-core/status/bpc

Description

Get the status of all loaded BPC modules/bundles.

Returns

HTTP Status Code

  • 200 : Karaf is running and all BPC modules are not in state 'Resolved' and not in state 'Failure`

  • 503 : At least one BPC module is in state 'Resolved' or 'Failure'

Required Access Rights

Can be used without a user session.

GET

/cxf/bpc-core/status/maintenance

Description

Get the maintenance mode status.

Returns

HTTP Status Code

  • 200 : BPC is not in maintenance mode

  • 503 : BPC is in maintenance mode

Required Access Rights

Can be used without a user session.

GET

/cxf/bpc-core/status/opensearch

Description

Get the OpenSearch status.

Returns

HTTP Status Code

  • 200 : OK

  • 503 : No connection to OpenSearch

  • 503 : No nodes available

  • 503 : Cluster health status is 'red'

Required Access Rights

Can be used without a user session.

GET

/cxf/bpc-core/status/sessions

Description

Get a list of all sessions.

Returns

The requested data as JSON.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

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

  • Right : getSessionStatus

GET

/cxf/bpc-core/status/clustermaster

Description

To check if this is the BPC master server.

Returns

HTTP Status Code

  • 200 : BPC is the master server

  • 503 : BPC is not the master server

Required Access Rights

Can be used without a user session.

Storage API

These are the storage endpoints.

Method Endpoint

GET

/cxf/bpc-core/storage/store/{storeId}

Description

Get store items from the OpenSearch index bpc-store-<storeId>. Returns empty response when the store does not exist.

Path Parameter

storeId

the ID of the store to get the items from

Query Parameter

timezoneOffset

optional

timezoneName

optional

start

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

limit

number of records to read (optional, default = 1000, max. 10.000). Default is 1000.

query

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

filter

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

sort

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

Returns

The requested store items as JSON

HTTP Status Code

  • 200 : OK

  • 404 : OpenSearch service not found

  • 500 : Given JSON could not be parsed

  • 500 : Something went wrong while accessing OpenSearch

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

GET

/cxf/bpc-core/storage/store/{storeId}/{itemId}

Description

Get a specific store item from the OpenSearch index bpc-store-<storeId>.

Path Parameter

storeId

the ID of the store to get the data from

itemId

the ID of the item

Returns

The requested store item as JSON

HTTP Status Code

  • 200 : OK

  • 403 : No access rights

  • 404 : OpenSearch service not found

  • 404 : Store not found

  • 404 : Store item not found

  • 500 : Something went wrong while accessing OpenSearch

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

POST

/cxf/bpc-core/storage/store/{storeId}

Description

Creates a new store item. Writes the provided store item data to the OpenSearch index bpc-store-<storeId>. It uses a new ID for the store item and sets this also in the given store item data. Not well known elements on root level are automatically saved to the field 'customFields' to avoid OpenSearch mapping problems.

all fields example
{
  "id": "1f697af5-c147-3d94-c529-e06f3f15bb87",
  "moduleId": "monitor",
  "moduleInstanceId": "audit_log",
  "name": "data_view",
  "value": {
      "foo": "bar"
  },
  "favorite": true,
  "readRestriction" : {
      "user": "hans_schmidt",
      "organisations": [ "DEFAULT" ],
      "roles": [ "expert", "advanced", "beginner" ],
      "rights": [ "loadModule_monitor" ]
  },
  "writeRestriction" : {
      "user": "hans_schmidt",
      "organisations": [ "DEFAULT" ],
      "roles": [ "expert" ],
      "rights": [ "loadModule_monitor" ]
  },
  "customFields": {
      "foo": "bar"
  }
}

Fields

id (irrelevant)

ID of the store item. A new random UUID gets set instead.

moduleId (optional)

The ID of the module the store item belongs to. Can be used as a filter value while getting items.

moduleInstanceId (optional)

The ID of the module instance the store item belongs to. Can be used as a filter value while getting items.

name (optional)

The name of the store item (be creative). Can be used as a filter value while getting items.

value (required)

The actual value/content/data of the store item.

favorite (optional)

To flag the store item as a favorite. Defaults to false.

readRestriction (required)

The read restrictions. Define who can read this item. At least one of the sub elements should be set.

readRestriction.user (optional)

Only this username has read access to this store item. When set the other fields 'organisations', 'roles' and 'rights' are not saved.

readRestriction.organisations (optional)

Anyone with one of these organisations has read access to this store item.

readRestriction.roles (optional)

Anyone with one of these roles has read access to this store item.

readRestriction.rights (optional)

Anyone with one of these rights has read access to this store item.

writeRestriction (required)

The write restrictions. Define who can update and delete this item. At least one of the sub elements should be set.

writeRestriction.user (optional)

Only this username has write access to this store item. When set the other fields 'organisations', 'roles' and 'rights' are not saved.

writeRestriction.organisations (optional)

Anyone with one of these organisations has write access to this store item.

writeRestriction.roles (optional)

Anyone with one of these roles has write access to this store item.

writeRestriction.rights (optional)

Anyone with one of these rights has write access to this store item.

customFields (optional)

Values that do not fit into the 'value' field.

Consumes

  • application/json

Path Parameter

storeId

the ID of the store

Returns

The ID of the created store item

HTTP Status Code

  • 200 : OK

  • 403 : Store item exists already

  • 404 : OpenSearch service not found

  • 404 : Store not found

  • 406 : Mandatory fields missing

  • 500 : Store could not be created

  • 500 : Problem with the given JSON

  • 500 : Something went wrong while accessing OpenSearch

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

POST

/cxf/bpc-core/storage/store/{storeId}/{itemId}

Description

Creates or updates a store item. Writes the provided store item data in the body to the OpenSearch index bpc-store-<storeId>. An existing store item gets updated and a not existing one gets created. Not well known elements on root level are automatically saved to the field 'customFields' to avoid OpenSearch mapping problems.

all fields example
{
  "id": "1f697af5-c147-3d94-c529-e06f3f15bb87",
  "moduleId": "monitor",
  "moduleInstanceId": "audit_log",
  "name": "data_view",
  "value": {
      "foo": "bar"
  },
  "favorite": true,
  "readRestriction" : {
      "user": "hans_schmidt",
      "organisations": [ "DEFAULT" ],
      "roles": [ "expert", "advanced", "beginner" ],
      "rights": [ "loadModule_monitor" ]
  },
  "writeRestriction" : {
      "user": "hans_schmidt",
      "organisations": [ "DEFAULT" ],
      "roles": [ "expert" ],
      "rights": [ "loadModule_monitor" ]
  },
  "customFields": {
      "foo": "bar"
  }
}

Fields

id (irrelevant)

ID of the store item. The path parameter get set in the given document instead.

moduleId (optional)

The ID of the module the store item belongs to. Can be used as a filter value while getting items.

moduleInstanceId (optional)

The ID of the module instance the store item belongs to. Can be used as a filter value while getting items.

name (optional)

The name of the store item (be creative). Can be used as a filter value while getting items.

value (required)

The actual value/content/data of the store item.

favorite (optional)

To flag the store item as a favorite. Defaults to false.

readRestriction (required)

The read restrictions. Define who can read this item. At least one of the sub elements should be set.

readRestriction.user (optional)

Only this username has read access to this store item. When set the other fields 'organisations', 'roles' and 'rights' are not saved.

readRestriction.organisations (optional)

Anyone with one of these organisations has read access to this store item.

readRestriction.roles (optional)

Anyone with one of these roles has read access to this store item.

readRestriction.rights (optional)

Anyone with one of these rights has read access to this store item.

writeRestriction (required)

The write restrictions. Define who can update and delete this item. At least one of the sub elements should be set.

writeRestriction.user (optional)

Only this username has write access to this store item. When set the other fields 'organisations', 'roles' and 'rights' are not saved.

writeRestriction.organisations (optional)

Anyone with one of these organisations has write access to this store item.

writeRestriction.roles (optional)

Anyone with one of these roles has write access to this store item.

writeRestriction.rights (optional)

Anyone with one of these rights has write access to this store item.

customFields (optional)

Values that do not fit into the 'value' field.

Consumes

  • application/json

Path Parameter

storeId

the ID of the store

itemId

the ID of the item

Returns

HTTP Status Code

  • 200 : OK

  • 403 : Access rights not sufficient to update the store item

  • 404 : OpenSearch service not found

  • 404 : Store not found

  • 406 : Mandatory fields missing

  • 500 : Store could not be created

  • 500 : Problem with the given JSON

  • 500 : Something went wrong while accessing OpenSearch

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

DELETE

/cxf/bpc-core/storage/store/{storeId}/{itemId}

Description

Deletes a specific store item from the OpenSearch index bpc-store-<storeId>.

Path Parameter

storeId

the ID of the store

itemId

the ID of the item to delete

Returns

HTTP Status Code

  • 200 : OK

  • 403 : Access rights not sufficient to delete the store item

  • 404 : OpenSearch service not found

  • 404 : Store not found

  • 404 : Store item not found

  • 500 : Something went wrong while accessing OpenSearch

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.
Keywords:
Press Esc to exit full screen
Modal image placeholder
Press Esc to exit full screen