Hi @chase.freeman
Please, remember that the Android DHIS2 SMS Gateway is something that we DO NOT recommed using in production and that in those cases you should use a real gateway. In anycase, if you are receving the SMS in the backend everything should be automatically handled by the backend module.
I will provide an example for a DataSet with detailed information on every step (so this can be used as further reference post for other people).
-
We have the DHIS2 Android App without Internet connectivity and we want to synchronize with SMS. For this we need to make sure that the SMS Gateway has been established in the phone either via the Android Settings Web App or manually in the settings (will not go into that as this is already well documented).
-
Depending on the version of the App the workflow might differ but you will end up sending an SMS like below, this can always be reviewed in the SMS application of the phone
-
This SMS is received by the Gateway, here you have several options. You are claiming to use the Android DHIS2 SMS Gateway App. It doesn’t matter, the important thing is to note that the Gateway will generate an API request like the following (to simplify I am showing/performing it manually)
Please note in the picture above how the text value corresponds to the SMS sent by the phone. Also, important to make sure that the user that is making the request has a matching phone number (see common issues further below). In this case I am encoding admin / district with basic auth. I am showing this here:
-
If the API POST request is properly composed and the values mentioned above are correct, the server will reply with a 200.
-
By inspecting the logs, we see how the encoded SMS is understood by the server and the actions performed (in this case, the update of the values in the dataset) without having to do anything else.
INFO org.hisp.dhis.sms.SmsConsumerThread [taskScheduler-20] Received SMS: sample text
WARN org.hisp.dhis.sms.SmsConsumerThread [taskScheduler-20] No SMS command found in received data
INFO org.hisp.dhis.sms.SmsConsumerThread [taskScheduler-9] Received SMS: pAJkAHDBAV+4GjmtpUlUVTl5PTUDmud9iohJJxUyZGBkZmBiAZyggQPXNMBq1PQL0UDgf39qCA==
INFO org.hisp.dhis.sms.listener.CompressionSMSListener [taskScheduler-9] New received Sms submission decoded as: {
"orgUnit": {
"uid": "DiszpKrYNg8",
"hash": 941647,
"type": "ORGANISATION_UNIT"
},
"dataSet": {
"uid": "ce7DSxx5H2I",
"hash": 0,
"type": "DATASET"
},
"complete": false,
"attributeOptionCombo": {
"uid": "HllvX50cXC0",
"hash": 2713,
"type": "CATEGORY_OPTION_COMBO"
},
"period": "202301",
"values": [
{
"categoryOptionCombo": {
"uid": "sqGRzCziswD",
"hash": 129,
"type": "CATEGORY_OPTION_COMBO"
},
"dataElement": {
"uid": "FTRrcoaog83",
"hash": 965030,
"type": "DATA_ELEMENT"
},
"value": "1",
"smsValue": {
"value": 1,
"type": "INT"
}
},
{
"categoryOptionCombo": {
"uid": "sqGRzCziswD",
"hash": 129,
"type": "CATEGORY_OPTION_COMBO"
},
"dataElement": {
"uid": "LjNlMTl9Nq9",
"hash": 354938,
"type": "DATA_ELEMENT"
},
"value": "2",
"smsValue": {
"value": 2,
"type": "INT"
}
},
{
"categoryOptionCombo": {
"uid": "sqGRzCziswD",
"hash": 129,
"type": "CATEGORY_OPTION_COMBO"
},
"dataElement": {
"uid": "eY5ehpbEsB7",
"hash": 952839,
"type": "DATA_ELEMENT"
},
"value": "1",
"smsValue": {
"value": 1,
"type": "INT"
}
},
{
"categoryOptionCombo": {
"uid": "sqGRzCziswD",
"hash": 129,
"type": "CATEGORY_OPTION_COMBO"
},
"dataElement": {
"uid": "Ix2HsbDMLea",
"hash": 1032117,
"type": "DATA_ELEMENT"
},
"value": "2",
"smsValue": {
"value": 2,
"type": "INT"
}
}
],
"header": {
"type": "AGGREGATE_DATASET",
"version": 2,
"lastSyncDate": "Mar 2, 2023, 9:47:45 AM",
"submissionId": 1
},
"userId": {
"uid": "lt0qSrjAagY",
"hash": 0,
"type": "USER"
}
}
-
And in fact, the SMS in the inbox can be see marked as processed
-
We can see how the data matches Data Entry in web (left) an phone (right):
Common issues
- In case the user sending the API request doesn’t have a matching phone number (either because of not set or because of mismatch) the API will produce a 409 error
- If the SMS sent is not properly formated the API will accept the SMS but will not process it and will mark it as unhandled (this is visible in the logs and in the SMS inbox). Note how I have prepend a “XX” to the SMS sent:
API Request
Error log
INFO org.hisp.dhis.sms.SmsConsumerThread [taskScheduler-19] Received SMS: XXpAJkAHDBAV+4GjmtpUlUVTl5PTUDmud9iohJJxUyZGBkZmBiAZyggQPXNMBq1PQL0UDgf39qCA==
WARN org.hisp.dhis.sms.SmsConsumerThread [taskScheduler-19] No SMS command found in received data
SMS Inbox
I hope this clarifies the situation. Let me know if you need further assistance
