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. 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. 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 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. |
de.civitascore.saga.result | Orchestrator | Portal backend | Report SAGA_COMPLETED or SAGA_FAILED |
The orchestrator does not send a command to an adapter over 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.. 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. 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. carries the envelope in the message headers.
Access control
Topic access control is not yet active. The installed 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. 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 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. ACL enforces the access per topic.
- The namespace prefix makes a wildcard rule possible for a whole category.
ADR 043 selects SASLSASL (Simple Authentication and Security Layer)A framework defined in RFC 4422 that decouples authentication from application protocols./SCRAMSCRAM (Salted Challenge Response Authentication Mechanism)A challenge-response authentication protocol defined in RFC 5802.-SHA-512 as the authentication mechanism.