dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #06397
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 208: Adding mobile documentation recevied from Bjornar
Merge authors:
Jason Pickering <jason@karolina-laptop>
------------------------------------------------------------
revno: 208 [merge]
committer: Jason Pickering <jason@karolina-laptop>
branch nick: dhis2-docbook-docs
timestamp: Wed 2010-06-23 14:02:14 +0200
message:
Adding mobile documentation recevied from Bjornar
added:
src/docbkx/en/dhis2_user_man_mobile.xml
modified:
src/docbkx/en/dhis2_documentation_guide.xml
src/docbkx/en/dhis2_user_man_reporting.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
=== modified file 'src/docbkx/en/dhis2_documentation_guide.xml'
--- src/docbkx/en/dhis2_documentation_guide.xml 2010-05-13 08:58:47 +0000
+++ src/docbkx/en/dhis2_documentation_guide.xml 2010-06-23 11:54:50 +0000
@@ -1,16 +1,14 @@
<?xml version='1.0' encoding='UTF-8'?>
-<!-- This document was created with Syntext Serna Free. --><!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; [
+<!-- This document was created with Syntext Serna Free. -->
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; [
<!ENTITY br ''>]>
<chapter>
- <chapterinfo>
- <title>DHIS 2 Documentation Guide</title>
- <author>
+ <chapterinfo><title>DHIS 2 Documentation Guide</title><author>
<firstname>Jason</firstname>
<surname>Pickering</surname>
<affiliation>
<orgname/>
- </affiliation>
- </author>
+ </affiliation></author>
<pubdate>14/09/09</pubdate>
<keywordset>
<keyword>DHIS2</keyword>
@@ -23,17 +21,14 @@
<date>28/10/09</date>
<revdescription>
<para> Added some more information on multilingual documents and editors.</para>
- </revdescription>
- </revision>
+ </revdescription></revision>
<revision>
<revnumber>1</revnumber>
<date>29/09/09</date>
<revdescription>
<para>Added more information on getting started with bzr and DocBook</para>
- </revdescription>
- </revision>
- </revhistory>
- </chapterinfo>
+ </revdescription></revision>
+ </revhistory></chapterinfo>
<title>DHIS2 Documentation Guide</title>
<section id="docs_1">
<title>DHIS 2 Documentation System Overview</title>
@@ -61,13 +56,15 @@
application itself. Therefore, there are wide range of possibilities in terms of which editor
can be used for the creation of DocBook files. A fairly complete list of possibilities is
located <ulink url="http://wiki.docbook.org/topic/DocBookAuthoringTools";>here</ulink>. It is
- currently recommended to use <ulink url="http://www.syntext.com/products/serna-free/ ">Syntext Serna Free</ulink> for editing DocBook source files as WYSIWYG. It is not recommended to use
+ currently recommended to use <ulink url="http://www.syntext.com/products/serna-free/ ">Syntext
+ Serna Free</ulink> for editing DocBook source files as WYSIWYG. It is not recommended to use
the editor XMLmind XML Editor Personal Edition (also known as XXE Personal), as the editor
"silently" places unneeded whitespace and other ornamentation to the DocBook source
which makes collaborative editing of documents very difficult. </para>
<para>One of the key concepts to keep in mind when authoring documentation in DocBook, or other
presentation neutral formats, is that the <emphasis role="bold">content </emphasis>of the
- document should be considered in the first instance. The <emphasis role="bold">presentation </emphasis>of the document will take place in a separate step, where it will be rendered into
+ document should be considered in the first instance. The <emphasis role="bold">presentation
+ </emphasis>of the document will take place in a separate step, where it will be rendered into
different formats, such as HTML and PDF. It is therefore important that the document is will
organised and structured, with appropriate DocBook tags and structural elements being
considered.</para>
@@ -83,7 +80,8 @@
</section>
<section id="docs_3">
<title>Getting started with Launchpad</title>
- <para>Currently, the documentation system is part of the source code housed at <ulink url="https://launchpad.net/";>Launchpad</ulink>. Launchpad is a collaborative platform that
+ <para>Currently, the documentation system is part of the source code housed at <ulink
+ url="https://launchpad.net/";>Launchpad</ulink>. Launchpad is a collaborative platform that
enables multiple people to work on software projects collaboratively. In order for this to be
possible, a version control system is necessary in order to manage all the changes that
multiple users may make. Launchpad uses the <emphasis>Bazaar</emphasis> source control system.
@@ -94,7 +92,9 @@
<para> In order to start adding or editing the documentation, you should first perform a
checkout of the source code. If you do not already have a Launchpad login id, you will need to
get one. This can be done <ulink url="https://launchpad.net/+login";>here</ulink>. Once you
- register with Launchpad, you will need to request access to the<emphasis> dhis2-documenters</emphasis> group. Login to Launchpad, and then request access <ulink url="https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs";>here</ulink>.
+ register with Launchpad, you will need to request access to the<emphasis>
+ dhis2-documenters</emphasis> group. Login to Launchpad, and then request access <ulink
+ url="https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs";>here</ulink>.
Your request will need to be approved by the group administrators. Once you have been granted
access to the group, you can commit changes to the documentation branch and send and receive
emails on the groups' list. </para>
@@ -105,7 +105,9 @@
documentation to your computer. Launchpad uses a version control system known as bzr . There
are different methods for getting Bazaar working on your system, depending on which operating
system you are using. A good step-by-step guide for <productname>Microsoft</productname>
- operating systems can be viewed <ulink url="http://wiki.showmedo.com/index.php/Using_Launchpad_and_Bazaar#Steps_to_download_a_project_on_Launchpad_that_uses_Bazaar_with_only_one_branch";>here</ulink>. If you are using Linux, you will need to install bzr on your system through
+ operating systems can be viewed <ulink
+ url="http://wiki.showmedo.com/index.php/Using_Launchpad_and_Bazaar#Steps_to_download_a_project_on_Launchpad_that_uses_Bazaar_with_only_one_branch";
+ >here</ulink>. If you are using Linux, you will need to install bzr on your system through
your package manager, or from source code.</para>
<para>Once you have installed bzr on your system, you will need to download the document source.
Just follow this procedure:</para>
@@ -114,14 +116,19 @@
<para>Make sure you have Bazaar installed.</para>
</listitem>
<listitem>
- <para>Start Bazaar by right-clicking a folder if you are using <productname>Windows</productname> and selecting <command>Bzr Here</command>. If you use Linux, you
+ <para>Start Bazaar by right-clicking a folder if you are using <productname
+ >Windows</productname> and selecting <command>Bzr Here</command>. If you use Linux, you
can just create a folder to hold the document sources. You can place the document source
in any folder you like.</para>
</listitem>
<listitem>
- <para>To download the latest revision of the DHIS2 documents project type: <command>bzr branch http://bazaar.launchpad.net/%7Edhis2-documenters/dhis2/dhis2-docbook-docs</command> if
+ <para>To download the latest revision of the DHIS2 documents project type: <command>bzr
+ branch
+ http://bazaar.launchpad.net/%7Edhis2-documenters/dhis2/dhis2-docbook-docs</command> if
you are using Linux, or alternatively if you are using <productname>Windows</productname>
- type the url to the source code repository "<ulink url="https://bazaar.launchpad.net/%7Edhis2-documenters/dhis2/dhis2-docbook-docs";>http://bazaar.launchpad.net/%7Edhis2-documenters/dhis2/dhis2-docbook-docs</ulink>"</para>
+ type the url to the source code repository "<ulink
+ url="https://bazaar.launchpad.net/%7Edhis2-documenters/dhis2/dhis2-docbook-docs";
+ >http://bazaar.launchpad.net/%7Edhis2-documenters/dhis2/dhis2-docbook-docs</ulink>"</para>
</listitem>
<listitem>
<para>The download process should start and all the documentation source files will be
@@ -129,25 +136,16 @@
</listitem>
</orderedlist>
</section>
- <section>
- <title>Creating a new document with Serna Free</title>
- <para>Serna Free is an intuitive XML editor with a user friendly user interface. Once you have downloaded the documentation source, you can begin to add your own documents or create new documents. To create a new document with Serna, choose Document->New Document and then Choose the "Docbook 4.4" document type. Ensure that you use this exact document type, as it is currently the only one that is supported by the rendering engine that will be used to transform the Docbook XML source into other formats, such as HTML and PDF. Save the document in the corresponding language folder in the source code tree. For instane, if you are creating English documents, save the new file in the <filename>/dhis2-docbook-docs/src/docbkx/en</filename> directory. </para>
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="resources/images/documentation/create_new_document_serna.png" width="60%" align="center" format="PNG"/>
- </imageobject>
- </mediaobject>
- </screenshot>
- <para>If you are creating main sections in the documentation choose "Chapter" as the template type. If you are creating an appendix, choose "Article". This is simply necessary to conform to the Docbook schema. Otherwise the documents template types are essentially the same.</para>
- </section>
<section id="docs_5">
<title>Editing the documentation</title>
<para>Once you have downloaded the source, you should have a series of folders inside of the
- dhis2-docbook-docs directory. All documents should be placed in the <filename>dhis2-docbook-docs/src/docbkx/XX</filename> folder. Note that the <filename>XX</filename>
+ dhis2-docbook-docs directory. All documents should be placed in the <filename
+ >dhis2-docbook-docs/src/docbkx/XX</filename> folder. Note that the <filename>XX</filename>
represents the ISO 639-1 (two-letter) language code of the documentation. If you are
- developing English language documentation, place it inside the <filename>/dhis2-docbook-docs/src/docbkx/en/</filename> folder. Place any image files that may be
- linked to your document in the <filename>/dhis2-docbook-docs/src/docbkx/XX/resources/images</filename> folder and link these inside
+ developing English language documentation, place it inside the <filename
+ >/dhis2-docbook-docs/src/docbkx/en/</filename> folder. Place any image files that may be
+ linked to your document in the <filename
+ >/dhis2-docbook-docs/src/docbkx/XX/resources/images</filename> folder and link these inside
your DocBook document using a relative file link. When the documentation is built, in a
separate step, the images will be automatically copied over to the correct directory during
the build process.</para>
@@ -218,7 +216,8 @@
<title>Handling multilingual documentation</title>
<para>The directory structure of the documentation has been created in order to facilitate the
creation of documents in any language. If you want to create a new set of documents in a given
- language, simply create a new directory in the <filename>dhis2-docbook-docs/src/docbkx/</filename> directory. Be sure to use the ISO 639-1 code for
+ language, simply create a new directory in the <filename
+ >dhis2-docbook-docs/src/docbkx/</filename> directory. Be sure to use the ISO 639-1 code for
the language you are going to create documents in. A complete list of these codes can be found
<ulink url="http://en.wikipedia.org/wiki/ISO_639-1";>here</ulink>. Add a new folder for
images in a sub-directory , replacing XX with the actual ISO 639-1 code for the language you
@@ -239,8 +238,11 @@
<section>
<title>Building the documentation with Apache maven</title>
<para>In order to transform the documentation source files to different formats, such as HTML
- or PDF, you will need to install the Apache Maven program. You can get a copy <ulink url="http://maven.apache.org/download.html";>here</ulink> or by installing it through your
- package manager if you are using Linux. Just execute the command <command>mvn clean package</command> on Windows or on Linux from the <filename>/dhis2-docbook-docs </filename>directory. Maven will start to download the necessary components to transform the
+ or PDF, you will need to install the Apache Maven program. You can get a copy <ulink
+ url="http://maven.apache.org/download.html";>here</ulink> or by installing it through your
+ package manager if you are using Linux. Just execute the command <command>mvn clean
+ package</command> on Windows or on Linux from the <filename>/dhis2-docbook-docs
+ </filename>directory. Maven will start to download the necessary components to transform the
documents into HMTL and PDF. Once the process has completed (be patient the first time, as
there are a number of components that must be downloaded), all of the target document types
will be generated in the /<filename>dhis2-docbook-docs/target/docbkx</filename> directory.
@@ -254,7 +256,9 @@
can be found <ulink url="http://cyberelk.net/tim/software/xmlto/";>here</ulink>. If you do
not want to use Apache Maven for some reason, you can install <command>xmlto</command>
through your package manager. Once you have installed <command>xmlto</command> you can just
- execute <command>xmlto <parameter>html</parameter><parameter>file_to_transform</parameter></command> where the <parameter>file_to_transform</parameter> parameter is the name of the file you wish to transform.
+ execute <command>xmlto <parameter>html</parameter><parameter
+ >file_to_transform</parameter></command> where the <parameter
+ >file_to_transform</parameter> parameter is the name of the file you wish to transform.
There are many other formats available, such as PDF, PS, JavaHelp and others. </para>
</section>
</section>
@@ -268,11 +272,14 @@
of your new files, you will need to commit them to your local branch with the following
command:</para>
<blockquote>
- <para><command>bzr commit -m "Created Amharic translation of documentation"</command></para>
+ <para><command>bzr commit -m "Created Amharic translation of
+ documentation"</command></para>
</blockquote>
<para>Just add an informative message of what you have done. Once you have committed changes to
your local branch, you can push them to the master branch with the following command: <blockquote>
- <para><command>bzr push bzr+ssh://bazaar.launchpad.net/%7Edhis2-documenters/dhis2/dhis2-docbook-docs </command></para>
+ <para><command>bzr push
+ bzr+ssh://bazaar.launchpad.net/%7Edhis2-documenters/dhis2/dhis2-docbook-docs
+ </command></para>
</blockquote></para>
<para>If you have any questions, or cannot find that you can get started, just send an email
with your problem to <email>dhis2-documenters@xxxxxxxxxxxxxxxxxxx</email>.</para>
=== added file 'src/docbkx/en/dhis2_user_man_mobile.xml'
--- src/docbkx/en/dhis2_user_man_mobile.xml 1970-01-01 00:00:00 +0000
+++ src/docbkx/en/dhis2_user_man_mobile.xml 2010-06-23 11:54:50 +0000
@@ -0,0 +1,192 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!-- This document was created with Syntext Serna Free. -->
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; []>
+<chapter>
+ <title>DHIS Mobile</title>
+ <section>
+ <title>Briefly how DHIS Mobile works</title>
+ <para>Wherever DHIS 2 is installed, a GSM modem holding a SIM card can be
+ installed on this computer. A mobile application (often referred to as DHIS Mobile)
+ needs to be installed on java enabled cell phones. This application lets the
+ users register data. When registration is finished, the users can use the
+ application to send the (encrypted) data, using SMS technology, to the
+ SIM card installed in the GSM modem. Once the SMS is received by the GSM modem,
+ the DHIS 2 software will automatically store the received data in the
+ database on the computer.</para>
+ </section>
+ <section>
+ <title>Set up a computer to receive DHIS Mobile SMSs</title>
+ <section>
+ <title>You need</title>
+ <para>- DHIS2 2.0.4(/2.0.5) source code <ulink url="https://code.launchpad.net/~dhis2-devs-core/dhis2/2.0.4";>
+ https://code.launchpad.net/~dhis2-devs-core/dhis2/2.0.4</ulink> (or prebuilt .war-file of DHIS2 2.0.4(/2.0.5) containing the mobile module)</para>
+ <para>- Various files:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Driver for the GSM modem</para>
+ </listitem>
+ <listitem>
+ <para>comm.jar</para>
+ </listitem>
+ <listitem>
+ <para>javax.comm.properties</para>
+ </listitem>
+ <listitem>
+ <para>win32com.dll</para>
+ </listitem>
+ <listitem>
+ <para>formIDLayout.csv</para>
+ </listitem>
+ <listitem>
+ <para>SMSserver.conf</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Steps</title>
+ <section>
+ <title>Build DHIS2 2.0.4</title>
+ <para>Download the latest source code from launchpad. From the dhis-mobile
+ folder, copy the dhis-service-mobile folder to the dhis-services folder
+ and the dhis-web-mobile folder to the dhis-web folder. Then modify the
+ following pom.xml files:</para>
+ <itemizedlist>
+ <listitem>
+ <para>in dhis-web-portal\pom.xml, add dependency to dhis-web-mobile:
+ <screen>
+<dependency>
+ <groupId>org.hisp.dhis</groupId>
+ <artifactId>dhis-web-mobile</artifactId>
+ <version>${version}</version>
+ <type>war</type>
+</dependency>
+ </screen>
+ </para>
+ </listitem>
+ <listitem>
+ <para>in dhis-web\pom.xml, add module dhis-web-mobile:
+ <screen><module>dhis-web-mobile</module></screen>
+ </para>
+ </listitem>
+ <listitem>
+ <para>in dhis-services\pom.xml, add module dhis-service-mobile:
+ <screen><module>dhis-service-mobile</module></screen>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>After the pom-files are altered, build your .war-file using
+ <code>mvn clean install</code>. (To skip the tests, use
+ <code>mvn clean install -Dtest=false -DfailIfNoTests=false</code>.)</para>
+ <para>Copy the dhis.war file from dhis-web-portal\target to the
+ tomcat\webapps folder. Rename it if you want.</para>
+ </section>
+
+ <section>
+ <title>Install the GSM modem</title>
+ <para>Plug in your modem and install the drivers. You might have to use the manufacturer's provided drivers from a CD or their web page.</para>
+ <para><emphasis>You might need administrator privileges to do this. If you still can't do it, try starting Windows in Safe Mode.</emphasis></para>
+ </section>
+
+ <section>
+ <title>Files needed</title>
+ <itemizedlist>
+ <listitem>
+ <para>comm.jar</para>
+ <para>Copy it to your <code>java\jreX\lib\ext</code> folder. If you've got multiple
+ installations of JRE, you can find the path to the installation used by
+ DHIS 2 by right clicking the Monitor Tomcat icon in the system tray,
+ then Configure -> Java.</para>
+ </listitem>
+ <listitem>
+ <para>javax.comm.properties</para>
+ <para>Copy it to your <code>java\jreX\lib</code> folder.</para>
+ </listitem>
+ <listitem>
+ <para>win32com.dll</para>
+ <para>Copy it to your <code>java\jreX\bin</code> folder.</para>
+ <para><emphasis>Note: You might need administrator privileges to do this.
+ If you still can't do it, try starting Windows in Safe Mode.</emphasis></para>
+ </listitem>
+ <listitem>
+ <para>SMSserver.conf</para>
+ <para>Copy it to your <code>DHIS2_HOME</code> folder (the folder where hibernate.properties is located). The settings in this file can also be modified from the Settings page in the mobile module in DHIS 2.</para>
+ <para>In this file the manufacturer and the model of the GSM modem are specified. Also, make sure the PIN code for the SIM card in the GSM modem is turned off, and set <code>modem1.pin=0000</code> in the SMSserver.conf, or use the Settings page in the mobile module in DHIS 2 to set the pin to 0000.</para>
+ <para>The port of the modem also needs to be specified in this file. After the drivers are successfully installed and the modem is installed in a usb port, you can find the port of the modem by opening Device Manager, locate your modem and right click on it, click on Properties and navigate to the Modem tab. There you'll see which port is assigned to the modem.</para>
+ <para><emphasis>Important: Note that if you install the modem into another usb port another time, the port will change, and you will have to update the settings. If you for some reason need to take the modem out of your computer, make sure you'll install it in the same usb port as last time, or else you'll have to update the SMSserver.conf file.</emphasis></para>
+ </listitem>
+ <listitem>
+ <para>formIDLayout.csv</para>
+ <para>Copy it to your <code>DHIS2_HOME\mi</code> folder. If you have not yet deployed your latest build of DHIS2, you'll have to create the mi folder manually.</para>
+ <para>This file specifies which data elements are to be imported. There's one line for each different mobile application in use. The lines start with a mobile application's id, then followed by comma separated data element ids and their categoryoptioncombo ids. The lines will be on the form
+ <screen>
+1 = <data element id>.<categoryoptioncombo id>,
+<data element id>.<categoryoptioncombo id>, ... ,
+<data element id>.<categoryoptioncombo id>
+ </screen>
+ E.g.
+ <screen>1 = 652.207, 652,208, 20485.271, 20485.272, 683.14</screen>
+ </para>
+ <para><emphasis>Note: If the same mobile application is installed on several phones, the �id� for each application is the same! The formIDLayout.csv file should thus only have one line, starting with 1 = .</emphasis></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Register users</title>
+ <para>The phone numbers of the cell phones used for reporting with the
+ mobile application needs to be registered in DHIS 2 in order for the data
+ to be imported and stored in the database. A phone number has to be
+ registered for a user, and the user can <emphasis>only</emphasis> be
+ associated with <emphasis>one organisation unit</emphasis>!</para>
+ <para>The phone number must include the regular phone number as well as
+ the country code without <code>+</code> or <code>00</code>. E.g. for a
+ Norwegian number, having the country code <code>47</code> and phone number
+ <code>98765432</code>, the phone number to store is <code>4798765432</code>.</para>
+ </section>
+
+ </section>
+</section>
+
+ <section>
+ <title>Install the mobile application on a phone</title>
+ <para>If you've got a phone and a computer with Bluetooth, you will in the most cases be able to send the <code>.jar</code> file (the mobile application) via Bluetooth from the computer to the phone. When using a cable, and also in some cases for phones with Bluetooth, you might have to install some software to be able to communicate with the phone. E.g. Nokia PC Suite for Nokia phones.</para>
+ <para>Once the mobile application is installed on the phone, open it and navigate to the last page in the application. Select settings, and enter the number of the SIM card in the GSM modem. This works both with and without country code.</para>
+ <para>If there are several GSM modems installed on several computers running DHIS 2 and you want to report to all of these, you can enter the numbers of the SIM cards installed in these GSM modems as well in the remaining fields in your mobile application. When clicking send, the application will now send the registered data to all the registered numbers at the same time.</para>
+ </section>
+
+ <section>
+ <title>Using the system</title>
+ <para>Navigate to the Mobile module via Services -> Mobiles</para>
+ <section>
+ <title>Start the SMS Service</title>
+ <para>To start the SMS Service, navigate to "Receive Data and Import" or
+ "Send SMS" in the left menu, and then press the Start button next to where
+ it says: "SMS Service: Not Started". If everything works well, it should
+ now say: "SMS Service: Started".</para>
+ </section>
+ <section>
+ <title>Receive Data and Import</title>
+ <para>To receive and import data, the SMS Service needs to be started. </para>
+ <section>
+ <title>Automated import of messages</title>
+ <para>When SMSs are sent from the phones while the SMS Service is running, the messages will be processed automatically, and the data will automatically be imported and stored in the database.</para>
+ </section>
+ <section>
+ <title>Import pending messages</title>
+ <para>If SMSs are sent from the phones to the SIM card in the GSM modem
+ while the SMS Service is inactive, the messages will be stored as xml
+ files in the folder <code>DHIS2_HOME\mi\pending</code> short time after
+ the service is started. On the Receive Data and Import page it will say
+ how many SMSs are pending. These can be imported by pressing the "Import
+ All Pending" button.</para>
+ </section>
+ </section>
+ <section>
+ <title>Send SMS</title>
+ <para>The mobile module can be used to send messages to one number at a
+ time. To send an SMS, the SMS Service needs to be started. Use the local
+ phone number here <emphasis>without</emphasis> the country code.</para>
+ </section>
+
+ </section>
+</chapter>
=== modified file 'src/docbkx/en/dhis2_user_man_reporting.xml'
--- src/docbkx/en/dhis2_user_man_reporting.xml 2010-05-13 08:58:47 +0000
+++ src/docbkx/en/dhis2_user_man_reporting.xml 2010-06-23 11:54:50 +0000
@@ -1,4 +1,4 @@
-<?xml version='1.0' encoding='UTF-8'?>
+<?xml version='1.0' encoding='UTF-8'?>
<!-- This document was created with Syntext Serna Free. --><!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; []>
<chapter>
<title>Reporting</title>
@@ -97,80 +97,16 @@
<section>
<title>Reports</title>
<para>The reporting module in DHIS 2 provides a range of reporting alternatives, including canned reports using either JasperReports or BIRT, data set reports, charts, pivot tables and report tables.</para>
- <section>
- <title>The DHIS2 datamart</title>
- <para>he purpose of the datamart is to provide pre-processed data to external data analysis and reporting tools. The datamart consists of two tables, <classname>aggregateddatavalues</classname> and <classname>aggregatedindicatorvalues</classname> in the DHIS2 database. The values in the datamart are aggregated versions of the raw data found in the datavalue table as well as calculated indicator values. Aggregation can take place over time (e.g. from monthly data to aggregated quarterly values), or place (e.g. from PHU data to aggregated district totals) and the datamart can store all kinds of such aggregated values. The datamart is as such just a processed "copy" of the data values and it can be emptied and regenerated at any time from the underlying raw data. The datamart is a read-only table, and should be used by reports (such as BIRT) and other analytical tools (such as Excel) for further ad-hoc analyis or presentation. The metadata in the two data mart tables are referenced by internal identifiers, such as <varname>dataelementid</varname>, <varname>organisationunitid</varname> which refer to the tables like <classname>dataelement</classname> and <classname>organisationunit</classname>. See the section 'How to make use of the data mart in external tools' for more on this. How the data is aggregated and what ends up in these two tables is controlled from the Data mart export user interface under the Services submenu.
-
-</para>
- <section>
- <title>The datamart export process</title>
- <para>The datamart export process is defined in the user interface and controls what kind of data that is populated in the data mart tables. Data mart exports are defined as a set of selection boxes where the user can select which data elements, indicators, orgunits and periods to export.
-</para>
- <section>
- <title>How to create a data mart export </title>
- <para>In the Datamart management window click on the Add New button and a Generate data mart window will open. There are 4 selection boxes; Data elements, Indicators, Organisation units, and periods. For each of the boxes select what you want to export, note if you don't want both data elements and indicators, you can leave one of these empty, but at least on of these need some selected items together with selected orgunits and periods. The available list on the left side can be filtered by data element group, indicator group, organisation unit level, and period type accordingly. You can move items across to the selected list by double clicking on an item in the available list or by selecting an item and use the move buttons (see selection button explanations below).
-
-When you are done selecting you can export to data mart by clicking on the Export button. If you want to keep your selections for later you can give it a name in the Name text box at the bottom of the window and click on Save. See more about saved data mart exports below.
-
-</para>
- <para>Each of the selection buttons function will now be described.</para>
- <itemizedlist>
- <listitem>
- <para>> Pressing this icon will move the selected item across form the available list on the left to the selected list on the right</para>
- </listitem>
- <listitem>
- <para>>> Pressing this icon will move all items in the available list across to the selected list</para>
- </listitem>
- <listitem>
- <para>>>> This icon is only applicable when moving orgunits from the available list to the selected list. This operation will move all children organizational units from the available list, to the selected list. </para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Datamart organizational units</title>
- <para>The datamart can include values aggregated to different levels in the same table and exactly which level a value belongs to is described by the 'level' column. When pulling data put of the datamart into external tools it is important to be aware of this level as combining data for different levels will result in duplication.
-
-For DHIS 1.4 users this means that there is no longer a separate table per level, but instead on a common table and a level column that separates the levels. Unlike DHIS 1.4, in DHIS 2 you specify in individual data element and indicator definitions specific orgunit levels the datamart should export to. In DHIS2 this is only defined in the datamart export window. In DHIS2, the export process is thus completely decoupled from the data element and indicator definitions and up to any user to define which orgunits (at any level) they want to see aggregated data for.
-</para>
- <para>Which orgunits that get exported to datamart (the two tables agggregateddatavalue and aggregatedindicatorvalue) are <emphasis>only</emphasis> controlled through the datamart export window, and there you define this per orgunit, not per orgunit level. There is a filter using orgunit level, but the orgunits that are selected are the only ones that end up in the datamart. Same for data elements and indicators.
-
-</para>
- <para>Every time you do a datamart export you can change which orgunits to export data for. The data values will automatically be aggregated up to the orgunit that is selected, no matter what level.
-</para>
- </section>
- <section>
- <title>Datamart periods</title>
- <para>The datamart can hold values aggregated to different period types or frequencies, e.g. monthly, quarterly or yearly data. The <varname>periodtypeid</varname> field refers to the frequency the value belongs to, and the <varname>periodid</varname> column refers to the exact period. These columns are always referenced to the <classname>periodtype</classname> and <classname>period</classname> table respectively. With these tables, queries can be constructed to display the name of the <classname>periodtype</classname> and <classname>period</classname> to the user. As an example, a particular <varname>periodtypeid </varname> might refernece a particular <classname>periodtype</classname> with a <varname>name </varname>property equal to 'Monthly'. The <varname>periodid</varname> property can be used then to determine a particular period from the database. Note that DHIS2 only stores the <varname>startdate</varname> and <varname>enddate</varname> for a particular period, so you may need to format the date to display a value, such as 'Jan 2009'. Be careful in combining values with different periodtypes as this may cause duplication in subsequent ad-hoc analysis.
-
-
-</para>
- </section>
- <section>
- <title>Data element categories in the datamart</title>
- <para>Each data value for a data element has a reference to a category option combo, which is a combination of the disaggregations for the data value, e.g. (male,<5y) or (In PHU, <1y). These disaggregations are exported as they are to the data mart, and no further aggregation is done on this dimension. See the data elements section for more on data element categories and the resource tables section for more information on how to perform automatic aggregation on these categories.
-</para>
- </section>
- <section>
- <title>Limitation on the number of data elements</title>
- <para>Due to the limitation in number of columns per table in the database, there is a limit to how many data elements that can be selected for each data mart export. If you are using the Postgresql database system, this limit you will need to select no more than 255 data elements per data mart export. If you need to export more than this number of data elements, you have to split it up into multiple data mart exports and run them one by one.
-</para>
- </section>
- <section>
- <title>Adding new data to an existing data mart </title>
- <para>When you add new data to an existing data mart, the new values will be appended to the existing values already present in the datamart, so that the datamart grows for each new process if new selections (such as new periods) have been made. If any of the selected values are already in the data mart then the old will be replaced by the newly generated values. If data updates have been made to values that are used to generate the aggregate values in the datamart, these values will be updated.
-</para>
- </section>
- </section>
- </section>
<section id="reportTable">
<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>
- <para>When a report table is created and generated, a new database table will appear in the DHIS 2 database as a normal table, but always with the prefix <classname>_report</classname>. 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 accessed 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>
+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>
<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. Being 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).
+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>
<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.
@@ -184,99 +120,6 @@
<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.
</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>
- <section>
- <title>Report table features</title>
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">Crosstab dimensions</emphasis></para>
- <para>Report tables can be generated with cone or more of the following cross-tabulation dimensions: data element/indicator, orgunit, and period. This implies that columns will be created based on the values of the dimensions chosen. For example, if "Indicator" is selected as the crosstab dimension, a column name will be generated for each indicator present in the report table. You must select at least one dimension for the table to be valid. Selecting all three dimensions is possible, but makes little sense and is not reccomended.</para>
- </listitem>
- <listitem>
- <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>
- </listitem>
- <listitem role="bold">
- <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>
- </listitem>
- <listitem>
- <para><emphasis role="bold">Organisation units </emphasis></para>
- <para>Here you can either select static orgunits to always include in the report, or to keep this section empty and let the users select orgunits when running the report through the use of report parameters. See the section below for a decscription of report paramaters.
-</para>
- </listitem>
- <listitem>
- <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 opt for relative periods in stead.
-</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">Relative periods</emphasis></para>
- <para>In stead of using fixed/static periods like 'Jan-2010' or 'Q1-2010' more generic periods can be used to create reusable report tables. For monthly reports the period 'reporting month' will simply pick the current reporting month selected by the user when running the report. A description of each of the supported relative periods is provided below.</para>
- <itemizedlist>
- <listitem>
- <para><emphasis>Reporting month:</emphasis>
-Use this for monthly reports. The month selected in the reporting month parameter will be used in the report.
-</para>
- </listitem>
- <listitem>
- <para><emphasis>Last 3/6/9/12 months:</emphasis> Relative to the selected reporting month the aggregated value for the previous 3,6,9,or 12 months will be used.</para>
- </listitem>
- <listitem>
- <para><emphasis>Last 3-6, 6-9, 9-12 months:</emphasis> Used for "rolling quarters" reports. Aggregated 3 months values will be used based on the selected reporting month. As an exmple, if July 2010 is selected the last 3-6 period will be an aggregated period of Feb-April 2010.
-</para>
- </listitem>
- <listitem>
- <para><emphasis>Last 12 individual months:</emphasis> Use this for monthly trend analysis. This will give 12 values, one for each of the 12 previous months relative to the chosen reporting month.
-</para>
- </listitem>
- <listitem>
- <para><emphasis>So far this year:</emphasis> This is the cumulative so far in the year, aggregating the months from the beginning of the year up to and including the selected reporting month.
-</para>
- </listitem>
- <listitem>
- <para><emphasis>So far this financial year:</emphasis> Similar to the above, but a cumulative value relative to start of the financial year to the selected reporting month.
-</para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- </section>
- </section>
- <section>
- <title>Reporting parameters </title>
- <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>
- <itemizedlist>
- <listitem>
- <para><emphasis>Reporting month</emphasis></para>
- <para>This paramater will determing which fixed periods that will be fetched for chosen relative periods.
-</para>
- </listitem>
- <listitem>
- <para><emphasis>Parent organisation unit</emphasis></para>
- <para>Select the parent of all the orgunit children you want listed in the report. For instance, a selected district will result in all sub-districts being present in the report.
-
-</para>
- </listitem>
- <listitem>
- <para><emphasis>Organisation unit</emphasis></para>
- <para>This triggers the use of this orgunit in the report. No dependent organizational units will be listed in the report.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Report table limitations</title>
- <para>Due to limitations of the number of columns that a given table can have in the database, the number of cross-tab columns for a report table is limited to the maximum number of columns that your DHIS2 database system supports. Postgresql supports approximately 250 columns per report table. You will therefore need to select fewer than 250 crosstab elements for any given report table.</para>
- <para>Currently, there are restrictions on the use of views that are linked to a given report table. If you create your own database views that link to a report table, the DHIS2 system will not be able to delete the report table, and an error messages will result. You should monitor the list of announcments on the DHIS2 development page for more information on this limitation.</para>
- </section>
</section>
<section>
<title>BIRT reports</title>
@@ -286,12 +129,7 @@
</section>
<section>
<title>Design the report in BIRT</title>
- <para>In order to run a BIRT report, you must 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). A step-by-step guide of this process will be detailed in the following sections.</para>
- <section>
- <title>Preparing the JDBC connectors</title>
- <para>JDBC, or Java Data Connectivity, are client-side adapters that provide connectivity between a Java application (DHIS2) and a database system (e.g. Postgresql, MySQL, H2). To connect to the DHIS2 database from BIRT (both when designing and viewing reports) a jdbc connection is needed, and for this you will need an appropriate JDBC driver for your database server (e.g. PostgreSQL or MySQL).
-</para>
- </section>
+ <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</para>
</section>
<section>
<title>Define and run the report in DHIS</title>
=== modified file 'src/docbkx/en/dhis2_user_manual_en.xml'
--- src/docbkx/en/dhis2_user_manual_en.xml 2010-04-23 05:21:31 +0000
+++ src/docbkx/en/dhis2_user_manual_en.xml 2010-06-23 11:54:50 +0000
@@ -34,6 +34,7 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_user_man_reporting.xml" encoding="UTF-8"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_user_man_gis.xml" encoding="UTF-8"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_user_man_excel_reports.xml" encoding="UTF-8"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_user_man_mobile.xml" encoding="UTF-8"/>
<appendix>
<title> DHIS Documentation Guide</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_documentation_guide.xml" encoding="UTF-8" xpointer="docs_1"/>
