dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #11864
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 307: Fixed validation error
------------------------------------------------------------
revno: 307
committer: Lars Helge Overland <larshelge@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Thu 2011-04-28 18:22:37 +0200
message:
Fixed validation error
modified:
src/docbkx/en/dhis2_user_man_getting_started.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_getting_started.xml'
--- src/docbkx/en/dhis2_user_man_getting_started.xml 2011-01-14 09:02:46 +0000
+++ src/docbkx/en/dhis2_user_man_getting_started.xml 2011-04-28 16:22:37 +0000
@@ -1,366 +1,366 @@
-<?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>Getting started with DHIS 2</title>
- <section id="mod2_1">
- <title>Getting started with DHIS2</title>
- <para>After reading this chapter you will be able to understand:</para>
- <itemizedlist>
- <listitem>
- <para>Start DHIS 2 from the desktop</para>
- </listitem>
- <listitem>
- <para>How to log-in from the desktop</para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>Create new users and user roles</para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>What steps are needed to design a DHIS 2 database for your organisation</para>
- </listitem>
- </itemizedlist>
- <section>
- <title>Prerequisites</title>
- <para>You must be sure that you have a current version of the Java Runtime installed on your machine. Depending on your operating system, there are different ways of installing Java. The reader is referred to this <ulink url="http://java.sun.com/javase/downloads/index.jsp";>website</ulink> for detailed information on getting java installed.</para>
- </section>
- <section>
- <title>Starting the DHIS2 Live package</title>
- <para>The DHIS2 Live package is the easiest way to get started with DHIS2. DHIS2 Live is appropriate for a stand-alone type of installation. Simply download the application from <ulink url="http://www.dhis2.org/downloads";>here</ulink>.
- Once the file is downloaded, you can simply double-click the downloaded file, and get started using DHIS2. </para>
- <section>
- <title>Starting up with a blank database</title>
- <para>The live package comes with a demo database just like what you see on the online demo (which is based on the national Sierra Leone HMIS), and if you want to start with a blank system/database and build up your own system then you need to do the following:
-
-</para>
- <para>1) Stop the DHIS2 live if it is already running. Right click on the tray icon and select Exit.
-The tray icon is the green symbol on the bottom right of your screen (on Windows) which should say' DHIS2 Server running' if you hold your mouse pointer over it.</para>
- <para>2) Open the folder where the DHIS2 live package is installed and locate the folder called "conf".
-</para>
- <para>3) In conf/ open the file called 'hibernate.properties' in a text editor (notepad or similar) and do the following modification:
-locate the string 'jdbc:h2:./database/dhis2' and replace the 'dhis2' part with any name that you want to give to your database (e.g. dhis2_test).</para>
- <para>4) Save and close the hibernate.properties file.
-</para>
- <para>5) Start DHIS2 live by double-clicking on the file dhis2-live.exe in the DHIS2 live installation folder or by using a desktop shortcut or menu link that you might have set up.
-</para>
- <para>6) Wait for the browser window to open and the login screen to show, and then log in with username: admin and password: district
-</para>
- <para>7) Now you will see a completely empty DHIS2 system and you should start by adding your users, organisational hierarchy, data elements, and datasets etc. Please refer to the other sections of the user manual for instructions on how to do this.
-</para>
- </section>
- </section>
- <section>
- <title>Working directly with the H2 database</title>
- <para>
- DHIS2 Live uses an embedded <ulink url="www.h2database.com/">H2</ulink> database. This has several advantages - there is no need
- to install a separate database engine such as PostgresSql or MySql, and backup can be made by just copying the file. The whole db
- exists in memory, which means high performance. The disadvantage is need for RAM. It is also not suitable for mulitiuser server
- installations.
- </para>
- <para>
- In general, it is recommended to work with the database through the DHIS2 user interface, but in some situations one may need to
- manipulate the data directly. If one downloads H2 separately, it comes with a web interface. It can also be manipulated using
- <ulink url="http://openoffice.org";>OpenOffice.org</ulink>, using the following procedure. This assumes that dhis2-live is located in
- the user's Linux home directory (represented by ~). Substitute the absolute path to your dhis2-live installation.
- <itemizedlist>
- <listitem>
- <para>Start OpenOffice Word Processor and select Tools - Options, then Java - Class Path ... and click on Add Archive...</para>
- </listitem>
- <listitem>
- <para>Select the following file (version may differ): ~/dhis2-live/webapps/dhis/WEB-INF/lib/h2-1.1.119.jar</para>
- </listitem>
- <listitem>
- <para>Close OpenOffice completely and then open OpenOffice.org Database. Select connect to an existing database - JDBC</para>
- </listitem>
- <listitem>
- <para>Datasource URL is h2:~/dhis2-live/database/dhis2;AUTO_SERVER=TRUE, and JDBC driver class is org.h2.Driver</para>
- </listitem>
- <listitem>
- <para>User name is sa, password not needed. Finally, select a name and folder for the .odb file.</para>
- </listitem>
- </itemizedlist>
- <ulink url="http://www.oooforum.org/forum/viewtopic.phtml?t=97522";>More tips</ulink>
-
- </para>
- </section>
- <section>
- <title>Downloading and installing the server version</title>
- <para>DHIS2 functions both as a
- desktop application, as well as a web-enabled client-server application.
- For larger, production installations with many users and large volumes
- of data (for instance as a national level server) it is recommended to
- install the server version. The latest version of the infrastructure can be
- found <ulink url="http://dhis.uio.no/ci/job/Dhis2%20Web%20Trunk/lastSuccessfulBuild/artifact/dhis-2/dhis-web/dhis-web-portal/target/dhis.war";>here</ulink>.
- </para>
- <para>There are many permutations of getting a server installation up and running, and will depend very much on the nature of the installation. A typical installation for a single machine, running Ubuntu Linux will be described in the discussion that follows. This type of single-installation would be appropriate for a small work-group. There are so many different ways to get the application running, and this will depend to a large extent on the number of users you will be catering to, the type of hardware you have available, and the nature of the implementation of the application (e.g one central server as opposed to multiple subnational installations). The example provided here is meant to be a rough guide for those that are setting up a DHIS2 server instance from scratch, however, you should consider all security requirements of your implementation before blindly following this example. </para>
- <para>You will need to decide which back-end database system you will use. DHIS2 is a database agnostic application in principle, and should run on any system with a compatible JDBC driver. However, it is recommended either to use Postgresql or MySQL, as these systems are widely used by other members of the DHIS2 community. In addition to a back-end database system, you will need a compatible servlet container. Apache Tomcat 6 is recommended by the developers, however in principle, the application should run in any container that conforms to the Servlet 2.5 specification. </para>
- <para>It is certainly possible to install all packages from source code, but it is suggested that you install most of the basic packages through your systems package manager. Depending on which version of Linux that you may be using, you may need to install a newer version of both the back-end database system (such as Postgresql and MySQL) and Servlet container. It is recommended to use at least Postgresl version 8.3 or MySQL 5.0. </para>
- <para>To get started downloading the necessary packages, execute the following commands. Note that you may need to add the <command>sudo</command> command before these commands, if you are not running as root. </para>
- <para><programlisting><userinput>apt-get install nano <userinput>wget nano /etc/apt/sources.list </userinput></userinput></programlisting></para>
- <para>Uncomment and add “multiverse†after “universe†in each line of this file. </para>
- <para>After editing the sources.list execute these commands. </para>
- <para><programlisting><userinput>apt-get update </userinput>
-<userinput>apt-get install sun-java6-jdk postgresql postgresql-client</userinput>
-<userinput>postgresql-contrib postgresql-8.3-postgis</userinput></programlisting></para>
- <para>This will install a number of packages on your system, including Java and the Postgresql database system. In principle, DHIS2 will run under any servlet container, but it is recommended to use Apache Tomcat. Check with the DHIS2 developers if you have questions about using other servlet containers. To get Tomcat, execute the following commands</para>
- <para><programlisting><userinput><userinput>wget http://apache.mirror.testserver.li/tomcat/tomcat-6/v6.0.20/bin/apache-tomcat-6.0.20.tar.gz</userinput> tar xvzf apache-tomcat-6.0.20.tar.gz mv apache-tomcat-6.0.20 /usr/local/tomcat</userinput></programlisting></para>
- <para>If you need plan on installing Geoserver as part of your DHIS2 installation, go ahead and download and install it. You should check on the <ulink url="http://www.geoserver.org";>Geoserver web page</ulink> for the latest version. </para>
- <para>
-
-<userinput>wget http://downloads.sourceforge.net/geoserver/geoserver-2.0.0a-war.zip</userinput></para>
- <para><userinput>unzip geoserver-2.0.0a-war.zip</userinput></para>
- <para>
-<userinput>unzip geoserver.war -d /usr/local/tomcat/webapps </userinput></para>
- <para>
-<userinput>mv /usr/local/tomcat/webapps/geoserver/data /usr/local/geodata</userinput></para>
- <para>You should now change the default Geoserver password to something more secure. Execute<userinput> nano /usr/local/geodata/security/users.properties </userinput>and change the password and then save all changes. </para>
- <para>Edit one of your persistent environment variables (see <ulink url="https://help.ubuntu.com/community/EnvironmentVariables#Persistent%20environment%20variables";>this page</ulink> for details). Add the following lines to the chosen file. </para>
- <para><envar>export JAVA_HOME=/usr/lib/jvm/java-6-sun</envar></para>
- <para><envar>export JDK_HOME= /usr/lib/jvm/java-6-sun</envar>
-</para>
- <para><envar>export JAVA_OPTS=-XX:PermSize=256m -XX:MaxPermSize=1536 -Xms512m -Xmx1024m -server</envar>
-</para>
- <para><envar>export GEOSERVER_DATA_DIR=/usr/local/geodata</envar>
-</para>
- <para><envar>export DHIS2_HOME=/root/dhis/dhis2</envar>
-</para>
- <para>Note that you may need to alter the file paths to point to the actual directories on your system. </para>
- <para>Assuming that you have installed the postgresql database system, you can create a new database with the following commands. </para>
- <para><userinput>sudo su - postgres</userinput></para>
- <para><userinput>createdb createdb -E utf-8 <parameter>dhis</parameter></userinput></para>
- <para>Note that you can change the name of the database to anything that suits your environment. </para>
- <para> To tell the DHIS2 application where to find its database you need a <filename>hibernate.properties</filename> file in <envar>DHIS2_HOME</envar> . For a postgres database connection to a database called 'dhis', with user name and password 'dhis', you need to put the following inside your file /root/dhis/dhis2/hibernate.properties: </para>
- <para><userinput>hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect</userinput></para>
- <para><userinput>hibernate.connection.driver_class = org.postgresql.Driver</userinput>
-</para>
- <para><userinput>hibernate.connection.url = jdbc:postgresql:dhis</userinput></para>
- <para><userinput>hibernate.connection.username = dhis </userinput></para>
- <para><userinput>hibernate.connection.password = dhis</userinput>
-</para>
- <para><userinput>hibernate.hbm2ddl.auto = update</userinput></para>
- <para>Save this file in the DHIS2_HOME directory. Exit the current shell in order to reload the environment variables and open a new shell. You will need to start both postgresql as well as the tomcat server. If you installed postgresql with the apt-get command, you can start this from the /etc/init.d/ directory with the commands. </para>
- <para><userinput>sudo su - </userinput></para>
- <para><userinput>cd /etc/init.d/</userinput></para>
- <para><userinput>./S18postgresql start</userinput></para>
- <para>Note that you may need to alter this command to your particular system. </para>
- <para>It is good security practise to run the tomcat application as a separate user. If you do not already have a separate user account, you can create one with the following commands. </para>
- <para> <userinput>sudo useradd -d /home/tomcat6 -m tomcat6</userinput></para>
- <para><userinput>sudo passwd tomcat6 </userinput></para>
- <para>You should not change the file permissions for the entire directory that you installed Tomcat to, with the following command. </para>
- <para><userinput>sudo chown -R tomcat6:tomcat6 /usr/local/tomcat</userinput></para>
- <para>To start the application, login as the user, navigate to the <filename>/usr/local/tomcat/bin/</filename> directory, and execute the <filename>start.sh</filename> script. </para>
- <para><userinput>sudo su - tomcat6</userinput></para>
- <para><userinput>cd /usr/local/tomcat/bin</userinput></para>
- <para><userinput>./startup.sh</userinput></para>
- </section>
- <section>
- <title>Installing DHIS2 with the Debian install package</title>
- <para>If you are using Ubuntu or Debian, a separate Debian installation package has been created to simplify the installation process. You can simply download this <ulink url="http://www.dhis2.org/download/dhis2-2.0.3.deb";>file</ulink> and then install DHIS2 from the command line with the following command. </para>
- <para><userinput>sudo dpkg -i dhis2-2.0.3.deb</userinput></para>
- <para>You can also install this Debian package from your systems package manager. </para>
- </section>
- </section>
- <section id="mod2_2">
- <title>Logging on to DHIS2</title>
- <para>Regardless of whether you have installed the server version of the
- desktop Live version, you will use a web-browser to log on to the
- application. DHIS 2 should be compatible with most modern web-browsers,
- although you will need to ensure that Java Script is enabled.</para>
- <para>To log on to the application just enter <ulink url="http://localhost:8080/dhis"; type="">http://localhost:8080/dhis</ulink> if you
- are using the DHIS2 live package, or replace localhost with the name or IP
- address of the server where the server version is installed.</para>
- <para>Once you have started DHIS2, either on-line or offline, the displayed
- screen will prompt you to enter your registered ‘user name’ and
- ‘password’. After entering the required information click on log-in button
- to log into the application. The default user name and password are 'admin' and 'district'. They should be changed immediately upon logging on the first time. </para>
- </section>
- <section id="users">
- <title>Creating new users and roles</title>
- <para>This section will describe how to add new users to the DHIS 2
- application.</para>
- <section>
- <title>Open User Menu</title>
- <para>To create or find a user begin with clicking on the ‘user’ module
- displayed in the drop down menu of the Maintenance module located on the
- main tool bar on the top part of the displayed screen.</para>
- <screenshot>
- <screeninfo>Select Users menu item</screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata width="100%" format="PNG" fileref="resources/images/dhis2UserManual/select_user_menu.png"/>
- </imageobject>
- </mediaobject>
- </screenshot>
- <para>User names already registered will appear as a list as seen in the screen shot below.</para>
- <screenshot>
- <screeninfo>Search by user name</screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata width="100%" format="PNG" fileref="resources/images/dhis2UserManual/search_user_by_name.png"/>
- </imageobject>
- </mediaobject>
- </screenshot>
- <para>You can search for specific user names in the user list by
- entering the name in the ‘filter by user name’ field as shown
- above.</para>
- </section>
- <section id="user_roles">
- <title>Define a new role</title>
- <para>As part of creating a user name you are required to define the user
- role. Do so by clicking on the ‘user role’ appearing on the left side of
- the displayed screen. This will lead you to the Role Management page where you will have
- to click on <guibutton>Add new</guibutton> to create a new role.</para>
- <screenshot>
- <screeninfo>Add new user role</screeninfo>
- <mediaobject>d
- <imageobject>
- <imagedata width="100%" format="PNG" fileref="resources/images/dhis2UserManual/add_user_role.png"/>
- </imageobject>
- </mediaobject>
- </screenshot>
- <para>The following screen will open and here in the first text box you
- need to give Name of the Role such as Super User, Admin User, etc. The
- second text box called ‘Description’ gives more information about the
- type of User Role that is being created for e.g. State Admin User,
- District Data Entry.</para>
- <screenshot>
- <screeninfo>Role maintenance page</screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata width="100%" format="PNG" fileref="resources/images/dhis2UserManual/role_maintenance_page.png"/>
- </imageobject>
- </mediaobject>
- </screenshot>
- <para>Next you will specify the particular data set(s) that are to be
- made available to the particular role. You will also need to specify the
- type of ‘authority’ to be given to the particular user. For each of the
- three options namely Datasets, Reports and Authorities user can select
- multiple options from the scroll down menu provided against each field.
- A user can choose multiple options either by moving them
- one-by-one.</para>
- <para>In order for particular users to be able to enter data, you must
- add them to both a dataset as well as an organisational unit level. You
- can also select multiple datasets individually by pressing the Ctrl key
- on the keyboard and clicking on individual datasets.</para>
- <para>Finally when you have entered the required fields click on
- <guibutton>Save</guibutton> which is located on the lower part of the
- displayed screen. The desired user role and related authorisation will
- be saved to the database, and can then be assigned to a particular
- user.</para>
- </section>
- <section>
- <title>Add New User</title>
- <para>Under particular user role there can be more than one user. To add
- new users go to the User options under the Maintenance module.</para>
- <para>To add a new user, just follow these steps:</para>
- <itemizedlist>
- <listitem>
- <para>Click on the <guibutton>Add New</guibutton> button.</para>
- </listitem>
- <listitem>
- <para>Enter New User details like <guilabel>User name</guilabel>, <guilabel>Password</guilabel>, <guilabel>Confirm password</guilabel>, <guilabel>Surname</guilabel>, <guilabel>First name</guilabel> and <guilabel>Email</guilabel> in new user’s option tabs.</para>
- </listitem>
- <listitem>
- <para>Click on <guibutton>Add</guibutton> button for confirmation of
- new user details and follow the user error while creation of new
- user.</para>
- </listitem>
- <listitem>
- <para>The recently created new user can be seen in main’ User
- management Screen</para>
- </listitem>
- <listitem>
- <para>You can edit (like password, surname….etc) and delete the
- details of new/old users by selecting corresponding User’s
- <guibutton>Edit</guibutton> and <guibutton>Delete</guibutton>
- Buttons.</para>
- </listitem>
- <listitem>
- <para>Click on <guibutton>Save</guibutton> tab after editing all
- details of a particular selected user.</para>
- <screenshot>
- <screeninfo>User management screen</screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata width="100%" format="PNG" fileref="resources/images/dhis2UserManual/user_management.png"/>
- </imageobject>
- </mediaobject>
- </screenshot>
- </listitem>
- </itemizedlist>
- </section>
- </section>
- <section id="mod2_4">
- <title>Logging out of DHIS2</title>
- <para>Just click on the Log out link in the top right corner to exit the application.</para>
- </section>
- <section id="database_design">
- <title>Quick intro to designing a DHIS 2 database</title>
- <para>The DHIS 2 application comes with a set of tools for data collection, validation, reporting and analysis, but the contents of the database, e.g. what to collect, who should collect it and on what format will depend on the context of use. This metadata need to be populated into the application before it can be used, and this can be done through the user interface and requires no programming or in-depth technical skills of the software. We call this initial process database design or customisation.</para>
- <para>This section will provide a very quick and brief introduction to DHIS 2 database design and mainly explain the various steps needed to prepare a new DHIS 2 system for use. How to do each step is explained in other chapters, and best practices on design choices will be explained in an implementers manual (expected during first half of 2011). Here are the steps to follow:</para>
- <para>1. Set up an organisational hierarchy</para>
- <para>2. Define data elements</para>
- <para>3. Define data sets and data entry forms</para>
- <para>4. Define validation rules</para>
- <para>5. Define indicators</para>
- <para>6. Define report tables and design reports</para>
- <para>7. Set up the GIS module</para>
- <para>8. Design charts and customise the dashboard</para>
- <section>
- <title>The organisational hierarchy</title>
- <para>The organisational hierarchy defines the organisation using the DHIS 2, the health facilities, administrative areas and other geographical areas used in data collection and data analysis. This dimension to the data is defined as a hierarchy with one root unit (e.g. Ministry of Health) and any number of levels and nodes below. Each node in this hierarchy is called an organisational unit in DHIS 2. The design of this hierarchy will determine the geographical units of analysis available to the users as data is collected and aggregated in this structure. There can only be one organisational hierarchy at the same time so its structure needs careful consideration. Additional hierarchies (e.g. parallel administrative boundaries to the health care sector) can be modelled using organisational groups and group sets, but the organisational hierarchy is the main vehicle for data aggregation on the geographical dimension. Typically national organisational hierarchies in public health have 4-6 levels, but any number of levels is supported. The hierarchy is built up of parent-child relations, e.g. a Country or MoH unit (the root) might have e.g. 8 parent units (provinces), and each province again ( at level 2) might have 10-15 districts as their children. Normally the health facilities will be located at the lowest level, but they can also be located at higher levels, e.g. national or provincial hospitals, so skewed organisational trees are supported (e.g. a leaf node can be positioned at level 2 while most other leaf nodes are at level 5). Typically there is a geographical hierarchy defined by the health system. e.g. where the administrative offices are located (e.g. MoH, province, district), but often there are other administrative boundaries in the country that might or might not be added, depending on how its boundaries will improve data analysis. When designing the hierarchy the number of children for any organisational unit may indicate the usefulness of the structure, e.g. having one or more 1-1 relationships between two levels is not very useful as the values will be the same for the child and the parent level. On the other extreme a very high number of children in the middle of the hierarchy (e.g. 50 districts in a province) might call for an extra level to be added in between to increase the usefulness of data analysis. The lowest level, the health facilities will often have a large number of children (10-60), but for other levels higher up in the hierarchy approx. 5-20 children is recommended. To few or too many children might indicate that a level should be removed or added. Note that it is quite easy to make changes to the upper levels of the hierarchy at a later stage, the only problem is changing organisational units that collect data (the leaf nodes), e.g. splitting or merging health facilities. Aggregation up the hierarchy is done based on the current hierarchy at any time and will always reflect the most recent changes to the organisational structure. Refer to the chapter on Organisation Units to learn how to create organisational units and to build up the hierarchy.</para>
- </section>
- <section>
- <title>Data Elements</title>
- <para>The Data Element is perhaps the most important building block of a DHIS 2 database. It represents the "WHAT" dimension, it explains what is being collected or analysed. In some contexts this is referred to an indicator, but in DHIS 2 we call this unit of collection and analysis a <emphasis role="italic">data element</emphasis>. The data element often represents a count of something, and its name describes what is being counted, e.g. "BCG doses given" or "Malaria cases". When data is collected, validated, analysed, reported or presented it is the data elements or expressions built upon data elements that describes the WHAT of the data. As such the data elements become important for all aspects of the system and they decide not only how data is collected, but more importantly how the data values are represented in the database, which again decides how data can be analysed and presented. </para>
- <para>It is possible to add more details to this "WHAT" dimension through the disaggregation dimension called data element categories. Some common categories are Age and Gender, but any category can be added by the user and linked to specific data elements. The combination of a data element's name and its assigned category defines the smallest unit of collection and analysis available in the system, and hence describes the raw data in the database. Aggregations can be done when zooming out of this dimension, but no further drill-down is possible, so designing data elements and categories define the detail of the analysis available to the system (on the WHAT dimension). Changes to data elements and categories at a later stage in the process might be complicated as these will change the meaning of the data values already captured in the database (if any). So this step is one of the more decisive and careful steps in the database design process.</para>
- <para>One best practice when designing data elements is to think of data elements as a unit of data analysis and not just as a field in the data collection form. Each data element lives on its own in the database, completely detached from the collection form, and reports and other outputs are based on data elements and expressions/formulas composed of data elements and not the data collection forms. So the data analysis needs should drive the process, and not the look an feel of the data collection forms. A simple rule of thumb is that the name of the data element must be able to stand on its own and describe the data value also outside the context of its collection form. E.g. a data element name like "Total referrals" makes sense when looking at it in either the "RCH" form or the "OPD" form, but on its own it does not uniquely describe the phenomena (who are being referred?), and should in stead be called "Total referrals from Maternity" or "Total referrals from OPD". Two different data elements with different meanings, although the field on the paper form might only say "Total referrals" since the user of the form will always know where these referrals come from. In a database or a repository of data elements this context is no longer valid and therefore the names of the data elements become so important in describing the data. </para>
- <para>Common properties of data elements can be modelled through what is called data element groups. The groups are completely flexible in the sense that they are defined by the user, both their names and their memberships. Groups are useful both for browsing and presenting related data, but can also be used to aggregate data elements together. Groups are loosely coupled to data elements and not tied directly to the data values which means they can be modified and added at any point in time without interfering with the raw data. </para>
- </section>
- <section>
- <title>Datasets and data entry forms</title>
- <para>All data entry in DHIS2 is organised through the use of Datasets. A Dataset is a collection of data elements grouped together for data collection, and in the case of distributed installs they also define chunks of data for export and import between instances of DHIS2 (e.g. from a district office local installation to a national server). Datasets are not linked directly to the data values, only through their data elements and frequencies, and as such a dataset can be modified, deleted or added at any point in time without affecting the raw data already captured in the system, but such changes will of course affect how new data will be collected. </para>
- <para>A dataset has a period type which controls the data collection frequency, which can be daily, weekly, monthly, quarterly, six-monthly, or yearly. Both which data elements to include in the dataset and the period type is defined by the user, together with a name, short name, and code.</para>
- <para>In order to use a dataset to collect data for a specific orgunit you must assign the orgunit to the dataset, and this mechanism controls which orgunits that can use which datasets, and at the same time defines the target values for data completeness (e.g. how many health facilities in a district expected to submit RCH data every month). </para>
- <para>A data element can belong to multiple datasets, but this requires careful thinking as it may lead to overlapping and inconstant data being collected if e.g. the datasets are given different frequencies and are used by the same orgunits.
-</para>
- <section>
- <title>Data entry forms</title>
- <para>Once you have assigned a dataset to an orgunit that dataset will be made available in Data Entry (under Services) for the orgunits you have assigned it to and for the valid periods according to the dataset's period type. A default data entry form will then be shown, which is simply a list of the data elements belonging to the dataset together with a column for inputting the values. If your dataset contains data elements with categories such as age groups or gender, then additional columns will be automatically generated in the default form based on the categories. In addition to the default list-based data entry form there are two more alternatives, the section-based form and the custom form.</para>
- <section>
- <title>Section forms</title>
- <para>Section forms allow for a bit more flexibility when it comes to using tabular forms and are quick and simple to design. Often your data entry form will need multiple tables with subheadings, and sometimes you need to disable (grey out) a few fields in the table (e.g. some categpories do not apply to all data elements), both of these functions are supported in section forms. After defining a dataset you can define it's sections with subsets of dataelements, a heading and possible grey fields i the section's table. The order of sections in a datsaset can also be defined. In Data Entry you can now start using the Section form (should appear automatically when sections are available for the selected dataset). You can switch between default and section forms in the top right corner of the data entry screen. Most tabular data entry forms should be possible to do with sections forms, and the more you can utilise the section forms (or default forms) the easier it is for you. If these two types of forms are not meeting your requirements then the third option is the completely flexible, although more time-consuming, custom data entry forms.</para>
- </section>
- <section>
- <title>Custom Forms</title>
- <para>When the form you want to design is too complicated for the default or section forms then your last option is to use a custom form. This takes more time, but gives you full flexibility in term of the design. In DHIS 2 there is a built in HTML editor (FcK Editor) for the form designer and you can either design the form in the UI or paste in your html directly (using the Source window in the editor. In the custom form you can insert static text or data fields (linked to data elements + category) in any position on the form and you have complete freedom to design the layout of the form. Once a custom form has been added to a dataset it will be available in data entry and used automatically. You can switch back to default and section (if exists) forms in the top right corner of the data entry screen. </para>
- </section>
- </section>
- </section>
- <section>
- <title>Validation rules</title>
- <para>Once you have set up the data entry part of the system and started to collect data then there is time to define data quality checks that help to improve the quality of the data being collected. You can add as many validation rules as you like and these are composed of left and right side expressions that again are composed of data elements, with an operator between the two sides. Typical rules are comparing subtotals to totals of something. E.g. if you have two data elements "HIV tests taken" and "HIV test result positive" then you know that in the same form (for the same period and organisational unit) the total number of tests must always be equal or higher than the number of positive tests. These rules should be absolute rules meaning that they are mathematically correct and not just assumptions or "most of the time correct". The rules can be run in data entry, after filling each form, or as a more batch like process on multiple forms at the same time, e.g. for all facilities for the previous reporting month. The results of the tests will list all violations and the detailed values for each side of the expression where the violation ocurred to make it easy to go back to data entry and correct the values.</para>
- </section>
- <section>
- <title>Indicators</title>
- <para>Indicators represent perhaps the most powerful data analysis feature of the DHIS 2. While data elements represent the raw data (counts) being collected the indicators represent formulas providing coverage rates, incidence rates, ratios and other formula-based units of analysis. An indicator is made up of a factor (e.g. 1, 100, 100, 100 000), a numerator and a denominator, the two latter are both expressions based on one or more data elements. E.g. the indicator "BCG coverage <1 year" is defined a formula with a factor 100, a numerator ("BCG doses given to children under 1 year") and a denominator ("Target population under 1 year"). The indicator "DPT1 to DPT3 drop out rate" is a formula of 100 % x ("DPT1 doses given"- "DPT3 doses given") / ("DPT1 doses given"). </para>
- <para>Most report modules in DHIS 2 support both data elements and indicators and you can also combine these in custom reports, but the important difference and strength of indicators versus raw data (data element's data values) is the ability to compare data across different geographical areas (e.g. highly populated vs rural areas) as the target population can be used in the denominator.</para>
- <para>Indicators can be added, modified and deleted at any point in time without interfering with the data values in the database. </para>
- </section>
- <section>
- <title>Report tables and reports</title>
- <para>Standard reports in DHIS 2 is a very flexible way of presenting the data that has been collected. Data can be aggregated by any organisational unit or orgunit level, by data element, by indicators, as well as over time (e.g. monthly, quarterly, yearly). The report tables are custom data sources for the standard reports and can be flexibly defined in the user interface and later accessed in external report designers such as iReport or BIRT. These report designs can then be set up as easily accessible one-click reports with parameters so that the users can run the same reports e.g. every month when new data is entered, and also be relevant to users at all levels as the organisational unit can be selected at the time of running the report.</para>
- </section>
- <section>
- <title>GIS</title>
- <para>In the integrated GIS module you can easily display your data on maps, both on polygons (areas) and as points (health facilities), and either as data elements or indicators. By providing the coordinates of your organisational units to the system you can qucikly get up to speed with this module. See the GIS section for details on how to get started. </para>
- </section>
- <section>
- <title>Charts and dashboard</title>
- <para>On of the easiest way to display your indicator data is through charts. An easy to use chart dialogue will guide you through the creation of various types of charts with data on indicators, organisational units and periods of your choice. These charts can easily be added to one of the four chart sections on your dashboard and there be made easily available right after log in. Make sure to set the dashboard module as the start module in user settings. </para>
- </section>
- </section>
-</chapter>
+<?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>Getting started with DHIS 2</title>
+ <section id="mod2_1">
+ <title>Getting started with DHIS2</title>
+ <para>After reading this chapter you will be able to understand:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Start DHIS 2 from the desktop</para>
+ </listitem>
+ <listitem>
+ <para>How to log-in from the desktop</para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>Create new users and user roles</para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>What steps are needed to design a DHIS 2 database for your organisation</para>
+ </listitem>
+ </itemizedlist>
+ <section>
+ <title>Prerequisites</title>
+ <para>You must be sure that you have a current version of the Java Runtime installed on your machine. Depending on your operating system, there are different ways of installing Java. The reader is referred to this <ulink url="http://java.sun.com/javase/downloads/index.jsp";>website</ulink> for detailed information on getting java installed.</para>
+ </section>
+ <section>
+ <title>Starting the DHIS2 Live package</title>
+ <para>The DHIS2 Live package is the easiest way to get started with DHIS2. DHIS2 Live is appropriate for a stand-alone type of installation. Simply download the application from <ulink url="http://www.dhis2.org/downloads";>here</ulink>.
+ Once the file is downloaded, you can simply double-click the downloaded file, and get started using DHIS2. </para>
+ <section>
+ <title>Starting up with a blank database</title>
+ <para>The live package comes with a demo database just like what you see on the online demo (which is based on the national Sierra Leone HMIS), and if you want to start with a blank system/database and build up your own system then you need to do the following:
+
+</para>
+ <para>1) Stop the DHIS2 live if it is already running. Right click on the tray icon and select Exit.
+The tray icon is the green symbol on the bottom right of your screen (on Windows) which should say' DHIS2 Server running' if you hold your mouse pointer over it.</para>
+ <para>2) Open the folder where the DHIS2 live package is installed and locate the folder called "conf".
+</para>
+ <para>3) In conf/ open the file called 'hibernate.properties' in a text editor (notepad or similar) and do the following modification:
+locate the string 'jdbc:h2:./database/dhis2' and replace the 'dhis2' part with any name that you want to give to your database (e.g. dhis2_test).</para>
+ <para>4) Save and close the hibernate.properties file.
+</para>
+ <para>5) Start DHIS2 live by double-clicking on the file dhis2-live.exe in the DHIS2 live installation folder or by using a desktop shortcut or menu link that you might have set up.
+</para>
+ <para>6) Wait for the browser window to open and the login screen to show, and then log in with username: admin and password: district
+</para>
+ <para>7) Now you will see a completely empty DHIS2 system and you should start by adding your users, organisational hierarchy, data elements, and datasets etc. Please refer to the other sections of the user manual for instructions on how to do this.
+</para>
+ </section>
+ </section>
+ <section>
+ <title>Working directly with the H2 database</title>
+ <para>
+ DHIS2 Live uses an embedded <ulink url="www.h2database.com/">H2</ulink> database. This has several advantages - there is no need
+ to install a separate database engine such as PostgresSql or MySql, and backup can be made by just copying the file. The whole db
+ exists in memory, which means high performance. The disadvantage is need for RAM. It is also not suitable for mulitiuser server
+ installations.
+ </para>
+ <para>
+ In general, it is recommended to work with the database through the DHIS2 user interface, but in some situations one may need to
+ manipulate the data directly. If one downloads H2 separately, it comes with a web interface. It can also be manipulated using
+ <ulink url="http://openoffice.org";>OpenOffice.org</ulink>, using the following procedure. This assumes that dhis2-live is located in
+ the user's Linux home directory (represented by ~). Substitute the absolute path to your dhis2-live installation.
+ <itemizedlist>
+ <listitem>
+ <para>Start OpenOffice Word Processor and select Tools - Options, then Java - Class Path ... and click on Add Archive...</para>
+ </listitem>
+ <listitem>
+ <para>Select the following file (version may differ): ~/dhis2-live/webapps/dhis/WEB-INF/lib/h2-1.1.119.jar</para>
+ </listitem>
+ <listitem>
+ <para>Close OpenOffice completely and then open OpenOffice.org Database. Select connect to an existing database - JDBC</para>
+ </listitem>
+ <listitem>
+ <para>Datasource URL is h2:~/dhis2-live/database/dhis2;AUTO_SERVER=TRUE, and JDBC driver class is org.h2.Driver</para>
+ </listitem>
+ <listitem>
+ <para>User name is sa, password not needed. Finally, select a name and folder for the .odb file.</para>
+ </listitem>
+ </itemizedlist>
+ <ulink url="http://www.oooforum.org/forum/viewtopic.phtml?t=97522";>More tips</ulink>
+
+ </para>
+ </section>
+ <section>
+ <title>Downloading and installing the server version</title>
+ <para>DHIS2 functions both as a
+ desktop application, as well as a web-enabled client-server application.
+ For larger, production installations with many users and large volumes
+ of data (for instance as a national level server) it is recommended to
+ install the server version. The latest version of the infrastructure can be
+ found <ulink url="http://dhis.uio.no/ci/job/Dhis2%20Web%20Trunk/lastSuccessfulBuild/artifact/dhis-2/dhis-web/dhis-web-portal/target/dhis.war";>here</ulink>.
+ </para>
+ <para>There are many permutations of getting a server installation up and running, and will depend very much on the nature of the installation. A typical installation for a single machine, running Ubuntu Linux will be described in the discussion that follows. This type of single-installation would be appropriate for a small work-group. There are so many different ways to get the application running, and this will depend to a large extent on the number of users you will be catering to, the type of hardware you have available, and the nature of the implementation of the application (e.g one central server as opposed to multiple subnational installations). The example provided here is meant to be a rough guide for those that are setting up a DHIS2 server instance from scratch, however, you should consider all security requirements of your implementation before blindly following this example. </para>
+ <para>You will need to decide which back-end database system you will use. DHIS2 is a database agnostic application in principle, and should run on any system with a compatible JDBC driver. However, it is recommended either to use Postgresql or MySQL, as these systems are widely used by other members of the DHIS2 community. In addition to a back-end database system, you will need a compatible servlet container. Apache Tomcat 6 is recommended by the developers, however in principle, the application should run in any container that conforms to the Servlet 2.5 specification. </para>
+ <para>It is certainly possible to install all packages from source code, but it is suggested that you install most of the basic packages through your systems package manager. Depending on which version of Linux that you may be using, you may need to install a newer version of both the back-end database system (such as Postgresql and MySQL) and Servlet container. It is recommended to use at least Postgresl version 8.3 or MySQL 5.0. </para>
+ <para>To get started downloading the necessary packages, execute the following commands. Note that you may need to add the <command>sudo</command> command before these commands, if you are not running as root. </para>
+ <para><programlisting><userinput>apt-get install nano <userinput>wget nano /etc/apt/sources.list </userinput></userinput></programlisting></para>
+ <para>Uncomment and add “multiverse†after “universe†in each line of this file. </para>
+ <para>After editing the sources.list execute these commands. </para>
+ <para><programlisting><userinput>apt-get update </userinput>
+<userinput>apt-get install sun-java6-jdk postgresql postgresql-client</userinput>
+<userinput>postgresql-contrib postgresql-8.3-postgis</userinput></programlisting></para>
+ <para>This will install a number of packages on your system, including Java and the Postgresql database system. In principle, DHIS2 will run under any servlet container, but it is recommended to use Apache Tomcat. Check with the DHIS2 developers if you have questions about using other servlet containers. To get Tomcat, execute the following commands</para>
+ <para><programlisting><userinput><userinput>wget http://apache.mirror.testserver.li/tomcat/tomcat-6/v6.0.20/bin/apache-tomcat-6.0.20.tar.gz</userinput> tar xvzf apache-tomcat-6.0.20.tar.gz mv apache-tomcat-6.0.20 /usr/local/tomcat</userinput></programlisting></para>
+ <para>If you need plan on installing Geoserver as part of your DHIS2 installation, go ahead and download and install it. You should check on the <ulink url="http://www.geoserver.org";>Geoserver web page</ulink> for the latest version. </para>
+ <para>
+
+<userinput>wget http://downloads.sourceforge.net/geoserver/geoserver-2.0.0a-war.zip</userinput></para>
+ <para><userinput>unzip geoserver-2.0.0a-war.zip</userinput></para>
+ <para>
+<userinput>unzip geoserver.war -d /usr/local/tomcat/webapps </userinput></para>
+ <para>
+<userinput>mv /usr/local/tomcat/webapps/geoserver/data /usr/local/geodata</userinput></para>
+ <para>You should now change the default Geoserver password to something more secure. Execute<userinput> nano /usr/local/geodata/security/users.properties </userinput>and change the password and then save all changes. </para>
+ <para>Edit one of your persistent environment variables (see <ulink url="https://help.ubuntu.com/community/EnvironmentVariables#Persistent%20environment%20variables";>this page</ulink> for details). Add the following lines to the chosen file. </para>
+ <para><envar>export JAVA_HOME=/usr/lib/jvm/java-6-sun</envar></para>
+ <para><envar>export JDK_HOME= /usr/lib/jvm/java-6-sun</envar>
+</para>
+ <para><envar>export JAVA_OPTS=-XX:PermSize=256m -XX:MaxPermSize=1536 -Xms512m -Xmx1024m -server</envar>
+</para>
+ <para><envar>export GEOSERVER_DATA_DIR=/usr/local/geodata</envar>
+</para>
+ <para><envar>export DHIS2_HOME=/root/dhis/dhis2</envar>
+</para>
+ <para>Note that you may need to alter the file paths to point to the actual directories on your system. </para>
+ <para>Assuming that you have installed the postgresql database system, you can create a new database with the following commands. </para>
+ <para><userinput>sudo su - postgres</userinput></para>
+ <para><userinput>createdb createdb -E utf-8 <parameter>dhis</parameter></userinput></para>
+ <para>Note that you can change the name of the database to anything that suits your environment. </para>
+ <para> To tell the DHIS2 application where to find its database you need a <filename>hibernate.properties</filename> file in <envar>DHIS2_HOME</envar> . For a postgres database connection to a database called 'dhis', with user name and password 'dhis', you need to put the following inside your file /root/dhis/dhis2/hibernate.properties: </para>
+ <para><userinput>hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect</userinput></para>
+ <para><userinput>hibernate.connection.driver_class = org.postgresql.Driver</userinput>
+</para>
+ <para><userinput>hibernate.connection.url = jdbc:postgresql:dhis</userinput></para>
+ <para><userinput>hibernate.connection.username = dhis </userinput></para>
+ <para><userinput>hibernate.connection.password = dhis</userinput>
+</para>
+ <para><userinput>hibernate.hbm2ddl.auto = update</userinput></para>
+ <para>Save this file in the DHIS2_HOME directory. Exit the current shell in order to reload the environment variables and open a new shell. You will need to start both postgresql as well as the tomcat server. If you installed postgresql with the apt-get command, you can start this from the /etc/init.d/ directory with the commands. </para>
+ <para><userinput>sudo su - </userinput></para>
+ <para><userinput>cd /etc/init.d/</userinput></para>
+ <para><userinput>./S18postgresql start</userinput></para>
+ <para>Note that you may need to alter this command to your particular system. </para>
+ <para>It is good security practise to run the tomcat application as a separate user. If you do not already have a separate user account, you can create one with the following commands. </para>
+ <para> <userinput>sudo useradd -d /home/tomcat6 -m tomcat6</userinput></para>
+ <para><userinput>sudo passwd tomcat6 </userinput></para>
+ <para>You should not change the file permissions for the entire directory that you installed Tomcat to, with the following command. </para>
+ <para><userinput>sudo chown -R tomcat6:tomcat6 /usr/local/tomcat</userinput></para>
+ <para>To start the application, login as the user, navigate to the <filename>/usr/local/tomcat/bin/</filename> directory, and execute the <filename>start.sh</filename> script. </para>
+ <para><userinput>sudo su - tomcat6</userinput></para>
+ <para><userinput>cd /usr/local/tomcat/bin</userinput></para>
+ <para><userinput>./startup.sh</userinput></para>
+ </section>
+ <section>
+ <title>Installing DHIS2 with the Debian install package</title>
+ <para>If you are using Ubuntu or Debian, a separate Debian installation package has been created to simplify the installation process. You can simply download this <ulink url="http://www.dhis2.org/download/dhis2-2.0.3.deb";>file</ulink> and then install DHIS2 from the command line with the following command. </para>
+ <para><userinput>sudo dpkg -i dhis2-2.0.3.deb</userinput></para>
+ <para>You can also install this Debian package from your systems package manager. </para>
+ </section>
+ </section>
+ <section id="mod2_2">
+ <title>Logging on to DHIS2</title>
+ <para>Regardless of whether you have installed the server version of the
+ desktop Live version, you will use a web-browser to log on to the
+ application. DHIS 2 should be compatible with most modern web-browsers,
+ although you will need to ensure that Java Script is enabled.</para>
+ <para>To log on to the application just enter <ulink url="http://localhost:8080/dhis"; type="">http://localhost:8080/dhis</ulink> if you
+ are using the DHIS2 live package, or replace localhost with the name or IP
+ address of the server where the server version is installed.</para>
+ <para>Once you have started DHIS2, either on-line or offline, the displayed
+ screen will prompt you to enter your registered ‘user name’ and
+ ‘password’. After entering the required information click on log-in button
+ to log into the application. The default user name and password are 'admin' and 'district'. They should be changed immediately upon logging on the first time. </para>
+ </section>
+ <section id="users">
+ <title>Creating new users and roles</title>
+ <para>This section will describe how to add new users to the DHIS 2
+ application.</para>
+ <section>
+ <title>Open User Menu</title>
+ <para>To create or find a user begin with clicking on the ‘user’ module
+ displayed in the drop down menu of the Maintenance module located on the
+ main tool bar on the top part of the displayed screen.</para>
+ <screenshot>
+ <screeninfo>Select Users menu item</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="100%" format="PNG" fileref="resources/images/dhis2UserManual/select_user_menu.png"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ <para>User names already registered will appear as a list as seen in the screen shot below.</para>
+ <screenshot>
+ <screeninfo>Search by user name</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="100%" format="PNG" fileref="resources/images/dhis2UserManual/search_user_by_name.png"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ <para>You can search for specific user names in the user list by
+ entering the name in the ‘filter by user name’ field as shown
+ above.</para>
+ </section>
+ <section id="user_roles">
+ <title>Define a new role</title>
+ <para>As part of creating a user name you are required to define the user
+ role. Do so by clicking on the ‘user role’ appearing on the left side of
+ the displayed screen. This will lead you to the Role Management page where you will have
+ to click on <guibutton>Add new</guibutton> to create a new role.</para>
+ <screenshot>
+ <screeninfo>Add new user role</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="100%" format="PNG" fileref="resources/images/dhis2UserManual/add_user_role.png"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ <para>The following screen will open and here in the first text box you
+ need to give Name of the Role such as Super User, Admin User, etc. The
+ second text box called ‘Description’ gives more information about the
+ type of User Role that is being created for e.g. State Admin User,
+ District Data Entry.</para>
+ <screenshot>
+ <screeninfo>Role maintenance page</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="100%" format="PNG" fileref="resources/images/dhis2UserManual/role_maintenance_page.png"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ <para>Next you will specify the particular data set(s) that are to be
+ made available to the particular role. You will also need to specify the
+ type of ‘authority’ to be given to the particular user. For each of the
+ three options namely Datasets, Reports and Authorities user can select
+ multiple options from the scroll down menu provided against each field.
+ A user can choose multiple options either by moving them
+ one-by-one.</para>
+ <para>In order for particular users to be able to enter data, you must
+ add them to both a dataset as well as an organisational unit level. You
+ can also select multiple datasets individually by pressing the Ctrl key
+ on the keyboard and clicking on individual datasets.</para>
+ <para>Finally when you have entered the required fields click on
+ <guibutton>Save</guibutton> which is located on the lower part of the
+ displayed screen. The desired user role and related authorisation will
+ be saved to the database, and can then be assigned to a particular
+ user.</para>
+ </section>
+ <section>
+ <title>Add New User</title>
+ <para>Under particular user role there can be more than one user. To add
+ new users go to the User options under the Maintenance module.</para>
+ <para>To add a new user, just follow these steps:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Click on the <guibutton>Add New</guibutton> button.</para>
+ </listitem>
+ <listitem>
+ <para>Enter New User details like <guilabel>User name</guilabel>, <guilabel>Password</guilabel>, <guilabel>Confirm password</guilabel>, <guilabel>Surname</guilabel>, <guilabel>First name</guilabel> and <guilabel>Email</guilabel> in new user’s option tabs.</para>
+ </listitem>
+ <listitem>
+ <para>Click on <guibutton>Add</guibutton> button for confirmation of
+ new user details and follow the user error while creation of new
+ user.</para>
+ </listitem>
+ <listitem>
+ <para>The recently created new user can be seen in main’ User
+ management Screen</para>
+ </listitem>
+ <listitem>
+ <para>You can edit (like password, surname….etc) and delete the
+ details of new/old users by selecting corresponding User’s
+ <guibutton>Edit</guibutton> and <guibutton>Delete</guibutton>
+ Buttons.</para>
+ </listitem>
+ <listitem>
+ <para>Click on <guibutton>Save</guibutton> tab after editing all
+ details of a particular selected user.</para>
+ <screenshot>
+ <screeninfo>User management screen</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="100%" format="PNG" fileref="resources/images/dhis2UserManual/user_management.png"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+ <section id="mod2_4">
+ <title>Logging out of DHIS2</title>
+ <para>Just click on the Log out link in the top right corner to exit the application.</para>
+ </section>
+ <section id="database_design">
+ <title>Quick intro to designing a DHIS 2 database</title>
+ <para>The DHIS 2 application comes with a set of tools for data collection, validation, reporting and analysis, but the contents of the database, e.g. what to collect, who should collect it and on what format will depend on the context of use. This metadata need to be populated into the application before it can be used, and this can be done through the user interface and requires no programming or in-depth technical skills of the software. We call this initial process database design or customisation.</para>
+ <para>This section will provide a very quick and brief introduction to DHIS 2 database design and mainly explain the various steps needed to prepare a new DHIS 2 system for use. How to do each step is explained in other chapters, and best practices on design choices will be explained in an implementers manual (expected during first half of 2011). Here are the steps to follow:</para>
+ <para>1. Set up an organisational hierarchy</para>
+ <para>2. Define data elements</para>
+ <para>3. Define data sets and data entry forms</para>
+ <para>4. Define validation rules</para>
+ <para>5. Define indicators</para>
+ <para>6. Define report tables and design reports</para>
+ <para>7. Set up the GIS module</para>
+ <para>8. Design charts and customise the dashboard</para>
+ <section>
+ <title>The organisational hierarchy</title>
+ <para>The organisational hierarchy defines the organisation using the DHIS 2, the health facilities, administrative areas and other geographical areas used in data collection and data analysis. This dimension to the data is defined as a hierarchy with one root unit (e.g. Ministry of Health) and any number of levels and nodes below. Each node in this hierarchy is called an organisational unit in DHIS 2. The design of this hierarchy will determine the geographical units of analysis available to the users as data is collected and aggregated in this structure. There can only be one organisational hierarchy at the same time so its structure needs careful consideration. Additional hierarchies (e.g. parallel administrative boundaries to the health care sector) can be modelled using organisational groups and group sets, but the organisational hierarchy is the main vehicle for data aggregation on the geographical dimension. Typically national organisational hierarchies in public health have 4-6 levels, but any number of levels is supported. The hierarchy is built up of parent-child relations, e.g. a Country or MoH unit (the root) might have e.g. 8 parent units (provinces), and each province again ( at level 2) might have 10-15 districts as their children. Normally the health facilities will be located at the lowest level, but they can also be located at higher levels, e.g. national or provincial hospitals, so skewed organisational trees are supported (e.g. a leaf node can be positioned at level 2 while most other leaf nodes are at level 5). Typically there is a geographical hierarchy defined by the health system. e.g. where the administrative offices are located (e.g. MoH, province, district), but often there are other administrative boundaries in the country that might or might not be added, depending on how its boundaries will improve data analysis. When designing the hierarchy the number of children for any organisational unit may indicate the usefulness of the structure, e.g. having one or more 1-1 relationships between two levels is not very useful as the values will be the same for the child and the parent level. On the other extreme a very high number of children in the middle of the hierarchy (e.g. 50 districts in a province) might call for an extra level to be added in between to increase the usefulness of data analysis. The lowest level, the health facilities will often have a large number of children (10-60), but for other levels higher up in the hierarchy approx. 5-20 children is recommended. To few or too many children might indicate that a level should be removed or added. Note that it is quite easy to make changes to the upper levels of the hierarchy at a later stage, the only problem is changing organisational units that collect data (the leaf nodes), e.g. splitting or merging health facilities. Aggregation up the hierarchy is done based on the current hierarchy at any time and will always reflect the most recent changes to the organisational structure. Refer to the chapter on Organisation Units to learn how to create organisational units and to build up the hierarchy.</para>
+ </section>
+ <section>
+ <title>Data Elements</title>
+ <para>The Data Element is perhaps the most important building block of a DHIS 2 database. It represents the "WHAT" dimension, it explains what is being collected or analysed. In some contexts this is referred to an indicator, but in DHIS 2 we call this unit of collection and analysis a <emphasis role="italic">data element</emphasis>. The data element often represents a count of something, and its name describes what is being counted, e.g. "BCG doses given" or "Malaria cases". When data is collected, validated, analysed, reported or presented it is the data elements or expressions built upon data elements that describes the WHAT of the data. As such the data elements become important for all aspects of the system and they decide not only how data is collected, but more importantly how the data values are represented in the database, which again decides how data can be analysed and presented. </para>
+ <para>It is possible to add more details to this "WHAT" dimension through the disaggregation dimension called data element categories. Some common categories are Age and Gender, but any category can be added by the user and linked to specific data elements. The combination of a data element's name and its assigned category defines the smallest unit of collection and analysis available in the system, and hence describes the raw data in the database. Aggregations can be done when zooming out of this dimension, but no further drill-down is possible, so designing data elements and categories define the detail of the analysis available to the system (on the WHAT dimension). Changes to data elements and categories at a later stage in the process might be complicated as these will change the meaning of the data values already captured in the database (if any). So this step is one of the more decisive and careful steps in the database design process.</para>
+ <para>One best practice when designing data elements is to think of data elements as a unit of data analysis and not just as a field in the data collection form. Each data element lives on its own in the database, completely detached from the collection form, and reports and other outputs are based on data elements and expressions/formulas composed of data elements and not the data collection forms. So the data analysis needs should drive the process, and not the look an feel of the data collection forms. A simple rule of thumb is that the name of the data element must be able to stand on its own and describe the data value also outside the context of its collection form. E.g. a data element name like "Total referrals" makes sense when looking at it in either the "RCH" form or the "OPD" form, but on its own it does not uniquely describe the phenomena (who are being referred?), and should in stead be called "Total referrals from Maternity" or "Total referrals from OPD". Two different data elements with different meanings, although the field on the paper form might only say "Total referrals" since the user of the form will always know where these referrals come from. In a database or a repository of data elements this context is no longer valid and therefore the names of the data elements become so important in describing the data. </para>
+ <para>Common properties of data elements can be modelled through what is called data element groups. The groups are completely flexible in the sense that they are defined by the user, both their names and their memberships. Groups are useful both for browsing and presenting related data, but can also be used to aggregate data elements together. Groups are loosely coupled to data elements and not tied directly to the data values which means they can be modified and added at any point in time without interfering with the raw data. </para>
+ </section>
+ <section>
+ <title>Datasets and data entry forms</title>
+ <para>All data entry in DHIS2 is organised through the use of Datasets. A Dataset is a collection of data elements grouped together for data collection, and in the case of distributed installs they also define chunks of data for export and import between instances of DHIS2 (e.g. from a district office local installation to a national server). Datasets are not linked directly to the data values, only through their data elements and frequencies, and as such a dataset can be modified, deleted or added at any point in time without affecting the raw data already captured in the system, but such changes will of course affect how new data will be collected. </para>
+ <para>A dataset has a period type which controls the data collection frequency, which can be daily, weekly, monthly, quarterly, six-monthly, or yearly. Both which data elements to include in the dataset and the period type is defined by the user, together with a name, short name, and code.</para>
+ <para>In order to use a dataset to collect data for a specific orgunit you must assign the orgunit to the dataset, and this mechanism controls which orgunits that can use which datasets, and at the same time defines the target values for data completeness (e.g. how many health facilities in a district expected to submit RCH data every month). </para>
+ <para>A data element can belong to multiple datasets, but this requires careful thinking as it may lead to overlapping and inconstant data being collected if e.g. the datasets are given different frequencies and are used by the same orgunits.
+</para>
+ <section>
+ <title>Data entry forms</title>
+ <para>Once you have assigned a dataset to an orgunit that dataset will be made available in Data Entry (under Services) for the orgunits you have assigned it to and for the valid periods according to the dataset's period type. A default data entry form will then be shown, which is simply a list of the data elements belonging to the dataset together with a column for inputting the values. If your dataset contains data elements with categories such as age groups or gender, then additional columns will be automatically generated in the default form based on the categories. In addition to the default list-based data entry form there are two more alternatives, the section-based form and the custom form.</para>
+ <section>
+ <title>Section forms</title>
+ <para>Section forms allow for a bit more flexibility when it comes to using tabular forms and are quick and simple to design. Often your data entry form will need multiple tables with subheadings, and sometimes you need to disable (grey out) a few fields in the table (e.g. some categpories do not apply to all data elements), both of these functions are supported in section forms. After defining a dataset you can define it's sections with subsets of dataelements, a heading and possible grey fields i the section's table. The order of sections in a datsaset can also be defined. In Data Entry you can now start using the Section form (should appear automatically when sections are available for the selected dataset). You can switch between default and section forms in the top right corner of the data entry screen. Most tabular data entry forms should be possible to do with sections forms, and the more you can utilise the section forms (or default forms) the easier it is for you. If these two types of forms are not meeting your requirements then the third option is the completely flexible, although more time-consuming, custom data entry forms.</para>
+ </section>
+ <section>
+ <title>Custom Forms</title>
+ <para>When the form you want to design is too complicated for the default or section forms then your last option is to use a custom form. This takes more time, but gives you full flexibility in term of the design. In DHIS 2 there is a built in HTML editor (FcK Editor) for the form designer and you can either design the form in the UI or paste in your html directly (using the Source window in the editor. In the custom form you can insert static text or data fields (linked to data elements + category) in any position on the form and you have complete freedom to design the layout of the form. Once a custom form has been added to a dataset it will be available in data entry and used automatically. You can switch back to default and section (if exists) forms in the top right corner of the data entry screen. </para>
+ </section>
+ </section>
+ </section>
+ <section>
+ <title>Validation rules</title>
+ <para>Once you have set up the data entry part of the system and started to collect data then there is time to define data quality checks that help to improve the quality of the data being collected. You can add as many validation rules as you like and these are composed of left and right side expressions that again are composed of data elements, with an operator between the two sides. Typical rules are comparing subtotals to totals of something. E.g. if you have two data elements "HIV tests taken" and "HIV test result positive" then you know that in the same form (for the same period and organisational unit) the total number of tests must always be equal or higher than the number of positive tests. These rules should be absolute rules meaning that they are mathematically correct and not just assumptions or "most of the time correct". The rules can be run in data entry, after filling each form, or as a more batch like process on multiple forms at the same time, e.g. for all facilities for the previous reporting month. The results of the tests will list all violations and the detailed values for each side of the expression where the violation ocurred to make it easy to go back to data entry and correct the values.</para>
+ </section>
+ <section>
+ <title>Indicators</title>
+ <para>Indicators represent perhaps the most powerful data analysis feature of the DHIS 2. While data elements represent the raw data (counts) being collected the indicators represent formulas providing coverage rates, incidence rates, ratios and other formula-based units of analysis. An indicator is made up of a factor (e.g. 1, 100, 100, 100 000), a numerator and a denominator, the two latter are both expressions based on one or more data elements. E.g. the indicator "BCG coverage <1 year" is defined a formula with a factor 100, a numerator ("BCG doses given to children under 1 year") and a denominator ("Target population under 1 year"). The indicator "DPT1 to DPT3 drop out rate" is a formula of 100 % x ("DPT1 doses given"- "DPT3 doses given") / ("DPT1 doses given"). </para>
+ <para>Most report modules in DHIS 2 support both data elements and indicators and you can also combine these in custom reports, but the important difference and strength of indicators versus raw data (data element's data values) is the ability to compare data across different geographical areas (e.g. highly populated vs rural areas) as the target population can be used in the denominator.</para>
+ <para>Indicators can be added, modified and deleted at any point in time without interfering with the data values in the database. </para>
+ </section>
+ <section>
+ <title>Report tables and reports</title>
+ <para>Standard reports in DHIS 2 is a very flexible way of presenting the data that has been collected. Data can be aggregated by any organisational unit or orgunit level, by data element, by indicators, as well as over time (e.g. monthly, quarterly, yearly). The report tables are custom data sources for the standard reports and can be flexibly defined in the user interface and later accessed in external report designers such as iReport or BIRT. These report designs can then be set up as easily accessible one-click reports with parameters so that the users can run the same reports e.g. every month when new data is entered, and also be relevant to users at all levels as the organisational unit can be selected at the time of running the report.</para>
+ </section>
+ <section>
+ <title>GIS</title>
+ <para>In the integrated GIS module you can easily display your data on maps, both on polygons (areas) and as points (health facilities), and either as data elements or indicators. By providing the coordinates of your organisational units to the system you can qucikly get up to speed with this module. See the GIS section for details on how to get started. </para>
+ </section>
+ <section>
+ <title>Charts and dashboard</title>
+ <para>On of the easiest way to display your indicator data is through charts. An easy to use chart dialogue will guide you through the creation of various types of charts with data on indicators, organisational units and periods of your choice. These charts can easily be added to one of the four chart sections on your dashboard and there be made easily available right after log in. Make sure to set the dashboard module as the start module in user settings. </para>
+ </section>
+ </section>
+</chapter>
