OpenEAI Methodology

Version 1.0

May, 2005

Rupa Majumdar (rmajumd@uillinois.edu)

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".

Generate Messages Objects

Develop, Document, and Test Messaging Applications

Update Enterprise Documentation Artifacts

Deploy in Production

Tracking Progress along the Way

Methodology Details: The OpenEAI Integration Template

Step 1: Describe Existing Integrations

Step 2: Describe the Data Involved in the Proposed Integrations

Step 3: Describe the Flow of Data in the Proposed Integrations

Step 4: List Existing and New Enterprise Data Objects Required for the Integrations

Step 5: Name the Messages that Will Be Used to Implement the Integrations

Step 6: Name the Existing and New Messaging Applications Required

Step 7: Provide Technical Stories for the Primary Application

Step 8: Provide Technical Stories for the other Applications Named in the Template

Step 9: Summarize all Outstanding Questions, Issues, and Action Items

Step 10: Perform Work Estimation and Scheduling

Step 11: Functional Approval of Analysis, Scope, and Scheduling

Step 12: Initiate Template Change Control Processes

Step 13: Provide Testing Specifications

Step 14: Develop and Test Integrations

Step 15: Prepare Implementation and Rollout Plan

Step 16: Implement in Production

Appendix 1: Completed Analysis Template Example – Institutional Identity Service

Appendix 2: Completed Analysis Template Example – SunGard SCT Banner

Appendix 3: The GNU Free Documentation License

Introduction

The purpose of the OpenEAI methodology is to bring order, discipline, and transparency to the practices of integration analysis, development, testing, and project management. While the OpenEAI methodology, analysis template, and related artifacts are tailored around some of the specifics of the OpenEAI concepts and technology, many aspects of this methodology add value to any integration project using any concepts and technology. The OpenEAI project encourages organizations to adapt the methodology and artifacts to their practices and technologies and appreciates feedback and suggestions to make the OpenEAI methodology more generally applicable and useful in a wide range of applications.

Note that a number of different names can be used to refer to the defined discrete units of business data used to conduct enterprise messaging transactions: Enterprise Data Objects, Enterprise Message Objects, Enterprise Business Objects, and so on. In the introduction and overview, we’ll simply use the term “enterprise objects” to refer to these business data objects.

Methodology Overview

Perform Analysis

Identify, in general, the systems that need to be integrated. Once those are identified, an analysis group comprised of business or functional experts and technical integration analysts complete the OpenEAI analysis template, or their organization’s customized version of the template, for each application that is to be integrated. Among other things, the template:

· documents general integration requirements

· identifies which new enterprise objects will be required

· specifies which existing enterprise objects will be used

· defines the structure of new enterprise objects

· specifies which message actions of the OpenEAI Message Protocol will be required for each enterprise object

· enumerates the messaging applications, gateways, and infrastructure that must be developed to implement the integrations, and

· enumerates detailed message production and consumption logic

Define Messages

Define any new enterprise objects needed and the message actions they require through the process of completing the OpenEAI analysis template. Technical integration analysts can then create XML message definitions for each of the new messages and their message actions and slot them into the organization’s message hierarchy, and provide a sample message for each definition. This process allows organizations to share message definitions and communicate about them effectively internally and with trading partners. For more background on defining and sharing OpenEAI message definitions and enterprise object documents, see the OpenEAI Message Definition Document.

Generate Message Objects and Related Artifacts

Next, the message definitions are implemented as Java objects. A Java object must be created for every complex enterprise object defined. These Java objects are automatically generated using the OpenEAI MoaGenApplication, which also generates their corresponding enterprise object XML documents. This step is typically performed by EAI analysts, who should be well-suited to complete the enterprise objects documents with the appropriate rules based on the outcome of their EAI analysis. For more information on the Java message object API (MOA), see the Java message object section of the OpenEAI API Introduction Document.

Develop, Document, and Test Messaging Applications

The details of this phase will vary from organization to organization: many organizations already have application development and testing practices established. However an organization chooses to implement them, the following guidelines should be considered.

1. Developers and analysts prepare detailed, technical stories for each messaging application and gateway listed in the completed analysis. These stories will draw heavily on the message production and consumption logic prepared by the subject matter experts and analysts included in the analysis template.

2. Developers implement the appropriate messaging applications and gateways listed in the template using OpenEAI foundation components, the message object API that was generated for the organization’s enterprise objects, and the enterprise object documents completed by the subject matter experts and analysts. When developing an OpenEAI-based application or gateway, this means developing the commands needed to support the processes defined in the analysis.

3. While steps one and two above are proceeding, integration analysis staff can prepare OpenEAI TestSuiteApplication test suite documents for testing the message gateways that are to be developed. Test suite documents are XML documents made up of messaging test cases. The OpenEAI TestSuiteApplication can take a test suite document and execute all its test cases very rapidly: it sends test messages to a target application and compares the replies received and sync messages published by the target application with expected results, produces a detailed report, and can even tear-down any messaging artifacts or database entries created as a result of the TestSuite execution. Subject matter experts and analysts are typically the best equipped to prepare these test suite documents, because they are the people who know the business logic and they also specified the integration requirements, message production logic, and message consumption logic. Developers can perform this work, but if they do, the subject matter experts and analysts should review the test cases and certify they represent the requirements.

It is useful for developers to have these test cases available to them during the development process. As they implement message support they can iteratively execute the test suite using the OpenEAI TestSuiteApplication to check their progress. As developers make changes they can use the test suites to verify they do not break any required behavior.

At this time, subject matter experts and analysts also prepare real-world online and batch scenarios to test the new messaging applications and gateways in combination with the rest of the messaging enterprise in a test environment.

4. All messaging applications and gateways pass both informal developer testing and all of the formal test suites executed using the TestSuiteApplication.

5. The new messaging applications and gateways are promoted from a development environment to a test environment for integration testing, and the real-world online and batch scenarios are executed until the subject matter experts and analysts are convinced the new applications are performing appropriately. Note that although the practice of preparing test suites and unit testing messaging applications can be very effective at ensuring that messaging applications perform as designed, it may not help validate that the design is correct. From time to time integration testing with the rest of the messaging enterprise turns up new requirements, such as identifying additional applications that need to know about data from a new authoritative source. For this reason, integration testing is a critical part of the process. It is also the part of the testing process that gives management a tangible level of confidence that it is appropriate to proceed with a production implementation.

Update Enterprise Documentation Artifacts

Practicing the OpenEAI methodology produces a number of documentation artifacts, including an analysis template for each application that interfaces with other applications, enterprise object definitions, message definitions, and javadoc for applications that implement support for each enterprise object. These artifacts should be posted in a web-accessible format. For example, message definitions and enterprise object documents should be posted on a web server so messages can be validated when necessary and so field-level business rules and translations can be applied by the Java implementation of the message objects at runtime. This practice allows you to build a web page to nicely document each messaging application or gateway, linking to and leveraging each of these artifacts that must be created anyway to support XML document validation and enterprise object validation. For more information on posting message object definitions, enterprise object documents, and a description of the application in an enterprise, and which enterprise objects these are authoritative for, see the OpenEAI Message Definition Document.

This document recommends a format for these web pages in the documentation section below. One real-world example of such documentation is available on the “Get Enterprise Data” page of the University of Illinois’ Administrative IT web site at http://www.aits.uillinois.edu/GetEnterpriseData.

Just as your organization may customize the analysis template or the OpenEAI methodology itself, you will likely choose to customize the web documentation template as well. This web documentation can be posted on your organizational web site or intranet. Posting this documentation helps managers, functional analysts, and technical analysts plan and prepare for new integrations. Additionally, many organizations have auditing or best-practice requirements that mandate the preparation of some type of formal documentation for each integration. Posting this documentation as a web page makes this information available to those who need it. In some cases, it can even be helpful to complete and post most of the template prior to or during the development phase.

Deploy in Production

There’s not much to say about this step from an overview perspective, since if you get to this point, most of the work has already been done. If you follow the recommended OpenEAI practices for testing in pre-production environments, deploying in production should be anticlimactic. The OpenEAI Deployment Patterns document provides details on the minimum number of recommended environments you should set up for a messaging enterprise and how and when to promote messaging applications and gateways from one environment to the next.

Tracking Progress along the Way

Two major risk categories inherent in integration projects are “real” and “perceived” failure. There are many ways to fail when integrating complex systems. The best way to avoid failure, or even the perception of failure, is to track progress and manage changing requirements, expectations, and timelines. The single most important benefit of a structured integration analysis template is that it breaks work into discrete tasks for which status can be recorded in the template and tracked by integration project managers in their overarching project plans. The OpenEAI integration analysis template supports this tracking and reporting by encouraging integrators and analysts to identify resources, estimate work, and set goals for every step along the way. These goals can be noted and tracked by project managers who can help escalate deficient resources or accelerate lagging progress before they become blocking issues or high risks for the integration project or the larger project under which this integration work is occurring.

Methodology Details: The OpenEAI Integration Template

Note: a standalone version of this template, separate and distinct from the Methodology Document, is available on the OpenEAI Project documentation page at:

http://www.openeai.org/openeai.xml?document=Documentation.xml

This standalone version can be a convenient starting point for customizing your organization’s own version of an integration process.

