Attached is a zip file containing a DSD for two indicators. I will use this DSD to illustrate some of the functionality in the OpenMRS - SDMX-HD integrationThis example zip file will be used in the following examples to illustrate how to 'read' SDMX-HD packages, and prepare them to work with the OpenMRS integration.
Package File Structure and Features
If you look at the contents of the .zip file above, you'll notice that in the root of the archive is a file called DSD.xml. If you are building this .zip file from scratch, you need to make sure that the DSD.xml file is in the root of the archive. This is the main descriptor file for the data set definition of the indicators that you are trying to export. DSD.xml contains the concepts, codeLists, indicator disaggregation and indicator hierarchy descriptions, and key families for your export -- all of which affect the structure of the indicator output.
The example package above was developed as an experiment to determine what the 'rules' are for exporting data in SDMX format. The ultimate goal of this work is to create a new DSD SDMX-HD descriptor package for the 2012 Rwanda TracNET indicators. If you are building a new export, you could use the example file as a template for getting started. You just need to add your own indicators, disaggregations, and indicator hierarchy.
This example DSD is built on a WHO-published example. Many of the included files aren't used. The best way to determine what's important in a DSD is to look in the KeyFamily section and work backwards.
How Indicators Are Defined:
The way the OpenMRS SDMX-HD module determines what an indicator is is elements are 'indicators' as follows:
1) a Dimension defined in the KeyFamily section in the DSD is found that is mapped to CL_INDICATOR:
In this example, there are two indicators, one called 'TEST1: adult initial' with value = 1, and 'TEST2: adult return'. In production, these would be real indicators with names like 'Number of Pediatric Primary Care Visits'. It is essential that each indicator has a unique value.
How Dimensions Are Defined:
Dimensions can be defined similarly to Indicators, but they don't have to have a specific name (Indicators, however, must be defined in CL_INDICATOR). In the example DSD, one of the dimensions is Gender. Following the pointers you'll see that:
<?xml version="1.0" encoding="UTF-8"?> <Structure xmlns="http://www.SDMX.org/resources/SDMXML/schemas/v2_0/message" xmlns:structure="http://www.SDMX.org/resources/SDMXML/schemas/v2_0/structure" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.SDMX.org/resources/SDMXML/schemas/v2_0/message SDMXMessage.xsd"> <Header> <ID>SDMX-HD-DSD</ID> <Test>false</Test> <Truncated>false</Truncated> <Name xml:lang="en">TRAC PLUS</Name> <Prepared>2009-03-20</Prepared> <Sender id="TRACPLUS"> <Name>TRAC PLUS</Name> <Contact> <Name xml:lang="en">Admin</Name> <Department>Health Care Informatics</Department> </Contact> </Sender> </Header> <CodeLists> <structure:CodeList id="CL_GENDER_TRAC" agencyID="TRACPLUS" version="1.0" urn="urn:sdmx:org.sdmx.infomodel.codelist=TRACPLUS:CL_GENDER_TRAC"> <structure:Name xml:lang="en">Gender</structure:Name> <structure:Code value="0" urn="urn:sdmx:org.sdmx.infomodel.codelist.Code=TRACPLUS:CL_GENDER_TRAC[1.0].0"> <structure:Description xml:lang="en">Male</structure:Description> </structure:Code> <structure:Code value="1" urn="urn:sdmx:org.sdmx.infomodel.codelist.Code=TRACPLUS:CL_GENDER_TRAC[1.0].1"> <structure:Description xml:lang="en">Female</structure:Description> </structure:Code> </structure:CodeList> </CodeLists> </Structure>
So How Do I Use These Dimensions With OpenMRS?
Dimension Hierarchies can be applied on an indicator-by-indicator basis. To see how this works, look at the CodeListHeirarchy section of the DSD, which says:
<ns:OBS_VALUE GENDER="0" value="37" INDICATOR="1"/> <ns:OBS_VALUE GENDER="1" value="45" INDICATOR="1"/> <ns:OBS_VALUE value="154" INDICATOR="2"/>
How Do I Setup Dimensions In OpenMRS To Match This Example?
There is a simple list of steps that were undertaken to test the above SDMX-HD package. For more information, see the documentation for the Reporting Module.
4) Finally, follow the instructions in Ryan's tutorial for how to upload and map an SDMX-HD package. *It is important to do things in order* -- configuration first, then dimensions, then indicators, then attributes. Then you should be able to just run the thing.
How To Define Sections
In the 0.6.6 version of the SDMX-integration module, you can have your indicators grouped into sections in the output. I'm going to use this in the final TracNET output to explicitly group ART and PRE-ART indicators (these are the two values in the CL_ISET CodeList).
Notice how each indicator ended up in its own Section.
Notes About Final Report Output
The above output is the complete SDMX-HD indicator result for the DSD attached at the top of this page. When you run an SDMX-HD report in OpenMRS, you must choose the SDMX-HD renderer. When you do this, you get a .zip file, and this .zip file contains the entire SDMX-HD .zip file you started with, with the addition of DATA_CROSS.xml which is added to the root directory of the zip file, next to DSD.xml. DATA_CROSS.xml contains the indicator result shown above.