Events
If you created a project with a version prior to 4.0.5 events are handled differently than documented here. Please check the article around Event Support 1.0 to find out how to deal with events there.
Introduction
Events in IBM Industry Solutions 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.
IBM Industry Solutions 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 IBM Industry Solutions 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 Designer. 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)
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. IBM Industry Solutions 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 IBM Industry Solutions 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.
Event Support Version 1.0 vs 2.0
In IBM Industry Solutions Workbench version prior to 4.0.5, events were handled differently. The previous version will be called Event Support 1.0 whereas the "new" version will be Event Support 2.0. The Event Support Version can be discovered in the General Information section of your project.
The main changes coming with 2.0 are:
- Event payloads are no longer modelled as entities. Instead, shared schemas modelled in a central schema registry are used
- Event identifiers don't have to be named equally in consumer and producer services
- Event filtering by identifier doesn't happen anylonger. Topics need to be used for isolating events
Even though it's deprecated, it will still be allowed to use Event Support 1.0 to be backwards compatible. All projects created prior 4.0.5 will automatically have Event Support Version 1.0 enabled by default. For projects created from scratch with a version 4.0.5 or higher, the Event Support Version will be set to 2.0 by default.
In Event Support Version 1.0 it is possible to create both events of type 1.0 and events of type 2.0. The distinction will be made automatically depending whether you chose an entity as payload (1.0) or a schema as payload (2.0). This way, you can migrate your service event per event depending on your needs (see Migration documentation).
Consume 1.0 events in a new service
If you want to consume an event from a service that is still based on Event Support 1.0, your consuming service has to use version 1.0 as well. If your version is 2.0, you can navigate to the General Information section of your project and adjust Event Support Version there.
Since Event Support 1.0 is deprecated, it is recommended to rather switch all services to 2.0.