Create BPC Module Instances

Prerequisites

Elasticsearch must be installed
Karaf with the used BPC modules/bundles must be running

In the examples below, Elasticsearch uses the default port 9200 and Karaf the default port 8181.

Summary

The BPC API can either be used by using user/password (does not work when Keycloak is used) or by using an API-Key (preferred way)
The settings (JSON) of the BPC module instances to be created must exist (e.g. exported upfront)
The BPC deployment API is used to create module instances (dashboard, monitor, logservice, …)

Create API-Key to make BPC API calls (Version 1)

This must be done upfront by using the BPC Frontend → Core Services → API Keys or by inserting the setting directly into Elasticsearch (in case there are no existing ones; otherwise the existing setting gets overwritten).

Insert directly into Elasticsearch:

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 which gets set as a HTTP header while calling the BPC API. Of course you must adjust the "issuedOn" field to the current date. Otherwise your request gets rejected as it is - in this example - only valid for one day.

Create API-Key to make 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. It gets used in the next step.

Check if session is valid

curl -X GET \
     -b cookies.txt \
     "http://localhost:8181/cxf/bpc-core/authentication"

Check Session : Success Response

{
  "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 : Failure Response

{
  "error": {
    "messageKey": "CORE_ERROR_IDENTITY_PROVIDER_AUTHENTICATION_FAILED",
    "code": 540,
    "name": "AUTHENTICATION_UNAUTHORIZED",
    "message": "Authentication failed",
    "properties": {}
  }
}

Create the API-Keys 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"
} ]'

Getting a new module instance ID

There is now (12.05.2020) an additional API endpoint to get a new instance ID:

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

You have to set the {moduleId} to the ID of the module the instance should be created for
You have to set the {instanceType}` to the correct instance type of the module instance. Set it to ‘none’ in case the module does not support instance types.

You will get extended error responses (list of supported module IDs and instance types) in case your provided module id or instance type is wrong.

Error response example when you provide a wrong module id ('unknown' in this case):

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

Error response example when you provide a wrong instance type ('xyz' in this case):

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 when you provide 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"
}

History related, the module ID of a backend connection is ‘httproxy’. This is the only case where we use a wrong naming.

Settings of the module instances to be created

When you know which module instances should be created and they already exist in an other BPC installation. The easiest way is to "export" those settings.

Example to get 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" : [ {
    ...
  }, {
    ...
  }, {
    ...
  } ]
}

Use the deployment API to create module instances

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 with the content of the 'settings' element above.

Now the module instance should be created! :-)

Keywords: