"NBIA Connector" Software Design Document (SDD) - QI-Bench

NBIA Connector

SDD

Rev 0.1



BBMSC

1

of
16



NBIA Connector

Software Design Document


October 19, 2011

Rev
0.1






Required Approvals:

Author of this
Revision
:

Patrick Reynolds






System Engineer:

Andrew Buckler






Print Name


Signature


Date



Document Revisions:

Revision

Revised By

Reason for Update

Date

0.1

Patrick Reynolds

First Issue

10
-
19
-
2011


































NBIA Connector

SDD

Rev 0.1



BBMSC

2

of
16

Table of Contents

1.

EXECUTIVE SUMMARY

................................
................................
................................

3

1.1.

C
OMPONENT
D
ESCRIPTION AND
P
URPOSE

................................
................................
.............

3

1.2.

S
COPE

................................
................................
................................
................................
....

3

1.3.

P
LATFORM
D
ETAILS

................................
................................
................................
..............

3

1.4.

R
EFERENCED
S
TANDARDS

................................
................................
................................
.....

3

2.

DEFINITIONS

................................
................................
................................
....................

4

3.

COMPONENT
-
LEVEL REQUIREMENTS

................................
................................
...

4

3.1.

F
UNCTIONALITY

................................
................................
................................
....................

4

3.2.

P
ERFORMANCE
................................
................................
................................
.......................

5

3.3.

D
EFERRED
R
EQUIREMENTS

................................
................................
................................
....

5

4.

PLATFORM SPECIFIC MO
DEL

................................
................................
....................

5

4.1.

O
VERVIEW

................................
................................
................................
.............................

5

4.2.

A
SSUMPTIONS AND
D
EPENDENCIES

................................
................................
.......................

6

4.3.

C
OMPONENT
I
NTERFACE

................................
................................
................................
........

7

4.3.1. Interface Model

................................
................................
................................
..............

7

4.3.2. Operations Details for
<Interface Name>

................................
............................

8

4.4.

M
ESSAGE
I
NFORMATION
M
ODEL

................................
................................
...........................

9

4.4.1. Information Model
................................
................................
................................
..........

9

4.4.2. Information Model Description

................................
................................
......................

9

4.5.

S
ERVICE
I
NTERACTIONS

................................
................................
................................
.........

9

4.5.
1. Actors

................................
................................
................................
...........................

10

4.5.2. Interaction Details
................................
................................
................................
........

10

4.6.

I
MPLEMENTATION
C
ONSIDERATIONS

................................
................................
...................

11

4.6.1. Security

................................
................................
................................
.........................

11

4.6.2. Auditing

................................
................................
................................
........................

13

4.6.3. Priva
cy

................................
................................
................................
.........................

14

4.6.4. Error Handling

................................
................................
................................
.............

14

4.7.

D
EPLOYMENT
D
ETAILS

................................
................................
................................
........

15

4.8.

C
ONSTRAINTS

................................
................................
................................
......................

16

NBIA Connector

SDD

Rev 0.1



BBMSC

3

of
16

1.

Executive Summary

1.1.

Component

Description and Purpose

Provide the overall description of the
component

and its intended purpose.

1.2.

Scope

Describe the overall scope of the
component
. Define all the functionality that this
particular implementation of the
component

provides.

1.3.

Platform Details

Provide

the
implementation platform selected for
the
component

and also provide the
rationale behind
choosing it
.
Examples of
Component

Implementation can be Java EJB
Service, Web Service, RESTful Service, Grid(caGrid) Service, etc
.

1.4.

Referenced Standards

Provide references to the standards as well as technical standards that
component

is
using.


E.g.

S
ta
ndards such as
-

HL7V3, BRIDG2.1, ISO 21090 Data types

Domain
Standards

Description

BRIDG v2.1


HL7v3


ISO 21090


…….


……..



Technology
Standards such as

SOAP 1.1, Http, Https, SAML

Technology
Standards

Description

SOAP 1.1

