Wiki Spaces

Documentation
Projects
Resources

Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack

Documentation

Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Example Files

Attached is a zip file containing a DSD for two indicators.   This 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.

SDMX-HD_example.zip

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.

...

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 elements are 'indicators' as follows: 

...

  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:

...

Code Block
<?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:

...

Code Block
<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.

...