Revision history: the OpenEAI project strongly recommends that you use a versioning system such as CVS, Subversion, or something similar to track changes to analysis artifacts, and that you clearly indicate the current revision of artifacts within them. For example, see the revision information in header on each page of this document.

Application Name: XXXXXXXXXXXX

Module Name (if appropriate): XXXXXXXXXXXX

Phase (if appropriate): XXXXXXXXXXXX

Integration Timeframe: XXXXXXXXXXXX

Target Template Completion Date: XXXXXXXXXXXX

Template Owner Name: XXXXXXXXXXXX

Total Work Estimate: XXXXXXXXXXXX

Resources Named in Template: XXXXXXXXXXXX

XXXXXXXXXXXX

Location of Detailed Project Plan: XXXXXXXXXXXX

Template Change Reviewers: XXXXXXXXXXXX

XXXXXXXXXXXX

Template Status: Step 1 Step 2 Step 3 Step 4

Step 5 Step 6 Step 7 Step 8

Step 9 Step 10 Step 11 Step 12

Step 13 Step 14 Step 15 Step 16

Overview:

The integration analysis and design process consists of the following steps. Steps 1 and 2 should be completed prior to the integration design meetings with EAI staff.

Step 1: Describe Existing Integrations - Describe and define present application interfaces for the application named in this template. This information will be used to help define enterprise data objects for use in messages when design teams meet with integration staff. It is recommended that this section be completed prior to integration design meetings with integration staff.

Step 2: Describe Data Involved in Proposed Integrations - Define the data for which the application named in this template is authoritative. That is, which data in this application will other applications need. Also describe which data this application will need for which other applications are authoritative. This information will also be used to help define enterprise data objects for use in message when design teams meet with integration staff. It is recommended that this section be completed prior to integration design meetings with integration staff.

Step 3: Describe the Flow of Data in the Proposed Integrations - Define (at a high level) the flow of data between the application named in this template and other applications to support the interfaces defined in steps 1 and 2. This section should be completed during the integration design phase with integration staff.

Step 4: List Existing and New Enterprise Data Objects Required for the Integrations - List existing enterprise data objects that will be reused and new enterprise data objects that will be defined to support application interfaces for the application named in this template. This section should be completed during the integration design phase with integration staff.

Step 5: Name the Messages that will be used to Implement the Integrations - Name the messages that use the enterprise data objects to implement the integration flows. This section should be completed during the integration design phase with integration staff.

Step 6: Name the Existing and New Messaging Applications Required - Name the existing messaging applications that will be used or define the new messaging applications that must be implemented to produce, consume, transform, and route the messages listed in step 5. This section should be completed during the integration design phase with integration staff.

Step 7: Provide Technical Stories for the Primary Application - For the primary application named in this template, list the messages it must produce and consume and provide detailed stories describing the prescribed production and consumption logic. The owner of the application, who is also responsible for implementing message production and consumption, should prepare the detailed stories. This section should be completed during the integration design phase with integration staff.

Step 8: Provide Technical Stories for the other Applications Named in the Template - For each remaining application listed in step 7, list the new messages each application must produce and consume and provide brief stories describing the prescribed production and consumption logic. This section should be completed during the integration design phase with integration staff.

Step 9: Summarize all Outstanding Questions, Issues, and Action Items - Record all questions, issues and action items during the analysis and design sessions.

Step 10: Perform Work Estimation and Scheduling – Identify resources and estimate work for each aspect of the project enumerated in the template and prepare a detailed project plan.

Step 11: Functional Approval of Analysis, Scope, and Scheduling - Functional team members must signoff to indicate completion of the analysis, design, and planning.

Step 12: Initiate Template Change Control Processes – Identify the integration change reviewers and begin the process of convening them to review every subsequent change to the template. These reviews should answer the following questions and ensure the appropriate follow-up actions are taken:

· Does the change impact the scope or timeline established for the integration?

· Does the change impact the overall design of the integration?

· Has the impact been properly reflected in the project plan and timeline?

· Do all approvers who initially approve this template also approve of this change?

Step 13: Provide Testing Specifications – Develop detailed testing specifications for the integration. This will usually consist of one or more OpenEAI Test Suites and some functional application use cases that can be used to certify the functionality of the integration. Typically, test specifications will also include a load testing strategy for the integration, which may again use OpenEAI test suites or involve testing the integration in a production-like environment. Finally, some production readiness test procedures should be specified. This testing can be performed in production after the integration is deployed to verify that it is properly deployed. The procedures can be reused whenever changes are made to the production deployment of this integration. Usually, production readiness testing is implemented with an OpenEAI test suite or application use-case scenarios that can be automated using monitoring or testing tools.

Step 14: Develop and Test Integrations – Develop the required message support for the gateways and applications using the technical stories and test specifications provided in the template. Most development processes are iterative, so changes in stories and requirements should be documented and trigger the template change control process. In this step, tests are often expanded and improved as a concrete picture of the integration functionality emerges.

Step 15: Prepare Implementation and Rollout Plan – Prepare a deployment diagram that visually depicts the deployment and complete an implementation rollout plan enumerating the steps required to implement the new integration in production.

Step 16: Implement in Production – Execute the rollout plan and production readiness testing.

The next sections of the document describe the details required for the steps listed above.

Step 1: Describe Existing Integrations

Describe and define present application interfaces for the application named in this template. This information will be used to help define enterprise data objects for use in messages when design teams meet with integration staff. This section should be completed prior to integration design meetings with integration staff.

What data does this application store and operate on that it does not create itself? Typically, this data is usually acquired by the application through batch extracts and feeds, remote procedure calls, or data replication. For example, a payroll history database and an employee change of status application may both maintain and in some cases update employee job data. This data is kept synchronized with the payroll system by scheduled batch feeds from the payroll system to these applications. Changes made to this data in these applications are updated in the payroll system through scheduled batch feeds from these applications back to the payroll system. Another way to ask this question is: What business events occur in other applications that the current application must know about and what business events occur in this application that other applications must know about?

1.1. Describe the current business processes that the primary application named in the template supports, how data is presently acquired, the timeline in the case that some of these existing integrations are being phased out, and the current flow of data between applications. This should be a high-level description in plain English prose not to exceed one page of text. No charts or diagrams should be provided.

Description: XXXXXXXXX

Timeline: XXXXXXXX

Flow: XXXXXXXXX

1.2. List current application interfaces for the primary application named in the template that synchronizes data changes made in other applications to the primary application named in this template.

[For each application, provide the name, description, source data structure, target data structure and how the source data is used to update the target. Use the structure below for the first application and repeat for other applications. If not applicable indicate above by N/A.]

List of interfaces: XXXXXXXX, XXXXXXXX

1.2.1. Source application details:

Source Application Name:	XXXXXXXX
Source Application Description:	XXXX XXXX (Brief description)
Source Data Structure: (repeat for each table or filename related to this interface)	Database Name: XXXXXXXX Table Name: XXXXXXXX File Name: XXXXXXXX
Source Field Name	Field type	Width	Nullable	Comments
Example TAPPOINTMENT.APPT_REF_NBR	CHAR	1	NO	The appointment reference number in the employee change of status application

1.2.2. Target application details:

Target Application Name:	This is the application named in the template
Target Application Description:	Description already given for the Application named in the template.
Target Data Structure: (repeat for each table or filename related to this interface)	Database Name: XXXXXXXX Table Name: XXXXXXXX File Name: XXXXXXXX
Target Field Name	Field type	Width	Nullable	Comments
Example APPOINTMENT-REF-NUM-60	VARCHAR	60	NO	The appointment reference number in the payroll system

1.3. List the interfaces that take data changes from the primary application named in the template to other existing applications.

List of interfaces: XXXXXXXX, XXXXXXXX

1.3.1. Source application details:

Source Application Name:	This is the application named in the template
Source Application Description:	Description already given for the Application named in the template.
Source Data Structure: (repeat for each table or filename related to this interface)	Database Name: XXXXXXXX Table Name: XXXXXXXX File Name: XXXXXXXX
Source Field Name	Field type	Width	Nullable	Comments
Example LAST-NAME-10	CHAR	23	NO	The last name of a person in the payroll system

1.3.2. Target application details:

Target Application Name:	XXXXXXXX
Target Application Description:	XXXX XXXX (Brief description)
Target Data Structure: (repeat for each table or filename related to this interface)	Database Name: XXXXXXXX Table Name: XXXXXXXX File Name: XXXXXXXX
Target Field Name	Field type	Width	Nullable	Comments
Example TPERSON.LAST_NAME	VARCHAR	30	NO	The last name of a person in the employee change of status system

Step 2: Describe Data Involved in Proposed Integrations

Describe and define the data that may be involved in interfaces with the application named in this template. This information will also be used to help define enterprise data objects for use in message when design teams meet with integration staff. This section should be completed prior to integration design meetings with integration staff.

2.1. Describe the proposed business processes that the application named in the template will supports, how data will be acquired, the timeline and the proposed flow of data between applications. This should be a high-level description in plain English prose not to exceed one page of text. No charts or diagrams should be provided.

Description: XXXXXXXXX

Timeline: XXXXXXXX

Flow: XXXXXXXXX

2.2. What data will this application require from other authoritative sources?

