Data elements

Data elements Data elements form the basis of DHIS2. Data elements define what is actually recorded in system, e.g. number of immunizations or number of cases of malaria. The actual creation and defition of the data elements themselves are far beyond the scope of this manual to describe, but it is assumed that an administrator will be provided with a list of standardized data elements for inclusion into the DHIS2 system. - Each of the options for maintainence of data elements will be described in the following section. + Each of the options for maintenance of data elements will be described in the following section. Data element @@ -39,10 +39,10 @@

- Data element maintence - To access the data element maintainence mage, choose Maintainence->Data elements->Data element. + Data element maintenance + To access the data element maintenance module, choose Maintenance->Data elements->Data element. The ‘Filter by name’ will allow you to filter a range of data elements if you know either the full name of the data element, or just a part of it. Type the name -into the search field andany matching data elements are displayed below. +into the search field and any matching data elements are displayed below. You can also choose ‘Filter by group/view all’ to narrow down a data element search within a particular data element group. In default mode, this @@ -59,7 +59,7 @@ To add a new data element, click the 'Add new' button. There are various options available from this page that allow the user to modify data elements already present in the database. Each of the options are described below in the "Editing data elements".

Editing data elements - Click the "Edit" button to modify the properties of a data element that has been previouly defined. + Click the "Edit" button to modify the properties of a data element that has been previously defined. @@ -75,10 +75,10 @@ Short name: Typically, an abbreviation of the full data element name. This attribute is often used in reports to display the name of the data element, where there is limited space available. - Alternative name: Allows the defintion of an alternative name of the data element. + Alternative name: Allows the definition of an alternative name of the data element. - Code: In many countries, data elements are assigned a code. This code can be entered in thsi field. + Code: In many countries, data elements are assigned a code. This code can be entered in this field. Description: Allows a full textual description of the data element to be entered. The user should be as precise as possible, and include full information on how the data element is measured and what its meaning is. @@ -104,7 +104,7 @@ Combination of categories: Defines which category combination the data element should have. - Data element group sets: Click the check box to activate this option hen choose which data element group sets this data element should belong to. Available data element group sets are displaye din the upper window. Click the desired data element group set, then the "Add selected" button to add the data element to the group set. To remove a data element from a group set, click the data element group set in the lower list, and then click "Remove selected". + Data element group sets: Click the check box to activate this option hen choose which data element group sets this data element should belong to. Available data element group sets are displayed din the upper window. Click the desired data element group set, then the "Add selected" button to add the data element to the group set. To remove a data element from a group set, click the data element group set in the lower list, and then click "Remove selected". @@ -129,7 +129,7 @@ levels option, a drop down menu appears which displays available aggregation levels. The desired aggregation level is then selected by clicking the ‘Add Selected’ button. - By default, the aggregation will start at the lowest assgined organisation unit. + By default, the aggregation will start at the lowest assigned organisation unit. @@ -164,7 +164,7 @@ Refers to the ISO 3166-1-alpha-2 code. A complete listing is available here. - The combination of these two codes together, forms a "locale" code, which is composed of the combination of the location and language. A very comprehensive discsussion of the technical standard (RFC 3066) is available here. This page provides a very comprehensive list of recognized locale codes. + The combination of these two codes together, forms a "locale" code, which is composed of the combination of the location and language. A very comprehensive discussion of the technical standard (RFC 3066) is available here. This page provides a very comprehensive list of recognized locale codes.

Deleting a data element @@ -183,8 +183,8 @@

