Domain Events

Introduction

Events are used to inform the system that something has happened. They are meant to describe business occurrences and not technical. Additionally, they can trigger a change when they are caught by Agents (see Domain Agents). Events can be triggered across aggregate and domain boundaries.

Note: An event is always bound to exactly one Event Topic Binding. You have to create an event topic binding first, before you can create an event.
Tip: Commands, Services and Agents can all throw events which in turn are published to an event topic (see Event Topic Bindings).

Modelling Events

IBM Financial Services Workbench currently supports three different use cases in combination with events. The first one is the Internal Event, meaning that sending and receiving an event happens in the same project. So you might publish an event in one domain namespace and model an agent to listen for it in another domain namespace. This way you could separate the logic into two parts making it easier to maintain and to evolve the business logic. See Modelling Internal Events for further details.

The second use case is to send events from one microservice and receive it in another microservice. Both of these microservices have been modelled and implemented with IBM Financial Services Workbench. That's what we call a Cross-Solution Event. See Modelling Cross-Solution Events for further details.

The last use case is to send and receive events from and to external systems, meaning that

  • the Producer is built with IBM Financial Services Workbench but the Consumer is an external application

  • the Consumer is built with IBM Financial Services Workbench but the Producer is an external application

The support for this use case is still limited in IBM Financial Services Workbench 2.9 but there is some workaround described at External Events.

Create Events

Events are created by using the Create capability on the Events tab of a domain namespace's Overview page or when editing Commands and Services (see Edit Commands or Edit Services).

Events are defined using the following master data:

  • Local Identifier: Identifier of the command. this value must be unique within the namespace and cannot be changed afterwards. 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 (optional)

  • Short Label: Short label of the command (optional)

  • Event Topic Binding: Select the Topic Binding that holds the information to about the topic to use (required)

  • Notes: Useful information regarding the command definition (optional)

Add Event Payload

It is possible to add an Entity as payload to the event in case the event should carry data. You can choose between

  • Create new private entity

  • Select existing entity

To add properties to the payload entity click on the Add capability and choose

  • Create new property

  • Associate existing property

See Domain Properties for further details on creating properties.

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

Note: 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.

Attention: 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.