Building a Subscription Agent

From OpenIndivo Documentation Wiki

Contents 1 Overview 2 Subscription Agent Design 3 Document Relationships 4 Extending the AbstractSubscriptionJob 5 Implementing Type Handlers 6 Configuring your property files 7 Developing, building, and deploying

Overview

The general architecture of an Indivo subscription agent is described on the Subscription Architecture page. This page discusses how to implement a subscription agent that conforms to the general subscription agent architecture.

Very simply, building a subscription agent consists of three main steps:

1. Extend the AbstractSubscriptionJob class
2. Implement the TypeHandler class for each document type you intend to import
3. Properly configure all properties files

This guide will first lay out an agent's basic structure, then describe each of the above steps in a general sense, and conclude with tips on how to use NetBeans and Maven to build, package, and deploy your agent.

Subscription Agent Design

SubscriptionAgent is the main class which runs a SubscriptionJob on the specified schedule. The agent's job scheduling is driven by the Quartz library. The basic configuration provided in the Indivo source does simple once-off or once-daily scheduling out-of-the-box, but advanced options, outlined in the Quartz documentation, may be used.

The SubscriptionJob class is meant to perform core agent tasks, most importantly the execution of each TypeHandler for each subscribed Indivo record, adding and updating all documents returned, and keeping the record's Subscription Document up to date.

A TypeHandler retrieves source data for a given document type, i.e. labs, allergies, immunizations, translates it all into discrete Indivo documents, and returns the documents to the SubscriptionJob.

Document Relationships

Our particular subscription architecture relies on a Subscription Document, stored within each subscribed record, to maintain relationships between Indivo documents and an external datasource. Such a relationship is needed to allow updates of Indivo documents should the external data be changed at a later time. A full description of the Subscription Document schema is available on the Subscription Architecture page.

In your implementation, you may choose to store document relationships and all other necessary metadata outside of the Indivo record.

Extending the AbstractSubscriptionJob

The SubscriptionJob interface has one important method, execute(). Though the specifics differ in each implementation, here's the basic rundown of what it needs to do:

• Identify all the records to which the agent has access
• For each record,
  • Read the Subscription Document
  • Instantiate and run each TypeHandler, collecting the documents it outputs
  • For each document, check Subscription Document for an existing Document Relationship. If one exists, update the existing Indivo document with a new version. Otherwise, add a new document.
  • Update the Subscription Document with any new document relationships and any revised metadata.

The AbstractSubscriptionJob class gives you several useful methods to use by default:

• configure()
  Instantiates a new TalkClient
• getIndivoIds()
  Queries the Indivo Server for accessible records
• getSubscriptionDocument()
  Retrieves a record's subscription document
• updateSubscriptionDocument()
  Updates a record's subscription document
• addOrUpdateDocument()
  Checks the document relationships, then adds a new Indivo document or updates an existing one if possible.
• getTicket()
  Authenticates with the Indivo Server and returns an session ticket

Implementing Type Handlers

Type Handlers have two simple tasks:

• Retrieve data from an external source (i.e. database, web service, CCR file)
• Translate that data into Indivo documents

Ideally, your agent should have a specialized Type Handler for each "type" of Indivo document you would like to import. As such, we recommend that you first implement TypeHandler as an abstract class and define any reusable methods that each handler will need (i.e. database connections, string-to-code translators, etc.).

Configuring your property files

The property files are pretty self-explanatory. These are the properties files that we use by default:

• agent.properties
  Identifies the subscription job class name and the schedule on which to run
• log4j.xml
  For configuring the logger
• quartz.properties
  Quartz scheduler properties
• subscriptionjob.properties
  Contains agent credentials, Indivo server details, and a list of available type handlers
• typehandler.properties
  Database credentials that the type handlers need, plus anything else you find useful

Developing, building, and deploying

A sample subscription agent Maven project is available for download. It may be opened into any IDE that works with Maven, like NetBeans. It will compile out of the box, but it won't really work. The AbstractTypeHandler needs to be customized for your particular datasource/database type, and the SampleHandler is a good place to start building handlers of your own. Refer to the rest of the Indivo codebase for how to create Indivo documents and set their fields.

The Maven build action will generate a project JAR. The assembly action will make a tar.gz of all necessary files to run the agent. Two run scripts (Windows & *nix) will help you start your agent.