- Data element group maintainece - Data element groups provide a mechanism for classifying related data elements into a common theme. For instance, two data elements "Measles immunization" and "BCG Immunization" might be grouped together into a data element group "Childhood immunization". To access the data element group maintainence page, click Maintainence->Data elements and indicators->Data Element Group . The following screen will be displayed. + Data element group maintenance + Data element groups provide a mechanism for classifying related data elements into a common theme. For instance, two data elements "Measles immunization" and "BCG Immunization" might be grouped together into a data element group "Childhood immunization". To access the data element group maintenance page, click Maintenance->Data elements and indicators->Data Element Group . The following screen will be displayed. @@ -192,7 +192,7 @@ - Similar to the "Data element" maintainence page, data elements groups can be searched with by entering a search string in the "Filter by name" field. + Similar to the "Data element" maintenance page, data elements groups can be searched with by entering a search string in the "Filter by name" field. To add a new data element group, click the "Add new" button. @@ -204,7 +204,7 @@

Data element group editor - The data element group editor provides advanced functionality to the administrator to allow multiple data elements to be added or removed from a group. It is also possible to create new data element groups, rename existing groups, and delete groups entirely. To access the data element group editor, press "Maintaience->Data elements and indicators->Data element group editor" from the main DHIS2 menu. The following screen will appear. + The data element group editor provides advanced functionality to the administrator to allow multiple data elements to be added or removed from a group. It is also possible to create new data element groups, rename existing groups, and delete groups entirely. To access the data element group editor, press "Maintainers->Data elements and indicators->Data element group editor" from the main DHIS2 menu. The following screen will appear. @@ -222,7 +222,7 @@

Data element group sets - Data element group sets allow multiple data element groups to be categorized into a set. Data element group sets are used during analysis and reporting to combine similar data element groups into a common theme. To access the data element group set maintainence module, choose "Maintainence->Data elements and indicators->Data element group set". Similar to the other data element maintainence modules, new data element group sets can be added by pressing the "Add new button". Other operations include Edit, Translate, Delete and Information, similar to the other modules in this section. + Data element group sets allow multiple data element groups to be categorized into a set. Data element group sets are used during analysis and reporting to combine similar data element groups into a common theme. To access the data element group set maintenance module, choose "Maintenance->Data elements and indicators->Data element group set". Similar to the other data element maintenance modules, new data element group sets can be added by pressing the "Add new button". Other operations include Edit, Translate, Delete and Information, similar to the other modules in this section. @@ -236,11 +236,11 @@ - Available data element groups are displayed in the left panel. They can be moved into the selected data element group set by pressing the "Move right" button. Data element groups that are currently members of the data element group set are displayed in the right hand panel. They can be removed from the data elemente group set by clicking the desired data element group and pressing the "Move left" button. The ordering of the data element groups can be set with the "Move Up" and "Move Down" arrows. This ordering will be used in the datamart and reports to order the data element groups. Press the "Update" button to save any changes and the "Cancel" button to discard all changes. + Available data element groups are displayed in the left panel. They can be moved into the selected data element group set by pressing the "Move right" button. Data element groups that are currently members of the data element group set are displayed in the right hand panel. They can be removed from the data element group set by clicking the desired data element group and pressing the "Move left" button. The ordering of the data element groups can be set with the "Move Up" and "Move Down" arrows. This ordering will be used in the datamart and reports to order the data element groups. Press the "Update" button to save any changes and the "Cancel" button to discard all changes.

