described how to outbox custom CAP service events

java/outbox.md

@@ -191,6 +191,98 @@ and use custom outboxes instead to avoid delays in outbox entry processing for t
 occur during processing.
 :::
 
+### Outboxing Custom CAP Service Events
+
+The generic outbox allows you to outbox custom CAP service events in a elegant and CAP-like way. The following way
+describes this feature using a custom CAP service.
+
+To provide a custom CAP service, you need to define the service interface:
+
+```java
+import com.sap.cds.services.Service;
+
+public interface CustomService extends Service {
+	String SERVICE_NAME = "CustomService";
+
+	void sendCustomEvent(String name, String lastName);
+}
+```
+
+Since the implementation of the method `CustomService.sendCustomEvent(String name, String lastName)` is going to wrap
+the passed parameters in an `EventContext` object, you have to define a custom event context:
+
+```java
+@EventName(CustomEventContext.EVENT_NAME)
+public interface CustomEventContext extends EventContext {
+	String EVENT_NAME = "CustomEvent";
+
+	static CustomEventContext create() {
+		return EventContext.create(CustomEventContext.class, null);
+	}
+
+	String getName();
+	void setName(String name);
+
+	String getLastName();
+	void setLastName(String lastName);
+}
+```
+
+The custom event context must only provide properties that can be serialized to JSON, since it is going to be stored in the
+database when outboxing it.
+
+The implementation of the service is done as a SpringBoot component that is automatically instantiated and registered in the
+CAP service catalog when your microservice is starting:
+
+```java
+@Component
+public class CustomServiceImpl extends ServiceDelegator implements CustomService {
+	private static final Logger logger = LoggerFactory.getLogger(CustomServiceImpl.class);
+
+	protected CustomServiceImpl() {
+		super(SERVICE_NAME);
+	}
+
+	@On
+	public void handleCustomEvent(CustomEventContext context) {
+		logger.info("CustomEvent received: name = {}, lastName = {}", context.getName(),  context.getLastName());
+		context.setCompleted();
+	}
+
+	@Override
+	public void sendCustomEvent(String name, String lastName) {
+		CustomEventContext customEventContext = CustomEventContext.create();
+		customEventContext.setName(name);
+		customEventContext.setLastName(lastName);
+
+		emit(customEventContext);
+	}
+}
+```
+
+The implementation of custom service provides the event handler `handleCustomEvent(CustomEventContext context)` that is called
+when a `CustomEventContext` is received. Pleas note, that the event context must be set to completed after the logic has been executed.
+
+The custom events can now outboxed by getting an outboxed instance of the custom service as shown in the following example:
+
+```java
+OutboxService outboxService;
+CustomService customService;
+CustomService outboxedCustomService = outboxService.outbox(customService);
+
+outboxedCustomService.sendCustomEvent("John", "Doe");
+```
+
+It also possible to create a `CustomEventContext` programmatically for emitting using the outboxed service:
+
+```java
+CustomEventContext customEventContext = CustomEventContext.create();
+customEventContext.setName("John");
+customEventContext.setLastName("Doe");
+
+outboxedCustomService.emit(customEventContext);
+```
+
 ### Technical Outbox API
 
 The generic outbox provides the technical API `OutboxService.submit(String event, OutboxMessage)` that can