Topic Configuration
Configuration event topics
A configuration event topic starts with the reverse domain prefix de.civitascore. The
domain, the entity and the event follow.
ADR 041 defines this convention and
replaces the first convention from
ADR 021.
de.civitascore.<domain>.<entity>.<event>
| Segment | Description | Examples |
|---|---|---|
de.civitascore | The fixed platform prefix | — |
<domain> | The platform domain, lowercase | idm, api, data |
<entity> | The platform entity, lowercase, no separator | user, realm, backend, route, project |
<event> | The event type, past tense | created, updated, deleted |
A dot separates the segments. Kafka limits a topic name to 249 characters.
Every configuration event is a confirmation. The name is therefore in the past tense: the change has already occurred. There is no command topic in this namespace.
Identity management, idm
| Entity | Events |
|---|---|
user | created, updated, deleted, locked, unlocked, password.changed, password.reset |
realm | created, updated, deleted |
client | created, updated, deleted |
group | created, updated, deleted |
role | created, updated, deleted |
de.civitascore.idm.user.created
de.civitascore.idm.user.password.changed
de.civitascore.idm.realm.created
de.civitascore.idm.group.deleted
API management, api
| Entity | Events |
|---|---|
backend | created, updated, deleted |
route | created, updated, deleted |
de.civitascore.api.backend.created
de.civitascore.api.route.updated
Data management, data
| Entity | Events |
|---|---|
thing | created, updated, deleted |
location | created, updated, deleted |
sensor | created, updated, deleted |
observedproperty | created, updated, deleted |
datastream | created, updated, deleted |
project | created, updated, deleted |
pipeline | created, updated, deleted |
de.civitascore.data.thing.created
de.civitascore.data.datastream.updated
de.civitascore.data.pipeline.deleted
A new event
To add an event, do these four steps:
- Select the domain:
idm,api,data, or a new abbreviation. - Give the entity a name. Use lowercase and no separator.
- Write the event type in the past tense.
- For a composite event, separate the parts with a dot, for example
password.changed.
Saga topics
The orchestrator uses two topics. Both use the same de.civitascore prefix as the
configuration events.
| Topic | Publisher | Subscriber | Purpose |
|---|---|---|---|
de.civitascore.dataset.saga.trigger | Portal backend | Orchestrator | Start a saga for a Dataset |
de.civitascore.saga.result | Orchestrator | Portal backend | Report SAGA_COMPLETED or SAGA_FAILED |
The orchestrator does not send a command to an adapter over Kafka. It calls the adapter handler directly in the process. Saga pattern describes the mechanism.
Payload data topics
This namespace is not yet built. The Architecture Board has not reviewed it.
Payload data uses a topic namespace of its own. An installation selects one of two strategies.
Preferred: the domain of the customer. The reverse domain name of the customer is the prefix. This shows the owner and prevents a collision between installations.
<customer-domain>.<bundle>.<context>.<message-type>
de.musterstadt.umwelt.luftqualitaet.raw
de.musterstadt.verkehr.zaehlstellen.raw
ch.beispielgemeinde.energie.zaehler.validated
The installation sets the domain of the customer.
Fallback: the platform namespace. If there is no domain of the customer, the prefix
de.civitascore.data applies.
de.civitascore.data.<bundle>.<context>.<message-type>
de.civitascore.data.umwelt.luftqualitaet.enriched
| Scenario | Namespace |
|---|---|
| A dedicated installation with a known domain | The domain of the customer |
| A shared, staging or development environment | The platform namespace |
Payload structure
A payload is JSON. It holds only the data that the operation needs. There is no generic wrapper, because the topic already gives the context.
Example for de.civitascore.idm.user.created:
{
"firstname": "Max",
"lastname": "Mustermann",
"email": "max.mustermann@civitas-stg.de"
}
The CloudEvents envelope holds the metadata. Kafka carries the envelope in the message headers.
Access control
Topic access control is not yet active. The installed Kafka cluster has no authentication on its listeners and no ACL, and it creates a topic automatically on first use.
The target model applies least privilege:
- A component gets read or write access only on the topics that it needs.
- A Kafka ACL enforces the access per topic.
- The namespace prefix makes a wildcard rule possible for a whole category.
ADR 043 selects SASL/SCRAM-SHA-512 as the authentication mechanism.