Integration Specification

PENNSYLVANIA DEPARTMENT OF PUBLIC

WELFARE

<System <Name>
Integration Specification

Version 1.0 <Page 1 of 14>

 <System Name>
Integration Specification

<System Name>
Integration Specification

<Version #>

<Page 2 of 14>
 <System Name>
Integration Specification

Revision History
Date Version Description Author

<Page 3 of 14>
 <System Name>
Integration Specification

Table of Contents

1. INTRODUCTION............................................................................................................................ 3
2. <APPLICATION SUBSYSTEM>......................................................................................................... 3
2.1 <WEB SERVICE NAME 1> TECHNICAL ASSUMPTIONS...............................................................................3
2.2 <WEB SERVICE NAME 1> BUSINESS RULES............................................................................................3
2.3 INTERFACE DESCRIPTION......................................................................................................................3
2.4 INTERFACE FREQUENCY AND SCHEDULE..................................................................................................3
2.5 MESSAGE DETAILS..............................................................................................................................3
2.6 DATA MAPPING AND TRANSFORMATION RULES......................................................................................3
2.7 INTEGRATION INTERFACE DESIGN..........................................................................................................3
2.7.1 Flowchart..................................................................................................................................3
2.7.2 Design time components..........................................................................................................3
2.7.3 Global Variables.......................................................................................................................3
2.7.4 Database Queries.....................................................................................................................3
2.7.5 Class diagram...........................................................................................................................3
2.7.6 Exception Rules.........................................................................................................................3
2.7.7 Adapters...................................................................................................................................3
2.7.8 Integration Standard................................................................................................................3
2.8 PERFORMANCE SPECIFICATIONS............................................................................................................3
2.9 AUDIT SPECIFICATIONS........................................................................................................................3
2.10 LOGGING SPECIFICATIONS....................................................................................................................3
2.11 SYSTEM SPECIFICATIONS......................................................................................................................3

<Page 4 of 14>
 <System Name>
Integration Specification

1. Introduction
[The purpose of this document is to detail the design of all the web services
created for an application by subsystem. It is to include all the design and
implementation time components for integration such as interfaces exposed by
the web services to the end systems, business and validation rules,
transformation rules, data field mappings and implementation logic.
The integration design specification is used to translate what needs to be
developed into how an integration interface will be developed for each of the web
services.

Also, provide a summary of the document highlighting the key points in each
section, if applicable.]

<Page 5 of 14>
 <System Name>
Integration Specification

2. <Application
Subsystem>
[This section is intended to be repeated for as many application subsystems
within an application that contain web services. Further, each section is to be
elaborated with the design details for each web service within that subsystem. ]

2.1 <Web Service Name 1> Technical Assumptions

[This section documents any technical assumptions made during the design and
implementation of this web service for this subsystem.]

Sr No Assumption Comments
<No> <Document the assumptions made during <Document the comments to provide additional
the design and implementation of the sub- details if any>
systems
Example: The end system will search and
return data only for current active employees
and no other employees will be searched.>

Table 1: Technical Assumptions

2.2 <Web Service Name 1> Business Rules

[This section describes the business events and rules that trigger the web
service to perform an action. The interfaces exposed by the integration
subsystem to implement the business flow are defined. The message elements
critical to implement the business functionality and the business logic
implemented by the interface to implement the business rule is documented.
Refer them to the business Rules Specification for the details of the rules.]

The table below provides a high level description only. These rules are at a field
level.

Requireme Business Rule Description Interface Message name Business

nt # Rule Name Logic
Description
<req id> <Event Name <Description> <Interface <Business <Describe the
name Object Name or business logic
Example: Example: Data element to be
Example: implemented
The Employee The employee Example:
should be should exist in searchEmplo by the
active to the current yee_Active > Employee integration sub-
perform the employee Business Object system
required database to be > Example:
functionality> eligible.
Retrieve the
employee first

<Page 6 of 14>
 <System Name>
Integration Specification

Requireme Business Rule Description Interface Message name Business

nt # Rule Name Logic
Description
name and last
name from the
message and
search in the
Employee
database. If the
Employee flag
is set to
“Active”, then
retrieve the
employee
address and
send an email
notification to
xxxx. >

Table 2: Business rules

2.3 Interface Description

[This section describes the interfaces exposed by the integration sub-system to
all the end systems in order to implement the required business functionality.
The business functionality performed on the interface invocation including any
post and pre conditions that should be met when the interface is invoked are
documented.]

Interface Name Actors Involved Context goal Preconditions Post conditions

<Interface <Document the <Document the <Document any <Document any post
name end systems and functionality preconditions for the conditions performed
any other actor performed by interface after the interface
Example: using the the interface> successfully completes
searchEmploye interface Example: the business
e_Active > Example: The Portal end system functionality
Example: makes a web-service call
The interface Example:
Siebel fetches all the and populates all the
active request data. > An email notification is
Portal employees sent to Siebel after
SQL Server > based on successful execution of
request the search query in SQL
parameters> Server.>

