Skip to main content

ADR 021: Definition of Configuration Events

Date: 2025-11-07

Status: Reviewed

Decision Makers: @DerLinne @luckey @g.grune @mhoffmann

Context​

With ADR 013 we have decided, to use Cloud events as envelope of configuration events within CIVITAS/CORE V2.

To define a standard for the event communication, we need a specialized CIVITAS/CORE Configuration Event. The events adds some more definitions on the cloud events standard.

Checked Architecture Principles​

  • [full] Model-centric data flow
  • [full] Distributed architecture with unified user experience
  • [full] Modular design
  • [full] Integration capability through defined interfaces
  • [full] Open source as the default
  • [full] Cloud-native architecture
  • [full] Prefer standard solutions over custom development
  • [full] Self-contained deployment
  • [full] Technological consistency to ensure maintainability
  • [full] Multi-tenancy
  • [full] Security by design

(if partial, then this topic should be commented)

Decision​

We use the following concrete defintions, for the cloud events:

Event Topics for Operations​

We concatenate the name of the Kafka Topics with a semanctic approach. Due to the length restriction of max 249 Chars, we have to use some abbreviations.

  • The topic names start with a prefix of Civitas Core Configuration Events. The abbreviation for this is defined by ccc.
  • The next part is be the tenant, the event is processed for. Tenants schuld habe a max length of 20 chars in this case
  • The next part is the domain within the platform like Identity Management, API Management or Geodata Management. The domain abbreviation must be max. 20 Chars long
  • The next part is the Platform Entity, the event is send for like User, Dataset, Datasource, ... The Entity Name must have max. 20 Chars
  • The last part is the operation itself like create, update, delete or password_change. The Event must have max. 20 Chars
  • The different parts are concatenated with dots

The result looks like this:

ccc.<tenant>.<domain>.<enitity>.<operation>

Examples are:

  • ccc.civitas-stg.idm.user.create
  • ccc.civitas-stg.idm.user.update
  • ccc.civitas-stg.idm.user.password_change
  • ccc.civitas-stg.apim.upstream.create

Operation Payload​

The event payload is defined by a JSON structure. The structure should only contain the data needed, to execute the operation, specified by the topic.

Example for user.create:

{
  „firstname“: „Max“,
  „lastname“: „Mustermann“,
  „email“: „max.mustermann@civitas-stg.de“
}

Event Topics for Confirmations​

We concatenate the name of the Kafka Topics with a semanctic approach. Due to the length restriction of max 249 Chars, we have to use some abbreviations.

  • The topic names start with a prefix of Civitas Core Configuration Events. The abbreviation for this is defined by ccc.
  • The next part is be the tenant, the event is processed for. Tenants schuld habe a max length of 20 chars in this case
  • The next part is the domain within the platform like Identity Management, API Management or Geodata Management. The domain abbreviation must be max. 20 Chars long
  • The next part is the Platform Entity, the event is send for like User, Dataset, Datasource, ... The Entity Name must have max. 20 Chars
  • The last part is the resulting event of an operation like created, updated, deleted or password_changed. The Event must have max. 20 Chars
  • The different parts are concatenated with dots

The result looks like this:

ccc.<tenant>.<domain>.<enitity>.<event>

Examples are:

  • ccc.civitas-stg.idm.user.created
  • ccc.civitas-stg.idm.user.updated
  • ccc.civitas-stg.idm.user.password_changed
  • ccc.civitas-stg.apim.upstream.created

Consequences​

All participants of the configuration system of CIVITAS/CORE have to follow these definitions. All possible produsers or consumers must use the official SDKs provided by https://cloudevents.io/.

Alternatives​

None

See also​