Community tracking of TB

Hi all,

Can anyone share their experiences of building a tracker program to track TB contacts in the community?

I have the task of building a TB tracker and I would be very pleased if anyone could share some material.



Thank you for your question! As you can see I moved your topic post to the category #implementation:tuberculosis where you might find some TB tracker program experiences and discussion topics.

Just today in the Tracker Config course @brian shared this slide with reference to “List recommended analyses” which I think you might find interesting. (search (Ctrl+F) for TB to quickly navigate and check out the ideas)

I actually think you will benefit from the whole presentation so I will share the recording with you here when it is available in the DHIS2 YouTube channel

@fernandoshake, here’s the recording - I recommend you follow along the whole playlist for Tracker Config ^_^:

Hi @fernandoshake
I would recommend you also consider the TB Case Surveillance metadata package, found here:

The documentation here explores in more detail what is included.

If you need to record the contacts of each TB patient, you could potentially download this package, and add to it the Relationships feature in DHIS2. But it’s nice if you could share more details about your use case here, so we can make a clearer recommendation.


Hi @brian,

Here are some details:
Activists go out to the community to find contacts of TB index case, screen them, and refer those who have signs and symptoms to the health facility for diagnosis and treatment. Below I am trying to describe the workflow through a diagram, and I am also attaching the form.
The activist screens the household contacts of the TB index case:

  1. If they have no symptoms, the activist will make a second visit to screen for symptoms again. If during five visits (contact examination), a contact presents no Tb symptoms, the contact is closed.
  2. If they have symptoms, they are referred to the health facility for diagnosis.
    A) If the lab result is positive, they initiate treatment.
  3. B) If the result is negative, the activist will visit the contact again for screening.

NB: If a contact is a child (<15) and has no symptoms the first time they are screened, they are referred to the health facility to initiate Chemoprophylaxis. Although the contact starts Chemoprophylaxis, they will be screened in the following visits by activist and closed if no symptoms are detected during five visits.


Household tracking form

This appears on the form
F - fever
WL – Weight loss
NS – night sweats
C - cough
A - asthenia

@brian, I was wondering if you could help me organize program stages based on the attached form.


Here’s my opinion @fernandoshake if you want - @brian correct me if I got it wrong please :blush:. (:

Stage 1: Scan for symptoms (repeatable stage) with a Data Element has the number of visits and a program rule that doesn’t allow the visit number to be more than 5 so that when in the 5th visit the only option is to complete the stage.
Stage 2: Lab tests (not repeatable)
Stage 3: Treatment [if Lab result is positive]

If lab result is negative then the visits Data Element changes back to Zero using a program rule so that it’s possible to repeat Stage 1 and screen for symptoms again (within the stages 1 → 3 use program rules to control most of the conditions mentioned.)

I had the idea that it might be possible to enroll a TEI more than once in a program but I might have misunderstood that. (: Thanks!

Hope this helps in a way!

1 Like

Hi @Gassim,

In each visit, we need to screen the contacts for these symptoms (F - fever, WL – Weight loss, NS – night sweats, C - cough, A - asthenia). If a contact has any of the symptoms, he/she is referred to US HF for testing. If a contact has presents no symptoms in all 5 visits, we close the contact. So I think we should also have a data element to capture symptoms here:

These parts are clear:

Here I don not see how I can implement this part through a program rule. I am not an expert at Program rules. Would mind helping me achieve this?

What is meant in this text snippet:

In the diagram, we show that if a contact is a child (<15) and has no symptoms the first time he/she screen, they initiate Chemoprophylaxis, but they continue to be screened in the following visits. Can we create a stage for Chemoprophylaxis treatment for this case?


Thanks @fernandoshake for sharing details of your use case, and @Gassim for your response.

From my reading of your requirements, a new enrollment will be opened when a new contact is identified. The enrollment is closed when five consecutive visits have been made where the contact presents no symptoms. If the enrollment is closed, and at a later time the same person (TEI) becomes a household contact of a second index case, then the same person can re-registered with a new enrollment to repeat the cycle. I think this is what Gassim means by “I had the idea that it might be possible to enroll a TEI more than once in a program”.

Stage 1: Screening Visit
Scan for symptoms
You could have yes-only or yes-no data elements for each of the five symptoms as you describe.
If any symptoms are present, then a yes-only data element is shown and auto-filled Yes, saying patient has symptoms and referral should be made to health facility.

Stage counter program rule.
This assumes you need five consecutive visits without symptoms to close the case.
a) Create a data element for program stage for “Stage Counter” (positive integer).
b) Create a program rule variable for “Stage Counter, Previous” for previous event in the program stage and “Stage Counter, Current” for current event.
c) Create a program rule variable for “Symptoms Present, Previous” for previous event in the program stage.
d) Program rule Priority 1: if !d2:hasValue('counter_previous') || d2:hasValue('symptoms_previous') then ASSIGN Stage Counter value 1.
e) Program rule Priority 2: if d2:hasValue('counter_previous') && !d2:hasValue('symptoms_previous') then ASSIGN Stage Counter value V{counter_previous} + 1
f) Program rule Priority 3: if V{stage_counter} == 5 then WARNING under the stage counter data element that enrollment should be closed if no symptoms are present.
g) Program Rule Priority 3: if V{stage_counter} > 5 then SHOW ERROR under stage counter. You can also have a program rule action to HIDE PROGRAM STAGE to prevent the user from generating more Screening Visit events.

