What is the Self-Service Import App?

The Self-Service Import Application is a tool accessible within DATIM that enables Implementing Partners and PEPFAR country teams to independently validate and import MER results.

The app provides a single consolidated platform to:

• Verify data files for conformance to technical requirements
• Validate interdependencies between metadata dimensions, including Operating Units (OU), funding mechanisms, and data elements (indicators)
• Execute "Dry Runs" to provide an initial summary of and analyze how a proposed import will impact potentially existing data in DATIM
• Independently Import validated MER data directly into the production environment

Why use the Self-Service Import App?

The app was developed to simplify the MER import process in DATIM by addressing limitations in the DHIS2 import process. Key reasons for utilizing this application include:

• Simplification in data import process: The app replaces the legacy process of submitting MER results and validation screenshots via DATIM support tickets, removing the need for hands-on assistance from the DATIM support team for routine imports.
• Reduced Turnaround Time: Users no longer need to wait the standard 1-2 business days for the support team to review and import their data. Once validation criteria are met, the import can be initiated immediately.
• Consolidated Access: By moving the entire workflow into DATIM, users are no longer required to obtain separate OKTA access for external R Shiny validation tools.
• Enhanced Data Quality Checks: The app leverages DHIS2 "Importance" levels to categorize issues into validation errors (high/critical issues that block import) and Validation Warnings (indicator data that should be cleaned or justification provided to continue).
• Users can download comparison files to review which results will be updated or ignored, providing full visibility into how the import file affects existing data. (in development)

Who would want to use the Self-Service Import App?

The intended audience of the Self-Service Import App is MER data reporting entities. The app can be used by either partners or interagency users depending on the circumstances of the Operating Unit.

Unlike the data import process where DATIM support team assists with the import of the consolidated MER results data file, the Self-Service Import App allows partners to import their data without requiring consolidation of the data at the country level for import-based reporting.

Country teams will have to collaborate to ensure clear roles, to ensure that different users do not attempt to import the same data.

A custom DATIM role is required for a user to use the app. Reporting entities should designate the user who will be responsible for importing the data into DATIM.

Users wishing to be granted the role should confirm that they have reviewed this guidance documentation and understand how the app works.

Roles and Responsibilities

Code Lists

Current Code Lists: The code lists provide the identifier to be used in the data import files i.e. UIDs for MER data elements, Disaggregates/Category Option Combos, Mechanisms/Attribute Option Combos, and Organization Units. In addition, to provide additional context, these code lists contain common names and codes for data elements (Indicators & Disaggregates) and data sets (forms).

Code lists are Not open to the public, and you will need to log into DATIM to access them

• Data Elements
• Mechanism
• Org Unit

Current Code Lists

Data Elements

File Format

Data intended for import into DATIM must satisfy strict requirements with respect to the format. It must be in correct format, use correct metadata, as well as valid values.

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:

Constructing Appropriately Formatted Files for Import File 

A correctly formatted .CSV file containing MER data should be generated. The following columns are required in the CSV file and must match the following order:

1. Dataelement
2. Period
3. OrgUnit
4. CategoryOptionCombo
5. AttributeOptionCombo
6. Value

Data Element and Category Option Combo/Disaggregation

MER data in DATIM must have a data element and disaggregation (also known as a category option combination). Data elements and category option combos/disaggregations must be reported using their DATIM UIDs (Unique Identifier). Please refer to the code list on the DATIM Support page for UIDS.

Many data elements have multiple levels of disaggregation (age, sex, service type, etc.). DATIM also contains several legacy data elements, which are present in the system (for historical data) but may not be active or relevant for the current data entry. You must make sure to reference the correct code list for the corresponding reporting period.

The data element and CategoryOptionCombos/Disaggregations UIDs are organized on the DATIM Support page by reporting period (year/version), available types (e.g. results, targets, narratives, etc.), dataset type (e.g., community, facility), and the code list in various formats (HTML, JSON and CSV).

Note: The ultimate reference for this is the data entry screens of DATIM itself. If there are any invalid data elements or disaggregations present in the import file, a conflict will be reported during the validation phase. Code lists have been made available to help you develop mappings for data elements and disaggregations.

If you are unsure about which version of the code lists to use for your data, contact the DATIM Support Team for further guidance.

Period

Each data value in DATIM must have a valid period. MER results are currently reported on a quarterly basis. All periods refer to calendar periods referring to the time period when the data is captured.

DATIM uses the DHIS2 internal date format for designating reporting periods. All periods in DATIM data import files must provide a valid DHIS2 period identifier. Thus, MER FY27 Q1, spanning October 1, 2026 – December 31, 2026, should be entered as “2026Q4.”

Organization Unit

Organization units (OU) are typically the site where the data is captured. Examples include site, facility, community, district, and county. This should not be confused with PEPFAR Operating Units. Facility, site, community, and OU UIDs are available in the current code list available on the DATIM Support page.

Attribute Option Combo

This refers to the funding mechanism for which the data apply.

FACTS Info is the source for the DATIM implementing mechanism. Data from FACTS Info is regularly synchronized with DATIM. All mechanisms that are present in a given data import file must be active for the period for which data is being imported. After a mechanism is “promoted” or made active in FACTS Info, it will take up to 24 hours for the data to be updated in DATIM. Please ensure that all mechanisms for which you will be reporting data are active in FACTS Info prior to attempting to validate and import your data. If any mechanisms are not active or data need to be reported against mechanisms to which the user does not have access, validation errors will occur.  

The “Agreement End Date” attribute in FACTS Info may inhibit a mechanism being visible or available in DATIM. The date must be valid for data to be entered appropriately. NOTE: IPs DO NOT have access to this system. Funding agencies should provide the mechanism ID to partners interested in data exchange.