Data element categories - Data element categories can be used to disaggregate data elements into individual atomic components. Data element categories are typically a concept, such as Gender, Age or Disease Status. Data elements such as "Number of cases of confirmed malaria" are often broken into smaller component parts to determine, for instance, the number of confirmed malaria cases of particular age groups. As an example, three data element categories: Under 1, 1-5 and Over 5 could be created. They could be assigned as categories to the data element, which would then create in the data entry screens, three seperate fields for this data element namely: + Data element categories can be used to disaggregate data elements into individual atomic components. Data element categories are typically a concept, such as Gender, Age or Disease Status. Data elements such as "Number of cases of confirmed malaria" are often broken into smaller component parts to determine, for instance, the number of confirmed malaria cases of particular age groups. As an example, three data element categories: Under 1, 1-5 and Over 5 could be created. They could be assigned as categories to the data element, which would then create in the data entry screens, three separate fields for this data element namely: Number of confirmed malaria cases (Under 1) @@ -252,12 +252,12 @@ Number of confirmed malaria cases (Over 5) - Effective use of data element categories greatly simplifies the process of setting up the DHIS2 system, as the data element categories can be reused to disaggregate many different data elements. Otherwise, each of the data elements listed above, would need to be created seperately. Judicious use of data element categories will greatly simplify the DHIS2 implementation, and allow for subsequent advanced analysis. + Effective use of data element categories greatly simplifies the process of setting up the DHIS2 system, as the data element categories can be reused to disaggregate many different data elements. Otherwise, each of the data elements listed above, would need to be created separately. Judicious use of data element categories will greatly simplify the DHIS2 implementation, and allow for subsequent advanced analysis. Data element categories are composed of category options. Category options must be defined when a data element category is created for the first time. Subsequent changes to the data element category, i.e. adding or deleting new category options, are not allowed once the data element category has been created. - It is critical that the proper categories and category options are defined in the intial definition step, as further changes to the category and its options will are not possible. + It is critical that the proper categories and category options are defined in the initial definition step, as further changes to the category and its options will are not possible. - To access the data element category maintaince module, press "Maintainance->Data elements and indicators->Data element category". The following screen will be displayed. + To access the data element category maintenance module, press "Maintenance->Data elements and indicators->Data element category". The following screen will be displayed. @@ -265,7 +265,7 @@ - Similar to the other data element maintiance modules, data element categories can be filtered by typing the name of the data element category (or a portion of it) into the "Filter by name" field. To add a new data element category, press the "Add new" button which will then display the following screen. + Similar to the other data element maintains modules, data element categories can be filtered by typing the name of the data element category (or a portion of it) into the "Filter by name" field. To add a new data element category, press the "Add new" button which will then display the following screen. @@ -273,13 +273,13 @@ - Type the name of the new data element category in the "Name" field in the "Details" region. Category options can be added by typing the name of the category option in the "Category option" region and pressing the "Add category option" button. Category options can be reordered using the "MoveUp" and "Move Down" buttons. Categories options can be deleted by selecting the data element category option and pressing the "Delete" button. Once all data element categories options have been added to the data elemente category, press the "Add" button to save all changes or the "Cancel" button to discard any changes. + Type the name of the new data element category in the "Name" field in the "Details" region. Category options can be added by typing the name of the category option in the "Category option" region and pressing the "Add category option" button. Category options can be reordered using the "Move Up" and "Move Down" buttons. Categories options can be deleted by selecting the data element category option and pressing the "Delete" button. Once all data element categories options have been added to the data element category, press the "Add" button to save all changes or the "Cancel" button to discard any changes. All data element category options must be added and defined properly in this step. Subsequent alterations to the data element category (other than reordering of the category options themselves) is not possible.

Data element category combinations - Data element category combinations allow multiple data element categories to be combined into a related set. As an example, a data element "Number of new HIV infections" might be disaagrgated according to the following categories. + Data element category combinations allow multiple data element categories to be combined into a related set. As an example, a data element "Number of new HIV infections" might be disaggregated according to the following categories. Age: "Under 5", "5-15", "15-24", "24 and above" @@ -288,8 +288,8 @@ Gender: Male, Female - In this example, there would be two levels of disaggreation, consisting of two seperate data element categories, each consisting of several data element category options. In most HMIS systems, different data elements are disaggregated according to a common set of categories. By combining these different categories into a data element category combination and assigning these combinations to data elements, the appropriate disaggregation levels can be applied efficiently and quickly to a large number of data elements. - To access the data element category combination maintainence module, select "Maintainence->Data element and indicators->Data element category combinations" from the main DHIS2 menu. As with the other maintaince modules, you can filter the listed cateogry combinations by entering the name (or portion thereof) of the category combination. Other operations such as "Edit", "Delete" and "Information" should be familiar to the reader. + In this example, there would be two levels of disaggregation, consisting of two separate data element categories, each consisting of several data element category options. In most HMIS systems, different data elements are disaggregated according to a common set of categories. By combining these different categories into a data element category combination and assigning these combinations to data elements, the appropriate disaggregation levels can be applied efficiently and quickly to a large number of data elements. + To access the data element category combination maintenance module, select "Maintenance->Data element and indicators->Data element category combinations" from the main DHIS2 menu. As with the other maintains modules, you can filter the listed category combinations by entering the name (or portion thereof) of the category combination. Other operations such as "Edit", "Delete" and "Information" should be familiar to the reader. To add a new category combination, click the "Add new" button. The following dialog will be displayed. @@ -304,4 +304,140 @@

