Event Utilities
Authors:
Kirill Gaiduk, Holger Lierse
Changed on:
10 July 2025
Overview
The `EventUtils` class in the `util-core` bundle provides a set of essential helper methods to simplify event creation, modification, and forwarding. Using these utilities helps to eliminate boilerplate code and prevent common errors, such as forgetting to copy event attributes or improperly handling event schedules.
Key points
- Safe Event Handling: The utilities eliminate common errors by automatically handling attribute copying and schedule management when cloning or forwarding events.
- Immutability:
`Event`objects are immutable.`EventUtils`methods always return a new event instance when a modification is made. - Simplified Forwarding: Provides simple, one-line methods for common forwarding patterns, like cloning and sending an event immediately (
`forwardInboundEventWithNewName`) or adding attributes (`forwardInlineEventWithAttributes`). - Type-Safe Attribute Access: Use
`getEventAttributeAs`to retrieve and convert an event attribute to a specific type (including complex POJOs) in a single, null-safe operation.
Cloning and Forwarding Events
`cloneAndRenameEvent`
You can use the `EventUtils.cloneAndRenameEvent` method to create a copy of the context event with a new name, which can then be forwarded to trigger the next Ruleset or used as a payload for sending a webhook.
1Event clonedEvent = EventUtils.cloneAndRenameEvent(context, "newEventName");`cloneAndRenameEvent` (using a transformer)
The `EventUtils.cloneAndRenameEvent` method can also be used to copy the context event with a new name, apply a custom transformation, which can then be forwarded to trigger the next Ruleset or used as a payload for sending a webhook. Inbound scheduled events will automatically be converted to non-scheduled unless the outbound event has a different root entity type. The third parameter is optional and can be `null`; it accepts an `Event.Builder` to apply additional parameters to the event.
1Event clonedEvent = EventUtils.cloneAndRenameEvent(context, "newEventName",
2 e -> e.scheduledOn(new Date()))`forwardInboundEventWithNewName`
To send an event with the same structure but a new name, use the `EventUtils.forwardInboundEventWithNewName` method. This is a convenient wrapper around the `cloneAndRenameEvent` method, which will send the newly cloned event.
Inbound scheduled events will automatically be converted to non-scheduled events, and all event attributes will be preserved.
1EventUtils.forwardInboundEventWithNewName(context, "newEventName")`forwardInlineEventWithAttributes`
Use the `EventUtils.forwardInlineEventWithAttributes` method to send an event with the same structure but a new name and custom attributes.
Originating External Events or Cross Workflow Events will automatically be converted to Inline Events, and all event attributes will be preserved.
1Map<String, Object> attributes = ImmutableMap.of("attribute1", "attribute1Value");
2EventUtils.forwardInlineEventWithAttributes(context, "newEventName", attributes);`forwardCustomInlineEvent`
To send a new event with the same structure but a different name and apply a custom transformation, use the `EventUtils.forwardCustomInlineEvent` method. This enhanced version of `forwardEvent` includes a transformer, allowing you to modify the event before it is sent.
If the transformer changes the type of the root entity (`rootEntityType`), the event is treated as a Cross Workflow Event, and a `scheduledOn` value is set ensuring a new Execution Context. If not, the event is treated as an Inline Event, and any original External Event will automatically be converted to an Inline Event.
1EventUtils.forwardCustomInlineEvent(context, "newEventName",
2 (e) -> e.rootEntityType("Location"))Scheduling Events
`scheduleEvent`
Use the `EventUtils.scheduleEvent` method to create a Scheduled Event that will be executed a specified number of seconds in the future.
1EventUtils.scheduleEvent(context, event, 10)`scheduleEvent` (with name)
To schedule an event with a new name to occur a specified number of seconds in the future, use the `EventUtils.scheduleEvent` method. This method uses the current `context.getEvent()` and changes the event name while preserving all other fields.
1EventUtils.scheduleEvent(context, "eventName", 10)Event Attributes
`appendEventAttribute`
The `EventUtils.appendEventAttribute` method adds a new attribute to an event. Since events are immutable, this method returns a new event instance with the added attribute.
1Event appendedEvent = EventUtils.appendEventAttribute(event, "myAttribute", "test")This will return a new instance of the `Event` class based on the inbound event, but with the newly added attribute `"myAttribute"` and its value `"test"`.
`getEventAttributeAs`
Retrieves a named attribute from the event and safely converts it to the desired type. This method uses `JsonUtils.anyToPojo` under the hood, so it can handle complex type conversions.
It is particularly useful for ensuring consistent attribute handling across different plugins, as it can convert between similar types. However, it does not support conversions between completely incompatible types.
1TestAttribute myAttribute = EventUtils.getEventAttributeAs(context, "myPojo",
2 TestAttribute.class).orElse(null)
