dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #12688
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 358: Updated section on creating report tables
------------------------------------------------------------
revno: 358
committer: op.registrering@xxxxxx
branch nick: dhis2-docbook-docs
timestamp: Sun 2011-06-19 22:17:01 +0000
message:
Updated section on creating report tables
added:
src/docbkx/en/resources/images/dhis2_creating_reporting/catcombo.jpg
src/docbkx/en/resources/images/dhis2_creating_reporting/general_options.jpg
src/docbkx/en/resources/images/dhis2_creating_reporting/relative_options.jpg
src/docbkx/en/resources/images/dhis2_creating_reporting/select_data.jpg
modified:
src/docbkx/en/dhis2_user_man_creating_reporting.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
=== modified file 'src/docbkx/en/dhis2_user_man_creating_reporting.xml'
--- src/docbkx/en/dhis2_user_man_creating_reporting.xml 2011-06-19 18:26:24 +0000
+++ src/docbkx/en/dhis2_user_man_creating_reporting.xml 2011-06-19 22:17:01 +0000
@@ -198,17 +198,26 @@
<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 data mart 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 data mart, and to speed up the data processing and aggregation (small targeted data marts are obviously faster than big ones).
-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. DHIS 2 now suports reports created with Jaspersoft iReport Designer (up to v 2.0.6 DHIS 2 was integrated with the BIRT report designer from the Eclipse platform), and this makes it especially easy to link Jasper 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 Jasper 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>
- <para>A report table is a data source that can be defined once and then run automatically in the background when a report needs new and updated data. Standard reports are directly linked to one or more report tables and these are then automatically processed in the background when the report is run. Report parameters are added to the report tables to make these generic and reusable over time or across different orgunits. </para>
+</para>
+ <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. DHIS 2 now suports reports created with Jaspersoft iReport Designer (up to v 2.0.6 DHIS 2 was integrated with the BIRT report designer from the Eclipse platform), and this makes it especially easy to link Jasper 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 Jasper 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>
+ <para>A report table is a data source that can be defined once and then run automatically in the background when a report needs new and updated data. Standard reports are directly linked to a report table, which is then automatically processed in the background when the report is run. Report parameters are added to the report tables to make these generic and reusable over time or across different orgunits. </para>
</section>
</section>
<section>
<title>How to create report tables</title>
- <para>To create a new report table, click on one of the four Add buttons in the top right corner on the 'Report Table' page (Services -> Reports -> Report Table).</para>
+ <para>To create a new report table, go to the Report tables section of the Reports module (Reports -> Report Table). Above the list of standard reports, use the "Add report table" or "Add Dataelement Dimension Table" buttons. A regular report table can be used to hold data on data elements, indicators or dataset completeness, while Dataelement dimension tables are used to include data element categories in report tables. Creating the tables are done in the same way, however, the only exception being when choosing data.</para>
+ <para>To create a report table, you start by making some general choices for the table, the most important of which is the crosstab dimension. Then, you choose what data elements, indicators, datasets or data element dimensions you want to report on. Finally, you make you options on reporting parameters relating to organisation units and time periods. Each of these steps are described in detail below.</para>
<section>
- <title>Data Element and Indicator tables</title>
- <para>These two tables types are very similar with the only difference being that one has data element values and the other indicator values.</para>
+ <title>General options</title>
+ <screenshot>
+ <screeninfo>Report table options</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="70%" fileref="resources/images/dhis2_creating_reporting/general_options.jpg" format="JPEG"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
<para><emphasis role="bold">Cross tab dimensions</emphasis></para>
<para>You can cross-tab one or more of the following dimensions: data element/indicator, orgunit, and period, which means that columns will be created based on the values of the dimensions chosen, e.g. if indicators is selected you will get column names in the table reflecting the names of the selected indicators. You must select at least 1 dimension for the table to be valid. Selecting all 3 is possible, but makes little sense.</para>
<para>
@@ -233,16 +242,46 @@
</imageobject>
</mediaobject>
</screenshot>
+ <para>Note that the options made here regarding crosstab dimentions may have consequences for what options are available when using the report table as a data source later, for example for standard reports.</para>
+ <para><emphasis role="bold">Sort order</emphasis></para>
+ <para>Affects the rightmost column in the table, allows you to choose to sort it low to high or high to low.</para>
+ <para><emphasis role="bold">Top limit</emphasis></para>
+ <para>Top limit allow you to set a maximum number of rows you want to include in the report table.</para>
<para><emphasis role="bold">Include regression</emphasis></para>
<para>This adds additional columns with regression values that can be included in the report design, e.g. in line charts.</para>
+ </section>
+ <section>
+ <title>Selecting data</title>
+ <screenshot>
+ <screeninfo>Data options</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="70%" fileref="resources/images/dhis2_creating_reporting/select_data.jpg" format="JPEG"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
<para><emphasis role="bold">Indicators/Data elements</emphasis></para>
- <para>Here you select the data elements/indicators that you want to include in the report. Use the group filter to more easily find what you are looking for and double click on the items you want to include.</para>
- <para><emphasis role="bold">Organisation Units</emphasis></para>
- <para>Here you can either choose some fixed/static orgunits to always include in the report, or you can leave this section empty and let the users select orgunits when running the report through the use of report parameters (see further down).</para>
- <para><emphasis role="bold">Periods</emphasis></para>
- <para>Here you can either choose fixed periods that you always want to include in the report or leave this section empty and choose relative periods in stead.</para>
+ <para>Here you select the data elements/indicators that you want to include in the report. Use the group filter to more easily find what you are looking for and double click on the items you want to include, or use the buttons to add/remove elements. You can have both data elements and indicators in the same report.</para>
+ <para><emphasis role="bold">Data sets</emphasis></para>
+ <para>Here you select the data sets that you want to include in the report. Including a data set will give you data on the data completeness of the given set, not data on its data elements. Double click on the items you want to include, or use the buttons. </para>
+ </section>
+ <section>
+ <title>Selecting report parameters</title>
+ <screenshot>
+ <screeninfo>Report parameter options</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="70%" fileref="resources/images/dhis2_creating_reporting/relative_options.jpg" format="JPEG"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ <para>There are two ways to select both what organisation units to include in a report, and what time periods should be included: relative, or fixed. Fixed organisation units and/or periods means that you select the units/periods to include in the report table when you create the report table. Using relative periods, you can select the time and/or units as parameters when the report table is populated, for example when running a standard report or creating a chart. A combination is also possible, for example to add some organisation units in the report permanently while letting the users choose additional. Report parameters is discussed below. In general, using fixed organisation units and/or time periods are an unnecessary restriction.</para>
+ <para><emphasis role="bold">Fixed Organisation Units</emphasis></para>
+ <para>To add fixed organisation units, click "Toggle fixed organisation units". A panel will appear where you can choose orgunits to always include in the report. If you leave it blank, the users select orgunits when running the report through the use of report parameters. Use the drop down menu to filter organisation units by level, double click or use the buttons to add/remove.</para>
+ <para><emphasis role="bold">Fixed Periods</emphasis></para>
+ <para>To add fixed periods, click "Toggle fixed organisation units". A panel will appear where you can choose periods to always include in the report. If you leave it blank, the users select periods when running the report through the use of report parameters. Use the drop down menu to choose period type (week, month, etc), the Prev and Next button to choose year, and double click or use the buttons to add/remove.</para>
<para><emphasis role="bold">Relative periods</emphasis></para>
- <para>Instead of using fixed/static periods like 'Jan-2010' or 'Q1-2010', more generic periods can be used to create reusable report tables, e.g. for monthly reports the period 'Reporting month' will simply pick the current reporting month selected by the user when running the report. Here is a description of the possible relative periods:
+ <para>Instead of using fixed/static periods like 'Jan-2010' or 'Q1-2010', more generic periods can be used to create reusable report tables, e.g. for monthly reports the period 'Reporting month' will simply pick the current reporting month selected by the user when running the report. Note that all relative periods are relative to a "reporting month". The reporting month is either selected by the users, otherwise the current month is used. Here is a description of the possible relative periods:
</para>
<itemizedlist>
@@ -273,16 +312,19 @@
</listitem>
</itemizedlist>
<para><emphasis role="bold">Example - relative periods</emphasis></para>
- <para>Let's say we have chosen three indicators: A, B and C, and we have also chosen to use the relative periods 'Reporting month' and 'This year' when we created the report table. When we're running the report table, we will be asked to select a reporting month. Now, if we choose May 2010, the report table will calculate the values for the three selected indicators for May 2010 (= the 'Reporting month') and the accumulated values for the three selected indicators so far in 2010 (= so far 'This year').</para>
+ <para>Let's say we have chosen three indicators: A, B and C, and we have also chosen to use the relative periods 'Reporting month' and 'This year' when we created the report table. If the reporting month (selected automatically or by the user) is for example May 2010, the report table will calculate the values for the three selected indicators for May 2010 (= the 'Reporting month') and the accumulated values for the three selected indicators so far in 2010 (= so far 'This year').</para>
<para>Thus, we will end up with six values for each of the organisation units: "Indicator A May 2010", "Indicator B May 2010" "Indicator C May 2010", "Indicator A so far in 2010", "Indicator B so far in 2010" and "Indicator C so far in 2010".</para>
<para><emphasis role="bold">Report parameters</emphasis></para>
- <para>Report parameters make the reports more generic and reusable over time and for different orgunits. These parameters will pop up when generating the report table or running a report based on the report table, and the users will select what they want to see in the report. There are three possible report parameters, and you can select to use none, 1, 2 or all 3 parameters.
-
-</para>
+ <para>Report parameters make the reports more generic and reusable over time and for different organisation units. These parameters will pop up when generating the report table or running a report based on the report table. The users will select what they want to see in the report. There are four possible report parameters, and you can select none, all, or any combination.</para>
<itemizedlist>
<listitem>
<para><emphasis role="italic">Reporting month:</emphasis> </para>
- <para>This decides which month that will be used, when the system is choosing the relative periods.
+ <para>This decides which month will be used when the system is choosing the relative periods. If the box it not checked, the user will not be asked for the reporting month when the report is generated - the current month will then be used.
+</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="italic">Grand parent organisation unit:</emphasis> </para>
+ <para>Select the grand parent of all the orgunit children and grand children you want listed in the report. E.g. a selected region will trigger the use of the region itself, all its district, and all their sub-districts.
</para>
</listitem>
<listitem>
@@ -303,29 +345,29 @@
</section>
<section>
<title>Data element dimension tables</title>
- <para>These tables enable the use of data element categories in report tables. One category combination per report. Subtotals and the total will also be included in the table, e.g. a gender(male,female)+EPI age(<1,>1 category combo would give the following columns:
+ <para>These tables enable the use of data element categories in report tables. There are two differences from regular report tables. The first is that it is not possible to select crosstab dimensions, as the columns will always be the disaggregations from the category combinations. The other is the actual choice of data. Only one category combination can be added per report, and only data elements from the same category combo can be selected. </para>
+ <para>Subtotals and the total will also be included in the table, e.g. a gender (male, female) + EPI age(<1, >1) category combo would give the following columns:
male+<1, male+>1, Female+<1, female+>1, male, female,<1, >1, total.
</para>
- <para>Only data elements from the same category combination can be included.
-
-</para>
- <para>All cross tab dimensions are disabled since the columns are the various disaggregations from the category combination.
-
-</para>
- <para>Orgunit, periods and parameters as in the data element/indicator tables.
+ <para><emphasis role="bold">Selecting data</emphasis></para>
+ <screenshot>
+ <screeninfo>Selecting category combinations</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="70%" fileref="resources/images/dhis2_creating_reporting/catcombo.jpg" format="JPEG"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ <para>Use the drop down menu to choose category combinations. The data elements using this category combination will be listed. Double click to add to the report, or use the buttons.
</para>
</section>
<section>
<title>Report table - best practices</title>
- <para>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 it can be mentioned 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. The ability 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 DHIS 2, the user must specify the values for the report tables that are linked to the report. First the report table is re-generated (deleted and re-created with updated data), and then the report is run (in the background, in Jasper report engine).
+ <para>To make the report tables reusable over time and across orgunits they can have \ parameters. Four types of parameters are allowed; orgunit, parent orgunit (for listing of orgunits in one area), grand parent orgunit and reporting month. As a side note it can be mentioned 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. The ability 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 DHIS 2, the user must specify the values for the report tables that are linked to the report. First the report table is re-generated (deleted and re-created with updated data), and then the report is run (in the background, in Jasper report engine).
</para>
- <para>Report tables can consist of either values related to data elements or indicators, and not a mix of the two. 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>
- <para>
-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.
-</para>
+ <para>Report tables can consist of values related to data elements, indicators or data completeness, which is related to completeness of reporting across orgunits for a given month. Completeness reports will be covered in a separate section.</para>
<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, either one specific orgunit or an orgunit parent (making itself and 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.</para>
<para><emphasis role="bold">Using relative periods</emphasis></para>
<para>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. Instead, if you want to design a monthly report, you should 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. 'Months this year', which would give you values for each month so far in the year. 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 might be added to the report table options.</para>
@@ -916,7 +958,7 @@
<para>By default, a 3D bar chart is included in the .jrxml file that is downloaded from DHIS 2. This is set up so that only data from the «parameter orgnisation unit» (often the parent or grand parent) is used. Usually, this is a good solution. Since it is the default, we will start by looking at bar charts, before looking at line charts.</para>
<section>
<title>Bar charts</title>
- <screenshot>
+ <screenshot>
<screeninfo>Example bar chart</screeninfo>
<mediaobject>
<imageobject>
@@ -978,7 +1020,6 @@
</imageobject>
</mediaobject>
</screenshot>
-
<para>As the expression, we chose organisationunitname, as shown below.</para>
<screenshot>
<screeninfo>Choose organisation unit name.</screeninfo>
@@ -988,8 +1029,7 @@
</imageobject>
</mediaobject>
</screenshot>
-
- <para>When we are finished, the series editor should look like below. Click OK, then Close to close the Chart Details window.</para>
+ <para>When we are finished, the series editor should look like below. Click OK, then Close to close the Chart Details window.</para>
<screenshot>
<screeninfo>Series editor.</screeninfo>
<mediaobject>
@@ -998,7 +1038,6 @@
</imageobject>
</mediaobject>
</screenshot>
-
<para>If you add a good description in the Category expression area, you can leave out the legend box. This is done in the Report properties panel of iReport, where you can also edit many other details of the chart.</para>
<screenshot>
<screeninfo>Checkbox to show/hide chart legend</screeninfo>
@@ -1027,7 +1066,7 @@
</mediaobject>
</screenshot>
<para>The chart is now ready.</para>
- </section>
+ </section>
<section>
<title>Line charts</title>
<para>Line charts can be useful in many circumstances. However, to make line charts the report data (report table) must be suited for it. Thus if you want to make a line chart, it is important that the report table does not have periods in the crosstab dimension. Examples where this is useful is if you are making a report for a single organisation unit with one or more indicators, or if you are making a report with one indicator and one or more organisation units.</para>
@@ -1211,9 +1250,7 @@
</imageobject>
</mediaobject>
</screenshot>
- </section>-->
-
- <section>
+ </section>--> <section>
<title>Adding the Report to DHIS 2</title>
<para>We can now switch to DHIS 2 and import our report. Go to the Report Module in DHIS 2, and select "Standard Report". In the "Standard Report" screen, click "Add new", or edit an existing one.</para>
<para>In the following screen, there are several actions we need to take. First, enter a name for the new "Standard Report". Second, for design, click "Choose File" and find the .jrxml-file you have edited in iReport. Then we select the report table that we used as a basis for the report in iReport. Click add, and it should move to the "Selected report tables" area. Finally, click save.
=== added file 'src/docbkx/en/resources/images/dhis2_creating_reporting/catcombo.jpg'
Binary files src/docbkx/en/resources/images/dhis2_creating_reporting/catcombo.jpg 1970-01-01 00:00:00 +0000 and src/docbkx/en/resources/images/dhis2_creating_reporting/catcombo.jpg 2011-06-19 22:17:01 +0000 differ
=== added file 'src/docbkx/en/resources/images/dhis2_creating_reporting/general_options.jpg'
Binary files src/docbkx/en/resources/images/dhis2_creating_reporting/general_options.jpg 1970-01-01 00:00:00 +0000 and src/docbkx/en/resources/images/dhis2_creating_reporting/general_options.jpg 2011-06-19 22:17:01 +0000 differ
=== added file 'src/docbkx/en/resources/images/dhis2_creating_reporting/relative_options.jpg'
Binary files src/docbkx/en/resources/images/dhis2_creating_reporting/relative_options.jpg 1970-01-01 00:00:00 +0000 and src/docbkx/en/resources/images/dhis2_creating_reporting/relative_options.jpg 2011-06-19 22:17:01 +0000 differ
=== added file 'src/docbkx/en/resources/images/dhis2_creating_reporting/select_data.jpg'
Binary files src/docbkx/en/resources/images/dhis2_creating_reporting/select_data.jpg 1970-01-01 00:00:00 +0000 and src/docbkx/en/resources/images/dhis2_creating_reporting/select_data.jpg 2011-06-19 22:17:01 +0000 differ
