dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #25148
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 821: Removing deprecated section on integration.
------------------------------------------------------------
revno: 821
committer: Jason P. Pickering <jason.p.pickering@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Wed 2013-10-02 16:52:27 +0200
message:
Removing deprecated section on integration.
removed:
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
=== removed file 'src/docbkx/en/dhis2_user_man_integration.xml'
--- src/docbkx/en/dhis2_user_man_integration.xml 2013-06-01 12:33:28 +0000
+++ src/docbkx/en/dhis2_user_man_integration.xml 1970-01-01 00:00:00 +0000
@@ -1,126 +0,0 @@
-<?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 Enterprise 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 of 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>Transforming data - a Java route</title>
- <para>This route is used internally in the DHIS2 integration module to perform the
- transformation from SDMX input data to the DHIS2 DXF2 data format. The listing below is a
- slightly simplified illustration.</para>
- <programlisting><![CDATA[
-package org.hisp.dhis.integration.routes;
-
-// imports not shown ....
-
-public class SDMXDataIn
- extends RouteBuilder
-{
- @Override
- public void configure() throws Exception
- {
- DescriptionDefinition desc = new DescriptionDefinition();
- desc.setText("Sdmx data input");
-
- RouteDefinition sdmxDataIn = from("direct:sdmxDataIn).
- convertBodyTo( java.lang.String.class, "UTF-8" ).
- to("xslt:transform/cross2dxf2.xsl").
- convertBodyTo( java.io.InputStream.class).
- inOut("dhis2:data?orgUnitIdScheme=CODE&dataElementIdScheme=CODE&importStrategy=NEW_AND_UPDATES");
-
- sdmxDataIn.setDescription( desc );
- sdmxDataIn.setId( "internal-sdmx-input" );
- }
- }]]></programlisting>
- <para>Some notes on the above:
- <itemizedlist>
- <listitem><para>The DHIS2 integration is configured to automatically scan and load java routes which are in the package <emphasis>org.hisp.dhis.integration.routes</emphasis>. So any
- <emphasis>RouteBuilder</emphasis> classes like this, found in the classpath will be automatically loaded.</para></listitem>
- <listitem><para>This example shows the use of an xslt transform. The url <emphasis>"xslt:transform/cross2dxf2.xsl"</emphasis> will search for the xsl file amongst the classpath resources.
- It is also possible to use an absolute file reference.</para></listitem>
- <listitem><para>The dhis2:data endpoint is a DHIS2 specific
- component which is available to the author of DHIS2 routes as a destination for
- importing DXF2 data.</para></listitem>
- </itemizedlist>
- </para>
- </section>
-</chapter>
=== modified file 'src/docbkx/en/dhis2_user_manual_en.xml'
--- src/docbkx/en/dhis2_user_manual_en.xml 2013-08-22 14:52:01 +0000
+++ src/docbkx/en/dhis2_user_manual_en.xml 2013-10-02 14:52:27 +0000
@@ -32,7 +32,6 @@
<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_apps.xml"/>
<!--
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhis2_user_man_excel_reports.xml" encoding="UTF-8"/>