22.4. SMS Command

SMS command feature helps DHIS2 system receiving SMS from users, patients, or even anonymous. A SMS command is an object containing the configurations for each SMS form: reporting data from phones or j2me apps, alerting users, registering patient or user, etc.

22.4.1. Set up SMS command

This is where you can create a new SMS command

Usually each SMS command has it own property, then the setting up process may be different from each other. Currently, we have 4 types of SMS command:

With KEY_VALUE_PARSER and J2ME_PARSER, the SMS command will have dataset because those are used for reporting data

With ALERT_PARSER and UNREGISTERED_PARSER, the SMS command will have user group because those are used for sending message such as SMS, DHIS2 conversation, email.

There are certain parameters which are common to all SMS Command types. These parameters have default values configured in the system, if user does provide any value to these parameters then those default ones will be used. Here is the list of those parameters

Table 22.2. Common Parameters

ParameterTypeDescription
Code and value SeparatorStringTo provide custom code value separator. Default is "="
Reply message if no codes are sent (only the command)StringTo provide message if no code is found in SMS text input. Default is "Parameter missing"
Wrong format messageStringTo provide message if command is not formatted correctly. Command should be fomatted as per code value separator. This message will also be sent back if any mandatory parameter is missing.
No user messageStringTo provide message if sending phone number is not registered in DHIS 2.
User belong to more than one OrgUnit messageStringCertain SMS command types require user ( retrived from sending phone number ) to be associated with only one organization unit. This message can be configured to be sent back in case that requirement is not fullfilled.
Success MessageStringTo provide message that will be sent upon successful completion of the process.

22.4.2. SMS Command Type

The SMS command is basically defined by its parser type. In other word, each SMS command has one unique parser to parse the plain text SMS, then the result will be used for the purpose of that SMS command.

22.4.2.1. SMS Command for Reporting Data

In order to report data for example data set (aggregation), we use SMS commands which have KEY_VALUE_PARSER (for phone's plain text), or J2ME_PARSER (for j2me apps)

If the command has name "report", and a list of data element with code like above. The format should be: [command's name] [code][value] [code][value] [code][value]....,the [value] of course might be changed depends on real data, so you have to preapre a SMS text like this example: report vo2 vn5 a2 b6 z3 x1

In case the command has a separator for instance ".", the SMS text should be:

report vo.2.vn.5.a.2.b.6.z.3.x.1

or report vo.2|vn.5|a.2|b.6|z.3|x.1

Moreover in SMS text input, orgUnit can be specified like this org orgUnitCode If no orgUnit is specified in SMS then user is retrieved first from the sending phoneNumber and then orgUnit from that user. As far as PeriodType is concerned it should be specified in this format "ddMM" for example 3108, but in case its not specified then PeriodType will be retrieved from DataSet attached to SMSCommand

With the J2ME_PARSER, you don't need to prepare those SMS text, because the J2ME will do this job

User can set the custom response message for "Wrong format message", "No User Message", "User belong to more than one OrgUnit message" and "Success message". If no custom message is being set, system will use the default message.

22.4.2.2. SMS Command for Alerting, Registering

In order to alert users or register patients, users, we use SMS commands which have ALERT_PARSER (for phone's plain text), or UNREGISTERED_PARSER (for j2me apps)

The format of those command will be: [command's name] [text], for example:

alert one emergency case in A town

Commands which has ALERT_PARSER will be received from users only

22.4.2.3. SMS Command for Event Registration

Event Registration can be used to register anonymous event into the system based on the data collected through SMS. This command type is associated with Programs of type WITHOUT_REGISTRATION. For example Birth events can be tracked using this parser.

The format of those command will be: [command's name] [code][separator][value], for example:

birth A=1,B=2,G=Male

Code/Value separator is configurable. Comma "," is by default taken as field separator. Commands which has EVENT_REGISTRATION_PARSER will be received from DHIS2 users only. Once command is successfully received then data received in SMS will be parsed and event will be registered in DHIS2.