Admin SMS Templates and Gateway - hmislk/hmis GitHub Wiki

SMS Templates and Gateway Configuration

Overview

HMIS can send automated SMS notifications for events such as lab result readiness, appointment reminders, and admission confirmations. The SMS system requires a gateway connection (external SMS provider) and message templates. Configuration is managed through application-level ConfigOptions and the SMS testing utility in the Lab Administration module.

When to Use

  • Setting up SMS notifications for the first time
  • Changing the SMS gateway provider or credentials
  • Updating message templates when text needs to change
  • Testing whether the SMS gateway is connected and sending correctly

SMS Gateway Configuration

Gateway credentials and settings are stored as Application-Level ConfigOptions. Common keys include:

Config Key Description
SMS gateway URL / API endpoint The provider's API URL
SMS API username / API key Authentication credentials
SMS sender name / from number The sender ID shown on outgoing messages
SMS enabled Boolean toggle to enable/disable all SMS sending

Navigate to Administration → Manage Institutions → Application Options and filter by "SMS" to find and edit these keys.

Important: SMS credentials are sensitive. Ensure only authorised administrators can access Application Options.

Message Templates

SMS message content is stored as Long Text ConfigOptions. Each template typically uses placeholder variables (e.g. {patientName}, {resultDate}) that are substituted at send time.

Common template keys (key names vary by deployment):

  • SMS Template - Lab Result Ready
  • SMS Template - Appointment Reminder
  • SMS Template - Admission Confirmation
  • SMS Template - Bill Ready

Edit templates via Application Options — find the key, click to edit, update the Long Text value, and save.

Testing the SMS Connection

A test utility is available from the Lab Administration module:

  1. Click Administration → Manage Lab Services
  2. Navigate to Check SMS (in the lab admin index)
  3. Enter a test phone number and a test message
  4. Click Send Test SMS
  5. Verify the message is received on the test device

If the test fails, check:

  • The gateway URL is correct
  • API credentials are valid and not expired
  • The sending number/ID is approved by the provider
  • Network connectivity from the server to the SMS gateway

SMS Notification Events

SMS notifications can be triggered by various system events. The exact set of events depends on which subscriptions are configured. See User Subscription Management for how to set up event-based alerts.

Technical Notes (Admin/Developer)

SMS sending is handled by the SmsController or equivalent service bean. The gateway type is selected from the SmsGateway enum or similar configuration. Templates are retrieved via configOptionApplicationController.getLongTextValueByKey(key). Placeholder substitution is performed in the sending method before the HTTP call to the gateway.

Related Features