+ Indicator maintenance + Indicator maintenance functions essentially the same as each of the respective sections in the previous section on data elements. The basic operations will be described in this section, but the reader should refer to the corresponding sections above for detailed instructions. + Indicators are composed of multiple data elements, and typically consist of a numerator and denominator. Indicators are never entered in DHIS2, but are derived from combinations of data elements and factors. Indicators are used to calculate coverage rates, incidence and other values are are a result of data element values that have been entered into the system. + To access the Indicator maintains page, press Maintenance->Data element and indicators->Indicators from the main DHIS2 menu. Similar to data elements, you can add, delete, modify and view extra information about the indicators in the system. + + + + + + + + Indicators can be filtered by entering the name or a part of the indicator name in the "Filter by name" field. Similar to data elements, indicators can be added by pressing the "Add new" button. Other operations available from this menu are as follows. + + + Existing indicators can be edited. + + + Translate an existing indicator. + + + Delete an existing indicator. + + + Get detailed information about this indicator. + + + To add a new indicator, click the "Add new" button. The following screen is displayed. + + + + + + + + Each of the fields marked with an asterisk are compulsory. A description of each field is provided below. + + + Name: The full name of the indicator, such as "Incidence of confirmed malaria cases per 1000 population" + + + Short name: An abbreviated name of the indicator such as "Inc conf. malaria per 1000 pop" + + + Alternative name: An additional field for a possible alternative name of the indicator. + + + Code: In many countries, indicator are often assigned a particular code. This code can be entered here. + + + Description: A brief, informative description of the indicator and how it is calculated can be entered here. + + + Annualized: Determines whether or not an annualization factor is applied during the calculation of the indicator. Typically, annualized indicator's numerator are multiplied by a factor of 12, and the denominator is for instance a yearly population figure. This allows for monthly coverage values to be calculated with yearly population figures. + + + Type: This field will determine a factor that will automatically be applied during the calculation of the indicator. Possible choices are determined by the Indicator Types (described below). For instance, a "Percent" indicator will automatically be multiplied by a factor of 100 when exported to the data mart, so that it will display as a percentage. + + + URL: Can be used as a link to an indicator registry, where a full metadata description of the indicator can be made available. + + + To define the numerator and denominator, simply press the respective button, and the following dialog will be displayed. + + + + + + + + Essentially, an indicator is a formula that can be composed of multiple data element, constant factors, and mathematical operators. In order to define a new indicator proceed with the following steps. + + + Provide a description of the numerator can be provided in the "Description field". + + + Choose the aggregation operator, either as a SUM or COUNT. + + + Define the formula of the indicator by selecting the data elements that should compose the numerator from the "Data elements" field. Simply select the data element, and double click it. It will now appear in the formula. You formula must be mathematically valid, including the proper use of parentheses when necessary. You can double click on each of the mathematical operator buttons below the indicator formula definition to add them to your formula. + + + Click the Save button to save all changes to the numerator. Click cancel to discard any changes that you have made. + + + Follow the same procedure in order to define the denominator. + + +

