FHI Enable – Lifestyle SMS Campaign Script

This script drives a lifestyle SMS campaign from DHIS2. It reads campaign configuration and DHIS2 metadata from the DHIS2 dataStore and can run in test or live mode.

Requirements

• Python 3.9+ with requests and pandas installed.
• Network access to your DHIS2 instance.
• A DHIS2 user with permission to read tracked entity data and manage the sms-campaigns dataStore namespace.

DHIS2 connection configuration

The script connects to DHIS2 using environment variables. All three must be set:

• DHIS2_URL: Base API URL, e.g. https://your-server.org/dhis/api
• DHIS2_USERNAME: DHIS2 username
• DHIS2_PASSWORD: DHIS2 password

Example:

export DHIS2_URL="https://your-server.org/dhis/api"
export DHIS2_USERNAME="myuser"
export DHIS2_PASSWORD="mypassword"
python sms_script.py --next-week

DataStore configuration (sms-campaigns/config)

The script expects a JSON object stored at:

• Namespace: sms-campaigns
• Key: config

The JSON combines scheduling, message content, and DHIS2 metadata:

{
  "anchorMonday": "2026-01-05",
  "weeksUntilStop": 20,
  "dhis2": {
    "programUid": "WSGAb5XwJ3Y",
    "profileStageUid": "iF5roNU7QWm",
    "birthOutcomeStageUid": "gEyexNoAqHB",
    "birthOutcomeDe": "VIEg1M2z5Vs",
    "phoneAttributeUid": "RJxLa3nITB3"
  },
  "campaigns": {
    "DIET": {
      "dayOfWeek": 0,
      "messages": ["Diet SMS 1", "Diet SMS 2"]
    },
    "PHYSICAL": {
      "dayOfWeek": 2,
      "messages": ["Physical SMS 1"]
    },
    "AIR": {
      "dayOfWeek": 4,
      "messages": ["Air SMS 1"]
    }
  }
}

• anchorMonday: A Monday ISO date that defines the start of the bi‑weekly cycle.
• weeksUntilStop: Number of weeks after enrollment that a woman keeps receiving messages (see below). Optional; defaults to 20.
• dhis2: DHIS2 metadata for the program and attributes used to select and contact women.
  • programUid: Program UID.
  • profileStageUid: Program stage UID for the “Women’s profile and history” event.
  • birthOutcomeStageUid: Program stage UID that holds the birth/pregnancy outcome. The birth-outcome data element is only checked within this stage.
  • birthOutcomeDe: Data element UID for the Birth Outcome. When any non-empty value is recorded for this data element, the woman stops receiving messages.
  • phoneAttributeUid: Tracked entity attribute UID for the phone number.
• campaigns.*.dayOfWeek: 0=Monday, 1=Tuesday, …, 6=Sunday.
• campaigns.*.messages: Ordered list of SMS texts for that campaign.

To adapt the script to a different DHIS2 instance, update only the dhis2 block and campaigns in the dataStore JSON; the code does not need changes.

When messages stop

A woman who has a “Women’s profile and history” event receives campaign messages until either of the following stop conditions is reached, whichever comes first:

• 20 weeks after enrollment — once the send date is on or after enrollmentDate + weeksUntilStop weeks (20 by default).
• A birth outcome is recorded — once the birthOutcomeDe data element holds any non-empty value in the birthOutcomeStageUid stage.

The window length is set by weeksUntilStop in the dataStore config. If it is missing, the script falls back to 20 weeks.

Creating or updating the DataStore entry

You can use the DHIS2 Datastore Manager app or plain HTTP requests.

Using HTTP (POST first time, PUT for updates):

curl -X POST -u "$DHIS2_USERNAME:$DHIS2_PASSWORD" \
  -H "Content-Type: application/json" \
  -d @sms_datastore_config.json \
  "$DHIS2_URL/dataStore/sms-campaigns/config"

curl -X PUT -u "$DHIS2_USERNAME:$DHIS2_PASSWORD" \
  -H "Content-Type: application/json" \
  -d @sms_datastore_config.json \
  "$DHIS2_URL/dataStore/sms-campaigns/config"

Running the script

From the sms directory:

python sms_script.py

Key options:

• --live: Actually send SMS via the DHIS2 gateway. Without this flag, the script only exports messages.
• --next-week: Preview messages for next week’s Monday, Wednesday, and Friday.
• --target-date YYYY-MM-DD: Run for a specific date.

On completion the script writes or logs:

• In test mode:
  • sms_test_YYYYMMDD_HHMMSS.csv: one row per eligible TEI and campaign with a phone number, including status.
  • sms_test_YYYYMMDD_HHMMSS.json: array of outbound SMS payloads, each of the form {"message": "<text>", "recipients": ["<phone>"]}.
• In live mode:
  • No CSV/JSON is created for the run.
  • Each successful POST to the DHIS2 SMS API is appended as a JSON line to sms_live.log together with TEI, phone, campaign, date, and message.

Cron example

Run every Monday, Wednesday, and Friday at 09:00 on a Unix-like system:

0 9 * * 1,3,5  cd /path/to/sms && DHIS2_URL="https://your-server.org/dhis/api" DHIS2_USERNAME="user" DHIS2_PASSWORD="pass" python3 sms_script.py --live >> sms_cron.log 2>&1