dhis2-devs team mailing list archive

[noreply@xxxxxxxxxxxxx]

------------------------------------------------------------
revno: 566
committer: Bob Jolliffe <bobjolliffe@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Sun 2012-08-05 18:59:52 +0100
message:
  WIP - Integration chapter
added:
  src/docbkx/en/dhis2_user_man_integration.xml
modified:
  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

=== added file 'src/docbkx/en/dhis2_user_man_integration.xml'
--- src/docbkx/en/dhis2_user_man_integration.xml	1970-01-01 00:00:00 +0000
+++ src/docbkx/en/dhis2_user_man_integration.xml	2012-08-05 17:59:52 +0000
@@ -0,0 +1,89 @@
+<?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>Integration Engine</title>
+  <para>DHIS2 has a built in component for managing integration scenarios. The functionality is
+    provided by <ulink url="http://camel.apacher.org";>Apache Camel</ulink> which is itself an
+    implementation of the Enterprize Integration Patterns (EIP) described in the book <ulink
+      url="http://www.eaipatterns.com"/> by Gregor Hohpe and Bobby Woolf. It complements the web-api
+    by providing the means to consume services from other applications and perform transformations
+    on data. Because integration requirements are always dependent on particular contexts, the
+    integration engine is designed to be configurable on site.</para>
+  <section>
+    <title>Introduction</title>
+    <para>The integration engine is configured by defining <emphasis>routes</emphasis>. A route
+      defines a particular message flow from an external system into DHIS2. Routes may consist of
+      timers, http client requests, transformations, message processors, loggers etc. Routes can be
+      defined in XML or in Java. XML routes have the advantage that they can be easily configured
+      and loaded into a running DHIS2 instance. More complex routes might require the greater
+      expressiveness of the Java language. Routes written in Java need to be made available on the
+      classpath of the web application on application startup.</para>
+    <para/>
+    <para>Some sample routes are shown in the sections following. <emphasis>Disclaimer</emphasis>:
+      please do not experiment with these routes on a production server. Be sure to test routes
+      thoroughly on a test instance before deploying to production. These routes update metadata and
+      data automatically.</para>
+  </section>
+  <section>
+    <title>Synchronising orgunits - an XML route</title>
+    <para>One use case which motivated the inclusion of the integration engine into DHIS2 is the
+      need to synchronise orgunits. In this example we present a simple XML route which allows one
+      DHIS2 instance to update it's orgunits from another DHIS2 instance.</para>
+    <para>The unavoidable long lines in the route listing may not render well in the DHIS2 user manual.  This and other
+    sample routes can be found in the resources section of the DHIS2 source code.</para>
+    <para>
+      <programlisting><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<route xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+  xsi:schemaLocation="http://camel.apache.org/schema/spring camel-spring-2.9.1.xsd"
+  xmlns="http://camel.apache.org/schema/spring"; id="dataUpdater">
+
+  <description>Synch orgunits every 5 minutes</description>
+  <!-- trigger every 5 minutes ... -->
+  <from uri="quartz://everyHour?cron=0+0/5+*+*+*+%3F"/>
+  <!-- filter required elements from metadata export -->
+  <setHeader headerName="CamelHttpQuery">
+    <constant>assumeTrue=false&amp;organisationUnits=true&amp;organisationUnitGroups=true&amp;organisationUnitGroupSets=true&amp;organisationUnitLevels=true&amp;attributeTypes=true</constant>
+  </setHeader>
+  <!-- send http request -->
+  <to
+    uri="http://apps.dhis2.org/demo/api/metaData.xml?httpClient.authenticationPreemptive=true&amp;authMethod=Basic&amp;authUsername=system&amp;authPassword=System123"/>
+  <log logName="org.hisp.dhis.camel" loggingLevel="INFO" message="Importing orgunits"/>
+  <!-- import to dhis2 component -->
+  <inOut uri="dhis2:metadata"/>
+  <!-- log the import summary -->
+  <log logName="org.hisp.dhis.camel" loggingLevel="INFO" message="${body}"/>
+</route>
+]]></programlisting>
+    </para>
+    <para>Some notes on the above:
+    <itemizedlist>
+      <listitem><para>Note that the route has an id and a description.  These are important if you want the route to show up in the Import-Export module.</para></listitem>
+      <listitem>
+          <para>Camel components are configured using urls. The trigger expression for the quartz
+            URL should be cron=0+0+*+*+*+?" but the "?" character cannot appear unencoded in the XML route,
+            hence the escaped "%3F".  Similarly, the "&amp;" is replaced in the query string with "&amp;mp;"/</para></listitem>
+      <listitem>
+          <para>Additional parameters to the URL such as "authenticationPreemptive" etc are
+            documented for the Camel http component <ulink url="http://camel.apache.org/http.html";
+            />. These are consumed by the camel processor and not sent to the server as part oif the
+            request.</para></listitem>
+      <listitem>
+          <para>The dhis2:metadata endpoint is not part of the camel core. It is a DHIS2 specific
+            component which is available to the author of DHIS2 routes as a destination for
+            importing DXF2 metadata.</para></listitem>
+    </itemizedlist>
+    </para>
+  </section>
+  <section>
+    <title>Loading an XML route</title>
+    <para>Routes like the one in the previous section can be loaded into a running DHIS2 instance through the integration configuration screen found under the Import/Export module.
+    From here routes can be enabled and disabled.  The route definition can be updated by adding a new route with the same route id.</para>
+    <para>DHIS2 also provides a means to automatically load a set of XML routes on application startup.  When the application starts it will look for a directory called "routes" under the
+    DHIS2_HOME directory.  Any XML routes found in that directory will be loaded into the running application.</para>
+  </section>
+  <section>
+    <title>A Java route</title>
+    <para></para>
+  </section>
+</chapter>

=== modified file 'src/docbkx/en/dhis2_user_manual_en.xml'
--- src/docbkx/en/dhis2_user_manual_en.xml	2012-08-02 17:36:34 +0000
+++ src/docbkx/en/dhis2_user_manual_en.xml	2012-08-05 17:59:52 +0000
@@ -31,6 +31,7 @@
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_user_man_data_dimensions.xml"/>
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_user_man_persons_and_programs.xml" encoding="UTF-8"/>
   <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_excel_reports.xml" encoding="UTF-8"/>
   -->