[Provide the name, description, authoritative source data structure, target data structure, and how the data will be used to update the application named in the template. Use the structure below for each authoritative source table and Target table and repeat as needed. If not applicable indicate above by N/A.]

2.2.1. Module details:

Source Application Name:	(name of the other authoritative system)
Source Application Description:	(Briefly describe the authoritative source module or business function involved in this interface.)
Source Data Structure: (repeat for each table or filename related to this interface)	Database Name: XXXXX Table Name: XXXXXXXX
Source Field Name	Field type	Width	Nullable	Comments
Example GENDER	VARCHAR	1	YES	The gender code stored by the authoritative source related to a person’s gender

2.2.2. Target application details:

Target Application Name:	This is the application named in the template
Target Application Description:	Description already given for the application named in the template
Target Data Structure: (repeat for each table or filename related to this interface)	Database Name: XXXXXXXX Table Name: XXXXXXXX File Name: XXXXXXXX
Target Field Name	Field type	Width	Nullable	Comments
Example LEGACY_GENDER	CHAR	1	NO	Gender code stored by the legacy system

2.3. For what data will this application be the authoritative source?

[Provide the name, description, and how the inputs will used to update the application named in the template. Use the structure below for each source data structure. If not applicable indicate above by N/A.]

2.3.1. Source application details:

Source Application Name:	(This is the application named in the template)
Source Application Description:	(Description already given for the Application named in the template.)
Source Data Structure: (repeat for each table or filename related to this interface)	Database Name: XXXXXXXX Table Name: XXXXXXXX File Name: XXXXXXXX
Source Field Name	Field type	Width	Nullable	Comments
Example LAST-NAME-10	CHAR	23	NO	The last name of a person in the legacy system

2.3.2. Target module details:

Target Application Name:	Other system that requires data from our legacy system
Target Application Description:	(Briefly describe the module involved in this interface.)
Target Data Structure: (repeat for each table or filename related to this interface)	Database Name: XXXXX Table Name: XXXXXXXX
Target Field Name	Field type	Width	Nullable	Comments
Example LAST_NAME	VARCHAR	60	NO	The last name of a person in the target system

Step 3: Describe the Flow of Data in the Proposed Integrations

Define (at a high level) the flow of messages between the application named in this template and other applications to support the interfaces defined in steps 1 and 2. This section should be completed during the integration design phase with integration staff.

3.1. Application 1: Payroll System (Example)

1. As basic person and basic employee information changes the Payroll System, the Payroll System publishes synchronization messages to keep the ERP and Identity Service up-to-date.

2. …

3.2. Application 2: Identity Service (Example)

1. The Identity Service must handle incoming ID number query and generate requests and send the appropriate replies.

2. The Identity Service must handle incoming basic person and basic employee synchronization messages and apply any changes to the Identity Service database to keep its data current.

3. …

3.3. Application 3: ERP (Example)

1. The ERP must consume basic person and basic employee synchronization messages from the legacy Payroll system to keep its data current.

2. …

Step 4: List Existing and New Enterprise Data Objects Required for the Integrations

List existing enterprise data objects that will be reused and new enterprise data objects that will be defined to support application interfaces for the application named in this template. This section should be completed during the integration design phase with integration staff.

XML’s Naming Convention:

? – Optional (0 or 1)

* – Optional (0 or more)

+ – At least 1 or more

Example:

<!ELEMENT ParentElement (ChildElementOne, ChildElementTwo?, ChildElementThree*, ChildElementFour+)>

<!ATTLIST ParentElement

parentAttributeOne CDATA #REQUIRED

parentAttributeTwo CDATA #IMPLIED

All attribute names begin with lowercase. All element names begin with uppercase. In this example, ChildElementOne is required, ChildElementTwo is either “null” or has a single value, ChildElementThree is either “null” or can have one or more values, and ChildElementFour cannot be null but must have one or more values. Attribute parentAttributeOne must be provided in the XML message, whereas parentAttributeTwo is optional.

Object Hierarchy Naming Convention:

The following naming conventions are equivalent:

ParentObject / ChildObject

ParentObject

ChildObject

ParentObject.ChildObject

ParentObject @ parentAttribute

ParentObject

parentAttribute

ParentObject.parentAttribute

[Existing enterprise data objects are found in the Segments.dtd files.] These are available as part of the integration documentation at:

[location to the Segment file(s)]

4.1 Existing enterprise data objects that will be reused or modified. This section should include the current definition of the enterprise objects as they appear in the enterprise message repository at the time the analysis was performed and any proposed changes.

[List the enterprise objects to be reused or state ‘None’ if no objects are available.]

1. LightweightPerson (Example)

2. UnknownPerson (Example)

4.2 New enterprise data objects proposed. This section should include the proposed name and structure of the new data objects.

File

Name

Proposed Definition

Segments

InstitutionalIdentity

<!ELEMENT InstitutionalIdentity (InstitutionalId, UnknownPerson)>

Step 5: Name the Messages that Will Be Used to Implement the Integrations

Name the existing and proposed messages that use the enterprise data objects to implement the integration flows. This section should be completed during the integration design phase with integration staff.

5.1. Existing Messages

[List existing messages to be used in this interface or indicate that none are available for use.]

1. org.any-openeai-enterprise.CoreApplication.InstitutionalIdentity.Generate-Request (Example)

2. org.any-openeai-enterprise.CoreApplication.InstitutionalIdentity.Delete-Request

(Example)

5.2. Proposed Messages

[List proposed messages to be used in this interface or indicate that none are proposed for this interface.]

1. com.sct.Person.BasicPerson.Create-Sync (Example)

2. com.sct.Person.BasicPerson.Delete-Sync (Example)

3. com.sct.Person.BasicPerson.Update-Sync (Example)

Step 6: Name the Existing and New Messaging Applications Required

Name the existing messaging applications that will be used or define the new messaging applications that must be implemented to produce, consume, transform, and route the messages listed in step 5. This section should be completed during the integration design phase with integration staff.

6.1. Existing Messaging Components

[List existing components to be used in this interface or indicate that none are available for use]

Name	Type	Status	Responsible Unit
(Example) Identity Service	Gateway	Implemented	Unit responsible for supporting this service (both the data and the implementation)

6.2. New Messaging Components

Name	Type	Status	Responsible Unit
(Example) Payroll system	gateway	planned	Unit responsible for supporting this service (both data and the implementation)
(Example) ERP Gateway	gateway	In development

6.3. Other interface Components

Name	Type	Status	Responsible Unit
(Example) Payroll extract	application	planned

Step 7: Provide Technical Stories for the Primary Application

For the messaging component(s) of the application named in this template, list the messages that component must produce and consume and provide detailed stories describing the prescribed production and consumption logic. The owner of the application who is also responsible for implementing message production and consumption should prepare the detailed stories. This section should be completed during the integration design phase with integration staff.

7.1. Messages

Messages to produce

1. org.any-openeai-enterprise.CoreApplication.InstitutionalIdentity.Query-Request (Example)

2. org.any-openeai-enterprise.CoreApplication.InstitutionalIdentity.Generate-Request (Example)

Messages to consume

3. org.any-openeai-enterprise.CoreApplication.InstitutionalIdentity.Provide-Reply (Example)

4. org.any-openeai-enterprise.CoreApplication.InstitutionalIdentity.Create-Sync (Example)

7.2. Message Production Logic

[Describe the message production logic, the XML format for each message and mapping to source data that the application or gateway must produce.]

(Example) The legacy payroll system gateway must send InstitutionalIdentity.Query-Request and InstitutionalIdentity.Generate-Request messages to determine if each new employee is already known by the identity service and to generate a new identity for each new employee who is not already known by the identity service. This gateway must also publish BasicPerson and BasicEmployee synchronization messages as person and employee information changes. This process will occur whenever the legacy payroll system gateway is provided with new payroll data. Presently, new payroll files are produced nightly.

1. org.any-openeai-enterprise.CoreApplication.InstitutionalIdentity-Query-Request (provide DTD link| Sample message link)

Data Area Element values:

(Example) UnknownPerson element (provide Segments link)

The UnknownPerson/SocialSecurityNumber element value is taken from the Payroll SSN-10 field.

Enterprise Object Element / Attribute	Source Database Table Example Paymaster Table	Source Database Field and transformations Example Paymaster Field
UnknownPerson
SocialSecurityNumber	Paymaster	SSN-10 This must be numeric
Name/FirstName	Paymaster	FIRST-NAME-10 Convert to mixed case

Implementation resources:

Work estimate in hours:

2. org.any-openeai-enterprise.CoreApplication.InstitutionalIdentity-Generate-Request (provide DTD link| Sample message link)

Data Area Element values:

Enterprise Object Element / Attribute	Source Database Table	Source Database Field and transformations

Implementation resources:

Work estimate in hours:

7.3. Message Consumption Logic

[Describe the message consumption logic, the XML format for each message and mapping to target data that the application or gateway must consume.]

(Example) The Payroll gateway will consume messages in response to each of the messages it produces and sends to other messaging components. The messages it must consume are:

3. org.any-openeai-enterprise.CoreApplication.InstitutionalIdentity-Provide-Reply (provide DTD link| Sample message link)