Simple Object Access Protocol ver 1.1 is used
to interact with the
component

SAML v2.0

Simple Assertion Markup Language ver2.0 will
be used for security related data



…….


NBIA Connector

SDD

Rev 0.1



BBMSC

4

of
16

……..


2.

Definitions

The following are terms commonly used that may of assistance

to the reader.

xxx

Def xxx.


3.

Component
-
level Requirements

Note that, the normal process of requirements development does not guarantee that
adjacent requirements are directly related. In situations where requirements are tightly
related or where
requirements are to be considered in the context of an upper level
requirement, explicit parent
-
child relationships have been created. These can be
identified by the requirement numbering
–

child requirements have numbers of the form
XX.Y indicating the Y
th

child of requirement XX.

The following list of attributes is used:



Origin
–

Identifies the project or Enterprise Use Case that originated the
requirement.



Component
–

Identifies all Enterprise Use Case/project components to which the
requirement applie
s.



Comment / TI
–

Additional information regarding the requirement. This may
include information as to how the requirement may be tested (i.e. the test
indication).



Design Guideline
–

Used to identify requirements that are to be taken as
guidance or are
otherwise not testable. In such cases the phrase “Not a testable
requirement” will appear.

Requirements may, and often do, apply to multiple components. In such cases, the
Component attribute will identify all components where the requirement applies
(in
cluding components that do not apply to this Enterprise Use Case).

The Origin of a requirement is intended to identify the application for which the
requirement was originally defined.

3.1.

Functionality

Functional requirements.

Requirements

Origin

Comment / TI

Design
Guideline

Do such and such




Do something else




Integrate the two




NBIA Connector

SDD

Rev 0.1



BBMSC

5

of
16

Requirements

Origin

Comment / TI

Design
Guideline

X




Y












3.2.

Performance

Non
-
functional requirements, such as how fast a capability needs to run.

Requirements

Origin

Comment / TI

Design
Guideline

























3.3.

Deferred Requirements

Defined but not yet staged for implementation.

Requirements

Origin

Comment / TI

Design
Guideline

















4.

Platform Specific Model

4.1.

Overview

Provide Technical overview of the platform. This includes the Domain Model and
includes technology stack. This information can be a reference to a separate document
if a number of
component
s comply with the same platform.

E.g.

Domain Model

All COPPA serv
ices comply to a given implementation model of BRIDG, HL7V3, ISO
21090 data types

NBIA Connector

SDD

Rev 0.1



BBMSC

6

of
16


Domain Model

Description

NCI’s
Implementation
of ISO 21090
Data types

The
component

specifications will be based on
NCI’s restricted implementation of ISO 21090
data types







…

…


Technology Stack

Specify what technology stack is used to access the
component
.

Only interface
-
specific
technologies should be described here.

Technology

Affects

Globus
Toolkit 4.1

GTK is used to develop this WSRF complaint
grid service

Tomcat 5.x

Tomcat server will be used to deploy this
service





…

…


4.2.

Assumptions and Dependencies

This section enumerates any assumptions made in this specification as well as any
dependencies.


Assumptions can include deployment environment constraints such as network
connectivity, lack of firewalls etc.

Assumptions

Affects

Component

will be deployed
in its individual container

A new separate server needs to
be procured for each of the
component

installations

Component

will deployed in
the DMZ

Institutional Network team
needs to ensure this is
possible

NBIA Connector

SDD

Rev 0.1



BBMSC

7

of
16



…

…


Dependencies can include external components such as the caGrid Production
environment, other
component
s. This section can
include both business as well as
technical dependencies

Dependency

Description

caGrid Production
Environment

Component

relies on caGrid Production
environment for advertisement and
discovery

Subject Registry
Service

Uses the Subject Registry Service to
retrieve additional subject information





…

…


4.3.

Component

Interface

This section should provide details of the
component

interface
s implemented by this
specification
. A UML model with details of the main entry point of the
component

should
be included. The content would depend on the technology binding used for this model.
For example for a
component

