The OpenEAI Message Protocol

Version 1.0

January, 2003

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Section being the first section entitled "Introduction", with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "Appendix 1: GNU Free Documentation License".

Introduction

The Root Concept: Authoritative Source

The OpenEAI Message Protocol

Basic Messaging Behavior

*.Query-Request and *.Provide-Reply

*.Create-Request and org.openeai.CoreMessaging.Generic.Response-Reply

*.Update-Request and org.openeai.CoreMessaging.Generic.Response-Reply

*.Delete-Request and org.openeai.CoreMessaging.Generic.Response-Reply

*.Generate-Request and *.Response-Reply

Synchronization Messages

org.openeai.CoreMessaging.Sync.Error-Sync

*.Create-Sync

*.Update-Sync

*.Delete-Sync

Common Error Messages

Enterprise Data Values

Implementing Message Support

Introduction

Work on the OpenEAI Message Protocol began in December 2000 as a collaborative effort between the University of Illinois and SCT Corp. The intent of this collaboration was to provide a format for quantifying enterprise data objects and to prescribe a protocol to communicate or request changes in the state of these enterprise data objects at their authoritative source. The work of the Open Application Group (http://www.OpenApplications.org) provided initial inspiration for early message structure, and that influence is evident in OpenEAI message structure and message definition practices. The OpenEAI Message Protocol strives to express all actions that can be performed on or for enterprise data objects in both request/reply and publish/subscribe messaging models. This protocol is maintained by the OpenEAI Project (info@OpenEAI.org). The original draft of this document was written by Tod Jackson (tod@openeai.org) and Steve Wheat (steve@openeai.org) in 2002 and published January, 2003.

If you are familiar with the Simple Object Access Protocol (SOAP) and related web services technologies, much of what you read here will be familiar—up to a point, particularly the concepts of defining enterprise data as XML objects (what OpenEAI calls "enterprise message objects"), putting them into messages, and transporting them via your preferred transport mechanism. From there, OpenEAI goes on to specify a general protocol for what you can do with any message object within a message, based on the OpenEAI Project’s documented theories of enterprise application integration and the experience of many messaging implementations by the projects participants.

The message format specified by the OpenEAI Message Protocol includes administrative information required to successfully support many complex request/reply and publish/subscribe interfaces that have special performance, security, routing, logging, and auditing requirements. While the OpenEAI Message Protocol can be used for linking two or three applications (and it is easy to use for that purpose), it is important to keep in mind that many of the details of OpenEAI address integration requirements within large enterprises that are complex, with many applications to integrate.

You may be familiar with the concept of foundational APIs that help developers by implementing much of the lower-level mechanics of, for example, building XML messages from data objects. OpenEAI employs this concept. In fact, developing foundational APIs has been the primary focus of the project to date. EAI can involve heavy lifting, such as content-based message routing and data value and format translations. Having a foundation to do this grunt work for you, driven by clear configuration artifacts, makes EAI technology practical to use.

A word of encouragement…if you look at the sample messages and other artifacts below and find yourself thinking, "This is complex!" or, "Gee, do I need all this stuff?"…we advise you to suspend your concern: there are solid foundational APIs to much of the work. For example, one of the message objects described in subsequent sections is BasicPerson. Here is how you would query a remote application for a BasicPerson, and receive the reply:

import org.openeai.jms.producer.PointToPointProducer;

import com.any_erp_vendor.moa.jmsobjects.person.v1_0.BasicPerson;

import com.any_erp_vendor.moa.jmsobjects.person.v1_0.LightweightPerson;

// Get a preconfigured LightweightPerson out AppConfig (an OpenEAI

// application foundation component you can read about in the API

// Introduction document). LightweightPerson is the object we must

// use to query for a BasicPerson according to the definition of

// the message com.any-erp-vendor.Person.BasicPerson.Query-Request.

LightweightPerson lPerson =

(LightweightPerson)getAppConfig().getObject("LightweightPerson.v1_0");

// Set the InstitutionalId, which is an identification number, on the

// LightweightPerson to be that of the BasicPerson we’re querying for.

// If the data we’re passing is not valid, enterprise-quality data

// as prescribed by the enterprise object documents we’ve completed

// an exception will be thrown. You can read more about using enterprise

// object documents to specify valid values, translations, and rules in

// the API Introduction document.

try {

lPerson.setInstitutionalId("123456789");

}

catch (Exception e) {

// perform appropriate exception handling…

}

// Get a preconfigured BasicPerson object from AppConfig.

BasicPerson bPerson =

(BasicPerson)getAppConfig().getObject("BasicPerson.v1_0");

// Get a preconfigured, started PointToPointProducer object from AppConfig

// with which to perform the query action via JMS.

PointToPointProducer p2p =

(PointToPointProducer)getAppConfig().getObject("PointToPoint");

// Perform the query. The query will return a List of BasicPerson

// objects if any are found that match the LightweightPerson we used

// in the query. If any errors occur during the query, an

// exception will be thrown. This includes errors that occur in the

// application that handles the request we are sending.

Java.util.List personList = null;

try {

personList = bPerson.query(lPerson, p2p);

}

catch (Exception e) {

// perform appropriate exception handling…

}

// Log the name associated with each BasicPerson object returned, so

// we can se something about the results we got back from the remote

// application we queried.

For (int i=0; i<personList.size(); i++) {

(BasicPerson)aBasicPerson = (BasicPerson)personList.get(i);

logger.info("Name: " + aBasicPerson.getName().getLastName() + ", " + aBasicPerson.getName().getFirstName());

}

This sends a request and receives the following reply over your message transport.

Request

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE com.any-erp-vendor.Person.BasicPerson.Query SYSTEM "http://xml.openeai.org/message/releases/com/any-erp-vendor/Person/BasicPerson/1.0/dtd/Query-Request.dtd">

<com.any-erp-vendor.Person.BasicPerson.Query>

<SenderAppId>edu.uillinois.uihr.NessieApplication</SenderAppId>

</MessageId>

<AuthUserId>nessie</AuthUserId>

</Authentication>

</Sender>

</Datetime>

</ControlAreaRequest>

</LightweightPerson>

</DataArea>

</com.any-erp-vendor.Person.BasicPerson.Query>

Reply

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE com.any-erp-vendor.Person.BasicPerson.Provide SYSTEM "http://xml.openeai.org/message/releases/com/any-erp-vendor/Person/BasicPerson/1.0/dtd/Provide-Reply.dtd">

<com.any-erp-vendor.Person.BasicPerson.Provide>

<SenderAppId>edu.uillinois.aits.Paymaster</SenderAppId>

</MessageId>

<AuthUserId>paymaster</AuthUserId>

</Authentication>

</Sender>

</Datetime>

<SenderAppId>edu.uillinois.uihr.NessieApplication</SenderAppId>

</ProcessedMessageId>

</Result>

</ControlAreaReply>

<Name>

<LastName>Thoreau</LastName>

<FirstName>Henry</FirstName>

<MiddleName>David</MiddleName>

</Name>

</BirthDate>

</DeceasedDate>

<Ethnicity>Caucasian</Ethnicity>

<Street1>50 Gerty Drive</Street1>

<CityOrLocality>Champaign</CityOrLocality>

<StateOrProvince>Illinois</StateOrProvince>

</EffectiveDate>

</Address>

<Street1>5 Transcendental Pike</Street1>

<CityOrLocality>Concord</CityOrLocality>

<StateOrProvince>Massachusetts</StateOrProvince>

</EffectiveDate>

</Address>

</Phone>

<EmailAddress>dead-transcendentalist@uiuc.edu</EmailAddress>

</Email>

</BasicPerson>

</DataArea>

</com.any-erp-vendor.Person.BasicPerson.Provide>

You can move on to the OpenEAI API Introduction Document after reading this document for details on the foundational APIs and developing OpenEAI integrations using them. Don’t stress about how to actually implement what you see in this document. That’s addressed in detail in the API Introduction document. Think about how the administrative information that you see in these messages could help you. Think about having all of these messages or messages for highly-sensitive transactions sitting in a message log, viewable and searchable from a web application to meet the requirements of those pesky auditors that always seem to pop up when you least expect them. Think about being able to route a publish/subscribe message differently based on which application published it and when it was sent. Think about being able to allow or deny requests to an application based on which application is making the request, which message object or action is being requested, which user is using the application that is making the request, or any other piece of data in the message or that can be queried for using data within the message.

A general understanding of EAI concepts is required in order to understand the mechanics of the OpenEAI Protocol. The following section is a brief primer on EAI concepts. Then we will talk about some basic naming and jargon used by the OpenEAI Message Protocol. Finally, we’ll talk about the messaging behavior prescribed by the protocol. It can be helpful to read this document iteratively. You may wish to read it once, and then read the concepts and naming sections again. It may bring them into sharper focus after you have read about the messaging behavior. They are presented first because an introduction to the concepts and the language are required in order to discuss the messaging behavior.

The Root Concept: Authoritative Source

An authoritative source is the definitive or master source for some unit of quantifiable data in the enterprise. This source is usually implemented as an application or as a database. The following are statements that apply this concept:

1. The Paymaster system is the authoritative source for BasicPerson information for employees.

2. The SCT Banner system is the authoritative source for EmergencyContact data.

3. Icard (the identity card) system is the authoritative source for InstitutionalIdentity data.

This concept of authoritative source raises four questions. Answering these questions is the key practice of Enterprise Application Integration.

The OpenEAI Project provides a concrete methodology, strategies, foundation, and deployment patterns to use as organizations strive to answer these questions.

1. How do you quantify data for which applications are authoritative?

2. How do you expose this quantified data to the rest of the enterprise?

3. How do you transport these messages?

4. How do you produce and consume messages?

For a deeper discussion of the concept of authoritative source, see the OpenEAI Methodology Document. Although the concept of authoritative source is central to OpenEAI, it is important to keep in mind that it is a concept to help organize integrations efficiently. It is not a constraint or a limitation. Use it to your benefit. For example, it is easiest, most clear, and overwhelmingly most common to be able to declare one application in an enterprise to be the authoritative source for a message object (like BasicPerson information) or a qualified message object (like BasicPerson information for employees). Other non-authoritative applications can send request messages to the authoritative application to make changes for objects of that type at the authoritative application. The authoritative application can publish synchronization messages that are routed to non-authoritative applications that just need to know about the state of objects for which the application is authoritative.

However, it is possible that some enterprises may believe that they have two or more applications that are authoritative for the exact same data. In reality, all of these applications may be authoritative for that data, but not all at the exact same moment for the exact same data. In this way, the concept of authoritative source can be used to discover the need for an entirely new messaging infrastructure application—an authoritative source service—and to drive the creation of convergence rules for the rare, but real cases in which multiple applications may need to operate on exactly the same data independently of each other, without messaging with each other, and converging the changes through messaging. For thorough examples of how an enterprise of authoritative sources can be organized, see the OpenEAI Implementation Strategies Document.

For now, let’s look briefly at how OpenEAI attempts to answer these four key questions.

1. How do you quantify data for which applications are autho

Contents

Introduction

The Root Concept: Authoritative Source