+ Indicator types + Indicator types simply define a factor that will be applied during aggregation. Indicator values that are calculate during a data mart export or report table generation process will appear properly formatted, and will therefore not require an additional multiplier (e.g. 100 in the case of percents) for the values to appear correctly formatted. + The indicator type maintenance panel has all of the same functions (Add new, Edit, Translate, Delete, and Information) as the Indicator maintenance section. + There are only two fields that need to be filled-in to create an indicator type, Name and Factor, as seen below. Name refers to the Indicator type (e.g. Per cent, Per thousand, Per ten thousand, etc). The factor is the numeric factor that will be applied during the calculation of the indicator. + + + + + + + + +

+ Indicator groups + Indicator groups function essentially the same as data element groups. Multiple indicators can be assigned to a group for easy filtering and analysis. To assign indicators to groups, simple press Maintenance->Data elements and indicators->Indicator groups. See the section on Data element groups for detailed instructions of how to use this module. +

+ Indicator group editor + The indicator group editor module functions essentially the same as the data element group editor module, except on indicators. You can easily rearrange the groups that indicators belong to with this module. To access it, choose To assign indicators to groups, simple press Maintenance->Data elements and indicators->Indicator group editor from the main menu. See the section on Data element group editor for further instructions. +

+ Indicator group sets + Similar to data element group sets, indicator group sets serve to create combined groups of similar indicators. For instance, you might have a group of indicators called "Malaria" and "Leishmaniasis". Both of these groups could be combined into a group set called "Vector-borne diseases". Indicator groups sets are used during analysis of data to combine similar themes of indicators. To access this module choose Maintenance->Data elements and indicators->Indicator group sets from the main menu. The following dialog will appear. + + + + + + + + Supply a name for the indicator group set, and then move the desired members from the "Available Indicator Groups" to the "Group members". Click "Add" to save your changes and "Cancel" to discard any changes. +

+ Data dictionary + Data dictionaries are used to group data elements and indicators during filtering operations. They are useful for combining related groups of data elements and indicators according to the programs to which they belong. For instance a data dictionary called "MCH" could be created, and all maternal and child health data elements and indicators could be added to the dictionary. The data dictionary can be access by choosing Maintenance->Data elements and indicators->Data dictionary. The following screen will be displayed in the browser. + + + + + + + + Provide a name for the data dictionary in the "Name" field and a description of its contents. Data elements and indicators can be added or removed from the dictionary. Click "Save" if you are creating a new data dictionary or "Add" if you are editing the contents of an existing data dictionary. +

- Getting started with DHIS2 - - After reading this chapter you will be able to understand: - - - Start DHIS 2 from the desktop - - - How to log-in from the desktop - - - Create new users and user roles - - - -

- Prerequisites - 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 website for detailed information on getting java installed. - -

- Starting the DHIS2 Live package - The DHIS2 Live package is the easiest way to get started with DHIS2. DHIS2 Live is appropirate for a stand-alone type of installation. Simply download the application from here. Once the file is downloaded, you can simply double-click the downloaded file, and get started using DHIS2. -

