DHIS2 Implementation Guide

+ Packaging and installation +

+ "Building an installer is the last thing the developer does but the first thing the customer sees." + Will Iverson, strategic partner manager for Symantec's Internet Tools Division. +

+ Introduction + DHIS2 is a browser-based Java application, and will therefore run on essentially any operating system that support Java. The application has been architected to run both on stand-alone laptops as well as servers intended for multi-user enviornments discussed in the previous sections. Creating a single installer for all of these types of deployments is a major challenge and must be carefully considered when rolling out DHIS2 within a given organization. In this section, the packaging of DHIS2 based on the BitRock InstallBuilder will be considered. The source code for these installers is included in the /dhis2/dhis2-live-installer directory of the main source code. +

+ Building the installer + You will need a few extra components in order to build the BitRock installer. + + + A recent version of the Java SDK. + + + Download a copy of BitRock InstallBuilder 6 Multiplatform (Professional).. The install builder is available for multiple operating systems, so choose the one that is appropriate for you. The DHIS2 project has been granted a special liscense by BitRock for the use within the context of the project. Please send a note to the developers list if you want to build the installer, and a copy of the key required for the application will be sent to you. + + + Apache Maven 2 + + + If you are planning to build an embedded installer (described below), you will need a recent copy of the Java Runtime Environment (JRE). More specific details wil be provided in the section below. + + + Once you have downloaded and installed all the necessary components, you will need to make some changes to the environment variables that are defined in the build.sh script (or build.bat script if you are using Windows). + + + export JAVA_HOME=/usr/share/java/jdk1.6.0_19/ + This should point to the path where your local copy of the Java SDK exists. If this has been define else where on your system, you can comment this line out. + + + export PATH=$PATH:/home/jason/apache-maven-2.2.1/bin/ + This command will add the Apache Maven binary to the current path. If Maven is is accessible on the current enviornment, you can comment out this line. + + + export BITROCK_HOME=/home/jason/installbuilder-6.3.1/ + This command will define an enviornment variable which should point to the directory where the BitRock Installer Professional has been downloaded to. + + + export DHIS2_DOCS="/home/jason/dhis2/dhis2-docbook-docs/" + This environment variable will be used by the build script to automatically build the DHIS2 documentation and should point to the documentation source directory. + + + + +

Configuration

Organizational unit hierarchy === modified file 'src/docbkx/en/dhis2_user_man_mobile.xml' --- src/docbkx/en/dhis2_user_man_mobile.xml 2010-06-23 11:54:50 +0000 +++ src/docbkx/en/dhis2_user_man_mobile.xml 2010-07-15 09:15:30 +0000 @@ -1,192 +1,176 @@ - - - - - DHIS Mobile -

- Briefly how DHIS Mobile works - 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. -

- Set up a computer to receive DHIS Mobile SMSs -

- You need - - DHIS2 2.0.4(/2.0.5) source code - https://code.launchpad.net/~dhis2-devs-core/dhis2/2.0.4 (or prebuilt .war-file of DHIS2 2.0.4(/2.0.5) containing the mobile module) - - Various files: - - - Driver for the GSM modem - - - comm.jar - - - javax.comm.properties - - - win32com.dll - - - formIDLayout.csv - - - SMSserver.conf - - -

- Steps -

- Build DHIS2 2.0.4 - 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: - - - in dhis-web-portal\pom.xml, add dependency to dhis-web-mobile: - -<dependency> - <groupId>org.hisp.dhis</groupId> - <artifactId>dhis-web-mobile</artifactId> - <version>${version}</version> - <type>war</type> -</dependency> - - - - - in dhis-web\pom.xml, add module dhis-web-mobile: - <module>dhis-web-mobile</module> - - - - in dhis-services\pom.xml, add module dhis-service-mobile: - <module>dhis-service-mobile</module> - - - - After the pom-files are altered, build your .war-file using - mvn clean install. (To skip the tests, use - mvn clean install -Dtest=false -DfailIfNoTests=false.) - Copy the dhis.war file from dhis-web-portal\target to the - tomcat\webapps folder. Rename it if you want. -

- -

- Install the GSM modem - 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. - You might need administrator privileges to do this. If you still can't do it, try starting Windows in Safe Mode. -

- -

