Configuration - vanillabp/businesscockpit-process-engine-api-adapter GitHub Wiki

This page names every key the Business Cockpit reads in an application whose workflows run through the Process-Engine-API. There is no version-1 table. The Business Cockpit supported Camunda 7 and Camunda 8 in Version 1, and this integration is new with Version 2.

1. Where the keys live
   The four sections the cockpit is configured in, and which of them wins.
2. Where the reports go
   The cockpit server's address, or the Kafka brokers, and the templates.
3. What a workflow module tells the cockpit
   Where the module answers, how its forms are served, in which languages it reports, and what a single workflow of it says for itself.
4. The one key of this half
   How many delivered user tasks a node remembers, and why it has to remember any.
5. What the engine adapter is configured with
   The two keys of the Process-Engine-API adapter which change what the cockpit sees.

Every key is the key version 1 of the Business Cockpit read, in the place version 1 read it. So an application which comes from one of the other two engines brings its configuration along unchanged:

vanillabp.cockpit.<key>
vanillabp.workflow-modules.<moduleId>.cockpit.<key>
vanillabp.workflow-modules.<moduleId>.workflows.<process>.cockpit.<key>
vanillabp.workflow-modules.<moduleId>.workflows.<process>.user-tasks.<task>.cockpit.<key>

The most specific value wins per key. What a user task says beats what its workflow says, and what a workflow says beats what its workflow module says. What holds for the whole application is written once at the top and exists nowhere else: the transport, the templates and the two switches.

VanillaBP reads nothing below vanillabp.cockpit, so the cockpit binds that part of the tree itself on both platforms. On Quarkus that binding is also what lets the application start, because a key below vanillabp which nothing declares ends the startup there. A misspelled key ends the Quarkus build with a message naming it and the key it was nearest to, and a key of version 1 which is gone ends the build with what became of that key. Spring Boot ignores both. A workflow module's own defaults file (<moduleId>.yaml next to its BPMN files) carries these keys as well, below everything the application itself writes.

Exactly one transport is configured. Neither of them, or both, ends the boot with a message naming the keys of both.

These keys stand below vanillabp.cockpit.

The client-credentials flow configures its own connection. connect-timeout, read-timeout, verify-ssl, ssl-truststore-filename, ssl-truststore-password and proxy.* below rest.authentication.oauth describe the way to the authorization server and inherit nothing from rest.*.

There is no key which switches a request log on. The REST client logs through SLF4J, so set the logger io.vanillabp.cockpit.bpms.api.v1_1.BpmsApi to DEBUG to see what is sent.

These stand below vanillabp.workflow-modules.<moduleId>.cockpit, because that is what they are about.

A gap is reported at startup, and one boot reports every gap of these keys. Each line names the key which fixes it. The one key of this half is read later. So a boot which ends on the keys above does not report that key yet. A workflow module which writes none of these keys reports nothing to the cockpit, and the log says so while the application starts.

Four of these mean something for a single workflow as well, and one of them for a single user task. Both levels have a cockpit section of their own:

vanillabp:
  workflow-modules:
    taxi-ride:
      cockpit:
        i18n-languages:
          - en
          - de
      workflows:
        TaxiRide:
          cockpit:
            i18n-languages:
              - fr
            bpmn-description-language: fr
            template-path: rides
            initiator-source: by-application
          user-tasks:
            approve:
              cockpit:
                template-path: approval

It stands below vanillabp.cockpit and nowhere else. What it sizes is one memory per node, shared by every workflow module, so a value per module would promise a division which does not exist. There is no such key below a workflow module. One written there ends the boot on Quarkus and is ignored on Spring Boot, like every other key nothing declares. A value which is not a positive number ends the boot on either platform, naming the key.

Why a node has to remember anything: every other BPMS can read the state of a task from its engine whenever it is asked. The Process-Engine-API has no task query and no history. So what arrived with the delivery is all there is, and the node keeps it until the task is gone. The report of a delivery is built right away, so no report waits on this memory. The questions which come later do: how a task ended, which tasks of a case are open, and what getUserTask shows. A node which starts fresh answers none of them.

One key of the VanillaBP Process-Engine-API adapter changes what the cockpit gets to see:

by-adapter, the platform's default, is refused at startup by the adapter itself, because the Process-Engine-API has no tenants to keep workflow modules apart with. Choose none or use-prefix.