I see from the reporting form that the scheduled contact visits are unevenly spaced.
You could use program rules to suggest a next contact date to the activist in a separate data element, based on the current stage number (if this is visit 2, add 15 days from event date; if this is visit 3, add 2 months). The activist would then manually schedule a new visit at that date.

You may want to have a separate stage for this, or include it in a combined “Treatment” stage (see below). Note there is also a program rule action to “Hide Program Stage”. So if the contact is over 15 yeas old, the chemoprophylaxis stage is “hidden”. If contact is under 15 years old, a program rule alerts the user to make this referral.

For the referrals, this could be made through the DHIS2 referrals feature. You would need a program rule (warning box) to tell the user to make this referral to the appropriate facility.

Some remaining questions to think about for the other program stages.

  • Will labs have access to the program to capture lab results for diagnosis, or is this information captured elsewhere? Can there potentially be more than one lab result for the same contact?
  • Will facilities have access to the program to capture details on a child’s Chemoprophylaxis treatment, or is this data captured elsewhere?
  • Will facilities have access to the program to capture details on the Treatment of positive TB Cases, or is this data captured elsewhere? Note that the Metadata Package linked above is for TB Case Surveillance, i.e. positive TB cases, and does not capture TB contacts or presumptive TB cases. So once the patient has been identified as a positive case, perhaps they should be enrolled in a separate Case Surveillance program to track their treatment.
1 Like

Hi @brian,

About this part,

Lab details, details on a child’s Chemoprophylaxis treatment and details on the Treatment of positive TB Cases will all captured by the health activist in the tracker program on android phone. After referring contacts with symptoms, the health activist will go to the HF to check the contacts’ diagnosis results and capture the information on android. If the result is negative, the activist will go back to the community again after a period of time ( intervals showing in the reporting from) to screen the same contacts and refer them again to the HF if they still present symptoms. This process goes on each time the lab result is negative. That means if the contact presents symptoms in all five visits made by the activist but the lab result is negative we close the contact. It is like the process that occurs if a contact has no symptoms in all visits. (I think is a second scenario because in the first scenario we have a situation in which a contact has no symptoms in all visits)

This process breaks if in one of visit the contact has symptoms and is referred to the HF but the lab result is positive. Here the contact starts treatment and there is no more screening in the community afterwards

I do not understand here

I hope this new information provides more details about my use case.

Thanks again.

Thanks for that @fernandoshake . Your use case is now more clear.

In the previous post, I assumed a scenario where a cycle of screening visits “resets” to the 1st visit once the contact presents symptoms but has a negative lab result. That would mean a contact could receive more than 5 visits in total.

From your response, I see that every contact receives exactly five scheduled screening visits from the activist, on a fixed interval schedule. Only when the contact presents symptoms and tests positive is the sequence is broken, and then, no further contacts are needed.

