Topic Configuration
Configuration Event Topics
Configuration events use the reverse domain name prefix de.civitascore followed by domain, entity, and event type. All configuration events are confirmation events (past tense), indicating that a state change has occurred.
Structure
de.civitascore.<domain>.<entity>.<event>
| Segment | Description | Examples |
|---|---|---|
de.civitascore | Fixed platform prefix (reverse domain) | -- |
<domain> | Platform domain | idm, api, data |
<entity> | Platform entity | user, realm, backend, route, project |
<event> | Event type (past tense) | created, updated, deleted |
Segments are concatenated with dots (.). The total topic name must not exceed 249 characters (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. limit).
Domains and Events
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 |
Examples:
de.civitascore.idm.user.created
de.civitascore.idm.user.updated
de.civitascore.idm.user.deleted
de.civitascore.idm.user.locked
de.civitascore.idm.user.unlocked
de.civitascore.idm.user.password.changed
de.civitascore.idm.user.password.reset
de.civitascore.idm.realm.created
de.civitascore.idm.client.deleted
de.civitascore.idm.group.created
de.civitascore.idm.role.updated
API Management (api)
| Entity | Events |
|---|---|
backend | created, updated, deleted |
route | created, updated, deleted |
Examples:
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 |
Examples:
de.civitascore.data.thing.created
de.civitascore.data.sensor.updated
de.civitascore.data.project.created
de.civitascore.data.pipeline.deleted
Extending the Event Catalog
New configuration events follow the same convention:
- Identify the domain (
idm,api,data, or a new domain abbreviation) - Define the entity name (lowercase, no separators)
- Use past tense for the event type
- Composite operations use dot-separated segments (e.g.,
password.changed)
Saga / Orchestrator Topics
Multi-step provisioning workflows use the core.civitas prefix, as defined in ADR 031:
core.civitas.<system>.<entity>.<operation|result>
| Topic | Publisher | Subscriber | Purpose |
|---|---|---|---|
core.civitas.dataset.create.requested | Portal Backend | Orchestrator | Trigger provisioning |
core.civitas.frost.project.create | Orchestrator | FROST Adapter | Create FROST project |
core.civitas.frost.project.delete | Orchestrator | FROST Adapter | Delete / compensate |
core.civitas.frost.project.result | FROST Adapter | Orchestrator | Step result |
core.civitas.apisix.route.create | Orchestrator | APISIXApache APISIXAn open-source API gateway for traffic management, security and observability. In CIVITAS/CORE it is used as the centralized entrypoint to route and protect externally exposed APIs. Adapter | Create route |
core.civitas.apisix.route.result | APISIXApache APISIXAn open-source API gateway for traffic management, security and observability. In CIVITAS/CORE it is used as the centralized entrypoint to route and protect externally exposed APIs. Adapter | Orchestrator | Step result |
core.civitas.dataset.create.completed | Orchestrator | Portal Backend | Saga succeeded |
core.civitas.dataset.create.failed | Orchestrator | Portal Backend | Saga failed |
Payload Data Topics
Payload data topics are not yet implemented. The namespace structure described here is the planned approach, subject to Architecture Board review. See Authorization Concept for the full context.
Payload data (sensor readings, geodata, domain-specific content) uses a separate topic namespace. The platform supports two namespace strategies, selected during installation:
Preferred: Customer Domain Namespace
Each installation uses the customer's own reverse domain name as the top-level prefix. This provides clear organizational ownership and avoids namespace collisions across installations.
<customer-domain>.<bundle>.<context>.<message-type>
Examples:
de.musterstadt.umwelt.luftqualitaet.raw
de.musterstadt.umwelt.luftqualitaet.enriched
de.musterstadt.verkehr.zaehlstellen.raw
ch.beispielgemeinde.energie.zaehler.validated
The customer domain is configured during platform installation.
Fallback: Platform Namespace
If no customer domain is available, the platform prefix de.civitascore.data serves as a default namespace.
de.civitascore.data.<bundle>.<context>.<message-type>
Examples:
de.civitascore.data.umwelt.luftqualitaet.raw
de.civitascore.data.verkehr.zaehlstellen.enriched
Namespace Selection
| Scenario | Namespace | Example Prefix |
|---|---|---|
| Dedicated installation with known domain | Customer domain | de.musterstadt.* |
| Shared / staging / development environment | Platform fallback | de.civitascore.data.* |
Payload Structure
Event payloads are JSON structures. Each payload contains only the data required for the operation or event. There is no generic wrapper -- the topic provides the context.
Example: de.civitascore.idm.user.created
{
"firstname": "Max",
"lastname": "Mustermann",
"email": "max.mustermann@civitas-stg.de"
}
The payload is wrapped in a CloudEvents envelope, which provides standardized metadata (source, type, subject, time, etc.) as 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. message headers.
Access Control
Topic-level access control follows the least privilege principle:
- Each component is granted read/write permissions only on the topics it needs
- 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. ACLs enforce per-topic authorization
- The namespace prefix enables wildcard-based ACL rules per category
For the planned authorization model with principal types, permission matrices, and operational governance, see the Authorization Concept.