Alerts Module¶
Contents
Introduction¶
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.
Alert¶
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
Long.compare(priority1, 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¶
org.motechproject.alerts.domain.AlertType
- CRITICAL
- HIGH
- MEDIUM
- 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¶
org.motechproject.alerts.domain.AlertStatus
- 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)
Criteria¶
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
searchCriteria.byType(AlertType.MEDIUM);
searchCriteria.byStatus(AlertStatus.NEW);
List<Alert> alerts = alertService.search();
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();
updateCriteria.status(AlertStatus.READ;)
updateCriteria.name("newName");
updateCriteria.description("newDescription");
updateCriteria.priority(2);
updateCriteria.data(newData);
alertService.update(alert.getId(), updateCriteria);
Alert Events¶
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:
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>motech-platform-event</artifactId>
<version>${project.version}</version>
</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);
eventRelay.sendEventMessage(createAlertEvent);
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);
eventRelay.sendEventMessage(updateAlertEvent);
Configuration¶
This module does not require any custom configuration.