23.4 Manage data sets and data entry forms

23.4.1 About data sets and data entry forms

All data entry in DHIS2 is organised in data sets. A data set is a collection of data elements grouped together for data entry and data export between instances of DHIS2. To use a data set to collect data for a specific organisation unit, you must assign the organisation unit to the data set. Once you have assigned the data set to an organisation unit, that data set is available in the Data entry app. Only the organisation units that you have assigned the data set to can use the data set for data entry.

A category combination can link to both data elements and data sets. If you use a category combination for a data set, the category combinations is applicable for the whole form. This means that you can use categories to capture information which is common to an entire form, for example the name of the a project or grant. When a data set is linked to a category combination, those categories will be displayed as drop-down boxes in the Data entry app. Data captured in the form will then be linked to the selected category options from those drop-down boxes. For information about how to create categories and category combinations, see section “Manage data elements and categories”. Make sure that you set the type of categories and category combinations to “Attribute”.

An scenario for when categories are useful is when you need to capture a data entry form for a implementing partner organisation and a project. In that case:

  1. Create category options and categories for all partner organisations and projects and link them in a new category combination.

  2. Assign the category combination to the data set (form) for which you need to capture this information.

    When opening this data set in data entry module, the partner organisation and project categories will automatically be rendered as drop-down boxes, allowing you to select a specific implementing partner organisation and project before continuing to do data entry.

You create and edit data sets in the Maintenance app. Here you define, for example, which data elements you want to include in the data set and the data collection frequency.

You enter data in the Data entry app. The Data entry app uses data entry forms to display the data sets. There are three types of data entry forms:

Data entry form types
Data entry form type Description

Default form

Once you have assigned a data set to an organisation unit, a default form is created automatically. The default form is then available in the Data entry app for the organisation units you have assigned it to.

A default form consist of a list of the data elements belonging to the data set together with a column for inputting the values. If your data set contains data elements with a non-default category combination, for example age groups or gender, additional columns are automatically created in the default form based on the different categories.

If you use more than one category combination you get multiple columns in the default form with different column headings for the options.

Section form

If the default form doesn’t meet your needs, you can modify it to create a section form. Section forms give you more flexibility when it comes to using tabular forms.

In a section form you can, for example, create multiple tables with subheadings and disable (grey out) cells in a table.

When you have added a section form to a data set, the section form is available in the Data entry app.

Custom form

If the form you want to design is too complicated for default or section forms, you can create a custom form. A custom form takes more time to create than a section form, but you have full control over the design.

You can, for example, mimic an existing paper aggregation form with a custom form. This makes data entry easier, and should reduce the number incorrectly entered data elements.

When you have added a custom form to a data set, the custom form is available in the Data entry app.

Note

If a data set has both a section form and a custom form, the system displays the custom form during data entry. Users who enter data can’t select which form they want to use. In web-based data entry the order of display preference is:

  1. Custom form (if it exists)

  2. Section form (if it exists)

  3. Default form

Mobile devices do not support custom forms. In mobile-based data entry the order of display preference is:

  1. Section form (if it exists)

  2. Default form

In the Maintenance app, you manage the following data set objects:

Data set objects in the Maintenance app

Object type

Available functions

Data set

Create, assign to organisation units, edit, share, delete, show details and translate

Edit compulsory data elements

Add and remove multiple data sets to organisation units at once

Section form

Create, edit and manage grey fields

Section

Change display order, delete and translate

Custom form

Create, edit and script

23.4.2 Workflow

You need to have data elements and categories to create data sets and data entry forms.

  1. Create a data set.

  2. Assign the data set to organisation units.

    A default form is created automatically.

  3. Create a section form or a custom form.

    Now you can register data in the Data entry app.

