Not sure what exactly was the magic trick, Jason, but I’m happy to report that building the documentation now seems to work from behind the proxy using “mvn clean package”.
Knut
···
On Tue, Dec 8, 2009 at 7:18 PM, noreply@launchpad.net wrote:
revno: 61
committer: Jason Pickering jason@jason-laptop
branch nick: dhis2-docbook-docs
timestamp: Tue 2009-12-08 20:15:27 +0200
message:
Morphed aggregation document into a chapter and added to main document. Deleted build scripts as they are no longer necessary and added a readme file instead.
removed:
build.bat
build.sh
added:
readme.txt
modified:
pom.xml
src/docbkx/en/dhis2_user_man_mod1.xml
src/docbkx/en/dhis2_user_man_mod11.xml
src/docbkx/en/dhis2_user_manual_en.xml
–
lp:~dhis2-documenters/dhis2/dhis2-docbook-docs
https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs
Your team DHIS 2 developers is subscribed to branch lp:~dhis2-documenters/dhis2/dhis2-docbook-docs.
To unsubscribe from this branch go to https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs/+edit-subscription.
=== removed file ‘build.bat’
— build.bat 2009-10-21 00:08:51 +0000
+++ build.bat 1970-01-01 00:00:00 +0000
@@ -1,4 +0,0 @@
-echo “Building HTML files”
-mvn clean docbkx:generate-html
-echo “Building PDF files”
-mvn clean docbkx:generate-pdf
=== removed file ‘build.sh’
— build.sh 2009-11-24 17:36:04 +0000
+++ build.sh 1970-01-01 00:00:00 +0000
@@ -1,13 +0,0 @@
-#!/bin/bash
-echo “Building HTML files”
-myargs=$1
-if [ “$1” = “clean” ]
-then
-mvn clean docbkx:generate-html
-echo “Building PDF files”
-mvn clean docbkx:generate-pdf
-else
-mvn docbkx:generate-html
-echo “Building PDF files”
-mvn docbkx:generate-pdf
-fi
=== modified file ‘pom.xml’
— pom.xml 2009-12-04 07:31:44 +0000
+++ pom.xml 2009-12-08 18:15:27 +0000
@@ -41,14 +41,9 @@
<sourceDirectory>${basedir}/src/docbkx/en/</sourceDirectory> <xincludeSupported>true</xincludeSupported> <includes>*.xml</includes>-
<name>glossary.collection</name>
<!--<htmlStylesheet>resources/css/docbook_bsd.css</htmlStylesheet>--><htmlCustomization>${basedir}/src/docbkx/en/resources/xsl/docbook-fo.xsl</htmlCustomization>-${basedir}/src/docbkx/en/resources/glossary/glossary_en.xml
<htmlStylesheet>resources/css/docbook_bsd.css</htmlStylesheet> <postProcess> <copy todir="target/site/en">=== added file ‘readme.txt’
— readme.txt 1970-01-01 00:00:00 +0000
+++ readme.txt 2009-12-08 18:15:27 +0000
@@ -0,0 +1,9 @@
+This is the DHIS2 documentation project.
+To build the documents, consult the DHIS2 documentation guide for details.
+Otherwise, just execute
+mvn package
=== modified file ‘src/docbkx/en/dhis2_user_man_mod1.xml’
— src/docbkx/en/dhis2_user_man_mod1.xml 2009-12-04 07:31:44 +0000
+++ src/docbkx/en/dhis2_user_man_mod1.xml 2009-12-08 18:15:27 +0000
@@ -1,4 +1,5 @@
<?xml version='1.0' encoding='UTF-8'?>+
@@ -33,8 +34,7 @@
HMIS</para> </listitem> <listitem>
<para>What is the difference between patient based and aggregatedata.</para>
<para>What is the difference between patient based and <glossterm baseform="aggregate data">aggregate data</glossterm>.</para> </listitem> <listitem> <para>What are the different modules in DHIS 2.</para>=== modified file ‘src/docbkx/en/dhis2_user_man_mod11.xml’
— src/docbkx/en/dhis2_user_man_mod11.xml 2009-11-21 17:50:00 +0000
+++ src/docbkx/en/dhis2_user_man_mod11.xml 2009-12-08 18:15:27 +0000
@@ -1,143 +1,144 @@
-<?xml version='1.0' encoding='UTF-8'?>
-
-
-
- Aggregation and reporting
<firstname>Ola</firstname><surname>Titlestad</surname><affiliation><orgname>HISP</orgname></affiliation>2009-11-14
- An overview of how aggregation takes place and rules of the system
-In the bigger picture of HIS terminology all data in DHIS are usually called aggregated as they are aggregates (e.g. monthly summaries) of medical records or some kind of service regiters reported from the health facilities. Aggregation inside DHIS however, which is the topic here, is concerned with how the raw data captured in DHIS (through data entry or import)are further aggregated over time (e.g. from monthly to quarterly values) or up the organisational hierarchy (e.g. from facility to district values).
-
<title>Terminology</title><itemizedlist><listitem><para><emphasis>Raw data</emphasis> refers to data that is registered into the DHIS 2 either through data entry or data import, and has not been manipulated by the DHIS aggregation process. All these data are stored in the table (or Java object if you prefer) called DataValue.</listitem><listitem><para><emphasis>Aggregated data</emphasis>refers to data that has been aggregated by the DHIS2, meaning it is no longer raw data, but some kind of aggregate of the raw data.</para></listitem><listitem><para><emphasis>Indicator values</emphasis> can also be understood as aggregated data, but these are special in the way that they are calculated based on user defined formulas (factor * numerator/denominator). Indicator values are therefore processed data and not raw data, and are located in the aggregatedindicatorvalue table/object. Indicators are calculated at any level of the organisational hierarchy and these calculations are then based on the aggregated data values available at each level. A level attribute in the aggregateddatavalue table refers to the organisational level of the orgunit the value has been calculated for.</listitem><listitem><para>Period and Period type are used to specify the time dimension of the raw or aggregated values, and data can be aggregated from one period type to another, e.g from monthly to quarterly, or daily to monthly. Each data value has one period and that period has one period type. E.g data values for the periods Jan, Feb, and Mar 2009, all of the monthly period type can be aggregated together to an aggregated data value with the period “Q1 2009” and period type “Quarterly”.
</listitem></itemizedlist><title>Basic rules of aggregation</title><sect3><title>What is added together</title><para>Data (raw) can be registered at any organisational level, e.g. at at national hospital at level 2, a health facility at level 5, or at a bigger PHC at level 4. This varies form country to country, but DHIS is flexible in allowing data entry or data import to take place at any level. This means that orgunits that themselves have children can register data, sometimes the same data elements as their children units. The basic rule of aggregation in DHIS 2 is that <emphasis>all raw data is aggregated together</emphasis>, meaning data registered at a facility on level 5 is added to the data registered for a PHC at level 4.</para><para>-It is up to the user/system administrator/designer to make sure that no duplication of data entry is taking place and that e.g. data entered at level 4 are not about the same services/visits that are reported by orgunit children at level 5. NOTE that in some cases you want to have “duplication” of data in the system, but in a controlled manner. E.g. when you have two different sources of data for population estimates, both level 5 catchment population data and another population data source for level 4 based on census data (because sum of level 5 catchments is not always the same as level 4 census data). Then you can specify using advanced aggregation settings (see further down) that the system should e.g. not add level 5 population data to the level 4 population data, and that level 3,2,1 population data aggregates are only based on level 4 data and does not include level 5 pop data.
</sect3><sect3><title>How data gets added together</title><para>How data is aggregated depends on the dimension of aggregation (see further down).</para><para>Along the orgunit level dimension data is always summed up, simply added together. Note that raw data is never percentages, and therefore can be summed together. Indicator values that can be percentages are treated differently (re-calculated at each level, never summed up).</para><para>-Along the time dimension there are several possibilities, the two most common ways to aggregate are sum and average. The user can specify for each data element which method to use by setting the aggregation operator (see further down). Monthly service data are normally summed together over time, e.g. the number of vaccines given in a year is the sum of the vaccines given for each month of that year. For population, equipment, staff and other kind of what is often called semi-permanent data the average method is often the one to use, as, e.g. “number of nurses” working at a facility in a year would not be the sum of the two numbers reported in the six-monthly staffing report, but rather the average of the two numbers. More details further down under “aggregation operators”.
-
</sect3><title>Dimensions of aggregation</title><sect3><title>Orgunits and levels</title></sect3><sect3><title>Period</title></sect3><sect3><title>Data Element Categories</title></sect3><title>Aggregation operators, methods for aggregation</title><sect3><title>Sum</title></sect3><sect3><title>Average</title></sect3><sect3><title>Count</title></sect3><sect3><title>Where to specify </title></sect3><title>Advanced aggregation settings (aggregation levels)</title><sect3><title>Aggregation levels</title><para>The normal rule of the system is to aggregate all raw data together when moving up the organisational hierarchy, and the system assumes that data entry is not being duplicated by entering “the same services provided to the same clients” at both facility level and also entering an “aggregated” (sum of all facilities) number at a higher level. This is to more easily facilitate aggregation when the same services are provided but to different clients/catchment populations at facilities on level 5 and a PHC (the parent of the same facilities) at level 4. In this way a facility at level 5 and a PHC at level 4 can share the same data elements and simply add together their numbers to provide the total of services provided in the geographical area.</para><para>Sometimes such an aggregation is not desired, simply because it would mean duplicating data about the same population. This is the case when you have two different sources of data for two different orgunit levels. E.g. catchment population for facilities can come from a different source than district populations and therefore the sum of the facility catchment populations do not match the district population provided by e.g. census data. If this is the case we would actually want “duplicated” data in the system so that each level can have as accurate numbers as possible, but then we do NOT want to aggregate these data sources together.-
<para>In the Data Element section you can edit data elements and for each of them specify how aggregation is done for each level. In the case described above we need to tell the system NOT to include facility data on population in any of the aggregations above that level, as the level above, in this case the districts have registered their population directly as raw data. The district population data should then be used at all levels above and including the district level, while facility level should use its own data.</para></sect3><sect3><title>How to edit data element aggregation</title><para>This is controlled through something called aggregation levels and at the end of the edit data element screen there is a tick-box called Aggregation Levels. If you tick that one you will see a list of aggregation levels, available and selected. Default is to have no aggregation levels defined, then all raw data in the hierarchy will be added together. To specify the rule described above, and given a hierarchy of Country, Province, District, Facility: select Facility and District as your aggregation levels. Basically you select where you have data. Selecting Facility means that Facilities will use data from facilities (given since this is the lowest level). Selecting District means that the District level raw data will be used when aggregating data for District level (hence no aggregation will take place at that level), and the facility data will not be part of the aggregated District values. When aggregating data at Province level the District level raw data will be used since this is the highest available aggregation level selected. Also for Country level aggregates the District raw data will be used. Just to repeat, if we had not specified that District level was an aggregation level, then the facility data and district data would have been added together and caused duplicate (double) population data for districts and all levels above.</para></sect3>- Reports
<title>Report tables</title><para>-Report tables are meant to be database tables fulfilling the specific data needs of a report, chart, pivot table or other output format. It can be understood as a mini datamart that contains only the data needed for its purpose (the report). The rationale behind this concept is to automatically provide the data sources for reports without bothering the users every time, like a normal datamart, and to speed up the data processing and aggregation (small targeted datamarts are obviously faster than big ones).
-
<para>-When created and generated a report table will appear in the DHIS 2 database as a normal table, but always with the prefix _report. This table should not be altered manually as it is controlled by the system. These tables are constantly being deleted and recreated as the user wants new updated data within the same table structure. These tables can then be access and used from any third party tool for displaying data. In DHIS 2 we have integrated with the BIRT report designer from the Eclipse platform and made it especially easy to link BIRT reports to report tables and to run these reports from within DHIS 2. However, we see report tables as a much broader tool and concept than to just support BIRT reports. It can and should (for performance gain and automation) be used for as many data output purposes as possible. e.g. as data sources for the database views used for Excel pivot tables.
-
<para>-Report tables are meant to be defined once and then run automatically in the background each time a report that depends on it is generated. Reports (BIRT, the default report in DHIS 2) is directly linked to one or more report tables and these are automatically processed in the background when the report is run. To make the report tables reusable over time and across orgunits they can have parameters. Three types of parameters are allowed; orgunit, parent orgunit (for listing of orgunits in one area) and reporting month. As a side note I can mention that we are looking into expanding this to include reporting quarter and year, or to make that period parameter more generic with regard to period type somehow. Be able to use period as a parameter makes the report table reusable over time and as such fits nicely with report needs such as monthly, quarterly or annual reports. When a report is run by the user in the DHIS 2 the user must specify the values for the report tables that are linked to the report, and first the report table is re-generated (deleted and re-created with updated data) and then the report is run (in BIRT report engine).
-
<para>-Report tables can consist of either values related to data elements or indicators, and not a mix of the two. A third report table type is data completeness, which is related to completeness of reporting across orgunits for a given month. Completeness reports will be covered in a separate section. The reason for not mixing data elements and indicators in one report table is due to the cross tab functionality that would be very complex and less useful with yet another dimension. Since two or more report tables can easily be linked to one report this limitation should not have much effect on report design possibilities.
-
<para>-There are three dimensions in a report table that identify the data; indicators or data elements, orgunits and periods. For each of these dimensions the user can select which metadata values to include in the report. The user must select one or more data elements or indicators to appear in the report. The orgunit selection can be substituted with a parameter, wither one specific orgunit or an orgunit parent (making all its children appear in the report). If one or more orgunits are selected and no orgunit parameter is used then the report is static with regard to which orgunits to include, which in most cases is an unnecessary restriction to a report. The period selection is more advanced as it can in addition to specific periods like Jan-09, Q1-08, 2007 also contain what is called relative periods. As report usually is run routinely over time a specific period like Jan-09 is not very useful in a report. In stead, if you want to design a monthly report you could use the relative period called Reporting Month. Then you must also include Reporting Month as one of your report parameters to let the system know what exactly is the Reporting Month on the time of report generation. There are many other relative periods available and they all relate to the report parameter Reporting Month. E.g. the relative period called So far this year refers to the accumulative value for the year incl. the Reporting Month. If you want a trend report with multiple periods in stead of one aggregated period you can select e.g. Individual Months this year which would give you values for each month so far in the year, and you can do a similar report with quarters. The idea is to support as many generic report types as possible using relative periods, so if you have other report needs please suggest new relative periods on the mailing list and they will be added to the report table options.
-
<para>-Cross tabbing is a very powerful functionality in report design as the typical DHIS data table with references to period, data element/indicator and orgunit makes more advanced report design very difficult as you cannot put e.g. specific indicators, periods or orgunits on specific columns. E.g. by cross-tabbing on the indicator dimension in an indicator report table you will get the indicator names on the column headers in you report, in addition to a column referencing orgunit, and another column referencing period. With such a table design you could drag and drop indicator names to specific columns or chart positions in the BIRT report design. Similarly you can cross tab on orgunits or periods to make their names specifically available to report design. E.g. by cross-tabbing on periods and selecting the two relative periods, reporting month and so far this year you can design reports with both the last month and the accumulative annual value for given month as they will be available as column headers in your report table. It is also possible to combine two dimensions in cross-tabbing, e.g. period and indicator, which makes it possible to e.g. look at three selected indicators for two specific relative periods. This would e.g. make it possible to make a table or chart based report with BCG, DPT3 and Measles coverage, both for the last month and the accumulative coverage so far in the year.
-
<para>-All in all, by combining the functionality of cross tabbing, relative periods and report table parameters you should have a tool to support most report scenarios. If not we would be very happy to receive suggestions to further improvements to report tables. As already mentioned we have started to look at more fine-grained parameters for the period dimension as the Reporting Month does not cover or at least is not intuitive enough when it comes to e.g. quarterly reports.
-
<title>BIRT reports</title><sect3><title>Create a report table in DHIS 2</title><para>- create a report table in DHIS 2 is to create so-called report tables in DHIS, found under Reports module, which will serve as the data table for your report. Normally one table per report, but multiple tables for one report is also possible. A report table can be a cross tabulated table on any of the dimensions period/indicator/data element / orgunit, and also in combination, like “BCG < 1 coverage + last 3 months” and “BCG coverage < 1 year+ last month”. This cross-tabulation makes it a lot easier to control the design of the report which is then done with dragging and dropping column headings onto the report. The report table can also have report parameters like reporting month, organisation unit and organisation unit parent (if you are e.g. listing all sub-districts in a given district).</para></sect3><sect3><title>Design the report in BIRT</title><para>Then you design the report in the stand-alone BIRT designer (based on the Eclipse platform) and access the report table in the DHIS 2 database using a jdbc connection and an sql query (all using the BIRT user interface). When you have connected to the table and selected which columns to use they will be available as fields that you can drag and drop onto your report design. In BIRT you can preview the report at any point, and when you're done you can save the report as an xml file (.rptdesign). More instructions here: [http://208.76.222.114/confluence/display/HISP/Birt+designer%27s+notes](http://208.76.222.114/confluence/display/HISP/Birt+designer%27s+notes)</para></sect3><sect3><title>Define and run the report in DHIS</title><para>(the very first time you need to configure where the BIRT report viewer is installed, go to Reports→Report→Configure report) In DHIS 2 you can define a report in the Reports module that you link to a report table and provide with a name. Then the report is ready to be generated and displayed, and this can be done in two ways, 1) run report with new data or run report with existing data. This all depends on whether your report table is populated already or not. Most likely you will have to run it with new data and then you are asked to provide values for the report parameters (if defined in the report table) and then the table will be populated in teh background and a new window will show the report as soon as it is ready. The new window will actually be generated by the BIRT report viewer, which is a separate web application running on the same tomcat instance.</para></sect3>-
+<?xml version='1.0' encoding='UTF-8'?>
+
+
+
- Aggregation and reporting
<firstname>Ola</firstname><surname>Titlestad</surname><affiliation><orgname>HISP</orgname></affiliation>2009-11-14
- Aggregation and reporting
- An overview of how aggregation takes place and rules of the system
+In the bigger picture of HIS terminology all data in DHIS are usually called aggregated as they are aggregates (e.g. monthly summaries) of medical records or some kind of service regiters reported from the health facilities. Aggregation inside DHIS however, which is the topic here, is concerned with how the raw data captured in DHIS (through data entry or import)are further aggregated over time (e.g. from monthly to quarterly values) or up the organisational hierarchy (e.g. from facility to district values).
+
<title>Terminology</title><itemizedlist><listitem><para><emphasis>Raw data</emphasis> refers to data that is registered into the DHIS 2 either through data entry or data import, and has not been manipulated by the DHIS aggregation process. All these data are stored in the table (or Java object if you prefer) called DataValue.</listitem><listitem><para><emphasis>Aggregated data</emphasis>refers to data that has been aggregated by the DHIS2, meaning it is no longer raw data, but some kind of aggregate of the raw data.</para></listitem><listitem><para><emphasis>Indicator values</emphasis> can also be understood as aggregated data, but these are special in the way that they are calculated based on user defined formulas (factor * numerator/denominator). Indicator values are therefore processed data and not raw data, and are located in the aggregatedindicatorvalue table/object. Indicators are calculated at any level of the organisational hierarchy and these calculations are then based on the aggregated data values available at each level. A level attribute in the aggregateddatavalue table refers to the organisational level of the orgunit the value has been calculated for.</listitem><listitem><para>Period and Period type are used to specify the time dimension of the raw or aggregated values, and data can be aggregated from one period type to another, e.g from monthly to quarterly, or daily to monthly. Each data value has one period and that period has one period type. E.g data values for the periods Jan, Feb, and Mar 2009, all of the monthly period type can be aggregated together to an aggregated data value with the period “Q1 2009” and period type “Quarterly”.
</listitem></itemizedlist><title>Basic rules of aggregation</title><section><title>What is added together</title><para>Data (raw) can be registered at any organisational level, e.g. at at national hospital at level 2, a health facility at level 5, or at a bigger PHC at level 4. This varies form country to country, but DHIS is flexible in allowing data entry or data import to take place at any level. This means that orgunits that themselves have children can register data, sometimes the same data elements as their children units. The basic rule of aggregation in DHIS 2 is that <emphasis>all raw data is aggregated together</emphasis>, meaning data registered at a facility on level 5 is added to the data registered for a PHC at level 4.</para><para>+It is up to the user/system administrator/designer to make sure that no duplication of data entry is taking place and that e.g. data entered at level 4 are not about the same services/visits that are reported by orgunit children at level 5. NOTE that in some cases you want to have “duplication” of data in the system, but in a controlled manner. E.g. when you have two different sources of data for population estimates, both level 5 catchment population data and another population data source for level 4 based on census data (because sum of level 5 catchments is not always the same as level 4 census data). Then you can specify using advanced aggregation settings (see further down) that the system should e.g. not add level 5 population data to the level 4 population data, and that level 3,2,1 population data aggregates are only based on level 4 data and does not include level 5 pop data.
</section><section><title>How data gets added together</title><para>How data is aggregated depends on the dimension of aggregation (see further down).</para><para>Along the orgunit level dimension data is always summed up, simply added together. Note that raw data is never percentages, and therefore can be summed together. Indicator values that can be percentages are treated differently (re-calculated at each level, never summed up).</para><para>+Along the time dimension there are several possibilities, the two most common ways to aggregate are sum and average. The user can specify for each data element which method to use by setting the aggregation operator (see further down). Monthly service data are normally summed together over time, e.g. the number of vaccines given in a year is the sum of the vaccines given for each month of that year. For population, equipment, staff and other kind of what is often called semi-permanent data the average method is often the one to use, as, e.g. “number of nurses” working at a facility in a year would not be the sum of the two numbers reported in the six-monthly staffing report, but rather the average of the two numbers. More details further down under “aggregation operators”.
+
</section><title>Dimensions of aggregation</title><section><title>Orgunits and levels</title></section><section><title>Period</title></section><section><title>Data Element Categories</title></section><title>Aggregation operators, methods for aggregation</title><section><title>Sum</title></section><section><title>Average</title></section><section><title>Count</title></section><section><title>Where to specify </title></section><title>Advanced aggregation settings (aggregation levels)</title><section><title>Aggregation levels</title><para>The normal rule of the system is to aggregate all raw data together when moving up the organisational hierarchy, and the system assumes that data entry is not being duplicated by entering “the same services provided to the same clients” at both facility level and also entering an “aggregated” (sum of all facilities) number at a higher level. This is to more easily facilitate aggregation when the same services are provided but to different clients/catchment populations at facilities on level 5 and a PHC (the parent of the same facilities) at level 4. In this way a facility at level 5 and a PHC at level 4 can share the same data elements and simply add together their numbers to provide the total of services provided in the geographical area.</para><para>Sometimes such an aggregation is not desired, simply because it would mean duplicating data about the same population. This is the case when you have two different sources of data for two different orgunit levels. E.g. catchment population for facilities can come from a different source than district populations and therefore the sum of the facility catchment populations do not match the district population provided by e.g. census data. If this is the case we would actually want “duplicated” data in the system so that each level can have as accurate numbers as possible, but then we do NOT want to aggregate these data sources together.+
<para>In the Data Element section you can edit data elements and for each of them specify how aggregation is done for each level. In the case described above we need to tell the system NOT to include facility data on population in any of the aggregations above that level, as the level above, in this case the districts have registered their population directly as raw data. The district population data should then be used at all levels above and including the district level, while facility level should use its own data.</para></section><section><title>How to edit data element aggregation</title><para>This is controlled through something called aggregation levels and at the end of the edit data element screen there is a tick-box called Aggregation Levels. If you tick that one you will see a list of aggregation levels, available and selected. Default is to have no aggregation levels defined, then all raw data in the hierarchy will be added together. To specify the rule described above, and given a hierarchy of Country, Province, District, Facility: select Facility and District as your aggregation levels. Basically you select where you have data. Selecting Facility means that Facilities will use data from facilities (given since this is the lowest level). Selecting District means that the District level raw data will be used when aggregating data for District level (hence no aggregation will take place at that level), and the facility data will not be part of the aggregated District values. When aggregating data at Province level the District level raw data will be used since this is the highest available aggregation level selected. Also for Country level aggregates the District raw data will be used. Just to repeat, if we had not specified that District level was an aggregation level, then the facility data and district data would have been added together and caused duplicate (double) population data for districts and all levels above.</para></section>- Reports
<title>Report tables</title><para>+Report tables are meant to be database tables fulfilling the specific data needs of a report, chart, pivot table or other output format. It can be understood as a mini datamart that contains only the data needed for its purpose (the report). The rationale behind this concept is to automatically provide the data sources for reports without bothering the users every time, like a normal datamart, and to speed up the data processing and aggregation (small targeted datamarts are obviously faster than big ones).
+
<para>+When created and generated a report table will appear in the DHIS 2 database as a normal table, but always with the prefix _report. This table should not be altered manually as it is controlled by the system. These tables are constantly being deleted and recreated as the user wants new updated data within the same table structure. These tables can then be access and used from any third party tool for displaying data. In DHIS 2 we have integrated with the BIRT report designer from the Eclipse platform and made it especially easy to link BIRT reports to report tables and to run these reports from within DHIS 2. However, we see report tables as a much broader tool and concept than to just support BIRT reports. It can and should (for performance gain and automation) be used for as many data output purposes as possible. e.g. as data sources for the database views used for Excel pivot tables.
+
<para>+Report tables are meant to be defined once and then run automatically in the background each time a report that depends on it is generated. Reports (BIRT, the default report in DHIS 2) is directly linked to one or more report tables and these are automatically processed in the background when the report is run. To make the report tables reusable over time and across orgunits they can have parameters. Three types of parameters are allowed; orgunit, parent orgunit (for listing of orgunits in one area) and reporting month. As a side note I can mention that we are looking into expanding this to include reporting quarter and year, or to make that period parameter more generic with regard to period type somehow. Be able to use period as a parameter makes the report table reusable over time and as such fits nicely with report needs such as monthly, quarterly or annual reports. When a report is run by the user in the DHIS 2 the user must specify the values for the report tables that are linked to the report, and first the report table is re-generated (deleted and re-created with updated data) and then the report is run (in BIRT report engine).
+
<para>+Report tables can consist of either values related to data elements or indicators, and not a mix of the two. A third report table type is data completeness, which is related to completeness of reporting across orgunits for a given month. Completeness reports will be covered in a separate section. The reason for not mixing data elements and indicators in one report table is due to the cross tab functionality that would be very complex and less useful with yet another dimension. Since two or more report tables can easily be linked to one report this limitation should not have much effect on report design possibilities.
+
<para>+There are three dimensions in a report table that identify the data; indicators or data elements, orgunits and periods. For each of these dimensions the user can select which metadata values to include in the report. The user must select one or more data elements or indicators to appear in the report. The orgunit selection can be substituted with a parameter, wither one specific orgunit or an orgunit parent (making all its children appear in the report). If one or more orgunits are selected and no orgunit parameter is used then the report is static with regard to which orgunits to include, which in most cases is an unnecessary restriction to a report. The period selection is more advanced as it can in addition to specific periods like Jan-09, Q1-08, 2007 also contain what is called relative periods. As report usually is run routinely over time a specific period like Jan-09 is not very useful in a report. In stead, if you want to design a monthly report you could use the relative period called Reporting Month. Then you must also include Reporting Month as one of your report parameters to let the system know what exactly is the Reporting Month on the time of report generation. There are many other relative periods available and they all relate to the report parameter Reporting Month. E.g. the relative period called So far this year refers to the accumulative value for the year incl. the Reporting Month. If you want a trend report with multiple periods in stead of one aggregated period you can select e.g. Individual Months this year which would give you values for each month so far in the year, and you can do a similar report with quarters. The idea is to support as many generic report types as possible using relative periods, so if you have other report needs please suggest new relative periods on the mailing list and they will be added to the report table options.
+
<para>+Cross tabbing is a very powerful functionality in report design as the typical DHIS data table with references to period, data element/indicator and orgunit makes more advanced report design very difficult as you cannot put e.g. specific indicators, periods or orgunits on specific columns. E.g. by cross-tabbing on the indicator dimension in an indicator report table you will get the indicator names on the column headers in you report, in addition to a column referencing orgunit, and another column referencing period. With such a table design you could drag and drop indicator names to specific columns or chart positions in the BIRT report design. Similarly you can cross tab on orgunits or periods to make their names specifically available to report design. E.g. by cross-tabbing on periods and selecting the two relative periods, reporting month and so far this year you can design reports with both the last month and the accumulative annual value for given month as they will be available as column headers in your report table. It is also possible to combine two dimensions in cross-tabbing, e.g. period and indicator, which makes it possible to e.g. look at three selected indicators for two specific relative periods. This would e.g. make it possible to make a table or chart based report with BCG, DPT3 and Measles coverage, both for the last month and the accumulative coverage so far in the year.
+
<para>+All in all, by combining the functionality of cross tabbing, relative periods and report table parameters you should have a tool to support most report scenarios. If not we would be very happy to receive suggestions to further improvements to report tables. As already mentioned we have started to look at more fine-grained parameters for the period dimension as the Reporting Month does not cover or at least is not intuitive enough when it comes to e.g. quarterly reports.
+
<title>BIRT reports</title><section><title>Create a report table in DHIS 2</title><para>- create a report table in DHIS 2 is to create so-called report tables in DHIS, found under Reports module, which will serve as the data table for your report. Normally one table per report, but multiple tables for one report is also possible. A report table can be a cross tabulated table on any of the dimensions period/indicator/data element / orgunit, and also in combination, like “BCG < 1 coverage + last 3 months” and “BCG coverage < 1 year+ last month”. This cross-tabulation makes it a lot easier to control the design of the report which is then done with dragging and dropping column headings onto the report. The report table can also have report parameters like reporting month, organisation unit and organisation unit parent (if you are e.g. listing all sub-districts in a given district).</para></section><section><title>Design the report in BIRT</title><para>Then you design the report in the stand-alone BIRT designer (based on the Eclipse platform) and access the report table in the DHIS 2 database using a jdbc connection and an sql query (all using the BIRT user interface). When you have connected to the table and selected which columns to use they will be available as fields that you can drag and drop onto your report design. In BIRT you can preview the report at any point, and when you're done you can save the report as an xml file (.rptdesign). More instructions here: [http://208.76.222.114/confluence/display/HISP/Birt+designer%27s+notes](http://208.76.222.114/confluence/display/HISP/Birt+designer%27s+notes)</para></section><section><title>Define and run the report in DHIS</title><para>(the very first time you need to configure where the BIRT report viewer is installed, go to Reports→Report→Configure report) In DHIS 2 you can define a report in the Reports module that you link to a report table and provide with a name. Then the report is ready to be generated and displayed, and this can be done in two ways, 1) run report with new data or run report with existing data. This all depends on whether your report table is populated already or not. Most likely you will have to run it with new data and then you are asked to provide values for the report parameters (if defined in the report table) and then the table will be populated in teh background and a new window will show the report as soon as it is ready. The new window will actually be generated by the BIRT report viewer, which is a separate web application running on the same tomcat instance.</para></section>+
=== modified file ‘src/docbkx/en/dhis2_user_manual_en.xml’
— src/docbkx/en/dhis2_user_manual_en.xml 2009-12-04 07:31:44 +0000
+++ src/docbkx/en/dhis2_user_manual_en.xml 2009-12-08 18:15:27 +0000
@@ -5,6 +5,7 @@
<xi:include xmlns:xi="[http://www.w3.org/2001/XInclude](http://www.w3.org/2001/XInclude)" href="dhis2_user_man_mod1.xml" encoding="UTF-8"/> <xi:include xmlns:xi="[http://www.w3.org/2001/XInclude](http://www.w3.org/2001/XInclude)" href="dhis2_user_man_mod2.xml" encoding="UTF-8"/> <xi:include xmlns:xi="[http://www.w3.org/2001/XInclude](http://www.w3.org/2001/XInclude)" href="dhis2_user_man_mod3.xml" encoding="UTF-8"/>
- <xi:include xmlns:xi=“http://www.w3.org/2001/XInclude” href=“dhis2_user_man_mod11.xml” encoding=“UTF-8”/>
<title>DHIS2 GIS Module User Manual</title> <xi:include xmlns:xi="[http://www.w3.org/2001/XInclude](http://www.w3.org/2001/XInclude)" href="dhis2_gis_user_manual_en.xml" xpointer="gis_1" encoding="UTF-8"/>@@ -47,7 +48,7 @@
<xi:include xmlns:xi="[http://www.w3.org/2001/XInclude](http://www.w3.org/2001/XInclude)" href="dhis2_technical_architechture_guide.xml" xpointer="arch_7" encoding="UTF-8"/> <xi:include xmlns:xi="[http://www.w3.org/2001/XInclude](http://www.w3.org/2001/XInclude)" href="dhis2_technical_architechture_guide.xml" xpointer="arch_8" encoding="UTF-8"/>