Configure programs in the Maintenance app¶

About programs¶

Traditionally, public health information systems have been reporting aggregated data of service provision across its health programs. This does not allow you to trace the people provided with these services. In DHIS2, you can define your own programs with stages. These programs are a essential part of the "tracker" functionality which lets you track individual records. You can also track other ‘entities’ such as wells or insurances. You can create two types of programs:

To create a program, you must first configure several types of metadata objects. You create these metadata objects in the Maintenance app.

Configure event programs in the Maintenance app¶

About event programs¶

Single event without registration programs are called event programs. You configure them in the Maintenance app. Event programs can have three types of data entry forms:

Note

• Custom forms takes precedence over section forms if both are present.

• If no custom or section form are defined, the basic form will be used.

• The Android apps only supports section forms.

You can create program notifications for event programs. The notifications are sent either via the internal DHIS2 messaging system, via e-mail or via text messages (SMS). You can use program notifications to, for example, send an automatic reminder to a tracked entity 10 days before a scheduled appointment. You use the program’s tracked entity attributes (for example first name) and program parameters (for example enrollment date) to create a notification template. In the Parameters field, you'll find a list of available tracked entity attributes and program parameters.

Workflow: Create an event program¶

1. Enter the event program details.

2. Assign data elements.

3. Create data entry form(s): Basic, Section or Custom.

4. Assign the program to organisation unit(s).

5. Create program notification(s).

Create or edit an event program¶

Enter event program details¶

1. Open the Maintenance app and click Program > Program.

2. Click the add button and select Event Program in the popup menu.

3. Enter program details, then click next.

   Field	Description
   Name	The name of the program.
   Color	Color used for this program in the data capture apps.
   Icon	Icon used for this program in the data capture apps.
   Short name	A short name of the program. The short name is used as the default chart or table title in the analytics apps.
   Description	A detailed description of the program.
   Version	The version of the program. This is used for example when people collect data offline in an Android implementation. When they go online and synchronize their metadata, they should get the latest version of the program.
   Category combination	The category combination you want to use. The default setting is None.
   Open days after category option end date	If you selected a category combination other than None, you may enter zero or a positive number. This lets you enter data for this program for a category option up to the specified number of days after that category option's end date.
   Data approval workflow	The data approval workflow you want to use. The default setting is No value.
   Completed events expiry date	Defines the number of days for which you can edit a completed event. This means that when an event is completed and the specified number of expiry days has passed, the event is locked. If you set "Completed events expiry days" to 10", an event is locked ten days after the completion date. After this date you can no longer edit the event.
   Expiry period type Expiry days	The expiry days defines for how many days after the end of the previous period, an event can be edited. The period type is defined by the expiry period type. This means that when the specified number of expiry days has passed since the end date of the previous period, the events from that period are locked. If you set the expiry type to "Monthly" and the expiry days to "10" and the month is October, then you can't add or edit an event to October after the 10th of November.
   Block entry form after completed	Select checkbox to block the entry form after completion of the event of this program. This means that the data in the entry form can't be changed until you reset the status to incomplete.
   Feature type	Sets whether the program is going to capture a geographical feature type or not. - None Nothing is captured. - Polygon An area is captured. For single event programs the area will be the area representing the event being captured. For tracker programs, the area will represent the area of the enrollment. - Point A point/coordinate is captured. For single event programs the point will be representing the event being captured. For tracker programs, the point will represent the enrollment.
   Validation strategy	Sets the server and client side validation requirement. Data type validation is always performed regardless of the validation strategy. An integer field is never stored containing text, for example. - On complete This option will enforce required field and error messages to be fixed when completing the event, but the event can be saved to the server without passing these validation requirements. For legacy reasons, this is always the validation strategy for tracker programs, where each data value in the event is stored to the server while entering data. - On update and insert This option will enforce required field validation when saving the event to the server regardless of the completion status. When using this option no events can be stored without passing validations.
   Pre-generate event UID	Select checkbox to pre-generate unique event id numbers.
   Description of report date	Type a description of the report date. This description is displayed in the case entry form.

4. Click next.

Assign data elements¶

1. Click Assign data elements.

2. In the list of available items, double-click the data elements you want to assign to the event program.

3. (Optional) For each data element, add additional settings:

   Setting	Description
   Compulsory	The value of this data element must be filled into data entry form before you can complete the event.
   Allow provided elsewhere	Specify if the value of this data element comes from other facility, not in the facility where this data is entered.
   Display in reports	Displays the value of this data element into the single event without registration data entry function.
   Date in future	Will allow user to select a date in future for date data elements.
   Mobile render type	Can be used to select different render types for mobile devices. Available options vary depending on the data element's value type. For example, for a numerical value you may select "Default", "Value", "Slider", "Linear scale", and "Spinner".
   Desktop render type	WARNING: NOT IMPLEMENTED YET. Can be used to select different render types for desktop (i.e. the web interface). Available options vary depending on the data element's value type. For example, for a numerical value you may select "Default", "Value", "Slider", "Linear scale", and "Spinner".

4. Click next.

Create data entry forms¶

The data entry forms decide how the data elements will be displayed to the user in the Event Capture app.

1. Click Create data entry form.

2. Click Basic, Section or Custom.

3. To create a Basic data entry form: Drag and drop the data elements in the order you want.

4. To create a Section data entry form:

   1. Click the add button and enter a section's name, description and render type for desktop and mobile.

   2. Click the section so it's highlighted by a black line.

   3. Add data elements by clicking the plus sign next to the data elements' names.

   4. Repeat above steps until you've all the sections you need.

   5. Change the section order: click the options menu, then drag the section to the place you want.

5. To create a Custom data entry from: Use the WYSIWYG editor to create a completely customized form. If you select Source, you can paste HTML code directly in the editing area. You can also insert images for example flags or logos.

6. Click next.

Access¶

Access options decide who can capture data for the program or view/edit the program's metadata. A program can be shared to organisation units, and in addition, the main program and any program stages' access options can be configured through the Sharing dialog. Access options are available in the Access tab.

Assign organization units:

1. In the organisation tree, double-click the organisation units you want to add to the program to.

   You can locate an organisation unit in the tree by expanding the branches (click on the arrow symbol), or by searching for it by name. The selected organisation units display in orange.

Change roles and access:

