Alerts Module


With the Alerts module you can store and edit information about alerts for users identified by a supplied external id. These operations can be performed using an OSGI service or by firing events. The way you choose depends entirely on you and on your implementation.


The Alerts module is a database structure for storing alerts. The module also listens for the specific events associated with alerts. The true meaning of some fields located in a single alert depends on your implementation(alertType, priority, externalId).

Alert fields

Name Description Type
id Alert id generated by the system. Long
externalId External id of the person who is associated with this alert. This is an arbitrary value controlled by your application. This field is required. String
alertType Alert type, this field is required. org.motechproject.alerts.domain.AlertType
dateTime Alert date. org.joda.time.DateTime
priority Alert priority, this field is required and it’s used in Alert compareTo method(It works in the same way as, priority2)). The true meaning of the priority depends on your implementation. Long
status Alert status, this field is required. org.motechproject.alerts.domain.AlertStatus
description Alert description. String
data Key/Value pairs. Map<String, String>

Alert type


  • HIGH
  • LOW

For example CRITICAL may indicate that, if an alert will not be readed by the patient then it can have very bad consequences(For example, a reminder of taking the medicines).

Alert status


  • NEW - Alert has not been read.
  • READ - Alert was readed.
  • CLOSED - Alert is closed.

OSGI Service API

Public API

  • void create(String entityId, String name, String description, AlertType type, AlertStatus status, int priority, Map<String, String> data); - create a new alert.
  • List<Alert> search(AlertCriteria alertCriteria) - finds alerts matching the specified search criteria.
  • Alert get(Long id) - finds an alert by ID.
  • void update(Long alertId, UpdateCriteria updateCriteria) - updates an alert with given ID.

Deprecated methods:

  • void update(String alertId, UpdateCriteria updateCriteria)
  • Alert get(String id)


Search Criteria

To search alerts using OSGI Service you must create a org.motechproject.alerts.contract.AlertCriteria object which specifies the search criteria. To add filters, use the following methods:

  • AlertCriteria byExternalId(String id) - Adds criterion to search by external id of alert.
  • AlertCriteria byStatus(AlertStatus status) - Adds criterion to search by status of alert.
  • AlertCriteria byType(AlertType type) - Adds criterion to search by type of alert.
  • AlertCriteria byPriority(Integer priority) - Adds criterion to search by priority of alert.
  • AlertCriteria byDateRange(DateTime from, DateTime to) - Adds criterion to search by the date of alert in the given range.
AlertCriteria searchCriteria = new AlertCriteria();
searchCriteria.byExternalId("personId"); //primary criterion
List<Alert> alerts =;

First added filter is primary criterion. This means that records will be retrieved from the database on the basis of it’s value. Fetched records are filtered on the basis of the following criteria. If you do not add any filters, all records will be retrieved.

Update Criteria

To update alerts using OSGI Service you must create a org.motechproject.alerts.contract.UpdateCriteria object which specifies the update criteria. To change an alert values, use the following methods:

  • UpdateCriteria status(AlertStatus newStatus) - Marks that status field of alert is to be updated and stores the new value.
  • UpdateCriteria name(String newName) - Marks that name field of alert is to be updated and stores the new value.
  • UpdateCriteria description(String newDescription) - Marks that description field of alert is to be updated and stores the new value.
  • UpdateCriteria priority(int newPriority) - Marks that priority field of alert is to be updated and stores the new value.
  • UpdateCriteria data(Map<String, String> newData) - Marks that data field of alert is to be updated and stores the new value.
UpdateCriteria updateCriteria = new UpdateCriteria();
alertService.update(alert.getId(), updateCriteria);

Alert Events


The module handles the event with the following subjects(In parentheses are the names of constants, which are located in org.motechproject.alerts.EventKeys):

  • org.motechproject.alerts.api.Create.Alert (CREATE_ALERT_SUBJECT)
  • org.motechproject.alerts.api.Close.Alert (CLOSE_ALERT_SUBJECT)
  • org.motechproject.alerts.api.Mark.Alert.Read (MARK_ALERT_READ_SUBJECT)

To create new alert using event you must put to the event object parameters corresponding to the alert fields:

  • “ExternalId” - required (EXTERNAL_ID_KEY)
  • “AlertName” - not required (ALERT_NAME)
  • “AlertType” - required (ALERT_TYPE)
  • “AlertPriority” - required (ALERT_PRIORITY)
  • “AlertStatus” - required (ALERT_STATUS)
  • “AlertDescription” - not required (ALERT_DESCRIPTION)
  • “AlertData” - not required (ALERT_DATA)

To close alert or mark it as read you must put to the event object parameter “AlertId”(ALERT_ID). To create and fire events you will need MOTECH Platform Event module, so you must add following dependency:


To fire events you must use OSGI Service, so you will need add reference to it in the blueprint.xml in your module:

<osgi:reference id="eventRelay" interface="org.motechproject.event.listener.EventRelay"/>

Creating Alert

Map<String, Object> params = new HashMap<>();
params.put(EventKeys.EXTERNAL_ID_KEY, "personId");
params.put(EventKeys.ALERT_NAME, "alertName");
params.put(EventKeys.ALERT_DESCRIPTION, "sample description");
params.put(EventKeys.ALERT_TYPE, AlertType.MEDIUM);
params.put(EventKeys.ALERT_STATUS, AlertStatus.NEW);
params.put(EventKeys.ALERT_PRIORITY, 3);
params.put(EventKeys.ALERT_DATA, alertData);
MotechEvent createAlertEvent = new MotechEvent(EventKeys.CREATE_ALERT_SUBJECT, params);

Updating Alert

Updates in this context is understood as closing alert or marking it as read.

Map<String, Object> params = new HashMap<>();
params.put(EventKeys.ALERT_ID, alertId);
MotechEvent updateAlertEvent = new MotechEvent(EventKeys.MARK_ALERT_READ_SUBJECT, params);


This module does not require any custom configuration.