implemented as java API, this could be the UML model
showing the main java interfaces. For a web service this could show the service po
rt
type. For a web application implementation this should include screen shots. Details of
the major
component

interfaces should be presented as part of this section such as java
interface, WSDL portTypes.

4.3.1.

Interface Model

This section is a placeholder for
an overall description of the interface
s implemented
.

Implemented
Interface No.

Supported
Interface Name

Interface Description

Link

AE
-
INF1

AEManagement

Contains
functionality to
manage the
lifecycle of an
AE

Provide the link to the
WSDL or Java
Interface

Specification
(eg. javadocs)

depending upon the
platform

AE
-
INF2

AEQuery

Contains
functionality to
Provide the link to the
WSDL or Java
NBIA Connector

SDD

Rev 0.1



BBMSC

8

of
16

retrieve an AE

Interface Specification
(eg. javadocs)

depending upon the
platform










…


…


Provide the
UML
diagrams describing the

above mentioned

interface
s.


4.3.2.

Operations Details for
<Interface Name>

This section should descr
ibe in detail the operations for each of the interfaces within the
component
. Each operation should be listed separately and described.

NOTE
:
This

section should be repeated for each implemented interface.

4.3.2.1.

<
Operation Name
>

Description

An overall description on what the operation does. An
activity diagram showing the details of the operation can be
optionally included.

Pre
-
Conditions

Specify any
platform specific
pre
-
conditions for invoking this
operation.

(Eg. User needs to have a X.509 Grid Proxy to
invoke this secured operation)

Security
Controls

Describe the controls used to enforce the security
requirements for this operation

In
puts

Provide
the syntactic detail of the input parameters (eg. Link
to XSD in GME)

Outputs

Provide
the syntactic detail of the output parameters (eg.
Link to XSD in GME)

Post
-
Conditions

Provide details about the state of the system after this
operation i
s executed successfully.

Also describe any state
changes for the data types in this operation

Exception
Conditions

List down all the possible exception conditions along with its
error code and error message

Notes

Include
additional implementation details
.


NBIA Connector

SDD

Rev 0.1



BBMSC

9

of
16

4.4.

Message Information Model

This section describes the information model of the messages sent to the
component
.
This should match the semantic profile detailed above. It should include a UML model
showing the object model for the
component
. It should als
o include a detailed
description of the model elements in a tabular format. This section should also include
artifacts such as an xml schema as required for the technology binding.

4.4.1.

Information Model

A UML diagram showing the
component

object model.

4.4.2.

Information Model Description

This section should include a detailed description of the
component

object model. This
object model is the external facing object model which the clients of the
component

will
use to interact with the
component
. This can include a tabular description of objects and
attributes of the
component

model. Any artifacts that implementers of this
component

need to adhere such as an xml schema or java interfaces should be referred to here.


NOTE: the following table shou
ld be repeated for each entity which acts as an input or
output parameter within the Information Model. Note: Exceptions should be defined
separately in the Error Handling section below

Object Name

AdverseEvent

Description of the Object

Represents the Adv
erse Event
occurring within the system

Link to the Object
Specification

Provide link to the XSD or the Java Interface
Specifications

Attribute Name

Type

Description

Id

String /
Number /
II etc.

Stores the Id of the Adverse Event







…


…



4.5.

Service

Interactions

This section describes the actors involved with the
component

and the dynamic
behavior of the
component
. It should include details of
component

behavior in all
significant service interactions.

An interaction diagram illustrating the interact
ion should also be included

in this section
.

NBIA Connector

SDD

Rev 0.1



BBMSC

10

of
16

4.5.1.

Actors

A description of the actors involved in
component

interactions.


Name

Type

Description

caEHR

System

System interacts with the
component

to input Adverse Event Data

Subject
Registry
Service


Uses the
Subject Registry Service
to retrieve additional subject
information







…


…


4.5.2.

Interaction Details

Provide
the interaction details between this
component

and other actors
.
Describe the
technology used for this interaction
.