- Downloading and installing the server version - 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 application can be - found here. - - 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 workgroup. 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. - You will need to decide which backend 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 backend database system, you will need a compatible servlet container. Apache Tomcat 6 is reccomended by the developers, however in principle, the application should run in any container that conforms to the Servlet 2.5 specification. - 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 backend database system (such as Postgresql and MySQL) and Servlet container. It is reccomended to use at least Postgresl version 8.3 or MySQL 5.0. - To get started downloading the necessary packages, execute the following commands. Note that you may need to add the sudo command before these commands, if you are not running as root. - apt-get install nano - wget nano /etc/apt/sources.list - Uncomment and add “multiverse” after “universe” in each line of this file. - After editing the sources.list execute these commands. - apt-get update - apt-get install sun-java6-jdk postgresql postgresql-client postgresql-contrib postgresql-8.3-postgis - 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 reccomended 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 - wget http://apache.mirror.testserver.li/tomcat/tomcat-6/v6.0.20/bin/apache-tomcat-6.0.20.tar.gz - tar xvzf apache-tomcat-6.0.20.tar.gz - mv apache-tomcat-6.0.20 /usr/local/tomcat - 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 Geoserver webpage for the latest version. - - -wget http://downloads.sourceforge.net/geoserver/geoserver-2.0.0a-war.zip - unzip geoserver-2.0.0a-war.zip - -unzip geoserver.war -d /usr/local/tomcat/webapps - -mv /usr/local/tomcat/webapps/geoserver/data /usr/local/geodata - You should now change the default Geoserver password to something more secure. Execute nano /usr/local/geodata/security/users.properties and change the password and then save all changes. - Edit one of your persistent environment variables (see this page for details). Add the following lines to the chosen file. - export JAVA_HOME=/usr/lib/jvm/java-6-sun - export JDK_HOME= /usr/lib/jvm/java-6-sun - - export JAVA_OPTS=-XX:PermSize=256m -XX:MaxPermSize=1536 -Xms512m -Xmx1024m -server - - export GEOSERVER_DATA_DIR=/usr/local/geodata - - export DHIS2_HOME=/root/dhis/dhis2 - - Note that you may need to alter the file paths to point to the actual directories on your system. - Assuming that you have installed the postgresql database system, you can create a new database with the following commands. - sudo su - postgres - createdb createdb -E utf-8 dhis - Note that you can change the name of the database to anything that suits your enviornment. - To tell the DHIS2 application where to find its database you need a hibernate.properties file in DHIS2_HOME . For a postgres database connection to a database called 'dhis', with username and password 'dhis', you need to put the following inside your file /root/dhis/dhis2/hibernate.properties: - hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect - hibernate.connection.driver_class = org.postgresql.Driver - - hibernate.connection.url = jdbc:postgresql:dhis - hibernate.connection.username = dhis - hibernate.connection.password = dhis - - hibernate.hbm2ddl.auto = update - Save this file in the DHIS2_HOME directory. Exit the current shell in order to reload the enviornment 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. - sudo su - - cd /etc/init.d/ - ./S18postgresql start - Note that you may need to alter this command to your particular system. - It is good security practice to run the tomcat application as a seperate user. If you do not already have a seperate user account, you can create one with the following commands. - sudo useradd -d /home/tomcat6 -m tomcat6 - sudo passwd tomcat6 - You should not change the file permissions for the entire directory that you intsalled tomcat to, with the following command. - sudo chown -R tomcat6:tomcat6 /usr/local/tomcat - To start the application, login as the user, navigate to the /usr/local/tomcat/bin/ directory, and exectute the start.sh script. - sudo su - tomcat6 - cd /usr/local/tomcat/bin - ./startup.sh -

- Installing DHIS2 with the Debian install package - If you are using Ubuntu or Debian, a seperate Debian installation package has been created to simplify the installation process. You can simply download this file and then install DHIS2 from the command line with the following command. - sudo dpkg -i dhis2-2.0.3.deb - You can also install this Debian package from your systems package manager. -

- Logging on to DHIS2 - 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. - To log on to the application just enter http://localhost:8080/dhis 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. - Once you have started DHIS2, either online 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. - - DHIS2 Login screen - - - - - - -

- Creating new users and roles - This section will describe how to add new users to the DHIS 2 - application. -

- Open User Menu - 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. User names - already registered will appear as a list as seen in the screen shot - below. - - Select Users menu item - - - - - - - - Search by user name - - - - - - - You can search for specific user names in the user list by - entering the name in the ‘filter by username’ field as shown - above. -

- Define a new role - As part of creating a username 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. - - Create new user role - - - - - - - This will lead you to the Role Management page where you will have - to click on Add new to create a new role. - - Add new user role - - - - - - - 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. - - Role maintainence page - - - - - - - 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. - - Adding a dataset to a user role - - - - - - - In order for particular users to be able to enter data, you must - add them to both a dataset as well as an organizational unit level. You - can also select multiple datasets individually by pressing the Ctrl key - on the keyboard and clicking on individual datasets. - - Adding multiple datasets to user roles - - - - - - - Finally when you have entered the required fields click on - Save which is located on the lower part of the - displayed screen. The desired user role and related authorization will - be saved to the database, and can then be assigned to a particular - user. -

