arrow back Icon

Simplifying Event Upcasting and Event Replaying

Geschreven door

Laura Devriendt

Read the news article or just listen to it!

In the world of software development, there are phrases that sound like a cast of a wizard spell For example, Event sourcing and Command Query Responsibility Segregation (CQRS). They may seem like mysterious incantations, but they are actually super useful architectural principles to design & create scalable and evolutionary software systems.


Event Upcasting

In this article, we are going to unravel two magical concepts of the Event sourcing world: Event Upcasting and Event Replaying. Understanding these concepts is vital because as businesses expand and respond to new market demands, the structure and content of events must evolve accordingly. We'll delve into these concepts, uncovering their mysteries and illustrating how they benefit both tech wizards and business sorcerers alike. Our journey will be guided by concrete examples, utilizing the Axon Framework to demonstrate their practical application.

Building on the Basics

Before we embark on this magical journey of Event Upcasting and Event Replaying, it is essential to lay a strong foundation in event sourcing and CQRS.

🧙‍♀️ For Business Professionals: No need for a crystal ball. Understanding the basics of event sourcing and CQRS empowers you to make informed decisions about your digital kingdom. It is your ticket to speak the language of the tech wizards fluently. For more mystical insights, check out talks like  "Capture, Keep, and Unlock All Your Data," from Michael Schoenmaekers, designed just for you.

🧙 For Developers: Imagine event sourcing and CQRS as the spells that create powerful and resilient systems. To become the wizards of the digital realm, mastering these incantations is a must. Do not worry; you will not need a Hogwarts letter. Just head over toAxon Academy to unlock these magical skills and watch their free courses.

What is Event Upcasting?

Imagine you are upgrading your favorite enchanted sword without losing any of its magical properties. That is precisely what Event Upcasting does. It transforms historical events into a shiny new format while preserving all their original charm.

🛡️For Business Professionals: Upcasting ensures that your system can handle changes seamlessly, reducing the risk of data inconsistencies and preserving historical data.

🛡️For Developers: Event Upcasting enables you to evolve your event schema without breaking existing systems. This flexibility is crucial for adapting to changing requirements.

What is Event Replaying?

Picture this: It's movie night in your castle, and you decide to rewatch your favorite epic tale. Event Replaying is similar, but it is about reconstructing your entire kingdom's story by re-enacting past events. It is like summoning all the magical creatures and characters from your realm's history to relive their adventures.

🎬 For Business Professionals: It allows you to perform historical analysis, create audit trails, and ensure regulatory compliance, enhancing data management and decision-making. 

🎬 For Developers: Event Replaying is a powerful tool for debugging, auditing, and maintaining data consistency in your systems. Furthermore you can expand easier on existing code because you can remove your data tables and repopulate them by the event store or create new modules based on existing events and data.

How Event Upcasting and Event Replaying Collaborate

These two magical practices often join forces, especially when you are on a quest to migrate data from one event schema version to another. 

🤝 For Business Professionals: This collaboration ensures seamless transitions between data structures, enhancing the kingdom's data harmony and reliability. It keeps your digital kingdom agile and ready to respond to ever-evolving desires from the market and your loyal subjects.

🤝 For Developers: The collaboration between Upcasting and Replaying is your secret weapon for managing data changes effectively. It is like adding new spells to your repertoire, fostering innovation while ensuring compatibility with your old charms.

Let’s see this collaboration in action by telling the tale of the potion delivery company 


A Tale of Potion Delivery - The Delightful Expansion

In the beginning, our shop delivered only in the Netherlands, with a specific event in their order scroll (list of orders):

 Event For Business Professionals:

Potion Order Placed Event (Version 1.0)

   -  Order ID

   -  Customer Name

   -  Dutch Address

Event For Developers:

The quest 

Now, the Dutch Address had some peculiar properties: postal code, house number, and addition. But lo and behold! News arrived that customers across the border in Belgium also yearned for potions. The challenge? Belgian addresses needed street names, while Dutch ones did not. This is a concrete example of how businesses expand and respond to new market demands. This means the structure and content of the PotionOrderPlacedEvent must evolve accordingly.

How could “Bubbles” serve both Dutch and Belgian lands without shattering their current business event? The answer: Upcasting! 

Step 1: Creating Address, the shape shifter

First, “Bubbles” conjured a new 'Address' object that could shape-shift into either a Dutch or Belgian address, thanks to the 'getCountry'  and ‘getAddress’ ’spell:

Step 1 for Business Professionals:

🪄 Address (The Shape-Shifter):

   - `getAddress()` spell => shows the complete address in one sentence 

   - `getCountry()` spell => shows if it is a Dutch or Belgian Address by returning the country Belgium or Netherlands

Then, the shape shifter is used:

🏡 DutchAddress:

   - postal code

   - house number

   - addition

   - `getAddress()` spell => shows the complete Dutch address in one sentence 

   - `getCountry()` spell => shows that it is a Dutch address by returning NETHERLANDS

🏡 BelgianAddress:

   - postal code

   - street name

   - house number

   - addition

   - `getAddress()` spell => shows the complete Belgian address in one sentence 

   - `getCountry()` spell => shows that it is a Belgian address by returning BELGIUM

Step 1 for Developers:

Step 2: craft an update of the event

We use this newfound 'Address' shapeshifter in a new version of the event so we could deliver to both Dutch and Belgian addresses.

Step 2 for Business Professionals:

Potion Order Placed Event (Version 2.0):

   - Order ID

   - Customer Name

   - Shape shifter Address

Step 2 for Developers:

Step 3: Behold the Upcaster Spell - transform the old to the new

The order scroll contains our history with the older events and we do not want to overwrite our history. A history is in the past so should never be adapted. However all the delivery lists should clearly state if the deliverers should fly to Belgium or the Netherlands. 

Here comes the transformation (upcaster) spell in place which makes it possible to use the order scroll, our history, in all our delivery lists. This is done by adding the country property when reading old events from the order scroll. This change allowed “Bubbles” to expand their potion kingdom to Belgium without losing track of their Dutch adventures.

Step 3 for Business Professionals:

🧙‍♂️ Magical Upcaster Spell:

   - Detects old order events (version 1.0)

   - Transforms them into new order events (version 2.0) with the 'country' spell set to "NETHERLANDS"

Step 3 for Developers:

Step 4: casting the upcaster spell and crafting the delivery lists

But wait, the feast is not over yet! While we can read our history now as if we always had a country property, we should update our delivery lists so we could see to which land we deliver. What to do? Event Replaying!

The old Delivery list looked as follows:

We burn down all the data in the delivery list, and summon the order scroll (our history). We tell the scroll that we deleted the data (in developer language => by removing the token) and the scroll will use the upcaster spell to fill the delivery list again with the country field.

Now when we receive new orders our list will look like this: 

🔮 Seeking More Knowledge? 

If you're:

  • eager to delve deeper into the realms of Event Upcasting and Event Replaying, 
  • or if you have specific questions
  • or crave more enchanting content
  • or look for a system that you can use like a trusty Swiss Army knife

Our team of tech wizards is here to assist you! Feel free to reach out into the comments section or to our dedicated support wizards and magical content creators at or We're always thrilled to share our wisdom and provide you with the mystical insights you seek. Your journey into the world of software magic has just begun! 🧙🧙

Lees ook:

Arrow white - hover in

Laten we praten

Waving hand asset

Contacteer ons

Laten we praten

Waving hand asset

Contacteer ons

Laten we praten

Waving hand asset

Contacteer ons

Laten we praten

Waving hand asset

Contacteer ons