(Example) The payroll gateway will expect this reply message from the Identity Service gateway in Response to an org.any-openeai-enterprise.CoreApplication.InstitutionalIdentity.Query-Request message.

Data Area Element values:

Enterprise Object Element / Attribute	Target Database Table	Target Database Field and transformations

Implementation resources:

Work estimate in hours:

4. org.any-openeai-enterprise.CoreApplication.InstitutionalIdentity-Create-Sync

Data Area Element values:

Enterprise Object Element / Attribute	Target Database Table	Target Database Field and transformations

Implementation resources:

Work estimate in hours

Step 8: Provide Technical Stories for the other Applications Named in the Template

For each remaining messaging component listed in step 6, list the new messages that component must produce and consume and provide brief stories describing the prescribed production and consumption logic. This section should be completed during the integration design phase with integration staff.

8.1. Messaging Component 1: ERP Gateway (Example)

8.1.1. Messages

1. com.sct.Person.BasicPerson.Create-Sync (Example)

2. com.sct.Person.BasicPerson.Delete-Sync (Example)

3. com.sct.Person.BasicPerson.Update-Sync (Example)

8.1.2. Brief Story

(Example) The ERP Gateway must consume the BasicPerson and BasicEmployee synchronization messages.

8.2. Messaging Component 2: Identity Service (Example)

8.2.1. Messages

1. org.any-openeai-enterprise.CoreApplication.InstitutionalIdentity-Query-Request (Example)

2. org.any-openeai-enterprise.CoreApplication.InstitutionalIdentity-Generate-Request (Example)

3. org.any-openeai-enterprise.CoreApplication.InstitutionalIdentity-Provide-Reply (Example)

8.2.2 Brief Story

(Example) The Identity Service must field incoming InstitutionalIdentity query request and provide replies. It must also …..

Step 9: Summarize all Outstanding Questions, Issues, and Action Items

Record all questions, issues and action items during the analysis and design sessions. Status will be indicated only when it is “closed”.

#	Question / Issues /Actions	Who?	Resolution	Date Resolved	Status
1
2
3
4
5
6
7
8
9
10

Step 10: Perform Work Estimation and Scheduling

Review work estimates provided with each story and messaging application. Sequence implementation work into a detailed project plan using your preferred project management tools.

10.1 List New Messaging Applications to Develop and Summary Work Estimates

Messaging Application

Resources

Total Hours

(Example) Payroll System Gateway

Chris Analyst, analysis and test suite development (24 hours)
Suzy Developer, BasicPerson message support (12 hours)
Joe Developer, BasicEmployee message support (12 hours)
Q.A. Masters, Test Suite Review and Certification (24 hours)

10.2 List New Message Support to Add to Existing Messaging Applications and Summary Work Estimates

Messaging Application

Resources

Total Hours

(Example) Identity Service

Chris Analyst, analysis and test suite development (36 hours)
Suzy Developer, InstitutionalIdentity synchronization message support (20 hours)
Q.A. Masters, Test Suite Review and Certification (24 hours)

10.3 Detailed Work Plan

Location of detailed implementation project plan: [provide link to location here]

Step 11: Functional Approval of Analysis, Scope, and Scheduling

Functional team members must give approval to indicate completion of the analysis and design. An e-mail stating approval may be copied and pasted here instead of a signature on paper.

While many may consider this a pedantic step, experience teaches that this level of explicit approval is often required to support a strict scope management and change control process.

Project Role	Team member name	Signature	Approval Date

Step 12: Initiate Template Change Control Processes

Application name:

Payroll System Gateway (example)

Requestor name(s):

xxxx xxxxxxx

Priority:

XXXX (Low, Medium, High. Please give details in later section for priority)

Change Request Number:

(starts at 1 and increments by 1 for each application change request)

Brief change request description: xxxxxxxxx

Process for change requests: The EAI template should be completed during the period allocated to do the analysis and design work. Any changes subsequent to approval and acceptance of the template should follow the change request process. The change requests will be submitted by the requesting team to the EAI project manager who will forward the request to management for approval.

All items in this template must be filled out completely otherwise it may delay processing. For items that are not relevant to the change being requested please indicate that by typing in “Not Applicable”.

The change requests must be packaged each week and delivered to the EAI project manager by Thursday noon. The review will be generally completed by the following Tuesday.

12.1 New requirements information: Please fill out the story and the details for the new functionality or services the gateway or application must support. This section must also be completed if there are new tables or fields in the requirements with or without any new functionality or services being requested.

[Provide story here]

12.2 Reference section in the existing EAI template which is impacted by the new request:

[Provide template section numbers or messages that are impacted by the new requirements]

12.3 Impact on other known integrations:

[example: Same change required in IdentityService template]

12.4 Describe priority (LOW, MEDIUM, HIGH):

[Describe the reasons behind the priority assessment in story format. If this requires a faster turnaround describe why and what dependencies it may share with other tasks]

12.5 New source system table and fields, if applicable:

[List the table and fields]

12.6 New target system table and fields, if applicable:

[List the table and fields]

12.7 New transformation requirements, if applicable:

Source table or file:	XXXXXX
Target table or file:	XXXXXX
Source field	Target field	Transformation and reformatting rules	Message object
Example Last-Name-10	Last_Name	None	BasicPerson/Name/LastName

12.8 Message Object changes:

[Enumerate message object definition changes.]

12.9 Work impact:

[Describe the anticipated impact on the project plan and timeline.]

12.10 Approval:

Management will sign and send documents back to the EAI team and the requestor. Approval implies acceptance of the change in timeline.

Approval Request date:	mm-dd-yyyy
Project Role	Name	Signature	Signature date	Status (Approved or Denied)
Project director
Project manager
Project manager
Project manager

Step 13: Provide Testing Specifications

13.1 Test Stories

For every messaging application and gateway listed in this template, provide a brief description of how it will be tested for functional, performance, and production readiness certification.

(Example) Payroll System Gateway

Functional testing of the payroll system gateway will be accomplished by preparing an OpenEAI test suite to test the gateway’s ability to handle BasicPerson and BasicEmployee query, create, update, and delete request messages as well as its ability to publish the corresponding synchronization messages. The goal of this test suite is to cover all actions on both BasicPerson and BasicEmployee objects using an appropriately diverse set of data.

Performance testing of the payroll system gateway will be accomplished by preparing an OpenEAI test suite with multiple series that can be run concurrently from one or more deployments of the test suite application to simulate the peak anticipated production load of concurrent requests. This suite will be used to test a deployment of the payroll system gateway to determine if the performance of deployment will handle the anticipated peak load. Additionally performance tests of web applications that send request messages to this gateway will be conducted independently of the gateway testing.

A self-contained production readiness OpenEAI test suite will be prepared that creates, queries for, updates, and deletes several bogus users and employees using realistic data. This test suite will be executed to certify the deployment in both non-production and production environments.

13.2 Links to Testing Artifacts Listed in the Test Stories and Preparation Status

Testing Artifact Description	Location	Preparation Status
(Example) Payroll System Gateway Functional Test Suite	CVS Repository Project/TestSuites PayrollSystemGateway.TestSuite1.xml	100%
(Example) Payroll System Gateway Performance Test Suite	CVS Repository Project/TestSuites PayrollSystemGateway.TestSuite2.xml	70%

Step 14: Develop and Test Integrations

At this point, development tasks for each messaging application and service should be enumerated in the integration project plan or master project plan. Developers and quality assurance staff should be developing and testing applications and gateways and reporting status on their assigned tasks.

A summary of tasks and their status could be maintained here in the integration template, but it is strongly encouraged to maintain this information and refer to it in a master project plan.

Step 15: Prepare Implementation and Rollout Plan

A rollout plan differs from the overall project plan in that it provides clear, step by step instructions for deployment and production readiness testing activities. This plan should be completed prior to production implementation and executed in a non-production environment as a practice or “dress rehearsal” run.

Step 16: Implement in Production

At this stage, production implementation should be anti-climactic. Execute the rollout plan, which should include production readiness testing, and celebrate.

Appendix 1: Completed Analysis Template Example – Institutional Identity Service

This completed template is an example of an organization’s use of the OpenEAI template to perform the analysis for an identity service. The template was customized and curtailed for the organization’s needs. This completed template was given to the OpenEAI project by the University of Illinois.

$Revision: 1.5 $

$Date: 6/2/2005 5:07 PM$

$Source: /cvs/repositories/openeai/project/documentation/core/Methodology.rtf,v $

Application Name: ICard

Module Name: ICard

Phase: 1

Timeframe: December 2001—June 2002)

Target template completion date: 07-30-2001

Template Owner Name: Jeff Fletcher

Template Status: Step1 Step2 Step3 Step4

Step5 Step6 Step7 Step8

Overview

The integration analysis and design process consists of the following steps. Steps 1 and 2 should be completed prior to the integration design meetings with AITS staff.

Step 1. Describe and define present application interfaces for the application named in this template. This information will be used to help define enterprise data objects for use in messages when design teams meet with AITS integration staff. This section should be completed prior to integration design meetings with AITS integration staff.

Step 2. Describe and define Banner data that may be involved in interfaces with the application named in this template. This information will also be used to help define enterprise data objects for use in message when design teams meet with AITS integration staff. This section should be completed prior to integration design meetings with AITS integration staff.