- Add New User - Under particular user role there can be more than one user. To add - new users go to the User options under the Maintenance module. - - Add new user - - - - - - - To add a new user, just follow these steps: - - - Click on the Add New button. - - - Enter New User details like User name, - Password, Confirm password, Surname, First name and Email in new user’s option - tabs. - - - Click on Add button for confirmation of - new user details and follow the user error while creation of new - user. - - - The recently created new user can be seen in main’ User - management Screen - - - You can edit (like password, surname….etc) and delete the - details of new/old users by selecting corresponding User’s - Edit and Delete - Buttons. - - - Click on Save tab after editing all - details of a particular selected user. - - Add or edit users - - - - - - - - User management screen - - - - - - - - -

- Logging off of DHIS2 - Just click on the Log off button to exit the - application. - - Logging off of DHIS 2 - - - - - - -

+ Getting started with DHIS2 + + After reading this chapter you will be able to understand: + + + Start DHIS 2 from the desktop + + + How to log-in from the desktop + + + Create new users and user roles + + + +

+ Prerequisites + 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 website for detailed information on getting java installed. + +

+ Starting the DHIS2 Live package + The DHIS2 Live package is the easiest way to get started with DHIS2. DHIS2 Live is appropirate for a stand-alone type of installation. Simply download the application from here. Once the file is downloaded, you can simply double-click the downloaded file, and get started using DHIS2. +

+ Downloading and installing the server version + 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 application can be + found here. + + 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 workgroup. 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. + You will need to decide which backend 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 backend database system, you will need a compatible servlet container. Apache Tomcat 6 is reccomended by the developers, however in principle, the application should run in any container that conforms to the Servlet 2.5 specification. + 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 backend database system (such as Postgresql and MySQL) and Servlet container. It is reccomended to use at least Postgresl version 8.3 or MySQL 5.0. + To get started downloading the necessary packages, execute the following commands. Note that you may need to add the sudo command before these commands, if you are not running as root. + apt-get install nano + wget nano /etc/apt/sources.list + Uncomment and add “multiverse” after “universe” in each line of this file. + After editing the sources.list execute these commands. + apt-get update + apt-get install sun-java6-jdk postgresql postgresql-client postgresql-contrib postgresql-8.3-postgis + 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 reccomended 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 + wget http://apache.mirror.testserver.li/tomcat/tomcat-6/v6.0.20/bin/apache-tomcat-6.0.20.tar.gz + tar xvzf apache-tomcat-6.0.20.tar.gz + mv apache-tomcat-6.0.20 /usr/local/tomcat + 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 Geoserver webpage for the latest version. + + +wget http://downloads.sourceforge.net/geoserver/geoserver-2.0.0a-war.zip + unzip geoserver-2.0.0a-war.zip + +unzip geoserver.war -d /usr/local/tomcat/webapps + +mv /usr/local/tomcat/webapps/geoserver/data /usr/local/geodata + You should now change the default Geoserver password to something more secure. Execute nano /usr/local/geodata/security/users.properties and change the password and then save all changes. + Edit one of your persistent environment variables (see this page for details). Add the following lines to the chosen file. + export JAVA_HOME=/usr/lib/jvm/java-6-sun + export JDK_HOME= /usr/lib/jvm/java-6-sun + + export JAVA_OPTS=-XX:PermSize=256m -XX:MaxPermSize=1536 -Xms512m -Xmx1024m -server + + export GEOSERVER_DATA_DIR=/usr/local/geodata + + export DHIS2_HOME=/root/dhis/dhis2 + + Note that you may need to alter the file paths to point to the actual directories on your system. + Assuming that you have installed the postgresql database system, you can create a new database with the following commands. + sudo su - postgres + createdb createdb -E utf-8 dhis + Note that you can change the name of the database to anything that suits your enviornment. + To tell the DHIS2 application where to find its database you need a hibernate.properties file in DHIS2_HOME . For a postgres database connection to a database called 'dhis', with username and password 'dhis', you need to put the following inside your file /root/dhis/dhis2/hibernate.properties: + hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect + hibernate.connection.driver_class = org.postgresql.Driver + + hibernate.connection.url = jdbc:postgresql:dhis + hibernate.connection.username = dhis + hibernate.connection.password = dhis + + hibernate.hbm2ddl.auto = update + Save this file in the DHIS2_HOME directory. Exit the current shell in order to reload the enviornment 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. + sudo su - + cd /etc/init.d/ + ./S18postgresql start + Note that you may need to alter this command to your particular system. + It is good security practice to run the tomcat application as a seperate user. If you do not already have a seperate user account, you can create one with the following commands. + sudo useradd -d /home/tomcat6 -m tomcat6 + sudo passwd tomcat6 + You should not change the file permissions for the entire directory that you intsalled tomcat to, with the following command. + sudo chown -R tomcat6:tomcat6 /usr/local/tomcat + To start the application, login as the user, navigate to the /usr/local/tomcat/bin/ directory, and exectute the start.sh script. + sudo su - tomcat6 + cd /usr/local/tomcat/bin + ./startup.sh +

