Configuration

This page names every key the Business Cockpit reads in an application whose workflows run on Camunda 7, and what changed against version 1.

1. Where the keys live
   The four sections the cockpit is configured in, which of them wins, and where the engine itself is configured.
2. What the engine has to write
   The history a business case is read from, and why a user task needs none of it.
3. Where the reports go
   The cockpit server's address or the Kafka brokers, and the rest of that connection.
4. What a workflow module tells the cockpit
   Where the module answers, how its forms are served, in which languages it reports and who answers the initiator of its reports.
5. What one workflow or one user task says for itself
   The five keys a single workflow, or a single task of it, may differ from its module in.
6. What changed against version 1
   The keys which are gone, the keys which are new, and the two settings which behave differently.

Where the keys live

Every key is the key version 1 read, in the place version 1 read it:

vanillabp.cockpit.<key>
vanillabp.workflow-modules.<moduleId>.cockpit.<key>
vanillabp.workflow-modules.<moduleId>.workflows.<wf>.cockpit.<key>
vanillabp.workflow-modules.<moduleId>.workflows.<wf>.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: 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. A key of version 1 which is gone ends it 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.

The Camunda 7 half of the cockpit adds no key of its own. What it has to know about an engine is the tenant a workflow module is deployed under, and it reads that from vanillabp.adapters.<id>.*, which the VanillaBP Camunda 7 adapter owns. Configure the engine there, and the cockpit follows.

What the engine has to write

There is one thing about your engine the cockpit insists on. It has to write history, because that is where a workflow's start, its end and its cancellation are read from. Every Camunda level from activity upwards writes what is read, and Camunda's default is audit. So this concerns you only if something in your application switches the history off, and then the boot ends with a message naming the events the engine no longer writes.

A user task needs none of that history. Its report is built while the engine's listener runs, out of the task the engine hands over. So an engine which writes no task history at all still shows its tasks in the cockpit with everything they carry.

Where the reports go

Configure exactly one transport. If you configure neither, or both, the boot ends with a message naming the keys of both. These keys stand below vanillabp.cockpit.

Key	What it is
user-tasks-enabled	false stops user tasks from being reported at all
workflow-list-enabled	false stops workflows from being reported at all
rest.base-url	The address of the cockpit server's BPMS API, and with it the choice of the REST transport
rest.authentication.basic	true sends a basic authentication with every report
rest.authentication.username, rest.authentication.password	The user it is sent with
rest.authentication.oauth.base-url	Where tokens are issued, and with it the choice of the client-credentials flow
rest.authentication.oauth.client-id, rest.authentication.oauth.client-secret	The client the token is asked for
rest.authentication.oauth.basic	true sends the client in an Authorization header rather than in the token request
rest.connect-timeout, rest.read-timeout	How long connecting and answering may take. Write the number of milliseconds version 1 expected, or write a unit (1500ms, PT20S). 1.5 and 10 seconds by default
rest.proxy.host, rest.proxy.port	The HTTP proxy the cockpit server is reached through
rest.proxy.username, rest.proxy.password	The user that proxy expects, where it expects one
rest.verify-ssl	false switches the certificate check off altogether
rest.ssl-truststore-filename, rest.ssl-truststore-password	The PKCS12 file the server's certificate is checked against
kafka.bootstrap-servers	The brokers, and with them the choice of the Kafka transport
kafka.topics.user-task	The topic user-task reports go to
kafka.topics.workflow	The topic workflow reports go to
kafka.topics.workflow-module	The topic a workflow module registers itself on
kafka.properties.<name>	Any further producer setting, handed to the client unchanged
template-loader-path	The directory the title templates are loaded from

The client-credentials flow configures its own connection, the way it did in version 1. Below rest.authentication.oauth the keys connect-timeout, read-timeout, verify-ssl, ssl-truststore-filename, ssl-truststore-password and proxy.* describe the way to the authorization server, and they inherit nothing from rest.*. That is what keeps an authorization server behind another proxy reachable.

There is no key switching a request log on. The REST client logs through SLF4J, so the logging configuration of your application does it. Set the logger io.vanillabp.cockpit.bpms.api.v1_1.BpmsApi to DEBUG to see what is sent.

What a workflow module tells the cockpit

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