23.4.3 Create or edit a data set

  1. Open the Maintenance app and click Data set > Data set .

  2. Click the add button.

  3. In the Name field, type the precise name of the data set.

  4. In the Short name field, define a short name for the data set.

    Typically, the short name is an abbreviation of the full data set name. This attribute is often used to display the name of the data set where space is limited.

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

  6. In the Description field, type a description of the data set.

  7. Enter the number of Expiry days .

    The number of expiry days controls for how long it should be possible to enter data in the Data entry app for this data set. Expiry days refer to the number of days after the end date of the selected data entry period where the data entry form should be open for entry. After the number of days has expired, the data set will be locked for further entry.

    You can set manual exceptions to this using the lock exception functionality in the Data Administration app.

    Note

    To allow data entry into all possible historical time periods, set the number of expiry days to zero.

  8. If you want it to be possible to enter data for future periods, type the number of periods in the Open future periods for data entry field.

    The value is the number of future periods which are available for data entry.

    For a monthly data set a value of 2 allows you to enter data for 2 months in advance. This is useful for, by example, population, target and planning data.

  9. In the Days after period to qualify for timely submission field, type the number of days in which data can be entered to be considered reported on time.

    To verify the number of timely reports submitted, go to Reports > Reporting rate summary .

  10. Select a Period type .

    The period type defines the frequency of reporting for the particular data set. The frequency can for example be daily, quarterly or yearly.

  11. Select a Category combination to assign it to the data set.

    Tip

    Click Add new to create category combinations that you’re missing. In the form that opens, create the category combinations you need. When you’re done, click Refresh values .

  12. In the Complete notification recipients list, select a user group that should receive a message when the data set is marked as complete in the Data Entry app.

    The message is delivered through the DHIS2 messaging system.

  13. If you want the user who entered the data to receive a message when the data set is marked as complete in the Data entry app, select Send notification to completing user .

    The message is delivered through the DHIS2 messaging system.

  14. If applicable, select, a Data approval workflow .

  15. If you want it to be possible to use the data set within the Java mobile DHIS2 application, select Enable for Java mobile client .

  16. If you want it to be mandatory to fill all values for a data element in data entry if one or more values have been filled, select All fields for data elements required .

    This means that if you enter one data value for a data element in an entry field (that is for a category option combination), then you must enter data for all fields belonging to that data element (that is all category option combinations).

  17. If you want it to be possible to mark a data entry form as complete only if the validation of that form is successful, select Complete allowed only if validation passes .

    If you select this option, you can’t mark the form as complete if validation fails.

  18. If you want it to be mandatory that any missing values require a comment to justify their absence, select Missing values requires comment on complete .

  19. (Optional) Assign one or multiple Legends .

  20. If applicable, select Skip offline .

    This option controls whether this data entry form should be downloaded and saved in the user’s web browser. Normally you shouldn’t select Skip offline . This is the default setting. If you have big forms which are rarely used you can consider selecting this option to speed up initial loading in the data entry module.

  21. If applicable, select Data element decoration

    If you select this option, descriptions of data elements render in call-outs in downloaded data sets in offline mode in the Data entry app.

  22. If applicable, select Render sections as tabs .

    This option is only applicable for section forms. The option allows you to render each section as a tab horizontally above the data set. This is useful for long data sets as it allows appropriate sections to be selected quickly without going through the entire form.

  23. If applicable, select Render vertically .

    This option is only applicable for section forms.

  24. Select data elements and assign them.

    You can override the category combination for each selected data set by clicking on the gear icon above the list of selected data elements. This allows you to utilize a specific category combination (disaggregation) within the current data set instead of the category combination associated directly with the data element itself.

  25. Select indicators and assign them.

  26. In the organisation unit tree, select the organisation units you want to assign the data set to.

    Tip

    • Click Organisation unit level to select all organisation units that belong to a certain organisation level.

    • Click Organisation unit group to select all organisation units that belong to a certain organisation unit group.

  27. Click Save .

You can now use the data set in the Data Entry app for the organisation units that you have assigned to and for periods according to the selected frequency (period type).

23.4.4 Create or edit Data set Notification

  1. Open the Maintenance app and click Data set > Data set notification .

  2. Click the add button.

23.4.4.1 What to send?

  1. In the Name field, type the precise name of the data set notification.

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

  3. Enter Data sets .

    These data sets will be associated to this notification. In case any of them is completed for a certain period and organisation unit, notification will be generated by the system.

    Note

    Nothing will happen if no data set is selected

  4. In Message template section there are two parameters.

    • Subject template subject of the notification sent in notification. It can have values from the list of variables available on the right side.

    • Message template actual message sent in notification. It can have values from the list of variables available on the right side.

    Note

    Subject is only relevant in case of Email and internal DHIS2 messages. It is ignored in case of SMS.

23.4.4.2 When to send?

  1. Data set notification trigger field determine when to send notification.

    • Data Set Completion will trigger notification as soon as data set is completed.

    • Schedule Days will schedule notification based on number days relative to scheduled date. Schedule date will be decided by Period associated with Data set.

      • Send notification as provides two different types of notifications

        • Collective summary send notification in summary mood

        • Single notification sends notification in single mood

    Note

    Send notification as option is only available in case of scheduled notification. This option is set to default which is Single notification in case of completion notification

23.4.4.3 Who to send?

  1. Notification recipient field determine recipients of the notification.

    • Organisation Unit contact will send notification to contact assigned to organisation unit which the data has been collected from.

    • UserGroup will send notification to all the member of the selected UserGroup.

    Note

    An internal DHIS2 message will be sent in case if recipient is UserGroup. Moreover user will also receive SMS/EMAIL if phone number and email address exist for that user and SMS/EMAIL notifications are enabled in SystemSettings