- Files needed - - - comm.jar - Copy it to your java\jreX\lib\ext 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. - - - javax.comm.properties - Copy it to your java\jreX\lib folder. - - - win32com.dll - Copy it to your java\jreX\bin folder. - Note: You might need administrator privileges to do this. - If you still can't do it, try starting Windows in Safe Mode. - - - SMSserver.conf - Copy it to your DHIS2_HOME 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. - 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 modem1.pin=0000 in the SMSserver.conf, or use the Settings page in the mobile module in DHIS 2 to set the pin to 0000. - 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. - 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. - - - formIDLayout.csv - Copy it to your DHIS2_HOME\mi folder. If you have not yet deployed your latest build of DHIS2, you'll have to create the mi folder manually. - 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 - -1 = <data element id>.<categoryoptioncombo id>, -<data element id>.<categoryoptioncombo id>, ... , -<data element id>.<categoryoptioncombo id> - - E.g. - 1 = 652.207, 652,208, 20485.271, 20485.272, 683.14 - - 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 = . - - -

- -

- Register users - 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 only be - associated with one organisation unit! - The phone number must include the regular phone number as well as - the country code without + or 00. E.g. for a - Norwegian number, having the country code 47 and phone number - 98765432, the phone number to store is 4798765432. -

- -

- Install the mobile application on a phone - If you've got a phone and a computer with Bluetooth, you will in the most cases be able to send the .jar 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. - 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. - 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. -

- -

- Using the system - Navigate to the Mobile module via Services -> Mobiles -

- Start the SMS Service - 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". -

- Receive Data and Import - To receive and import data, the SMS Service needs to be started. -

- Automated import of messages - 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. -

- Import pending messages - 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 DHIS2_HOME\mi\pending 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. -

- Send SMS - 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 without the country code. -

- -

- + + + + DHIS Mobile +

+ Introduction to DHIS Mobile + Collection of data in the field can be technically challenging and expensive. The DHIS2 Mobile module is meant to significantly reduce the complexity of deploying a distributed data collection system. A simple Java client can be installed on data collectors phones, who them send an SMS message to a central server. The SMS message is decrypted and converted imported into the DHIS2 database. +

+ Set up a computer to receive DHIS Mobile SMSs +

+ Pre-requisites + By default, DHIS2 does not ship with the DHIS Mobile web module. You will need to modify the client side application with your own data elements, as well as installing the DHIS2 mobile web module in the DHIS2 server. + - DHIS2 2.0.4(/2.0.5) source code https://code.launchpad.net/~dhis2-devs-core/dhis2/2.0.4 (or prebuilt .war-file of DHIS2 2.0.4(/2.0.5) containing the mobile module) + - Various files: + + + Driver for the GSM modem + + + comm.jar + + + javax.comm.properties + + + win32com.dll + + + formIDLayout.csv + + + SMSserver.conf + + +

+ Steps +

+ Build DHIS2 2.0.4 + 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: + + + in dhis-web-portal\pom.xml, add dependency to dhis-web-mobile: + +<dependency> + <groupId>org.hisp.dhis</groupId> + <artifactId>dhis-web-mobile</artifactId> + <version>${version}</version> + <type>war</type> +</dependency> + + + + + in dhis-web\pom.xml, add module dhis-web-mobile: + <module>dhis-web-mobile</module> + + + + in dhis-services\pom.xml, add module dhis-service-mobile: + <module>dhis-service-mobile</module> + + + + After the pom-files are altered, build your .war-file using + mvn clean install. (To skip the tests, use + mvn clean install -Dtest=false -DfailIfNoTests=false.) + Copy the dhis.war file from dhis-web-portal\target to the + tomcat\webapps folder. Rename it if you want. +

+ Install the GSM modem + 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. + You might need administrator privileges to do this. If you still can't do it, try starting Windows in Safe Mode. +

+ Files needed + + + comm.jar + Copy it to your java\jreX\lib\ext 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. + + + javax.comm.properties + Copy it to your java\jreX\lib folder. + + + win32com.dll + Copy it to your java\jreX\bin folder. + Note: You might need administrator privileges to do this. If you still can't do it, try starting Windows in Safe Mode. + + + SMSserver.conf + Copy it to your DHIS2_HOME 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. + 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 modem1.pin=0000 in the SMSserver.conf, or use the Settings page in the mobile module in DHIS 2 to set the pin to 0000. + 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. + 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. + + + formIDLayout.csv + Copy it to your DHIS2_HOME\mi folder. If you have not yet deployed your latest build of DHIS2, you'll have to create the mi folder manually. + 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 + +1 = <data element id>.<categoryoptioncombo id>, +<data element id>.<categoryoptioncombo id>, ... , +<data element id>.<categoryoptioncombo id> + + E.g. + 1 = 652.207, 652,208, 20485.271, 20485.272, 683.14 + + 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 = . + + +