Table 3: Interface details

2.4 Interface Frequency and Schedule

[This section describes the frequency and schedule for the invocation of the
interface for the integration sub-system.]

Immediate (real-time)
On demand

<Page 7 of 14>
 <System Name>
Integration Specification

Hourly Day: ___________ Time: ___________ Push/Pull: ___________

Daily Day: ___________ Time: ___________ Push/Pull: ___________
Weekly Day: ___________ Time: ___________ Push/Pull: ___________
Monthly Day: ___________ Time: ___________ Push/Pull: ___________
Quarterly Day: ___________ Time: ___________ Push/Pull: ___________
Annually Day: ___________ Time: ___________ Push/Pull: ___________
Other Day: ___________ Time: ___________ Push/Pull: ___________

2.5 Message details

[This section documents the details of the message exchanged between the
integration sub-system interfaces and the end system. The messages may
contain business objects and/or data elements used by the interface to
implement the business functionality for the integration sub-system. This section
describes the operations performed on the message elements and any validation
rules performed on the messages when they are received by the interface of the
integration sub-system. The XML schema files (xsd) used to define the message
structure for XML based messages document are documented.]

Interface Message Message Request / Operation Validation Rule

Name Name element Response performed
(select /insert
/delete /update)
<Interface <Business <Messag <Select <Select <Describe the
name Object Name e element appropriate appropriate validation
or data name option option based on performed on the
Example: element grouped depending on the actions message data
searchEmploye name within the whether the performed on the
e_Active > Business message is used data element Example:
Example: Object for request or within the Example: Check
Employee response within interface if
Example: the interface
Business FirstNam Employee.FirstN
Object > e> Example: ame is not NULL
Example: >
Request >
Select, Update >

Table 4: Message details

2.6 Data Mapping and Transformation Rules

[This section describes the integration sub-system (source) and end system
(target) messages such as the message element names, data type, date length
and a description about the business purpose of the message element within the
sub-system. Further the source and target sub-system message elements are
mapped to each other and appropriate transformation rules are applied to clearly
ensure that the message elements retain the business definitions as defined
within the respective systems. The source and target messages are also
mapped to the canonical model (if one exists) and appropriate transformation
rules are applied to ensure that the business definitions of the messages are
retained.]

<Page 8 of 14>
 <System Name>
Integration Specification

The table below lists the message elements for the integration sub-system
(source) and documents the message element name, description of its purpose
within the sub-system, the data type and length.
Field Name Description Type Length (if applicable)
<Field Name> <Describe the use of the <Select data type <If the field is of numeric type,
field> for the field> document the length of the field>
Example: Example: Example:
Example:
Contains the first name of String NA
Employee.FirstName the employee

Table 5: Source Message

The table below lists the message elements for the end system (target) and
documents the message element name, description of its purpose within the sub-
system, the data type and length.
Field Name Description Type Length (if applicable)
<Field Name> <Describe the use of the <Select data type <If the field is of numeric type,
field> for the field> document the length of the field>
Example: Example: Example:
Example:
Contains the first name and Char 100
Name last name delimited by
space

Table 6: Target Message

The table below lists the message elements for the canonical model that is used
within the interface and documents the message element name, description of its
purpose within the sub-system, the data type and length.
Field Name Description Type Length (if applicable)
<Field Name> <Describe the use of the <Select data type <If the field is of numeric type,
field> for the field> document the length of the field>
Example: Example: Example:
Example:
Contains the first name and Char 100
Name last name delimited by
space

Table 7: Canonical Message

The table below lists the Source message to Target message mapping details
including any transformation logic that has to be applied during the message
exchange.

<Page 9 of 14>
 <System Name>
Integration Specification

Source System> Required (Y/N) <Target Required (Y/N) Mapping Logic

Data Element System>
Data
Element
<Field Name> <Flag> <Field <Flag> <Define any mapping rules
Name> between the two fields such
Example: Example: Example: as the change in format,
Example: default values etc>
Employee.FirstNam Y Y
e Name Example:
Concatenate or Segregate
Employee.FirstName into
Name

Table 8: Source to Target Message mapping

The table below lists the Source message to Canonical message mapping details
including any transformation logic that has to be applied during the message
exchange.
<Source System> Canonical Data Mapping Rule Cross Reference Notes
Data Element Element Details (if any)
<Field Name> <Field Name> <Define any <Define any cross <Provide any
mapping rules reference rules comments as
Example: Example: between the two such as checking required>
Employee.FirstNam Person.FirstNam fields such as the the timezone field
e e change in format, before inserting the
default values etc> time values,
checking the
Example: country field before
One to one mapping inserting currency
between values etc >
Employee.FirstNam Example:
e and
Person.FirstName Check that
Employee.LastNam
e is not NULL

