10.3. Manage data sets and data entry forms

10.3.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".

Example 10.5. Categories for data sets

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:

Table 10.5. Data entry form types

Data entry form typeDescription

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]A data set can have both section and custom forms

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:

Table 10.6. Data set objects in the Maintenance app

Object type

Available functions

Data set

Create, assign to organisation units, edit, clone, 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


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

10.3.3. Create 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]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.

    Example 10.6. Open future periods 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]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 DHIS 2 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) Select a Legend.

    [Tip]Tip

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

  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.

    [Tip]Tip

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

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

    [Tip]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).

10.3.4. Edit data sets

  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. Modify the options you want, for example add or remove data elements and indicators.

  5. Click Save.

10.3.5. Clone data sets

Cloning a data set can save time when you create many similar data sets.

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

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

  3. Click the options menu and select Clone.

  4. Modify the options you want.

  5. Click Save.

10.3.6. Change sharing settings for data sets

You can assign different rights to the data set based on user groups and user roles.

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

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

  3. Click the options menu and select Share.

  4. (Optional) Search for a user group and select it. The user group is added to the list.

  5. Change the settings for the user groups you want to modify.

    • Can view: Everyone in the user group can view the object

    • Can edit: Everyone in the user group can view and edit the object

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

  6. Click Close.

10.3.7. Delete data sets and forms

[Warning]Warning

Any data set which is deleted 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 click Data set > Data set.

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

  3. Click the options menu and select Delete.

    This deletes the data set and all associated data forms.

  4. Click OK to confirm.

10.3.8. Display details of data sets

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

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

  3. To display all metadata about the selected object, click the options menu and select Show details.

10.3.9. Translate data sets

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

[Tip]Tip

To activate a translation, go to Apps > Settings > Appearance and select a language.

To translate the name of a data set:

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

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

  3. Click the options menu and select Translate.

  4. Select a locale.

  5. Enter the required information.

  6. Click Close.

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

Example 10.7. 

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 Override icon.

  5. Select new category combinations and click Close.

  6. Click Save.

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

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

10.3.13. Manage section forms

10.3.13.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. In the Name field, type the name of the section.

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

  7. Select a Category combination.

    [Note]Note

    You can only use one category combination per section.

  8. Select data elements and assign them.

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

  10. Click Save.

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

Example 10.8. Section form example

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.


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

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

  7. Click Save.

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

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

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

10.3.14. Manage custom forms

10.3.14.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-clik 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.

10.3.14.2. Scripting in custom forms

In custom data entry form you can use JavaScript to create dynamic behavior 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.

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

Table 10.7. Data entry events

KeyDescriptionArguments

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]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 unregister 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.

10.3.14.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"];