MDM Service: Publishing Event Notifications

This document provides MDM developers the background needed to publish new notification event types to the JMS message broker so that clients can subscribe to topics and receive real-time updates to MDM events. In JMS, a topic implements publish and subscribe semantics. When you publish a message it goes to all the subscribers who are interested - so zero to many subscribers will receive a copy of the message. Only subscribers who had an active subscription at the time the broker receives the message will get a copy of the message.

The JMS implementation for YOUnite MDM is Apache ActiveMQ (AMQ). 

Subscribers (e.g. the YOUnite UI) use the STOMP protocol to register listeners and receive notifications (messages).

Topics and Notification Types

JMS uses "topics" as a distribution mechanism for publishing messages to multiple subscribers. MDM creates topics based on MDM zones.  Each notification generated by MDM will be of a given topic (zone) and event type.  

The published list of notification event types and their payloads can be found on the MDM Client: Subscribing to Event Notifications (this page should be updated as developers add new notification event types).

Notification Delivery Scope

The scope of delivery for a given event type will be limited to the following in the future. For now all event types are of type ALL:

Notification Flow

This notification flow describes the interaction between the core YOUnite MDM service, the JMS service and client that subscribe to YOUnite MDM events (e.g. the YOUnite UI).  This notification flow is separate from the YOUnite MDM Router/Adaptor flow that will be published in a separate document.

Adding Notification Types to MDM

More notification types will need to be added as features are added to MDM. The process is broken down into the following steps:

1. Add the new notification topic name  to the topic enum in: open-mdm/src/main/resources/raml/schemas/topicPref.json. This is a RAML file so the source needs to be built for the change to take effect.
   
   
2. Typically the notification is triggered at the resource layer (e.g. impl.resource/DomainsResource.java) after the service layer has successfully completed the event. Use the static method createEvent() in the NotificationService class.
   
   Notification Service Method
   

   NotificationService.createEvent(Enum eventType, String message, Map<String, String> map)

   Trigger a JMS notification of a given topic (zone) for a given event type.  

   Parameters

   eventType - The event type being generated defined in the enum TopicPref.Topic

   message - A message to be sent to the subscriber. This string should be a human readable appropriate for viewing in a log or UI.

   map - Optional map of key values that the subscriber can use to discover details about the event.

   The notification sent to the subscriber can retrieve a full message using the "body" key found in the JMS payload. A series of key/value pairs can be retrieved inside of the JMS header. A series of standard key/value pairs are included in the header of each request (for a description see MDM Client: Subscribing to Event Notifications).  Additionally, the header will include the key/value pairs provided by the publisher in "map" described above. 
        

3. The notification deliver scope for an event by default is ALL but you can override this by TBD (TODO: Mayank):

Subscribing to Topics

Clients such as the YOUnite UI require real time updates of MDM events. Background on how to develop applications that subscribe to events can be found on the MDM Client: Subscribing to Event Notifications page.