Table 9: Source to Canonical Message mapping

The table below lists the Canonical message to Target message mapping details
including any transformation logic that has to be applied during the message
exchange.
Canonical Data <Target System> Mapping Rule Cross Reference Notes
Element Data Element Details (if any)
<Field Name> <Field Name> <Define any <Define any cross <Provide any
mapping rules reference rules such comments as
Example: Example: between the two as checking the required>
Person.FirstNam Name fields such as the timezone field before
e change in format, inserting the time
default values values, checking the
etc> country field before
inserting currency

<Page 10 of 14>
 <System Name>
Integration Specification

Canonical Data <Target System> Mapping Rule Cross Reference Notes

Element Data Element Details (if any)
Example: values etc >
Concatenate or Example:
Segregate
Person.FirstNam Check that
e into Name Person.LastName is
not NULL

Table 10: Canonical to Target Message mapping

2.7 Integration Interface design

[This section provides details on the business logic implemented by the interface,
the components of this interface that are called into action and in what order the
components are invoked. This section also describes any external components
that are triggered by the interface.]

2.7.1 Flowchart
[This section gives a detailed description of the implementation logic within the
interface.]

<Insert a graphic of the intended flowchart. This will most likely be a Visio
diagram or a graphic created in a word processing tool.>
igure 1: <Insert the title of the figure>

2.7.2 Design time components

[This section describes any design time components or libraries that are used to
implement the business logic of the integration sub-system.]

2.7.3 Global Variables

[This section describes any global variables that are used within the interface to
implement the business functionality.]

Global Variable Value Description

<Name> <Value> <Give a description about the usage of the variable>

Table 11: Global Variables

2.7.4 Database Queries

[This section documents the any SQL queries that are used by the interface to
retrieve or insert data in the database.]

<Page 11 of 14>
 <System Name>
Integration Specification

2.7.5 Class diagram

[This section provides a class diagram for any custom programming required for
the interface.]

2.7.6 Exception Rules

[This section documents the any exceptions that that should be logged by the
interface when an error is encountered by the interface.]

Exception Rule Exception Id Description

<Exception Rule> <Value> <Give a description about the usage of the
variable>
Example: Example:
Example:
The interface throws an Duplicate_Employee: 1234
exception when there are Duplicate entries found in Employee
multiple entries for the database
same employee in the
database

2.7.7 Adapters
[This section provides a description of the adapters used by the within the
integration sub-system such as database adapter, email adapter, adapter for
proprietary tools etc.]

Adapter Name Description

<Adapter Name> <Give a description about the usage of the adapter>
Example: Example:
Email adapter This adapter is used to configure the email server and send email notifications.

Table 12: Adapters

2.7.8 Integration Standard

Includes: security, hosting, transactions, bindings and transport

Hosting = within IIS, windows service, AppFabric, etc.

Binding and transport = HTTPS, MSMQ, named pipes, NetTCP, etc.
Transactions= two phase commits or not, etc. If using, what transaction
standards, like WS-transactions
Security = NTLM, tokens, etc.]
Table 13:

2.8 Performance specifications

[This section documents the performance parameters that the interface should
meet and the corresponding values. The performance requirements are defined

<Page 12 of 14>
 <System Name>
Integration Specification

as part of the non-functional requirements Software Requirements Specification

(SRS). The performance requirements capture parameters such as expected
normal/peak frequency of the interface, response time, data load etc.]

Performance Values Comments

Parameter
<parameter <Value> <Describe comments if any>
name>
Example:
Example:
2 secs
Response time

Table 14: Performance specifications

2.9 Audit specifications

[This section documents the transaction data that needs to be have an audit
entry as defined in the business requirements.]

Audit Parameter Values Comments

<parameter name> <Value> <Describe comments if any>
Example: Example: Example:
Employee.FirstName xxxxx The request message containing the employee name
is inserted in the audit history table.

Table 15: Audit specifications

2.10 Logging specifications

[This section documents the fields to be logged and the level of logging. This
helps log the functionality as it gets executed within the sub-systems and is
useful to debug any issues by checking the log files. The logging framework is
defined as part of the common services framework defined in the design
approach.]

Logging Parameter Values Comments

<parameter name> <Value> <Describe comments if any>
Example: Example:
Employee.FirstNam Received data
e successfully
from Portal:
<firstname>

Table 16: Logging specifications

2.11 System specifications

[This section documents the system parameters and the corresponding values
for the integration subsystem.]

<Page 13 of 14>
 <System Name>
Integration Specification

Environmen Location Logical Server Comments

t Name
<environment <location> <refer to BIS environment <Describe comments if any such as
name> configuration diagram for relative URL, port number etc>
the server name>
Example:
Example:
Portal
Production Client network
xxx

Table 17: System specifications

<Page 14 of 14>