Integration Specification

Version 1.0 <Page 1 of 14>

PENNSYLVANIA DEPARTMENT OF PUBLIC
WELFARE

<System <Name>
Integration Specification

<System Name>
Integration Specification


<Page 2 of 14>

<System Name>
Integration Specification

<Version #>
<System Name>
Integration Specification


<Page 3 of 14>

Revision History

Date Version Description Author



<System Name>
Integration Specification


<Page 4 of 14>


Table of Contents


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


<Page 5 of 14>

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



<System Name>
Integration Specification


<Page 6 of 14>

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
the design and implementation of the sub-
systems
Example: The end system will search and
return data only for current active employees
and no other employees will be searched.>
<Document the comments to provide additional
details if any>

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
nt #
Business Rule Rule
Description
Interface
Name
Message name Business
Logic
Description
<req id>

<Event Name
Example:
The Employee
should be
active to
perform the
required
functionality>
<Description>
Example:
The employee
should exist in
the current
employee
database to be
eligible.
<Interface
name
Example:
searchEmploy
ee_Active >

<Business Object
Name or Data
element
Example:
Employee
Business Object
>
<Describe the
business logic
to be
implemented by
the integration
sub-system
Example:
Retrieve the
employee first
name and last
name from the
message and
<System Name>
Integration Specification


<Page 7 of 14>

Requireme
nt #
Business Rule Rule
Description
Interface
Name
Message name Business
Logic
Description
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
name
Example:
searchEmploye
e_Active >

<Document the
end systems and
any other actor
using the
interface
Example:
Siebel
Portal
SQL Server >
<Document the
functionality
performed by
the interface>
Example:
The interface
fetches all the
active
employees
based on
request
parameters>
<Document any
preconditions for the
interface
Example:
The Portal end system
makes a web-service call
and populates all the
request data. >
<Document any post
conditions performed
after the interface
successfully completes
the business
functionality
Example:
An email notification is
sent to Siebel after
successful execution of
the search query in SQL
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
Hourly Day: ___________ Time: ___________ Push/Pull: ___________
Daily Day: ___________ Time: ___________ Push/Pull: ___________
<System Name>
Integration Specification


<Page 8 of 14>

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 Name Message
Name
Message
element
Request /
Response
Operation
performed
(select /insert
/delete /update)
Validation Rule
<Interface
name
Example:
searchEmploye
e_Active >

<Business
Object Name
or data
element
name
Example:
Employee
Business
Object >
<Messag
e element
name
grouped
within the
Business
Object
Example:
FirstNam
e >
<Select
appropriate
option depending
on whether the
message is used
for request or
response within
the interface
Example:
Request >
<Select
appropriate option
based on the
actions performed
on the data
element within the
interface

Example:
Select, Update >
<Describe the
validation
performed on the
message data
Example:
Example: Check if
Employee.FirstNa
me is not NULL >

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

<System Name>
Integration Specification


<Page 9 of 14>

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>

Example:
Employee.FirstName
<Describe the use of the
field>
Example:
Contains the first name of
the employee
<Select data type
for the field>
Example:
String
<If the field is of numeric type,
document the length of the field>
Example:
NA

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>

Example:
Name
<Describe the use of the
field>
Example:
Contains the first name and
last name delimited by
space
<Select data type
for the field>
Example:
Char
<If the field is of numeric type,
document the length of the field>
Example:
100

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>

Example:
Name
<Describe the use of the
field>
Example:
Contains the first name and
last name delimited by
space
<Select data type
for the field>
Example:
Char
<If the field is of numeric type,
document the length of the field>
Example:
100

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.
<System Name>
Integration Specification


<Page 10 of 14>

Source System>
Data Element
Required (Y/N) <Target
System>
Data
Element
Required (Y/N) Mapping Logic
<Field Name>
Example:
Employee.FirstName
<Flag>
Example:
Y
<Field
Name>
Example:
Name
<Flag>
Example:
Y
<Define any mapping rules
between the two fields such
as the change in format,
default values etc>
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>
Data Element
Canonical Data
Element
Mapping Rule Cross Reference
Details (if any)
Notes
<Field Name>
Example:
Employee.FirstName
<Field Name>
Example:
Person.FirstName
<Define any
mapping rules
between the two
fields such as the
change in format,
default values etc>
Example:
One to one mapping
between
Employee.FirstName
and
Person.FirstName
<Define any cross
reference rules such
as checking the
timezone field before
inserting the time
values, checking the
country field before
inserting currency
values etc >
Example:
Check that
Employee.LastName
is not NULL
<Provide any
comments as
required>

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
Element
<Target
System> Data
Element
Mapping Rule Cross Reference
Details (if any)
Notes
<Field Name>
Example:
Person.FirstName
<Field Name>
Example:
Name
<Define any
mapping rules
between the two
fields such as the
change in format,
default values
etc>
<Define any cross
reference rules such
as checking the
timezone field before
inserting the time
values, checking the
country field before
inserting currency
<Provide any
comments as
required>
<System Name>
Integration Specification


<Page 11 of 14>

Canonical Data
Element
<Target
System> Data
Element
Mapping Rule Cross Reference
Details (if any)
Notes
Example:
Concatenate or
Segregate
Person.FirstName
into Name

values etc >
Example:
Check that
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.>
Figure 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.]
<System Name>
Integration Specification


<Page 12 of 14>

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>
Example:
The interface throws an
exception when there are
multiple entries for the
same employee in the
database
<Value>
Example:
Duplicate_Employee: 1234

<Give a description about the usage of the
variable>
Example:
Duplicate entries found in Employee
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>
Example:
Email adapter
<Give a description about the usage of the adapter>
Example:
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
<System Name>
Integration Specification


<Page 13 of 14>

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
Parameter
Values Comments
<parameter
name>
Example:
Response time
<Value>
Example:
2 secs
<Describe comments if any>

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>
Example:
Employee.FirstName
<Value>
Example:
xxxxx
<Describe comments if any>
Example:
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>
Example:
Employee.FirstName
<Value>
Example:
Received data
successfully from
Portal:
<firstname>
<Describe comments if any>
Table 16: Logging specifications
2.11 System specifications
[This section documents the system parameters and the corresponding values
for the integration subsystem.]
<System Name>
Integration Specification


<Page 14 of 14>

Environment Location Logical Server Name Comments
<environment
name>
Example:
Portal
Production
<location>

Example:
Client network
xxx
<refer to BIS environment
configuration diagram for
the server name>
<Describe comments if any such as
relative URL, port number etc>
Table 17: System specifications