Skip to main content
Version: 2.0.0

ADR 021: Definition of Configuration Events

Date: 2025-11-07 Status: Accepted

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 definitions, for the cloud events:

Event Topics for Operations​

We concatenate the name of the KafkaApache KafkaA distributed event streaming platform. In CIVITAS/CORE it is used as the message bus to transport events, models and data in data flows. Topics with a semantic 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 tenantTenantAn isolated organizational partition that owns Data pools, Datasets, Users, Groups, and Roles. All access rules exist within their Tenant, and the Tenant is the widest Scope of a Role. Currently, one Tenant corresponds to the Platform., the event is processed for. TenantsTenantAn isolated organizational partition that owns Data pools, Datasets, Users, Groups, and Roles. All access rules exist within their Tenant, and the Tenant is the widest Scope of a Role. Currently, one Tenant corresponds to the Platform. should have 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, DatasetDatasetA data-related element that contains processed data and makes it available for consumption. A Dataset is populated via Pipelines and carries Metadata and access permissions., 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>.<entity>.<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 KafkaApache KafkaA distributed event streaming platform. In CIVITAS/CORE it is used as the message bus to transport events, models and data in data flows. Topics with a semantic 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 tenantTenantAn isolated organizational partition that owns Data pools, Datasets, Users, Groups, and Roles. All access rules exist within their Tenant, and the Tenant is the widest Scope of a Role. Currently, one Tenant corresponds to the Platform., the event is processed for. TenantsTenantAn isolated organizational partition that owns Data pools, Datasets, Users, Groups, and Roles. All access rules exist within their Tenant, and the Tenant is the widest Scope of a Role. Currently, one Tenant corresponds to the Platform. should have 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, DatasetDatasetA data-related element that contains processed data and makes it available for consumption. A Dataset is populated via Pipelines and carries Metadata and access permissions., 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>.<entity>.<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 producers or consumers must use the official SDKs provided by https://cloudevents.io/.

Alternatives​

None

See also​