Admin FAQ How to work with messaging services

How to work with messaging services?

Table of contents

• Introduction
• The message template
• The query
• Query optimization
• Creating message for patients – the patient template
• The actor concept
• Message scheduling
• Executing scheduled messages

Introduction

This manual describes the inner workings behind messaging services in CFL. This is a technical manual, that gives an overview of how the messaging module functions – how does it translate messaging service definitions, such as a ‘visit reminder’ into messages sent to patients or their caregivers through SMS or voice calls.

The purpose of this manual is to give an overview to the technical reader and give them an idea on how the module functions without having to delve into the code. It can also serve as a map to those perusing the code – give them an overview they need in order to gather their bearings.

The purpose of this manual is not to introduce the messaging module to an end user – this is a technical manual aimed at people seeking to find out how the module is working under the hood.

The message template

A messaging service starts with a message template. This template represents services and their configuration. A single message template maps to a service – for example, the visit reminder has its own template.

The message template is a domain entity, stored in the OpenMRS database. It consists of multiple fields, but the most important ones are the query ones:

• service_query_type – the type of the service query, currently only SQL is supported
• service_query – the query executed when scheduling messages
• calendar_service_query – the query executed when showing message executions on the calendar GUI view (optional)

The template also contains a list of template fields – these are definitions for fields that users (doctors) need to fill out when scheduling messages, basically they are inputs that are then passed to the query.

The query

The query is expected to return executions in a given timeframe. These executions represent messages that were sent or are to be sent.

This query can be executed from two distinct contexts:

• Scheduling context – in this context, the service query is called to schedule messages to be sent in the future and the date range passed to the query, will always be in the future.
• Calendar context – in this context, the service query is called to display messages on the calendar GUI for a given patient. If calendar_service_query is defined, it will be used instead.

The reason for which the query can be redefined for the calendar context using the calendar_service_query field is optimization. The scheduling will happen for thousands of patients consecutively and does not have to worry about past executions. However, the calendar query needs to take into consideration both future and past executions. It also does not need to be that performant – it is generally executed for one patient on the GUI view.

Query optimization

The query can be optimized, this is indicated by the should_use_optimized_query field. When this is set to true, the query will be executed once – and it is expected to return results for all patients at once. If it is not set, the query will be executed on a per-patient basis and is expected to return executions for a single patient.

Creating message for patients – the patient template

The patient entity is an entity related to the message template. While the message template represents the service, the patient template represents this service configured for a particular patient.

It contains most importantly the template fields values – these are the values for template parameters already filled out by the user configuring messaging for this patient. These are the actual values for these params that will be passed on the service query when it will be executing for this patient.

It also defines the actor – the recipient of the actual message.

The actor concept

It’s important to understand that at the patient template level, we introduce the concept of an actor. The actor is the person for which the messages are intended. In most cases, this will be the patient themselves. However, this can also be a related person, such as a caregiver, that should receive the call – for example, if the patient is unable to receive the calls themselves.

The message will always be sent to the actor, which needs to be an OpenMRS Person (doesn't have to be a patient) related through a relationship to the patient (the relationship entity).

Message scheduling

Messages are scheduled through a cron job. The scheduler processes all the message templates. Then, if the template is optimized, it simply executes its query. If not, it executes its query for each patient template. The job passes a date range to the query dependent on its configuration (it is tied to how often it runs). If executing per each patient template, the values from that template are passed to the query as named parameters. For the optimized query – it needs to retrieve those from the database itself.

For each execution returned by the query, a task is scheduled at the time when it is expected to be sent. When the task executes, it is expected for the message to be delivered to the recipient. The execution details are saved in the database.

Executing scheduled messages

The execution itself is simple. The scheduled task is executed at the given time and retrieves execution details from the database. This information is then packed into an event, which is next published using the OpenMRS Event module. This event is destined to the proper recipient based on the channel – it can be tailored for the CallFlows module or the SMS module (other implementation possible in the future).

Once the Messages module pushes out the event, the message is then in the hands of the channel modules. It is expected to deliver the message to the recipient, either by sending an SMS or calling them.