Step 3. Define (at a high level) the flow of messages between the application named in this template and other applications to support the interfaces defined in steps 1 and 2. This section should be completed during the integration design phase with AITS integration staff.

Step 4. List existing enterprise data objects that will be reused and new enterprise data objects that will be defined to support application interfaces for the application named in this template. This section should be completed during the integration design phase with AITS integration staff.

Step 5. Name the messages that use the enterprise data objects to implement the integration flows. This section should be completed during the integration design phase with AITS integration staff.

Step 6. Name the existing messaging components that will be used or define the new messaging components that must be implemented to produce, consume, transform, and route the messages listed in step 5. This section should be completed during the integration design phase with AITS integration staff.

Step 7. For the messaging component(s) specifically for the application named in this template, list the new messages that component must produce and consume and provide detailed stories describing the prescribed production and consumption logic. The owner of the application who is also responsible for implementing message production and consumption should prepare the detailed stories. This section should be completed during the integration design phase with AITS integration staff.

Step 8. For each remaining messaging component listed in step 6, list the new messages that component must produce and consume and provide brief stories describing the prescribed production and consumption logic. This section should be completed during the integration design phase with AITS integration staff.

The next sections of the document describe the details required for the steps listed above.

1. Step 1

Describe and define present application interfaces for the application named in this template. This information will be used to help define enterprise data objects for use in messages when design teams meet with AITS integration staff. This section should be completed prior to integration design meetings with AITS integration staff.

What data does this application store and operate on that it does not create itself? Presently, this data is usually acquired by the application through batch extracts and feeds, remote procedure calls, or data replication. For example, applications such as Payroll History Database (PHD) and ECOS maintain and in some cases update appointment data. This data is kept synchronized with Paymaster by scheduled batch feeds from Paymaster to these applications. Changes made to this data in these applications are updated in Paymaster through scheduled batch feeds from these applications to Paymaster. Another way to look at this question is what business events occur in other applications that the current application must know about, and what business events occur in this application that other applications must know about.

1.1. Describe the current business processes that the application named in the template supports, how data is presently acquired, the timeline, and the current flow of data between applications. This should be a high-level description in plain English prose not to exceed one page of text. No charts or diagrams should be provided.

Description: ICard is the University’s identification card and ID number generation and tracking system for all University employees, students, and other entities like vendors, student spouses, and persons and non-persons that have university affiliations. Data for students is acquired when admitted applicants register to become students at the University through feeds from student systems. Data for employees is acquired through a feed from the Paymaster system. Data for other entities is acquired through special interfaces like Intensive English Institute feed, University foundation, McKinley Health Services feed.

In the future, the ICard system will continue to provide unique identification numbers for University employees, students and other entities like vendors, student spouses, and persons and non-persons that have university affiliations; at first through interfaces with existing systems which record new employees and new students, and later through a direct interface with Banner which will begin recording new students in June 2002 and new employees in October 2003.

Timeline: The Paymaster data changes must continue to be propagated to ICard using current batch processes until December 2001. Starting December 2001 Paymaster changes must begin to be reflected in ICard using the messaging technology. In June 2002 when Banner admissions module is implemented and new applicants are added to Banner directly, there may be a new interface between Banner and ICard to generate the ids for admitted students. The Paymaster interface will continue until December 2003 when Paymaster is decommissioned and Banner completely assumes support of all HR and payroll functions at which point there may be a new interface with ICard.

Flow: Basic person and employee information from Paymaster flows to ICard. ICard presently maintains its own copy of person and employee information that is in paymaster for ICard’s own purposes. For example, ICard client applications have interfaces that look up address and phone number information. Presently, data does not flow back from ICard to Paymaster. ICard receives similar feeds from campus student systems. Similarly, ICard maintains an image of that data as it appears in those systems.

1.2. List the current application interfaces for the application named in the template that synchronizes data changes made in other applications.

Only information for the current Paymaster to ICard interface is provided here, since the feeds from campus students systems, Intensive English Institute, University Foundation, and McKinley Health Services will continue until those systems are modified or retired.

1.2.1. Source application details:

Source Application Name:	Paymaster (This is the application named in the template)
Source Application Description:	The Paymaster system provides the essential HR and payroll functions for the University.
Source Data Structure: (repeat for each table or filename related to this interface)	Database Name: XXXXXXXX Table Name: XXXXXXXX File Name: PAYROLL_DAT
Source Field Name	Field type	Width	Nullable	Comments
Example LAST-NAME-10	CHAR	23	NO	The last name of a person in Paymaster
EXTERN_ID (SSN) Filler DEMOGRAPH.LAST_NAME Filler DEMOGRAPH.FIRST_NAME Filler DEMOGRAPH.MID_NAME Filler ADDRESS.ADDRESS_1 Filler ADDRESS.ADDRESS_2 Filler ADDRESS.CITY Filler ADDRESS.STATE Filler ADDRESS.ZIP_CODE Filler ADDRESS.MAIL_CODE Filler CAMPUS Filler DEMOGRAPH.BIRTHDATE Filler DEMOGRAPH.SEX Filler EMPLOYEE.HOME_DEPT Filler EMPLOYEE.EMP_GROUP Filler EMPLOYEE.EMP_STATUS Filler EMPLOYEE.APPT_TYPE Filler ADDRESS.PHONE Filler ADDRESS.ADDRESS_1 Filler ADDRESS.ADDRESS_2 Filler ADDRESS.CITY Filler ADDRESS.STATE Filler ADDRESS.ZIP_CODE Filler ADDRESS.PHONE Filler ADDRESS.SUPP_ADDR Filler ADDRESS.SUPP_PHONE		9* 1 23 1 15 1 15 1 25 1 25 1 16 1 3 1 5 1 3 1 1* 1 6 1 1 1 4 1 1 1 1 1 1 1 10 1 25 1 25 1 16 1 3 1 5 1 10 1 1 1 1		ADDR_TYPE = ‘LOCAL’ ADDR_TYPE = ‘WORK’ ADDR_TYPE=’WORK’ ADDR_TYPE=’WORK’ ADDR_TYPE=’LOCAL’ ADDR_TYPE=’LOCAL’

1.2.2. Target application details:

Target Application Name:	ICARD
Target Application Description:	Description already given for the Application named in the template.
Target Data Structure: (repeat for each table or filename related to this interface)	Database Name: ICARD Table Name: DEMOGRAPH
Target Field Name	Field type	Width	Nullable	Comments
SOURCE EXT_ID_TYP* EXTERN_ID* CAMPUS* NAME LAST_NAME FIRST_NAME MID_NAME PREF_NAME SUFF_NAME SEX BIRTHDATE TIME_STAMP REC_UPDATE	Char(10) Char(10) Char(16) Char(1) Varchar(31) Varchar(30) Varchar(30) Varchar(35) Varchar(10) Varchar(10) Char(1) Char(8) Timestamp Datetime	10 10 16 1 31 30 30 35 10 10 1 8	NO NO NO NO NO NO	YYYYMMDD
Target Data Structure:	Table Name: ADDRESS
Target Field Name	Field type	Width	Nullable	Comments
SOURCE* EXT_ID_TYP* EXTERN_ID* CAMPUS* ADDR_TYPE* ADDRESS_1 ADDRESS_2 ADDRESS_3 CITY STATE ZIP_CODE MAIL_CODE COUNTRY PHONE SUPP_ADDR SUPP_PHONE TIME_STAMP REC_UPDATE	Char(10) Char(10) Char(16) Char(1) Char(10) Varchar(30) Varchar(30) Varchar(30) Varchar(20) Char(3) Varchar(10) Varchar(6) Char(3) Varchar(25) Char(1) Char(1) Timestamp Datetime	10 10 16 1 10 30 30 30 20 3 10 6 3 25 1 1	NO NO NO NO NO NO NO	Home,Local,Work
Target Data Structure:	Table Name: EMPLOYEE
Target Field Name	Field type	Width	Nullable	Comments
SOURCE EXT_ID_TYP* EXTERN_ID* CAMPUS* HOME_DEPT EMP_GROUP EMP_STATUS APPT_TYPE TIME_STAMP REC_UPDATE	Char(10) Char(10) Char(16) Char(1) Char(4) Char(1) Char(1) Char(1) Timestamp Datetime	10 10 16 1 4 1 1 1	NO NO NO NO NO NO

1.2.3. How are the source inputs used to update the target application?

