From d73ed7b3426efdc2fc50a2b59c071f4f8c2e585f Mon Sep 17 00:00:00 2001
From: Thomas Bonk <130759028+t-bonk@users.noreply.github.com>
Date: Thu, 19 Mar 2026 16:13:46 +0100
Subject: [PATCH 1/5] Added information regarding de-/serialization of custom
 data types

---
 java/outbox.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/java/outbox.md b/java/outbox.md
index b2c84c51c6..07cf6cf4a1 100644
--- a/java/outbox.md
+++ b/java/outbox.md
@@ -321,6 +321,45 @@ You must ensure that the handler is completing the context, after executing the
 
 [Learn more about event handlers.](./event-handlers/){.learn-more}
 
+::: tip Preparing outbox entries with custom data types
+
+The outbox has no information regarding the structure and the data types that
+shall be serialized and deserialized to and from the outbox. To avoid
+serialization and deserialization errors, the corresponding data objects must
+be transformed using custom outbox handlers:
+
+```java
+@Component
+@ServiceName(value = "*", type = OutboxService.class)
+public class DwcOutboxHandler implements EventHandler {
+
+    @On
+    void publishedByOutbox(OutboxMessageEventContext context) {
+        // Restore DwC context only
+        if (Boolean.FALSE.equals(context.getIsInbound())) {
+            return;
+        }
+
+        // custom deserialization logic
+    }
+
+    @Before(event = "*")
+    void prepareOutboxMessage(OutboxMessageEventContext context) {
+        // prepare outbox message for storage only
+        if (Boolean.TRUE.equals(context.getIsInbound())) {
+            return;
+        }
+
+        // custom serialization logic
+    }
+}
+
+**Don't complete the context in any of those two handlers, otherwise other
+handlers aren't called.**
+```
+
+:::
+
 ## Handling Outbox Errors { #handling-outbox-errors }
 
 The outbox by default retries publishing a message, if an error occurs during processing, until the message has reached the maximum number of attempts.

From 67652b36814746e0d68b75c2780aa4397df6effd Mon Sep 17 00:00:00 2001
From: Thomas Bonk <130759028+t-bonk@users.noreply.github.com>
Date: Fri, 20 Mar 2026 10:19:36 +0100
Subject: [PATCH 2/5] changes after review

---
 java/outbox.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/java/outbox.md b/java/outbox.md
index 07cf6cf4a1..1ceff7a24a 100644
--- a/java/outbox.md
+++ b/java/outbox.md
@@ -331,16 +331,18 @@ be transformed using custom outbox handlers:
 ```java
 @Component
 @ServiceName(value = "*", type = OutboxService.class)
-public class DwcOutboxHandler implements EventHandler {
+public class CustomOutboxHandler implements EventHandler {
 
     @On
     void publishedByOutbox(OutboxMessageEventContext context) {
-        // Restore DwC context only
+        // Restore custom values from context only
         if (Boolean.FALSE.equals(context.getIsInbound())) {
             return;
         }
 
         // custom deserialization logic
+        Long date = (Long) context.getMessage().getParams().get("orderDate");
+        context.getMessage().getParams().put("orderDate", Instant.ofEpochSecond(date));
     }
 
     @Before(event = "*")
@@ -351,6 +353,8 @@ public class DwcOutboxHandler implements EventHandler {
         }
 
         // custom serialization logic
+        Instant date = (Instant) context.getMessage().getParams().get("orderDate");
+        context.getMessage().getParams().put("orderDate", new Long(date.getEpochSecond()));
     }
 }
 

From 98ba29022e99f3a0d1e385d368d9aeba1847343c Mon Sep 17 00:00:00 2001
From: Thomas Bonk <130759028+t-bonk@users.noreply.github.com>
Date: Fri, 20 Mar 2026 15:30:03 +0100
Subject: [PATCH 3/5] changes after review

---
 java/outbox.md | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/java/outbox.md b/java/outbox.md
index 1ceff7a24a..1d9d9603ba 100644
--- a/java/outbox.md
+++ b/java/outbox.md
@@ -324,9 +324,12 @@ You must ensure that the handler is completing the context, after executing the
 ::: tip Preparing outbox entries with custom data types
 
 The outbox has no information regarding the structure and the data types that
-shall be serialized and deserialized to and from the outbox. To avoid
-serialization and deserialization errors, the corresponding data objects must
-be transformed using custom outbox handlers:
+shall be serialized and deserialized to and from the outbox.
+
+As long as there are CDS modelled services used, no special handling is
+required. Only if there are custom data types used or additional context
+properties are required, special handling needs to be implemented to avoid
+serialization and deserialization errors in custom outbox handlers:
 
 ```java
 @Component