Key	What it is
workflow-module-uri	Where the module answers the cockpit's provider APIs
ui-uri-type	A name agreed with your cockpit user interface; VanillaBP knows none
ui-uri-path	Where the module's forms are served from
i18n-languages	The languages titles are reported in, written as a list
bpmn-description-language	The language the names in the BPMN files are written in; mandatory without templates
group-hierarchy.<group>	Which groups a group stands for, written as a list
template-path	The segment this module contributes to the template lookup path
initiator-source	Who answers the initiator of this module's reports: by-application or system. It has no default

A gap is reported while the application starts. Every gap of the application is reported in one boot, and each line names the key which fixes it. A workflow module which writes none of these keys reports nothing to the cockpit, and the log says so while the application starts.

initiator-source is the one key of this table without a default. A module which reports to the cockpit and answers it nowhere ends the boot. Every report names an initiator: the user who caused what is reported. Nobody can find that user out later. Write by-application where the application sets the initiator itself, in a method annotated with @WorkflowDetailsProvider or @UserTaskDetailsProvider. A report which still carries no initiator after the provider ran fails. Write system where the module knows no action a user causes, a nightly import for instance. If all modules of an application give the same answer, write it once at vanillabp.cockpit.initiator-source.

On Camunda 7 system does not hide a real user. The cockpit writes the constant only where the initiator is still empty after the provider ran. And this adapter fills a workflow's report in advance with the start user the engine recorded. So a case somebody started while logged in to the engine keeps that user. Only a case without a recorded start user is reported as system. A user task's report starts without an initiator, so there every report of such a module says system.

What one workflow or one user task says for itself

Four of the module's keys 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, and the most specific value wins per key.

vanillabp:
  workflow-modules:
    taxi-ride:
      cockpit:
        i18n-languages:
          - en
          - de
        bpmn-description-language: en
        group-hierarchy:
          TEAM_LEAD:
            - TEAM_MEMBER
            - ASSISTANT
      workflows:
        TaxiRide:
          cockpit:
            i18n-languages:
              - fr
            bpmn-description-language: fr
            template-path: rides
          user-tasks:
            approve:
              cockpit:
                template-path: approval

Key	What it is
workflows.<wf>.cockpit.i18n-languages	The languages this workflow's titles are reported in
workflows.<wf>.cockpit.bpmn-description-language	The language this workflow's BPMN names are written in
workflows.<wf>.cockpit.template-path	The segment this workflow contributes to the template lookup path
workflows.<wf>.cockpit.initiator-source	Who answers the initiator of this workflow's reports
workflows.<wf>.user-tasks.<task>.cockpit.template-path	The segment this user task contributes

The module still has to name i18n-languages and bpmn-description-language. A workflow which says nothing is reported the way its module is.

What changed against version 1

Every key not named here is the key it was, in the place it was. These are gone, one reason each:

Version 1 key	Why it is gone
rest.log	the client logs through SLF4J, so set the logger io.vanillabp.cockpit.bpms.api.v1_1.BpmsApi to DEBUG
rest.additional-get-parameters.<name>	it appended query parameters to GET requests, and every report is a POST
rest.retry.enabled, .max-attempts, .period, .max-period	a failed report waits in the outbox and is repeated from there, which vanillabp.outbox.* configures
kafka.group-id-suffix	it made a consumer group unique, and the adapter only produces
jwt.hmacSHA256-base64, jwt.cookie.*	version 1 bound them and read them nowhere, and the cockpit server configures its own tokens
group-hierarchy-bean-name	the hierarchy is configuration, and which groups may see a module is answered by the WorkflowModuleDetailsProvider bean
workerId	it named the instance a report came from, and the adapter takes the host name for that

Four keys are not version 1's. kafka.bootstrap-servers and kafka.properties.* are what version 1 took from spring.kafka.bootstrap-servers and spring.kafka.producer.*. The cockpit builds its own producer now, and does so on both platforms. process-engine-api.remembered-user-tasks belongs to the cockpit's Process-Engine-API half and does nothing in an application running on Camunda 7. initiator-source is the fourth, and an application coming from version 1 has to write it before it starts again. Version 1 left the initiator empty where nothing set one. Version 2 asks who answers for it. The keys of the Camunda 8 half which are gone are named on that BPMS' own page.

Two things behave differently while they are spelled the same. The timeouts accept the number of milliseconds version 1 expected as well as the spelling both platforms use, and they keep version 1's defaults of 1.5 and 10 seconds. And every setting is read and checked while the application starts, rather than when the first event arrives, so the log of the first boot is what you work from.

What else changes for an application coming from version 1 is on Migrating from Version 1.