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.

IBM Financial Services 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 Financial Services 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.

Tip: Commands, services and agents can all throw events which in turn are published to an event topic (see event topic bindings) . In case you are in the user role tm_admin you can also create event topic bindings from within Solution Designer.

Modelling events

IBM Financial Services Workbench 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-service 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 3.1-Preview but there is some workaround described at external events.

Internal events

Internal events are used within a single project to publish a business occurrence from one domain namespace and trigger an action in another domain namespace.

To do so,

create the event in the domain namespace that should publish the event
add a payload entity
go to the second domain namespace that should receive the event ( see create domain namespaces)
create an agent
select the event you created before from the drop-down

This agent will get triggered whenever an event with this Local Identifier (which will be used as the message key) gets published to the topic specified by the event topic binding. You can later implement what this agent should call, e.g. a domain service, an integration service or you could even call factory commands or instance commands to create new root entities or to update their state and persist them.

Cross-project events

Note: Please be aware that there are some limitations when trying to use the same event between two projects with different implementation languages (e.g., a TypeScript project and a Java project). Due to different implementation of some (numeric) property types there may be issues with consuming the payload. In case you already plan to use different implementation languages we recommend to use only properties of type: string in the event payload. This datatype is equal in all implementations and allows proper consumption.

One of the most common use cases with events is to publish an event in one microservice and react on it in another microservice. These cross-service events will only work if both microservices have been modelled and implemented with IBM Financial Services Workbench. If you want to react on events that are published by external applications or publish an event and react with an external application, please see external events.

In the following example we will use two projects projectA and projectB, where projectA will publish an event and projectB will receive the event (see setting up projects for further details on creating new projects). All used names are just for the example, meaning you are totally free to name your events, namespaces and topics however you want. Just make sure they match between the two projects.

Modelling the publishing project

projectA has a domain namespace with the prefix dom1 ( see create domain namespaces) and a domain service called RaiseEventOne (see create services) that will publish the event. Furthermore, there is an event topic binding called eventTopic1 that specifies the Kafka topic named event-topic-1 to be used (don't forget to set this value either when creating the event or inside Solution Hub).

Follow the instructions below to create the event.

Inside the domain namespace dom1 create an event called Eve1
Use the drop-down event topic binding to select the binding called eventTopic1
Add a payload entity with properties as needed
Commit & Push your changes

Modelling the receiving project

projectB also needs a domain namespace to model an agent that subscribes to the same topic and listens for the associated event.

Attention: The domain namespace in the project that should receive the event MUST have the exact same prefix as the domain namespace that publishes the event! Also, the event MUST have the exact same Local Identifier as the event in the publishing project!

Therefore,

Create a domain namespace and set the prefix to dom1 (the label doesn't have to be the same as in the other project)
Create an event called Eve1 inside the domain namespace dom1
Use the drop-down event topic binding to select the binding called eventTopic1
Add a payload entity with the exact same properties as the payload entity of the publishing project's event (open a second browser tab to compare both event payloads)
Create an agent inside the domain namespace dom1 and select the event dom1:Eve1 as Trigger Event
You can use any name as the Local Identifier for this Agent
Commit & Push your changes

Note: An agent subscribes to the Kafka topic that is specified in the associated event topic binding and listens for messages that have a message key that equals the Local Identifier of the Trigger Event. The message key would be dom1:Eve1 in this example.

External events

Handling external events is still limited in IBM Financial Services Workbench 3.1-Preview. You can of course publish events to arbitrary Kafka topics and consume them with any Kafka client you implemented. Therefore, you just need to provide the necessary info regarding the event message to your external application.

Below you can find a sample event message to help you implement your external application to use events published by projects built with IBM Financial Services Workbench. This project has

a domain namespace with the prefix: procs
an event with the Local Identifier: Testeve
a payload entity for this event with the Identifier: procs:Testeve_Payload
a property called title of type String
a property called message of type String

Note: No matter to which topic this event will be published, it will have a message key with the value: procs:Testeve which your external application can listen for.

Event Message Payload Structure:

{
  "type": "procs:Testeve_Payload",
  "id": "e93f0c71-d9a2-4ee6-a22d-fc39fddd8d54",
  "title": "The title",
  "message": "This is the message body"
}

The value for "id" will change on every message. You can use a UUID when sending events.

There will be cases when you want to react on an event that has been published by an external application with a microservice that has been built with IBM Financial Services Workbench. Due to the limitations regarding the message key (that is built by concatenating the domain namespace's prefix with the local identifier of the event) it is currently not possible to model agents for arbitrary events.

Tip: You can still consume event messages that have been published by external applications with microservices built with IBM Financial Services Workbench as long as you use a valid message key and model an appropriate event payload inside Solution Designer.

This message key MUST follow the syntax: prefix:local_identifier and must match the values of the project that should receive the event message.

So if you have the chance to set the message key to the value that the Agent would expect, you can consume external events within IBM Financial Services Workbench.

Example:

You want to consume an event with an agent in the domain namespace with the prefix: dom1.

Therefore, you need to model the event inside this domain namespace accordingly to the payload of the event. Let's say you use Event1 as the Local Identifier of that event in Solution Designer. Then, inside the implementation of your external application you would specify the message key to be:

dom1:Event1

With this approach, you are able to consume external events with an Agent.

Note: There will be support for creating Agents that listen for arbitrary events (and their message key) in upcoming releases.

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 event 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.

Note: It is not possible to have an array of entities as event payload. But you can of course create an entity with a property that is an array.

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.