Async Event Handler

The Async Event Handler is deprecated as of version 17 and will be removed in version 18.

If migration is not immediately possible, the Async Event Handler can continue to be used for small data volumes until version 18. We strongly recommend migrating to the Streaming Event Handler for all new implementations.

How Async Event Handler works

The Async Event Handler (EventHandlerAsync) is a legacy implementation that captures change events during data processing and forwards them to external systems.

In earlier versions, this handler was referred to as the data event handler and publisher.

The handler consists of two independent components that work together:

The processor type you choose determines when and how events are grouped before being sent to publishers.
The publisher type determines where and how the events are delivered.

During processing, the event handler stores all necessary data to a specified storage (file or database). Once the operation is completed, it initiates publishing of the data.

If publishing of an event fails for any publisher, the publishing is stopped. When resumed, the event at which the failure occurred is published again by all publishers (that means some publishers might have distributed it multiple times).

The preceding events are not published again.

Types of processors

A single Async Event Handler requires one processor. The following processors are available, each of which consumes events in a specific way.

Simple event processor

Passes events directly to the configured publishers (grouping events per operation). As all events are available, the simple event processor is suitable when aggregating file outputs is required.

Batching event processor

Groups events by entity type then passes them to publishers in small groups, allowing for faster event delivery.

The batch size is defined in nme.eventHandler.publish.batchSize in Runtime Parameters. Events are delivered to the publisher in batches so aggregation is not possible.

The batching event processor is most suitable when faster reporting is required or when append storage databases are used.

Grouping event processor

Groups related events before passing them to publishers.

The processor groups the events in a tree-like model similar to the relationship configuration defined in the logical model. One processor can contain multiple roots.

The root of each tree model is the entity for which related entities will be configured (the root is typically the central entity for a given domain, for example, Party in case of the MDM Example Project).

Master entity-based roots can have both other master entities and instance entities as children. Instance entity-based roots can have other instance entities as children. Entities belonging to one group are sent to publishers together.

For configuration instructions, see Processors.

Types of publishers

Publishers define how events are distributed to external systems. The Async Event Handler supports multiple publisher types, and you can configure multiple publishers within a single event handler.

The following publisher types are available.

Additionally, two delegating publishers are available. These are configured directly in the generated nme-event_handler.gen.xml configuration file (see Event Handler).

Filtering Publisher: Adds filtering capabilities to any publisher.
Retrying Publisher: Adds retry logic to any publisher.

Event JMS publisher

This publisher sends the events through Java Message Service (JMS).

To run this publisher, the JMS server connection must first be configured in the MDM runtime configuration.

Event plan publisher (recommended)

Sends events as records to a configured ONE plan.

Only the events of the entities defined in the steps that follow are processed. Each entity is generated as a separate Integration Input step in the plan, with the following naming convention: <entity_name>.master.<view> for master entities and <entity_name>.instance for instance entities.

The publisher is available to both SoR and consolidation event handlers.

Event plan publisher propagates data in batches (applies to batching and grouping processors). Therefore, steps that operate with all records in one processing run (like Text File Writer, Representative Creator, JDBC Writer with a "before" script) do not behave as expected. Data change events might get overwritten with each batch processing, or might not be part of the same publishing batch.

This behavior is required to support the "at-least-one semantic" of the Async Event Handler and related publishers.

Event SQL publisher

Executes SQL statements on a database.

To run this publisher, a data source must first be configured in the MDM runtime configuration.

HTTP SOAP publisher

Constructs a SOAP message and sends it through an HTTP protocol to a specified destination.

To run this publisher, a URL resource must first be configured in the MDM runtime configuration.

Standard output publisher

Outputs events to standard output (StdOut), making it useful for debugging and presenting.

Traversing plan publisher

Extends the event plan publisher. The traversing plan publisher ensures that all related records defined by the model are present in the plan.

