Project description

In the DHIS 2.0 software data is collected in DataElements. DHIS also
has indicators which show trends and relations between values being
collected. Indicators is then used as a way of connecting and showing
the relationship between different types of data. One example could be
an indicator who shows the relation between the population in an area
and how many of those being vaccinated last year.

Targets are a way of defining goals to reach over time for these
trends and relations. Example: Target is 90% vaccination coverage for
children below 5 years within year 2008.

The Target project consist of fitting the target concept into the rest
of the software. Making it easy for the end user to define, select
store, and display targets in the DHIS 2.0 software

This means that the project must look into both the persistence layer
and the web presentation layer of the software.

Group members and division of labour

The project has been developed by four students in course INF5750
(Open Source Software development and Java frameworks in global networks)
at the University of Oslo, Norway.

Name	Username AT ifi.uio.no	Task
Jan Tore Bøe	jantb	dhis-web-targets. Research. Setting up the web application
Arne Hanssen	arnehans	dhis-web-targets. Documentation
Aleksander Blomskøld	aleksabl	Setting up the modules, the API/hibernate part
Ismar Slomic	ismars	dhis-web-targets. GUI drafts and documentation

Goals

The main goal of this project is to write and commit source code to the
code base which provides the functionality needed for an end user to
define targets with a given name, description and a target value. The
end user should be able to define the target as either a
IndicatorTarget (a Target linked to an Indicator), or a DataElementTarget.
(a Target linked to a DataElement). The software must also make
it possible to connect the target defined with current and past
Indicator and DataElement values.

The software developed should also make it possible to connect the
target defined to an OrganisationUnit and a Period. (time-period)

Achievement

What we achieved

We achieved to design a data model that should be sufficient to solve
the problem given in the description. This we have done by making an
UML-model of the concepts found in the domain and implemented them as
classes in Java.

We've also made some basic services for the Targets module (an
API). Currently, the API only supports basic CRUD-actions, and this is
something that we think should be be extended in the future.

We've also made a basic web-gui to test the functionality. This
web-module is currently not very well-integrated in the DHIS-project.

What we didn't achieve and why

We did not achieve to make a fully functional module as we originally
had intended . The main reason for this was lack of skills from our
side. We used a lot of time in learning new technologies and striving
to do basic tasks in for instance Maven 2, Spring, WebWork, Velocity,
etc. This meant we had very little time to do coding.

What we're currently missing is:

Business logic in the API. For instance have we not made a method
that checks if a Target is reached or not.

Good integration with the current HISP web pages.

Our master plan was to re-use one of the other modules to do the data
input and output. But we experienced lot of technical problems when we
tried to fit the module in with the rest of what we had done. So
after hours upon hours of frustration and anger we ended up by making
some rudimentary stand-alone web pages in order to some testing of the
input and output facilities of the system. It should be noted that
these pages are very basic with very little integrated with the rest
of the DHIS web pages.

Future plans

As mentioned above, we're currently missing some functionality in the API (which we think it should be easy to add later), and web pages that are integrated with the current DHIS web pages.

GUI drafts - integration with DHIS

Our idea is that it could be useful to list all targets for one specific organization unit. By selecting one org.unit in the tree
you get a list of all targets that is registered. Then you can manage targets from this page. Note that there is no "Add new" button
for adding new Target at this page. This is only possible when a specific Target or DataElement is selected (see next draft).

Other way to list registered targets is to click the "Target management" button for specific DataElement or Indicator.
We will then get a list of all registered targets ( see next draft ) and this is also the only way for adding new Targets.
Because we will be sure to get which Indicator or DataElement we want to connect the new Target to, before filling the
information about it.

In the edit page you can change information about the target, such as connect it to another
DataElement ( or Indicator for IndicatorTarget ) and choose another organization unit.
As we can see, we have only drop down list for DataElements. This is because displayed
Target is of type DataElementTarget and it's only possible to make change of relation between Target and DataElement.
The same thing is valid for IndicatorTargets. Since the form for add and edit target are very similar, we will not show add target draft.

Detailed documentation

Data model

We extended the DHIS-data model with three new classes:

Target: An abstract class which is the super class of the two other targets.
IndicatorTarget: A target which is linked to an Indicator.
DataElementTarget: A target which is linked to a DataElement.
Here is a UML-diagram showing the persistent objects in the Targets module
and their relationships to some of the objects outside the Targets module:

As the diagram shows, a Target has a many-to-one relationship with an
OrganisationUnit and either a DataElement or a Indicator, dependent
upon what type of Target we are talking about. A Target has also an
association to a Period.

The relation between a target and an Indicator should be self evident
but why do we need to connect a target to a dataElement?. The reason
for this can be contemplated in this example: You have 6 beds in your
clinic. You have a DataElement named "Number of beds". You want to
have 10 beds at the end of 2008 and so you create a suitable target
for this DataElement.

dhis-api-targets

This module is made as a front end for the business logic in the
developed module . Through the TargetDataStore.java interface the
dhis-web-targets module offers a way to persist and to collect
target data . The Target class serves as a superclass for the
different types of target one can define in the system. The
dhis-api-targets also has a TargetStoreException class which is used to
signal errors.

dhis-api-targets is a branch of dhis-api from trunk. The following files were added (no files was modified):

Target.java a java-implementation of the abstract class shown in the UML-diagram above. Equals and hashcode methods were implemented too.
DataElementTarget.java a java-implementation of the persistant class shown in the UML-diagram above.
IndicatorTarget.java a java-implementation of the persistant class shown in the UML-diagram above.
TargetStoreException.java an Exception-class to be used in the TargetStore.
TargetStore.java a interface that deals with services related to Targets. Now it's manly an interface for CRUD/DAO logic, but business logic might be added later.

dhis-web-targets

This is a module developed to make it possible for an end user to
input target data to the system. This module also make it possible to
look at previously entered target data.

The module uses the WebWorks a Java web-application development
framework as its web engine. And Velocity a Java-based template
engine.

CreateTargetsAction

The two main classes in the dhis-web-targets is CreateTargetsAction and
ListTargetsAction. CreateTargetsAction is used to define actions to
do when the user is inputing data into the defined form page. It has
an targetParameter array which set with data through the setName
method, and the setDescription method.

CreateTargetsAction also has a getIndicator method used to populate
the drop-down menu in the createTargets.vm file with indicators. We've
included a if-test in the getIndicator method which will make some
sample indicators if the software is run with an empty data-store.
This is only ment to be used in the test-stage, and should be removed
before the code hits production.

We also made a getOrganisationUnit method duplicating the actions in
the getIndicator method. The difference being this method returns a
collection of organisationUnits. Most important the
CreateTargetsAction class has a execute method performing the action
necessary to make a new Target. We also have med getters and setters
for the various variables in this class.

ListTargetsAction

This class is used in order to show defined targets. It has a
getTargets method and of course an execute method performing the
action necessary to display defined targets. The ListTargetsAction
class also has setters and getters for its variables.

Dependency injection

In the beans.xml found in the /dhis-web-targets/src/main/resources/META-INF/dhis/
path we have defined our beans. We use autowiring so the dependencies to the other
beans are not specified.

Xwork

In the /dhis-web-targets/src/main/resources/ path there is a xwork.xml
file used by the Velocity engine as a mapping between the web page
and the actions associated with it. In our module we have two
distinct actions. Mainly where the system should do when it receive a
createTarget of listTarget action.

Web-pages

The part of the web-page that we have defined is found in the
dhis-web-targets/src/main/webapp/dhis-web-targets directory.
Here we find 2 .vm files, createTarget.vm and listTarget.vm

These files contains the html code needed making the input forms and
other text the end user sees. The main point here is that the velocity
engine gives us access to the variables and methods defined in the
java files. So some of the code here is in the velocity template
language. e.g:

#foreach( $orgunit in $organisationUnits )
... do something ...
#end

The rest.

Inside the /dhis-web-targets/target/ directory one will find the rest
of the necessary stuff in order to making the web-pages happening.
The only thing we have done here is tweaking some of the dependencies
in the pom.xml file also found here.

dhis-service-datastore-hibernate

This is the module with the implementation of the service API interface made in dhis-api-targets. Hibernate mappings for the Target hierarchy is also located here. The joined-subclass (table-per-subclass) strategy was used for mapping the inheritance. This choice of inheritance strategy has not been tought very well trough, so it might be a good idea to change it in the future.

Placement of modules

All the modules are currently in the branches-directory, even though dhis-api-targets is the only module which in fact is a branch.