Also provide the exact version of the
component

to
be used and the data specifications to adhere to for a particular interaction. The number
of consumers of the
component

can always increase in the future. However provide a
notional interaction with a con
sumer below to describe the specification of the

*Producers provided the data which this
component

needs.

*Consumers consume the data provided by this
component
.

Actor
Name

Producer /
Consumer

Data

Link

Description

Subject
Registry
Service

v1.0

Producer

Subject
Informati
on

Provide
link to
the XSD or
Java
Specification
defining the
data element
exchanged

AE Service
relies on
Subject Registry
Service to
retrieve
additional
subject
information

Scheduled
Calendar
Service

v1.0

Consumer

AE
Informati
on

Provide
link to
the XSD or
Java
Specification
defining the
data element
exchanged

AE Service
supplies AE
information to
the Treatment
Plan service

NBIA Connector

SDD

Rev 0.1



BBMSC

11

of
16











…




…


4.6.

Implementation Considerations

The following sections can optionally

be

used to specify any implementation specific
details for this
component
.

4.6.1.

Security

Provide technical
spe
cification on security requirements to access this
component
. This
includes authentication, authorization, encryption, and other LOA requirements.

Access Control

Does the
Component

require Access Control mechanism to be in
place to restrict access to only authenticated users

or systems
?

Yes/No

If Yes then provide the following in detail:

1. Authentication Mechanism used to authenticate the user

or external systems

2. Type of Credentials which are required to connect to
the
component

3. The minimal LOA which the users
/systems

need to provide
to access the
component

4. Does the
Component

allow anonymous access to its
operations

Application (Servi
ce) Security

[Access Policy]

Does the
Component

incorporate any security controls
(Authorization) to ensure that access to information is granted to
only the authorized users

/ systems
?

Yes/No

If Yes then provide the following in detail:

1. Explain the Authorization Mechanism used to secure the
component

(Grid Grouper, CSM, Custom etc.)

2. List down in detail the Authorization Policy which is
implemented to restrict access to information and
operations in the
component

to authorized users
only. If
the
component

allows Anonymous access list down the
operations which allow Anonymous access as part of the
Authorization Policy. NOTE: If the Authorization Policy is
large, it can be provided as an appendix to this document

Cryptography

NBIA Connector

SDD

Rev 0.1



BBMSC

12

of
16

Does the
Component

require encryption of data transmitted to and
from it?

Yes/No

If Yes then provide the following in detail:

1. The Cryptographic algorithm / mechanisms used for
encryption / decryption of the information

Information Security and Risk
Management

Is the information served by the
component

confidential or
privileged
? A
nd
if yes,
is it at risk from
any external
threats or
vulnerabilities?

Yes/No

If Yes then provide the following in detail:

1. Policy against unauthorized access, use, disclosure,
disruption, modification or destruction of information
served by the
component
.

2. The possible risks to the
component

and the ways to
reduce or mitigate these risks

Legal, Regulations, Compliance
and Investigations

Does the information served by the
component

fall under any legal /
regulatory compliance either at federal, state, local or institutional
level ?

Yes/No

If Yes then provide the following in detail:

1. List all the legal / regulatory compliance which the
component

has to cater too

2. The security controls in place to ensure that the legal
/ regulatory compliance is met

Telecommunications and Network Security

Does the
component

need any network or transport level security
such as SSL, Firewall protection etc.

Yes/No

If Yes then provide the following in detail:

NBIA Connector

SDD

Rev 0.1



BBMSC

13

of
16

1. Transport level security requirements such as SSL and
how it has been achieved in the
component

2. Network
requirements such as firewall configurations,
DMZ configurations etc.

4.6.2.

Auditing

Provide auditing requirements for the
component
. The level of auditing required, what
interactions need to be audited etc.


Operation
Name

Auditing Details

createAE



Logged in

User



Time stamp of creation



AE Identifier

queryAE

None





…

…


Entity Name

Auditing Details

AdverseEvent