The configuration requires defining a root entity and related entities. Master entity-based roots can have both other master and instance entities as related entities. Instance entity-based roots can have other instance entities as related entities.

When an event containing one or more entities from the defined model is sent to the publisher, the adapter traverses through all the relationships between the entities, retrieves their data, and provides them to the plan to their corresponding Integration Input steps.

The traversing plan publisher is called by the processor for each group of related records that will always contain at least one record that had some change event. The record group is always consistent and complete based on the defined publisher model configuration (that is usually a subset of the MDM logical model).

iSM publisher

Compiles and sends XML messages to a specified host and port from every event it receives. Every XML message is then prefixed with the length of the message in the form of a 4-byte binary integer (big endian) and sent separately to the specified host and port.

This publisher is available to both SoR and consolidation event handlers.

Processor and publisher combinations

While combining different processors and publishers is possible, some combinations might produce redundant configurations. If that occurs, you are notified during configuration.

For example:

Using the Grouping Event Processor with the Traversing Plan Publisher creates redundancy, as both components perform relationship traversal.
The Simple Event Processor works best with the Event Plan Publisher when aggregation is needed.
The Traversing Plan Publisher is recommended with the Grouping Event Processor to remove duplicate results.

Migrating to Streaming Event Handler

To migrate from the Async Event Handler, configure a new Streaming Event Handler using the following table as a guideline. The table summarizes key changes and actions required when migrating between the two event handler implementations.

Feature Async Event Handler Streaming Event Handler Action required

Feature	Async Event Handler	Streaming Event Handler	Action required
Processors	Separate configuration for processors (simple, grouping, batching) and adapters.	Unified logic built into the handler.	Create a new event handler according to Add a Streaming Event Handler. Processor configuration is one of the required steps.
Publishers	Multiple types (SOAP, SQL, Plan, StdOut, Traversing, iSM). Flat entity list.	Plan publisher only. Hierarchical `<root>` model.	Configure the plan publisher for the new event handler. See What can be reused.
Persistence	File system or database.	Database only.	Switch to database persistence.
Retrying	Fixed interval retries (`<retryDelay>`)	Exponential backoff (`<maxRetryTimeout>`)	Configure the new timeout parameter.
Filters	Basic event and entity filters.	Event, entity, and operation type filters.	Configure additional filters as needed. See What can be reused.
Hard delete event	`meta.event_type = 'DELETE'`	`meta.event_type = 'PURGE'`	Update filter expressions as needed.

Processors

Separate configuration for processors (simple, grouping, batching) and adapters.

Unified logic built into the handler.

Create a new event handler according to Add a Streaming Event Handler. Processor configuration is one of the required steps.

Publishers

Multiple types (SOAP, SQL, Plan, StdOut, Traversing, iSM).
Flat entity list.

Plan publisher only.
Hierarchical <root> model.

Configure the plan publisher for the new event handler. See What can be reused.

Persistence

File system or database.

Database only.

Switch to database persistence.

Retrying

Fixed interval retries (<retryDelay>)

Exponential backoff (<maxRetryTimeout>)

Configure the new timeout parameter.

Filters

Basic event and entity filters.

Event, entity, and operation type filters.

Configure additional filters as needed. See What can be reused.

Hard delete event

meta.event_type = 'DELETE'

meta.event_type = 'PURGE'

Update filter expressions as needed.

What can be reused

Even though the migration is manual, you can keep and reuse significant parts of your existing implementation:

Filter Expressions: The core filtering logic remains the same. You can copy it directly into the new handler configuration and edit as needed:
- If filtering DELETE events, update the type to PURGE or UPDATE. See Event types.
- Review the new filtering options and expand your configuration as required.
ONE plans: Your existing component (.comp) files for publishing are still valid and the new handler sends data in a compatible format.

While no changes are needed in the core transformation logic within the plans, you might need to adjust the plan Integration Input steps to align with the new traversing model.

Was this page useful?