Funding mechanisms must be reported using their UIDs in the import file. Funding mechanism UIDs are available at the DATIM Support page.

Value

This is the data value being reported. It has to be a positive number. Zeros are accepted, however discouraged, as they carry no meaning in the downstream analytical systems.

Validation Rules

Data validation rules define how data values of different indicators relate to each other. As a simple example, the number of positive HTS_TST tests should not exceed the number of HTS_TST tests. Validation rules are evaluated for a given OU, period, and attribute option combination. Thus, data are not validated across two different periods or for two different mechanisms. Data validation rules provide additional restrictions and quality checks on the data that can be imported into DATIM.

Validation rules are categorized as errors and warnings. Errors will prevent data from being imported. For example, validation rule that checks that optional age bands (50+) are not present at the same time as regular ones (50-54, etc.) is an error, and data violating this rule will be flagged, preventing its import. Warnings are validation rules that are violations but can either be data quality issues or justifiable under certain circumstances. For example, one validation rule stipulates that HTS_INDEX offered and accepted must match, however if a patient was offered in one quarter and they accepted it in the next one, the two values will not match and this validation rule violation will be encountered when data file is validated prior to import.

Validation rule violations should be reviewed, and if they are data quality issues, addressed in the data. If issues are justifiable, note explaining the justification details should be provided in the textbox presented to the user prior to data import.

The full list of MER validation rules can be found here.

How to Use the App

After the file is appropriately formatted per File Format, follow the below steps for the Self-Service Import App.

Note: Use the Validation Tool prior to using the Self-Service Import App as this version does not yet have all the validations. After using the Validation Tool, proceed with the steps below.

1) Select the "MER Self-Service Import” Application.

2) From the Self-Service Import app landing page, start a new import by using the blue + button at the bottom right. Once you select “Start your import here”, the following pop-up will appear. Drag and drop your import file or browse the file and select the appropriate Operating Unit. Then click “Process File.”

3) After the File Upload successfully completes, the application will automatically continue to the Validations. This screen indicates that the Validations are in progress.

Note: If you encounter errors at this stage, please refer to the Appendix Error List for guidance on how to fix the given Validation Errors.

4) After Validations successfully complete, the application will automatically continue to the Dry Run. This screen indicates that the Dry Run is in progress.

5) After the Dry Run successfully completes, this screen will appear, providing high level summary of the dry run activity. The table contains three columns:

• Created – the number of records that will be created in DATIM when data file is imported.
• Updated – the number of records that will be updated. This indicates that records with the same metadata already exist in DATIM and have different values. These records will be updated with the values from the import file.
• Ignored – the number of records that cannot be imported. This indicates that either records with the same exact values are already present in DATIM, and they do not require updating, or errors were encountered during the dry run. For records ignored due to errors, encountered validation issues will be provided. In case of errors, identified issues must be resolved, and the import file should be re-uploaded.

If there are no errors, and you would like to proceed with the import, click “Start Import.”

6) During the Import, this screen will appear. 

7) When the Import is successfully completed, this screen will appear. The table provides a high-level summary of the imports. Refer to the dry-run section above for details regarding interpreting created, updated, and ignored entries.

8) After the file is successfully imported, validate that data is in DATIM. There are two methods to validate that the import was successful:

Post-Import Activities 

Move Imported Data through DATIM Approval Workflow

Data imported into DATIM must still follow the required approval workflow. When data is imported into the production system, they will be in the “Pending” state. IPs should submit their data to the agency, which can then approve and submit the data to inter-agency space.

Data Deduplication

Once data has been imported and approved to inter-agency level, if there are any duplicates, they will also need to be resolved by the PEPFAR country team. In terms of planning, it is important to consider that the de-duplication process can be very lengthy depending on the number of duplicates.

Data Import Cleaning Guidance

Please read the below guidance for each of the data import cleaning options.

Preferred Approach for Data Updates: Delete File + New/Updates File

In most circumstances when updating data, previously reported data needs to be removed from DATIM (e.g. erroneously included data). If you intend to delete data, and know what data you want to delete, you should prepare another file with the data values that should be deleted.

You will use the delete file first to expunge the records, and then the update file. Please exercise extreme caution to ensure that the delete file includes only the data you intend to remove.

If you would like to update existing data or import supplemental data, you should import them as a single combined file.

Current limitations

Updating data in DATIM

To update data in DATIM using an import file, it is necessary to provide a delete file to first clear out implicated data before importing updated data. This two-step process prevents any outdated data from remaining in the system by mistake.  The app is designed to streamline routine imports but does not yet support the specialized two-step workflow required for data updates. Under the current iteration of the Self-Service Import App, updating data will follow the standard data import processes, by submitting a DATIM support ticket along with your delete file and your updated import file. Please plan accordingly and allow enough time for potential complications, data review, deduplication, and necessary approvals.

Resources

Several reference and guidance materials further explaining the DATIM data import are available on the DATIM Support page under the DATIM Data Import and Exchange Resources page.

Appendix

Error List

The Self-Service Import App performs a series of checks during the file upload, validation, dry run, and import to ensure a successful import. If any issues are detected, the application will display error message(s) to help resolve the problems. This section outlines the various error messages you may encounter, where you may encounter them in the process, and guidance on how to fix them so you can complete the import process.

Note: These are the error messages built for the Pilot Release. The next release will have additional error messages and validation checks.

Examples of Potential Errors

Below are examples of the different types of errors you may encounter. The screenshots are not exhaustive, but an example of the type and location of the errors during the upload process.

File Upload:

Validation Errors:

Dry Run Errors: