Introduction

Getting started

Prerequisites

The Open eHealth Integration Platform (IPF) is based on Apache Camel. It is therefore important that you have a good understanding how Camel works before continuing with the IPF documentation. For a general Camel overview go the project's main page. Camel tutorials can be found on a separate tutorials page. A recommended starting point is the tutorial introducing Camel steadily in a real life integration.

Application development on the Open eHealth Integration Platform (IPF) follows Enterprise Integration Patterns. Integration platforms or service buses won't help you unless you have a good understanding of the principles and concepts of messaging solutions. This book gives you excellent hints how to design messaging-based integration solutions.

Initial reading

After you've learned some basics about Apache Camel the best way to start with IPF is to read through the IPF overview section. It will give you a high-level view of the features provided by IPF including some links to more detailed documentation. The IPF architecture section starts with diagrams of the physical components that make up IPF. A short description of the component namspaces and the individual components is given as well.

Infrastructure setup

Before you start working with IPF make sure that you've read the IPF development pages. These will explain how to

Setup the development environment.
Checkout and compile the sources (optional).
Import the IPF sources into Eclipse (optional).
Create new projects using archetypes (see also IPF Tutorials).

First project

The first steps tutorial is a good starting point for creating your first IPF project. It demonstrates how to use IPF project archetypes for creating a project and walks through the key project artifacts. A simple message processing example will introduce some core features of IPF. You can find further tutorials on the IPF tutorials page.

IPF overview

The Open eHealth Integration Platform (IPF) is an extension of the Apache Camel routing and mediation engine. It has an application programming layer based on the Groovy programming language and comes with comprehensive support for message processing and connecting systems in the eHealth domain. IPF provides domain-specific languages (DSLs) for implementing Enterprise Integration Patterns in general-purpose as well as healthcare-specific integration solutions. These DSLs are extensible via Groovy meta-programming. An example of an healthcare-related use case of IPF is the implementation of interfaces for transactions specified in IHE profiles, but you may also use it for developing integration solutions in other domains. IPF can be easily embedded into any Java application and additionally supports deployments inside OSGi environments. Failure recovery and high-availability features support application developers implementing non-functional requirements. The following table summarizes the IPF features.

Feature	Description
Apache Camel	IPF is based on Apache Camel. For an overview of Camel's rich feature set (which can be fully used in IPF applications) refer to the project's integration patterns and integration components pages.
Groovy scripting layer	With IPF you define integration routes with the Groovy programming language. It is more than a mere usage of Camel's domain-specific language (internal DSL or fluent API) inside Groovy: Camel's native DSL has been extended to support e.g. the usage of closures (for inline definitions of message processors, routing rules etc.) and also provides a DSL extension mechanism to define custom extensions to the Camel DSL.
DSL extension mechanism	The DSL extension mechanism is a Groovy meta-programming-based mechanism for defining new DSL elements to be used in integration routes. This is especially useful if you want to provide custom language elements for re-occurring message processing patterns or if you want to design a project-specific message processing DSL (e.g. one that is related to the HL7 domain).
DSL extension index	An index of all predefined DSL extensions provided by IPF.
Core features	These are domain-neutral message processors and DSL extensions usable for general-purpose message processing. The core features also enhance existing Camel DSL elements for usage with Groovy-specific language elements such as closures. For XML message processing there is special Groovy XML support.
HL7 message processing	Basis for HL7 message processing is the HL7 DSL, the HAPI extensions and the HL7 validation DSL. These provides the basis for implementing HL7 message processing routes.
IHE support	A set of components for creating actor interfaces as specified in IHE profiles. IPF currently supports creation of actor interfaces for the IHE profiles XDS.a, XDS.b, PIX and PDQ.
CDA support	A domain-specific language for building and navigating CDA documents. This DSL supports the creation of structurally correct CDA documents by enforcing CDA-relevant schema definitions but without dealing with low-level XML details.
Flow management	A platform service to monitor, query, audit, replay and cleanup message flows. The management interfaces are based on JMX.
OSGi support	Enables the deployment of IPF components (bundles) to OSGi platforms. IPF service bundles register platform services at the OSGi service registry for consumption by IPF applications. Extender bundles control the activation of DSL extensions inside an OSGi environment. A reference implementation of IPF on top of Eclipse Equinox is available as IPF runtime in the IPF Tools project. This project also maintains the complete IPF OSGi documentation.
Event infrastructure	An infrastructure for unified publishing of system-events and application-events. Subscriber components can be configured to translate application events to e.g. Atom/RSS feeds or log files to mention a few.
Performance measurement	DSL and tools to determine the performance characteristics of IPF applications. These allow for measuring the processing time of messages for routes or route parts as well as the message throughput. Performance measurement results can be viewed with a web browser.
Large message support	Provides memory efficient processing of messages with large content sizes.
Quality of service	IPF provides extensions, guidance and solution blueprints (code examples) for implementing non-functional requirements. Covered topics are transactional messaging, flow management, load-balaning and high-availability.
Module adapters	An infrastructure for including platform-independent message processing libraries into platform-specific message processing routes. An alternative is Camel's bean integration mechanism.
Tutorials	A bunch of tutorials that help you get started with IPF.
Guidelines	Guidelines for IPF application development. For example, the DSL extensions guide describes how to write you own DSL extensions.
Project templates	Maven archetypes for most commonly used IPF project types, ranging from simple embedded integration solutions to cluster configurations supporting high-availability scenarios. Usage examples of IPF features are provided as well.

IPF subprojects

Since version 2.0 of IPF several existing components as well as newly developed components have been moved to IPF subprojects. There are currently two IPF subprojects which are described in the following subsections.

IPF Tools

This project provides Eclipse-based development, administration and monitoring tools for the Open eHealth Integration Platform.

The development tools support developers in creating, testing and packaging IPF applications within the Eclipse plugin development environment (PDE). IPF applications created with these tools can be deployed and operated on OSGi R4.1 platforms. Part of the development tools is the IPF Runtime - the OSGi edition of IPF.
The administration and monitoring tools are Eclipse plugins for managing IPF platform and application resources. Examples are JMX-based system management clients or the IPF platform manager.
The IPF runtime is an Eclipse plugin that make IPF features and services available for application development inside Eclipse. The runtime is used to develop OSGi-based IPF applications.

For guidelines how to contribute to this project refer to the Contributing page of the IPF documentation.

IPF Lab

This project is the incubation area for the projects Open eHealth Integration Platform and Open eHealth Integration Platform Tools. Contributions of new features from the IPF community will be mainly done in this project. New features may come from existing IPF applications or are developed from scratch directly in the IPF Lab. This project also hosts components from current research activities such as integrating IPF into cloud-computing environments or into different web application frameworks. For guidelines how to contribute to this project refer to the Contributing page of the IPF documentation.

IPF architecture

IPF architecture in OSGi environments described elsewhere

IPF's architecture in OSGi environments is described in the architecture section of the OSGi support page. It complements the information presented here.

Component architecture

The following figure gives an overview of the IPF components, their dependencies and their namespaces (abbreviated package names). The components of the ihe subpackages (white color) are shown in the next section. The last subsection describes the namespaces and components in more detail. The component names match the jar file names in the Maven repository. The IPF component architecture is also closely related to the project structure in the code repository.

IHE components

The next figure shows the IPF IHE components. The Camel-independent components are contained in the ipf.commons.ihe package, Camel-specific IHE components are contained in the ipf.platform-camel.ihe package. IPF IHE components can be used to implement actor interfaces of IHE transactions. The transaction numbers (ITI) contained in the component name correspond to the transaction numbers in IHE specifications.

IPF and OSGi

All IPF components have been designed to run on an OSGi R4 version 4.1 platform. The osgi package additionally containes specialized OSGi bundles such as extender bundles and configuration fragments (not shown). For a detailed description about IPF and OSGi refer to the OSGi support section.

Namespace and component descriptions

Namespace	Description
`commons`	Namespace for commonly used libraries. Components in this namespace are independent of Apache Camel and have no dependencies to `platform-camel`.
`modules`	Namespace for domain-specific (e.g. HL7) libraries and message processing components. Components in this namespace are independent of Apache Camel and have no dependencies to `platform-camel`.
`osgi`	Namespace for IPF OSGi infrastructure and configuration bundles.
`platform-camel`	Namespace for extensions to the Apache Camel routing and mediation engine. These extensions together with Apache Camel are referred to as the Open eHealth Integration Platform (IPF) from a technical viewpoint.
`tutorials`	Namespace for tutorials demonstrating the features of the Open eHealth IPF (not shown in any of the figures).
`archetypes`	Namespace for IPF project archetypes (not shown in any of the figures).

Component	Description
`commons-core`	A library that defines the common message processing API to be implemented by components contained in the `modules` folder. `platform-camel` provides special integration points for components implementing this common API. The API was defined for implementing message processing components independent of a certain integration infrastructure like Apache Camel. This increases their re-usability and allows applications to implement light-weight message processing functionality without implementing an integration platform or enterprise service bus.
`commons-flow`	A library implementing the flow management services. It is used to monitor, query, audit and replay message flows. The management interfaces are based on JMX. An integration into Apache Camel is provided by `platform-camel-flow`.
`commons-ihe-atna`	A library used by other IPF IHE components to implement IHE ATNA.
`commons-ihe-xds-*`	Libraries used to implements IHE XDS.a and XDS.b actor interfaces. The libraries are Camel-independent
`commons-map`	A code-mapping library.
`commons-lbs`	A library providing storage for large binaries and `javax.activation.DataSource` implementations to represent stored binaries.
`commons-event`	A library containing the Camel independent functionality of the Event infrastructure.
`commons-test`	A library providing support for HTTP-based integration and performance tests.
`commons-xml`	An XML library with focus on Schematron validation.
`modules-cda`	A library for creating, parsing, navigating and rendering CDA documents. Also includes support for several CDA profiles.
`modules-hl7`	A library that implements extensions to the HAPI library.
`modules-hl7dsl`	A library that implements a DSL for manipulating HAPI messages.
`osgi-commons`	See IPF bundle overview.
`osgi-extender-basic`	See IPF bundle overview.
`osgi-extender-spring`	See IPF bundle overview.
`osgi-config-log`	See IPF bundle overview.
`osgi-config-jms`	See IPF bundle overview.
`osgi-config-flow-repository`	See IPF bundle overview.
`osgi-config-flow-manager`	See IPF bundle overview.
`platform-camel-core`	A component that is required by most other `platform-camel` component. It provides: Groovy-based scripting layer DSL extension mechanism Core DSL extensions Adapters to the `commons-core` modules API.
`platform-camel-flow`	A component that implements a flow management DSL for integrating `commons-flow` into Camel routes. The DSL was built with the DSL extension mechanism.
`platform-camel-event`	A component offering the DSL extensions of the event infrastructure
`platform-camel-hl7`	A component that implements an HL7 message processing DSL for integrating `modules-hl7` and `modules-hl7dsl` into Camel routes. The DSL was built with the DSL extension mechanism.
`platform-camel-lbs-core`	A component offering the DSL extensions of the large binary support mechanism as well as the interface to adapt various endpoint technologies to the LBS.
`platform-camel-lbs-cxf`	A component with adaptor implementations for using CXF endpoints with the large binary support.
`platform-camel-lbs-http`	A component with adaptor implementations for using HTTP/Jetty endpoints with the large binary support.
`platform-camel-lbs-mina`	A component with adaptor implementations for using MINA/HL7 endpoints with the large binary support.
`platform-camel-ihe-mllp-*`	Provides MLLP-related functionality used by IPF PIX and PDQ components.
`platform-camel-ihe-pix-*`	Components to implement actor interfaces of IHE PIX transactions. See IHE support.
`platform-camel-ihe-pdq-*`	Components to implement actor interfaces of IHE PDQ transactions. See IHE support.
`platform-camel-ihe-xds-*`	Components to implement actor interfaces of IHE XDS.a and XDS.b transactions. See IHE support.
`platform-camel-test`	A component for measuring the performance characteristics of IPF applications. It provides DSL extensions used to measure processing time of messages (for route parts and whole routes) and the message throughput. Performance measurement reports can be created as well.
`tutorials-basic`	A Hello World-level tutorial for getting started with `platform-camel`
`tutorials-flow`	A tutorial demonstrating IPF flow management features.
`tutorials-hl7`	A tutorial demonstrating HL7 message processing features.
`tutorials-lbs`	A tutorial demonstrating the use of the LBS with CXF and HTTP endpoints.
`tutorials-osgi-*`	A tutorial demonstrating how to write IPF OSGi applications.
`tutorials-ref`	A complete reference application that may be used as blueprint for production-ready IPF applications. The reference application is a comprehensive demonstration of IPF features.
`tutorials-xds`	A tutorial that demonstrates how to use IPF XDS components.
`ipf-archetype-*`	Archetypes for creating IPF integration projects with a ready-to-use Maven 2 and Eclipse configuration plus an example route and unit tests.

IPF Introduction