1. Scroll down to the Roles and access section.

   The first row shows the main program's access options, and each subsequent row shows the options of one program stage. Program stages with a warning icon (exclamation mark) contain access options that deviate from the main program, meaning they are accessed by a different combination of users.

2. Click on either of the rows and the Sharing dialog will show.

3. Modify the access options accordingly. See documentation on the sharing dialog for details.

4. Click the Apply button.

5. Repeat the process for each program/program stage. You can also copy all access options from the main program to your child programs:

   1. Select the program stages you want to have similar access options as the main program by toggling the checkboxes on the right hand side of the program stages. You can also choose to Select all program stages, Deselect all program stages or Select similar stages, in terms of access options, to that of the main program. Similar stages are toggled by default.

   2. Click Apply to selected stages

Create program notifications¶

1. Create the message you want to send:

   1. Click What to send?.

   2. Enter a Name.

   3. Create the Subject template: Double-click the parameters in the Template variables field to add them to your subject.

      Note

      The subject is not included in text messages.

   4. Create the Message template: Double-click the parameter names in the Template variables list to add them to your message.

      Dear A{w75KJ2mc4zz}, You're now enrolled in V{program_name}.

2. Define when you want to send the message:

   1. Click When to send it?.

   2. Select a Notification trigger.

      Notification trigger	Description
      Program stage completion	The program stage notification is sent when the program stage is completed
      Days scheduled (due date)	The program stage notification is sent XX number of days before or after the due date You need to enter the number of days before or after the scheduled date that the notification will be sent.

3. Define who you want to send the message to:

   1. Click Who to send it to?.

   2. Select a Notification recipient.

      Notification recipient	Description
      Tracked entity instance	Receives program notifications via e-mail or text message. To receive a program notification, the recipient must have an e-mail address or a phone number attribute.
      Organisation unit contact	Receives program notifications via e-mail or text message. To receive a program notification, the receiving organisation unit must have a registered contact person with e-mail address and phone number.
      Users at organisation unit	All users registered to the selected organisation unit receive program notifications via the internal DHIS2 messaging system.
      User group	All members of the selected user group receive the program notifications via the internal DHIS2 messaging system
      Program	TBA

   3. Click Save.

4. Repeat above steps to create all the program notifications you need.

5. Click Save.

Note

You configure when the program notifications are sent in the Data Administration app > Scheduling > Program notifications scheduler.

• Click Run now to send the program notifications immediately.

• Select a time and click Start to schedule the program notifications to be send at a specific time.

Reference information: Program notification parameters¶

Configure tracker programs in the Maintenance app¶

About Tracker programs¶

Single or multiple event programs with registration are called Tracker programs. A program must be specified with only one tracked entity. Only tracked entities that are the same as the tracked entity of program can enroll into that program. A program needs several types of metadata that you create in the Maintenance apps.

Workflow: Create a tracker program¶

1. Enter the tracker program details.

2. Enter enrollment details.

3. Assign attributes and create section or custom registration form.

4. Create program stages.

5. Configure access, and assign to organisation units.

6. Create program and program stage notification(s).

Create or edit a Tracker program¶

1. Open the Maintenance app and click Program > Program.

2. Click the add button and select Tracker Program in the popup menu.

Enter program details¶

Enter enrollment details¶

Assign tracked entity attributes.¶

1. In the list of Available program tracked entity attributes, double-click the attributes you want to assign to the program.

2. (Opptional) For each assigned attribute, add additional settings:

1. Create registration form

   The registration form defines how the attributes will be displayed to the user in consuming apps, such as Android and Tracker Capture.

   1. Click Create registration form.

   2. Click Section or Custom.

   3. To create a Section form:

      1. Click the add button and enter a section’s name, description and render type for desktop and mobile.
      2. Click the section so it is highlighted by a black border.
      3. Add data elements by clicking the plus sign next to the name of the data elements you wish to add.
      4. Repeat above steps until you have all the sections you need. To change the section order: click the options menu, then drag the section to the place you want.

   4. To create a Custom registration form: Use the WYSIWYG editor to create a completely customized form. If you select Source, you can paste HTML code directly in the editing area. You can also insert images for example flags or logos.

   5. Click add stage.

Create program stages¶

A program consist of program stages. A program stage defines which actions should be taken at each stage.

Note

Changes to a program stage is not saved until you save the program.

1. Click the plus sign to create a program stage.
2. Enter program stage details:
   1. Enter a Name.
   2. (Optional) select a Color and an Icon that will be used by the data capture apps to identify this program stage.
   3. Enter a Description.
   4. Enter the required number of days into the Scheduled days from start field: The first event in this program stage will be scheduled this many days after the enrollment or the incident date, depending on the configuration. If Show incident date in Enrollment details is configured, the system will use incident date as start. If Genereate events based on enrollment date in Program stage details is configured the system will use enrollment date as start.
3. Enter repeatable program stage details.
   1. Specify if the program stage is Repeatable or not.
   2. Select a Period type.
   3. Clear Display generate event box after completed if you don't want to display Create new event box to create new event for a repeatable stage after you click Complete for an event of the stage in data entry form. This field is selected by default.
   4. Enter Standard interval days. This value will be the suggested interval between the last event in a repeatable stage and the scheduled date of the next event.
   5. (Optional) Select a Default next scheduled date. This will show a list of assigned data elements of type date. If an element is selected, the Tracker client will use this as the default scheduled date. The data element can be used by program rules to dynamically schedule intervals between events.
4. Enter form details

1. Assign data elements to program stage:

   1. In the list of Available data elements, double-click the data elements you want to assign to the program stage.

   2. For each assigned data element, review the properties. You can select:

1. Create data entry forms for program stage

   The data entry forms decide how the data elements will be displayed to the user in the Tracker Capture app.

2. Click Create data entry form.

3. Click Basic, Section or Custom.

4. To create a Basic data entry form: Drag and drop the data elements in the order you want.

5. To create a Section data entry form:

   1. Click the add button and enter a section's name, description and render type for desktop and mobile.

   2. Click the section so it's highlighted by a black border.

   3. Add data elements by clicking the plus sign next to the data elements' names.

   4. Repeat above steps until you've all the sections you need.

   5. Change the section order: click the options menu, then drag the section to the place you want.

