MDM Client: Subscribing to Event Notifications

This document provides client application developers the background needed to subscribe to YOUnite MDM notification topics and event types so they can receive real-time updates to MDM events. A topic is created for each MDM zone and for each MDM zone there are various notification types.

Note: Currently we are using simple username/password authentication between the YOUnite UI and AMQ. All interaction between zones and clients that are tied to zones (e.g. YOUnite UI) should interact with AMQ with OAuth tokens or even better SSO→OAuth. See YOUMDM-103.

Subscribing to Topics

MDM uses the Apache ActiveMQ messaging system which leverages the STOMP text-based messaging protocol. STOMP allows clients to be written easily. A STOMP protocol implementation in node.js can be found here.

Adding STOMP

Add the following libraries in your local workspace:

amq_jquery_adapter.js
amq.js
stomp.js

Note: Hari is working on inserted the STOMP libraries into the project . There may be some changes to the following using npm to install the libraries.

Injecting STOMP Libraries

Directly add to the library section of your source code e.g. (use the appropriate path to your libraries):

{src: `${this.ASSETS_SRC}/vendor-libs/js/amq_jquery_adapter.js`, inject: true, vendor: true},
{src: `${this.ASSETS_SRC}/vendor-libs/js/amq.js`, inject: true, vendor: true},
{src: `${this.ASSETS_SRC}/vendor-libs/js/stomp.js`, inject: true, vendor: true},

Subscribing to a Topic

Setup your credentials in your configuration (e.g. config.ts)

//
// Define these in a config file e.g. config.ts
//
ACTIVEMQ_CLIENT: process.env.ACTIVEMQ_CLIENT ? process.env.ACTIVEMQ_CLIENT : 'ws://docker.local:61614',
ACTIVEMQ_USER_NAME: process.env.ACTIVEMQ_USER_NAME ? process.env.ACTIVEMQ_USER_NAME : 'admin',
ACTIVEMQ_PASSWORD: process.env.ACTIVEMQ_PASSWORD ? process.env.ACTIVEMQ_PASSWORD : 'admin',

Setup your handler:

subscribeNotification() {
	this.loggedInZoneUuid = localStorage.getItem('zoneUuid');
	this.client = Stomp.client(Config.ACTIVEMQ_CLIENT);
	let topicUrl = '/topic/' + this.loggedInZoneUuid;
	let connectHeaders = {
		login: Config.ACTIVEMQ_USER_NAME,
		passcode: Config.ACTIVEMQ_PASSWORD,
		'client-id': this.loggedInZoneUuid
	};
	let componentRef = this;
	
	let callback = function (message) {
		// called when the client receives a STOMP message from the server
		componentRef.toastr.info(message.body);
		componentRef.incrementUnreadNotificationCount();
	};
	let subscribeHeaders = {'activemq.subscriptionName': this.loggedInZoneUuid};
	this.client.connect(connectHeaders, function () {
		componentRef.client.subscribe(topicUrl, callback, subscribeHeaders);
	}
);

Disconnect from the handler on logout, this should be in the same file as the above handler:

this.client.disconnect();

Notification Event Types

The following is list of event types that a subscriber can be notified of on a per zone (topic) basis. Each time an event is triggered it publishes a new notification of a given event type .

Event	Event Type	Default Scope	Additional Payload

Event	Event Type	Default Scope	Additional Payload
A zone is created	ZONE_POST	ALL	none
A zone is updated	ZONE_PUT	ALL	none
A zone is deleted	ZONE_DELETE	ALL	none
A zone's thumbnail image is updated (TBD)	ZONE_THUMBNAIL_PUT	ALL	TBD
A data domain is created or a new version of of the data domain has been created	DOMAIN_POST	ALL	TBD
A data domain has been created	DOMAIN_PUT	ALL	TBD
A data domain has been deleted	DOMAIN_DELETE	ALL	TBD
An MDR has been created for a given data domain (TBD)	DOMAIN_NAME_DATA_POST	ALL	TBD
An MDR has been updated in a given data domain (TBD)	DOMAIN_NAME_DATA_PUT	ALL	TBD
An MDR has been deleted in a give data domain (TBD)	DOMAIN_NAME_DATA_DELETE	ALL	TBD

Notification Event Response Body

The notification's JMS header includes the following:

key	value

key	value
description	A full description of the event - i.e. a full concatenation of the information described below for easy displaying.
changeVersion	The resources change version.
createdDate	The date the resource was created.
Name	The resource name
message-id	The JMS message ID.
dateCreated	Unix timestamp of when the event notification was sent
uuid	Zone uuid of target resource
eventType	One of the above described "Notification Event Types"
originatorName	The name of the zone that generated the event.
originatorUuid	The UUID of the zone that generated the event.
timestamp	The time the notification was created.
optional	Other key/values that are appropriate for the notification type

Requesting Notification Log

A client can make a request to get the log history for all notifications sent to their zone. The user provides their zone and a from and to date.