Purpose
This article provides guidance on DATIM concepts, outlining requirements for importing data into DATIM, ensuring compatibility and alignment with system and program needs.
DATIM Concepts
Data intended for import into DATIM must satisfy strict requirements with respect to the format of the data as well the relationship of the data to the current metadata within the system.
- Current Code List: The code lists provides the identifier to be used in the data exchange files i.e. the Codes and UIDs code for MER data elements, Disaggregates/Category Option Combos, Mechanisms and Organization Unit. In addition they contain common names and codes for data elements (Indicators & Disaggregates) and data sets (forms).
- Data Exchange Guidance: This section provides instructions and useful resources necessary for performing MER data exchange with DATIM.
Additional Resources: Other useful DATIM and DHIS2 links and resources are provided in this section.
Metadata dimensions
Data must be valid with respect to the destination sites, periods, indicators, disaggregation and mechanisms, therefore all data values must be associated with four metadata dimensions which describe different aspects of the data namely:
-
-
Where - Organization Unit: This dimension describes the location of the data i.e. where the data is captured.
- Example: Clinical Facility, Community Site, or OU Level
- What - Data element (Indicator) + Disaggregation: This dimension describes the phenomena which the data value is attached to, such as the Number of HTC tests for Females 1-4. In this case the data element has a disaggregation of Female 1-4. Data elements in DATIM typically have many different disaggregations with respect to age and sex. In addition to that, different classes of data elements such as Targets and Results and DSD and TA exist.
-
When - Period: This dimension describes the time period of the data being reported.
- Example: January through March 2016 or April through June 2016
- Who - Funding mechanism: Also known as the “attribute option combination” this is an extra custom dimension in DATIM, which describes which implementing mechanism the data is being reported for and refers to the FACTS Info funding mechanism ID.
-
Where - Organization Unit: This dimension describes the location of the data i.e. where the data is captured.
Format
Data intended for import into DATIM must also satisfy strict requirements with respect to the format i.e. valid types of data (integers, options, etc.)
The data formats are generic DHIS2 formats which have been mapped to PEPFAR specific concepts in DATIM. The elements in the formats are described in the following.
| DHIS2 concept |
PEPFAR concept |
Description | Format |
|---|---|---|---|
| Data element | Indicator | Data item being captured. In PEPFAR terms referred to as indicator. Example is "Number of adults and children currently receiving antiretroviral therapy (ART)." | Data elements can be reported either using Codes or UIDs (refer to Current Code List contained in this online guide for specific Codes and UIDs). |
| Period | Period |
The time period for which the data is captured. |
For further information, you can view the DHIS2 documentation here. |
| Org unit | Facility / Site / Community / OU | Organizational unit for the data. Examples are site, district and country. Not to be confused with PEPFAR OU. Would typically be the site where the data is captured. | Facility, Site, Community and OU codes and UIDs are available in the Current Code List contained in this online guide. |
| Category option combo | Disaggregation | The disaggregation of an indicator/data element. Example is "Female, Under 5." | For the Disaggregation/ Category option combo Codes or UIDs refer to the Current Code List contained in this online guide for specific Codes and UIDs). |
| Attribute option combo | Funding mechanism | Funding mechanism for which the data applies. Example is "25147". Refers to the FACTS info mechanism ID. | The appropriate funding mechanism Code or UID should be reported (refer to Current Code List contained in this online guide for specific Codes and UIDs) |
| Value | Data value | This is the data value being reported. | An example data value is "45." |
| Comment | Data comment | This is a comment associated with the data value. | An example comment is "Needs follow-up." |
Back to the top.
Current Code Lists
Data Elements
| Fisacl Year (Version) | Type | Data Set | HTML | JSON | CSV |
|---|---|---|---|---|---|
|
FY25 (MER 2.8.2) |
Results | MER Results: Community Based | HTML | JSON | CSV |
| MER Results: Facility Based | HTML | JSON | CSV |
Code List Comparison File
An Excel file has been developed as an additional resource to assist with the data element updates from MER v2.8 to MER 2.8.2. This file shows the changes between the two versions as it pertains to codes that have been removed or updated from this transition.
Download the comparison file: Excel comparison file
Note, the Excel file contains two sheets:
- Sheet 1: list of Data elements (indicators) that have been removed
- Sheet 2: list of Category Option Combos (disaggregations) that are to be updated or removed
Re-importing FY25 Q1 January Snapshot Data
For OUs that have previously entered FY25 Q1 data under the deprecated MER 2.8 dataset, you should have received a CSV snapshot file of your data from GHSD. The original FY25 Q1 data has been removed from DATIM, however, you can update your snapshot file to be complient with MER 2.8.2 to re-import into DATIM.
The Excel code list comparison file above can be used together with the Q1 Data Transformation guide below to assist you in transforming the Q1 data snapshot files for data import.
Download the data transformation guide: Q1 Data transformation guide
Mechanism
| Concepts | HTML | JSON | CSV |
|---|---|---|---|
| Mechanism Attribute Combo Option UIDs | HTML | JSON | CSV |
Org Units *
* The Org Unit code lists are Not open to the public i.e. you will need a DATIM log in to access them
Click this link to view and download your Org Unit code list
Data Exchange Guidance
| April 22, 2024 | MER |
This guide will provide guidance to Data for Accountability, Transparency and Impact Monitoring (DATIM) data importers and explain key concepts in more detail including how to construct an appropriately formatted file for import as well as a graphical representation of the steps necessary to perform a successful MER data import into DATIM. |
|
| Apr 9, 2025 | MER |
This guide explains how to update the 2025Q1 snapshot files from the DATIM team for re-import. |
Back to top
Additional Resources
DATIM instances
Multiple instances of DATIM with various purposes are deployed.
- datim.org - This is the live production server of DATIM. Here, you can use the Validation App to ensure your imported files meet all necessary standards before proceeding.
- dev-de.datim.org - Also known as "DEV-DE", this is a dedicated server and a copy of the actual DATIM production system that can be used for final testing of your import file. It is strictly a testing environment that can be used to test data import files prior to submission for import into the actual production system, without affecting the data stored in production.
Common DATIM data exchange formats
DATIM supports multiple data formats for data exchange, however this guidance will focus on the following:
- CSV (Comma separated values)
- JSON
CSV
The CSV format is documented in general here. A sample CSV data file looks like this:
"data_element","period","org_unit","category_option_combo", /
"attribute_option_combo","value","stored_by","last_updated","comment"
"deCode","201202","ouCode",,"aocID","1",,,"comment1"
"deCode","201202","ouCode",,"aocID","2",,,"comment2"
"deCode","201202","ouCode",,"aocID","3",,,"comment3"JSON
The JSON format is documented in general here. A sample JSON data file looks like this:
{
"idScheme": "code",
"period": "peCode",
"orgUnit": "ouCode",
"attributeOptionCombo", "aocCode",
"dataValues": [
{ "dataElement": "deCode", "value": "1", "comment": "com1" },
{ "dataElement": "deCode", "value": "2", "comment": "com2" },
{ "dataElement": "deCode", "value": "3", "comment": "com3" }
]
} Support
For questions or issues related to data exchange please submit a help desk ticket at the help desk.
Back to top.
Comments