+ Register users + 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 only be + associated with one organisation unit! + The phone number must include the regular phone number as well as + the country code without + or 00. E.g. for a + Norwegian number, having the country code 47 and phone number + 98765432, the phone number to store is 4798765432. +

+ Install the mobile application on a phone + If you've got a phone and a computer with Bluetooth, you will in the most cases be able to send the .jar 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. + 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. + 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. +

+ Using the system + Navigate to the Mobile module via Services -> Mobiles +

+ Start the SMS Service + 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". +

+ Receive Data and Import + To receive and import data, the SMS Service needs to be started. +

+ Automated import of messages + 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. +

+ Import pending messages + 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 DHIS2_HOME\mi\pending 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. +

+ Send SMS + 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 without the country code. +

+ === modified file 'src/docbkx/en/dhis2_user_man_reporting.xml' --- src/docbkx/en/dhis2_user_man_reporting.xml 2010-06-23 11:54:50 +0000 +++ src/docbkx/en/dhis2_user_man_reporting.xml 2010-07-15 09:15:30 +0000 @@ -1,4 +1,4 @@ - + Reporting @@ -48,27 +48,28 @@

Dimensions of aggregation

- Orgunits and levels - + Organisational units and levels + Organisational units are used to represent the "where" dimension associated with data values. In DHIS2, organisational units are arranged in a hierarchy, which typically corresponds to the hierarchical nature of the organisation or country. Organisational unit levels correspond to the distinct levels within the hierarchy. For instance, a country maybe organized into provinces, then districts, then facilities, and then sub-centers. This organisational hierarchy would have five levels. Within each level, a number of organisational units would exist. During the aggregation process, data is aggregated from the lower organisational unit levels to higher levels. Depending on the aggregation operator, data may be "summed" or "averaged" within a given organisational unit level, to derive the aggregate total for all the organisational units that are contained within a higher level organisational unit level. For instance, if there are ten districts contained in a province and the aggregation operator for a given data element has been defined as "SUM", the aggregate total for the province would be calculated as the sum of the values of the individual ten distrincts contained in that province.

Period - + Periods are used to represent the "when" dimension associated with data values. Data can easily be aggregated from weeks to months, from months to quarters, and from quarters to years. DHIS2 uses known rules of how these different intervals are contained within other intervals (for instance Quarter 1 2010 is known to contain January 2010, February 2010 an March 2010) in order to aggregate data from smaller time intervals, e.g. weeks, into longer time intervals, e.g. months.

- Data Element Categories - + Data Elements and Categories + The data element dimension specifies "what" is being recorded by a particular data value. Data element categories are actually degenerate dimensions of the data element dimension, and are used to disaggregate the data element dimension into finer categories. Data element categories, such as "Age" and "Gender", are used to record a particular data element, typically for differen population groups. These categories can then be used to calculate the overall total for the category and the total of all categories.

Aggregation operators, methods for aggregation

Sum - + The "sum" operator simply calcuates the sum of all data values that are contained within a particular aggregation matrix. For instance, if data is recorded on a monthly basis at the district level and is aggregated to provincial quarterly totals, all data contained in all districts for a given province and all weeks for the given quarter will be added together to obtained the aggregate total.

Average - + When the average aggregation operator is selected, the unweighted average of all data values within a given aggregation matrix. + It is important to understand how DHIS2 treats null values in the context of the average operator. It is fairly common for some organisational units not to submit data for certain data elements. In the context of the average operator, the average results from the number of data elemements that are actually present (therefore NOT NULL) within a given aggregation matrix. If there are 12 districts within a given province, but only 10 of these have submitted data, the average aggreate will result from these ten values that are actually present in the database, and will not take into account the missing values.

Count @@ -133,7 +134,7 @@

Define and run the report in DHIS - (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 the 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. + 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: generate the report with new data or run report with existing data. This all depends on whether your report table has already been populated and contains the most recent data from the database. It is important to keep in mind that the data present in a report table is not automatically refreshed when new data has been imported into the database. It is therefore important to ensure that your report table is up to date, especially in multi-user enviornments when data updates may have been affected by other users. 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 the 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 than DHIS2.