From 9a44ba201676a63e05ee7d0d4fe57aeeadae3c25 Mon Sep 17 00:00:00 2001
From: Thomas Bonk <130759028+t-bonk@users.noreply.github.com>
Date: Fri, 20 Mar 2026 15:41:39 +0100
Subject: [PATCH 4/5] Changes after review

---
 java/outbox.md | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/java/outbox.md b/java/outbox.md
index 1d9d9603ba..0954836dad 100644
--- a/java/outbox.md
+++ b/java/outbox.md
@@ -321,7 +321,7 @@ You must ensure that the handler is completing the context, after executing the
 
 [Learn more about event handlers.](./event-handlers/){.learn-more}
 
-::: tip Preparing outbox entries with custom data types
+::: tip Customizing Outbox Entries
 
 The outbox has no information regarding the structure and the data types that
 shall be serialized and deserialized to and from the outbox.
@@ -331,7 +331,9 @@ required. Only if there are custom data types used or additional context
 properties are required, special handling needs to be implemented to avoid
 serialization and deserialization errors in custom outbox handlers:
 
-```java
+::: code-group
+
+```java [srv/src/main/java/com/myapp/CustomOutboxHandler.java]
 @Component
 @ServiceName(value = "*", type = OutboxService.class)
 public class CustomOutboxHandler implements EventHandler {
@@ -360,10 +362,12 @@ public class CustomOutboxHandler implements EventHandler {
         context.getMessage().getParams().put("orderDate", new Long(date.getEpochSecond()));
     }
 }
+```
+
+:::
 
 **Don't complete the context in any of those two handlers, otherwise other
-handlers aren't called.**
-```
+handlers aren't called and functionality is broken.**
 
 :::
 

From aab9ccbe750ac14b2f2c7257cc5f158ba965f324 Mon Sep 17 00:00:00 2001
From: Mahati Shankar <93712176+smahati@users.noreply.github.com>
Date: Mon, 23 Mar 2026 14:28:16 +0100
Subject: [PATCH 5/5] cosmetics

---
 java/outbox.md | 9 +--------
 1 file changed, 1 insertion(+), 8 deletions(-)

diff --git a/java/outbox.md b/java/outbox.md
index 0954836dad..0cba54d407 100644
--- a/java/outbox.md
+++ b/java/outbox.md
@@ -326,12 +326,7 @@ You must ensure that the handler is completing the context, after executing the
 The outbox has no information regarding the structure and the data types that
 shall be serialized and deserialized to and from the outbox.
 
-As long as there are CDS modelled services used, no special handling is
-required. Only if there are custom data types used or additional context
-properties are required, special handling needs to be implemented to avoid
-serialization and deserialization errors in custom outbox handlers:
-
-::: code-group
+Special handling is needed to avoid serialization and deserialization errors in custom outbox handlers if custom data types are used, **or** if additional context properties are required. _Special handling isn't required for CDS model-based services._
 
 ```java [srv/src/main/java/com/myapp/CustomOutboxHandler.java]
 @Component
@@ -364,8 +359,6 @@ public class CustomOutboxHandler implements EventHandler {
 }
 ```
 
-:::
-
 **Don't complete the context in any of those two handlers, otherwise other
 handlers aren't called and functionality is broken.**