23.4.5 Override data elements’ category combinations in a data set

You can override which category combination to use for a data element within the context of a data set. This means that a data element can use different category combinations within different data sets. This is useful when you want to reuse a data element since you don’t have to replicate the data element to allow multiple category combinations.

If different regions within your organisation unit hierarchy use different disaggregations, or if the disaggregations change over time, you can represent this by creating different data sets with the appropriate category combinations.

  1. Open the Maintenance app and click Data set > Data set .

  2. In the list, find the data set you want to modify.

  3. Click the options menu and select Edit .

  4. Go to the data elements section and click the spanner icon.

  5. Select new category combinations and click Close .

  6. Click Save .

23.4.6 Edit compulsory data elements in a data set

You can add or remove data elements which will be marked as compulsory during data entry.

  1. Open the Maintenance app and click Data set > Data set .

  2. In the list, find the data set you want to edit.

  3. Click the options menu and select Edit compulsory data elements .

  4. Assign the compulsory data elements.

  5. Click Save .

23.4.7 Download default data forms in PDF format

You can download a default data from in PDF format for offline data entry.

  1. Open the Maintenance app and click Data set > Data set .

  2. In the list, find the object you want to download.

  3. Click the options menu and select Get PDF for data entry .

23.4.8 Manage section forms

23.4.8.1 Create a section form

Section forms are separated automatically by data element category combinations, which produce a spreadsheet like data entry form for each section.

  1. Open the Maintenance app and click Data set > Data set .

  2. In the list, find the data set you want to create a section form for.

  3. Click the options menu and select Manage sections .

  4. Click the add button.

  5. (Optional) In the Name field, type the name of the section.

  6. (Optional) In the Description field, type a description of the section.

  7. (Optional) To display totals for rows in the section form during data entry, select Show row totals .

  8. (Optional) To display totals for columns in the section form during data entry, select Show column totals .

  9. Assign data elements to the section:

    1. (Optional) Select a Category combination filter .

      Note

      You can only use one category combination per section.

      Option

      Description

      None

      Displays all data elements that don’t have a category combination.

      <No filter>

      Displays all data elements.

    2. Select data elements and assign them.

  10. (Optional) Sort the data elements within the section by using the up and down arrows to the left of the assigned data elements field.

  11. Click Save .

  12. Repeat add section steps for each section you want to have in your section form.

    In the Data Entry app you can now use the section form. The section form appears automatically when sections are available for the selected data set. Data sets which have section forms will automatically display the section form.

Note how each data element category has been separated into a separate section, and a data entry table has been automatically generated by the system. Use of section forms in combination with data element categories can drastically reduce the amount of time which is required to create data entry forms for data sets.

23.4.8.2 Edit a section form

  1. Open the Maintenance app and click Data set > Data set .

  2. In the list, find the data set you want to edit the section form for.

  3. Click the options menu and select Manage sections .

  4. In the list, find the section you want to edit.

  5. Click the options menu and select Edit .

  6. Edit the section and click Save .

  7. Repeat edit section steps for each section you want to edit.

23.4.8.3 Manage grey fields in a section form

You can disable data elements and category options for data entry. That means it won’t be possible to enter data into these fields during data entry.

  1. Open the Maintenance app and click Data set > Data set .

  2. In the list, find the data set you want to edit the section form for.

  3. Click the options menu and select Manage sections .

  4. In the list, find the section you want to edit.

  5. Click the options menu and select Manage grey fields .

  6. Select which fields you want to disable.

    Note

    If you’ve sections that contain data elements assigned to multiple category combinations, switch between the category combinations to view all fields.

  7. Click Save .

23.4.8.4 Change section display order in a section form

You can control in which order sections are displayed in a section form.

  1. Open the Maintenance app and click Data set > Data set .

  2. In the list, find the data set you want to edit the section form for.

  3. Click the options menu and select Manage sections .

  4. In the list, find the section you want to move.

  5. Click the options menu and select Move up or Move down .

    If the section you want to move is the first or last section in the list, you’ll only see one of the move options.

23.4.8.5 Delete a section in a section form

  1. Open the Maintenance app and click Data set > Data set .

  2. In the list, find the data set you want to edit the section form for.

  3. Click the options menu and select Manage sections .

  4. In the list, find the section you want to delete.

  5. Click the options menu and select Delete .

23.4.8.6 Translate a section in a section form

  1. Open the Maintenance app and click Data set > Data set .

  2. In the list, find the data set you want to edit the section form for.

  3. Click the options menu and select Translate .

  4. Select a locale.

  5. Enter the required information.

  6. Click Close .

23.4.9 Manage custom forms

23.4.9.1 Create a custom form

You design custom forms in a built-in WYSIWYG HTML editor. If you select Source , you can paste HTML code directly in the editing area. For a complete guide on how to use the editor, refer to http://docs.ckeditor.com/ .

To create a custom form:

  1. Open the Maintenance app and click Data set .

  2. In the list, find the data set you want to add a custom form to.

  3. Click the options menu and select Design data entry form .

  4. In the editing area, create the custom form.

    • Double-click on a object in the left-hand list to insert it in the form.

    • If you already have the HTML code for your form, click Source and paste the code.

  5. Select a Form display style .

  6. Click Save .

23.4.9.2 Scripting in custom forms

In custom data entry form you can use JavaScript to create dynamic behaviour and customizations. As an example, you can hide form sections based on specific user input for data elements, or show specific information when a form loads.

23.4.9.2.1 Events

The DHIS2 data entry module provides a range of events which you can register for and use to perform actions at certain times. The events are registered on the document element. The jQuery event object and the data set identifier are always the first two arguments provided to the callback functions. The table below provides an overview of the events and when they are triggered.

Data entry events
Key Description Arguments

dhis2.de.event.formLoaded

Triggered after the data entry form is rendered, but before data values are set in entry fields.

Event | Data set ID

dhis2.de.event.dataValuesLoaded

Triggered after data values are set in entry fields.

Event | Data set ID

dhis2.de.event.formReady

Triggered when the data entry form is completely rendered and loaded with all elements.

Event | Data set ID

dhis2.de.event.dataValueSaved

Triggered when a data value is saved successfully.

Event | Data set ID | Data value object

dhis2.de.event.completed

Triggered when a data set is successfully marked as complete.

Event | Data set ID | Complete registration object

dhis2.de.event.uncompleted

Triggered when a data set is successfully marked as incomplete.

Event | Data set ID

dhis2.de.event.validationSuccess

Triggered when validation is done and there were no violations.

Event | Data set ID

dhis2.de.event.validationError

Triggered when validation is done and there were one or more violations.

Event | Data set ID

dhis2.ou.event.orgUnitSelected

Triggered when one or more organisation units are selected in the org unit web tree.

Event | Org unit IDs | Org unit names | Sub org unit IDs

To register for an event:

<script type="text/javascript">

dhis2.util.on( 'dhis2.de.event.formReady', function( event, ds ) {
  console.log( 'The form with id: ' + ds + ' is loaded!' );
} );

dhis2.util.on( 'dhis2.de.event.dataValueSaved', function( event, ds, dv ) {
  console.log( 'Data value: ' + dv.value + ' was saved with data element: ' + dv.de );
} );

dhis2.util.on( 'dhis2.de.event.completed', function( event, ds, cr ) {
  console.log( 'Form was completed for org unit: ' + cr.ou );
} );

</script>

Note

Be careful to only use “namespaced” events like the ones in the example above and not general ones like “click” as the dhis2.util.on method will deregister the event first.

If your function only applies to certain data sets you can use the supplied data set identifier and shortcut your function for unwanted data sets like this:

dhis2.de.on( 'dhis2.de.event.validationSuccess', function( event, ds ) {
  if ( $.inArray( ds, ['utXOiGbEj14', 'Re7qzHEThSC'] ) == -1 ) {
    return false;
  }
  console.log( 'Form with id: ' + ds + ' validated successfully!' );
} );

The identifiers of the input fields in the data entry form is on the format described below. This format can be used to select the input fields in your script and perform actions on them:

<dataelementid>-<optioncomboid>-val

Since the data set identifier is provided for all events a feasible alternative is to utilize the “files” Web API resource and keep your callback functions in a single file, where you let the JavaScript code take action based on which data set is currently loaded.

23.4.9.2.2 Functions

The DHIS2 data entry module contains JavaScript API functions which can be accessed from custom data entry forms.

dhis2.de.api.getSelections : This function returns a JavaScript object which contains properties for all dimensions with corresponding values for the identifiers of the selected options. It contains properties for “ds” (data set), “pe” (period), “ou” (organisation unit) and identifiers for all data set categories.

An example response looks like this:

{
 +  ds: "lyLU2wR22tC",
 +  pe: "201605",
 +  ou: "g8upMTyEZGZ",
 +  LFsZ8v5v7rq: "CW81uF03hvV",
 +  yY2bQYqNt0o: "yMj2MnmNI8L"
 +}

Example JavaScript usage of this function:

var sel = dhis2.de.api.getSelections();
 +var orgUnit = sel["ou"];
 +var partner = sel["LFsZ8v5v7rq"];

23.4.10 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 .

23.4.11 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 .

23.4.12 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 .

23.4.13 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 .