In this scenario, I would actually recommend five separate stages for the screening visits (Visit 1, Visit 2, etc), and a sixth stage for the Lab Result (repeatable). There are a few reasons for this.

  • You can auto-generate scheduled events for each screening visit on enrollment, and you can set a fixed interval of days from enrollment date for each visit, just like your paper form. The user guide has step-by-step instructions on how to do this.
  • The enrollment should be closed once five screening visits have been entered. On the stage configuration for Visit 5, you can check “Ask User to Complete Program When Stage is Complete”, and it will prompt the Activist to close the Contact on the fifth screening visit.
  • Program indicators are generally easier to configure for non-repeatable events.

For the lab result stage, you can create a program rule that is triggered by a positive test result. This would hide the remaining Screening Visit stages, tell the user to close the Contact’s enrollment, and (optionally) ask them to open a new enrollment in a separate TB Case Surveillance program.

For Chemoprophylaxis, you need the start date and end date of the child’s treatment. Where you put these data points depends on how the Activist collects those dates. It could be entered at the end of the Screening Visit stage, or during the Lab Result stage, or a separate program stage (if Chemoprophylaxis is recorded at a different facility than the lab).

I hope this helps.

Hi @brian,

I am so happy with all your explanation. Things are getting clearer for me. Would you mind you elaborating on this passage:

If we have program stages in the following order:

PS. Screening visit 1
PS. Screening visit 2
PS. Screening visit 3
PS. Screening visit 4
PS. Screening visit 5
PS. Lab Result

I understand from the passage that if contact has symptoms ,for example, in any of screening visits and the result is positive, we hide the remaining screening visits and he user closes the contact’s enrolment. (if yes, this is exactly what we want. once we have a positive lab result, there should be no more screening)

a) Our problem is how the program rules would look like to control the flow
b) To ask user to open a new enrollment in a separate program. Would this be done through a prompt message. I mean in case the user closes the contact and wants to register treatment and treatment outcomes in another program.
c) Opening a new enrollment in a separate program (treatment in my case) means registering the person again for treatment program?

Thank you for having patience with me. I am still a learner.

Dear @fernandoshake. Great to hear things are clearer.

To quickly address your questions:
a) Program rules to control the flow when positive test result occurs. The simplest solution would not be “hiding” the subsequent Screening Visit stages, but rather SHOW ERROR in the Screening Visit stages on the condition that the test result in the latest lab result event is Positive. Then, you could not submit any new Screening Visits once the Contact is positive. If you wanted to hide the subsequent Screening Visit stages, the logic is a bit more complex for each Visit stage, like this:
If V{test_result_latest_event}=="POSITIVE" && d2:hasValue([mandatory Visit 1 Data Element]) && !d2hasValue([mandatory Visit 2 Data Element]), hide screening visit stage 2, 3, 4, & 5.
If V{test_result_latest_event}=="POSITIVE" && d2:hasValue([mandatory Visit 2 Data Element]) && !d2hasValue([mandatory Visit 3 Data Element]), hide screening visit stage 3, 4, & 5.

b) Yes, this message would be shown through a SHOW WARNING program rule action on the “Test Result” data element, when the value turns Positive.

c) To open a new enrollment, you would enroll the same TEI in a different program. Then you could use the same TEI Attributes (name, date of birth, etc) in both programs.

These images show how to do the operation on Tracker Capture (web) and Android, respectively.


Hi @brian,

My last question:

As regards to program rules, I will opt for the simple solution as suggested, i.e, SHOW ERROR in the Screening Visit stages on the condition that the test result in the latest lab result event is Positive. But from the DHIS 2 Manual, it seems the program rule action SHOW ERROR is applicable to a dataElement or a trackedEntityAttribute and not a program stage. Am I right?

Adopting this solution means showing error in the screening visit stage.

It has really been a great lesson. I really can’t ask for more.

Thanks for being so responsive and helping me.

Hi @fernandoshake ,

It is optional to attach a SHOW ERROR action to a data element or tracked entity attribute. If you do not attach it to either, a pop-up box will display when you open the Screening Visit stages. A ERROR ON COMPLETE action will display an error in pop-up when you try to “Complete” the program stage.

Thanks for your interest in this material! Good luck with the implementation.

1 Like