Create BPC module instances
Prerequisites
-
OpenSearch must be installed
-
Karaf must be running with the required BPC modules/bundles
In the examples below, OpenSearch uses the default port 9200 and Karaf uses the default port 8181.
Summary
-
The BPC API can be accessed either via username/password (does not work if Keycloak is used) or via an API key (preferred method).
-
The settings (JSON) for the BPC module instances to be created must be available (e.g., exported beforehand).
-
The BPC Deployment API is used to create module instances (Dashboard, Monitor, Log Service, etc.).
Creating an API Key for BPC API Calls (Version 1)
This must be done in advance either via the BPC frontend → Core Services → API Keys or by directly adding the setting in OpenSearch (if none exist; otherwise, the existing setting will be overwritten).
Add directly in OpenSearch:
curl -X POST \
-H 'Content-Type: application/json' \
"http://localhost:9200/bpc-configuration/bpc-setting/_core_noinstance_apiKeys" -d '
{
"id": "_core_noinstance_apiKeys",
"moduleId": "_core",
"instanceId": "noinstance",
"instanceType": "none",
"name": "apiKeys",
"type": "json",
"value": {
"1f697af5-c147-3d94-c529-e06f3f15bb87": {
"issuedFor": "inubit",
"issuedOn": "2020-03-16T07:00:00.000Z",
"assignedRoles": [
"bpcadmin"
],
"assignedRights": [],
"issuedBy": "bpcadmin",
"assignedOrganisations": [],
"expiresIn": "1 days"
}
}
}'
"1f697af5-c147-3d94-c529-e06f3f15bb87" is a random API key that is set as an HTTP header when calling the BPC API. Of course, you must update the "issuedOn" field to the current date. Otherwise, your request will be rejected because, in this example, it is only valid for one day.
Creating an API Key for BPC API Calls (Version 2)
This version uses the BPC login and a BPC API call to create API keys.
Log in with bpcadmin
curl -X POST \
-c cookies.txt \
-H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
"http://localhost:8181/cxf/bpc-core/authentication" \
--data-urlencode "tenantname=DEFAULT" \
--data-urlencode "username=bpcadmin" \
--data-urlencode "password=bpcadmin"
You must save the cookies and retain the X-CSRF-Token from the response. This will be used in the next step.
Check if the session is valid
curl -X GET \
-b cookies.txt \
"http://localhost:8181/cxf/bpc-core/authentication"
Check session: Server response on success
{
"organisations": [
"DEFAULT"
],
"inactiveOrganisations": [],
"roles": [
"bpcadmin",
"bpcuser"
],
"rights": [
"loadModule_blank"
],
"principals": {
"X-Csrf-Token": [
"anQdpgq-aHCHHYCfAZmn0_B7Xr-CNIBb_c3qHJ9gLQyTCavo8CLygvPMl8jcsCF45NdOeEx9AipHpBx-4r7-bASxJgzk7vL-5PGXgMNzZXl7oT6njH4Tu62YW_ad23ckmOr05nq7jzecHaYkSMHMBHqqGcW8zV7rEDpm_CkqTUY"
],
"org.apache.karaf.jaas.boot.principal.UserPrincipal": [
"bpcadmin"
]
},
"loginContext": null,
"customData": {},
"expirationDate": 1589406354988,
"firstName": "",
"lastName": "bpcadmin",
"loginName": "bpcadmin"
}
Check session: Server response in case of error
{
"error": {
"messageKey": "CORE_ERROR_IDENTITY_PROVIDER_AUTHENTICATION_FAILED",
"code": 540,
"name": "AUTHENTICATION_UNAUTHORIZED",
"message": "Authentication failed",
"properties": {}
}
}
Create the API key setting
Use the previously saved cookies and set the ` X-Csrf-Token ` to the value from the login response.
curl -X POST \
-b cookies.txt \
-H 'Content-Type: application/json' \
-H 'X-Csrf-Token: 3worAKpB4gLk5fLDbMesVPn76DbWdBvh_lQHYE0SbBzQtxGJfxVZqekxRe7MaFJ7Wj5mTsYtTX5evCM1T3rouVp89HO7_4fGZtm7gl1Zy407rjv_yZwrV8HXApJJovsFyixrf9U70Wd6qmy_BOfdlZSUG18l7cOALdTBR09u7J4' \
"http://localhost:8181/cxf/bpc-core/configuration/_core" -d '
[ {
"id" : "_core_noinstance_apiKeys",
"name" : "apiKeys",
"moduleId" : "_core",
"instanceId" : "noinstance",
"instanceType" : "none",
"type" : "json",
"value" : {
"1f697af5-c147-3d94-c529-e06f3f15bb87" : {
"expiresIn" : "1 days",
"issuedFor" : "inubit-installer",
"assignedRoles" : [ "bpcadmin" ],
"assignedOrganisations" : [ ],
"issuedBy" : "bpcadmin",
"assignedRights" : [ ],
"issuedOn" : "2020-05-07T13:19:19.544Z"
}
},
"_group" : "core",
"_readableByRoles" : [ "bpcadmin" ],
"_writeableByRoles" : [ "bpcadmin" ],
"_label" : "CORE_SETTING_LABEL_API_KEYS"
} ]'
"1f697af5-c147-3d94-c529-e06f3f15bb87" is a random API key that is set as an HTTP header when calling the BPC API. Of course, you must update the "issuedOn" field to the current date. Otherwise, your request will be rejected because—in this example—it is only valid for one day.
Requesting a New Module Instance ID
As of May 12, 2020, there is an additional API endpoint for requesting a new instance ID:
/cxf/bpc-core/configuration/{moduleId}/{instanceType}/newInstanceId
-
You must set `
{moduleId}` to the ID of the module for which the instance is to be created. -
You must set `
{instanceType}` to the correct instance type for the module instance. Set it to 'none' if the module does not support instance types.
You will receive detailed error messages (a list of supported module IDs and instance types) if the specified module ID or instance type is incorrect.
Example of an error message if you specify an incorrect module ID (in this case, 'unknown'):
curl -X GET \
-H 'X-APIKey: 1f697af5-c147-3d94-c529-e06f3f15bb87' \
'localhost:8181/cxf/bpc-core/configuration/unkonwn/none/newInstanceId'
{
"error" : {
"code" : 20,
"name" : "MODULE_NOT_FOUND",
"message" : "Please use the ID of one of the loaded and instantiable modules: backendconnection, externalContent, webtsm, logservice, collaboration, documentation, globalsearch, monitor, analysis, dashboard",
"properties" : {
"loadedInstantiableModules" : "backendconnection, externalContent, webtsm, logservice, collaboration, documentation, globalsearch, monitor, analysis, dashboard"
}
}
}
Example of an error message if you specify an incorrect instance type (in this case, 'xyz'):
curl -X GET \
-H 'X-APIKey: 1f697af5-c147-3d94-c529-e06f3f15bb87' \
'localhost:8181/cxf/bpc-core/configuration/httpproxy/xyz/newInstanceId'
{
"error" : {
"code" : 20,
"name" : "MODULE_NOT_FOUND",
"message" : "Please use one of the instance types the module 'backendconnection' supports: http_proxy, identity_provider, deployment_system, data_source",
"properties" : {
"instanceTypes" : "http_proxy, identity_provider, deployment_system, data_source",
"moduleId" : "backendconnection"
}
}
}
Example of entering correct data (a backend connection of the 'deployment_system' instance type):
curl -X GET \
-H 'X-APIKey: 1f697af5-c147-3d94-c529-e06f3f15bb87' \
'localhost:8181/cxf/bpc-core/configuration/backendconnection/deployment_system/newInstanceId'
{
"instanceId" : "1589263141954",
"instanceType" : "deployment_system",
"moduleId" : "backendconnection"
}
Settings for the module instances to be created
If you know which module instances are to be created and they already exist in another BPC installation, is the easiest way to "export" these settings.
Example of retrieving the settings for a 'logservice' module instance with the ID '1496037736378'.
curl -X GET \
-H 'Content-Type: application/json' \
-H 'X-APIKey: 1f697af5-c147-3d94-c529-e06f3f15bb87' \
"http://localhost:8181/cxf/bpc-core/configuration/logservice/1496037736378?format=json"
From the JSON response, you need the array contents of the 'settings' element.
{
"moduleName" : "Log Service",
"moduleId" : "1496037736378",
"instanceType" : "none",
"instancesDefaultConfiguration" : null
"instances" : null,
"settings" : [ {
...
}, {
...
}, {
...
} ]
}Using the Deployment API to Create Module Instances
Example of how to customize the settings of a 'logservice' module instance.
curl -X POST \
-H 'X-APIKey: 1f697af5-c147-3d94-c529-e06f3f15bb87' \
-H 'Content-Type: application/json' \
"http://localhost:8181/cxf/bpc-deployment/deployment/import?enableMaintenanceMode=false" -d '
{
"settings": {
"updateOrCreate": [
{
...
},
{
...
},
{
...
}
]
}
}'
The array contents of "updateOrCreate" must be replaced with the contents of the 'settings' element mentioned above.
Now the module instance should be created! :-)
