Methodology.doc
Copyright © 2005 OpenEAI Software Foundation.
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".
Contents
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:
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
XXXXXXXXXXXX
Location of Detailed Project Plan: XXXXXXXXXXXX
Template Change Reviewers: XXXXXXXXXXXX
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.
[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.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 | 1. Chris Analyst, analysis and test suite development (24 hours) 2. Suzy Developer, BasicPerson message support (12 hours) 3. Joe Developer, BasicEmployee message support (12 hours) Q.A. Masters, Test Suite Review and Certification (24 hours) | 72 |
10.2 List New Message Support to Add to Existing Messaging Applications and Summary Work Estimates
Messaging Application | Resources | Total Hours |
(Example) Identity Service | 1. Chris Analyst, analysis and test suite development (36 hours) 2. Suzy Developer, InstitutionalIdentity synchronization message support (20 hours) Q.A. Masters, Test Suite Review and Certification (24 hours) | 80 |
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: | 1 (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.13 $
$Date: 6/17/2009 3:38 PM$
$Source: /cvs/repositories/production/aits/www/openeai/content/doc/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.
[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.]
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:
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
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 AITS integration staff.
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.
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.
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.
MR
MS
MRS
DR
JR.
JR
- (there were 4 rows with this value)
SR
II
III
IV
V
VI
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.
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.
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.
The ICard Gateway must produce this message in the XML format specified in the message DTD when it receives a query request.
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.
The ICard Gateway must produce this message in the XML format specified in the message DTD in response to a Person-InstitutionalIdentity-Generate-Request.
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.
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.
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:
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.
The ICard Gateway must consume this message in the XML format specified in the message DTD.
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.
The ICard Gateway must consume this message in the XML format specified in the message DTD.
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.
The ICard Gateway must consume this message in the XML format specified in the message DTD.
The BasicPerson element is a complex object with the DTD
<!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
>
Consumption logic:
We will use a standard enterprise consumer to invoke application logic encapsulated in stored procedures MSG_PERSON_CREATE_SYNC, MSG_ADDRESS_SYNC, and MSG_PHONE_SYNC.
Procedure Name: MSG_PERSON_CREATE_SYNC
Arguments:
SOURCE CHAR(10)
INSTITUTIONALID CHAR(16)
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
Procedure Name: MSG_ADDRESS_CREATE_SYNC
Arguments:
SOURCE CHAR(10)
INSTITUTIONALID CHAR(16)
TYPE CHAR(10)
STREET1 VARCHAR(30)
STREET2 VARCHAR(30)
STREET3 VARCHAR(30)
CITY VARCHAR(20)
STATE CHAR(3)
ZIP VARCHAR(10)
COUNTRY CHAR(3)
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
Procedure Name: MSG_PHONE_CREATE_SYNC
Arguments:
SOURCE CHAR(10)
INSTITUTIONALID CHAR(16)
PHONE_TYPE CHAR(10)
PHONE VARCHAR(25)
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
The ICard Gateway must consume this message in the XML format specified in the message DTD.
The BasicPerson element is a complex object with the DTD
<!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
>
Consumption logic:
We will use a standard enterprise consumer to invoke application logic encapsulated in stored procedures.
Procedure Name: MSG_PERSON_UPDATE_SYNC
Arguments:
SOURCE CHAR(10)
INSTITUTIONALID_BASELINE CHAR(16)
INSTITUTIONALID CHAR(16)
LASTNAME VARCHAR(30)
FIRSTNAME VARCHAR(30)