dhis2-devs team mailing list archive

[noreply@xxxxxxxxxxxxx]

------------------------------------------------------------
revno: 336
committer: Lars Helge Overland <larshelge@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Sat 2011-06-18 15:38:33 +0200
message:
  Added chapter on users/userroles and dataelements/categories
added:
  src/docbkx/en/dhis2_implementation_guide_users_and_user_roles.xml
renamed:
  src/docbkx/en/dhis2_implementation_guide_data_elements_and_forms.xml => src/docbkx/en/dhis2_implementation_guide_data_elements_and_custom_dimensions.xml
modified:
  src/docbkx/en/dhis2_implementation_guide_en.xml
  src/docbkx/en/dhis2_implementation_guide_data_elements_and_custom_dimensions.xml


--
lp:~dhis2-documenters/dhis2/dhis2-docbook-docs
https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs

Your team DHIS 2 developers is subscribed to branch lp:~dhis2-documenters/dhis2/dhis2-docbook-docs.
To unsubscribe from this branch go to https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs/+edit-subscription

=== renamed file 'src/docbkx/en/dhis2_implementation_guide_data_elements_and_forms.xml' => 'src/docbkx/en/dhis2_implementation_guide_data_elements_and_custom_dimensions.xml'
--- src/docbkx/en/dhis2_implementation_guide_data_elements_and_forms.xml	2011-02-12 16:14:18 +0000
+++ src/docbkx/en/dhis2_implementation_guide_data_elements_and_custom_dimensions.xml	2011-06-18 13:38:33 +0000
@@ -1,5 +1,38 @@
 <?xml version='1.0' encoding='UTF-8'?>
+<!-- This document was created with Syntext Serna Free. -->
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; []>
 <chapter>
-  <title>Data Elements and Forms</title>
+  <title>Data Elements and Custom Dimensions</title>
+  <para>This chapter first discusses an important building block of the system: the data element. Second it discusses the category model and how it can be used to achieve highly customized meta-data structure for storage of data.</para>
+  <section>
+    <title>Data elements</title>
+    <para>The data element is together with the organisation unit the most important building block of a DHIS 2 database. It represents the what dimension and explains what is being collected or analysed. In some contexts this is referred to an indicator, however in DHIS 2 this meta-data element of data collection and analysis is referred to as a data element. The data element often represents a count of some event and its name describes what is being counted, e.g. &quot;BCG doses given&quot; or &quot;Malaria cases&quot;. When data is collected, validated, analysed or presented it is the data elements or expressions built with data elements that describe what phenomenon, event or case the data is registered for. Hence the data element become important for all aspects of the system and decide not only how data is collected, but more importantly how the data is represented in the database and how data can be analysed and presented.</para>
+    <para>An important principle behind designing data elements is to think of data elements as a self-contained description of an phenomenon or event and not as a field in a data entry form. Each data element lives on its own in the database, completely detached and independent from the collection form. It is important to consider that data elements are used directly in reports, charts and other tools for data analysis, in which the context in any given data entry form is not accessible nor relevant. In other words, it must be possible to clearly identify what event a data element represents by only looking at its name. Based on this one can derive a rule of thumb saying 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. </para>
+    <para>For instance, a data element called “Malaria” might be concise when seen in a data entry form capturing immunization data, in a form capturing vaccination stocks as well as in a form for out-patient data. When viewed in a report, however, outside the context of the data entry form, it is impossible to decide what event this data element represents. If the data element had been called “Malaria cases”, “Malaria stock doses received” or “Malaria doses given” it would have been clear from a user perspective what the report is trying to express. In this case we are dealing with tree different data elements with completely different semantics.</para>
+  </section>
+  <section>
+    <title>Categories and custom dimensions</title>
+    <para>Certain requirements for data capture necessitates a fine-grained breakdown of the dimension describing the event being counted. For instance one would want to collect the number of “Malaria cases” broken down on gender and age groups, such as “female”, “male” and “&lt; 5 years” and “&gt; 5 years”. What characterizes this is that the breakdown is typically repeated for a number of “base” data elements: For instance one would like to reuse this break-down for other data elements such as “TB” and “HIV”. In order to make the meta-data more dynamic, reusable and suitable for analysis it makes sense to define the mentioned diseases as data elements and create a separate model for the breakdown attributes. This can be achieved by using the category model, which is described in the following.</para>
+    <para>The category model has three main elements which is best described using the above example:</para>
+    <orderedlist>
+      <listitem>
+        <para>The category option, which corresponds to “female”, “male” and “&lt; 5 years” and “&gt; 5 years”.</para>
+      </listitem>
+      <listitem>
+        <para>The category, which corresponds to “gender” and “age group”.</para>
+      </listitem>
+      <listitem>
+        <para>The category combination, which should in the above example be named “gender and age group” and be assigned both categories mentioned above.</para>
+      </listitem>
+    </orderedlist>
+    <para>This category model is in fact self-standing but is in DHIS 2 loosely coupled to the data element. Loosely coupled in this regard means that there is an association between data element and category combination, but this association may be changed at any time without loosing any data. It is however not recommended to change this often since it makes the database less valuable in general since it reduces the continuity of the data. Note that there is no hard limit on the number of category options in a category or number of categories in a category combination, however there is a natural limit to where the structure becomes messy and unwieldy.</para>
+    <para>A pair of data element and category combination can now be used to represent any level of breakdown. It is important to understand that what is actually happening is that a number of custom dimensions are assigned to the data. Just like the data element represents a mandatory dimension to the data values, the categories adds custom dimensions to it. In the above example we can now through the DHIS 2 output tools perform analysis based on both “gender” and “age group” for those data elements, in the same way as one can perform analysis based on data elements, organisation units and periods.</para>
+    <para>This category model can be utilized both in data entry form designs and in analysis and tabular reports. For analysis purposes, DHIS 2 will automatically produce sub-totals and totals for each data element associated with a category combination. The rule for this calculation is that all category options should sum up to a meaningful total. The above example shows such a meaningful total since when summarizing “Malaria cases” captured for “female &lt; 5 years”, “male &lt; 5 years”, “female &gt; 5 years” and “male &gt; 5 years” one will get the total number of “Malaria cases”.</para>
+    <para>For data capture purposes, DHIS 2 can automatically generate tabular data entry forms where the data elements are represented as rows and the category option combinations are represented as columns. This will in many situations lead to compelling forms with a minimal effort. It is necessary to note that this however represents a dilemma these two concerns are sometimes not compatible. For instance one might want to quickly create data entry forms by using categories which does not adhere to rule of a meaningful total. We do however consider this a better alternative than maintaining two independent and separate models for data entry and data analysis.</para>
+    <para>An important point about the category model is that data values are persisted and associated with a category option combination. This implies that adding or removing categories from a category combination renders these combinations invalid and a low-level database operation much be done to correct it. It is hence recommended to thoughtfully consider which breakdowns are required and to not change them too often.</para>
+  </section>
+  <section>
+    <title>Data element groups</title>
+    <para>Common properties of data elements can be modelled through what is called data element groups. The groups are completely flexible in the sense that they are defined by the user, both their names and their memberships. Groups are useful both for browsing and presenting related data, and can also be used to aggregate values captured for data elements in the group. 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 low-level data.</para>
+  </section>
 </chapter>

