|
| 1 | +--- |
| 2 | +title: "Published CDC Services" |
| 3 | +url: /refguide/published-cdc-services/ |
| 4 | +weight: 10 |
| 5 | +description: "Describes how to configure a Published CDC Service document in Studio Pro to stream entity changes to Kafka topics." |
| 6 | +--- |
| 7 | + |
| 8 | +## Introduction |
| 9 | + |
| 10 | +A Published CDC Service document defines the entities whose object changes the Mendix runtime tracks and publishes as Kafka events. Each tracked entity produces a stream of create, update, and delete events on its own Kafka topic. |
| 11 | + |
| 12 | +{{% alert color="warning" %}} |
| 13 | +Change Data Capture is a beta feature in Mendix 11.12. Its behavior and configuration options may change in future releases. |
| 14 | +{{% /alert %}} |
| 15 | + |
| 16 | +## Creating a Published CDC Service {#create} |
| 17 | + |
| 18 | +To create a published CDC service, right-click a module in the App Explorer and choose **Add other** > **Change data capture service**. Studio Pro adds the document to that module for logical grouping, but the service operates at app level. |
| 19 | + |
| 20 | +You can have multiple CDC service documents in an app — for example, to group entities by domain area or team ownership. |
| 21 | + |
| 22 | +## General {#general} |
| 23 | + |
| 24 | +### Service Name {#service-name} |
| 25 | + |
| 26 | +The service name uniquely identifies the CDC service within the app. It is used as part of the Kafka topic name. |
| 27 | + |
| 28 | +### Description {#description} |
| 29 | + |
| 30 | +An optional description for the CDC service. |
| 31 | + |
| 32 | +## Entities to Track {#entities} |
| 33 | + |
| 34 | +The **Entities to track** table lists the entities whose object changes are published to Kafka. |
| 35 | + |
| 36 | +{{< figure src="/attachments/refguide/modeling/integration/change-data-capture/published-cdc-service.png" alt="Published CDC Service document showing the Entities to track table with columns for Exposed name, Modification, Revision, and Topic" >}} |
| 37 | + |
| 38 | +Use the toolbar to manage tracked entities: |
| 39 | + |
| 40 | +* **+ Add** — add an entity from the domain model |
| 41 | +* **Remove** — stop tracking a selected entity |
| 42 | +* **Accept changes** — lock in the current revision numbers after reviewing modifications (see [Revisions](#revisions)) |
| 43 | + |
| 44 | +Each row in the table has the following columns: |
| 45 | + |
| 46 | +| Column | Description | |
| 47 | +| --- | --- | |
| 48 | +| **Entities** | The domain model entity being tracked. Expand the row to view and select individual attributes and associations. | |
| 49 | +| **Exposed name** | The name used for this entity in the Kafka topic and event payload. Defaults to the entity name. | |
| 50 | +| **Modification** | The pending change state: **Added**, **Changed**, or **Removed**. Blank if the entity is unchanged since the last accepted revision. | |
| 51 | +| **Revision** | The schema version of the entity's event payload. See [Revisions](#revisions). | |
| 52 | +| **Topic** | The Kafka topic name for this entity, in the format `cdc.<app-name>.<ExposedName>.<revision>.{space}`, where `{space}` is replaced at runtime by the Event Broker space name. | |
| 53 | + |
| 54 | +### Adding an Entity {#add-entity} |
| 55 | + |
| 56 | +1. Click **+ Add** in the toolbar. |
| 57 | +2. Select a persistable entity from the domain model. |
| 58 | +3. Optionally edit the **Exposed name**. |
| 59 | +4. Expand the row to deselect any attributes or associations you do not want included in the event payload. |
| 60 | + |
| 61 | +### Attribute and Association Selection {#attributes} |
| 62 | + |
| 63 | +Expand an entity row to see each attribute and association with a checkbox. Uncheck an item to exclude it from the event payload. The **Exposed name** column lets you rename individual attributes in the payload independently of their domain model names. |
| 64 | + |
| 65 | +Associations appear as nested data within the parent entity's event payload. They do not produce separate Kafka topics and show no **Revision** or **Topic** values of their own. |
| 66 | + |
| 67 | +## Revisions {#revisions} |
| 68 | + |
| 69 | +Each tracked entity has a **Revision** number that identifies the schema version of its event payload. Downstream consumers use the revision to detect and respond to schema changes. The revision is also embedded in the Kafka topic name, so each schema version has its own isolated topic. |
| 70 | + |
| 71 | +Studio Pro manages revisions automatically. When you modify the tracked configuration of an entity, Studio Pro marks it as **Changed** and calculates the new revision based on whether the change is breaking or non-breaking: |
| 72 | + |
| 73 | +* **Minor revision** (for example, `1.0` → `1.1`) — a non-breaking change such as adding a new attribute. Existing consumers can continue reading the topic without modification. |
| 74 | +* **Major revision** (for example, `1.0` → `2.0`) — a breaking change such as removing an attribute, renaming an entity's exposed name, or removing an entity from tracking. Consumers must be updated to use the new topic. |
| 75 | + |
| 76 | +{{< figure src="/attachments/refguide/modeling/integration/change-data-capture/published-cdc-service-changes.png" alt="Published CDC Service document showing entities with Changed and Removed modification states and updated revision numbers" >}} |
| 77 | + |
| 78 | +### Accepting Changes {#accepting-changes} |
| 79 | + |
| 80 | +Pending modifications are not finalized until you click **Accept changes** in the toolbar. Until you do, Studio Pro shows a consistency error on the document. You must resolve this error by accepting the changes before you can deploy the app. |
| 81 | + |
| 82 | +Accepting changes confirms the new revision numbers and clears the modification states, leaving the document in a clean state ready for deployment. |
| 83 | + |
| 84 | +{{% alert color="warning" %}} |
| 85 | +A major revision creates a new Kafka topic. Consumers subscribed to the previous topic version will no longer receive events after deployment. Ensure downstream systems are updated before deploying a major revision change. |
| 86 | +{{% /alert %}} |
| 87 | + |
| 88 | +## Runtime Behavior {#runtime} |
| 89 | + |
| 90 | +* The CDC service runs in the system context — no user security applies. |
| 91 | +* Events are published for every committed object change: create, update, and delete. |
| 92 | +* Kafka topics are created automatically on deployment for each tracked entity. |
| 93 | +* Events use [CloudEvents](https://cloudevents.io/) payload format, consistent with other Mendix Event Broker services. |
| 94 | + |
| 95 | +## Read More |
| 96 | + |
| 97 | +* [Change Data Capture](/refguide/change-data-capture/) |
| 98 | +* [Mendix Event Broker](/appstore/services/event-broker/) |
| 99 | +* [Event Broker Bridges](/appstore/services/event-broker/#manage-mx-broker-bridge) |
0 commit comments