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",
  "dhis2": {
    "programUid": "WSGAb5XwJ3Y",
    "profileStageUid": "iF5roNU7QWm",
    "ancExamStageUid": "JqW7c9HYjVr",
    "ancVisitNumberDe": "bXVD2EMF7UW",
    "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.
• 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.
  • ancExamStageUid: Program stage UID for ANC Examination.
  • ancVisitNumberDe: Data element UID for ANC Visit Number.
  • 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.

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