=== modified file 'src/docbkx/en/dhis2_implementation_guide_en.xml'
--- src/docbkx/en/dhis2_implementation_guide_en.xml	2011-06-17 19:45:02 +0000
+++ src/docbkx/en/dhis2_implementation_guide_en.xml	2011-06-18 13:38:33 +0000
@@ -40,9 +40,10 @@
     </legalnotice>
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="../build.properties" encoding="UTF-8"/>
   </bookinfo>
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_implementation_guide_users_and_user_roles.xml" encoding="UTF-8"/>
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_implementation_guide_data_elements_and_custom_dimensions.xml" encoding="UTF-8"/>
   <!-- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_implementation_guide_system_design.xml" encoding="UTF-8"/>
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_implementation_guide_database_development.xml" encoding="UTF-8"/>
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_implementation_guide_data_elements_and_forms.xml" encoding="UTF-8"/>
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_implementation_guide_harmonisation.xml" encoding="UTF-8"/>
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_implementation_guide_data_analysis.xml" encoding="UTF-8"/> -->
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_implementation_guide_installation.xml" encoding="UTF-8"/>

=== added file 'src/docbkx/en/dhis2_implementation_guide_users_and_user_roles.xml'
--- src/docbkx/en/dhis2_implementation_guide_users_and_user_roles.xml	1970-01-01 00:00:00 +0000
+++ src/docbkx/en/dhis2_implementation_guide_users_and_user_roles.xml	2011-06-18 13:38:33 +0000
@@ -0,0 +1,57 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!-- This document was created with Syntext Serna Free. -->
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; []>
+<chapter>
+  <title>Users and User Roles</title>
+  <para>DHIS 2 comes with an advanced solution for fine-grained management of users and user roles. The system is completely flexible in terms of the number and type of users and roles allowed.</para>
+  <section>
+    <title>Users</title>
+    <para>A user in the DHIS 2 context is a human who is utilizing the software. Each user in DHIS 2 has a user account which is identified by a username. A user account allows the user to authenticate to system services and be granted authorization to access them. To log in (authenticate) the user is required to enter a valid combination of username and password. If that combination matches a username and password registered in the database, the user is allowed to enter.</para>
+    <para>In addition, a user should be given a first name, surname, email and phone number. This information is important to get correct when creating new users since certain functions in DHIS 2 relies on sending emails to notify users about important events. It is also useful to be able to communicate to users directly over email and telephone to discuss data management issues or to sort out potential problems with the system.</para>
+    <para>A user in DHIS 2 is associated with an organisation unit. This implies that when creating a new user account that account should be associated to the location where user works. For instance when creating a user account for a district record officer that user account should be linked with the particular district where she works. The link between user account and organisation unit has several implications for the operation of the system:</para>
+    <itemizedlist>
+      <listitem>
+        <para>In the data entry module, a user can only be entering data for the organisation unit she is associated with and the organisation units below that in the hierarchy. For instance, a district records officer will be able to register data for her district and the facilities below that district only.</para>
+      </listitem>
+      <listitem>
+        <para>In the user module, a user can only create new users for the organisation unit she is associated with in addition to the organisation units below that in the hierarchy.</para>
+      </listitem>
+      <listitem>
+        <para>In the reports module, a user can only view reports her organisation units and those below. (This is something we consider to open up to allow for comparison reports.)</para>
+      </listitem>
+    </itemizedlist>
+    <para>A user role in DHIS 2 is also associated with a set of user roles. Such user roles are discussed in the following section.</para>
+  </section>
+  <section>
+    <title>User Roles</title>
+    <para>A user role in the DHIS 2 context is a group of authorities. An authority in this regard means the permission to perform one or more specific tasks. For instance, a user role may contain authorities to create a new data element, update an organisation unit or view a report. Such a group of authorities constitutes a user role.</para>
+    <para>In a health system the users are logically grouped with respect to the task they perform and the position they occupy. Examples of commonly found positions are:</para>
+    <orderedlist>
+      <listitem>
+        <para>National health managers</para>
+      </listitem>
+      <listitem>
+        <para>National health information system division officers (HISO)</para>
+      </listitem>
+      <listitem>
+        <para>Province health managers</para>
+      </listitem>
+      <listitem>
+        <para>District health records and information officers (DHRIO)</para>
+      </listitem>
+      <listitem>
+        <para>Facility health records and information officers (HRIO)</para>
+      </listitem>
+      <listitem>
+        <para>Data entry clerks</para>
+      </listitem>
+    </orderedlist>
+    <para>When creating user roles such positions within the health system should be kept in mind and it is often sensible to create a user role dedicated for each of those positions. The process of creating user roles should be aligned with the process of deciding which users are doing what tasks in the system.</para>
+    <para>First it should be defined which users should fulfill the role as system administrators. This will often a part of the members of the national HIS division and should have full authority in the system. Second a user role should be created roughly for each position. A sensible consideration of what authorities should be given each role must be done. An important rule is that each role should only be given the authorities which are needed to perform the job well - not more. When operating a large, centralized information system there is a need to coordinate the work between the people involved. This is made easier if only those who are supposed to perform a task have the authorities to perform it. </para>
+    <para>An example might highlight this issue: The task of setting up the basic structure (meta-data) of the system is critical to the system and should only be performed by the administrators of system. This means that the system administrator user role should have the authority to add, update and delete the core elements of the system such as data elements, indicators and data sets. Allowing users outside the team of system administrators to modify these elements might lead to problems with coordination.</para>
+    <para>National and provincial health managers are often concerned with data analysis and monitoring. Hence this group of users should be authorized to access and use the reports module, GIS module, data quality module and dashboard. However they would not need authority to enter data or update data elements and data sets. District information officers are often tasked with both entering data into the system coming from facilities which are not able to do so directly as well as monitoring, evaluation and analysis of data. This means that they will need access to all of the analysis and validation modules mentioned above in addition to the authority to access and use the data entry module.</para>
+    <para>In addition, a user role is associated with a collection of data sets. This affects the data entry module in that the user is only allowed to enter data for the data sets registered for her user role. This is often useful in situations where one wants to allow officers from health programs to enter data for their relevant data entry forms only.</para>
+    <para>A user can be granted one or any number of user roles. In the case of many user roles, the user is privileged with the sum of all authorities and data sets included in the user roles. This means that user roles can be mixed and matched for special purposes instead of merely creating new ones.</para>
+    <para>An important part of user management is to control which users are allowed to create new users with which authorities. In DHIS 2 one can control which users are allowed to perform this task. In this process the key principle is that a user can only grant authorities and access to data sets that the user itself has. The users at national, province and district level are often relatively few and can be created and managed by the system administrators. If a large part of the facilities are entering data directly into the system the number of users might become unwieldy. Experience suggests that delegating and decentralizing this task to the district officers will make the process more efficient and support the facility users better.</para>
+  </section>
+</chapter>