Target Field Name	Source Field Name	Transformation, formatting, and business rules for target
Table DEMOGRAPH
SOURCE EXT_ID_TYP* EXTERN_ID* CAMPUS* NAME LAST_NAME FIRST_NAME MID_NAME PREF_NAME SUFF_NAME SEX BIRTHDATE TIME_STAMP REC_UPDATE	Value “PAYROLL” EXTERN_ID (SSN) DEMOGRAPH.LAST_NAME DEMOGRAPH.FIRST_NAME DEMOGRAPH.MID_NAME DEMOGRAPH.SEX DEMOGRAPH.BIRTHDATE
Table ADDRESS
SOURCE* EXT_ID_TYP* EXTERN_ID* CAMPUS* ADDR_TYPE* ADDRESS_1 ADDRESS_2 ADDRESS_3 CITY STATE ZIP_CODE MAIL_CODE COUNTRY PHONE SUPP_ADDR SUPP_PHONE TIME_STAMP REC_UPDATE	Value “PAYROLL” EXTERN_ID (SSN) ADDRESS.ADDRESS_1 ADDRESS.ADDRESS_2 ADDRESS.CITY ADDRESS.STATE ADDRESS.ZIP_CODE ADDRESS.MAIL_CODE ADDRESS.PHONE ADDRESS.SUPP_ADDR ADDRESS.SUPP_PHONE	“Work” or “Home”
Table EMPLOYEE
SOURCE EXT_ID_TYP* EXTERN_ID* CAMPUS* HOME_DEPT EMP_GROUP EMP_STATUS APPT_TYPE TIME_STAMP REC_UPDATE	Value “PAYROLL” CAMPUS EMPLOYEE.HOME_DEPT EMPLOYEE.EMP_GROUP EMPLOYEE.EMP_STATUS EMPLOYEE.APPT_TYPE

1.3. List the interfaces that take data changes from the application named in the template to other existing applications.

[For each application, provide the name, description, Source data structure, target data structure and how the source data is used to update the target. Use the structure below for the first application and repeat for other applications. If not applicable indicate above by N/A.]

List of interfaces: None

1.3.1. Source application details:

Source Application Name:	This is the application named in the template
Source Application Description:	Description already given for the Application named in the template.
Source Data Structure: (repeat for each table or filename related to this interface)	Database Name: Table Name: File Name:
Source Field Name	Field type	Width	Nullable	Comments

1.3.2. Target application details:

Target Application Name:
Target Application Description:	(Brief description)
Target Data Structure: (repeat for each table or filename related to this interface)	Database Name: Table Name: File Name:
Target Field Name	Field type	Width	Nullable	Comments

1.3.3. How are the source inputs used to update the target application?

Target Field Name	Source Field Name	Transformation, formatting, and business rules for target

2. Step 2

Describe and define Banner data that may be involved in interfaces with the application named in this template. This information will also be used to help define enterprise data objects for use in message when design teams meet with AITS integration staff. This section should be completed prior to integration design meetings with AITS integration staff.

2.1. Describe the proposed business processes that the application named in the template will supports, how data will be acquired, the timeline and the proposed flow of data between applications. This should be a high-level description in plain English prose not to exceed one page of text. No charts or diagrams should be provided.

Description: With the implementation of Banner, the ICard system will continue to provide unique identification numbers for University employees and students; at first through interfaces with existing systems which record new employees and new students, and later through a direct interface with Banner which will begin recording new students in June 2002 and new employees in October 2003.

Basic person and admitted applicant information from Banner will flow to ICard to generate ids. Generated id information will flow from ICard to Banner.

Timeline: ICard to Banner interface will begin in June 2002 when Banner begins recording new students and the interface will continue indefinitely.

Flow: Basic person and admitted applicant information from Banner will flow to ICard to generate university ids. Generated id information will flow from ICard to Banner.

2.2. What Banner data will this application require?

[Provide the name, description, Banner data structure, target data structure, and how the Banner data will used to update the application named in the template. Use the structure below for each Banner table and Target table and repeat as needed. If not applicable indicate above by N/A.]

N/A

3. Step 3

Define (at a high level) the flow of messages between the application named in this template and other applications to support the interfaces defined in steps 1 and 2. This section should be completed during the integration design phase with AITS integration staff.

3.1. Application 1: ICard

4. ICard must field incoming University identity query and generate requests and send the appropriate replies.

5. ICard must consume basic person and basic employee synchronization messages to keep its support data current.

3.2. Application 2: Paymaster

3. As basic person and basic employee information changes in Paymaster, Paymaster issues synchronization messages to keep ICard up-to-date.

4. In order to produce basic person and basic employee synchronization messages, Paymaster must send University Identity query requests to ICard and handle the replies. For cases of new employees, Paymaster must send University ID number generation requests and handle the replies.

4. Step 4

List existing enterprise data objects that will be reused and new enterprise data objects that will be defined to support application interfaces for the application named in this template. This section should be completed during the integration design phase with AITS integration staff.

[Existing enterprise data objects are found in the SctSegments.dtd and UiSegments.dtd files.] These are available as part of the integration documentation at:

SctSegments and UiSegments

4.1 Existing enterprise object XML definitions that will be reused or modified. This section should include the current definition of the enterprise objects as they appear in the SCT and University of Illinois enterprise message repository at the time the analysis was performed and any proposed changes.

[List the enterprise objects to be reused or state ‘None’ if no objects are available]

3. UnknownPerson

4. Name

5. BasicPerson

6. Address

7. Phone

8. Email

9. BasicEmployee

10. EmploymentDates

11. EmploymentLeave

12. EmploymentTermination

File	Name	Proposed Definition
SctSegments	UnknownPerson	Original (as of 3/20/2001): <!ELEMENT UnknownPerson (SocialSecurityNumber?, Name, BirthDate, Gender)> Proposed: ELEMENT UnknownPerson (SocialSecurityNumber?, Name, BirthDate) <!ATTLIST UnknownPerson gender (Male \| Female \| Unknown) #REQUIRED > Note: we need to make SSN optional in UnknownPerson to support sync from ICard.
	BasicPerson	Original (as of 3/12/2001): <!ELEMENT BasicPerson (InstitutionalId, Name, SocialSecurityNumber?, BirthDate?, Gender, DeceasedDate?, Ethnicity, Address, Phone, Email)> <!ATTLIST BasicPerson citizen CDATA #IMPLIED citizenshipType CDATA #IMPLIED disabledVeteran CDATA #IMPLIED deceased CDATA #IMPLIED maritalStatus CDATA #IMPLIED vietnamService CDATA #IMPLIED > Proposed: <!ELEMENT BasicPerson (InstitutionalId, Name, SocialSecurityNumber?, BirthDate?, DeceasedDate?, Ethnicity, Address, Phone, Email)> <!ATTLIST BasicPerson citizen (Yes \| No) #IMPLIED citizenshipType CDATA #IMPLIED disabledVeteran (Yes \| No) #IMPLIED deceased (Yes \| No) #IMPLIED gender (Male \| Female \| Unknown) #REQUIRED maritalStatus (Married \| Single \| Divorced) #IMPLIED vietnamService (Yes \| No) #IMPLIED >
	Address	Original (as of 8/15/2001): <!ELEMENT Address (Street1?, Street2?, Street3?, CityOrLocality, County?, State?, Nation?, Zip?, EffectiveDate, TerminationDate?)> <!ATTLIST Address type CDATA #REQUIRED > Proposed: <!ELEMENT Address (Street1?, Street2?, Street3?, CityOrLocality, County?, State?, Country?, Zip?, EffectiveDate, TerminationDate?, Phone?)> <!ATTLIST Address type (Home \| Office \| Extension \| Other) #REQUIRED directory (Suppress \| Publish) #REQUIRED >
	Phone	Original (as of 12/15/2000): <!ELEMENT Phone (CountryCode?, PhoneArea?, PhoneNumber?, PhoneExtension?)> <!ATTLIST Phone type CDATA #REQUIRED phoneAddressType CDATA #IMPLIED > Proposed: <!ELEMENT Phone (CountryCode?, PhoneArea?, PhoneNumber?, PhoneExtension?)> <!ATTLIST Phone type (Home \| Office) #REQUIRED directory (Suppress \| Publish) #REQUIRED >

4.2 New enterprise data objects proposed. This section should include the proposed name and structure of the new data objects.

File

Name

Proposed Definition

SctSegments

InstitutionalIdentity

<!ELEMENT InstitutionalIdentity (InstitutionalId, UnknownPerson)>

Note that this definition will be extended in the future to include other entities besides people, for example UnknownVendor.

5. Step 5

5.1. Proposed Messages

[List proposed messages to be used in this interface or indicate that none are proposed for this interface.]

1. Person-InstitutionalIdentity-Create-Sync

2. Person-InstitutionalIdentity-Update-Sync

3. Person-InstitutionalIdentity-Delete-Sync

4. Person-InstitutionalIdentity-Provide-Reply

5. Person-InstitutionalIdentity-Response-Reply

5.2. Existing Messages

[List existing messages to be used in this interface or indicate that none are available for use.]

6. CoreMessaging-Sync-Error-Sync

7. Generic-Response-Reply

8. Person-InstitutionalIdentity-Generate-Request

9. Person-InstitutionalIdentity-Query-Request

10. Person-BasicPerson-Create-Sync

11. Person-BasicPerson-Update-Sync

12. Person-BasicPerson-Delete-Sync

13. Employee-BasicEmployee-Create-Sync

14. Employee-BasicEmployee-Update-Sync

15. Employee-BasicEmployee-Delete-Sync

6. Step 6

Name the existing messaging components that will be used or define the new messaging components that must be implemented to produce, consume, transform, and route the messages listed in step 5. This section should be completed during the integration design phase with AITS integration staff.

6.1. Existing Messaging Components

[List existing components to be used in this interface or indicate that none are available for use.]

6.2. New Messaging Components

Name	Type	Status	Responsible Unit
ICard Gateway	gateway	planned	OBFS and AITS
Paymaster Gateway	gateway	planned	AITS

7. Step 7.

