Event Module


The Event module allows to create a listener, that contains an action, triggered by firing an event. The module is using MotechEvent to provide event with specific data that can be sent by any MOTECH module (using EventRelay) when an event is fired. The module is using ActiveMQ for delivery of the events. It is possible to register your own callback function using EventCallbackService.


The Event module uses MotechEvent to store information about fired event. Instance of this class can be sent by any module to a specific handler to fire an event. Every module can also be a subscriber of an event and receive events to handle.

Main fields of MotechEvent:

Field Description Type
subject Identifies event. The listeners can subscribe event using it. String
messageDestination Destination of an event. Contains the id of the Motech listener that this event is meant for. String
callbackName Name of service, which is containing callback functions. String
parameters Parameters of event. Contains data used in event execution. Map<String, Object>
metadata Stores any additional data, that is not meant to be the event’s payload. Map<String, Object>

This class is immutable.


There are 2 ways to create an event listener:

  1. Use an @MotechListener annotation to a handler function.

    In Core Architecture you can find an example usage of this annotation.

  2. Use an OSGi EventListenerRegistry service exposed by the event module.

Register custom callback

ActiveMQ is sending events with its own retry. The default ActiveMQ retries will take place when the handler method fails (an exception is thrown). The default retries can be disabled by custom event callback service (flag returned by the failureCallback method). To register event callbacks you should implement an EventCallbackService interface and expose it as OSGi service. Then this service name must be set in the callback field of the MotechEvent.

Example of a custom callback

First you should implement an EventCallbackService:

public class ServiceName implements EventCallbackService {
    public static final String CALLBACK_NAME = "CallbackName";

    public boolean failureCallback(MotechEvent event, Throwable throwable) {
        //Actions for failure

    public void successCallback(MotechEvent event) {
        //Actions for success

    public String getName() {
        return CALLBACK_NAME;

Then expose it as the OSGi service:

<osgi:service id="serviceId" auto-export="interfaces" ref="serviceName"

After that you can use a callback service in MotechEvent by using e.g. such construction:

eventRelay.sendEventMessage(new MotechEvent(eventSubject, parameters, ServiceName.CALLBACK_NAME, metadata));