Following operations for this entity are audited



Creation



Updating



Deletion







…

…

Also provide information about the technology used
for auditing purposes and additional
details like how long the audit information should be available, how to access audit
information etc.

NBIA Connector

SDD

Rev 0.1



BBMSC

14

of
16

4.6.3.

Privacy

Dataset should be analyzed for various federal regulations. Specify if the
component

implements privacy polic
y (such as HIPPA, 21 CFR
P
ar
t

11, PHI etc).


Based on each of these regulatory requirements:



Identify the data which requires privacy



Provide details of various controls which will be put in place to ensure this privacy



List down the requirements which a
user needs to fulfill to gain access to this
private data



Also mention about breach of privacy scenario and how it will be handled
(optional).

Data
Element

Privacy
Regulation

Security Control in
Place

Access Requirement

Subject

HIPAA

Component

will use
caGrid based Grid
Grouper
Authorization
controls to
restrict access

User needs to be
member of Study Co
-
ordinator or Site
Co
-
ordinator group














4.6.4.

Error Handling

Provide technical specification on how the errors will be raised by the
component

and
what information will be provided. Provide a technical model of the error conditions and
its specific meaning.

In this section, provide the technical specification on how the errors will be raised by the
component

and what information will be provided. Provide a technical model of the error
conditions and its specific meaning.

NOTE: This section should only list the errors which are to be returned to the clients.
The
component

should provide an encapsulation bounda
ry to all the internal error
s

and
return only the errors which are of use to the client application.

4.6.4.1.

Overview

Provide overview of the error handling and reporting mechanism for the specific
implementation. Depending upon the technology used to implement th
e
component

specification, describe in detail the appropriate error reporting mechanism. E.g. In case
NBIA Connector

SDD

Rev 0.1



BBMSC

15

of
16

of web services it would be web service faults or in case of EJB interface they will be
Java Exceptions.

4.6.4.2.

Error Object Details

Provide technology specific
details about
each
t attribute and its data type contained
within the error
objec
t
,

which can be used to describe the error condition
that
occurred.
It is recommended that each error object contain a unique code which can be used to
identify the error condi
tion programmatically. It should also be supported by a human
readable message which can be used for display purposes. Also an attribute describing
the criticality of the error can be present as well. Also an attribute describing the
criticality of the err
or (FATAL, MAJOR, MINOR, etc.) can be present as well.



In case of an EJB Interface these attributes become exception of the exception
object as class attributes.



In case of a WebService interface these attributes can be using the Error Code,
String and Mes
sage fields of a SOAP Fault. Additional information like severity
etc. can be represented in form of a Structured XML which can be included in the
message part of the SOAPFault.


Error Object Name

AEException

Description of the Error
Object

Represents the

Exception object in
the AE Service

Link to the Object
Specification

Provide link to the XSD or the Java Interface
Specifications

Attribute Name

Type

Description

Code

CD

Provides the Error Code

Message

ST

Provides the Error Message

Severity

CD

Provides the type of error (eg.
FATAL, MAJOR, MINOR etc.)





4.7.

Deployment Details

The following sections can optionally

be

used to specify any deployment specific details
for this
component
.

Deployment
Details

Impact

Deployment
Provide details of the different deployment
NBIA Connector

SDD

Rev 0.1



BBMSC

16

of
16

Modes

mode provided by this detail.

Performance
details

Provide specific measures of the
component
’s expected performance for each
component

operation.

Scalability
details

Does this
component

need to support a
particular number of requests? Are there
performance requirements for the
component
?

Discovery

How can clients call this
component
? For
example if this is an application it would
be installed on their computers,
downloaded from a publi
c web site etc.

Uptime

Provide the details of the uptime provided
by this implementation of the
component
.

Failover

Does this
component

need to provide hot
failover? If yes, then how should it be
handled at
component

/ database levels etc?








4.8.

Constraints

This section should include any additional constraints on the
component

that have not
been covered in the previous sections.

Constraints

Impact