+ Installing DHIS2 with the Debian install package + If you are using Ubuntu or Debian, a seperate Debian installation package has been created to simplify the installation process. You can simply download this file and then install DHIS2 from the command line with the following command. + sudo dpkg -i dhis2-2.0.3.deb + You can also install this Debian package from your systems package manager. +

+ Logging on to DHIS2 + 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. + To log on to the application just enter http://localhost:8080/dhis 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. + Once you have started DHIS2, either online 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. + + DHIS2 Login screen + + + + + + +

+ Creating new users and roles + This section will describe how to add new users to the DHIS 2 + application. +

+ Open User Menu + 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. User names + already registered will appear as a list as seen in the screen shot + below. + + Select Users menu item + + + + + + + + Search by user name + + + + + + + You can search for specific user names in the user list by + entering the name in the ‘filter by username’ field as shown + above. +

+ Define a new role + As part of creating a username 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. + + Create new user role + + + + + + + This will lead you to the Role Management page where you will have + to click on Add new to create a new role. + + Add new user role + + + + + + + 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. + + Role maintainence page + + + + + + + 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. + + Adding a dataset to a user role + + + + + + + In order for particular users to be able to enter data, you must + add them to both a dataset as well as an organizational unit level. You + can also select multiple datasets individually by pressing the Ctrl key + on the keyboard and clicking on individual datasets. + + Adding multiple datasets to user roles + + + + + + + Finally when you have entered the required fields click on + Save which is located on the lower part of the + displayed screen. The desired user role and related authorization will + be saved to the database, and can then be assigned to a particular + user. +

+ Add New User + Under particular user role there can be more than one user. To add + new users go to the User options under the Maintenance module. + + Add new user + + + + + + + To add a new user, just follow these steps: + + + Click on the Add New button. + + + Enter New User details like User name, + Password, Confirm password, Surname, First name and Email in new user’s option + tabs. + + + Click on Add button for confirmation of + new user details and follow the user error while creation of new + user. + + + The recently created new user can be seen in main’ User + management Screen + + + You can edit (like password, surname….etc) and delete the + details of new/old users by selecting corresponding User’s + Edit and Delete + Buttons. + + + Click on Save tab after editing all + details of a particular selected user. + + Add or edit users + + + + + + + + User management screen + + + + + + + + +

+ Logging off of DHIS2 + Just click on the Log off button to exit the + application. + + Logging off of DHIS 2 + + + + + + +