Create BPC module instances
Requirements
-
OpenSearch must be installed
-
Karaf with the required BPC modules/bundles must be running
In the examples below, OpenSearch uses the default port 9200 and Karaf the default port 8181.
Summary
-
The BPC API can be used either via user/password (does not work if Keycloak is used) or via an API key (preferred method).
-
The settings (JSON) of the BPC module instances to be created must be available (e.g. previously exported).
-
The BPC Deployment API is used to create module instances (dashboard, monitor, log service, …).
Create 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 inserting the setting in OpenSearch (if none exist; otherwise the existing setting will be overwritten).
Insert directly into 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 the BPC API is called. Of course, you must adjust the "issuedOn" field to the current date. Otherwise, your request will be rejected as it is only valid for one day in this example.
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.
Login 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 keep 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 API key setting
Use the previously saved cookies and set the X-Csrf-Token with the value of 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 adjust 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
There is now (12.05.2020) an additional API endpoint to request 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 of the module instance. Set it to 'none' if the module does not support instance types.
You will receive extended 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 if you specify correct data (a backend connection of instance type 'deployment_system'):
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 of the module instances to be created
If you know which module instances are to be created and these already exist in another BPC installation, the easiest way is to "export" these settings.
Example to retrieve the settings of 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 content 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 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 content of "updateOrCreate" must be replaced by the content of the 'settings' element mentioned above.
Now the module instance should be created! :-)
