SDMX-HD Module tutorial

Owned by Former user (Deleted)
Last updated: Nov 16, 2010 by Ryan CrichtonVersion comment
6 min read

<< Back to SDMX-HD Integration module

Introduction

Once the module is uploaded there will be 3 new item listed on the Administration page.

A short description of what each link does is listed below:

  • Upload an SDMX-HD Message - Allow a SDMX-HD Message to be uploaded to the system.

  • View SDMX-HD Messages - Allows the viewing of all SDMX-HD Messages that have been uploaded to the system as well as allowing the user to configure message and map indicators and dimensions in SDMX-HD to indicators and dimensions in the OpenMRS reporting framework.

  • Configuration Page - Allows the module to be configured easily.

Each of these functions will be described in more detail in the following sections.

Configuring the module

By clicking 'Configuration Page' the following screen will be shown:

Configuring the module is really easy, there is only one Configuration Option that need to be set. This configuration option is the 'Message Upload Directory'. This is the directory on the OpenMRS server's file system where SDMX-HD Messages can be stored. NB: This folder must be readable and writeable by the user that is running tomcat. For example here mine is set to '/usr/share/tomcat6/.OpenMRS/SDMX-HDMessages1-5-x'.

Uploading a SDMX-HD DataSet Definitions

By clicking 'Upload an SDMX-HD Message' the following screen will be shown:

Here a message can be uploaded by click the Browse button and locating the file on your local machine. The file can be given a Name (required) and a description (optional).

Viewing SDMX-HD DataSet Definitions

By clicking 'View SDMX-HD Messages' the following screen will be shown:

This shows a list of all the SDMX-HD Messages on the right. There is a Config icon that allows you to configure each message (explained below) a delete icon to delete this SDMX-HD Message and a 'Show KeyFamilies...' button. When this button is click all the KeyFamilies for this SDMX-HD Message are show on the right. There can be 1 or more KeyFamilies (explained below) for each SDMX-HD Message. There are a a few more action that can be performed for each KeyFamily, namely, a run report icon, a map indicators icon and a add attributes icon. These will be explained below.

DataSet Configuration

If you click the Config button for a SDMX-HD Message, you will see the following:

This page allows you to set a few useful attributes for the SDMX-HD Message. These are explained below:

  • Reporting Frequency - This is the frequency that this report should be run. If set this will be included in the exported SDMX-HD message.

  • datasetID - This is an ID for the DataSet that you are producing, this can be set to anything you like or left blank if not required.

  • dataProviderSchemeAgencyId - Set this only if it is required for your use case, otherwise it can be left blank.

  • dataProviderSchemeId - Set this only if it is required for your use case, otherwise it can be left blank.

  • dataProviderID - Think is the ID for the data provider that is often set in the SDMX-HD DataSet definition file. Look in the DataSet Definition file to find this ID if you require this attribute otherwise it can be left blank.

Clicking save stores these attributes.

Mapping a KeyFamily for a SDMX-HD DataSet Definition

A KeyFamily refers to a specific group of Indicators and Dimensions. Each KeyFamily defines a separate report in the OpenMRS Reporting framework and therefore each KeyFamily will be able to produce a separate export file.

When you click on the 'Map Indicator' icon for a specific KeyFamily they will see the following:

Here there are 2 steps you must perform:

  1. Map the dimensions that you need for the Indicators you want to report

  2. Map the actual Indicators

It is important that you do this in order as the mapping of an indicator will fail if the dimensions it refers to in teh SDMX-HD DataSet Definition is not already mapped. You don't have to map all of the Indicator and Dimensions, you may map only the ones that you require.

Dimension Mapping

When you click the map link on a Dimension you will see a page similar to the following:

You have 2 options when mapping a Dimension:

  1. You can map this dimension to a dimension that has been created in the OpenMRS reporting framework. When you select a dimension to map to a list of the different dimension options for the SDMX-HD dimension will be shown that you can map the dimension options of the dimension created in the reporting framework.

  2. You can map this dimension to a fixed value. This will set the dimension to that static value for every indicator that required this dimension.

Indicator Mapping

When you click the map link on a Indicator you will see a page similar to the following:

Select the correct indicator from the list of indicator that has been created in the reporting framework and click save. At this point the module automatically creates a report definition in the reporting framework (if one doesn't exist) and adds the indicator with the dimension options specified in the SDMX-HD DataSet Definition. If no dimension options are specified in the SDMX-HD DataSet Definition then all combinations dimensions and dimension options in this KeyFamily are added. (NB: If this doesn't make sense to you it is fine. You are not required to understand how this works to use the module).

Adding Attributes

Optionally you may add attributes for each KeyFamily. When you click the 'Add Attributes' icon you will see a page similar to the following:

Attributes are defined in the SDMX-HD DataSet Definition for each KeyFamily. Some are mandatory and some are conditional. All the mandatory attributes should be set to export a valid SDMX-HD Message. Where are various level at which attributes can be set, these can be seen above. A tick is displayed next to the 'Add xxxxx level Attributes' link if all mandatory attributes are set or if there aren't any mandatory attributes. A cross is displayed if there are mandatory attributes that need to be set.

Running a report for a KeyFamily

When you click on the 'Run' icon (looks like a green play button) for a specific KeyFamily they will see the following:

This takes you to a page where you can run the report that backs this KeyFamily. You will see a few different parameter that you must enter:

  • Start Date - This is the start date for the period you would like to report on.

  • End Date - This is the end date for the period you would like to report on.

  • Location - The OpenMRS location that you would like to report on.

  • Output format - The output format that you would like to repot in. Select SDMXHDCrossSectionalReportRender to export the report in the SDMX-HD Cross Sectional DataSet format. You may export the report in other formats to view the data that will be exported in a more readable fashion.

NB: If the reporting frequency is set to either 'Monthly' or 'Annual' then the report will only run if the reporting dates correspond to a entire month or year.

<< Back to SDMX-HD Integration module