1.25 Program rules

This section is about sending and reading program rules, and explains the program rules data model. The program rules gives functionality to configure dynamic behavior in the programs in DHIS.

1.25.1 Program rule model

The program rules data model consists of programRuleVariables, programRules and programRuleActions. The programRule contains an expression - when this expression is true, the child programRuleActions is triggered. The programRuleVariables is used to address data elements, tracked entity data values and other data values needed to run the expressions. All programRules in a program share the same library of programRuleVariables, and one programRuleVariable can be used in several programRules’ expressions.

1.25.1.1 Program rule model details

The following table gives a detailed overview over the programRule model.

programRule
name description Compulsory
program The program of which the programRule is executed in. Compulsory
name The name with which the program rule will be displayed to dhis configurators. Not visisble to the end user of the program. Compulsory
description The description of the program rule, can be used by configurators to describe the rule. Not visisble to the end user of the program. Compulsory
programStage If a programStage is set for a program rule, the rule will only be evaluated inside the specified program stage. optional
condition The expression that needs to be evaluated to true in order for the program rule to trigger its child actions. The expression is written using operators, function calls, hard coded values, constants and program rule variables.
d2:hasValue('hemoglobin') && #{hemoglobin} <= 7
Compulsory
priority The priority to run the rule in cases where the order of the rules matters. In most cases the rules does not depend on being run before or after other rules, and in these cases the priority can be omitted. If no priority is set, the rule will be run after any rules that has a priority defined. If a priority(integer) is set, the rule with the lowest priority will be run before rules with higher priority. optional

1.25.1.2 Program rule action model details

The following table gives a detailed overview over the programRuleAction model.

