Business Event
Introduction
When developing modern applications, messaging using event streaming platforms like Apache Kafka is often used to communicate between services. Especially for services with a lot of business logic, it makes sense to complement business use cases by using eventing, so that those events can be consumed by others.
Business Event Support
The Business Event Support Extension establishes an easy way to apply event driven architecture into a domain service, by providing enriched modelling and implementation capabilities.
The extension is available for the following stacks:
- Java Spring Boot Stack 2.0.0 and later
- NodeJS TypeScript Stack (only for Domain services and always enabled)
The extension is only available if Domain Modelling Extension is enabled as well.
Business Event Support offers the capability to model business events within a domain namespace, which indicate, that something happened within in a business context. A business event payload is described by a schema from a shared schema registry which can be managed in the Solution Builder UI. Business events are meant to be consumed by agents, which can be modelled as well within a domain namespace. To learn more about modelling business events, please check Domain Modelling - Events and Domain Modelling - Agents.
For a smooth implementation, there are various code artefacts generated, which allow to easily publish events within a domain context. The necessary dependencies are added to the project automatically and also the connection to the event streaming platform is established out of the box. Besides that, the generated code around agents ensures, that the events can be consumed easily while staying compliant with the schemas used in the payload. To find out more about the implementation capabilities please check Java Spring Boot Implementation and NodeJS TypeScript Implementation.
Event
Introduction
Events in Cloud Solution Workbench are used to inform the system that something has happened. They are meant to describe occurences rather related to your business use case than to a technical use case. Additionally, they can trigger a change when they are caught by agents (see domain agents). Events can be triggered across domain and service boundaries.
Cloud Solution Workbench uses Apache Kafka as event/messaging system. Therefore, if you are planning to use events in your project make sure you have configured a connection to at least one Kafka cluster.
If you don't have a running Kafka cluster yet, there is instructions on how to install Apache Kafka in your OpenShift cluster.
In case you already have a running cluster make sure you have at least one Message Hub Service Binding (Kafka binding) configured on Environment level. This service binding can then be referred to from any project modelled with Cloud Solution Workbench . You can configure additional Message Hub Service Bindings at the Project level (for each k5-project) in case you want to use different Kafka clusters depending on the stage your microservices get deployed to (e.g., one cluster for development and one for production use).
The next prerequisite is to have at least one event topic binding configured in Solution Hub so you can refer to it from within Solution Builder. These bindings are used to specify the Kafka topic(s) to use for sending or receiving event messages. Depending on your project's requirements, you have the option to either use just one topic for all related events or use separate topics for each event.
Additionally, it is necessary to have a schema registry provided for using schemas as event payloads. For further details, please check Schemas.
Commands, services and agents can all throw events which in turn are published to an event topic (see event topic binding). In case you are in the user role tm_admin you can also create event topic bindings from within Solution Designer.
Publish events in a Domain Service Project
To publish events within a Domain Service project, they need to be modelled within a domain namespace. A domain event is usually something that happens during the execution of business logic and therefore are named accordingly (e. g. "OrderCreated", "CustomerChanged").
Create a new event
Events are created by using the Create capability on the events tab of a domain namespace's Overview page or within commands and services (see edit commands or edit services).
Events are defined using the following master data:
- Local Identifier: Identifier of the event describing what happened in the business use case. This value must be unique within the namespace. Please note that only the characters A-z (without special characters), digits and the special character "_" are permitted for naming fields! Furthermore, identifiers may not begin with a digit (required)
- Label: Label of the command used for displaying purposes (optional)
- Short Label: Short label of the command used for displaying purposes (optional)
- Event Topic Binding: Binding alias which holds the details about the topic on which the event is going to be published. It is recommended to use one binding per Event so that messages are isolated from each other
- Notes: Useful information regarding the event definition used for displaying purposes (optional)
Edit events
You can edit the master data using the Info capability on the event's instance page and navigating to the section Master Data.
The following fields can be edited:
- Label
- Short Label
- Event Topic Binding
- Notes
It's not possible to edit the Local Identifier of an event.
Delete events
You can delete an event by using the row capability Delete in the table of the events tab of the domain namespace's Overview page.
You will need to confirm the action before the selected event gets permanently deleted. You can only delete an event if it is not in use. You can check the usages of an event by using the Info capability and navigating the Usages section.
Define event payload
An event can carry a payload with it which can hold additional information around what happened, e. g. the orderId of the order that has been created or the new name of a customer after it changed.
To ensure governance when dealing with events, schemas from a shared schema registry are used to describe the payload of an event. They act as a reliable contract between event producers and consumers. To learn more about schemas and how they are modelled, please check the article about Schema Introduction and Modelling Schemas.
Within an event, you can define your schema via the Select schema from schema registry capability. Cloud Solution Workbench will offer you all schemas from the connected schema registry. As a schema can evolve over time, multiple versions of the schema can exist. Therefore, the version has to be chosen in the second step. There, you also get an overview of all the properties that are defined for the schema.
When a schema has been used as event payload in the event producer, the same schema is expected to be chosen in the service that consumes the event.
Update schema version of event payload
As requirements change over time, new versions of schemas get created and usually the events want to use the new structure as well.
To update the event to use a new schema version, please use the Change schema version capability on the event page. Select your version of choice in the dropdown and save the changes for updating the event.
It is recommended to not update your event to a schema that has breaking changes to the current one. Otherwise event consumers will fail when they are processing the events. If you have major changes that you want to implement, it is recommended to create a new event publishing on a new topic. After all consumers are adjusted to use the new event, it is safe to delete the "old" one.
It is also possible that the producer service updates to a new version of the schema, while the consumer services still keeps the older version. The consuming of the event will keep working as long as no breaking change in the new schema version.
Implement publishing of events
To learn more about how to publish events please check
Consume event in same service
If you want to consume an event within the same service, it is only required to model an agent which has the desired event as trigger event.
Please check the article about Agents for further details.
With every publishing of the event, the agent will get triggered automatically.
Consume event in another Domain Service
To consume an event published by a Domain Service within another Domain Service, you have to recreate an event on the consuming service.
The event in the consuming service should be named dependending on the business context of the consuming service. Contrary to prior versions, from version 4.0.5 on it is no longer necessary to use equal identifiers in the consuming and producing service
When creating the event in the consuming service, it is important to choose the same topic binding as the one that was chosen for the event in the producing service. The chosen topic binding defines on which topics the consumer is subscribing and therefore decides which messages are processed.
After creating the event, the payload has to be defined. It is required to choose the same schema, which is used in the produing service. It is allowed to use a different version of the schema as long as the versions are not in conflict with each other.
After specifying the event, you have to model an agent which has the your modelled event as trigger event.
Please check the article about Agents for further details.
To isolate messages from each other and to ensure that only dedicated agents are processed, it is recommended to use just one event per topic. If multiple events are assigned to one topic, multiple agents will be processed when a message is published.
Consume event from an external service
If you want to consume an event from an external service, it is also possible using Cloud Solution Workbench .
Implementing this is similar as consuming events from other Domain Services. As a first step, you also have to create a new event in the your Domain Service Project. There you have to ensure that you assign the topic binding on which the external event is published to your event. If a schema exists, which describes the structure of the payload, please select this schema and define it as payload of the event.
Schemas used in external events are supported if they are managed by an Apicurio schema registry and provided in the format of JSON Schema 2019-09
In the next step, create a new agent and assign the created event as trigger event.
Agents
An agent is always bound to exactly one event, but you can create multiple agents bound to the same event if necessary. When this event is published to the event topic, the agent(s) bound to this event will be triggered and then executed.
Create agents
Agents are defined using the following master data:
- Type: There is one option available and this is the Event Agent (required)
- Trigger Event: The event to which the agent will be bound (required)
- Local Identifier: This is the identifier (name) of the agent. It is unique within a namespace. Please note that only the characters A-z (without special characters), digits and the special character "_" are permitted for naming agents! Furthermore, names may not begin with a digit and the first character must be uppercase. Furthermore, names may not begin with a digit and the first character must be uppercase (required)
- Tags: To tag the agent (optional)
Agents cannot have the same Local Identifier as a command or a service in the same namespace.
Edit agents
You can edit the master data of a agent by clicking the Edit agent details button in the Agent Details section on the agent's instance page. Alternatively, you can use the Edit capability of each table row on the Agents tab of a domain namespace's Overview page. The fields that can be edited are Local Identifier and Trigger Event.
It's not possible to edit the Type of an agent.
Delete agents
You can delete a agent by clicking the Delete agent button in the upper right corner of the agent instance page. Alternatively, you can use the Delete capability of each table row on the Agents tab of a domain namespace's Overview page.
You will need to confirm the action before the selected agent gets permanently deleted.