For the messaging component(s) of the application named in this template, list the new messages that component must produce and consume and provide detailed stories describing the prescribed production and consumption logic. The owner of the application who is also responsible for implementing message production and consumption should prepare the detailed stories. This section should be completed during the integration design phase with AITS integration staff.

7.1. Messages

1. Person-InstitutionalIdentity-Create-Sync

2. Person-InstitutionalIdentity-Update-Sync

3. Person-InstitutionalIdentity-Delete-Sync

4. Person-InstitutionalIdentity-Provide-Reply

5. Person-InstitutionalIdentity-Response-Reply

6. CoreMessaging-Sync-Error-Sync

7. Generic-Response-Reply

8. Person-InstitutionalIdentity-Generate-Request

9. Person-InstitutionalIdentity-Query-Request

10. Person-BasicPerson-Create-Sync

11. Person-BasicPerson-Update-Sync

12. Person-BasicPerson-Delete-Sync

13. Employee-BasicEmployee-Create-Sync

14. Employee-BasicEmployee-Update-Sync

15. Employee-BasicEmployee-Delete-Sync

7.2. Message Production Logic

[Describe the message production logic and the XML format for each message that the application or gateway must produce.]

ICard modifications

The following stories assume that ICard data structures will be modified to store a complete, authoritative set of data that comprises an institutional identity. Presently, ICard stores almost all of this information required in its MAIN table with the following structure:

TABLE [dbo].[MAIN] (

[ID_NUM] [char] (16) NOT NULL ,

[CREAT_DATE] [datetime] NOT NULL ,

[DATA_CHNGD] [datetime] NOT NULL ,

[DATA_DEACT] [datetime] NULL ,

[CARD_ISSUE] [datetime] NULL ,

[CARD_CHNGD] [datetime] NULL ,

[CARD_EXPIR] [datetime] NULL ,

[CARD_SEQ] [char] (2) NULL ,

[PASS_NUM] [char] (4) NULL ,

[BAR_CODE] [char] (14) NULL ,

[MAG_STRIPE] [char] (28) NULL ,

[IMAGE_PATH] [char] (8) NULL ,

[BADGE_TYPE] [char] (2) NULL ,

[TIME_STAMP] [timestamp] NOT NULL ,

[LOGN_TRIES] [int] NOT NULL ,

[UI_TEMP_PIN] [varchar] (255) NULL ,

[UI_PERM_PIN] [varchar] (255) NULL ,

[UI_PERM_PASSWORD] [varchar] (255) NULL ,

[FIRST_NAME] [varchar] (30) NOT NULL ,

[MID_NAME] [varchar] (35) NOT NULL ,

[LAST_NAME] [varchar] (30) NOT NULL ,

[BIRTHDATE] [char] (8) NULL ,

[OCP_QUESTION_A] [int] NULL ,

[OCP_ANSWER_A] [varchar] (255) NULL ,

[OCP_QUESTION_B] [int] NULL ,

[OCP_ANSWER_B] [varchar] (255) NULL

)

Of these attributes, the following are part of an institutional identity:

[ID_NUM] [char] (16) NOT NULL ,

[FIRST_NAME] [varchar] (30) NOT NULL ,

[MID_NAME] [varchar] (35) NOT NULL ,

[LAST_NAME] [varchar] (30) NOT NULL ,

[BIRTHDATE] [datetime] (8) NULL

The following three attributes complete an institutional identity and are presently lacking in the ICard MAIN table. These will be added to the MAIN table or a related table, and ICard will be modified to populate and maintain these attributes with appropriate data.

[CURRENT_SSN] [char] (16) NULL,

[GENDER] [char] (1) NULL ,

[NAME_PREFIX] [varchar] (10) NULL,

[NAME_SUFFIX] [varchar] (10) NULL

Once these modifications have been made to ICard, all message consumption and production logic should be able to operate on the authoritative copy of the institutional identity information in the MAIN table.

Summary

The ICard gateway must produce InstitutionalId provide replies and InstitutionalId response replies. It must also produce InstitutionalId create, update, and delete synchronization messages whenever a new institutional identity is generated, updated, or deleted by the ICard system. Like any application that consumes synchronization messages, the ICard gateway must also produce synchronization error messages to a standard error topic whenever it encounters errors applying changes from sync messages.

The ICard gateway will produce messages in XML format for each of the messages.

1. Person-InstitutionalIdentity-Create-Sync (Message DTD | Sample Message)

The ICard Gateway will generate this sync message whenever the ICard system generates a new institutional identity. Presently, new Institutional Identities are generated based on feeds from various sources including the Paymaster and Student systems and interactively at the ID centers. In the future new institutional IDs will also be generated when ICard consumes Person-InstitutionalId-Generate-Requests.

ICard will produce synchronization messages using the RDBMS Queue Table method in conjunction with a polling message producer.

The ICard Gateway must produce this message in the XML format specified in the message DTD.

Data Area Element values: (see SctSegments for all the elements)

The DataArea/NewData element is a complex object with the DTD

<!ELEMENT NewData (InstitutionalIdentity)>

The DataArea/NewData/InstitutionalIdentity/InstitutionalId element value is taken from the ICard MAIN.ID_NUM field. In ICard the ID_NUM field is a 16 character field but always contains a 9 digit numeric id in the first 9 positions and no translation is needed.

The DataArea/NewData/InstitutionalIdentity/UnknownPerson element is a complex object with the DTD

<!ELEMENT UnknownPerson (SocialSecurityNumber, Name, BirthDate, Gender)>

The UnknownPerson/SocialSecurityNumber element value is taken from the ICard MAIN.CURRENT_SSN field. The SocialSecurityNumber element must be nine numeric digits. MAIN.CURRENT_SSN is optional in ICard.

The UnknownPerson/Name element is a complex object with the DTD

<!ELEMENT Name (LastName, FirstName?, MiddleInitial?, Prefix?, Suffix?)>

<!ATTLIST Name

current CDATA #IMPLIED

UnknownPerson/Name@current will take the value “Yes”.

UnknownPerson/Name/LastName value is taken from the ICard MAIN.LAST_NAME field. In ICard this data should always be present. If no LAST_NAME is present in ICard, then a message cannot be produced since UnknownPerson/Name is required. In ICard it may be formatted in all upper case or in mixed case. In the enterprise message, LastName should be formatted in mixed case using the scrubbing algorithm implemented as edu.uillinois.aits.enterprise.config.NameScrubber.

UnknownPerson/Name/FirstName value is taken from the ICard MAIN.FIRST_NAME field. In ICard this data should always be present. If no FIRST_NAME is present in ICard the message will not include this element, as it is optional. In ICard it may be formatted in all upper case or in mixed case. In the enterprise message, FirstName should be formatted in mixed case using the scrubbing algorithm implemented as edu.uillinois.aits.enterprise.config.NameScrubber.

UnknownPerson/Name/MiddleName value is taken from the ICard MAIN.MID_NAME field. In ICard this data is optional. If no MID_NAME is present in ICard the message will not include this element, since it is optional in the message as well. In ICard it may be formatted in all upper case or in mixed case. In the enterprise message, MiddleName should be formatted in mixed case using the scrubbing algorithm implemented as edu.uillinois.aits.enterprise.config.NameScrubber.

UnknownPerson/Name/Prefix value is taken from ICard MAIN.NAME_PREFIX. In ICard this data is optional. If no NAME_PREFIX is present in ICard,, the message will not include this element, since it is optional in the message as well. In ICard it may be formatted in all upper or in mixed case. In the enterprise message, Prefix should be formatted in mixed case using the scrubbing algorithm implemented as edu.uillinois.aits.enterprise.config.NameScrubber.

Current Suffixes in ICard

An SQL query of the ICard database provided the following list of suffixes:

MR.

MRS

JR.

- (there were 4 rows with this value)

III

Possible additional suffixes the NameScrubber should handle are:

MS.

MRS.

DR.

SR.

UnknownPerson/Name/Suffix value may be taken from the ICard MAIN.NAME_SUFFIX field. If no value for MAIN.NAME_SUFFIX is present in ICard, then the message will not include this element since it is optional. In ICard this data may be present and take values like Jr, Sr, etc. In ICard it may be formatted in all upper case or in mixed case. In the enterprise message, Suffix should be translated using valid values defined in EnterpriseFields.

The UnknownPerson/BirthDate element value is taken from the ICard MAIN.BIRTHDATE field. BIRTHDATE appears in date format. If the birthdate is unknown, MAIN.BIRTHDATE will be null in ICard. In the enterprise message, the BirthDate should appear as an appropriately parsed XML date with a month in the range from 1-12, and a day in the range from 1-31 and a four digit year.

UnknownPerson/Gender value will be taken from the ICard MAIN.GENDER field. In ICard this data is generally present and takes values of Male, Female, Unknown, or null. In other words, since MAIN.GENDER is a new attribute in ICard, it will have the enterprise values.

2. Person-InstitutionalIdentity-Update-Sync (Message DTD | Sample Message)

The ICard Gateway will generate this sync message whenever the ICard system updates an institutional identity. Presently, Institutional Identities information is updated by backend matching cleanup processes, when name changes and such occur in Paymaster or students systems that feed ICard, and through on-line modification of ICard data using ICard clients. See message production logic for item 1 above. Note that the update sync message must include a Baseline InstitutionalIdentity and a new InstitutionalIdentity object.

