dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #09518
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 234: Tried to clean up the mobile sms solution docs a wee bit.
------------------------------------------------------------
revno: 234
committer: Jo Størset <storset@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Wed 2011-01-12 15:59:17 +0530
message:
Tried to clean up the mobile sms solution docs a wee bit.
modified:
src/docbkx/en/dhis2_user_man_mobile.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_mobile.xml'
--- src/docbkx/en/dhis2_user_man_mobile.xml 2010-07-15 09:15:30 +0000
+++ src/docbkx/en/dhis2_user_man_mobile.xml 2011-01-12 10:29:17 +0000
@@ -3,174 +3,319 @@
<chapter>
<title>DHIS Mobile</title>
<section>
- <title>Introduction to DHIS Mobile </title>
- <para>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. </para>
- </section>
- <section>
- <title>Set up a computer to receive DHIS Mobile SMSs</title>
- <section>
- <title>Pre-requisites</title>
- <para>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. </para>
- <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>
+ <title>Introduction</title>
+ <para>Collection of data in the field can be technically
+ challenging and expensive. Mobile phone
+ solutions has the potential to
+ significantly reduce the complexity of deploying a distributed
+ data collection system. Using a simple Java client installed on
+ a mobile phone, field workers
+ can report directly to DHIS2 instance. </para>
+ <para>There are currently two
+ mobile solutions for DHIS2, an older SMS based solution and a new
+ solution relying on the phone having a data connection to the web (e.g. GPRS).</para>
+ </section>
+ <section>
+ <title>GPRS based solution</title>
+ <para>This solution is currently being developed, documentation
+ coming soon...
+ </para>
+ </section>
+
+ <section>
+ <title>SMS based solution</title>
+ <para>With the SMS solution, the forms filled in on the phone is
+ sent using SMS messages to a
+ central server. The SMS message is
+ decrypted and converted, and then imported into the DHIS2
+ database.</para>
+ <para>
+ By default, DHIS2 does not ship with the DHIS SMS Mobile web
+ module. <!-- The DHIS2 downloads site ( <ulink url="http://dhis2.org/downloads";>http://dhis2.org/downloads</ulink>
+ ) has a prebuilt version of the latest release with this module added. Otherwise y -->
+ You will need to build in these modules
+ yourself. You also need to modify the client side
+ application with your own data elements.
+ </para>
+ <section>
+ <title>Build DHIS2 with the dhis-web-mobile module</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Download the latest source code from
+ launchpad, i.e. the DHIS2 trunk source
+ code from
+ <ulink url="https://code.launchpad.net/~dhis2-devs-core/dhis2/trunk";>
+ https://code.launchpad.net/~dhis2-devs-core/dhis2/trunk</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Build
+ DHIS2 as normal, by running
+ <code>mvn clean install</code>
+ (to skip tests, use
+ <code>mvn clean install -Dtest=false
+ -DfailIfNoTests=false</code>
+ ) in the dhis-2 and
+ dhis-2\dhis-web folders.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Build the mobile modules by
+ running
+ <code>mvn clean install</code>
+ in the dhis-mobile folder.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Modify
+ the dhis-web-portal\pom.xml file, adding a dependency to dhis-web-mobile:
+ </para>
+ <para>
+ <screen>
+ <dependency>
+ <groupId>org.hisp.dhis</groupId>
+ <artifactId>dhis-web-mobile</artifactId>
+ <version>${version}</version>
+ <type>war</type>
+ </dependency> </screen>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Build the portal (
+ <code>mvn clean
+ install</code>
+ in the dhis-web-portal folder)
+ </para>
+ </listitem>
+ <listitem>
+ <para>Copy the dhis.war file from dhis-web-portal\target to the
+ tomcat\webapps folder.
+ Rename it if you
+ want.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Install the GSM modem</title>
<itemizedlist>
<listitem>
<para>Driver for the GSM modem</para>
+ <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.
+ <emphasis>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>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>
- </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
+ <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>
+ 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>
+ <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>
+ <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>
</section>
</chapter>
