dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #24073
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 786: Fixed revision 770 on PDF imports.
------------------------------------------------------------
revno: 786
committer: Jason P. Pickering <jason.p.pickering@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Thu 2013-08-22 16:52:01 +0200
message:
Fixed revision 770 on PDF imports.
modified:
src/docbkx/en/dhis2_user_man_datasets_forms.xml
src/docbkx/en/dhis2_user_man_import_export.xml
src/docbkx/en/dhis2_user_manual_en.xml
--
lp:~dhis2-documenters/dhis2/dhis2-docbook-docs
https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs
Your team DHIS 2 developers is subscribed to branch lp:~dhis2-documenters/dhis2/dhis2-docbook-docs.
To unsubscribe from this branch go to https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs/+edit-subscription
=== modified file 'src/docbkx/en/dhis2_user_man_datasets_forms.xml'
--- src/docbkx/en/dhis2_user_man_datasets_forms.xml 2013-06-25 11:22:09 +0000
+++ src/docbkx/en/dhis2_user_man_datasets_forms.xml 2013-08-22 14:52:01 +0000
@@ -46,9 +46,9 @@
<listitem>
<para>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
+ 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.'</para>
+ planning data.'</para>
</listitem>
<listitem>
<para>All fields for data elements required: Defines whether it is mandatory to fill all
@@ -65,7 +65,7 @@
</listitem>
<listitem>
<para>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
+ 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.</para>
</listitem>
@@ -95,8 +95,7 @@
<para>Add new: Adds a new data set. When pressing this button, you can create a new data
set. You need to provide a name, shortname and frequency. The "Code" attribute
is optional. Data elements can be added to the "Selected data element" list by
- selecting them individually. and pressing the <inlinegraphic
- fileref="resources/images/dhis2_images/move_right.png"/> button. Indicators can also
+ selecting them individually. and pressing the <inlinegraphic fileref="resources/images/dhis2_images/move_right.png"/> button. Indicators can also
be added to data sets and will be available to be placed in custom data entry forms when
they need to be shown along with data elements on the same data entry form. Press
"Save" to add the new data set. </para>
@@ -176,8 +175,7 @@
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" <inlinegraphic fileref="resources/images/dhis2_images/move_up.png"/> and
- "Move down" <inlinegraphic
- fileref="resources/images/dhis2_images/move_down.png"/> buttons. Be sure to press
+ "Move down" <inlinegraphic fileref="resources/images/dhis2_images/move_down.png"/> buttons. Be sure to press
"Save" once you have finished.<note>
<para>You can only use one data element category combination per section. </para>
</note></para>
@@ -199,7 +197,7 @@
<screenshot>
<mediaobject>
<imageobject>
- <imagedata fileref="resources/images/datasets/grey_field_management.png" align="center" width="60%"/>
+ <imagedata width="60%" align="center" fileref="resources/images/datasets/grey_field_management.png"/>
</imageobject>
</mediaobject>
</screenshot>
@@ -253,18 +251,18 @@
of the form. There are two methods which can be used to hook into events in the data entry
module. To have your code invoked when a data entry form has been loaded you can add a
Javascript tag in your custom form like this:</para>
- <screen><script type="text/javascript">
+ <screen><script type="text/javascript">
onFormLoad( function() {
// Do your javascript stuff here
} );
-</script></screen>
+</script></screen>
<para>To have your code invoked when any data value is successfully saved in the form you can
add a Javascript tag like the example below. Note that you can access all properties for the
data value being saved through your callback function; the first parameter is the event
object while the second argument is the data value object being saved:</para>
- <screen><script type="text/javascript">
+ <screen><script type="text/javascript">
onValueSave( function( event, dataValue ) {
var de = dataValue.dataElementId;
@@ -275,10 +273,10 @@
// Do stuff like modifying the form based on the data element and value being saved
} );
-</script></screen>
+</script></screen>
<para>The identifiers of the input fields in the data entry form is on the format described
below. This format can be used to select the input fields in your script and perform actions
- on them:<screen><dataelementid>-<optioncomboid>-val</screen></para>
+ on them:<screen><dataelementid>-<optioncomboid>-val</screen></para>
</section>
<section id="dataSetAssignmentEditor">
<title>Data set assignment editor</title>
=== modified file 'src/docbkx/en/dhis2_user_man_import_export.xml'
--- src/docbkx/en/dhis2_user_man_import_export.xml 2013-06-25 11:22:09 +0000
+++ src/docbkx/en/dhis2_user_man_import_export.xml 2013-08-22 14:52:01 +0000
@@ -1,357 +1,364 @@
-<?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" "docbookV4.4/docbookx.dtd" []>
-<chapter>
- <title>Import and export</title>
- <para>In a primary health system, the HMIS typically involves a distributed application, where the
- same application is running in different geographical locations (PHCs,CHCs, hospitals,
- districts, and state). Most of these physical locations do not have Internet connectivity, and
- hence they work offline. At some point (normally at the district level), the data needs to be
- synchronised in order to have a consolidated database for the a particular geographical region.
- For this, it is important to be able to export data from one location (which is working offline,
- say at the health facility level) to another one say at the district level where the data would
- need to be imported. This feature of exporting and importing is thus a crucial function of a
- HMIS. This feature also helps us overcome the dependency on Internet to some degree, as data
- updates can be transferred via USB key where there is no connectivity, or through email where
- there is limited Internet connectivity. DHIS 2 provides robust export-import functionality to
- fulfil these needs. </para>
- <section id="export">
- <title>Exporting data</title>
- <para>DHIS 2 makes it possible to export various types of data in multiple data formats. You can
- export your data, also referred to as measures or facts; and your meta-data, which refers to
- the information describing your data. Data can be exported both in raw, non-aggregated format
- and in aggregated format. It is also possible to export a combination of data and meta-data in
- case you have special requirements. This chapter covers mainly how to export data and
- meta-data through the user interface of the import-export DHIS 2 module. Data can also be
- exported programmatically through the DHIS 2 Web API, and it is useful to be aware of the
- various options available:</para>
- <itemizedlist>
- <listitem>
- <para>Export raw, nonaggregatd data through the user interface: Covered in this
- chapter.</para>
- </listitem>
- <listitem>
- <para>Export aggregated data programmatically through the Web API: Please refer to the Web
- API chapter, section on Analytics.</para>
- </listitem>
- <listitem>
- <para>Export a combination of data and meta-data: Please refer to the SQL view sections in
- the Data administration chapter and Web API chapter.</para>
- </listitem>
- <listitem>
- <para>Export meta-data through the user interface: Covered in this chapter.</para>
- </listitem>
- <listitem>
- <para>Export meta-data programmatically through the Web API: Please refer to the Web API
- chapter, section on meta data.</para>
- </listitem>
- <listitem>
- <para>Export and periodically synchronize systems: Please refer to the Integration engine
- chapter.</para>
- </listitem>
- </itemizedlist>
- <para>Data can be exported on various formats, including DXF 2 (the DHIS 2 meta-data and data
- exchange format based on XML), CSV, PDF, MS Excel and the DHIS 1.4 XML format. </para>
- <para>Another aspect of data export is the type of DHIS 2 deployment. In the case of online
- deployment, all data is saved into a single database only. In an offline deployment, each
- instance will store data in a separate database in their local system. In an offline
- deployment, after the data entry is finished, data will have to be manually sent to the next
- level in the organizational hierarchy. In an on-line application this is not required, as all
- data is captured over an Internet connection and stored in a central location.</para>
- <section>
- <title>Exporting from DHIS 2</title>
- <para>The export option can be made use of by selecting it as follows.
-The import or export is available only when the selected organisation (source/destination) has defined datasets. This is because datasets help to define which data is to be or is being exported. Further, which specific data elements get exported is determined by the composition of the dataset being exported.
-If there are no datasets defined for an organisation unit, it indicates that no data values are registered for this level of organisation or lower.
-To access the main Import-Export module, choose <guimenu>Services->Import-Export</guimenu></para>
- <para>The exported data values are stored in an XML file. The file name is defined by the name
- of the source organisation unit and the period to allow the receiving organisation unit to
- identify the source and the period of the export file.</para>
- </section>
- <section>
- <title>Exporting data to other DHIS 2 systems</title>
- <para>Once the data export screen is displayed, select the Organisation unit, period and dataset for which data export should be selected.Finally click on the export option that will be available on the lower left side of displayed screen.
-If there are no datasets defined for an organisation unit, it indicates that no data values are registered for this level of organisation or lower.
-</para>
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata width="100%" fileref="resources/images/import_export/export_to_dhis2.png" format="PNG"/>
- </imageobject>
- </mediaobject>
- </screenshot>
- <para>A pop-up save option will appear on the displayed screen (see picture below) prompting the saving of the exported data. You may save the export folder on your desktop or any other folder by selecting the ‘Save to Disk’ option from the pop-up prompt.
-</para>
- </section>
- <section>
- <title>Exporting metadata to other DHIS 2 systems</title>
- <section>
- <title>Metadata export</title>
- <para>Metadata is "data about data". In the context of DHIS 2, metadata consists
- of definitions of data elements, indicators, the structure and names contained in the
- organizational hierarchy, and other options. Click on the "Metadata export" link
- from the main "Data export" screen in order to access this. Just select the
- features, format, and the compression that you want and click "Export". This
- metadata file can then be transmitted just like a data file, except it will contain
- information on the definitions of the various features, as opposed to the values of the
- data themselves. </para>
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata width="100%" fileref="resources/images/import_export/metadata_export.png" format="PNG"/>
- </imageobject>
- </mediaobject>
- </screenshot>
- </section>
- </section>
- <section>
- <title>DHIS 1.4 Metadata export</title>
- <para>The DHIS 1.4 Metadata export functionality provides the same functionality as the standard DHIS 2 metadata export, except that the resulting file can be used to transmit metadata information to DHIS 1.4 systems. </para>
- </section>
- <section>
- <title>DHIS 1.4 Detailed Metadata Export</title>
- <para>The DHIS 1.4 Metadata export functionality provides the same functionality as the detailed DHIS 2 metadata export, except that the resulting file can be used to transmit metadata information to DHIS 1.4 systems. Simply select the data elements and indicators that you want and click "Export" to begin the export process.</para>
- </section>
- <section>
- <title>PDF Metadata Export</title>
- <para>The PDF export functionality lets you export the meta-data definitions to the Portable
- Document Format (PDF).</para>
- </section>
- </section>
- <section id="import">
- <title>Importing data</title>
- <para>The import option allows different instance of DHIS 2 to receive standardised set of data in the absence of a networked system. Typically, a data set is exported from one DHIS instance (e.g. a district level system) to another system (e.g. a provincial level system). DHIS 2 is capable of importing data from other systems that either support the DXF of IXF formats. DHIS 2 is capable of importing data directly from a DHIS 1.4 Access database. Each of these options will be discussed in the following sections. </para>
- <section id="import_another_instance">
- <title>Importing data from another DHIS 2 instance</title>
- <para>Data can be imported into different instances of DHIS 2 through the use of the DXF data exchange format. There are two screens that are used to import data, with default and advanced options. </para>
- <para>The default data import menu can be accessed by clicking the <guimenuitem>"Import"</guimenuitem> from the main <guimenuitem>Import-Export</guimenuitem> screen. </para>
- <para>By clicking the <guibutton>"Browse"</guibutton> button, you can select a file from you local file system. This file may have been received by email, copied from another users system, or received on a CD for example. Simply select the file that you wish to import. </para>
- <screenshot>
- <screeninfo>Default import screen</screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata width="100%" fileref="resources/images/import_export/import_default.png" format="PNG"/>
- </imageobject>
- </mediaobject>
- </screenshot>
- <para/>
- <para>There are three separate options for importing data. </para>
- <itemizedlist>
- <listitem>
- <para>Dry run: This is similar to the old preview option, this will do a dry run import,
- and give you information about any errors.</para>
- </listitem>
- <listitem>
- <para>Strategy: There are three options here, "New and Updates", "New only", and "Update
- only". New and updates tells the importer to expect both new metadata, and updates to
- existing ones. New only will only accept fresh metadata, usually you would use this on a
- empty database. Updates only will only allow the metadata to match metadata that is
- already there (same identifiers, new name etc).</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">NOTE: We highly recommend always using the Dry run
- option</emphasis> when importing data to make sure you keep control over any changes
- to your metadata and databases being out of synch on data elements or orgunit
- names.</para>
- </listitem>
- </itemizedlist>
- <section>
- <title>Dry run before importing</title>
- <para>Before doing the import into your database, it is highly recommended that you run the
- import with the dry run option set to true first. This will enabled you to have a look at
- how many new, updates, and ignored metadata there will be. After you have selected your
- file, set dry run to true, you can now click the import button. After doing this, you will
- be greeted by this window.</para>
- <mediaobject>
- <imageobject>
- <imagedata width="100%" fileref="resources/images/import_export/display_import_summary.png"/>
- </imageobject>
- </mediaobject>
- <para>Here you can see a short summary of what was contained in your import file. To see
- further details, please click on the "display import summary" link.</para>
- <mediaobject>
- <imageobject>
- <imagedata width="100%" fileref="resources/images/import_export/import_summary.png"/>
- </imageobject>
- </mediaobject>
- <para>Here you can see that the import dry run was successful and the import contained
- <emphasis role="bold">1</emphasis> new organisation unit, <emphasis role="bold"
- >1332</emphasis> updated, and <emphasis role="bold">4</emphasis> organisation unit
- levels.</para>
- <para>Below you can see another example.</para>
- <mediaobject>
- <imageobject>
- <imagedata width="100%" fileref="resources/images/import_export/import_summary_conflicts.png"/>
- </imageobject>
- </mediaobject>
- <para>Here you can see that the organisation unit Nduvuibu MCHP had a unknown reference to
- an object with UID "aaaU6Kr7Gtpidn", which means that an object with this UID was not
- present in your imported file, and it could not be found in the existing database. Its
- important to note that even if a reference could not be found, the object will still be
- imported, but you might have to fix this directly in DHIS 2 later, if the reference should
- have pointed to something else.</para>
- </section>
- </section>
- <section>
- <title>Matching identifiers in DXF2</title>
- <para>The DXF2 format currently support matching for two identifiers, our own UID, and also a
- possible external identifier called code. When our importer is trying to search for
- references (like the one above), it will first go to the UID field, and then to the code
- field. This allows you to import from legacy systems without having a UID for every metadata
- object. I.e. if you are importing facility data from a legacy system, you can leave out the
- UID field completely (DHIS 2 will fill this in for you) and the put the legacy systems own
- identifiers in the code field, this identifier is required to be unique. This not only works
- for organisation units, but for all kinds of metadata, allowing for easy import from other
- systems.</para>
- </section>
- <section>
- <title>Importing data from DHIS 1.4</title>
- <para>There are two ways to import data from a DHIS 1.4 database; 1) through the 1.4 XML-based export files, or 2) directly from the DHIS 1.4 data file (.mdb). Both are accessible from the DHIS 1.4 Import menu under Import in the Import-Export module.</para>
- <para>It is critical that all data integrity violations which are present in the DHIS 1.4
- database be fully resolved before attempting an import into DHIS 2. You can check the data
- integrity of DHIS 1.4 through the CORE Module->Advanced->Data integrity checks. A
- report will be generated of all data integrity violations which should be resolved prior to
- importing into DHIS 2.</para>
- <section>
- <title>DHIS 1.4 File (database) Import</title>
- <para>This method is recommend when doing large imports from 1.4, and especially when importing into a new DHIS 2 database.</para>
- <para><emphasis role="bold">DHIS 1.4 File Configuration</emphasis> </para>
- <para>Before you can start the 1.4 file import you need to provide a few details about the 1.4 database:</para>
- <para><emphasis role="italic">Datafile(#):</emphasis> Here you put the full path to the DHIS 1.4 data file you want to import from, e.g. C:\DHIS14\DHIS_#LR_LIBERIA.mdb. </para>
- <para><emphasis role="italic">Username:</emphasis> Leave blank (unless you have set up extra security measures on the file)</para>
- <para><emphasis role="italic">Password:</emphasis> Leave blank (unless you have set up extra security measures on the file)</para>
- <para><emphasis role="italic">Levels:</emphasis> Provide the number of levels in the orgunit hierarchy in your 1.4 database, e.g. 5.</para>
- <para>Click "Save" and you will return to the DHIS 1.4 File Import window. </para>
- <para><emphasis role="bold">Import Type:</emphasis></para>
- <para>As with other imports you have the options to Import (directly), Preview, or Analyse the import. We recommend using the Analyse option first to check that the 1.4 database is OK and ready to be imported. </para>
- <para>When importing a large database into a new blank DHIS 2 database we recommend using the Import option to save time. </para>
- <para>For smaller incremental imports the Preview is OK.</para>
- <para><emphasis role="bold">Last Updated:</emphasis> </para>
- <para>If you want the full import, all the data in the 1.4 database you leave this field blank.</para>
- <para>If you only want to do an incremental import into an already existing DHIS 2 database you can use this field to filter which data values to import. Only values added or edited after the date you specify will be imported. This filter makes use of the LastUpdated column in the RoutineData table in the DHIS 1.4 data file.</para>
- <para><emphasis role="bold">Import process:</emphasis></para>
- <para>When you are done selecting Method, and LastUpdated you can begin the import by
- clicking on the Import button. This process might take a long time, depending on how many
- data values you are importing. On a reasonable spec. computer the import takes about 2
- million records per 30 minutes.</para>
- </section>
- <section>
- <title>DHIS 1.4 XML Import</title>
- <para>Import though XML data from DHIS 1.4 is also possible using the standard DHIS 1.4
- export format. Just be sure that the DHIS 1.4 export format has been set to "DHIS
- 2.0" as illustrated in the screen shot below. After the data has been exported by
- DHIS 1.4, you can import the data by choosing "Services->Import-Export->DHIS
- 1.4 Import->DHIS 1.4 XML Import" and proceeding via the procedure outline in the
- <link linkend="import_another_instance">previous section</link>. </para>
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata width="40%" align="center" fileref="resources/images/import_export/dhis14_export.png"/>
- </imageobject>
- </mediaobject>
- </screenshot>
- </section>
- <section>
- <title>Limitations to DHIS 1.4 imports</title>
- <para>Although it is possible to import and export data between instances of DHIS 1.4 and
- DHIS 2, there are significant limitations. Currently, the import of some metadata is not
- supported from DHIS 1.4 to DHIS 2. This includes:</para>
- <itemizedlist>
- <listitem>
- <para>Validation rules</para>
- </listitem>
- <listitem>
- <para>Organisational unit alternate names</para>
- </listitem>
- <listitem>
- <para>Compulsory data element pairings</para>
- </listitem>
- <listitem>
- <para>Custom data entry forms</para>
- </listitem>
- <listitem>
- <para>Dataset data entry levels</para>
- </listitem>
- </itemizedlist>
- <para>It is also important that the aggregation operator defined in DHIS 1.4 be set to the correct value. Some data, such as population, should have their aggregation operator set to "Average" in DHIS 2, as this controls how the aggregation of data is handled over time (but not within the organisational unit hierarchy). </para>
- </section>
- </section>
- </section>
- <section>
- <title>Importing CSV data</title>
- <para>DHIS 2 supports import of data in the CSV format. This can be used to import exchange file produced by DHIS 2 itself. It also comes in handy when you want to import data from a third-party system as CSV is widely supported in applications and is easy to produce manually.</para>
- <para>To import a CSV data exchange file navigate to the <emphasis role="italic">CSV Data Import </emphasis>item in the left-side menu. Upload the exchange file and click <emphasis role="italic">Import</emphasis>.</para>
- <para>The following section describes the CSV format used in DHIS 2. The first row is assumed to be a header row and will be ignored during import.</para>
- <para><table>
- <title>CSV format of DHIS 2</title>
- <tgroup cols="3">
- <tbody>
- <row>
- <entry>Column</entry>
- <entry>Required</entry>
- <entry>Notes</entry>
- </row>
- <row>
- <entry>Data element</entry>
- <entry>Yes</entry>
- <entry>Refers to uid by default, can also be name and code based on selected id scheme</entry>
- </row>
- <row>
- <entry>Period</entry>
- <entry>Yes</entry>
- <entry>In ISO format</entry>
- </row>
- <row>
- <entry>Org unit</entry>
- <entry>Yes</entry>
- <entry>Refers to uid by default, can also be name and code based on selected id scheme</entry>
- </row>
- <row>
- <entry>Category option combo</entry>
- <entry>No</entry>
- <entry>Refers to uid</entry>
- </row>
- <row>
- <entry>Value</entry>
- <entry>No</entry>
- <entry>Data value</entry>
- </row>
- <row>
- <entry>Stored by</entry>
- <entry>No</entry>
- <entry>Refers to username of user who entered the value</entry>
- </row>
- <row>
- <entry>Timestamp</entry>
- <entry>No</entry>
- <entry>Date in ISO format</entry>
- </row>
- <row>
- <entry>Comment</entry>
- <entry>No</entry>
- <entry>Free text comment</entry>
- </row>
- <row>
- <entry>Follow up</entry>
- <entry>No</entry>
- <entry>true or false</entry>
- </row>
- </tbody>
- </tgroup>
- </table></para>
- <para>The following is an example CSV file which can be imported into DHIS 2. It can be imported both as plain text file or as compressed ZIP file archive.</para>
- <screen>"dataelelement","period","orgunit","categoryoptioncombo","value","storedby","timestamp","comment","followup"
-"DUSpd8Jq3M7","201202","gP6hn503KUX","Prlt0C1RF0s","7","bombali","2010-04-17",,"false"
-"DUSpd8Jq3M7","201202","gP6hn503KUX","V6L425pT3A0","10","bombali","2010-04-17",,"false"
-"DUSpd8Jq3M7","201202","OjTS752GbZE","V6L425pT3A0","9","bombali","2010-04-06",,"false"</screen>
- </section>
- <section>
- <title>Importing XML data</title>
- <para>DHIS 2 supports import of data in XML format. The format is called DXF (DHIS Exchange
- Format). To import an XML file navigate to the XML Data Import item in the left side menu.
- Upload the exchange file and click <emphasis role="italic">Import</emphasis>. After the import
- process is finished you can follow the link to the import summary, which will inform you about
- the outcome of the import process in terms of number of records imported, updated and ignored
- and potential conflicts.</para>
- <para>If you need to manually produce such XML files please refer to the Web API chapter where you can find detailed documentation of the DXF format.</para>
- </section>
-</chapter>
+<?xml version='1.0' encoding='UTF-8'?>
+<!-- This document was created with Syntext Serna Free. --><!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; []>
+<chapter>
+ <title>Import and export</title>
+ <para>In a primary health system, the HMIS typically involves a distributed application, where the
+ same application is running in different geographical locations (PHCs,CHCs, hospitals,
+ districts, and state). Most of these physical locations do not have Internet connectivity, and
+ hence they work offline. At some point (normally at the district level), the data needs to be
+ synchronised in order to have a consolidated database for the a particular geographical region.
+ For this, it is important to be able to export data from one location (which is working offline,
+ say at the health facility level) to another one say at the district level where the data would
+ need to be imported. This feature of exporting and importing is thus a crucial function of a
+ HMIS. This feature also helps us overcome the dependency on Internet to some degree, as data
+ updates can be transferred via USB key where there is no connectivity, or through email where
+ there is limited Internet connectivity. DHIS 2 provides robust export-import functionality to
+ fulfil these needs. </para>
+ <section id="export">
+ <title>Exporting data</title>
+ <para>DHIS 2 makes it possible to export various types of data in multiple data formats. You can
+ export your data, also referred to as measures or facts; and your meta-data, which refers to
+ the information describing your data. Data can be exported both in raw, non-aggregated format
+ and in aggregated format. It is also possible to export a combination of data and meta-data in
+ case you have special requirements. This chapter covers mainly how to export data and
+ meta-data through the user interface of the import-export DHIS 2 module. Data can also be
+ exported programmatically through the DHIS 2 Web API, and it is useful to be aware of the
+ various options available:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Export raw, nonaggregatd data through the user interface: Covered in this
+ chapter.</para>
+ </listitem>
+ <listitem>
+ <para>Export aggregated data programmatically through the Web API: Please refer to the Web
+ API chapter, section on Analytics.</para>
+ </listitem>
+ <listitem>
+ <para>Export a combination of data and meta-data: Please refer to the SQL view sections in
+ the Data administration chapter and Web API chapter.</para>
+ </listitem>
+ <listitem>
+ <para>Export meta-data through the user interface: Covered in this chapter.</para>
+ </listitem>
+ <listitem>
+ <para>Export meta-data programmatically through the Web API: Please refer to the Web API
+ chapter, section on meta data.</para>
+ </listitem>
+ <listitem>
+ <para>Export and periodically synchronize systems: Please refer to the Integration engine
+ chapter.</para>
+ </listitem>
+ </itemizedlist>
+ <para>Data can be exported on various formats, including DXF 2 (the DHIS 2 meta-data and data
+ exchange format based on XML), CSV, PDF, MS Excel and the DHIS 1.4 XML format. </para>
+ <para>Another aspect of data export is the type of DHIS 2 deployment. In the case of online
+ deployment, all data is saved into a single database only. In an offline deployment, each
+ instance will store data in a separate database in their local system. In an offline
+ deployment, after the data entry is finished, data will have to be manually sent to the next
+ level in the organizational hierarchy. In an on-line application this is not required, as all
+ data is captured over an Internet connection and stored in a central location.</para>
+ <section>
+ <title>Exporting from DHIS 2</title>
+ <para>The export option can be made use of by selecting it as follows.
+The import or export is available only when the selected organisation (source/destination) has defined datasets. This is because datasets help to define which data is to be or is being exported. Further, which specific data elements get exported is determined by the composition of the dataset being exported.
+If there are no datasets defined for an organisation unit, it indicates that no data values are registered for this level of organisation or lower.
+To access the main Import-Export module, choose <guimenu>Services->Import-Export</guimenu></para>
+ <para>The exported data values are stored in an XML file. The file name is defined by the name
+ of the source organisation unit and the period to allow the receiving organisation unit to
+ identify the source and the period of the export file.</para>
+ </section>
+ <section>
+ <title>Exporting data to other DHIS 2 systems</title>
+ <para>Once the data export screen is displayed, select the Organisation unit, period and dataset for which data export should be selected.Finally click on the export option that will be available on the lower left side of displayed screen.
+If there are no datasets defined for an organisation unit, it indicates that no data values are registered for this level of organisation or lower.
+</para>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="100%" fileref="resources/images/import_export/export_to_dhis2.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ <para>A pop-up save option will appear on the displayed screen (see picture below) prompting the saving of the exported data. You may save the export folder on your desktop or any other folder by selecting the ‘Save to Disk’ option from the pop-up prompt.
+</para>
+ </section>
+ <section>
+ <title>Exporting metadata to other DHIS 2 systems</title>
+ <section>
+ <title>Metadata export</title>
+ <para>Metadata is "data about data". In the context of DHIS 2, metadata consists
+ of definitions of data elements, indicators, the structure and names contained in the
+ organizational hierarchy, and other options. Click on the "Metadata export" link
+ from the main "Data export" screen in order to access this. Just select the
+ features, format, and the compression that you want and click "Export". This
+ metadata file can then be transmitted just like a data file, except it will contain
+ information on the definitions of the various features, as opposed to the values of the
+ data themselves. </para>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="100%" fileref="resources/images/import_export/metadata_export.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ </section>
+ </section>
+ <section>
+ <title>DHIS 1.4 Metadata export</title>
+ <para>The DHIS 1.4 Metadata export functionality provides the same functionality as the standard DHIS 2 metadata export, except that the resulting file can be used to transmit metadata information to DHIS 1.4 systems. </para>
+ </section>
+ <section>
+ <title>DHIS 1.4 Detailed Metadata Export</title>
+ <para>The DHIS 1.4 Metadata export functionality provides the same functionality as the detailed DHIS 2 metadata export, except that the resulting file can be used to transmit metadata information to DHIS 1.4 systems. Simply select the data elements and indicators that you want and click "Export" to begin the export process.</para>
+ </section>
+ <section>
+ <title>PDF Metadata Export</title>
+ <para>The PDF export functionality lets you export the meta-data definitions to the Portable
+ Document Format (PDF).</para>
+ </section>
+ </section>
+ <section id="import">
+ <title>Importing data</title>
+ <para>The import option allows different instance of DHIS 2 to receive standardised set of data in the absence of a networked system. Typically, a data set is exported from one DHIS instance (e.g. a district level system) to another system (e.g. a provincial level system). DHIS 2 is capable of importing data from other systems that either support the DXF of IXF formats. DHIS 2 is capable of importing data directly from a DHIS 1.4 Access database. Each of these options will be discussed in the following sections. </para>
+ <section id="import_another_instance">
+ <title>Importing data from another DHIS 2 instance</title>
+ <para>Data can be imported into different instances of DHIS 2 through the use of the DXF data exchange format. There are two screens that are used to import data, with default and advanced options. </para>
+ <para>The default data import menu can be accessed by clicking the <guimenuitem>"Import"</guimenuitem> from the main <guimenuitem>Import-Export</guimenuitem> screen. </para>
+ <para>By clicking the <guibutton>"Browse"</guibutton> button, you can select a file from you local file system. This file may have been received by email, copied from another users system, or received on a CD for example. Simply select the file that you wish to import. </para>
+ <screenshot>
+ <screeninfo>Default import screen</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="100%" fileref="resources/images/import_export/import_default.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ <para/>
+ <para>There are three separate options for importing data. </para>
+ <itemizedlist>
+ <listitem>
+ <para>Dry run: This is similar to the old preview option, this will do a dry run import,
+ and give you information about any errors.</para>
+ </listitem>
+ <listitem>
+ <para>Strategy: There are three options here, "New and Updates", "New only", and "Update
+ only". New and updates tells the importer to expect both new metadata, and updates to
+ existing ones. New only will only accept fresh metadata, usually you would use this on a
+ empty database. Updates only will only allow the metadata to match metadata that is
+ already there (same identifiers, new name etc).</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">NOTE: We highly recommend always using the Dry run
+ option</emphasis> when importing data to make sure you keep control over any changes
+ to your metadata and databases being out of synch on data elements or orgunit
+ names.</para>
+ </listitem>
+ </itemizedlist>
+ <section>
+ <title>Dry run before importing</title>
+ <para>Before doing the import into your database, it is highly recommended that you run the
+ import with the dry run option set to true first. This will enabled you to have a look at
+ how many new, updates, and ignored metadata there will be. After you have selected your
+ file, set dry run to true, you can now click the import button. After doing this, you will
+ be greeted by this window.</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="100%" fileref="resources/images/import_export/display_import_summary.png"/>
+ </imageobject>
+ </mediaobject>
+ <para>Here you can see a short summary of what was contained in your import file. To see
+ further details, please click on the "display import summary" link.</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="100%" fileref="resources/images/import_export/import_summary.png"/>
+ </imageobject>
+ </mediaobject>
+ <para>Here you can see that the import dry run was successful and the import contained
+ <emphasis role="bold">1</emphasis> new organisation unit, <emphasis role="bold"
+ >1332</emphasis> updated, and <emphasis role="bold">4</emphasis> organisation unit
+ levels.</para>
+ <para>Below you can see another example.</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="100%" fileref="resources/images/import_export/import_summary_conflicts.png"/>
+ </imageobject>
+ </mediaobject>
+ <para>Here you can see that the organisation unit Nduvuibu MCHP had a unknown reference to
+ an object with UID "aaaU6Kr7Gtpidn", which means that an object with this UID was not
+ present in your imported file, and it could not be found in the existing database. Its
+ important to note that even if a reference could not be found, the object will still be
+ imported, but you might have to fix this directly in DHIS 2 later, if the reference should
+ have pointed to something else.</para>
+ </section>
+ </section>
+ <section>
+ <title>Matching identifiers in DXF2</title>
+ <para>The DXF2 format currently support matching for two identifiers, our own UID, and also a
+ possible external identifier called code. When our importer is trying to search for
+ references (like the one above), it will first go to the UID field, and then to the code
+ field. This allows you to import from legacy systems without having a UID for every metadata
+ object. I.e. if you are importing facility data from a legacy system, you can leave out the
+ UID field completely (DHIS 2 will fill this in for you) and the put the legacy systems own
+ identifiers in the code field, this identifier is required to be unique. This not only works
+ for organisation units, but for all kinds of metadata, allowing for easy import from other
+ systems.</para>
+ </section>
+ <section id="dhis14import">
+ <title>Importing data from DHIS 1.4</title>
+ <para>There are two ways to import data from a DHIS 1.4 database; 1) through the 1.4 XML-based export files, or 2) directly from the DHIS 1.4 data file (.mdb). Both are accessible from the DHIS 1.4 Import menu under Import in the Import-Export module.</para>
+ <para>It is critical that all data integrity violations which are present in the DHIS 1.4
+ database be fully resolved before attempting an import into DHIS 2. You can check the data
+ integrity of DHIS 1.4 through the CORE Module->Advanced->Data integrity checks. A
+ report will be generated of all data integrity violations which should be resolved prior to
+ importing into DHIS 2.</para>
+ <section>
+ <title>DHIS 1.4 File (database) Import</title>
+ <para>This method is recommend when doing large imports from 1.4, and especially when importing into a new DHIS 2 database.</para>
+ <para><emphasis role="bold">DHIS 1.4 File Configuration</emphasis> </para>
+ <para>Before you can start the 1.4 file import you need to provide a few details about the 1.4 database:</para>
+ <para><emphasis role="italic">Datafile(#):</emphasis> Here you put the full path to the DHIS 1.4 data file you want to import from, e.g. C:\DHIS14\DHIS_#LR_LIBERIA.mdb. </para>
+ <para><emphasis role="italic">Username:</emphasis> Leave blank (unless you have set up extra security measures on the file)</para>
+ <para><emphasis role="italic">Password:</emphasis> Leave blank (unless you have set up extra security measures on the file)</para>
+ <para><emphasis role="italic">Levels:</emphasis> Provide the number of levels in the orgunit hierarchy in your 1.4 database, e.g. 5.</para>
+ <para>Click "Save" and you will return to the DHIS 1.4 File Import window. </para>
+ <para><emphasis role="bold">Import Type:</emphasis></para>
+ <para>As with other imports you have the options to Import (directly), Preview, or Analyse the import. We recommend using the Analyse option first to check that the 1.4 database is OK and ready to be imported. </para>
+ <para>When importing a large database into a new blank DHIS 2 database we recommend using the Import option to save time. </para>
+ <para>For smaller incremental imports the Preview is OK.</para>
+ <para><emphasis role="bold">Last Updated:</emphasis> </para>
+ <para>If you want the full import, all the data in the 1.4 database you leave this field blank.</para>
+ <para>If you only want to do an incremental import into an already existing DHIS 2 database you can use this field to filter which data values to import. Only values added or edited after the date you specify will be imported. This filter makes use of the LastUpdated column in the RoutineData table in the DHIS 1.4 data file.</para>
+ <para><emphasis role="bold">Import process:</emphasis></para>
+ <para>When you are done selecting Method, and LastUpdated you can begin the import by
+ clicking on the Import button. This process might take a long time, depending on how many
+ data values you are importing. On a reasonable spec. computer the import takes about 2
+ million records per 30 minutes.</para>
+ </section>
+ <section>
+ <title>DHIS 1.4 XML Import</title>
+ <para>Import though XML data from DHIS 1.4 is also possible using the standard DHIS 1.4
+ export format. Just be sure that the DHIS 1.4 export format has been set to "DHIS
+ 2.0" as illustrated in the screen shot below. After the data has been exported by
+ DHIS 1.4, you can import the data by choosing "Services->Import-Export->DHIS
+ 1.4 Import->DHIS 1.4 XML Import" and proceeding via the procedure outline in the
+ <link linkend="import_another_instance">previous section</link>. </para>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="40%" align="center" fileref="resources/images/import_export/dhis14_export.png"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ </section>
+ <section>
+ <title>Limitations to DHIS 1.4 imports</title>
+ <para>Although it is possible to import and export data between instances of DHIS 1.4 and
+ DHIS 2, there are significant limitations. Currently, the import of some metadata is not
+ supported from DHIS 1.4 to DHIS 2. This includes:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Validation rules</para>
+ </listitem>
+ <listitem>
+ <para>Organisational unit alternate names</para>
+ </listitem>
+ <listitem>
+ <para>Compulsory data element pairings</para>
+ </listitem>
+ <listitem>
+ <para>Custom data entry forms</para>
+ </listitem>
+ <listitem>
+ <para>Dataset data entry levels</para>
+ </listitem>
+ </itemizedlist>
+ <para>It is also important that the aggregation operator defined in DHIS 1.4 be set to the correct value. Some data, such as population, should have their aggregation operator set to "Average" in DHIS 2, as this controls how the aggregation of data is handled over time (but not within the organisational unit hierarchy). </para>
+ </section>
+ </section>
+ </section>
+ <section id="importCSVdata">
+ <title>Importing CSV data</title>
+ <para>DHIS 2 supports import of data in the CSV format. This can be used to import exchange file produced by DHIS 2 itself. It also comes in handy when you want to import data from a third-party system as CSV is widely supported in applications and is easy to produce manually.</para>
+ <para>To import a CSV data exchange file navigate to the <emphasis role="italic">CSV Data Import </emphasis>item in the left-side menu. Upload the exchange file and click <emphasis role="italic">Import</emphasis>.</para>
+ <para>The following section describes the CSV format used in DHIS 2. The first row is assumed to be a header row and will be ignored during import.</para>
+ <para><table>
+ <title>CSV format of DHIS 2</title>
+ <tgroup cols="3">
+ <tbody>
+ <row>
+ <entry>Column</entry>
+ <entry>Required</entry>
+ <entry>Notes</entry>
+ </row>
+ <row>
+ <entry>Data element</entry>
+ <entry>Yes</entry>
+ <entry>Refers to uid by default, can also be name and code based on selected id scheme</entry>
+ </row>
+ <row>
+ <entry>Period</entry>
+ <entry>Yes</entry>
+ <entry>In ISO format</entry>
+ </row>
+ <row>
+ <entry>Org unit</entry>
+ <entry>Yes</entry>
+ <entry>Refers to uid by default, can also be name and code based on selected id scheme</entry>
+ </row>
+ <row>
+ <entry>Category option combo</entry>
+ <entry>No</entry>
+ <entry>Refers to uid</entry>
+ </row>
+ <row>
+ <entry>Value</entry>
+ <entry>No</entry>
+ <entry>Data value</entry>
+ </row>
+ <row>
+ <entry>Stored by</entry>
+ <entry>No</entry>
+ <entry>Refers to username of user who entered the value</entry>
+ </row>
+ <row>
+ <entry>Timestamp</entry>
+ <entry>No</entry>
+ <entry>Date in ISO format</entry>
+ </row>
+ <row>
+ <entry>Comment</entry>
+ <entry>No</entry>
+ <entry>Free text comment</entry>
+ </row>
+ <row>
+ <entry>Follow up</entry>
+ <entry>No</entry>
+ <entry>true or false</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></para>
+ <para>The following is an example CSV file which can be imported into DHIS 2. It can be imported both as plain text file or as compressed ZIP file archive.</para>
+ <screen>"dataelelement","period","orgunit","categoryoptioncombo","value","storedby","timestamp","comment","followup"
+"DUSpd8Jq3M7","201202","gP6hn503KUX","Prlt0C1RF0s","7","bombali","2010-04-17",,"false"
+"DUSpd8Jq3M7","201202","gP6hn503KUX","V6L425pT3A0","10","bombali","2010-04-17",,"false"
+"DUSpd8Jq3M7","201202","OjTS752GbZE","V6L425pT3A0","9","bombali","2010-04-06",,"false"</screen>
+ </section>
+ <section id="importXMLdata">
+ <title>Importing XML data</title>
+ <para>DHIS 2 supports import of data in XML format. The format is called DXF (DHIS Exchange
+ Format). To import an XML file navigate to the XML Data Import item in the left side menu.
+ Upload the exchange file and click <emphasis role="italic">Import</emphasis>. After the import
+ process is finished you can follow the link to the import summary, which will inform you about
+ the outcome of the import process in terms of number of records imported, updated and ignored
+ and potential conflicts.</para>
+ <para>If you need to manually produce such XML files please refer to the Web API chapter where you can find detailed documentation of the DXF format.</para>
+ </section>
+ <section id="importPDFdata">
+ <title>Importing PDF data</title>
+ <para>DHIS 2 supports import of data in the PDF format. This can be used to import data produced by offline PDF data entry forms. Please refer to the section "Data set management" for details on how to produce a PDF form which can be used for offline data entry. </para>
+ <para>To import a PDF data file, navigate to the <emphasis role="italic">PDF Data Import </emphasis>item in the left-side menu. Upload the completed PDF file and click <emphasis role="italic">Import</emphasis>.</para>
+ <para>After the import process is finished, you can follow the link to the import summary, which will inform you about the outcome of the import process in terms of number of records imported, updated and ignored and potential conflicts.</para>
+ </section>
+</chapter>
+
=== modified file 'src/docbkx/en/dhis2_user_manual_en.xml'
--- src/docbkx/en/dhis2_user_manual_en.xml 2013-06-25 11:22:09 +0000
+++ src/docbkx/en/dhis2_user_manual_en.xml 2013-08-22 14:52:01 +0000
@@ -1,6 +1,5 @@
<?xml version='1.0' encoding='UTF-8'?>
-<!-- This document was created with Syntext Serna Free. -->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; [
+<!-- This document was created with Syntext Serna Free. --><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; [
<!ENTITY version '2.X'>
<!ENTITY title 'DHIS2 User Manual'>
]>
@@ -35,10 +34,9 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_user_man_web_api.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_user_man_integration.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_user_man_apps.xml"/>
- <!--
+<!--
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_user_man_excel_reports.xml" encoding="UTF-8"/>
- -->
- <appendix>
+ --> <appendix>
<title> DHIS 2 Documentation Guide</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_documentation_guide.xml" encoding="UTF-8" xpointer="docs_1"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_documentation_guide.xml" encoding="UTF-8" xpointer="docs_2"/>
@@ -60,12 +58,12 @@
<appendix>
<title>R and DHIS 2 Integration</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_r.xml" encoding="UTF-8" xpointer="dhis2_r_intro"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_r.xml" encoding="UTF-8" xpointer="dhis2_r_odbc"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_r.xml" encoding="UTF-8" xpointer="dhis2_r_mydatamart"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_r.xml" encoding="UTF-8" xpointer="dhis2_r_maps"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_r.xml" encoding="UTF-8" xpointer="dhis2_r_google_vis"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_r.xml" encoding="UTF-8" xpointer="dhis2_r_plr"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_r.xml" encoding="UTF-8" xpointer="dhis2_r_web_api"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_r.xml" encoding="UTF-8" xpointer="dhis2_r_odbc"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_r.xml" encoding="UTF-8" xpointer="dhis2_r_mydatamart"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_r.xml" encoding="UTF-8" xpointer="dhis2_r_maps"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_r.xml" encoding="UTF-8" xpointer="dhis2_r_google_vis"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_r.xml" encoding="UTF-8" xpointer="dhis2_r_plr"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_r.xml" encoding="UTF-8" xpointer="dhis2_r_web_api"/>
</appendix>
<appendix>
<title> DHIS Technical Architecture Guide</title>