3. Person-InstitutionalIdentity-Delete-Sync (Message DTD | Sample Message)

The ICard Gateway will generate this sync message whenever the ICard system deletes an institutional identity. Presently, Institutional Identities are deleted by backend matching cleanup processes and through on-line modification of ICard data using ICard clients. See message production logic for item 1 above.

4. Person-InstitutionalIdentity-Provide-Reply (Message DTD | Sample Message)

The ICard Gateway must produce this message in the XML format specified in the message DTD when it receives a query request.

Data Area Element values: (see SctSegments for all elements)

The DataArea element is a complex object with the DTD

<!ELEMENT DataArea (InstitutionalIdentity?)>

The DataArea/InstitutionalIdentity/InstitutionalId element value is taken from the ICard MAIN.ID_NUM field. In ICard the ID_NUM field is a 16 character field but always contains a 9 digit numeric id in the first 9 positions and no translation is needed. See the production logic for /DataArea/InstitutionalIdentity/UnknownPerson in item 1 above.

5. Person-InstitutionalIdentity-Response-Reply (Message DTD | Sample Message)

The ICard Gateway must produce this message in the XML format specified in the message DTD in response to a Person-InstitutionalIdentity-Generate-Request.

Data Area Element values: (see SctSegments for all elements)

The DataArea element is a complex object with the DTD

<!ELEMENT DataArea (InstitutionalIdentity?)>

6. CoreMessaging-Sync-Error-Sync (Message DTD | Sample Message)

Whenever the ICard gateway or application encounters an error consuming a synchronization message from Paymaster, it must produce a CoreMessagingSyncErrorSync with the appropriate error information.

7. Generic-Response-Reply (Message DTD | Sample Message)

ICard may produce this message in an error situation in response to a query or generate request from Paymaster (see page 56 of Analysis-Paymaster.doc). It XML format is:

Data Area Element values: (see SctSegments for all elements)

The DataArea for this message is a complex object with the DTD

<!ELEMENT CoreMessagingGenericResponse (ControlAreaReply)>

7.3. Message Consumption Logic

[Describe the message consumption logic and the XML format for each message that the application or gateway must consume.]

The ICard gateway must consume the InstitutionalIdentity generate and query requests and BasicPerson and BasicEmployee synchronization messages.

1. Person-InstitutionalIdentity-Generate-Request (Message DTD | Sample Message)

The ICard Gateway must consume this message in the XML format specified in the message DTD.

Data Area Element values: (see SctSegments for all elements)

The DataArea/InstitutionalIdentity element is a complex object with the DTD

<!ELEMENT InstitutionalIdentity (InstitutionalId, UnknownPerson)>

The DataArea/InstitutionalIdentity/InstitutionalId element contains the institutional ID number. For the purposes of the generate request, this will have a values of “Requested”.

The DataArea/InstitutionalIdentity/UnknownPerson object is a complex object with the DTD

<!ELEMENT UnknownPerson (SocialSecurityNumber?, Name, BirthDate, Gender)>

The formatting for UnknownPerson is the same as described above for message Person-InstitutionalIdentity-Create-Sync.

Consumption logic:

We will use a standard enterprise consumer to invoke application logic encapsulated in stored procedures.

Procedure Name: MSG_UIN_GEN_REQUEST

Arguments:

SOURCE CHAR(10)

SSN CHAR(9)

LASTNAME VARCHAR(30)

FIRSTNAME VARCHAR(30)

MIDNAME VARCHAR(35)

PREFIX VARCHAR(10)

SUFFIX VARCHAR(10)

BIRTHDATE DATE

GENDER CHAR(1)

Result Set:

STATUS text string with value success or failure

APP_ERROR_CODE text string with app-specific values to be defined

APP_ERROR_DESCRIPTION text string with app-specific values to be defined

INSTITUTIONALID CHAR(9)

ICard should check to see if MAIN.ID_NUM for the UnknownPerson/SocialSecurityNumber exists for the message. If it does then it is an application error and failure. It returns an error telling that it cannot generate since the institutional id already exists for this SocialSecurityNumber.

If no MAIN.ID_NUM exists for the UnknownPerson/SocialSecurityNumber then ICard will generate a new InstitutionalIdentity for the UnknownPerson. Note that this behavior must be modified prior to phase 2. This approach works for phase I because PersonInstitutionalIdentityGenerateRequests are only being produced for Employees for whom we have SSNs.

Then ICard must:

1. Generate the institutional ID number and provide the result set.

2. Update the ICard database by storing the generated institutional ID number in MAIN.ID_NUM. It must store the SocialSecurityNumber in EXTERN_ID.EXTERN_ID and MAIN.CURRENT_SSN. It must store the other fields in the MAIN table as SocialSecurityNumber in MAIN.EXTERN_ID, LastName in LAST_NAME, FirstName in FIRST_NAME, MiddleName in MID_NAME, Prefix in PREF_NAME, Suffix in SUFF_NAME, BirthDate in BIRTHDATE and Gender in SEX.

3. For every new Identity generation it must also generate a Person-InstitutionalId-Create-Sync message (detailed description is in another section). The sync message must be added to the message queue table for this integration.

2. Person-InstitutionalIdentity-Query-Request (Message DTD | Sample Message)

The ICard Gateway must consume this message in the XML format specified in the message DTD.

Data Area Element values: (see SctSegments for all elements)

The DataArea element is a complex object with the DTD

<!ELEMENT DataArea (UnknownPerson)>

The DataArea/UnknownPerson object is a complex object with the DTD

<!ELEMENT UnknownPerson (SocialSecurityNumber, Name, BirthDate, Gender)>

The formatting for UnknownPerson is the same as described above for message Person-InstitutionalIdentity-Create-Sync.

Consumption logic:

We will use a standard enterprise consumer to invoke application logic encapsulated in stored procedures.

Procedure Name: MSG_UIN_QUERY_REQUEST

Arguments:

SOURCE CHAR(10)

SSN CHAR(9)

LASTNAME VARCHAR(30)

FIRSTNAME VARCHAR(30)

MIDNAME VARCHAR(35)

PREFIX VARCHAR(10)

SUFFIX VARCHAR(10)

BIRTHDATE DATE

GENDER CHAR(1)

Result Set:

STATUS text string with value success or failure

APP_ERROR_CODE text string with app-specific values to be defined

APP_ERROR_DESCRIPTION text string with app-specific values to be defined

INSTITUTIONALID CHAR(9)

ICard should check to see if MAIN.ID_NUM for the UnknownPerson/SocialSecurityNumber exists for the message. If it does then a match has been found and it must produce a Person-InstitutionalId-Provide-Reply message (detailed description is in another section).

If no MAIN.ID_NUM exists for the Unknown/SocialSecurityNumber then ICard it is an application error and failure. It returns an error telling that it cannot provide the institutional id for this SocialSecurityNumber. Note that this behavior must be modified prior to phase 2. This approach works for phase I because PersonInstitutionalIdentityGenerateRequests are only being produced for Employees for whom we have SSNs.

OpenEAI Methodology

Contents

Introduction

Methodology Overview

Perform Analysis

Define Messages

Generate Message Objects and Related Artifacts

Develop, Document, and Test Messaging Applications

Update Enterprise Documentation Artifacts

Deploy in Production

Tracking Progress along the Way

Methodology Details: The OpenEAI Integration Template

Overview:

Step 1: Describe Existing Integrations

XXXXXXXX

Source Field Name

Field type

Nullable

Comments

Target Field Name

Field type

Nullable

Comments

Source Field Name

Field type

Nullable

Comments

Target Field Name

Field type

Nullable

Comments

Step 2: Describe Data Involved in Proposed Integrations

Source Field Name

Field type

Nullable

Comments

Target Field Name

Field type

Nullable

Comments

Source Field Name

Field type

Nullable

Comments

Target Field Name

Field type

Nullable

Comments

Step 3: Describe the Flow of Data in the Proposed Integrations

Step 4: List Existing and New Enterprise Data Objects Required for the Integrations

Step 5: Name the Messages that Will Be Used to Implement the Integrations

Step 6: Name the Existing and New Messaging Applications Required

Step 7: Provide Technical Stories for the Primary Application

Enterprise Object Element / Attribute

Source Database Table

Example Paymaster Table

Source Database Field and transformations

Example Paymaster Field

UnknownPerson

Enterprise Object Element / Attribute

Source Database Table

Source Database Field and transformations

Enterprise Object Element / Attribute

Target Database Table

Target Database Field and transformations

Enterprise Object Element / Attribute

Target Database Table

Target Database Field and transformations

Step 8: Provide Technical Stories for the other Applications Named in the Template

Step 9: Summarize all Outstanding Questions, Issues, and Action Items

Step 10: Perform Work Estimation and Scheduling

Step 11: Functional Approval of Analysis, Scope, and Scheduling

Step 12: Initiate Template Change Control Processes

Change Request Number:

[Provide story here]

12.8 Message Object changes:

Step 13: Provide Testing Specifications

Step 14: Develop and Test Integrations

Step 15: Prepare Implementation and Rollout Plan

Step 16: Implement in Production