6. To create a Custom data entry from: Use the WYSIWYG editor to create a completely customized form. If you select Source, you can paste HTML code directly in the editing area. You can also insert images for example flags or logos.

7. Click add stage.

Access¶

Access options decide who can capture data for the program or view/edit the program's metadata. A program can be shared to organisation units, and in addition, the main program and any program stages' access options can be configured through the Sharing dialog. Access options are available in the Access tab.

Assign organization units:

1. In the organisation tree, double-click the organisation units you want to add to the program to.

   You can locate an organisation unit in the tree by expanding the branches (click on the arrow symbol), or by searching for it by name. The selected organisation units display in orange.

Change roles and access:

1. Scroll down to the Roles and access section.

   The first row shows the main program's access options, and each subsequent row shows the options of one program stage. Program stages with a warning icon (exclamation mark) contain access options that deviate from the main program, meaning they are accessed by a different combination of users.

2. Click on either of the rows and the Sharing dialog will show.

3. Modify the access options accordingly. See documentation on the sharing dialog for details.

4. Click the Apply button.

5. Repeat the process for each program/program stage. You can also copy all access options from the main program to your child programs:

   1. Select the program stages you want to have similar access options as the main program by toggling the checkboxes on the right hand side of the program stages. You can also choose to Select all program stages, Deselect all program stages or Select similar stages, in terms of access options, to that of the main program. Similar stages are toggled by default.

   2. Click Apply to selected stages

Create program notifications¶

You can create program notifications for programs with registration and their program stages. The notifications are sent either via the internal DHIS2 messaging system, via e-mail or via text messages (SMS). You can use program notifications to, for example, send an automatic reminder to a tracked entity 10 days before a scheduled appointment. You use the program’s tracked entity attributes (for example first name) and program parameters (for example enrollment date) to create a notification template.

1. Open the Maintenance app and click Program and then notifications.

   A list of existing program notifications for the selected program opens. If the program doesn't have any program notifications, the list is empty.

2. Click on add button and select Program notification.

   

3. Enter a Name.

4. Create the Subject template.

   Double-click the parameters in the Parameters field to add them to your subject.

   Note

   The subject is not included in text messages.

5. Create the Message template.

   Double-click the parameter names in the Parameters field to add them to your message.

   Dear A{w75KJ2mc4zz}, You're now enrolled in V{program_name}.

6. In the When-to-send it field, select what should trigger the notification.

   Trigger	Description	Note
   Program enrollment	The program notification is sent when the TEI enrols in the program.	-
   Program completion	The program notification is sent when the program of TEI is completed	-
   Days scheduled (incident date)	The program notification is sent XX number of days before or after the incident date	You need to enter the number of days before or after the scheduled date that the notification will be send.
   Days scheduled (enrollment date)	The program notification is sent XX number of days before or after the enrollment date	You need to enter the number of days before or after the scheduled date that the notification will be send.
   Program Rule	Notification will be triggered as a result of program rule exeuction.	Program rule with ProgramRuleActionType.SENDMESSAGE need to be in place to make this trigger successful.

7. In the Who-to-send-it field, select who should receive the program notification.

   Recipient type	Description	Note
   Tracked entity instance	Receives program notifications via e-mail or text message.	To receive a program notification, the recipient must have an e-mail address or a phone number attribute.
   Organisation unit contact	Receives program notifications via e-mail or text message.	To receive a program notification, the receiving organisation unit must have a registered contact person with e-mail address and phone number.
   Users at organisation unit:	All users registered to the selected organisation unit receive program notifications via the internal DHIS2 messaging system.	-
   User group	All members of the selected user group receive the program notifications via the internal DHIS2 messaging system	-
   Limit To Hierarchy	Send notification only to those users who belong to any of the organisation unit in the hierarchy.	This option is only available when User Group is selected as recipient.
   Parent OrgUnit Only	Send notification only to those users who belong to parent organisation unit.	This option is only available when User Group is selected as recipient.
   Program Attribute	TrackedEntityAttribute can also be selected as recipient.	This parameter will only be effective if TrackedEntityAttribute value type is PHONE_NUMBER/EMAIL.

8. Click Save.

Create a program stage notification¶

1. Open the Maintenance app and click Program and then notifications.

   A list of existing program stage notifications for the selected program stage opens. If the program stage doesn't have any program stage notifications, the list is empty.

2. Click on add button and select Program stage notification.

3. Click Add new.

4. Enter a Name.

5. Create the Subject template.

   Double-click the parameter names in the Parameters field to add them to your subject.

   Note

   The subject is not included in text messages.

6. Create the Message template.

   Double-click the parameter names in the Parameters field to add them to your message.

   Dear A{w75KJ2mc4zz}, please come to your appointment the V{due_date}.

7. In the When-to-send-it field, select what should trigger the notification.

   Trigger	Description	Note
   Program stage completion	The program stage notification is sent when the program stage is completed	-
   Days scheduled (due date)	The program stage notification is sent XX number of days before or after the due date	You need to enter the number of days before or after the scheduled date that the notification will be send.
   Program Rule	Notification will be triggered as a result of program rule execution.	Program rule with ProgramRuleActionType.SENDMESSAGE need to be in place to make this trigger successful.

   1. Allow notification to be sent multiple times

      This flag can be used if notification is required to be sent multiple times. For example in case of repeatable program stage, same notification will be sent as many times as the stage is repeated.

8. In the Recipients field, select who should receive the program stage notification. You can select:

   Recipient type	Description	Note
   Tracked entity instance	Receives program notifications via e-mail or text message.	To receive a program stage notification, the recipient must have an e-mail address or a phone number attribute.
   Organisation unit contact	Receives program notifications via e-mail or text message.	To receive a program stage notification, the receiving organisation unit must have a registered contact person with e-mail address and phone number. The system selects the same organisation unit as where the event took place.
   Users at organisation unit:	All users registered to the selected organisation unit receive program notifications via the internal DHIS2 messaging system.	-
   User group	All members of the selected user group receive the program notifications via the internal DHIS2 messaging system	-
   Limit To Hierarchy	Send notification only to those users who belong to any of the organisation unit in the hierarchy.	-
   Parent OrgUnit Only	Send notification only to those users who belong to parent organisation unit.	-
   Data Element	Data Element associated with ProgramStage can be selected as recipient.	Data Element will only be effective if DataElement has value type PHONE_NUMBER/EMAIL.
   Tracked Entity Attribute	Tracked Entity Attribute associated with ProgramInstance/Enrollment can be selected as recipient.	Attribute will only be effective if it has value type PHONE_NUMBER/EMAIL.
   Web Hook	Web hooks are automated HTTP messages sent to an external URL configured in web hook URL field. Notificaiton template variables will be sent as key-value pairs in the HTTP request.	-