programRuleAction
name description Compulsory
programRule The programRule that is the parent of this action. Compulsory
programRule- ActionType The type of action that is to be performed.
  • DISPLAYTEXT - Displays a text in a given widget.

  • DISPLAYKEYVALUEPAIR - Displays a key and value pair(like a program indicator) in a given widget.

  • HIDEFIELD - Hide a specified dataElement or trackedEntityAttribute.

    • content - if defined, the text in content will be displayed to the end user in the instance where a value is previously entered into a field that is now about to be hidden (and therefore blanked). If content is not defined, a standard message will be shown to the user in this instance.

    • dataElement - if defined*, the HIDEFIELD action will hide this dataElement when the rule is effective.

    • trackedEntityDataValue - if defined*, the HIDEFIELD action will hide this trackedEntityDataValue when the rule is effective.

  • HIDESECTION - Hide a specified section.

    • programStageSection - must be defined. This is the programStageSection that will be hidden in case the parent rule is effective.

  • ASSIGN - Assign a dataElement a value(help the user calculate something or fill in an obvious value somewhere)

    • content - if defined*, the value in data is assigned to this variable. If content id defined, and thus a variable is assigned for use in other rules, it is important to also assign a programRule.priority to make sure the rule with an ASSIGN action runs before the rule that will in turn evaluate the assigned variable.

    • data - must be defined, data forms an expression that is evaluated and assigned to either a variable(#{myVariable}), a dataElement, or both.

    • dataElement - if defined*, the value in data is assigned to this data element.

    • Either the content or dataElement must be defined for the ASSIGN action to be effective.

    • SHOWWARNING - Show a warning to the user, not blocking the user from completing the event or registration.

      • content - if defined, content is a static part that is displayed at the end of the error message.

      • data - if defined, data forms an expression that is evaluated and added to the end of the warning message.

      • dataElement - if defined*, the warning message is displayed next to this data element.

      • trackedEntityAttribute - if defined*, the warning message is displayed next to this tracked entity attribute.

      *Either dataElement or trackedEntityAttribute must be specified.

    • SHOWERROR - Show an error to the user, blocking the user from completing the event or registration.

      • content - if defined, content is a static part that is displayed in the start of the error message.

      • data - if defined, data forms an expression that is evaluated and added to the end of the error message.

      • dataElement - if defined*, the error message is linked to this data element.

      • trackedEntityAttribute - if defined*, the error message is linked to this tracked entity attribute.

      *Either dataElement or trackedEntityAttribute must be specified.

    • WARNINGONCOMPLETINON - Show a warning to the user on the “Complete form” dialog, but allowing the user to complete the event.

      • content - if defined, content is a static part that is displayed at the end of the error message.

      • data - if defined, data forms an expression that is evaluated and added to the end of the warning message.

      • dataElement - if defined, the warning message prefixed with the name/formName of the data element.

    • ERRORONCOMPLETION - Show an error to the user on in a modal window when the user tries to complete the event. The user is prevented from completing the event.

      • content - if defined, content is a static part that is displayed in the start of the error message.

      • data - if defined, data forms an expression that is evaluated and added to the end of the error message.

      • dataElement - if defined, the error message is linked to this data element.

    • CREATEEVENT - Create an event within the same enrollment.

      • content

      • data - if defined, contains data values to assign the created event. The format is <uid>:<data value>. Where several values is specified, these are separated with comma.

        AcMrnleqHqc:100,AqK1IHqCkEE:'Polyhydramnios'
      • programStage - must be defined, and designates the program stage that the rule shall create an event of.

    • SETMANDATORYFIELD - Set a field to be mandatory.

      • dataElement - if defined, this data element will be set to be mandatory in the data entry form.

      • trackedEntityAttribute - if defined, this tracked entity attribute will be set to mandatory in the registration form or profile.

    • SENDMESSAGE - Send message at completion of event/enrollment

      • messageTemplate - if defined, this template will be delivered either as SMS or EMAIL depending upon DeliveryChannel value in message template.

Compulsory
location Used for actionType DISPLAYKEYVALUEPAIR and DISPLAYTEXT to designate which widget to display the text or keyvalyepair in. Compulsory for DISPLAYKEYVALUEPAIR and DISPLAYTEXT. See description
content Used for user messages in the different actions. See the actionType overview for a detailed explanation for how it is used in each of the action types. Compulsory for SHOWWARNING, SHOWERROR, WARNINGONCOMPLETION, ERRORONCOMPLETION, DISPLAYTEXT and DISPLAYKEYVALUEPAIR. Optional for HIDEFIELD and ASSIGN. See description
data Used for expressions in the different actions. See the actionType overview for a detailed explanation for how it is used in each of the action types. Compulsory for ASSIGN. Optional for SHOWWARNING, SHOWERROR, WARNINGONCOMPLETION, ERRORONCOMPLETION, DISPLAYTEXT, CREATEEVENT and DISPLAYKEYVALUEPAIR See description
dataElement Used for linking rule actions to dataElements. See the actionType overview for a detailed explanation for how it is used in each of the action types. Optional for SHOWWARNING, SHOWERROR, WARNINGONCOMPLETION, ERRORONCOMPLETION, ASSIGN and HIDEFIELD See description
trackedEntity- Attribute Used for linking rule actions to trackedEntityAttributes. See the actionType overview for a detailed explanation for how it is used in each of the action types. Optional for SHOWWARNING, SHOWERROR and HIDEFIELD. See description
programStage Only used for CREATEEVENT rule actions. Compulsory for CREATEEEVENT. See description
programStage- Section Only used for HIDESECTION rule actions. Compulsory for HIDESECTION See description

1.25.1.3 Program rule variable model details

The following table gives a detailed overview over the programRuleVariable model.

programRuleVariable
name description Compulsory
name the name for the programRuleVariable - this name is used in expressions.
#{myVariable} > 5
Compulsory
sourceType Defines how this variable is populated with data from the enrollment and events.
  • DATAELEMENT_NEWEST_EVENT_PROGRAM_STAGE - In tracker capture, gets the newest value that exists for a dataelement, within the events of a given program stage in the current enrollment. In event capture, gets the newest value among the 10 newest events on the organisation unit.

  • DATAELEMENT_NEWEST_EVENT_PROGRAM - In tracker capture, get the newest value that exists for a dataelement across the whole enrollment. In event capture, gets the newest value among the 10 newest events on the organisation unit.

  • DATAELEMENT_CURRENT_EVENT - Gets the value of the given dataelement in the current event only.

  • DATAELEMENT_PREVIOUS_EVENT - In tracker capture, gets the newest value that exists among events in the program that precedes the current event. In event capture, gets the newvest value among the 10 preceeding events registered on the organisation unit.

  • CALCULATED_VALUE - Used to reserve a variable name that will be assigned by a ASSIGN program rule action

  • TEI_ATTRIBUTE - Gets the value of a given tracked entity attribute

Compulsory
dataElement Used for linking the programRuleVariable to a dataElement. Compulsory for all sourceTypes that starts with DATAELEMENT_. See description
trackedEntity- Attribute Used for linking the programRuleVariable to a trackedEntityAttribute. Compulsory for sourceType TEI_ATTRIBUTE. See description
useCodeFor- OptionSet If checked, the variable will be populated with the code - not the name - from any linked option set. Default is unchecked, meaning that the name of the option is populated.
programStage Used for specifying a specific program stage to retreive the programRuleVariable value from. Compulsory for DATAELEMENT_NEWEST_EVENT_PROGRAM_STAGE. See description

1.25.2 Creating program rules

-coming-