------------------------------------------------------------ revno: 566 committer: Bob Jolliffe <[email protected]> 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&organisationUnits=true&organisationUnitGroups=true&organisationUnitGroupSets=true&organisationUnitLevels=true&attributeTypes=true</constant> + </setHeader> + <!-- send http request --> + <to + uri="http://apps.dhis2.org/demo/api/metaData.xml?httpClient.authenticationPreemptive=true&authMethod=Basic&authUsername=system&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 "&" is replaced in the query string with "&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"/> -->
_______________________________________________ Mailing list: https://launchpad.net/~dhis2-devs Post to : [email protected] Unsubscribe : https://launchpad.net/~dhis2-devs More help : https://help.launchpad.net/ListHelp
