Welcome To iROAD Documentantion¶

What is iROAD 2?¶

Introduction to the iROAD

About The Documentation¶

The iROAD documentation is a collective effort and has been developed by the development team and users. While the guide strives to be complete, there may be certain functionalities which have been omitted or which have yet to be documented. This section explains some of the conventions which are used throughout the document.

iROAD is a browser-based application. In many cases, screenshots have been included for enhanced clarity. Shortcuts to various functionalities are displayed such as “Maintenance->Data administration”. The “->” character indicates that you should choose “Maintenance” and then click on “Data administration” in the menu which appears through the browser.

What is iROAD 2¶

Road Safety Management Information System (iROAD) is a software that intends to improve Management of Road Safety in Tanzania.

iROAD enables Car registration and use validity which involves verification of the car registration, driver and road license validity by police, customs, or TRA; Capturing, storage and use of traffic offence incidents which involves recording of traffic offence incidences when they occur by police or reported by the community (witness or victim), notification and-or educating of the offender by police about the offence(s) committed and tracking of the payment of fines or court decisions that result from the offence(s); Recording and transmitting accident scene which involves recording of traffic accident incidences when they occur by police,notification and locating of the accident reported by the community (witness or victim).

iROAD is a loosely coupled modular web based software bundle that is built with free and open source PHP >= 5.3 Web Frameworks. Among the frameworks Involves;

• Laravel PHP Web Development Framework
• Angular JS as a scripting language
• Google Angular Material Design for presentation layer
• Composer Package manager

iROAD Background¶

The iROAD software is developed by the University of Dar es salaam to help reducing accidents and offences occurring on Tanzania’s roads

through linking of the stakeholders involved in road safety to improve information sharing and dissemination.

The software should serve for the following data use.

• Reduce accidents through prompt reporting of traffic offences
• Time serving in dealing with traffic accidents through Notification / Alerts
• Appropriateness of reported information related to road safety
• Locating accidents using GIS
• Tracking/Verification of licenses and cars registration
• Raising awareness of road safety to drivers and general public
• Facilitate the management of reported road safety cases
• Linking the stakeholders involved in road safety to improve information sharing and dissemination

Key features and purpose of iROAD 2¶

• Faster response and less greedy on system resources HRIS was conceived from the start to be fast and to favor performance, its based on laravel Framework that uses Symphony and is about 3 times faster than ZendFramework 1.10 while taking 2 times less memory.
• Unlimited flexiblity through customization Whatever your needs are, HRIS will be adaptable. Its customizable capacity makes it entirely configurable, with less required to be done. Its also extensible, based on framework dependency injection and event dispatchers, more modules can be pluged in with simplicity. iROAD is distributed under GNU General Public Licence which does allow modification and extension of existing features.
• Ease of use through intuitive, user-friendly interfaces Simple and Flexible user interfaces allows performing advanced tasks simply and intuitively, which allows begginers to the system to quickly feel at ease with iROAD
• Stable and sustainable The system is in-built with self system tests, that ensures shipped system behaves and performs what is needed with guaranteed compatibility between versions
• Inteoperable Through Web APIs, iROAD can be interoperated by third party applications through the powerful RESTful APIs

Use of iROAD 2: data collection, processing, interpretation, and analysis.¶

iROAD 2 supports the different facets of the information cycle including:

• Collecting data.
• Running quality checks.
• Data access at multiple levels.
• Reporting.
• Making graphs and maps and other forms of analysis.
• Enabling comparison across time (for example, previous months) and space (for example, across facilities and districts).
• See trends (displaying data in time series to see their min and max levels).

As a first step, iROAD 2 serves as a data collection, recording and compilation tool, and all data (be it in numbers or text form) can be entered into it. Data entry can be done in lists of data elements or in customised user defined forms which can be developed to mimic paper based forms in order to ease the process of data entry.

As a next step, iROAD 2 can be used to increase data quality. First, at the point of data entry, a check can be made to see if data falls within acceptable range levels of minimum and maximum values for any particular data element. Such checking, for example, can help to identify typing errors at the time of data entry. Further, user can define various validation rules, and iROAD 2 can run the data through the validation rules to identify violations. These types of checks help to ensure that data entered into the system is of good quality from the start, and can be improved by the people who are most familiar with it.

When data has been entered and verified, iROAD 2 can help to make different kinds of reports. The first kind are the routine reports that can be predefined, so that all those reports that need to be routine generated can be done on a click of a button. Further, iROAD 2 can help in the generation of analytical reports through comparisons of for example indicators across facilities or over time. Graphs, maps, reports and health profiles are among the outputs that iROAD 2 can produce, and these should routinely be produced, analysed, and acted upon by health managers.

Technical background¶

iROAD as a platform¶

iROAD can be perceived as a platform on several levels. First, the application database is designed ground-up with flexibility in mind. Data structures such as data elements, organisation units, forms and user roles can be defined completely freely through the application user interface. This makes it possible for the system to be adapted to a multitude of locale contexts and use-cases. We have seen that iROAD supports most major requirements for routine data capture and analysis emerging in country implementations. It also makes it possible for iROAD to serve as management system for domains such as logistics, labs and finance.

Second, due to the modular design of iROAD it can be extended with additional software modules. These software modules can live side by side with the core modules of iROAD and can be integrated into the iROAD portal and menu system. This is a powerful feature as it makes it possible to extend the system with extra functionality when needed, typically for country specific requirements as earlier pointed out.

Understanding platform independence¶

All computers have an Operating System (OS) to manage it and the programs running it. The operating system serves as the middle layer between the software application, such as iROAD 2, and the hardware, such as the CPU and RAM. iROAD 2 runs on the Java Virtual Machine, and can therefore run on any operating system which supports Java. Platform independence implies that the software application can run on ANY OS - Windows, Linux, Macintosh etc. iROAD 2 is platform independent, and is extremely useful in the context of public health, where multiple operating systems may be in use.

Furthermore, iROAD 2 is also platform independent when it comes to the Database Management System (DBMS). iROAD 2 uses the Hibernate database abstraction framework and is compatible with any DBMS supported by Hibernate, such as PostgreSQL, MySQL, H2, MS SQL Server, Oracle and many more. PostgreSQL is the recommended DBMS for iROAD 2.

Lastly, and perhaps most importantly, since iROAD2 is a browser-based application, the only real requirement to interact with the system is with a web browser. iROAD2 supports most web browsers, although currently either Google Chrome, Mozilla Firefox or Opera are recommended.

Deployment strategies - online vs offline¶

iROAD 2 is a network enabled application and can be accessed over the Internet, a local intranet and as a locally installed system. The deployment alternatives for iROAD 2 are in this chapter defined as i) offline deployment ii) online deployment and iii) hybrid deployment. The meaning and differences will be discussed in the following sections.

Offline Deployment¶

An offline deployment implies that multiple standalone offline instances are installed for end users, typically at the district level. The system is maintained primarily by the end users/district health officers who enters data and generate reports from the system running on their local server. The system will also typically be maintained by a national super-user team who pay regular visits to the district deployments. Data is moved upwards in the hierarchy by the end users producing data exchange files which are sent electronically by email or physically by mail or personal travel. (Note that the brief Internet connectivity required for sending emails does not qualify for being defined as online). This style of deployment has the obvious benefit that it works when appropriate Internet connectivity is not available. On the other side there are significant challenges with this style which are described in the following section.

Hardware: Running stand-alone systems requires advanced hardware in terms of servers and reliable power supply to be installed, usually at district level, all over the country. This requires appropriate funding for procurement and plan for long-term maintenance.

Software platform: Local installs implies a significant need for maintenance. From experience, the biggest challenge is viruses and other malware which tend to infect local installations in the long-run. The main reason is that end users utilize memory sticks for transporting data exchange files and documents between private computers, other workstations and the system running the application. Keeping anti-virus software and operating system patches up to date in an offline environment are challenging and bad practices in terms of security are often adopted by end users. The preferred way to overcome this issue is to run a dedicated server for the application where no memory sticks are allowed and use an Linux based operating system which is not as prone for virus infections as MS Windows.

Software application: Being able to distribute new functionality and bug-fixes to the health information software to users are essential for maintenance and improvement of the system. Relying on the end users to perform software upgrades requires extensive training and a high level of competence on their side as upgrading software applications might a technically challenging task. Relying on a national super-user team to maintain the software implies a lot of traveling.

Database maintenance: A prerequisite for an efficient system is that all users enter data with a standardized meta-data set (data elements, forms etc). As with the previous point about software upgrades, distribution of changes to the meta-data set to numerous offline installations requires end user competence if the updates are sent electronically or a well-organized super-user team. Failure to keep the meta-data set synchronized will lead to loss of ability to move data from the districts and/or an inconsistent national database since the data entered for instance at the district level will not be compatible with the data at the national level.

Online deployment¶

An online deployment implies that a single instance of the application is set up on a server connected to the Internet. All users (clients) connect to the online central server over the Internet using a web browser. This style of deployment currently benefits from the huge investments in and expansions of mobile networks in developing countries. This makes it possible to access online servers in even the most rural areas using mobile Internet modems (also referred to as dongles).

This online deployment style has huge positive implications for the implementation process and application maintenance compared to the traditional offline standalone style:

Hardware: Hardware requirements on the end-user side are limited to a reasonably modern computer/laptop and Internet connectivity through a fixed line or a mobile modem. There is no need for a specialized server for each user, any Internet enabled computer will be sufficient. A server will be required for online deployments, but since there is only one (or several) servers which need to be procured and maintained, this is significantly simpler (and cheaper) than maintaining many separate servers is disparate locations.

Software platform: The end users only need a web browser to connect to the online server. All popular operating systems today are shipped with a web browser and there is no special requirement on what type or version. This means that if severe problems such as virus infections or software corruption occur one can always resort to re-formatting and installing the computer operating system or obtain a new computer/laptop. The user can continue with data entry where it was left and no data will be lost.

Software application: The central server deployment style means that the application can be upgraded and maintained in a centralized fashion. When new versions of the applications are released with new features and bug-fixes it can be deployed to the single online server. All changes will then be reflected on the client side the next time end users connect over the Internet. This obviously has a huge positive impact for the process of improving the system as new features can be distributed to users immediately, all users will be accessing the same application version, and bugs and issues can be sorted out and deployed on-the-fly.

Database maintenance: Similar to the previous point, changes to the meta-data can be done on the online server in a centralized fashion and will automatically propagate to all clients next time they connect to the server. This effectively removes the vast issues related to maintaining an upgraded and standardized meta-data set related to the traditional offline deployment style. It is extremely convenient for instance during the initial database development phase and during the annual database revision processes as end users will be accessing a consistent and standardized database even when changes occur frequently.

This approach might be problematic in cases where Internet connectivity is volatile or missing in long periods of time. iROAD2 however has certain features which requires Internet connectivity to be available only part of the time for the system to work properly, such as offline data entry and the MyDatamart tool presented in a separate chapter in this guide, which cater to information flow in situations when Internet connectivity may be challenging.

Hybrid deployment¶

From the discussion so far one realizes that the online deployment style is favourable over the offline style but requires decent Internet connectivity where it will be used. It is important to notice that the mentioned styles can co-exist in a common deployment. It is perfectly feasible to have online as well as offline deployments within a single country. The general rule would be that districts and facilities should access the system online over the Internet where sufficient Internet connectivity exist, and offline systems should be deployed to districts where this is not the case.

Defining decent Internet connectivity precisely is hard but as a rule of thumb the download speed should be minimum 10 Kbyte/second and accessibility should be minimum 70% of the time.

In this regard mobile Internet modems which can be connected to a computer or laptop and access the mobile network is an extremely capable and feasible solution. Mobile Internet coverage is increasing rapidly all over the world, often provide excellent connectivity at low prices and is a great alternative to local networks and poorly maintained fixed Internet lines. Getting in contact with national mobile network companies regarding post-paid subscriptions and potential large-order benefits can be a wort-while effort. The network coverage for each network operator in the relevant country should be investigated when deciding which deployment approach to opt for as it might differ and cover different parts of the country.

Server hosting¶

The online deployment approach raises the question of where and how to host the server which will run the iROAD 2 application. Typically there are several options:

Internal hosting within the Ministry of Health

Hosting within a government data centre

Hosting through an external hosting company

The main reason for choosing the first option is often political motivation for having physical ownership of the database. This is perceived as important by many in order to own and control the data. There is also a wish to build local capacity for server administration related to sustainability of the project. This is often a donor-driven initiatives as it is perceived as a concrete and helpful mission.

Regarding the second option, some places a government data centre is constructed with a view to promoting and improving the use and accessibility of public data. Another reason is that a proliferation of internal server environments is very resource demanding and it is more effective to establish centralized infrastructure and capacity.

Regarding external hosting there is lately a move towards outsourcing the operation and administration of computer resources to an external provider, where those resources are accessed over the network, popularly referred to as cloud computing or software as a service. Those resources are typically accessed over the Internet using a web browser.

The primary goal for an online server deployment is provide long-term stable and high-performance accessibility to the intended services. When deciding which option to choose for server environment there are many aspects to consider:

Human capacity for server administration and operation. There must be human resources with general skills in server administration and in the specific technologies used for the application providing the services. Examples of such technologies are web servers and database management platforms.

Reliable solutions for automated backups, including local off-server and remote backup.

Stable connectivity and high network bandwidth for traffic to and from the server.

Stable power supply including a backup solution.

Secure environment for the physical server regarding issues such as access, theft and fire.

Presence of a disaster recovery plan. This plan must contain a realistic strategy for making sure that the service will be only suffering short down-times in the events of hardware failures, network downtime and more.

Feasible, powerful and robust hardware.

All of these aspects must be covered in order to create an appropriate hosting environment. The hardware requirement is deliberately put last since there is a clear tendency to give it too much attention.

Looking back at the three main hosting options, experience from implementation missions in developing countries suggests that all of the hosting aspects are rarely present in option one and two at a feasible level. Reaching an acceptable level in all these aspects is challenging in terms of both human resources and money, especially when compared to the cost of option three. It has the benefit that is accommodates the mentioned political aspects and building local capacity for server administration, on the other hand can this be provided for in alternative ways.

Option three - external hosting - has the benefit that it supports all of the mentioned hosting aspects at a very affordable price. Several hosting providers - of virtual servers or software as a service - offer reliable services for running most kinds of applications. Example of such providers are Linode and Amazon Web Services. Administration of such servers happens over a network connection, which most often anyway is the case with local server administration. The physical location of the server in this case becomes irrelevant as that such providers offer services in most parts of the world. This solution is increasingly becoming the standard solution for hosting of application services. The aspect of building local capacity for server administration is compatible with this option since a local ICT team can be tasked with maintaining the externally hosted server, but with not being burdened with worrying about power supply and bandwidth constraints which usually exist outside of major data centres.

An approach for combining the benefits of external hosting with the need for local hosting and physical ownership is to use an external hosting provider for the primary transactional system, while mirroring this server to a locally hosted non-critical server which is used for read-only purposes such as data analysis and accessed over the intranet.

Getting Started with iROAD 2¶

Getting started with DHIS 2

Getting started with iROAD 2¶

After reading this chapter you will be able to understand:

• Start iROAD 2 from the desktop
• How to log-in from the desktop
• Create new users and user roles
• What steps are needed to design a iROAD 2 database for your organisationThe iROAD documentation is a collective effort and has been developed by the development team and users. While the guide strives to be complete, there may be certain functionalities which have been omitted or which have yet to be documented. This section explains some of the conventions which are used throughout the document.

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.

Installing iROAD¶

PHP5-INTL Dependency

On Systems running Linux Operating systems run:

sudo apt-get install php5-intl

On Systems running Mac OSX Operating systems run:

brew install icu4c

Download system source codes from our github repository - https://github.com/MorleyMinde/rsmsa:

https://github.com/MorleyMinde/rsmsa.git

Install composer inside project directory - hris Note: hris now comes with composer pre-installed:

curl -s https://getcomposer.org/installer | php

Note

