Owners: Vladimer Shioshvili and Jennifer E Shivers
This is an overview of the DATIM4U ADX (Aggregate Data eXchange) process. In a DATIM4U implementation, this process is designed to send aggregated PEPFAR indicator data from a DATIM4U system to DATIM Global system.
Before the ADX message can be received and processed by the DATIM Global system, the sites, indicators and mechanisms have to able to be understood by the receiving system. For DATIM4U, this is accomplished in the following way:
Sites are managed on the DATIM4U DHIS2 node PEPFAR Country Team's system and those sites are exchanged with the global via the site exchange process. For more information, see Overview - DATIM4U Site Exchange ProcessOverview - DATIM4U Site Exchange Process.
In the DATIM4U process, mechanisms are transferred from the source system, DATIM's FactsInfo system, into the 4U DHIS2 system. For more information see Overview - DATIM4U Mechanism Synchronization.
In the DATIM4U process, indicator metadata are currently synchronized by updating the DHIS2 forms.
The following system components are involved in the transaction:
- The Global PEPFAR System
- The FactsInfo system which is the source for PEPFAR Mechanisms.
- The Global InfoMan system which provides the standards-based process for transferring mechanisms.
- The shared OHIE Node Stack
- The shared InfoMan system which provides the standards-based process for transferring mechanisms.
- A mediator that controls the workflow for ADX and site exchange.
- XX DATIM4U System
- The 4U Node's DHIS2 system which imports the mechanisms.
Transaction Overview Diagram
The diagram above depicts the high-level transactions that support DATIM4U. Before submitting an ADX message containing the DATIM data, mechanism data will need to be imported into the 4U DHIS2 system and site data will automatically be synced before the ADX is submitted. Once the metadata is aligned, then the ADX message containing the DATIM data can be transmitted to the DATIM Global PEPFAR system.
ADX Exchange Process
The process will send aggregated PEPFAR indicator data (MER Targets or Results) from 4U to DATIM Global system.
To perform the exchange process, one will need to have access to the DATIM Data Submission DHIS2 app via DHIS2 permissions. These permissions are assigned by someone with the ability to manage users or perform user administration activities.
- "ADX User" role - a read only role that allows the user to open the DATIM Data Submission App and see the Data Export Log. However, users with this role cannot perform submissions.
- "ADX Exporter" role - a role that provides the functionality of the ADX user and enables the user to do submissions.
- "Super User" role - with this role, the user can perform the functionality of the "ADX User" and "ADX Exporter" as well as perform a test submission.
Exchange process steps
- Enter or upload data into 4U DHIS2 System and follow any business processes to get ready to submit the data.
- When ready to send the data to PEPFAR, log into DHIS2.
- Navigate to the DATIM Data Submission App and open the app.
- When the app opens, the following options will be available:
- A drop down that is used to denote what type of submission will be sent. You must select one of the following options.
- Select Results to send MER results data for most recent quarter that has been entered or uploaded into the 4U DHIS2 system.
- Select Targets to send MER target data for an upcoming COP year that has been entered or uploaded into the 4U DHIS2 system.
- Selecting Test will simply test that the settings for the ADX connection are in place and that the communications between the DATIM Global system and the 4U system are operating properly. It will NOT send any aggregate data.
b. To initiate the transaction, press the EXPORT button. This will begin the process of submitting the data.
- For Result and Target transactions, site metadata will be synced first. See Overview - DATIM4U Site Exchange Process for a detailed description of how the site exchange process works. Depending upon the volume of data entered, the transaction may take a couple of hours to finish importing the data into the DATIM Global system. The timeline is displayed to help track the progress of the transaction.
- To view the status of steps, you can click on the circles in the timeline to get more information about successes and failures of the import.
c. While exporting data, submissions errors may occur that prevents data transfer to DATIM. The following are the possible submission errors and how to handle them.
- Caused by un-approved mechanisms. This error will show if there are any mechanisms that are not yet been Submitted by Inter-Agency (level 2 f) on the DATIM4U. For more details on the MER approval workflow can be viewed here. The approval level for mechanisms can be seen on the Data Approval app by authorized users. In order to handle this submission error, the un-approved mechanism must have its approval to Submitted by Inter-Agency on DATIM4U through the Data Approval app. Click here for more information on Data Approval app.
- Caused by failed deletion. This error will show if the ADX Adapter is not able to delete all the data transmitted by the most recent successful submission. To handle this error, all mechanisms and data sets associated with the data that was successfully submitted must be at the 'Pending' stage (for mechanisms) and not expired (for data sets) on the DATIM Global side. The approval level for mechanisms can be seen and adjusted on the DATIM Data Approval app by authorized users. The expiration dates for data sets can be seen and adjusted on the DATIM Data Set Management (Data Sets app > Data Set) by authorized users.
ADX Data Exchange Steps
The following are the technical steps that occur once the EXPORT button in the DATIM4U DHIS2 app is pushed.
The DHIS2 App triggers data exchange process in the ADX Adapter, which in turn goes through following steps:
- The ADX Adapter, a 4U DHIS2 app, triggers a site synchronization process via the OpenHIM's site sync mediator. This process ensures that the destination system has latest organization hierarchy metadata prior to receiving the ADX message. For more information on the site exchange, see Overview - DATIM4U Site Exchange Process.
- Upon successful site synchronization, the ADX Adapter will automatically delete the data that is imported by the most recent successful ADX upload of that period. The ADX Adapter will send the ADX message to be deleted to 4U OpenHIM, where the deletion will be processed. If a successful ADX upload of that period does not exist, then deletion shall not happen.
- The ADX Adapter then retrieves relevant Target or Results data from the 4U DHIS2 system using Web API calls.
- The ADX Adapter then does any calculations or data checking prior to transforming into the ADX (Aggregate Data Exchange) format.
- The ADX Adapter then sends the ADX message to the 4U OpenHIM.
- The DATIM Mediator on the 4U OpenHim orchestrates and controls the transaction. Specifically it:
- Ensures that the transaction occurs over a secure channel through the DATIM Global OpenHIM.
- Enables the import into Global DHIS to be done asynchronously so that it is more reliable for large imports.
- Responds back to the 4U ADX app when an import completes.
Additional Technical Details
Additional technical details can be found in the following links.
- Link to ADX Message standard. http://www.ihe.net/uploadedFiles/Documents/QRPH/IHE_QRPH_Suppl_ADX_Rev1.0_PC_2015-05-29.pdf