 | Working draft
This document is a work in progress. It's meant as a discussion that will eventually lead to a specification. |
Specification
Index
Introduction
Organisation units
The component dealing with organisation units must support:
- Adding/Removing/Updating OrganisationUnits in a hierarchy
- Moving OrganisationUnits in the hierarchy
- Grouping of OrganisationUnits
- Groups of groups? groupsets?
Adding/Removing/Updating OrganisationUnits in a hierarchy
An OrganisationUnit object contains these members:
// The unique identifier
private int id;
private String name;
// The set of children organisation units
private Set children = new HashSet();
// The parent
private OrganisationUnit parent;
private String shortName;
private String organisationUnitCode;
private Date openingDate;
private Date closedDate;
private boolean active;
private String comment;
The object contains its own references to parent and children, so the hierarchy is represented by the organisation objects themselves.
Moving OrganisationUnits in the hierarchy
It must be possible to move OrganisationUnits in the hierarchy; E.g. OrganisationUnit A, B and C. A has B and C as children. It must be possible to move B from A's child to C's child. This is not only a matter of setting a new parent in B, the hierarchy's history must be stored. Since OrganisationUnits can register DataValues and these DataValues are registered for a Period, OrganisationUnits that have moved must be considered when doing queries. E.g. OrganisationUnit A, B, C and D. A has children B and C, D is a child of B. If D registeres DataValues for two months, but is moved two weeks into the second month (D becomes a child of C), then the DataValues that are registered after the move must be considered as registered under C, but everything prior to this must be considered as registered under B.
This should be invisible to the users of any any interface that work with aggregated DataValues.
OrganisationUnit Groups
This component must support the possibility of grouping OrganisationUnits; E.g. Rural OrganisationUnits, urban OrganisationUnits, OrganisationUnits near a water source, etc.
Orgunit groups can flexibly be added by the users and then assigned to the orgunits.
OrganisationUnit Group Sets
The orgunit group sets is a way to more strictly organise orgunits and groups by organising sets of groups that can be compulsory and/or exclusive.
E.g. if we want to classify all orgunits as either urban or rural units we first define the two orgunit groups "urban" and "rural". This functionality is already in place in dhis-oum. Then we want to make some restrictions on these groups: All orgunits must be part of one of these two groups (complusory) and can only be part of one of them (exclusive). To do so we create a new orgunit group set called "urban/rural" and add the two groups "rural" and "urban" to this set. Then we must define this set as complusory and exclusive. Then all orgunits must be assigned to one of these two groups for the database to be valid.
A group set must have:
- a Name
- a collection of (orgunit) groups
- a property Compulsory that can be true or false
- a property Exclusive that can be true or false
Registration of DataValues
Support for CRUD operations on RoutineDataValues, SemiPermanentDataValues and SurveyDataValues.
A registered DataValue is unique, since it represent a registered value for one DataElement, at an OrganisationUnit, for a Period.
A DataValue contains these members:
private DataElement dataElement;
private Period period;
// The unique identifer of the OrganisationUnit that registered the DataValue
private String source;
// A flag indicating what kind of DataValue it is (Routine, SemiPermanent, Survey)
private String flag;
// The registered value
private String value;
// The user that stored the value
private String storedBy;
// Time of registration
private Date timestamp;
private String comment;
Aggregation of DataValue's
It has been concluded that a DataValue stored in the DHIS database is a "raw" data value and should not be considered as an aggregated data valule. DHIS should also support the notion of an aggregated type for DataValue - AggregatedDataValue. The same holds for IndicatorValue's.
Aggregation of DataValues to a higher level should be supported in (at least) two ways:
- Single values on demand
- According to a defined set of DataValues that should be aggregated
Explanation of the aggregation strategy
DataSets
A dataset is used to organise the data entry (registration of data) and to organise the reporting of data between organisation units in the organisation hierarchy.
Dataset properties
- Name, e.g. "Immunisation program", "Population estimates"
- Type, the type of data the dataset contains: routine, semi-permanent or survey
- Frequency, the frequency by which this dataset is being registered and or reported
Dataset used to organise data entry
The data entry module (see below) is organised around the datasets. Data is registered for 1 dataset at a time. All the data elements in one dataset must be part of the data entry form used to register data for that dataset. As datasets refer to only one org unit, each org unit has a list of their own datasets that defines which data elements the org unit registers and at which frequency. A dataset will often represent the paper forms used in the health information system, but note that this is not a requirement for making reports (just like the paper forms if desired) in the reports module. See the report module below for more information on how to make reports.
Dataset used to organise data reporting between org units in the hierarchy
One of the core philosophies behind the HISP project that is inscribed in the DHIS software is the balance between local flexibility and central standardisation. HISP has used the hierarchy of standards approach to achieve this balance. The idea is that an orgunit in the org hierarchy; let us say a district health office has certain obligations to what data that must be reported to the level above (in this case the provincial/federal state health office). Again, the provincial office has to follow the reporting directions set by the national level. So the data reporting between org units is standardised and follows the directions of the level above. At the same time the DHIS allows for local flexibility so that each level in the hierarchy can add other local data elements to register and analyse in addition to the standardised set of data that is demanded by the level above. These local additions are of no interest to the level above so it will never be reported upwards, but it is of importance to the local level and will be used locally.
The dataset hierarchy
To enable this balance between standardised reporting and local flexibility to define what data to capture the datasets are organised in a hierarchy much the same way as the org units. A dataset can belong to only one org unit, but a hierarchy of related datasets can belong to a hierarchy of related org units to represent the reporting hierarchy. Dataset can be organised in a hierarchy so that all org units that are registering and/or reporting the same data, e.g. the immunisation program, will have a dataset with the same name, the same frequency, and the same set of data elements as the org unit parent at the level above. The set of data elements attached to each dataset is the key to how data reporting is standardised and at the same time there is flexibility to expand the data collection locally. A minimum requirement for any dataset (except for the root/top) in a dataset hierarchy is that the set of data elements contains at least the same data elements as the parent dataset (the dataset defined by the parent orgunit, "the demanding boss"). For any dataset additional data elements can be added to meet potential additional needs for local data collection. Any addition will then be part of the dataset that the child org units are using, if any, and so it passes on down the hierarchy. Note that an org unit can have many datasets, both datasets that are part of a reporting hierarchy of datasets, and also locally defined datasets that have no parent dataset and hence have full flexibility to define name, frequency and data elements.
DataElements
As discussed in the Friday meeting (October 28.), we should support hieararchies of DataElements, so that the OrganisationUnits can decide the granularity of their input.
When the OrganisationUnits register data, the level av granularity decides if the DataElements at the different levels in the hierarchy will be calculated or manually registered.
Validation
Indicators
Internationalization and Localization
- Multi-language support
- Localized dates and currency
- Translation of strings
Multi-language support
All strings not specific to the deployment must be multi-language enabled. This includes:
- Alle names of objects which are "global"; e.g. names of DataElement, Indicators, Validators, etc.
- All strings in the GUI
Strings specific to the deployment does not have to be multi-language enabled.
- OrganisationUnit names
Localized dates and currency
Dates and currency should be represented in a localized format.
Translation of strings
A GUI for translating strings should be thightly integrated in the application.
Data Dictionary
Data integration
BACKGROUND
This module covers different ways of sharing data internally within DHIS 2 instances and externally with other applications.
The different kinds of data that shall be exported/imported:
Data values
The "raw" data values that are registered in the system. Always linked to an orgunit, a data element and a data period.
-external use:
The data format for external exchange of this kind of data must include:
- The name of the registering organisational unit
- The names of the orgunits in the organisational tree above the registering orgunit (orgunit parent, grandparent, grand grandparent all the way up to level 1)
- The name of the data element
- The name of the data period
-internal use:
Already implemented using xstream and auto-generated xml formats based on the data model. This data format is not readable/understandable to external applications.
Datamart values
These data values are calculated or manipulated based on the raw data that is registered. There are indicator values are calculated based on indicator formulas defined by the user and aggregated data values that are aggregates of raw data values aggregated for orgunits and/or data periods.
SOLUTION
Step 1
Provide two comma separated values (csv) files, one for raw data values and one for indicator values.
The files shall include the orgunit registering data, the orgunit parents (all the way up to level 1) of the registering unit, the data period, the name of the data element/indicator and the value.
File format for raw data(based on a 5 level hierarchy):
OU1Name, OU2Name, OU3Name, OU4Name, OU5Name, DataElementName, DataPeriodName, DataValue
Norway, Hordaland, Bergen, Fana, Titlestad, Malaria, Jan 06, 100
Norway, Hordaland, Bergen, Fana, Titlestad, Malaria, Feb 06, 89
OU1Name, OU2Name, OU3Name, OU4Name, OU5Name, IndicatorName, DataPeriodName, IndicatorValue
Norway, Hordaland, Bergen, Fana, Titlestad, BCG Coverage, Jan 06, 100
Norway, Hordaland, Bergen, Fana, Titlestad, BCG Coverage, Feb 06, 89