If you don’t have curl, install composer with this script php -r “eval(‘?>’.file_get_contents(‘https://getcomposer.org/installer‘));”

Update your repository with latest dependecies:

php composer.phar install

php composer.phar update

Symbolic Link your web directory to the webroot directory:

ln -s ${PWD}/web/ /var/www/rsmsa     #Assuming your current directory(PWD) is inside hris project and your webroot is on /var/www/

Set date time zone inside php.ini to your location,change line date.timezone to your locale, e.g in Dar-es-salaam, Tanzania:

date.timezone = 'Africa/Dar_es_Salaam'

Turn off short_open_tag inside php.ini to disable detection of PHP codes between <? and ?> for better PHP >=5.3 Experience:

short_open_tag = Off

Give Web readwrite access to cache and log directory in your hris directory. To enjoy both user and web read-write access in linux use the following commands:

rm -rf app/cache/*

rm -rf app/logs/*

On Systems supporting chmod +a(e.g. Mac), you can give readwrite permission via:

sudo chmod +a "www-data allow delete,write,append,file_inherit,directory_inherit" app/cache app/logs

sudo chmod +a "`whoami` allow delete,write,append,file_inherit,directory_inherit" app/cache app/logs

On Systems that don’t support chmod +a(e.g. Linux), you can give readwrite permission via:

sudo setfacl -R -m u:www-data:rwx -m u:`whoami`:rwx app/cache app/logs

sudo setfacl -dR -m u:www-data:rwx -m u:`whoami`:rwx app/cache app/logs

Database Setup¶

System source code can be downloaded from github

Configuration file can be found from rsmsa/app/config/database.php

database.php:

'mysql' => array(
        'driver'    => 'mysql',
        'host'      => 'localhost',
        'database'  => 'rsmsa',
        'username'  => 'root',
        'password'  => '',
        'charset'   => 'utf8',
        'collation' => 'utf8_unicode_ci',
        'prefix'    => '',
),

To generating database,go to the command prompt and run the following commands.:

php artisan migrate                             #Creates Fresh new database
php artisan db:seed                             #seeds startup data to the database

Creating, Activating,Changing password, deactivate, demote & promote login-user from commandline:

app/console fos:user:create                     #Create User account
app/console fos:user:activate                   #Activate a user
app/console fos:user:change-password            #Change the password of a user.
app/console fos:user:create                     #Create a user.
app/console fos:user:deactivate                 #Deactivate a user
app/console fos:user:demote                     #Demote a user by removing a role
app/console fos:user:promote                    #Promotes a user by adding a role

Regenerating assets:

app/console assetic:dump
php app/console assets:install web

Shell Console:

app/console --shell

Description of the System¶

This part is intended to give user an insight on how to use the system and access different features and system components.

Logging on to iROAD 2¶

Open the browser and type the following address: http://www.roadsafety.udsm.go.tz then a page similar to the one shown in the image below will be displayed whereby a user will be required to type in their correct username and password. In the instance where one does not have a username or password please see register information following next. This system works best with Mozilla Firefox, Google Chrome or Opera browsers. From here on, the use of the word browser will refer to above mentioned web browsers only.Open the browser and type the following address: then a page similar to the one shown in the image below will be displayed whereby a user will be required to type in their correct username and password. In the instance where one does not have a username or password please see register information following next. This system works best with Mozilla Firefox, Google Chrome or Opera browsers. From here on, the use of the word browser will refer to above mentioned web browsers only.

fig 1.1: Image showing login Interface.

Upon successful login, a user will be directed to the page with the menu on the left hand side through which he can access various parts of the system (see figure 1.3 below). However on unsuccessful login an error message will be displayed (see figure 1.2 below) and you will be required to re-type the username and password.

fig 1.2: Image showing error message displayed on unsuccessful login.

fig 1.3: Image showing iROAD home page on successful Login.

Registering on to iROAD 2¶

In the case where one does not have a username or password, they will be required to first register themselves in order to have an account in the system. To do so; besides the login page, there is a register tab. On selecting it, a page similar to one shown below (Figure 1.4 below) will appear requesting the new user to fill in all required details and submit them by clicking the Register button. After doing so an email to activate the account will be sent to the users email account provided during registration; and the registering user will be prompted to visit their email and follow link sent for activating their account. These steps so far, will enable for an account to be created but access to information already in the system will still not be possible until verification of user is done by the help desk team who will then assign new user to an organization unit for complete registration.

fig 2.1: Image showing Register Page for new user.

User profile¶

User profile enables a user to view their profile, customize dashboard reports, view settings, change user password or log out of the system. To access the user profile click on the username and a drop down list as seen in the diagram will appear.

fig 4.3: Image showing User Profile options.

Change password¶

In the instance where a user wants to change his/her password, the Change Password? link on the login page is there to assistance. On clicking the link a user will be sent to a page as shown in the Figure 3.1 and required to provide the current password and the new password.After that the user shoul click on the “SUBMIT” button and he/she will have a new password.

fig 3.1: Image showing required details for changing password.

Home page¶

On successful login, a user is directed to the Home Page which consists of the main menu on the right side and dashboard charts in the middle.

fig 4.1: User Home Page displaying interactive components.

Services¶

On the Home page there is a link on the right hand side written “Services” that will direct you to the services the system offers.Figure below shows the services page.

fig 4.1: User Home Page displaying interactive components.

Quick intro to designing a iROAD 2 database¶

The iROAD 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.

This section will provide a very quick and brief introduction to iROAD 2 database design and mainly explain the various steps needed to prepare a new iROAD 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:

• Set up an organisational hierarchy
• Define data elements
• Define data sets and data entry forms
• Define validation rules
• Define indicators
• Define report tables and design reports
• Set up the GIS module
• Design charts and customise the dashboard

The organisational hierarchy¶

The organisational hierarchy defines the organisation using the iROAD 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 iROAD 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 groupings such as “Facility ownership”) can be modelled using organisational groups and group sets, however 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. Too 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.

Data Elements¶

The Data Element is perhaps the most important building block of a iROAD 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 iROAD 2 we call this unit of collection and analysis a data element. 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.

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.

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.

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.

Datasets and data entry forms¶

All data entry in iROAD 2 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 iROAD 2 (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.

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.

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).

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.

Data entry forms¶

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.

Section forms¶

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 categories 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 dataset 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.

Custom Forms¶

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 iROAD 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.

Validation rules¶

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 occurred to make it easy to go back to data entry and correct the values.

Indicators¶

Indicators represent perhaps the most powerful data analysis feature of the iROAD 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”).

Most report modules in iROAD 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.

Indicators can be added, modified and deleted at any point in time without interfering with the data values in the database.

Report tables and reports¶

Standard reports in iROAD 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.

GIS¶

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 quickly get up to speed with this module. See the GIS section for details on how to get started.

Charts and dashboard¶

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.

Administrative units¶

Administrative units

Administrative units Hierarchy¶

In this section you will learn how to:

• Create a new administrative unit and build up the administrative unit hierarchy
• Create administrative unit groups, group sets, and assigning administrative units to them
• How to make changes to the administrative unit hierarchy

The administrative hierarchy¶

The administrativeal hierarchy defines the administrative structure of the iROAD2 instance, such as how the health facilities, administrative areas and other geographical areas are arranged with respect to each other. It is essentially the “where” dimension of iROAD2, similar to how periods represent the “when” or time dimension. iROAD2 is structured so that the administrativeal unit hierarchy is a geographical hierarchy, and the GIS module depends on this. Non-geographical hierarchies are discouraged, and would better to be represented through the use of administrativeal unit groups. This dimension to the data is defined as a hierarchy with one root unit (e.g. Ministry of Health or a country) and any number of levels and nodes below. Each node in this hierarchy is called an administrativeal unit in iROAD2.

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 administrativeal 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 modeled using administrativeal groups and group sets, but the administrativeal hierarchy is the main vehicle for data aggregation on the geographical dimension. Typically national administrativeal hierarchies in public health have 4-6 levels, but any number of levels is supported.

The hierarchy is built up of parent-child relations. For instance a country might have eight provinces, and each province again might have a number of districts as their children. Normally the health facilities (from which data is typically collected) will be located at the lowest level, but they can also be located at higher levels, e.g. national or provincial hospitals, so skewed administrativeal trees are supported (e.g. a leaf node can be positioned at level 2 while most other leaf nodes are at level 5).

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 administrativeal 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 administrativeal structure.

Important:

Because the most recent information which is contained in the administrativeal unit hierarchy is always used for aggregation, it is important to keep in mind that changes to it (such as the division of districts into two separate districts) will not be respected over time. As an example, District A may be sub-divided into District B and District C. This is a process which often happens for political reasons. Facilities which belong to District A would need to be reassigned to District B and C. However, any historical data, which was entered before the split actually occurred, would still be registered as belonging to District B and C and not the defunct District A. This temporal representation of the administrativeal hierarchy across time will be lost.

Administrative unit maintenance¶

Administrative units¶

This is where you can create administrative units (from now on referred to as orgunits) and build up the orgunit hierarchy. Orgunits are added one by one as either root unit or a child of a selected unit. The left side menu represents the current administrativeal hierarchy and if you select a unit there you will see its children listed in the main list of orgunits in the middle of the screen. When an orgunit is selected in the left side menu you can also add new child units to it. To locate an orgunit in the hierarchy you can either navigate through the tree by expanding the branches (click on the + symbol), or search for it by opening the search field (click the green symbol above the root of the hierarchy). In search you can either search for the orgunit name or its code, both will only show exact matches (case-insensitive). To add a new orgunit first select its parent and then click on the Add new button in the top right corner of the list of orgunits. To add a new root orgunit make sure no orgunit is selected in the menu and click on “Add new”.

Editing administrative units¶

To edit the properties of an existing orgunit first select its parent (if any) in the left side menu, then locate the orgunit in the listed orgunits, and click on the name of the orgunit that you want to modify. A context menu will appear, and you should select “Edit”. Refer to the screen-shot below to see how it works.

The following properties can be defined in the Edit (or Create new) window:

• Name: Define the precise name of the orgunit in this field. Each orgunit must have a unique name.
• Short name: Typically, an abbreviation of the full name. This attribute is often used in reports to display the name of the orgunit, where there is limited space available.
• Code: In many countries, orgunits are assigned a code. This code can be entered in this field.
• Description: A description can be a longer piece of text which can be used to describe the administrativeunit.
• Opening date: Used to control which orgunits that where existing at a point in time, e.g. when analysing historical data. This attribute is required. The default date for opening of administrative units is 1900-01-01, but can be set to any date (even dates which occur in the future).
• Registers data: This property is used to identify which orgunits that can register data or not. Sometimes administrative orgunits at higher levels in the hierarchy are not supposed to register any data. This can help control the data entry process as only orgunits with this property set to Yes will be available for data entry.
• Comment: Any additional information that you would like to add can be put here.
• Coordinates: This field is used to create the maps in the GIS module. Paste in the coordinates of the orgunit in this field, either a polygon (for orgunits that represent an administrative boundary) or a point (for health facilities). Without this information the GIS module will not work. It might be more efficient to import these coordinates later as a batch job for all orgunits using the import module. See the GIS chapter for more details.
• URL: You can use this field to insert a URL link to an external web site that has additional information about this specific orgunit.
• Contact information: A contact person, address, email, and phone number can be entered in these fields. This information can be vital for facilitating follow-up.
• Datasets: Datasets can be assigned to administrativeal units here. See the chapter on “Data sets” for more detailed information on assigning datasets to administrativeal units.
• administrative unit groups: Assignments to administrativeal units group sets can be assigned through the individual drop-down boxes which appear for each group set.

In addition to all of the options listed above, if you have added any attributes to administrative units, your custom attributes may also appear there. Please refer to the section on “Attributes” for more information about how attributes can be used.

Organisation unit group sets¶

Group sets can be understood as a flexible tool to add more categorisation to orgunits. Any number of group sets can be added, but as a default start all databases will have the two group sets “Type” and “Ownership”. Using these group sets will simplify how reporting is done, and facilitate analysis through the use of tools such as Excel PivotTables.

While a group set like “Type” describes a measure dimension, the actual categories are represented by the groups, and the categorisation of an orgunit through the orgunit’s group memberships. This can be understood as a parallel hierarchy of orgunits with the group set as the root (“Type”), the groups at level 2 (e.g. “Clinic”, “Hospital”, “Dispensary”), and the actual orgunits at level 3. The group set can as such provide additional information and dimensionality to the data analysis as data is easily filtered, organised, or aggregated by groups within a group set.

For this aggregation to work without any duplication in the data some rules are necessary. A group set is always exclusive, which means that an orgunit cannot be member of more than one group in a group set. Therefore, when creating a new organisational unit, you will only be allowed to select a single organisational group membership for each group set. Furthermore it is possible to define whether a group set is compulsory or not, which will affect the completeness of the data when analysing data using group sets. Compulsory means that ALL orgunits must be member of a group in that group set.

We recommend that you approach the orgunit grouping in the following sequence (and one group set at a time):

Define a new group set, such as “Location”.

Add new groups (such as “Urban”, “Rural” and “Peri-urban”). Once all groups have been defined, return to the organisational unit group set and assign each of the desired groups to the group set.

Go back to each group, one by one, go to edit mode and assign the orgunits that should be member of the group. Should you follow this route, you can place multiple organisation units at a time in a group. However, you must be careful not to place the same organisational units in two groups which itself is a member of an organisation unit group set. This will result in a data integrity violation. If you have organisation unit groups which are not exclusive, they should not be members of a group.

A better way to ensure that you do not mistakenly assign an organisation unit to multiple members of a group set is you can use the edit feature of each organisational unit to assign memberships to each group set. You will only be able to assign a single organisation unit at a time however.

It is important to keep in mind when using the “Organisational unit group” set function, that unless great care is taken, organisational units can be assigned to multiple groups of a group set. This can be checked through the “Data Integrity” module, which will report which organisational units are not members of a compulsory organisational unit group set, and which organisational units have been assigned to more than one member of a group set.

Editing organisation unit group sets¶

Click on the name of the organisation unit group set you wish to modify, followed by “Edit” from the context menu which will appear. The following properties can be defined in the Edit (or Create new) window:

• Name: Provide a precise name for the group set.
• Description: Describe the phenomena the group set is measuring/capturing.
• Compulsory: Indicate whether ALL orgunits need to be member of a group in this group set or not.
• Available groups/Selected groups: Here you assign groups to your group set by using the arrow buttons to move highlighted groups between the two lists (/selected). If no groups appear in the list then you must go to orgunit groups and create new groups there first. Note that assigning groups that will violate the exclusive rule on group sets is not possible, e.g. adding a group that already has assigned an orgunit that again is already member of a group that has already been selected by this group set, will not be possible since one orgunit will end up with two group memberships in the same group set. To avoid such situations we recommend first adding groups to group sets, and then orgunits to groups.

Organisation unit groups¶

This function will allow you to add new and manage existing organisation groups and their memberships. It can be accessed by choosing Maintenance->Organisation units->Organisation Unit group from the main menu. To add a new orgunit group click on the “Add new” button in the top right corner of the list of groups.

Editing organisation unit groups¶

Click on name of the orgunit group that you want to modify and then select “Edit” from the context menu which will appear. The following properties can be defined in the Edit (or Create new) window:

• Name: Provide a precise,unique and descriptive name for the orgunit group.
• Short name: This name should be less than 25 characters, and will be used in certain places in DHIS2 when the number of characters needs to be restricted due to space constraints.
• Symbol: Select a symbol which will be used to display the organisation unit (points only) when the layer is displayed in the GIS.
• Organisation unit tree selection: This is where you assign orgunits to the group. The tree supports multiple selection so select all the orgunits that you want to add (the selected ones appear with orange color) and click on “Save”. Click on “Cancel” to undo your changes and return to the list of orgunit groups. Use the “Select at level” button and dropdown if you want to select all orgunits at a specific level in the hierarchy (e.g. all districts).
• Datasets: If you assign a dataset to an organisational unit group, all organisation units which are currently assigned to the dataset will be also present in this organisation unit group.

Organisation unit level¶

Here you specify a contextual name for each level in the hierarchy, e.g. “Country”, “Province”, “District”, “Health Facility”, and these names will be used all over the application where levels are referred to. This page will take some time to load if the orgunit hierarchy is very big.

Hierarchy operations¶

Here you can move orgunits around in the hierarchy by changing the parent of a selected orgunit. This process is done in three steps:

1. Select the orgunit you want to move (in the hierarchy in the left side menu) and click “Confirm” under the “Select an organisation unit to move” label.
2. Select the new parent orgunit (again by using the hierarchy in the left side menu). If no parent is selected then the orgunit will be moved up to root level (top of the hierarchy). Click on the “Confirm” button under the “Select the new parent organisation unit for the one to move” label.
3. Click on the “Move” button to apply your changes to the hierarchy.

Your changes will be immediately reflected in the left side menu hierarchy. At any time in the process (before hitting the Move button) you can click on the “Reset” button to deselect orgunit to move and the new parent.

Events DataElements¶

When the Data Elements and Indicators options is chosen from the main Maintenance menu, the following screen appears:

From the left side menu or by clicking on the sections listed in the central area you can access the various sections on data elements and indicators.

Each of the options for maintenance of data elements will be described in the following section.

• Data element
• Create, modify, view and delete data elements.
• Data element group
• Create, modify, view and delete data element groups.
• Data element group editor
• Easily add or remove data elements to and from data element groups.
• Data element group set editor
• Create, modify, view and delete data elements group sets.
• Data element category options, categories and category combinations
• Create, modify, view and delete data element categories.

Data elements¶

Data elements form the basis of iROAD2. Data elements define what is actually recorded in system, e.g. number of immunisations or number of cases of malaria. The actual creation and definition 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 standardised data elements for inclusion into the iROAD2 system.

To access the data element maintenance module, choose Maintenance -> Data elements and Indicators -> 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 and any matching data elements are displayed below. The ‘Sort’ button can be used to sort the data elements into alphabetical order.

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¶

To edit an existing data element, click the name of data element you wish to modify, and then select “Edit” from the context menu which will appear.

• Name: Define the precise name of the data element in this field. Each data element must have a unique name.
• 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.
• 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.
• Active: Defines whether a given data element is active or not. Data elements marked as inactive, will not be displayed in the data entry screens.
• Domain type: Defines whether a data element is an aggregate or patient type of data element.
• Value type: Defines the type of data this data element will be used to record. Currently there are five options:

1. Number: Numeric values.
2. Text: Textual values. The maximum number of characters which are allowed by the system is 60,000.
3. Yes/No: Boolean values, will render as drop-down lists in data entry.
4. Yes only: True values, will render as check-boxes in data entry.
5. Date: Dates, will render as calendar widget in data entry.
6. User name: This will be populated with the username of the user which performs data entry automatically during the data entry process.
7. Number type: iROAD 2 supports several different number types. During data entry, users will be restricted to enter the defined number types only. Each of the available options are described below.

• Number: This number type supports any real value with a single decimal point, an optional negative sign, and no thousands separators.

1. Integer: Any whole number (positive and negative), including zero.
2. Positive integer: Any whole number greater than (but not including) zero.
3. Negative integer: Any whole number less than (but not including) zero.
4. Positive or zero integer: Any whole number greater than or equal to zero.
5. Unit interval: Continuous number between 0 and 1.
6. Percentage: Whole number inclusive between 0 and 100.

• Text type: The detailed type relevant to text value type.

1. Text: Free text, rendered as standard input field.
2. Long text: Free text, rendered as text area in data entry.

• Aggregation operator: Defines the default aggregation operation that will be used on this data element. Most data elements should have the “SUM” option set. This includes all data elements which should be added together. Other data elements, such as staffing levels, should be set to use the “AVERAGE” operator, when values along the time dimension should not be added together, but rather averaged. The complete list of aggregation operators:

1. Sum: Sum of data values in the period and organisation unit dimension
2. Average (sum in orgunit hierarchy): Average of data values in the period dimension, sum in the organisation unit dimensions.
3. Average: Average the values in both the period as well as the orgunit dimensions.
4. Count: Count of data values.
5. Standard deviation: Standard deviation (population-based) of data values.
6. Variance: Variance (population-based) of data values.
7. Min: Minimum of data values.
8. Max: Maximum of data values.

• Store Zero Data Value: By default, iROAD2 will not store zeros which are entered in the data entry module. If zeros need to be saved for a particular reason, this option can be set to “Yes”.
• URL: A URL having an in-depth description of the data element can be entered in the URL field. This could be for instance, a link to a metadata repository or registry that contains detailed technical information about the definition and measurement of the data element.
• Category Combination: Defines which category combination the data element should have, also known as the “disaggregation”.
• Aggregation levels: The Aggregation Levels option allows the data element to be aggregated at one or more levels. When the user clicks on the Aggregation levels option, a drop down menu appears which displays available aggregation levels. The desired aggregation level is then selected by clicking the “Add Selecte” button. By default, the aggregation will start at the lowest assigned organisation unit. If e.g. Chiefdom is selected below it means that Chiefdom, District, and National aggregates will use Chiefdom (the highest aggregation level available) as the data source, and PHU data will not be included. PHU data will still be available for the PHU level, but not included in aggregations to the levels above. If District and Chiefdom are both selected then the District and National level aggregates will use District data as their source, Chiefdom will use Chiefdom, and PHU will use PHU. Read more about aggregation levels in the Reporting chapter i the section on data sources for reporting.
• Option set for data values: Option sets are predefined lists of options which can be used in data entry.
• Option set for comments: Option sets for comments are predefined list of options which can be used to specify standardized comments for data values in data entry.
• Legend set: Legend sets can be used in the GIS module to display certain data elements with certain icons. Refer to the GIS module documentation for more information on legend sets.
• Attributes: Data element attributes (if they have been defined) can be defined. In this example, “Rationale” and “Unit of measure” are both data element attributes.
• Data element group sets: If data element group sets have been defined, each will appear in the “Data element groups” section. Select each data element group from the list of group sets provided.

After making all the required changes, click “Save”. The “Cancel” button aborts all changes made.

Deleting a data element¶

In order to delete a data element, click the name of the data element you wish to delete, and then select “Remove” from the context menu. Note that this operation is only possible if there is no data attached to the data element itself. The user will be prompted to ensure that the data element should be deleted.

Displaying data element details¶

This operation displays an in-line panel in the browser which displays all metadata about a given data element. Click the name of the data element and then select “Show details” from the context menu.

Data element groups¶

Data element groups provide a mechanism for classifying related data elements into a common theme. For instance, two data elements “Measles immunisation” and “BCG Immunisation” might be grouped together into a data element group “Childhood immunisation”. To access the data element group maintenance page, click Maintenance -> Data elements and Indicators -> Data Element Group.

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 and the following screen will be displayed:

Fill in the “Name” field and then select all data elements that should belong to the group from the left panel. Click the “Move selected” button to add the selected data elements to the data element group. Click the “Remove selected” button to remove all data elements from the group that have been selected in the right panel. Finally, click the “Add” button to save changes, or the “Cancel” button to discard any changes.

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, go to “Maintenance -> Data elements and Indicators -> Data Element Group Editor”. The following screen will appear.

Data element groups area listed alphabetically in the leftmost panel. By clicking on a data element group, the current members of that group (data elements) are listed in the centre panel. Available data elements that can be added to the data element group appear are listed alphabetically in the rightmost panel. To remove an existing data element from the group, click the name of the data element in the centre panel, and then press the “Move right” button. To add data elements to the group, select them from the leftmost panel, and click the “Move left” button. Press the “Update data element group member” button to save your changes.

Data element group sets¶

Data element group sets allow multiple data element groups to be categorised 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 data elements and data element groups as described in the previous sections.

Existing data element group set members can be edited by clicking the name and selecting “Edit” from the context menu of the desired data element group set as seen below.

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 sets¶

..index:: Data Sets

Data sets¶

All data entry in iROAD2 is organised through the use of data sets. You can add and edit data sets in Maintenance->Data sets. A data set is a collection of data elements grouped together for data collection and data export between instances of iROAD2 (e.g. from a district office local installation to a national server).

A data set has a data collection frequency which can be set through the period type property. The frequency can be daily, weekly, monthly, quarterly, six-monthly, or yearly. Which data elements to include in the data set and the frequency are set in the Add/Edit Data set window. In order to use a data set to collect data for a specific orgunit you must assign the orgunit to the data set, and this mechanism controls which org units that can use which data sets.

Data sets also are assigned to specific organisation units which will be allowed to enter data for all data elements in that data set. You can assign org units to a data set in the Data set management by clicking on the blue folder icon, the first icon under Operations, next to the data set you would like to modify. Alternatively you can manage orgunit assignments for all data sets together in the Data set Assignment Editor (available in the right-side menu).

A data set has several properties that must be entered when creating a new one. Name, short name, code and description should be used to identify and describe the data set. The other properties deserve an explanation:

• Expiry days: Controls for how long it should be possible to enter data in data entry for this data set. Expiry days refer to the number of days after the end date of the selected data entry period where the data entry form should be open for entry. After the number of days has expired, the data set will be locked for further entry. You can set manual exceptions to this using the lock exception functionality in data administration module.

[Note] Note:: If the number of expiry days is set to zero, this will allow data entry into all possible historical time periods.

• Complete notification recipients: Sets which users should receive a message with a notification about this data set being marked as complete in data entry. In this list you can select a user group, and all members in this group will receive a notification. The message will be delivered through the iROAD messaging system.
• Approve data: Define whether data for this data set should be Approved. (See the Data approval chapter.)
• Skip aggregation: Define whether data for this data set should be skipped during data mart generation. You should leave this on no, which is the default behavior, in most situations. Can be useful if you have limited server resources and are setting up new experimental data sets.
• Allow future periods: Defines whether it should be possible to enter data for future periods for this data set in data entry. The default behavior is to allow data entry only for periods which have passed, i.e. the end date is after today’s date. If set to yes you can enter data for future periods, which is useful e.g. for population, target and planning data.’
• All fields for data elements required: Defines whether it is mandatory to fill all values for a data element in data entry if one or more values have been filled. This means that if the user enters one data value for a data element in an entry field (i.e. for a category option combination), then she must enter data for all fields belonging to that data element (i.e. all category option combinations).
• Complete allowed only if validation passes: Controls whether it should be possible to mark a data entry form as complete only if the validation of that form is successful. Default behavior is yes. If set to no, then a user cannot mark the form complete if validation fails.
• Skip Offline: Controls whether this data entry form should be downloaded and saved in the user’s web browser. Normally you should leave this on no, which is the default behavior. If you have forms which are rarely used and are very big you can consider setting it to yes to speed up initial loading of the data entry module.

Your data set will then be ready to be used in Services->Data Entry for the org units that you have assigned and for periods according to your selected frequency (period type).

Data set categories¶

Before reading this section it is recommended to familiarize oneself with the sections on categories in the data element chapter. Whereas data element categories can be used for capturing disaggregations of data elements, data set categories are used to capture information which is common to an entire form.

To set up categories for data set, start by creating category options, categories and category combinations like described in the data element chapter. Make sure that you set the type of categories and category combinations to “Attribute”. To assign a category combination to a data set, you can select it while creating or updating the data set from the “Combination of categories” drop-down box.

When a data set is linked to a category combination, those categories will be displayed as drop-down boxes in the data entry module. Data captured in the form will then be linked to the selected category options from those drop-down boxes.

An scenario for when data set categories are useful is when you need to capture a data entry form for a implementer partner organisation and a project. In that case, start by creating category options and categories for all partner organisations and projects, before linking these in a new category combination. Then, link the category combination to the data set (form) for which you need to capture this information. When opening this data set in data entry module, the partner organisation and project categories will automatically be rendered as drop-down boxes, allowing you to select a specific implementing partner organisation and project before continuing to do data entry.

Data Entry Forms¶

Once you have assigned a data set to an orgunit that data set will be made available in Data Entry for the orgunits you have assigned it to. A default data entry form will then be shown, which is simply a list of the data elements belonging to the data set together with a column for inputting the values. If your data set contains data elements with a non-default categorycombination, such as age groups or gender then additional columns will be automatically generated in the default form based on the different options/dimensions.

If you use more than one dataelement category combination you will get multiple columns in the data entry form with different column headings for the options. In addition to the default list-based data entry form there are two more alternatives, the section-based form and the custom form.

Section forms¶

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, both of these functions are supported in section forms. This function can be access by choosing Maintenance->Data set Section.

Adding a new section form¶

Section forms are separated automatically by data element category combinations, which produce a spreadsheet like data entry form for each section.

When designing a section form the procedure is as follows:

1. Set up your data set as described in Section 6.1, Data sets
2. Open the Data Set Section window (from right side menu under Data sets) and add your sections one by one. To add a new section to a section form, first choose the data set from the “Select data set” combo box. Then choose the specific category combo and press “Add new”. You can now add data elements from the “Available data element” list on the left to the “Selected data elements” list on the right. Data elements can be sorted within the section with the use of the “Move up” and “Move down” buttons. Be sure to press “Save” once you have finished.

[Note] Note:: You can only use one data element category combination per section.

1. You may need to control how the data element sections are displayed on the final form. In Data set Section management, select the data set from the “Data set” drop-down box, then leave [All] in the “Select Category Combo” drop-down. Click on “Sort section” to sort the order of appearance of your sections in the data entry form.
2. In Data Entry you can now start using the Section form (should appear automatically when sections are available for the selected data set). Data sets which have section forms will automatically display the section form.
3. Certain data elements may need to be disabled for data entry. Clicking on the “Section grey field management” menu item will allow you to disable specific data element category options as seen below. Pressing the “Disable” button will prevent data from being entered into this specific data element/category option during data entry. Be sure to press “Done” to save your changes.

User Management¶

..index:: User Management

User Management¶

iROAD2 allows for multiple users to access the system simultaneously, each with a defined set of permissions. These permissions can be finely tuned so that certain users can only enter data, while others may generate reports. Multiple user roles can be created, each with their own set of permissions, and then assigned to users which grant them certain privileges within the system. This chapter describes how to manage users and user roles.

Creating new users and roles¶

This section will describe how to add new users and manage existing users to the iROAD2 application. You can create as many user names as you need. Each user can be assigned certain privileges, and can be assigned to certain organisation units for which they will be enabled to enter data on behalf of. To access the user module, choose Users from the Apps menu and then click “User” from the menu items on the left-hand pane

User maintenance¶

You can search for specific user names in the user list by entering the name in the Filter by name field as shown above. Some non-standard functions are available by clicking on each user in the list:

Replicate: This will create an exact copy of the user. You will be asked to enter a new username and password for the replicated account.

Disable: This will disable the user, meaning that the account is not deleted, but the user will not be able to log in or use it.

User role management¶

As part of creating a user name you are required to define the user role. Do so by clicking on User Role on the left side of the displayed screen. This will lead you to the User role management page where you can click on Add new to create a new role.

The following screen will open and here in the first text box you need to give a 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.

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.

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.

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 authorisation will be saved to the database, and can then be assigned to a particular user.

User management¶

Under particular user role there can be more than one user. To manage users, click on User on the left side of the screen. This will lead you to the User management page.

To add a new user, follow these steps:

1. Click on the Add New button.
2. Choose whether you want to fill in all the personal user information now, or invite the user by email to complete the rest of the user information:

• Create account with user details - Choose this if you would like to enter all the details of the new user such as name, password, etc.

If you choose this action, then enter the following information: username, password, surname, first name, E-mail, OpenID account (if any) and mobile phone number (if any).

After you finish adding the user, the account will be ready for them to use with the username and password that you supply.

• Email invitation to create account - Choose this if you would like to send by email an invitation for the user to return to the system and finish setting up their user account. The user will then return to the system and fill in most of their personal information. The account that the user finishes setting up will be limited according to how you configure it below.

Note that you may not select this option to create an account with “critical” system authorities such as All, Scheduling Administration, Perform maintenance tasks, Merge organisation units, Eliminate duplicate data elements, Sql View Management, Change system settings, and List, Add or Delete user roles.

If you choose this action, then enter the email address to which the invitation should be sent. If you want to, you may also enter the user name that the account will have. If you leave the username empty, then the user may choose their own username when they respond to the invitation (as long as it is not taken already for another user.)

After you finish adding the new user, two emails will be sent to the address you provided. One contains a unique web link by which the user can return to the system and activate their account by entering the rest of their user information. The other email contains a unique code that they must enter into the system in order to complete the registration, after following the link in the first email. The user must finish setting up the account within three months, or the invitation becomes invalid.

1. Select the Interface language for the user. You may choose a language into which fixed elements of the iROAD2 user interface have been translated.
2. Select the Database language for the user. You may choose a language into which implementation-supplied items have been translated in the database, for example data element names, organisation unit level names, etc.
3. Users must be assigned to at least one data capture and maintenance organisation unit. Users will have access to all children of the organisation units which have been assigned to them. For instance, if a user has been assigned to a district which has several facilities contained in the district, the user would have access to the district’s data, as well as all of the facilities contained within the district. The data approval organisation units control for which organisation units the user can do data entry.
4. Users can be assigned to any number of data view organisation units. This controls which organisation units the user can view aggregated data for in analysis modules. Giving access to an organisation unit implicitly gives access to all organisation unit below it in the organisation unit hierarchy. Note that data view organisation units are optional. If you do not specify any, the user will have access to the full organisation unit hierarchy for viewing aggregated data.

In several places in the analysis modules one can select “user organisation unit” for the organisation unit dimension. This mechanism will first attempt to use the data view organisation units linked to the current user. If not found, it will use the data capture organisation units.

1. (Click on Show more options.) You may optionally assign users to user groups on this page.
2. (Click on Show more options.) You may optionally restrict the values this user sees in data analytics by selecting dimensions that will restrict the users view. For example, let’s say you have defined Implementing Partner as a category option group set, and you have shared with this user only one or more specific implementing partners (category option groups.) If you want to insure that the user does not see totals in analytics that include values from other groups, assign Implementing Partner to this user. This insures that any data visible to the user through iROAD2 analytics will be filtered to select only the Implementing Partner category option group(s) which are visible to the user.

1. Click on the Add button to complete adding the 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 Users Edit and Remove menu options.

User by organisation unit¶

The User by organisation unit function allows you see which users have been assigned to a particular organisation unit. Simply select the organisation unit from the tree on the left, and a list of users which have been assigned to this particular organisation unit will be displayed

Managed users¶

iROAD 2 supports a concept for user management referred to as managed users which which allows to explicitly define which users should be allowed to manage or modify which users. To “manage a user” implies that you can see and modify that user. The basic concept for user management is that you can see and modify users which you have been granted all of the authorities; in other words you can modify users which have a subset of your own authorities. The managed users concept gives you greater control over this.

The managed users concept allows you to define which users should be able to manage which users. This is configured through user groups and memberships within such groups. A user group can be configured to be allowed to manage other user groups from the standard add and update user interface. The effect is that a specific user can manage all users which are members of user groups which can be managed by a user group that the user is member of. In other words, users can be managed by all members of user groups which are managing user groups they are member of.

To enable this concept you should grant users the authority to “Add/update users within managed groups”, and not grant access to the standard “Add/update users” authority. An implication of the managed users concept is that when creating a user with the “Add/update users within managed groups” only, the user must be made a member of at least one user group that the current user can manage. If not, the current user would lose access to the user being created immediately. This is validated by the system.

When granted the “Add/update users within managed groups” authority, the system lets a user add members to user groups for which the have read-only access to. The purpose of this is to allow for desentralized user management. You may define a range of user groups where other users may add or remove members, but not remove or change the name of the group.

OpenID Support¶

iROAD 2 supports the OpenID standard, which allows third party login using a OpenID provider, please see http://openid.net for more information. To create a custom OpenID URL for a username you can visit this URL and log in with your OpenID provider: http://openid-provider.appspot.com.

To enable support for this in iROAD 2, two steps must be done:

Set your OpenID provider: This can be done inside system settings, under “Access”. Here you can set both the OpenID provider, and also the label to display on the login page to login with this provider (defaults to Login with OpenID).

Set the OpenID identifier on the user: For every user that should be able to login with his openid identifier, you will need to set this on the user itself. This can be done in user management, under the email field, there is noe a field called OpenID which can be used to fill in the OpenID identifier.

Sharing¶

..index:: Sharing

Sharing of objects¶

This chapter discusses the sharing of entities feature in DHIS 2. Many objects in DHIS 2, like reports, charts, maps and indicators, can be shared. Sharing means making an object, like a report, available for reading or modification to a group of users or to everyone. For instance for reports, the sharing dialog can be opened by clicking on the “Sharing settings” button next to each report in the list. Implementers can use this feature to allow access to certain objects to only certain user groups. Users can use the feature to decide who they would like to share objects (such as pivot tables, charts, dashboards, etc) with.

If sharing is supported for a particular class of objects, a dialog will be available called “Sharing settings”, usually available by clicking on the name of the object or in the analytics tools, through an icon (Share with other people). Once you have accessed the sharing settings for the object you wish to share, a dialog similar to the one below will be shown.

Sharing and access control¶

You can share your report with everyone or with a number of user groups. “External access” can be enabled to allow this resource to be shared with everyone, including users which cannot logon to DHIS2. This is useful for sharing public resources with external systems. Note, that if objects are shared externally, then they are visible to anyone who has access to the URL which provides the resource without any login credentials.

Next to “Public access” you can choose your public access option: “None”, “Can view” or “Can edit and view”. Public access refers to users which are logged into the system. Edit also implies deleting the report.

To share with a group, simply start typing the name of the group and the “Search for user groups” input field and select your desired group. Click on the “+” icon next to the input field to share with that group. For each group you can set an access option, similar to public access.

Sharing with a user group implies that all users in that group will get access to the shared object. To create a user group you can go to the dashboard module and click on “Groups”. This will lead you to the list of groups where you can click “Add new” in the top right corner. Creating user groups is open for everyone from the dashboard module.

Sharing and access control The objects which support sharing are indicator, indicator group, indicator group set, data dictionary, data set, program, standard report, resource, report table, chart, map and user group. Out of those objects, report table, chart, map and user group are open for everyone to create privately. Private means that the objects are available only to yourself or potentially to a number of user groups if you choose to share the object. These objects are referred to as “open” objects and can be created by all users. The remaining objects require that your user account has the authority to create them. These objects are referred to as “non-open” objects.

A user can be granted the authority to create publicly accessible objects or privately accessible objects. In order to create a publicly accessible object (available for viewing or editing by anyone) your user account must have the authority to do so. As an example, to create a publicly accessible chart, your user must have the “Create public chart” authority granted. The authority to create private objects applies only to non-open objects. For example, to allow a user to create indicators which will only be accessible to that user and not to everyone, the user can be issued with the “Create private indicator” authority.

Sharing a non-open object with another person and let her edit the object requires that the person’s user account has the authority for updating that type of objects granted. For instance, if you want to let another person edit your indicator, that person’s user account must have the “Update indicator” authority granted. This does not apply for open objects.

When you create a new object it will automatically become viewable for everyone if your user account has the authority to create public objects. As an example, if you create a standard report and you have the “Create public standard report” authority granted, the report will become viewable for everyone. If you do not have that authority granted the report will be viewable only to yourself. After you have created an object, you may navigate to the “Sharing settings” dialog and set your desired access control level.

If you need a user account which is able to view absolutely all objects you can create a user role with the “ALL” authority and assign a user to that role. If you need to switch between a “complete” view of objects and a “personal” view of objects it is recommended to create two user accounts, one assigned with the “ALL” authority and one without.

Sharing applied¶

The sharing functionality is useful in several scenarios. One use-case is setting up a DHIS instance for a global organisation with operations in multiple countries. Typically the organisation has a set of global data sets, indicators and reports which should apply to all countries, while all countries will have the need for country-specific data sets, indicators and reports. In this scenario the following approach could work:

• Set up one user group for global personnel.
• Set up a user group for personnel in each country.
• Create global data sets and reports, make them viewable for everyone and editable for the global user group only.
• Create country-specific data sets and reports, make them viewable and editable for the country user group and the global user group only.

This way, the global indicators and reports could be viewed and analysed by everyone, but maintained by the global user group only. The country-specific data sets, indicators and reports could be viewed and maintained by the country and global personnel, without being visible or impacting the system for other countries in the organisation.

A similar approach could work for a scenario with a donor, multiple funding agencies and implementing partners in a country, where user groups could be set up for each of those entities. That way each implementing partner could create and share their reports within their organisation without affecting or allowing access to others. Reports could also be shared with supervisors and funding agencies at the end of reporting periods.

Another use-case is a country department of health with multiple health programs. Typically there is a need for having general reports and charts for the department while allowing the health programs to develop specific reports and charts for internal use. This can be achieved by creating user groups for each health program. Later, when developing reports and charts, these can be made viewable and editable to the program user group only. This way the reports will not be visible to other programs and users. This is beneficial because the reports are kept internal to the program and because the visible list of reports of other users are kept shorter and more relevant.

Dashboards¶

..index:: Dashboards

Dashboards¶

Dashboards are intended to provide quick access to different analytical objects (maps, charts, reports, tables, etc) to an individual user. Dashboards can also be shared with user groups. For instance, a user or administrator could create a dashboard called “Malaria” which might contain all relevant information on malaria. This dashboard could then be shared with the user group called “Malaria contol”, which might consist of all users of the malaria control programme. All users within this group would then be able to view the same dashboard.

Setting up the dashboard¶

The dashboard can contain any number of objects (charts, maps, reports, tables, resources, etc). These can be freely arranged on the dashboard as you wish.

In this screen shot, the dashboard has already been populated with a number of objects, such as charts, map views, tables and messages. Simply clicking on one of the blue links will bring you automatically to the object. Maps, charts and tables can be viewed as full size as images (in the case of charts and map views) or as HTML resources (in the case of reports, tables and messages).

To reorder how the dashboard appears, simply drag-and-drop any of the objects to a new position.

If you would like to share an interpretation of an object (such as a chart of map), click “Share interpretation”. You interpretation will be shared publicly with other users of the iROAD2 system, in the “Interpretation” section of the dashboard.

Messages and feedback¶

iROAD2 has certain functions to facilitate communication between different users and user groups. This type of communication is important to facilitate feedback regarding data quality, timeliness of submissions, or to simply answer a question which a particular user may have.

Feedback messages are sent to a particular group of users and can be sent by all users who have access to the dashboard module. In order to enable the receipt of feedback messages sent from the dashboard, you must set the system setting “Feedback recipients” which is available from the Maintenance->System settings dialog. Be sure to define a user group (e.g. “Feedback recipients”) with all of the users who should receive feedback messages. Refer to the section in this manual on “User groups” for more information of how to do this. Once the “Feedback recipients” user group has been defined, each time a feedback message is sent, it will appear as a message in each of the “Feedback recipients” message queue within iROAD2. Note that messages will not be sent to users email addresses, but will only appear within the iROAD2 application.

To send a new feedback message, simply select “Write feedback” from the dashboard. Provide a subject and text in the respective text boxes. The message will appear in all of the specified users message queue.

Messages can be sent to specific groups of users who have been assigned to particular organisation units. To write a new message, simply click “Messages” from the dashboard screen and then press the “Write message” button.. Select an organisation unit (or group of organisation units) from the “Recipients” organisational unit tree. Provide a Subject and Text. To send the message, press the “Send” button. You can discard the message by pressing the “Discard” button as seen in the screenshot below.

To read messages which have been sent to you, select “Messages” from the “Dashboard” . You messages will be displayed as a list. Click the desired message to read all of the messages in this particular conversation.

Data Entry¶

..index:: Data Entry

Data entry with iROAD 2¶

Data entry with iROAD 2¶

To open the data entry window click on the services tab displayed in the main menu. A drop down menu will appear listing the services provided by iROAD 2. Click on the Data Entry option.

The data entry module is where data is manually registered in the iROAD 2 database. Data is registered for an organisation unit, a period, and a set of data elements (data set) at a time. A data set often corresponds to a paper-based data collection tool.

Selecting the data entry form¶

To start entering data the first step is to open the correct form by following these steps:

1. Locate the orgunit you want to register data for in the tree menu to the left. Expand and close branches by clicking on the +/- symbols. A quick way to find an orgunit is to use the search box just above the tree (the green symbol), but you need to write in the full name to get a match.
2. Select a data set from the dropdown list of data sets available to your selected orgunit.
3. Select a period to register data for. The available periods are controlled by the period type of the data set (reporting frequency). You can jump a year back or forward by using the arrows above the period.

By now you should see the data entry form. From a form design perspective, there are three types for forms: default forms, section forms and custom forms. If a custom form exists, it will be displayed, followed in order of precedence by a section form, and finally a default form.

Entering data¶

Start entering data by clicking inside the first field and type in the value. Move to the next field using the Tab button. Shift+Tab will take you back one step. You can also use the “up” and “down” arrow keys to navigate between the form cells. The values are saved immediately and do not require to be saved at a later stage. A green field indicates that the value has been saved in the system (on the server).

Input validation: If you type in an invalid value, e.g. a character in a field that only accepts numeric values you will get a pop-up that explains the problem and the field will be coloured yellow (not saved) until you have corrected the value. If you have defined a min/max range for the field (data element+organisation unit combination) a pop-up message will notify you when the value is out of range, and the value will remain unsaved until you have changed the value (or updated the range and then re-entered the value).

Disabled fields: If a field is disabled (grey) it means that the field can and should not be filled. The cursor will automatically jump to the next open field.

Data history: By double-clicking on any input field in the form a data history window opens showing the last 12 values registered for the current field (organisation unit+data element+categoryoptioncombo) in a bar chart. This window also shows the min and max range and allows for adjusting the range for the specific organisation unit and data element combination.

Follow Up: In the data history window there is also a feature to tag or star a value. E.g. a suspicious value that needs further investigation can be kept in the system, but marked for Follow-Up. In the Data Quality module you can run a Follow-Up analysis and view all values marked for Follow-Up, and then later edit the values if proved incorrect.

Audit trail: The audit trail allows you to view other data values which have been entered prior to the current value. As an example, the following data element was changed from its original value to 120. The audit trail shows when the data value was altered along with which user made the changes.

Editing and deleting data¶

If you wish to enter data which has already been entered, simply replace the data entry value with the update values.

If you want to delete a data value completely, you should select the value of interest, and press “Delete” on your keyboard. If you enter a zero and the data element has been configured to not store zeros, the previous data value (i.e. the one you wish to modify) will not be overwritten with the new value. Therefore, it is better practice to delete the data value completely (waiting for the cell to turn green) and then to enter the new value.

Validating data in the form¶

When all the available values for the form has been filled in you can run a validation check on the data in the form. Click on the “Run Validation” button in the top right corner. All validation rules which involves data elements in the current form (dataset) will be run against the new data. Upon completion you will be presented with a list of violations or a simply a message that says “The data entry screen successfully passed validation”. See the Data Quality chapter for information on how to define such validation rules.

When you have corrected any erroneous values and are done with the form the recommended practice is to click on the Complete button below the form to register the form as complete. This information is used when generating completeness reports for district, county, province or the national level.

Offline data entry¶

The data entry module will function even if during data entry the Internet connectivity is not stable. In order to utilize this functionality, you must login to the server while Internet connectivity is present, but if during data entry, the Internet link between your computer and the server becomes unstable, data can still be entered into the data entry form, saved to your local computer, and then pushed to the server once the Internet connectivity has been restored. Data can be entered and stored locally while being offline and uploaded to the central server when on-line. This means that the on-line deployment strategy will be more viable in areas with unstable Internet connectivity. The total bandwidth usage is greatly reduced since forms no longer are retrieved from the server for each rendering.

Multi-organisation unit data entry¶

In some scenarios it is beneficial to enter data for multiple organisation units in the same data entry form, for instance if there are few data elements in the form and a huge number of organisation units in the hierarchy. In that case you can enable multi-organisation unit data entry by going to “System settings” and tick the “Enable multi organisation unit forms” setting. Then, in data entry, select the organisation unit immediately above the organisation unit you want to enter for in the hierarchy. Note that this only work for the “section” based forms. You should now see the data elements appearing as columns and the organisation units appearing as rows in the form. Note that the data entry forms should still be assigned to the facilities that you actually enter data for, i.e. the organisation units now appearing in the form.

Using reporting functionality¶

..index:: Using reporting functionality

Using reporting functionality¶

14.1. Reporting functionality in iROAD 2 The reporting module in iROAD 2 provides a range of reporting alternatives, and this section will explain how to use them to view and analyse data. Another section explains how to configure and set up the various reporting tools.

Standard reports: Standard reports are built on report tables, but are more advanced in its design allowing for more cosmetics and styles. These reports can also combine multiple tables and charts in the same report and be made available as one-click reports that are very easy to use. These reports can be downloaded as PDF files which makes them ideal for printing as well as sharing offline.

Dataset reports: Dataset reports are simply a printer friendly way to look at the data entry forms with either raw or aggregated data (over time or place). The design used in data entry will be used also in the data set reports. This will work only for data sets that has a custom data entry form set up.

Dashboard: The fastest way to view your data. The dashboard can display up to four updated charts as well as shortcuts to your favourite reports, report tables, and map views. Each user can configure a personal dashboard.

Data Visualizer: Do flexible visualizations of your data as charts and data tables. Any number of indicators and data elements can be included. Several chart types are available, such as column, stacked column, line, area and pie charts. The charts can be saved in order to be easily retrieved later and can also be put on your personal dashboard. Charts can be downloaded as image and PDF files to your local computer.

Report tables: These are very configurable table outputs of your data, either showing raw or aggregated data, as well as indicator data. These tables are used as either a data source for more advanced reports, for export to external systems, or as a crude report itself, and are exportable to PDF, excel, CSV and jasper design files. These tables represent a very dynamic, flexible and quick way to look at the data. Report tables can be set up with parameters to make them reusable over time and place.

Orgunit distribution reports: These reports are generated off the orgunit group set information and can show what types (and how many of each type) of health facilities that are located in a given area (any level in the hierarchy). These reports are automatically generated and display the information in both tables and charts, and downloads in PDF, excel, and CSV are available.

Reporting rate summary: These reports provide a nice overview of how many facilities that have submitted their data for a given dataset and period. Here you can get both the counts and the percentages showing the reporting rate for all or single data sets.

Excel pivot tables: Excel pivot tables represents a very powerful way to analyse your data and iROAD 2 links directly to the pivot tables so that all the data will be available and updated in your Excel file. This can be a very useful tool for users that prefer working with the data offline. To update your local pivot tables you need the myDatamart tool which connects to the online server and downloads the latest data. This update will typically take place once a month when new data is available, but do not require a constant internet connection like the other reporting tools (if you are connecting to an online iROAD 2 server).

Web-based pivot tables: The built in pivot table tool is a simple web-based tool to display indicator data by orgunit and period in a typical pivot table view and allows for some basic pivoting manipulations of the tables. It is a quick and easy way to look at many indicator values at the same time (by orgunit and/or period), but does not have the same functionality as the offline Excel pivot tables.

GIS: Present and analyse your data using thematic maps. You can view both data elements and indicators and given that you have coordinates for all your orgunits you can drill down the hierarchy and view maps for all levels from country polygons to facility points. See the separate chapter on GIS for more details. All the map information is built into iROAD 2 and all you need to do is to register coordinates for your organisation units and the maps will be available.

Using standard reports¶

You access the available reports from the Services drop-down menu, by selecting Reports. In the report menu in the left bar, click Standard Report. A list of all pre-defined reports will appear in the main window.

You run/view a report by clicking on the name of the report and then selecting “Create” from the contextual menu. If there are any pre-define paramaters, you will see a report parameter window where you must fill in the values needed for orgunit and/or reporting month, depending on what has been defined in the underlying report table(s). Click on “Get Report” when you are ready. The report will either appear directly in your browser or be available as a PDF file for download, depending on your browser settings for handling PDF files. You can save the file and keep it locally on your computer for later use.

Using report tables¶

Report tables are a simple-to-use tool for creating tabular analysis. To run a report table first navigate to the list of available report tables in Reports->Report Tables and then the name of the report table you wish to use. Select “Create” from the contextual menu. If the report table has any pre-defined parameters, you will need to select them in the next screen. Finally, press “Create” to view the report table. Report tables are created through the PivoTable app. Consult the relevant section for more information on creating new report tables.

Report parameters: Most report tables have parameters, which means that you can filter which orgunits and/or periods you want in the report. This makes the reports much more reusable. When you run the report table a Report parameter window will open and ask the user to input values for the selected parameters. The possible parameters are Reporting Month and Organisation Unit, and either one of these or both will show in the window. After selecting the values click on the Get Report button.

Export/view options: When the report table is ready it will be displayed in a HTML view. The report table can be exported to PDF (for better printing and easier saving), Excel, CSV, and also to a standard report format (Jasper) with a nicer table and a chart shown in PDF, or as a Jasper design file (JRXML) for further improvements and changes to the report design before uploading it as a standard report (see the Creating standard reports section in the Developers Guide for more detail information).

You can also share a comment or interpretation about this report table from the report table view, by simply writing a comment in the box and pressing “Share”.

Using dataset reports¶

Dataset reports are printer friendly views of the data entry screen filled with either raw or aggregated data. These are only available for data sets that have custom data entry forms and not for default or section forms.

You can access data set reports from the Report menu under Services.

A Criteria window will appear where you fill in the details for your report:

Dataset: The data set you want to display.

Reporting period: The actual period you want data for. This can be aggregated as well as raw periods. This means that you can ask for a quarterly or annual report even though the data set is collected monthly. A data set’s period type (collection frequency) is defined in data set maintenance. First select the period type (Monthly, Quarterly, Yearly etc.) in the drop down next to Prev and Next buttons, and then select one of the available periods from the dropdown list below. Use Prev and Next to jump one year back or forward.

Use data for selected unit only: Use this option if you want a report for an orgunit that has children, but only want the data collected directly for this unit and not the data collected by its children. If you want a typical aggregated report for an orgunit you do not want to tick this option.

Reporting Organisation unit: Here you select the orgunit you want the report for. This can be at any level in the hierarchy as the data will be aggregated up to this level automatically (if you do not tick the option above).

When you are done filling in the report criteria you click on “Generate”. The report will appear as HTML in a printer-friendly format. Use the print and save as functions in the browser to print or save (as HTML) the report.You can also export the data set report in Excel and PDF formats.

Using resources¶

The resource tool allows you to upload both files from your local computer to the iROAD server and to add links to other resources on the Internet through URLs. If you want to share the direct link to the iROAD resource you can right click on the “view resource” button and copy the link address.

The create a resource click on the “Add new” button. Enter a name for the resource, then choose between uploading a file or external URL. If you chose file upload click “Choose file” and select your file your local computer. If you chose URL enter the link to the resource on the Internet. Then click “Save”.

Using reporting rate summary¶

Access the reporting rate summary from the Services->Reports menu. Reporting rate summaries will show how many datasets (forms) that have been submitted by organisation unit and period. There are two methods available to calculate reporting rates (completeness):

• Based on complete data set registrations. A complete data set registration refers to a user marking a data entry form as complete, typically by clicking the complete button in the data entry screen, hereby indicating to the system that she considers the form to be complete. This is i.e. a subjective approach to calculating completeness.
• Based on compulsory data element: You can define any number of data elements in a data set to be compulsory. This implies that data values must be captured for all data elements which have been marked as compulsory in order for the data set to be considered complete. This is i.e. an objective approach to calculating completeness.

The reporting rate summary will for each row show a range of measures:

• Actual reports: Indicates the number of data entry complete registrations for the relevant data set.
• Expected reports: Indicates how many data entry complete registrations are expected. This number is based on the number of organisation units the relevant data set has been assigned to (enabled for data entry).
• Percent: The percentage of reports registered as complete based on the number expected.
• Reports on time: Same as actual reports, only reports registered as complete within the maximum number of days after the end of the reporting period. This number of days after reporting period can be defined per data set in the data set management.
• Percent on time: Same as percentage, only reports registered as complete on time used as numerator.

To run the report you can follow these steps:

• Select an orgunit from the tree.
• Select one of the completeness methods to use to calcuate the reporting rates.
• Select all or one data set. All will give you a report with all data sets for the selected organisation unit. A single data set will give you a report with completeness for all children of the selected organisation unit.
• Select a period type and a period from the list of available periods for that period type. Move back/forward one year by using the prev/next buttons.
• The report will then be rendered. Change any of the parameters above and the report will be updated automatically.

Using organisation unit distribution reports¶

You can access the Orgunit Distribution reports from the left side menu in the Services->Reports module.

Orgunit distribution reports are reports that show how the orgunits are distributed on various properties like type and ownership, and by geographical areas.

The result can be presented in a table-based report or in a chart.

Running a report:

To run a report first select an orgunit in the upper left side orgunit tree. The report will be based on orgunits located under the selected orgunit. The select the orgunit group set that you want to use, typically these are Type, Ownership, Rural/Urban, but can be any user-defined orgunit group set. The you can click on either Get Report to get the table-based presentation or Get chart to get the same result in a chart. You can also download other format such as PDF, Excel and CSV.

Using Pivot Table¶

..index:: Pivot Table overview

Pivot Table overview¶

The pivot table app enables users to create pivot tables, using all available data dimensions in iROAD 2. A pivot table is a dynamic tool for data analysis which lets you quickly summarize and arrange data according to its dimensions. Examples of data dimensions in iROAD 2 are data elements (explaining what the data means), periods (representing the time aspect) and the organisational hierarchy (representing the geographical location of the data). From these dimensions you can freely select dimension items to include in the pivot table. Additional dimensions can be created in iROAD2, using the group set functionality, to allow for different aggregation pathways, such as aggregation by “Partner” or facility type.

A pivot table can arrange data dimensions on columns, rows, and as filters. When you place a data dimension on columns, the pivot table will display one column per dimension item. If you place multiple data dimensions on columns, the pivot table will display one column for all combinations of the items in the selected dimensions. When you place a data dimension on rows, the pivot table will display one row per dimension item in a similar fashion. The dimensions you select as filters will not be included in the pivot table, but will aggregate and filter the table data based on the selected filter items.

The workflow for creating a simple pivot table is:

• Select dimension items in the left menu, for instance a few data elements or indicators.
• Click “Layout” on the top menu and arrange the data dimensions as columns, rows, and filters. You can leave the selection as it is if desired.
• Click “Update”.

Based on the demo database, a pivot table approximately as below will be displayed. Notice how indicators are listed on columns and periods as rows.

Selecting dimension items¶

The left menu will list sections for all available data dimensions. From each section you can select any number of dimension items. As an example, you can open the section for data elements and select any number of data elements from the available list. You can select an item by marking it and clicking on the arrow in the section header or simply double-clicking on the item. Before you can use a data dimension in your pivot table you must at least select one dimension item. If you arrange a dimension as columns or rows but do not select any dimension items, the dimension will be ignored.

For the indicator and data element dimensions you must first select one or all groups from the group list. You can then select data elements from the available items list.

For the period dimension you can choose between using fixed periods or relative periods. An example of a fixed period is “January 2012”. To select fixed periods start by selecting a period type from the period type list. You can then select periods from the list of available periods. Relative periods are periods relative to the current date. Examples of relative periods are “Last month”, “Last 12 months”, “Last 5 years”. Relative periods can be selected by ticking the checkboxes next to each period. The main advantage of using relative periods is that when you save a pivot table favorite, it will stay updated with the latest data as time goes by without the need for constantly updating it.

For the organisation unit dimension you can select any number of organisation units from the hierarchy. To select all organisation units below a specific parent organisation unit, right click and click “Select all children”. To manually select multiple organisation units, click and hold the Ctrl button while clicking on organisation units. You can tick “User organisation unit”, “User organisation unit children” or “User organisation unit grand children” in order to dynamically insert the organisation unit or units associated with your user account. This is useful when you save a pivot table favorite and want to share it with other users, as the organisation units linked with the other user’s account will be used when viewing the favorite.

Arranging the table layout¶

After selecting data dimensions it is time to arrange your pivot table. Click “Layout” in the top menu to open the layout screen. In this screen you can position your data dimensions as table columns, rows or filters by clicking and dragging the dimensions from the dimensions list to the respective column, row and filter lists. You can set any number of dimensions in any of the lists. For instance, you can click on “Organisation units” and drag it to the row list in order to position the organisation unit dimension as table rows. Note that indicators, data elements and data set reporting rates are part of the common “Data” dimension and will be displayed together in the pivot table. For instance, after selecting indicators and data elements in the left menu, you can drag “Data” from the available dimensions list to the row dimension list in order to arrange them as rows in the pivot table.

After you have set up your pivot table you can click “Update” to render your pivot table, or click “Hide” to hide the layout screen without any changes taking effect. Since we in our example have selected both the period and organisation unit dimension as rows, the pivot table will generate all combinations of the items in these dimensions and produce a table like this:

Using table options¶

Several table options are available when working with a pivot table. Open the options screen by clicking on “Options” in the top menu. The following options are available:

• Show totals: Display total values in the table for each row and column, as well as a grand total for all values in the table.
• Show sub-totals: Display subtotals in the table for each dimension. In the screenshot above, notice how subtotals are generated for each of the periods in the period dimension. Note that subtotals will be hidden for columns or rows if there is only one selected dimension, as the values in that case are equal to the subtotals.
• Hide empty rows: Hides empty rows from the table, which is useful when looking at large tables where a big part of the dimension items do not have data in order to keep the table more readable.
• Show hierarchy: Shows the name of all ancestors for organisation units, e.g. “Sierra Leone / Bombali / Tamabaka / Sanya CHP” for Sanya CHP. The organisation units are then sorted alphabetically which will order the organisation units perfectly according to the hierarchy.
• Display density: Controls the size of the cells in the table. Can be set to “comfortable”, “normal” and “compact”. The “compact” option is handy in order to fit large tables into the browser screen.
• Font size: Controls the size of the table text font. Can be set to “large”, “normal” and “small”.
• Digit group separator: Controls which character to separate groups of digits or “thousands”. Can be set to “comma”, “space” and “none”.
• Legend set: Shows a color indicator next to the values. Currently the GIS legend sets are being used.

Creating a favorite¶

When you have set up a pivot table it is convenient to save it as a favorite. To do so, click “Favorites” on the top menu, click “Add new”, give the favorite a descriptive name and click “Create”. You can search for favorites through the search input field at the top. To load an existing favorite, simply click the name of the favorite in the list.

To rename a favorite, click the grey “Rename” icon next to the favorite in the list, change the name and click “Update”. To overwrite an existing favorite with the current pivot table, click the green “Overwrite” icon. To share a favorite with everyone or a user group, click the blue “Share” icon. To delete a favorite, click the red “Delete” icon.

Analysis integration¶

The analysis apps in iROAD 2 are completely integrated, so you can easily switch between pivot table, chart and map visualization of your data. When you have made a pivot table you can click e.g. “Chart” in the top right corner and then select “Open this table as chart”.

If you just want to visualize a small part of your pivot table as a chart, you can click directly on a value in the table instead. A menu will appear. If you mouse hover the “Open selection as chart” option you can see that some of the dimension headers in the table are highlighted, indicating what data will be visualized as a chart.

Downloading data¶

You can download the data in the current pivot table by clicking on “Download” in the top menu. The data can be downloaded in MS Excel and CSV format. The data table will have one column per dimension and contain names of the dimension items. You can easily create a pivot table in Microsoft Excel from the downloaded Excel file by clicking on “pivot table” in the top panel, then clicking on “create pivot table”, then marking the data range in the spreadsheet before clicking “OK”.

Data can also be downloaded in JSON and XML format. The data format is specified in the Web API chapter under the “Analytics” section. The data document will use identifiers of the dimension items and will be opened in a new browser window in order to reveal the URL of the request to the Web API in the address bar. This will be useful for developers of apps and other client modules based on the iROAD 2 Web API.

Sharing interpretations¶

For certain analysis-related resources in iROAD, like pivot tables, charts and maps, one can share a data interpretation. An interpretation is simply a link to the relevant resource together with a text expressing some insight about the data. If you want to share a pivot table interpretation you need to first save the table you want to share as a favorite. Then, without making any changes to the table, click the “Share” button the toolbar. A window will open up and this is where you write your interpretation. When you are done, click share button in the bottom right corner of the window. The window will close automatically and if the interpretation was shared successfully you will find a notification on the bottom toolbar.

Embed tables in any web page¶

Certain analysis-related resources in iROAD, like pivot tables, charts and maps, can be embeded in any web page by using a plugin. If you have created a table in the Pivot Table app you will get the plugin configuration for this table by clicking the “Share” button the toolbar and then “Embed as plugin”. You will find more information about the plugins in the web api chapter.

Constraints¶

When selecting and arranging dimensions there are a few constraints that apply. All of these constraints are validated and the pivot table module will provide feedback if any constraint is violated.

• At least one dimension must be selected on columns or rows.
• At least one period must be included in the pivot table.
• Data element group sets and reporting rates cannot appear in the same pivot table.
• A table cannot contain more than the maximum number of analytics records which have been specified through the system settings. The maximum number of records could also be constrained by the maximum RAM which is available to your browser. Considering making more smaller tables, instead of one table which displays all of your data elements and indicators together.

Data Visualizer overview¶

..index:: Data Visualizer overview

Data Visualizer overview¶

The data visualizer module enables users to easily create dynamic data analysis and visualizations through charts and data tables. You can freely select content (like indicators, periods and organisation units) for your analysis. This module can be accessed by going to “Services - Data Visualizer” in the main menu. The image below shows the viewport of the module. For a quick start:

1. Look under the “Indicator” heading and select an indicator group from the list of groups.
2. Look under “Available indicators” and select a few indicators from the list by double-clicking on them.
3. Click “Update” in the top bar and see the chart unfold.

The data visualizer is designed firstly to be easy-to-use - you can simply select the indicators, data elements, periods and organisation units you want to include and click “Update” to get your visualization. Secondly it is designed to be fast and work well over poor Internet connections - charts are generated in the web browser and very little data is transferred over the Internet.

Selecting chart type¶

The visualizer module provides seven different chart types, each with different characteristics. You can select the type of your chart by clicking on one of the icons in top left bar titled “Chart type”.

1. Column chart: Chart which displays information as vertical rectangular columns with lengths proportional to the values they represent. Useful e.g. for comparing performance of different districts.
2. Stacked column chart: Chart with vertical rectangular columns where bars representing multiple categories are stacked on top of each other. Useful e.g. for displaying trends or sums of related data elements.
3. Bar chart: Same as column chart, only with horizontal bars.
4. Stacked bar chart: Same as stacked column chart, only with horizontal bars.
5. Line chart: Graph which displays information as a series of points connected by straight lines. Also referred to as time series. Useful e.g. to visualize trends in indicator data over multiple time periods.
6. Area chart: Chart which is based on line chart, with the space between the axis and the line filled with colors and the lines stacked on top of each other. Useful for comparing the trends of related indicators.
7. Pie chart: Circular chart divided into sectors (or slices). Useful e.g. to visualize the proportion of data for individual data elements compared to the total sum of all data elements in the chart.
8. Radar chart: Displaying multivariate data on axes starting from the same point. Also known as spider chart.

Selecting series, category and filter¶

This section lets you define which dimension of the data you want to appear as series, category and filter. This asks for a closer explanation. Dimension in this regard refers to the elements which describe the data values in the system. We have three main dimensions in the system:

1. Data: Includes data elements, indicators and datasets (reporting rates), describing the phenomena or event of the data.
2. Periods: Describes when the event took place.
3. Organisation units: Describes where the event took place.

The visualization module lets you use these dimensions completely flexible in terms of appearing as series, categories and filter. Understanding these concepts is most easily done by looking at the screenshot from the opening page below:

More formally this can be described as following:

1. Series: A series is a set of continuous, related elements (e.g. periods or data elements) which you want to visualize in order to emphasize trends or relations in its data.
2. Categories: A category is a set of elements (e.g. indicators or organisation units) for which you want to compare its data.
3. Filter: Since most charts are two-dimensional, a filter must be used on the third dimension in order to use only a single element for the chart to become meaningful.

Selecting indicators and data elements¶

The visualizer module can display any number of indicators and data elements in a chart and data table. Both indicators and data elements can be selected and appear together in the same chart. You can select indicators by clicking at the “Indicators” header and selecting an indicator group from the list of groups below it. This will make the indicators in the selected group appear in the list under “Available indicators” to the left. From that list you can double click on any indicator in order to select it, this will move it to the list under “Selected indicators”. Alternatively you can mark one or more indicators and click the single-arrow button. To select all indicators you simply click on the double-arrow button. To deselect indicators you can do correspondingly in the “Selected indicators” list.

To select data elements click on the “Data elements” header. The same principle for selecting and deselecting applies as for indicators.

Selecting reporting rates¶

The visualizer can display reporting rates in a chart, by itself or together with indicators and data elements. Reporting rates can be selected by clicking at the “Reporting rates” header. Reporting rates are defined by data sets. It can be selected by double-clicking in the list of available data sets to the left.

Selecting fixed and relative periods¶

Click on the “Periods” header. For fixed periods, select a period type from the combo box. You can select any number of fixed periods from any period type. Below the fixed period you will find the relative period checkboxes and you may select as many as you like. The names should be fairly self-descriptive and they are relative to the current date, meaning that if the current month is March and you select “Last month”, the month of February will be included in the chart. You are also free to combine fixed periods and relative periods in the same chart. Overlapping periods will be filtered so that they only appear once.

Selecting organisation unit¶

You can select which organisation units to include in the chart by clicking the “Organisation units” header. This section features three ways of selecting organisation units. The default mode is called “Organisation units” and lets you select the organisation units you want to appear in the chart from the tree. This mode also features three checkboxes. Checking “User org unit” will disable the organisation unit tree and give you the organisation unit that is related to the current/logged in user instead. This is also useful for administrators as they can create a meaningful “system” favorite with this option checked and all users will find their respective organisation unit when they open it. The the same concept goes for “Org unit children” and “Org unit grand children”. The second mode is called “Select levels”. Here you can select all organisation units at one or more levels. However, at the same time you also have the option to select parent organisation units in the tree, which makes it easy to select e.g. all facilities inside one or more districts. The same thing goes for the third mode called “Select groups”. Here you can select all organisation units inside one or more groups and parent organisation units at the same time.

Selecting organisation unit group sets and data element group sets¶

All dimension tabs listed below “Organisation units” are organisation unit group sets and data element group sets. You are free to add groups from any of these group sets to your chart. Remember to add the group set in either the series, category or filters combobox.

Selecting chart options¶

You can set various chart options by clicking on the “Options” button the chart toolbar.

• Show values: Shows the values above the series in the chart.
• Hide empty category items: Hides category items with no data from the chart.
• Show trend lines: The trend line will visualize how your data evolves over time - e.g. is performance improving or deteriorating. Makes sense when periods are selected as category.
• Target line value/title: Displays a horizontal line at the given domain value. Useful e.g. when you want to compare your performance to the current target.
• Base line value/title: Displays a horizontal line at the given domain value. Useful e.g. when you want to visualize how your performance has evolved since the beginning of a process.
• Range axis max/min: Defines the maximum and minium value which will be visible on the range axis.
• Range axis tick steps: Defines the number of ticks which will be visible on the range axis.
• Range axis decimals: Defines the number of decimals which will be used for range axis values.
• Range axis title: Displays a label next to the range axis (also referred to as the Y axis). Can give context information to the chart, e.g. the unit of measure being used.
• Domain axis title: Displays a label below the domain axis (also referred to as the X axis). Can give context information to the chart, e.g. the type of periods being listed.
• Hide chart legend: Hides the legend and leaves more room for the chart itself.
• Hide chart title: Hides the title of your chart.
• Chart title: Type any title you like and it will appear above the chart.

Displaying a chart¶

You can display a chart based on your selections simply by clicking the “Update” button on the top centre menu. This requires that you have selected one or more elements from all of the three dimensions - data (indicators, data elements, reporting rates), periods (relative, fixed) and organisation units (units or groups). Note that “Months this year” from the period dimension and the root organisation unit are selected by default.

Notice that you can hide and show individual data series in the chart by clicking directly on the series label in the chart - they appear either at the top or to the right of the chart.

If you want to give the chart more space on your screen you can click on the triple left-arrow button on the top centre menu. This will collapse the left side menu. You can get this menu back by clicking on the same button again.

Downloading chart as image or PDF¶

After you have rendered a chart you can download it to your local computer as and image or pdf by clicking on “Download” on the top centre menu. The file will be automatically downloaded to your computer - for instance can you now embed the image file into a text document as part of a report. You can also download the data source behind the chart in json, xml, csv or Microsoft Excel format.

Saving chart as favorite¶

Once you have rendered a chart you can save it as a favorite to able to access it easily at a later point. Click on the “Favorites” button on the top menu to open up the favorites window. Click “Add new” and in the name field enter the desired name for your chart. The chart will be visible only to yourself. For every favorite in the list you have four options to the right. You can rename the chart (grey button), overwrite the chart (green button), modify the sharing settings of the chart (blue button) or delete the chart (red button).

These favorite charts can later be included on your personal dashboard. After saving you can navigate to the dashboard module, click on the “Insert” link over the chart areas and select your preferred chart.

Sharing interpretations¶

For certain analysis-related resources in iROAD, like pivot tables, charts and maps, one can share a data interpretation. An interpretation is simply a link to the relevant resource together with a text expressing some insight about the data. If you want to share a chart interpretation you need to first save the chart you want to share as a favorite. Then, without making any changes to the chart, click the “Share” button the toolbar. A window will open up and this is where you write your interpretation. When you are done, click share button in the bottom right corner of the window. The window will close automatically and if the interpretation was shared successfully you will find a notification on the bottom toolbar.

Embed charts in any web page¶

Certain analysis-related resources in iROAD, like pivot tables, charts and maps, can be embeded in any web page by using a plugin. If you have created a chart in the Data Visualizer you will get the plugin configuration for this chart by clicking the “Share” button the toolbar and then “Embed as plugin”. You will find more information about the plugins in the web api chapter.

Analysis integration¶

The analysis apps in iROAD 2 are completely integrated, so you can easily switch between pivot table, chart and map visualization of your data. When you have made a chart you can click e.g. “Map” in the top right corner and then select “Open this table as map”.

Exiting the data visualizer module¶

If you want to exit the module and go back to the iROAD start page you can click on the “Home” button to the right side of the top centre menu.

Using GIS¶

..index:: Using GIS

Using GIS¶

GIS module overview¶

You can access the GIS module from the Services -> GIS link in the top menu. The picture below shows the GIS viewport.

In the top right corner there is a panel called “Layer overview”. If you are online you will see Google Streets and Google Hybrid which can be used as background maps/layers. Switch between the two of them by checking the checkbox. By unchecking the box you can hide the background completely. If you want to see the background, but with reduced opacity, you can set the visibility to something lower than 100% in the numberbox to the right. The final four layers are the vector layers which the user has at his disposal for thematic mapping (explained in the next section). The panels below hold the map legends when you create a thematic map. A legend explains the link between values and colors on your map.

Lets take a look at the map toolbar. The four icons from the left represent the mentioned vector layers and this is the starting point of the GIS application. Further to the right we have “Favorites”: Save your maps to easily restore them later. Saving a map as a favorite also gives you the opportunity of sharing it with other users as an interpretation or put it on the dashboard. “Legend”: Create you own legend sets to ensure meaningful maps. “Download”: Export the maps as a PNG image. “Share”: Share your favorites as map interpretations with other users.

In the top right corner of the map viewport you find four buttons: “Zoom in”, “zoom out”, “zoom to visible extent” (automatically adjusts the zoom level and map center position to put the data on your map in focus) and “measure distances”.

The current longitude/latitude position of the mouse cursor is displayed in the bottom right corner of the map viewport.

Thematic mapping¶

This section describes the four vector layers which the user has at his disposal for thematic mapping: “Facility layer”, “Boundary layer” and “Thematic layer” 1-4.

This layer displays icons that represent facilities based on the facility type. Polygons will not show up on the map, so make sure to select an organisation unit level that has facilities. Click an icon on the map to open the context menu with two options. “Show information sheet” provides you with data for several data elements for this organisation unit. The data element group and period type are “system settings” called “Infrastructural data elements” and “Infrastructural period type”. The second option in the context menu is “Relocate” and lets you graphically move the organisation unit to a different location. The new coordinate will be stored permanently. Browser cache must be deleted to see the change if you reload the page.

In the “Edit layer” window will find “surrounding areas” in addition to group set, level and parent. This lets you draw a circle around each facility with a desired radius in kilometers.

Boundary layer¶

The purpose of the boundary layer is to display the boundaries/coordinates in the system. No data will be shown. This layer is useful if you are offline and thus have no background map. Click the boundary/globe icon on the toolbar and select “Edit layer”. You can select the organisation units you want to show on the map by selecting a level and a parent. That means “show all organisations units at this level that are children of this parent”. When there are visible organisation units on the map, you can easily navigate up and down in the hierarchy without using the level/parent user interface. By clicking one of the organisation units a context menu will open, then select “drill down” or “float up”. The drill down option will be disabled if you are already on the lowest level or if there are no coordinates available on the level below. Vice versa goes for floating up.

The layer menu also offers to put on labels and to locate an organisation unit in the map.

The final option in the layer menu is “Close”. This completely resets the layer content, the edit layer form and the legend panel.

Thematic layer 1-4¶

The four thematic layer panels let you use your data for thematic mapping. All you need to do is selecting your desired combination of indicator/dataelement, period and map combination. Then the organisation unit level and parent to define the boundaries. If your database has coordinates and aggregated data values for these organisation units they will appear on the map. Note that the iROAD2 data mart must be run in order to have aggregated values available.

You may choose between legend types: automatic and predefined. Automatic means that the application will create a legend set for you based on your what method, number of classes, low color and high color you select. Method alludes to the size of the legend classes. Set to Equal intervals they will be highest map value “-” lowest map value / number of classes. Set to Equal group count the legend creator will try to distribute the organisation units evenly. The legend will appear as an even gradation from the start color to the end color. Predefined legend sets are described in Section 17.3.2, Create predefined legend sets.

Low radius and high radius only have effect on points (facilities) and decides the circle radius for points with the lowest and highest value.

Thematic layer 1-4 menu have a “Filter” option in addition to the boundary layer menu options. It lets you apply value filters to the organisation units on the map. The filter is removed when you close the filter window.

Event layer¶

The purpose of the event layer is to display the geographical location of events registered in the iROAD 2 tracker. This layer enables you to drill down from the aggregated data displayed in the thematic layers to the underlying individual events or cases.

To work with this layer, click the event layer icon on the map toolbar and select “Edit layer”. Select a program and then select a program stage. If there is only one stage available for the selected program, the stage will be automatically selected. A list of data elements and attributes will appear in the “Available data elements” panel. You are free to select and use any data element or attribute from this list as part of your query. To select you can either double-click a data element or (multi) select and use the single-arrow downward button. The double-arrow button will select all data elements in the list. All selected data elements will get their own row in the “Selected data elements”. You can also use an element multiple times in your query by clicking the + button. For data elements of type text you will get two choices: “Contains” implies that the query will match all values which contains your search value, and “Is exact” implies that only values which is completely identical to your search query will be returned. For data elements of type option set, you can select any of the options from the drop down box by using the down-wards arrow or by start typing directly in the box to filter for options.

The event layer also requires you to select the time span for when the events took place using the “start date” and “end date” date pickers under the “Periods” section, as well as the organisation units to include in the query under the “Organisation units” section.

To get information for an event you can simply click on it. This will open a dialog which displays all available information for that event.

The layer menu also offers to put labels on the map and to close the layer, which completely resets the layer content.

Tools¶

This section describes the available GIS tools.

Favorite maps¶

Click the “Favorites” button on the toolbar to open the “Manage favorites” window. To add a new favorite, click the “Add new” button. A new window opens. Enter a name and click the “Create” button. You will find your new favorite in the list.

All favorites have four action buttons on the right hand side. Grey: Edit favorite name. Green: Save current map to this favorite (overwrite). Yellow: Add this favorite to dashboard. Red: Delete this favorite.

You can search for favorites in the textfield above the favorites. The list will be filtered on every character that is entered. Click the “next” and “prev” buttons in the bottom right corner to navigate between pages.

Create predefined legend sets¶

Click the “Legend” button on the map toolbar. To create a new set click the “Add new” button. Example usage (vaccination coverage): Firstly, give the legend set a name. Then create the legends you want in your legend set. The first one could be “Low bad” (name), 0 (start value), 50 (end value), red (color). Click “Add legend” and appears in the list below. Then create “Medium” / 50 / 80 / yellow, “High good” / 80 / 100 / green and finally “Too high” / 100 / 10000 / grey. Now, click the “Create” button in the bottom right corner. If your legend set has overlapping legends (e.g. 0-50 and 40-80) you will not be allowed to proceed. If your legend set has a gap between the legends (e.g. 0-50 and 60-80) you will get a warning, but are allowed to proceed.

NOTE! Continuous legends are supposed to end and start on the same value, e.g. 0-50 and 50-80. This will automatically be taken care of by the application. Do not try to do this yourself by setting legends to e.g. 0-50 and 51-80. This will cause a usually unwanted gap in your legend set.

You can assign a legend set to an indicator or a data element in the Indicator/Data element module. This legend set will then be automatically selected when such an indicator/data element is selected in the GIS.

Download map as image¶

Click the “Download” button on the map toolbar. Enter a name in the textfield and click “Download”. The browser will download a PNG image. If the toolbar “Download” button is disabled you need to create a map first.

Share map interpretation¶

Open a favorite or save a new map as a favorite. Then click the “Share” button on the map toolbar. Type in your interpretation and click “Share”.

Embed maps in any web page¶

Certain analysis-related resources in iROAD, like pivot tables, charts and maps, can be embeded in any web page by using a plugin. If you have created a map in the GIS app you will get the plugin configuration for this map by clicking the “Share” button the toolbar and then “Embed as plugin”. You will find more information about the plugins in the web api chapter.

Analysis integration¶

The analysis apps in iROAD 2 are completely integrated, so you can easily switch between pivot table, chart and map visualization of your data. When you have made a map you can click e.g. “Chart” in the top right corner and then select “Open this map as chart”.

Setting up GIS¶

..index:: Setting up GIS

Setting up GIS¶

Context¶

Setting up the GIS simply means storing coordinates for the organisation units you want to show on the map in the database. Coordinates are often distributed in proprietary formats and will need to be converted to a format which DHIS2 understands. ESRI shapefiles are the most common geospatial vector data format for desktop applications. You might find shapefiles for your country here or in many other geospatial data repositories on the web. Some amount of work needs to be done in order to use these coordinates in DHIS 2 GIS, namely transforming the data into a suitable format and ensuring the name which are contained in the geospatial data match exactly with the names of the organization units which they should be matched to.

If you go to the organisation unit module and edit one of the units, you can see a text field called Coordinates. Here you may fill in its coordinates directly (geojson format) which is useful if you just want to update a couple of units.

An example point/facility coordinate:

[29.341,-11.154]

An example polygon/area coordinates string:

[[[[29.343,-11.154],[28.329,-11.342],[28.481,-10.239],[29.833,-10.412]]]]

However, if you are going to e.g. add coordinates for all units at a certain level you don’t want to do that manually. This is where the automatic GML import comes into play and the following section explains the preferred way of using it.

[Important] Important:: The only co-ordinate reference system supported by DHIS2 is EPSG:4326, also known as geographic longitude/latitude. Coordinates must be stored with the longitude (east/west position) proceeding the latitude (north/south position). If your vector data is in a different CRS than EPSG 4326, you will need to re-project the data first before importing into DHIS2.

Importing coordinates¶

Step 1 - Simplify/generalize your geographical data

The boundaries in geographical data files are usually very accurate, too much so for the needs of a web-based GIS. This usually does not affect the performance when using GIS files on a local system, but it is usually necessary to optimize the geographical data for the web-based GIS system of DHIS2. All geographical data needs to be downloaded from the server and rendered in a browser, so if the data is overly complex, the performance of the DHIS2 GIS will be negatively impacted. This optimization process can be described as follows:

Coordinates: The number of significant decimal digits (e.g. 23.02937874993774) should be shortened to fewer digits (e.g. 23.03). Although this will result in some inaccuracies on the map, given the usual scale at which maps in DHIS2 are produced (> 1:50,000), the loss of precision should not be noticeable. Normally, no more than four significant digits after the decimal point should be necessary. Polygons: In addition to shortening the number of significant digits, the actual number of points should also be reduced to an optimal level. Finding this optimal level may take a bit of experimentation. Decreasing the precision of the points as well as the number of points through generalization, will lead to degradation of the polygon. However, after a bit of experimentation, an optimal level of generalization can be found, where the accuracy of the polygon is visually acceptable, and the performance of the GIS is optimal.

For polygons, we need to make the boundary lines less detailed by removing some of the line points. Make a backup of your shapefiles before you start. One possible method is the use of MapShaper which is an online tool which can be used to generalize geographical data. To use MapShaper, simply upload your shapefile to the site. Then, at the center bottom you see a slider that starts at 0%. It is usually acceptable to drag it up to about 80%. In the left menu you can check “show original lines” to compare the result and you may want to give a different simplification method a try. When you are happy with the result, click “export” in the top right corner. Then check the first of the four options called “Shapefile - polygons”, click “create” and wait for the download buttons to appear. Now, download the two files to your local computer and overwrite the existing ones. Move on to the next step with your new simplified shapefile.

Step 2 - Convert the shapefile to GML

The recommended tool for geographical format conversions is called “ogr2ogr”. This should be available for most Linux distributions sudo apt-get install gdal-bin. For Windows, go to http://fwtools.maptools.org/ and download “FWTools”, install it and open up the FWTools command shell. During the format conversion we also want to ensure that the output has the correct coordinate projection (called EPSG:4326 with geographic longitude and latitude). For a more detailed reference of geographic coordinates, please refer to this site. If you have already reprojected the geographic data to the geographic latitude/longitude (EPSG:4326) system, there is no need to explicitly define the output coordinate system, assuming that ogr2ogr can determine the input spatial reference system. Note that most shapefiles are using the EPSG:4326 system. You can determine the spatial reference system by executing the following command:

ogrinfo -al -so filename.shp

Assuming that the projection is reported to be EPSG:27700 by ogrinfo, we can transform it to EPSG:4326 by executing the following command:

ogr2ogr -s_srs EPSG:27700 -t_srs EPSG:4326 -f GML filename.gml filename.shp

If the geographic data is already in EPSG:4326, you can simply transform the shapefile to GML by executing the following command:

ogr2ogr -f GML filename.gml filename.shp

You will find the created GML file in the same folder as the shapefile.

Step 3 - Prepare the GML file

Unfortunately, the GML file is not ready for importation yet. Open it in a robust text editor like Geany (Linux) or Notepad++ (Windows). GML is an XML based format which means that you will recognize the regular XML tag hierarchy. In the GML file an organisation unit is represented as a <gml:featureMember>. Inside the feature members we usually find a lot of attributes, but we are just going to import their coordinates.

In order to import geospatial data from the feature members of the GML input, DHIS 2 must match each of them with an organisation unit in its database. The feature member element must, in other words, contain a reference to its corresponding organisation unit. The reference itself must be one of three possible DHIS 2 identifiers: uid, code or name. The identifier of choice must be provided as a property for each feature member element. The importer will look for a property with the local name of either Uid, Code or Name, e.g. “ogr:Name” or “anyPrefix:Code”.

If your feature members already contain a property of the identifier you wish to use (such as the name of an area) you can use search and replace in a text editor to rename these elements to a name DHIS 2 will recognize (see the below table). This is typically a workflow which is applicable when using the name as the identifier (the source shapefile or even GML will usually contain the name for each area it defines).

Table 18.1. Organisation unit identifiers supported for GML import

Matching priority	Identifier	Valid spellings		Header 4
1	Uid	uid, Uid, UID		Yes
2	Code	code, Code, CODE | No
3	Name	name, Name, NAME | No

In the case of renaming properties one would usually find a tag named something like “ogr:DISTRICT_NAME”, “ogr:NAME_1” and rename it to “ogr:Name”. If using the code or uid identifiers on the other hand, looking up the correct values in the DHIS 2 database and going through the GML file, adding the properties for each corresponding feature member might be necessary. In any of the cases it is important to realize that the identifier used must uniquely identify an organisation unit (e.g. if there are two organisation units in the database of the same name or code, these cannot be matched properly on either). As uid is the only guaranteed-to-be-unque identifier it is the most robust choice. However, as matching on name is usually easier (given that the name is already part of your data), a viable approach to solving uniqueness conflicts can be to match any non-uniquely named organisation units on a different identifier (uid, preferrably) and the rest on their names.

As can be seen in the above table there is a matching priority, meaning is any two or more identifiers are provided for the same feature member, matching will be performed on the highest priority identifier. Note also the valid properties which can be used in you GML. The namespace prefix is not important as only the local name is used.

A common pitfall of performing preparation of the GML files is syntax- or element naming errors. Therefore please make sure that all properties of the GML file are started and terminated with correctly corresponding tags. Also make sure the properties follow either of the given valid spellings of the property name. The identifying properties are supposed to look like e.g. <ogr:Name>Moyamba District</ogr:Name>, <somePrefix:uid>x7uuia898nJ</somePrefix:uid> or <CODE>OU_12345</CODE>. Another common error is not making sure the identifier matches exactly, especially when using the name property. All matches are performed on exact values, meaning that “Moyamba” in a source GML file would not be matched against “Moyamba District” in the database.

Have a brief look at the identifiers and compare them to the corresponding values in the database. If they seem to match fairly good, it is about time to do a preview in the import-export module.

Go to Services -> Import-Export, select “Preview”, select the GML file and click “Import”. Look for new/updated organisation units. Our intention is to add coordinates to already existing organisation units in the database, so we want as many updates as possible and 0 new. Those listed as new will be created as root units and mess up the organisation unit trees in DHIS 2. If any listed as new, click the number and the organisation units in question will appear in the list below. If there are any slight misspellings compared to the organisation unit names in the database - fix them and do the preview again. Otherwise, click the “discard all” button below the list and then the “Import all” button above the list.

If the import process completes successfully, you should now be able to utilize the geographical data in the DHIS2 GIS. If not, check the log for hints and look for common errors such as:

• Name duplicates in the GML file. The name column in the database is unique and does not accept two organisation units with the same name.
• The “shortname” column in the organisationunit table in your database has a too small varchar definition. Increase it to 100.
• Special name characters in the GML file. Be sure to convert these to appropriate XML equivalents or escape sequences.
• Wrongly formatted input GML, non-matching tags

Data Administration¶

..index:: System Settings

System Settings¶

The data administration module provides a range of functions to ensure that the data stored in the iROAD2 database is integral and that the database performance is optimised. These functions should be executed on a regular basis by a data administrator to ensure that the quality of the data stored is optimal.

Data browser¶

The data browser maintenance and analysis module which allows the user to produce a summary of the data contained in the iROAD2 database. The summary view provides a count of data elements which have been entered at the selected organisation unit as well as its descendants. Raw data for all data elements for a range of time periods and a given organisational unit can be browsed and exported to Excel, CSV, or PDF formats. There are four modes of the data browser, which determine how the data is summarized

• Data sets
• Data element groups
• Organisational unit groups
• Organisational units

Each of these options can be accessed by selecting the desired option from “Browse by” drop-down menu. In order to produce a summary of submitted data for a given period and grouped by data sets, the user should follow this procedure. Begin by selecting a given periodicity type (e.g. Weekly, monthly, yearly, etc) and then a “From date” and “To date”. (e.g. January 2009 to March 2009). Select the type of summary to be produced (e.g. Dataset) from the “Browse by” drop-down menu. Click the “Browse” button to view the summary.

A summary of the number of data element values that have been submitted over the user selected time period is shown below.

Data integrity¶

iROAD2 can perform a wide range of data integrity checks on the data contained in the database. Identifying and correcting data integrity issues is extremely important for ensuring that the data used for analysis purposes is valid. Each of the data integrity checks that are performed by the system will be described, along with general procedures that can be performed to resolve these issues.

Data elements without data set¶

Each data element must be assigned to a data set. Values for data elements will not be able to be entered into the system if a data element is not assigned to a data set. Choose Maintenance->Datasets->Edit from the main menu and then add the “orphaned” data element to the appropriate data set.

Data elements without groups¶

Some Data Elements have been allocated to several Data Element Groups. This is currently not allowed, because it will result in duplication of linked data records in the analytics record sets that provide aggregated data. Go to Maintenance -> Data Element Groups to review each Data Element identified and remove the incorrect Group allocations.

Data elements violating exclusive group sets¶

Some data elements have been allocated to several data element groups that are members of the same data element group set. All group sets in iROAD2 are defined as exclusive, which means that a data element can only be allocated to one data element group within that group set. Go to Maintenance -> Data elements and indicators ->Data element groups to review each data element identified in the integrity check. Either remove the data element from all groups except the one that it should be allocated to, or see if one of the groups should be placed in a different group set.

Data elements in data set but not in form or sections¶

Data elements have been assigned to a data set, but have not been assigned to any sections of the data set forms. All data sets which use section forms, should generally have all data elements in the data set assigned to exactly one section of the dataset.

Data elements assigned to data sets with different period types¶

Data elements should not be assigned to two separate data sets whose period types differ. The recommended approach would be to create two separate data elements (for instance a monthly and yearly data element) and assign these to respective datasets.

Data sets not assigned to organisation units¶

All data sets should be assigned to at least one organisation unit.

Sections with invalid category combinations¶

Data sets which use section forms should only have a single category combination within each section. This violation could result from assigning a data element to a section, but then changing the category combination of this data element at a later point in time.

Indicators with identical formulas¶

Although this rule will not affect data quality, it generally does not make sense to have two indicators with the exact same definition. Review the identified indicators and their formulas and delete or modify any indicator that appears to be the duplicate.

Indicators without groups¶

All data elements and indicators must be assigned to at least one group, so these Indicators need to be allocated to their correct Data Element and Indicator Group. From the main menu, go to Data elements/Indicators -> Indicator Groups, and allocate each of the Orphaned indicators to its correct group.

Invalid indicator numerators¶

Violations of this rule may be caused by an incorrect reference to a deleted or modified data element. Review the indicator and make corrections to the numerator definition.

Invalid indicator denominators¶

Violations of this rule may be caused by an incorrect reference to a deleted or modified data element. Review the indicator and make corrections to the denominator definition.

Indicators violating exclusive group sets¶

Some indicators have been allocated to several indicator groups that are members of the same indicator group set. All group sets in iROAD2 are defined as exclusive, which means that an indicator can only be allocated to one indicator group within that group set. Go to Maintenance -> Data elements and indicators ->Indicator groups to review each indicator identified in the integrity check. Either remove the indicator from all groups except the one that it should be allocated to, or see if one of the groups should be placed in a different group set.

Duplicate periods¶

If periods have been imported from external applications, it may be possible that some periods will be duplicated. If you have any periods which appear to be duplicated here, you will need to resolve these directly in the iROAD2 database. All data which has been assigned to the duplicated period, should be moved to the correct period, and the duplicate period should be removed.

Organisation units with cyclic references¶

Organisation units cannot be both parent and children of each other, directly nor indirectly. If this situation occurs, you will need to resolve the cyclic reference directly in the iROAD2 datrabase in the “organisationunit” table, by reassigning the “parentid” field of the organisation units.

Orphaned organisation units¶

All organisation units must exist within the organisation unit hierarchy. Go to Organisation- units >Hierarchy Operations and move the offending organisation unit into the proper position in the hierarchy.

Organisation units without groups¶

All organisation units must be allocated to at least one group. The problem might either be that you have not defined any compulsory OrgUnit Group Set at all, or that there are violations of the compulsory rule for some OrgUnits . NOTE: If you have defined no compulsory OrgUnit Group Sets, then you must first define them by going to Organisation units>Organisation unit group sets and define at least one compulsory Group Set (the group set ‘Type’ are nearly universally relevant). If you have the relevant group sets, go to Maintenance -> OrgUnit Groups to review each OrgUnit identified and add the relevant Group allocation.

Organisation units violating compulsory group sets¶

These organisation units have not been assigned to the any organisation unit group within one of the compulsory organisation unit group sets. When a group set is defined as compulsory, it means that an organisation unit must be allocated to at least one organisation unit group within that group set. For instance, all organisation units must belong to one of the groups in the ‘Type’ group set. It might belong to the Hospital or the Clinic or any other ‘type’ group - but it must belong to exactly one of them. Go to Organisation units->Organisation unit groups to review each organisation unit identified in the integrity check. Allocate all organisation units to exactly one compulsory group.

Organisation units violating exclusive group sets¶

Some organisation units have been allocated to several organisation unit groups that are members of the same organisation unit group set. All group sets in iROAD are defined as exclusive, which means that an organisation unit can only be allocated to one organisation unit group within that Group Set. For instance, one organisation unit cannot normally belong to the both the ‘Hospital’ and ‘Clinic’ groups , but rather to only to one of them. Go to Organisation unit- >Organisation unit groups to review each organisation unit identified in the integrity check. Remove the organisation units from all groups except the one that it should be allocated to.

Organisation unit groups without group sets¶

The organisation unit groups listed here have not been allocated to a group set. Go to Maintenance->Organisation unit- >Organisation unit group sets and allocate the Organisation unit group to the appropriate group set.

Validation rules without groups¶

All validation rules must be assigned to a group. Go to Data quality->Validation rule group and assign the offending validation rule to a group.

Invalid validation rule left side expressions¶

An error exists in the left-side validation rule definition. Go to Data quality->Validation rule and click the “Edit” icon on the offending rule. Press “Edit left side” and make the corrections that are required.

Invalid validation rule right side expressions¶

An error exists in the left-side validation rule definition. Go to Data quality->Validation rule and click the “Edit” icon on the offending rule. Press “Edit right side” and make the corrections that are required.

Maintenance¶

The data maintenance module has five options, each described below.

• Clear analytics tables

Completely empties the analytics tables. These tables are used to generate aggregate data for the pivot tables, GIS and reports.

• Clear data mart (aggregated indicator and data value values)

The data mart is where iROAD 2 stores aggregated data produced during the export to data mart process. This function empties the database table which contains aggregated indicator and data element values.

• Rebuild data mart index

Rebuilds the database indexes on the aggregated data generated during a data mart process.

• Clear zero values

This function removes zero data values from the database. Values registered for data elements with aggregation operator average is not removed, as such values will be significant when aggregating the data, contrary to values registered for data elements with aggregation operator sum. Reducing the number of data values will improve system performance.

• Clear dataset completeness

This function empties the aggregated dataset completeness value table. This data is produced and used by report tables.

• Prune periods

This function removes all periods which have no registered data values. Reducing the number of periods will improve system performance.

• Remove expired invitations

Will delete users which represent user account invitations that now have gone past their expiry date.

• Create SQL views
• Will recreate all SQL views in the database.
• Update category option combinations

Rebuilds the category option combinations. This may be required after altering the category options which belong to a given category.

Resource tables¶

Resource tables are supporting tables that are used during analysis of data. One would typically join the contents of these tables with the data value table when doing queries from third-party applications like Microsoft Excel. They are also used extensively by the analysis modules of iROAD2. Regeneration of the resource tables should only be done once all data integrity issues are resolved. The resource tables are also generated automatically, every time the analytics process is run by the system.

• Organisation unit structure (_orgunitstructure)

This table should be regenerated any time there have been any changes made to the organisational unit hierarchy. This table provides information about the organisation unit hierarchy. It has one row for each organisation unit, one column for each organisation unit level and the organisation unit identifiers for all parents in the lineage as values.

• Data element group set structure (_dataelementgroupsetstructure)

This table provides information about which data elements are members of which data element group sets. The table has one row for each data element, one column for each data element group set and the names of the data element group as values.

• Indicator group set structure (_indicatorgroupsetstructure)

This table provides information about which indicators are members of which indicator group sets. The table has one row for each indicator, one column for each indicator group set and the names of the indicator group as values.

• Organisation unit group set structure (_organisationunitgroupsetstructure)

This table provides information about which organisation units are members of which organisation unit group sets. The table has one row for each organisation unit, one column for each organisation unit group set and the names of the organisation unit groups as values.

• Category structure (_categorystructure)

This table provides information about which data elements are members of which categories. The table has one row for each data element, one column for each category and the names of the category options as values.

• Data element category option combo name (_categoryoptioncomboname)

This table should be regenerated any time there have been changes made to the category combination names. It contains readable names for the various combinations of categories.

• Data element structure (_dataelementstructure)

This table provides information about all data elements and which period type (frequency) they capture data at. The period type is determined through the data set membership and hence relies on data elements to be member of data sets with similar period types to have a defined behavior.

• Period structure (_dataperiodstructure)

This table provides information about all periods and which period type they are associated with. For each period type with lower frequency than itself, it contains information about which period it will fall within.

• Data element category option combinations (_dataelementcategoryoptioncombo)

This table provides a mapping between data elements and all possible category option combinations.

Locale Management¶

It is possible to create custom locales in iROAD2. In addition to the locales available through the system, you might want to add a custom locale such as “English” and “Zambia” to the system. This would allow you to translate metadata objects to local languages, or to account for slight variants between countries which use a common metadata definition. The locale is composed of a language along with a country. Select the desired values and press “Add”. This custom locale will now be available as one of the translation locales in the system.

SQL View¶

The SQL View functionality of iROAD2 will store the SQL view definition internally, and then materialize the view when requested.

Database administrators must be careful about creating database views directly in the iROAD 2 database. For instance, when the resource tables are generated, all of them will first be dropped and then re-created. If any SQL views depend on these tables, an integrity violation exception will be thrown and the process will be aborted. The SQL views are dropped in reverse alphabetical order based on their names in iROAD 2, and created in regular alphabetical order. This allows you to have dependencies between SQL views, given that views only depend on other views which come earlier in the alphabetical order. For instance, “ViewB” can safely depend on “ViewA”. Otherwise, having views depending on other view result in an integrity violation error.

Creating a new SQL view¶

To create a new SQL view, choose Maintenance->SQL view and click the “Add new” button.

The “Name” attribute of the SQL view will be used to determine the name of the table that iROAD2 will create when the view is materialized by the user. The “Description” attribute allows one to provide some descriptive text about what the SQL view actually does. Finally, the “SQL statement” should contain the SQL view definition. Only SQL “SELECT” statements are allowed and certain sensitive tables (i.e. user information) are not accessible Press “Save” to store the SQL view definition.

SQL View management¶

In order to utilize the SQL views, simply press the “Execute query” button from the “SQL View management page. Once the process is completed, you will be informed that a table has been created. The name of the table will be provided, and is composed from the “Description” attribute provided in the SQL view definition. Once the view has been materialized, click on the “View” button

Organisation unit merge¶

This function is useful when two organisation units need to be merged, e.g. it is decided that one facility will be shut down and its services will be provided by a nearby facility.

Start by selecting the organisation unit to eliminate from the tree and click confirm. Then select the organisation unit to keep and click confirm again. Finally, verify the selection and click merge.

In the situation where data exist for the organisation unit to eliminate and not for the one to keep, the data will be moved to the one to keep. When data exists for both organisation units, the data will be summarized and moved to the one to keep. When data exists only for the one to keep, no action is taken. The organisation unit to eliminate will eventually be deleted.

Duplicate data elimination¶

This function is useful when data has been entered mistakenly for two data elements which represents the same phenomena.

Start by selecting the data element to eliminate from the list and click confirm. Then select the data element to keep and click confirm again. Finally, verify the selection and click merge.

In the situation where data exists for the data element to eliminate and not for the one to keep, the data will be moved to the one to keep. When data exists for both data elements, the data which was updated last will be used. When data exists only for the one to keep, no action will be taken. The data element to eliminate will eventually be deleted, except when it is a multidimensional data element and has other data registered.

System Settings¶

..index:: Settings

System Settings¶

The settings module provides a set of application configuration options. There are two main groups of settings: the system settings apply to the whole system and all its users while the user settings apply to the environment of the currently logged in user. The system settings can be accessed from the maintenance menu, settings module. The user settings can be accessed under the profile menu, settings page.

System settings¶

The system settings section provides general configuration options and options specifically for appearance and email.

General settings¶

• Cache strategy: Decides for how long reports and responses related to analysis should be cached.

If you are using the scheduled, nightly data mart tasks it makes sense to put this on “Cache until 6 AM tomorrow”. This is because we know that data in reports change at that time, and you can safely cache data up to the moment when the data mart is updated. If you are loading data continuously into the datamart you should set it to “No cache”. If you load data very infrequently into data mart you should consider setting it to “Cache for two weeks”.

• Maximum number of analytics records: This number can be increased to provide more records from the analytics.

The default is 50,000 and can be increased

Warning:: You should be exceedingly careful when increasing the maximum number of analytics records, for instance to Unlimited. This could result in severe server instability, due to clients requesting large amounts of data from the system.

• Number of database server CPUs:

The number of CPU cores of your database server can be configured as a system setting. This allows the system to perform optimally when the database is hosted on a different server than the application server, as the analytics engine scales linearly on the number of available cores.

• Infrastructural data elements:

This setting defines a data element group where the member data elements should describe data about the infrastructure of organisation units. Examples of such infrastructural data elements could be population, doctors, beds, Internet connectivity and climate. This infrastructural data can currently be viewed in the GIS module in the facility information sheet.

• Infrastructural period type:

Sets the frequency for which the data elements in the infrastructural data elements group are captured. This will typically be yearly. When viewing the infrastructural data you will be able to select the time period of the data source.

• Feedback recipients:

This setting defines a user group where the members will receive all messages being sent through the function for writing feedback in the dashboard module. This will typically be members of the super user team who are able to support and answer questions coming from end-users.

• Maximum offline organisation unit levels:

This setting defines how many levels in the organisation unit hierarchy will be available offline in the organisation unit tree widget. Under normal circumstances you can leaves this on the lowest level, which is default behavior. Setting it to a higher level might be useful in order to reduce initial load time in cases where you have a large number of organisation units, typically more than 30 000.

• System notifications email address:

An email address can be specified to receive system notifications. Notifications about failures in processes such as analytics table generation will be sent here. This is useful for application monitoring.

• Data analysis std dev factor:

Sets the number of standard deviations for use in the outlier analysis performed on the captured data in the data entry module. The default value is 2; a high value will catch less outlier values than a low value.

• Days after period end to qualify for timely data submission:

Sets the number of days after the end of a period in which a data entry form must be marked as complete in order to be considered timely. This affects the “reporting rate” tool in the reporting module which lists forms marked as complete as well as marked as complete in time. The default value is 15.

• Phone number area code:

The area code for the area in which your deployment is located. Used for sending and receiving SMS.Typically, this would be a country code, for instance , +260 , which is the country code for Zambia.

• Help page link:

A URL can be provided for an alternative help source. This defines the URL which users will see when selecting Profile->Help.

• Google Analytics (Universal Analytics) Key:

Set your Google UA key here to provide analytics for your iROAD 2 instance. Most places are covered, but it will not be provided for custom apps. Read more about Google Analytics at http://google.com/analytics .

• Enable multi-organisation unit forms:

Enable support for entering data forms for multiple organisation units at the same time, in data entry, click on the parent organisation unit for the children that you want to enter data for, and the dataset list will include datasets that are assigned to the children of that parent.

• Omit indicator values with zero numerator value in data mart:

Defines whether aggregated indicator values with zero as the numerator value should be written to the indicator data mart table. Having such values written is required for instance when connecting Excel pivot tables to the data mart as Excel will need the numerator data to correctly aggregate up in the organisation unit hierarchy. If third-party tools like Excel are not used with the application this will reduce the total number of values written to the data mart (which again will improve performance) and could safely be set to omit.

• Put analytics in maintenance mode:

Puts the analytics engine / Web API resource in maintenance mode, implying that 503 Service Unavailable will be returned for all requests. This is useful when you need to perform maintenance on the server like rebuilding indexes while the server is running in production, in order to reduce load and more efficiently carry out the maintenance.

System appearance settings¶

• Application title: Sets the application title on the top menu.
• Application introduction: Sets an introduction of the system which will be visible on the top-left part of the login page.
• Application notification: Sets a notification which should be displayed to users. Will be visible on the front page under the login area.
• Application footer: Sets a text in the footer area of the login page.
• Style: Sets the style / look-and-feel of the system. The corresponding user style setting overrides this.
• Start page: Sets page / module which the user will be redirected to after logging in. The dashboard module is the recommended start module.
• Flag: Sets the flag which is displayed in the left menu of the dashboard module.
• Require authority to add to view object lists:

Will hide menu and index page items / links to lists of objects if the current user does not have the authority to create the type of objects (privately or publicly).

Email settings¶

• Host name: Refers to the host name of the SMTP server. For instance when using Google SMTP services this should be smtp.gmail.com.
• Port: The port to connect to the SMTP server.
• User name: The user name of the user account with the SMTP server. For instance mail@iROAD2.org.
• Password: The password of the user account with the SMTP server.
• TLS: Refers to whether the SMPT server requires TLS for connections.

Access settings¶

• Self registration account user role:

Defines which user role should be given to self-registered user accounts. To enable self-registration of users, select any user role from the list. To disable it, select “Do not allow self registration”. When enabled, a link to the self-registration form will be displayed on the login page.

• Do not require recaptcha for self registration:

Whether or not to use reCAPTCHA for user registration.

• Self registration account organisation unit:

Defines which organisation unit should be associated with self-registered users. Any organisation unit must be selected in order to enable self registration.

• Enable user account recovery:

Defines whether users are allowed to restore the password of their account if they forgotten it. When enabled, a link to the account recovery form will be displayed on the front page. User account recovery requires that you have configured email settings (SMTP).

• Enable user account invite:

Defines user account invites can be sent. Account invites let you invite new users to create their own accounts by sending an email invitation.

• Allow users to grant own user roles:

Defines whether users should be allowed to grant the user roles they are granted themselves to others.

• Users must belong to a group controlled by the user manager:

This allows user groups to play a role in user management. When checked, user A can manage user B only if user B belongs to a user group to which user A has read/write access. When user A creates a new user, she or he must assign the new user to such a user group.

• Require user account password change:

Require that users change their password every 3,6,12 months. Please note that for 2.14 release, they will have to login through the desktop to change passwords.

• OpenID provider: Defines the OpenId provider.
• OpenID provider label: Defines the label to display for the specified OpenID provider.

Calendar settings¶

• Calendar:

Defines which calendar system should be used throughout the system. There are currently eight calendar systems which are supported, namely Coptic, Ethiopic, Gregorian, Julian, Islamic, ISO, Nepal and Thai. Note that this is a system wide setting. It is not possible to have multiple calendars within a single iROAD2 instance.

• Date format:

Defines which date format should be used throughout the system.

Synchronization settings¶

• Remote server URL: The URL of the remote server running iROAD 2 to upload data values to.

Use of SSL/HTTPS is recommended since username and password is sent with the request (using basic authentication). The system will attempt to synchronize data once every minute. Note that you must enable data synch from Data administration > Scheduling.

• Remote server username:

The username of the iROAD 2 user account on the remote server to use for data synchronization.

• Remote server password:

The password of the iROAD 2 user account on the remote server. The password will be stored encrypted.

Remote access settings¶

• CORS whitelist: A list of domains to acccept cross-origin requests for resources. CORS is a mechanism that allows resources to be requested from another domain. This means e.,g. that you can make requests to the iROAD 2 Web API from a web page or portal living on another domain than the iROAD 2 instance.

Contributions¶

Contribute to Software Source Codes¶

Code¶

In case you will notice inconsistencies in the iROAD System please folow the instructions below.

Reporting a Bug¶

Whenever you find a bug in iROAD, we kindly ask you to report it. It helps us make a better iROAD.

Reporting a Security Issue¶

If you find a security issue in iROAD please do not reveal the issue to the public, report it to the iROAD-Project Team via John F. Mukulu

For each report, we first try to confirm the vulnerability. When it is confirmed, the Team works on a solution following these steps:

1. Send an acknowledgement to the reporter;
2. Work on a patch;
3. Write a post describing the vulnerability, the possible exploits, and how to patch/upgrade affected applications;
4. Apply the patch to all maintained versions of iROAD;
5. Inform the reporter of the Security Issue that the Issue has been resolved:

Note

While we are working on a patch, please do not reveal the issue publicly.

Contribute to Documentation¶

Documentation is as important as code. It follows the exact same principles: DRY, tests, ease of maintenance, extensibility, optimization, and refactoring just to name a few. And ofcourse documentation has bugs, typos, hard to read tutorials, and more. Human resource for health information system 3.0. source code and documentation are hosted on github:

• iROAD Website - https://github.com/MorleyMinde/rsmsa.git
• iROAD Documentation - https://github.com/mukulu/roadsafety-docs

If you want to submit a patch, fork the official repository on GitHub and then clone your fork:

$ git clone git://github.com/YOURUSERNAME/hris-docs.git

Make your changes into the documentation, when you’re done create a pull request on github.

GitHub covers the topic of pull request in detail.

Contributing¶

Before contributing, you need to become familiar with the markup language used by the documentation.

iROAD Documentation uses reStructuredText as its markup language and Sphinx for building the output(HTML,PDF, etc...).

reStructuredText¶

reStructuredText “is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system”.

If you’re familiar with Markdown, be careful as things are sometimes very similar but different

• Lists start at the beggining of a line(no indentation)
• Inline code blocks use double-ticks(like this)

Quick overview on reStructuredText can be found on sphnix website A more detailed documentation can be found at reStructuredText website

Sphinx¶

Sphnix is a build system that adds some nice tools to create documentation from reStructuredText documents. As such, it adds new directives and interpreted text roles to standard reST markup.

Quick overview on setting your sphinx up for documentation can be found from matplotlib website, a more detailed documentation can be found at sphnix website

Testing Documentation¶

To test documentation before a commit:

• Install Sphinx;
• Run the Sphinx quick setup;
• Install the Sphinx extensions (see below);
• Run make html and view the generated HTML in the build directory.

Installing the Sphinx extensions¶

Download the extension from the source repository Copy the sensio directory to the _exts folder under your source folder (where conf.py is located) Add the following to the conf.py file:

# ...
sys.path.append(os.path.abspath('_exts'))

# adding PhpLexer
from sphinx.highlighting import lexers
from pygments.lexers.web import PhpLexer

# ...
# add the extensions to the list of extensions
extensions = [..., 'sensio.sphinx.refinclude', 'sensio.sphinx.configurationblock', 'sensio.sphinx.phpcode']

# enable highlighting for PHP code not between ``<?php ... ?>`` by default
lexers['php'] = PhpLexer(startinline=True)
lexers['php-annotations'] = PhpLexer(startinline=True)

# use PHP as the primary domain
primary_domain = 'php'

Generating PDF Using rest2pdf¶

st2pdf user manual (you can simply refer to the “Sphinx” chapter) https://docs.google.com/viewer?url=http%3A%2F%2Fsphinx.pocoo.org%2Fsphinx-rst2pdf.pdf

Install rst2pdf

• use your package manager (or)
• pip install rst2pdf (or)
• easy_install rst2pdf

Add rst2pdf to the list of extensions in conf.py:

extensions = ['rst2pdf.pdfbuilder']

This list will be empty if you accepted the defaults when the project was setup. If not, just append ‘rst2pdf.pdfbuilder’ to the list.

Add a pdf_documents variable to conf.py:

pdf_documents = [('index', u'rst2pdf', u'Sample rst2pdf doc', u'Your Name'),]

# index - master document
# rst2pdf - name of the generated pdf
# Sample rst2pdf doc - title of the pdf
# Your Name - author name in the pdf

For all supported options, please check the manual

Generate pdf:

sphinx-build -b pdf source build/pdf

The generated pdf will be in the build/pdf directory.

Financing the Open Source Project¶

References¶

Project References

iROAD Best Practices¶

Recommendations for Deployment and Implementation

Indices and tables¶

• Index
• Module Index
• Search Page