9. Click Save.

Reference information: Program notification parameters¶

Configure program indicators¶

About program indicators¶

Program indicators are expressions based on data elements and attributes of tracked entities which can be used to calculate values based on a formula. Program indicators consist of an aggregation type, an analytics type, an expression and a filter.

Program indicators are evaluated based on the assigned aggregation type, expression and filter. The order of evaluation is:

1. The filter will filter the events which become part of the evaluation/aggregation routine.

2. The expression will be evaluated per event.

3. All evaluated expression values will be aggregated according to the aggregation type of the program indicator.

In the Maintenance app, you manage the following program indicator objects:

Create or edit a program indicator¶

Note

A program indicator belongs to exactly one program.

1. Open the Maintenance app and click Indicator > Program indicator.

2. Click the add button.

3. Select a Program and enter:

   • Name

   • Short name

   • Code

   • Color

   • Icon

   • Description

   • Select number of Decimals in data output.

4. Select an Aggregation type.

5. Select a if you want to Display in form.

6. Assign one or multiple **Legend**s.

7. (Optional) Enter a Category option combination for aggregate data export.

8. (Optional) Enter an Attribute option combination for aggregate data export.

9. Create the expression.

   1. Click Edit expression.

   2. Create the expression based on mathematical operators and the attributes, variables and constants listed to the right.

10. Create the filter.

    1. Click Edit filter.

    2. Create the expression based on mathematical operators and the attributes, variables and constants listed to the right.

11. Click Save.

Create or edit a program indicator group¶

1. Open the Maintenance app and click Indicator > Program indicator group.

2. Click the add button.

3. Enter Name and Code.

4. In the list of available program indicators, double-click the program indicators you want to assign to your group.

5. Click Save.

Reference information: Expression and filter examples per value type¶

The table below shows examples of how to write expressions and filters for different data element and attribute value types:

Reference information: Functions, variables and operators to use in program indicator expressions and filters¶

An expression that includes both attributes, data elements and constants looks like this:

(A{GPkGfbmArby} + #{mCXR7u4kNBW.NFkjsNiQ9PH}) * C{bCqvfPR02Im}

An expression which uses the custom aggregation type and hence can use inline aggregation types looks like this:

(sum(#{mCXR7u4kNBW.K0A4BauXJDl} * #{mCXR7u4kNBW.NFkjsNiQ9PH}) / sum(#{mCXR7u4kNBW.NFkjsNiQ9PH})) * 100

Note how the "sum" aggregation operator is used inside the expression itself.

Functions to use in a program indicator expression or filter¶

The program indicator expression and filter support a range of functions. The functions can be applied to data elements and attributes:

A filter that uses the "hasValue" function looks like this:

d2:hasValue(#{mCXR7u4kNBW.NFkjsNiQ9PH})

A filter that uses the "relationshipCount(relationshipTypeUid)" function looks like this:

d2:relationshipCount('KLkjshoQ90U')

A filter that uses the "is( x in y, z )" function looks like this:

is(#{oahc9ooVema} in 'New', 'Relapse')

An expression that uses the "zing" and "oizp" functions looks like this:

d2:zing(A{GPkGfbmArby}) + d2:oizp(#{mCXR7u4kNBW.NFkjsNiQ9PH}))

An expression that uses the "daysBetween" function looks like this:

d2:daysBetween(#{mCXR7u4kNBW.k8ja2Aif1Ae},'2015-06-01')

An expression that uses the "yearBetween" function to compare the latest event of the program stage 'mCXR7u4kNBW' to the enrollment date looks like this:

d2:daysBetween(V{enrollment_date},PS_EVENTDATE:mCXR7u4kNBW)

An expression that uses the "condition" function looks like this:

d2:condition('#{mCXR7u4kNBW.NFkjsNiQ9PH} > 100',150,50)

An expression that uses the "countIfValue" function to only count the number of times the value 10 has been collected looks like this:

d2:countIfValue(#{mCXR7u4kNBW.NFkjsNiQ9PH}),10)

An expression that uses the "zpvc" function looks like this:

d2:zpvc(A{GPkGfbmArby}),#{mCXR7u4kNBW.NFkjsNiQ9PH}),4,-1)

An expression that uses the "if" and "isnull" functions looks like this:

if(isNull(A{GPkGfbmArby}),10,20)

An expression that uses the "firstNonNull" function looks like this:

firstNonNull(A{GPkGfbmArby}),#{mCXR7u4kNBW.NFkjsNiQ9PH},44)

An expression that uses the "greatest" function looks like this:

greatest(#{mCXR7u4kNBW.k8ja2Aif1Ae},#{mCXR7u4kNBW.NFkjsNiQ9PH},1)

Variables to use in a program indicator expression or filter¶

The program indicator expression and filter support a range of variables:

A filter that uses the "Analytics period end" variable to only include women who has an LMP that would be in the first trimester:

d2:daysBetween(#{WZbXY0S00lP.w4ky6EkVahL}, V{analytics_period_end}) <= 84

An expression that uses the "value count" variable looks like this:

(#{A03MvHHogjR.a3kGcGDCuk6} + #{A03MvHHogjR.wQLfBvPrXqq}) / V{value_count}

An expression that uses the "event_date" and "incident_date" variables looks like this:

d2:daysBetween(V{incident_date},V{event_date})

Operators to use in a program indicator filter¶

These operators can be used to form logical expressions which ultimately evaluate to either true or false. For example you can assert that multiple data elements must be a specific value, or that specific attributes must have numerical values less or greater than a constant.

A filter that uses both attributes and data elements looks like this:

A{cejWyOfXge6} == 'Female' and #{A03MvHHogjR.a3kGcGDCuk6} <= 2

Tip

DHIS2 is using the JEXL library for evaluating expressions which supports additional syntax beyond what is covered in this documentation. See the reference at the project home page to learn how you can create more sophisticated expressions

Configure program rules¶

About program rules¶

Program rules allows you to create and control dynamic behaviour of the user interface in the Tracker Capture and Event Capture apps. During data entry, the program rules expressions are evaluated each time the user interface is displayed, and each time a data element is changed. Most types of actions will take effect immediately when the user enters values in the Tracker Capture and Event Capture apps.

In the Maintenance app, you manage the following program rule objects:

Workflow¶

1. In the Maintenance app, create program rule variable(s) if needed.

2. In the Maintenance app, create the program rule:

   1. أدخل تفاصيل قاعدة البرنامج.

   2. Create the program rule expression.

   3. Define the program rule actions.

3. In the Tracker Capture or Event Capture apps, verify that the program rule behaves as expected.

Create or edit a program rule variable¶

1. Open the Maintenance app and click Program > Program rule variable.

2. Click the add button.

3. Select a Program and enter a Name.

4. Select if you want to Use code for option set.

   This option is only effective when the data element or tracked entity attribute is connected to an option set. If you don't select this option, the program rule variable will be populated with the option set's name. If you select the option, the program rule variable will be populated with the option set's code instead.

5. Select a Source type and enter the required information.

   Depending on the source type, you'll have to select, for example, a Program stage, Data element or Tracked entity attribute.

   The source types determine how the program rule variable is populated with a value.

   Source type	Description
   Data element from the newest event for a program stage	This source type works the same way as Data element from the newest event in the current program, except that it only evaluates values from one program stage. This source type can be useful in program rules where the same data element is used in several program stages, and a rule needs to evaluate the newest data value from within one specific stage.
   Data element from the newest event in the current program	This source type is used when a program rule variable needs to reflect the newest known value of a data element, regardless of what event the user currently has open. This source type is populated slightly differently in Tracker Capture and Event Capture apps: Tracker Capture: the program rule variable will be populated with the newest data value collected for the given data element within the enrollment. Event Capture: the program rule variable will be populated with the current events data. NB Future dates are "newer" than current or past dates.
   Data element in current event	Program rule variables with this source type will contain the data value from the same event that the user currently has open. This is the most commonly used source type, especially for skip logic (hide actions) and warning/error rules.
   Data element from previous event	Program rule variables with this source type will contain the value from a specified data element from a previous event. Only older events is evaluated, not including the event that the user currently has open. This source type is commonly used when a data element only should be collected once during an enrollment, and should be hidden in subsequent events. Another use case is making rules for validating input where there is an expected progression from one event to the next - a rule can evaluate whether the previous value is higher/lower and give a warning if an unexpected value is entered.
   Calculated value	Program rule variable with this source type is not connected directly to any form data - but will be populated as a result of some other program rules ASSIGN action. This variable will be used for making preliminary calculations, having a ASSIGN program rule action and assigning a value, this value can be used by other program rules - potentially making the expressions simpler and more maintanable. These variables will not be persisted and will stay in memory only during the execution of the set of program rules. Any program rule that assigns a data value to a preliminary calculated value would normally also have a priority assigned - to make sure that the preliminary caculation is done before the rule that consumes the calculated value.
   Tracked entity attribute	Populates the program rule variable with a specified tracked entity attribute for the current enrollment. Use this is the source type to create program rules that evaluate data values entered during registration. This source type is also useful when you create program rules that compare data in events to data entered during registration. This source type is only used for tracker programs (programs with registration).

6. Click Save.

Create or edit a program rule¶

Note

A program rule belongs to exactly one program.

1. Open the Maintenance app and click Program > Program rule.

2. Click the add button.

3. Enter the program rule details. These fields are not shown to the end user, they are only meant for the program administrator.

   • Program

   • Trigger rule only for program stage

     If a program stage is selected, the program rule will only run for the selected program stage, as opposed to being run for every program stage in the program.

   • Name

   • Description

   • Priority

     Let's say you have 16 program rules in your program. You configure the program rules with the following priority settings:

     • Priority 1 for program rule A

     • Priority 2 for program rules B - K

     • No priority for program rules L - P

     Result: the system runs the program rules in the following order:

     1. Program rule A

     2. Program rules B - K (you can't find out or configure in which order the system runs these program rules)

     3. Program rules L - P.

4. Click Enter program rule expression and create the program rule expression with the help of variables, functions and operators.

5. Click Define program rule actions and create the actions executed when the expression is true.

   1. Click the add button, select an Action and enter the required information.

      Depending on the action type, you'll have to perform different types of settings. For some action types, you must also enter free text or create expressions.

      Action type	Required settings	Description
      Assign value	Data element to assign value to Tracked entity attribute to assign value to Program rule variable to assign value to Expression to evaluate and assign	Used to help the user calculate and fill out fields in the data entry form. The idea is that the user shouldn’t have to fill in values that the system can calculate, for example BMI. When a field is assigned a value, the user sees the value but the user can't edit it. NOTE: To assign a value to a tracked entity attribute, the user needs to open the tracked entity profile widget for the rule to trigger. Example from Immunization stock card i Zambia: The data element for vaccine stock outgoing balance is calculated based on the data element for incoming stock balance minus the data elements for consumption and wastage. Advanced use: configure an 'assign value' to do a part of a calculation and then assign the result of the calculation to a program rule variable. This is the purpose with the "Calculated value" program rule variable.
      Display text	Display widget Static text Expression to evaluate and display after static text	Used to display information that is not an error or a warning, for example feedback to the user. You can also use this action to display important information, for example the patient's allergies, to the user.
      Display key/value pair	Display widget Key label Expression to evaluate and display as value	Used to display information that is not an error or a warning. Example: calculate number of weeks and days in a pregnancy and display it in the format the clinician is used to see it in. The calculation is based on previous recorded data.
      Error on complete	Data element to display error next to Tracked entity attribute to display error next to Static text Expression to evaluate and display after static text	Used whenever you've cross-consistencies in the form that must be strictly adhered to. This action prevents the user from continuing until the error is resolved. This action differs from the regular Show error since the error is not shown until the user tries to actually complete the form. If you don't select a data element or a tracked entity attribute to display the error next to, make sure you write a comprehensive error message that helps the user to fix the error.
      Hide field	Data element to hide Tracked entity attribute to hide Custom message for blanked field	Used when you want to hide a field from the user. Custom message for blanked field allows you to define a custom message displayed to the user in case the program rule hides and blanks out the field after the user typed in or selected a value. If a hide field action hides a field that contains a value, the field will always removed. If no message is defined, a standard message will be displayed to alert the user.
      Hide section	Program stage section to hide	Used when you want to hide a section in a program stage from the user.
      Prevent adding new events to stage	Program stage where users will not be able to add new events	Used when you do not want users to add any more events to a program stage. Existing events will not be hidden.
      Make field mandatory	Data element to make mandatory Tracked entity attribute to make mandatory	Used when you want to make a data element or tracked entity attribute mandatory so they have to be filled out before the form can be saved.
      Show error	Data element to display error next to Tracked entity attribute to display error next to Static text Expression to evaluate and display after static text	Used whenever there are rules which must strictly be adhered to. The show error action prevents the user from continuing until the error is resolved. Such a strict validation should only be used when it's certain that the evaluated expression is never true unless the user has made a mistake in data entry. It's mandatory to define a message that is shown to the user when the expression is true and the action is triggered. You can select which data element or tracked entity attribute to link the error to. This will help the user to fix the error. In case several data elements or attributes are involved, select the one that is most likely that the user would need to change.
      Show warning	Data element to display warning next to Tracked entity attribute to display warning next to Static text Expression to evaluate and display after static text	Used to give the user a warning about the entered data, but at the same time to allow the user to save and continue. You can use warnings to help the user avoid errors in the entered data, while at the same time allow the user to consciously disregard the warnings and save a value that is outside preset expectations. Static text defines the message shown to the user when the expression is true and the action is triggered. You can select which data element or tracked entity attribute to link the error to. This will help the user to fix the error. In case several data elements or attributes are involved, select the one that is most likely that the user would need to change.
      Warning on complete	Data element to display warning next to Tracked entity attribute to display warning next to Static text Expression to evaluate and display after static text	Used to give the user a warning if he/she tries to complete inconsistent data, but at the same time to allow the user to continue. The warning is shown in a dialog when the user completes the form. Static text defines the message shown to the user when the expression is true and the action is triggered. This field is mandatory. You can select which data element or tracked entity attribute to link the error to. This will help the user to fix the error. If you don't select a data element or a tracked entity attribute to display the error next to, make sure you write a comprehensive error message that helps the user to fix the error.
      Send Message	Message template to send	Send Message triggers a notification based on provided message template. This action will be taken immediately. The message template will be parsed and variables will be substituted with actual values.
      Schedule Message	Message template to send Data field which contains expression to evaluate the date which notification should be sent at. If this expression results in any value other than Date, then resultant will be discarded and notification will not get scheduled.	Schedule Message will schedule notification at date provided by Expression in the data field. Sample expression is given below d2:addDays( '2018-04-20', '2' ) Message template will be parsed and variables will be substituted with actual values.
      Hide option	Data element to hide option for Tracked entity attribute to hide option for Option that should be hidden	Used to selectively hide a single option for an option set in a given data element/tracked entity attribute. When combined with show option group the hide option takes presedence.
      Hide option group	Data element to hide option group for Tracked entity attribute to hide option group for Option group that should be hidden	Used to hide all options in a given option group and data element/tracked entity attribute. When combined with show option group the hide option group takes precedence.
      Show option group	Data element to show option group for Tracked entity attribute to show option group for Option group that should be shown	Used to show only options from a given option group in a given data element/tracked entity attribute. To show an option group implicitly hides all options that is not part of the group(s) that is shown.

   2. Click Save.

   3. (Optional) Repeat above steps to add more actions.

6. Click Save.

Example: Program rules¶

Note

You can view all examples on the demo server: https://play.dhis2.org/dev/dhis-web-maintenance/#/list/programSection/programRule

This example shows how to configure a program rule which calculate number of weeks and days in a pregnancy and display the result in the format the clinician is used to see it in. The calculation is based on previous recorded data.

1. 

2. 

3. 

   The full expression in the Data field:

   d2:concatenate(d2:weeksBetween(#{lmp}, V{current_date}), '+',
   d2:modulus(d2:daysBetween(#{lmp}, V{current_date}), 7))
   

This example shows how to configure a program rule to display text in the Feedback widget in the Tracker Capture app.

This example shows how to configure a program rule to always display certain data in the Feedback widget in the Tracker Capture app. This is useful when you want to make sure that vital data, for example medicine allergies, is always visible.

By using a program rule of type "Assign value" you can calculate the "Gestational age at visit" value and fill it in the data entry form. You configure the program rule to calculate "Gestational age at visit" based on either "LMP date" or "Ultrasound estimated due date".

Reference information: Operators and functions to use in program rule expression¶

Tip

You can nest functions within each other and with sub-expressions to form more complex conditions. An example that produces the gestational age in weeks, based on last menstrual date:

d2:floor( d2:daysBetween(#{lastMenstrualDate},V{event_date}) / 7 )

Tip

The source type will determine how the d2: function calls will evaluate a (sourcefield) parameter.

Example: where #{hemoglobinCurrent} is set to source type Data element in current event. The following function call with evaluate whether haemoglobin is entered in the current event.

d2:hasValue( 'hemoglobinCurrent' )

Example: where #{hemoglobin} is set to source type Data element from the newest event in the current program. The following function call with evaluate whether there exists a value for the haemoglobin in any event in the enrollment.

d2:hasValue( 'hemoglobin' )

Example: where #{hemoglobinPrevious} is set to source type Data element from previous event . The following function call with evaluate whether there exists a value for the haemoglobin among the events preceding the current event.

d2:hasValue( 'hemoglobinPrevious' )

Configure relationship types¶

About relationship types¶

A relationship represents a link between two entities in the Tracker-model. A relationship is considered data in DHIS2 and is based on a Relationship Type, similar to how a Tracked Entity Instance is based on a Tracked Entity Type.

Relationships always include two entities, and these entities can include Tracked Entity Instances, Enrollments and Events, and any combination of these. Note that not all of these combinations are available in the current apps.

In addition, relationships can be defined as unidirectional or bidirectional. The only functional difference is currently that these requires different levels of access to create. Unidirectional relationships requires the user to have data write access to the “from” entity and data read access for the “to” entity, while bidirectional relationships require data write access for both sides.

For more information about configuration and the meaning of 'From constraint' and 'To constraint', see Relationship model.

Create or edit a relationship type¶

1. Open the Maintenance app and click Program > Relationship type.

2. Click the add button.

3. Type a Name of the relationship type.

4. (Optional) Assign a Code.

5. (Optional) Provide a Description of the relationship.

6. (Optional) Select whether the relationship should be bidirectional

7. Provide Relationship name seen from inititating entity. This is the name of the relationship that will be shown in the Data Entry app at the 'left' side of the relationship. E.g. in a Mother-child relationship this could be 'Mother of'.

8. (Optional) Provide Relationship name seen from receiving entity. This is the name of the relationship that will be shown at the 'right' side of the relationship in the Data Entry app. E.g. in a Mother-child relationship this could be 'Mother'.

9. Select a 'From constraint'. This limits what kind of entities can be included in the relationship. Relationship model. After selecting a 'From constraint', you have the option to choose which attributes or data elements should be shown in the relationship widget in Tracker Capture and Capture for the "From constraint". The list will vary based on the constraint:

   • When selecting “Tracked Entity Instance”, then a Tracked Entity Type only, choose between the configured Tracked Entity Type Attributes
   • When selecting “Tracked Entity Instance”, then a Tracked Entity Type and a Program, choose between the the attributes that have been configured for both the Tracked Entity Type and for the Program
   • When selecting “Enrollment in program”, choose between the attributes that have been configured for the Program
   • When selecting “Event in program or program stage”, choose between the data elements that have been configured for that Event program or Program stage

10. Select a 'To constraint'. This limits what kind of entities that can be included in the relationship. Relationship model. Repeat the selection of attributes or data elements that should be shown in the relationship widget for the "To constraint".

11. Click Save.

Configure tracked entity types¶

About tracked entity types¶

A tracked entity is a types of entities which can be tracked through the system. It can be anything from persons to commodities, for example a medicine or a person.

A program must have one tracked entity. To enroll a tracked entity instance into a program, the tracked entity type and tracked entity type of a program must be the same.

Tracked entity attributes are used to register extra information for a tracked entity. Tracked entity attributes can be shared between programs.

Create or edit a tracked entity attribute¶

1. Open the Maintenance app and click Program > Tracked entity attribute.

2. Click the add button.

3. In the Name field, type the tracked entity attribute name.

4. (Optional) Type a Short name.

5. (Optional) Type a Form name.

6. (Optional) In the Code field, assign a code.

7. (Optional) Type a Description.

8. (Optional) In the Field mask field, you may type a template that's used to provide hints for correct formatting of the attribute. NOTE: So far only implemented in the DHIS2 Android Capture app, not in the Capture and Tracker Capture web apps. The following are special characters that can be used in the mask. The special characters match exactly one character of the given type.

For example, the pattern can be used to show hyphens as needed in the input field of the data element. E.g "\d\d\d-\d\d\d-\d\d\d, would show an hyphen for every third digit.

1. Select an Option set.

2. In the Value type field, select the type of data that the tracked entity attribute will record.

   Value types

   Value type	Description
   Age	-
   Coordinate	A point coordinate specified as longitude and latitude in decimal degrees. All coordinate should be specified in the format "-19.23 , 56.42" with a comma separating the longitude and latitude.
   Date	Dates render as calendar widget in data entry.
   Date & time	-
   E-mail	-
   File	A file resource where you can store external files, for example documents and photos.
   Image	Similar to File, but restricted to images.
   Integer	Any whole number (positive and negative), including zero.
   Letter	-
   Long text	Textual value. Renders as text area in forms.
   Negative integer	Any whole number less than (but not including) zero.
   Number	Any real numeric value with a single decimal point. Thousands separators and scientific notation is not supported.
   Percentage	Whole numbers inclusive between 0 and 100.
   Phone number
   Positive integer	Any whole number greater than (but not including) zero.
   Positive of zero integer	Any positive whole number, including zero.
   Organisation unit	-
   Unit interval	Any real number greater than or equal to 0 and less than or equal to 1.
   Text	Textual value. The maximum number of allowed characters per value is 50,000.
   Time	Time is stored in HH:mm format. HH is a number between 0 and 23 mm is a number between 00 and 59
   Tracker associate	-
   Username	Rendered as a dialog with a list of users and a search field. The user will need the "View User" authority to be able to utilise this data type
   Yes/No	Boolean values, renders as drop-down lists in data entry.
   Yes only	True values, renders as check-boxes in data entry.

3. Select an Aggregation type.

   Aggregation operators

   Aggregation operator	Description
   Average	Average the values in both the period as and the organisation unit dimensions.
   Average (sum in organisation unit hierarchy)	Average of data values in the period dimension, sum in the organisation unit dimensions.
   Count	Count of data values.
   Min	Minimum of data values.
   Max	Maximum of data values.
   None	No aggregation is performed in any dimension.
   Sum	Sum of data values in the period and organisation unit dimension.
   Standard deviation	Standard deviation (population-based) of data values.
   Variance	Variance (population-based) of data values.

4. Select Unique to specify that the values of the tracked entity attribute is unique.

   There are two options for the unique setting:

   • Entire system: The values of the tracked entity attribute can duplicate with values which belong to other tracked entity attributes. But the values in this tracked entity attribute must not duplicate.

     Select Automatically generated to allow automatic generation of the tracked entity attribute value. When the generate setting is selected on, an optional field for specifying pattern also displays. This field should contain a pattern based on the TextPattern syntax. When the value is automatically generated, it will be unique for this attribute for the entire system. See the TextPattern section for more information on how it works.

   • Organisation unit: The values of the tracked entity attribute must not duplicate in the same organisation unit.

5. Select Inherit to registry a new entity for relationship with an available entity, all inherit entity attribute values of the entity will be pre-filled in the registration form.

6. (Optional) Select Confidential.

   This option is only available if you have configured encryption for the system.

7. (Optional) Select Display in list without program.

8. (Optional) Assign one or multiple Legends.

9. Click Save.

Create or edit a tracked entity type¶

1. Open the Maintenance app and click Program > Tracked entity type.

2. Click the add button or an already existing tracked entity type.

3. Type a Name of the tracked entity.

4. (Optional) select a Color and an Icon that will be used by the data capture apps to identify this tracked entity type.

5. (Optional) Enter a Description of the tracked entity.

6. (Optional) Enter a Minimum number of attributes required to search. This specifies the amount of attributes that need to be filled out in order to be able to search for this tracked entity type in a global search. See Configure Search for more information.

7. (Optional) Enter a Maximum number of tracked entity instances to return in search. This specifies the amount of tracked entity instances that will be returned in a global search. See Configure Search for more information.

8. (Optional) Add Tracked entity type attributes. This is used to configure search, see Configure Search for more information.

9. (Optional) Enter an Alternative name of the tracked entity.

10. Click Save.

Configure search¶

Users can be given search organisation units, which makes it possible to search for tracked entity instances outside their data capture organisation units.

Searching can be done either in the context of a program, or in the context of a tracked entity type. To be give users the option of searching in the context of a program, it is necessary to configure which of the programs tracked entity attributes is searchable. To give users the option of searching in the context of a tracked entity type, you will have to configure which of the tracked entity type attributes is searchable.

Configure search for tracker program¶

To be able to search with a program, you will have to make some of the program attributes searchable. Unique program attributes will always be searchable.

1. Open Maintenance app and click Program

2. Open or create a Tracker program

3. Go to Attributes

4. If you have no attributes, add one

5. Set the attribute searchable

Searchable program attributes will assigned to a search group.

• Unique group. One group per unique program attribute. Unique attributes cannot be combined with other program attributes in a search. The result from the search can only be 0 or 1 tracked entity instance.

• Non-unique group. This group contains all non-unique program attributes and makes it possible to combine multiple attributes in a search.

There are two limits that can be set for a program search, as part of the Program details configuration.

• Minimum number of attributes required to search: This property defines how many of the non-unique attributes that must be entered before a search can be performed.

• Maximum number of tracked entity instances to return: This property defines how specific a search must be, by limiting the number of matching tracked entity instances a user is allowed to get for her search criteria. If the number of matching records is larger than this maximum, they will not be returned. The user must provide more specific search criteria, in order to reduce the number of matching records, before they are returned.

  NOTE

  This maximum is only applied to search results outside the users capture org unit. Within the capture scope, the user can see any number of results.

Configure search for tracked entity type¶

Note

TET = Tracked entity type

To be able to search without a program, you will have to make some of the TET attributes searchable. Unique TET attributes will always be searchable.

1. Open Tracked entity type app

2. Open a Tracked entity type

3. If the TET has no attributes, add one

4. Set the attribute searchable

Searchable TET attributes will assigned to a search group.

• Unique group. One group per unique TET attribute. Unique attributes cannot be combined with other TET attributes in a search. The result from the search can only be 0 or 1 tracked entity instance.

• Non-unique group. This group contains all non-unique TET attributes and makes it possible to combine multiple attributes in a search.

There are two limits that can be set for a TET search

• Minimum number of attributes required to search: This property defines how many of the non-unique attributes that must be entered before a search can be performed.

• Maximum number of tracked entity types to return: This property defines how specific a search must be, by limiting the number of matching tracked entity types a user is allowed to get for her search criteria. If the number of matching records is larger than this maximum, they will not be returned. The user must provide more specific search criteria, in order to reduce the number of matching records, before they are returned.

  NOTE

  This maximum is only applied to search results outside the users capture org unit. Within the capture scope, the user can see any number of results.

Configure search organisation units for a user¶

To be able to search in other organisation units than the users data capture organisation units, the user must be assigned with search organisation units. Giving a user a search organisation unit will also give it access to search in all children of that organisation unit.

1. Open Users app

2. Click on a user

3. Open Assign search organisation units

4. Select organisation units

5. Click Save

Clone metadata objects¶

Cloning a data element or other objects can save time when you create many similar objects.

1. Open the Maintenance app and find the type of metadata object you want to clone.

2. In the object list, click the options menu and select Clone.

3. Modify the options you want.

4. Click Save.

Delete metadata objects¶

Note

You can only delete a data element and other data element objects if no data is associated to the data element itself.

Warning

Any data set that you delete from the system is irrevocably lost. All data entry forms, and section forms which may have been developed will also be removed. Make sure that you have made a backup of your database before deleting any data set in case you need to restore it at some point in time.

1. Open the Maintenance app and find the type of metadata object you want to delete.

2. In the object list, click the options menu and select Delete.

3. Click Confirm.

Change sharing settings for metadata objects¶

You can assign different sharing settings to metadata objects, for example organisation units and tracked entity attributes. These sharing settings control which users and users groups that can view or edit a metadata object.

Some metadata objects also allows you to change the sharing setting of data entry for the object. These additional settings control who can view or enter data in form fields using the metadata.

Note

The default setting is that everyone (Public access) can find, view and edit metadata objects.

1. Open the Maintenance app and find the type of metadata object you want to modify.

2. In the object list, click the context menu and select Sharing settings.

3. (Optional) Add users or user groups: search for a user or a user group and select it. The user or user group is added to the list.

4. Change sharing settings for the access groups you want to modify.

   • Can edit and view: The access group can view and edit the object.

   • Can view only: The access group can view the object.

   • No access (only applicable to Public access): The public won't have access to the object.

5. Change data sharing settings for the access groups you want to modify.

   • Can capture data: The access group can view and capture data for the object.

   • Can view data: The access group can view data for the object.

   • No access: The access group won't have access to data for the object.

6. Click Close.

Display details of metadata objects¶

1. Open the Maintenance app and find the type of metadata object you want to view.

2. In the object list, click the options menu and select Show details.

Translate metadata objects¶

DHIS2 provides functionality for translations of database content, for example data elements, data element groups, indicators, indicator groups or organisation units. You can translate these elements to any number of locales. A locale represents a specific geographical, political, or cultural region.

Tip

To activate a translation, open the System Settings app, click > Appearance and select a language.

1. Open the Maintenance app and find the type of metadata object you want to translate.

2. In the object list, click the options menu and select Translate.

   Tip

   If you want to translate an organisation unit level, click directly on the Translate icon next to each list item.

3. Select a locale.

4. Type a Name, Short name and Description.

5. Click Save.