Vendor Management

Page 1 of 31

Version:
1.0
Date: 4/16/2008

Vendor Management
Software Design
Specification (SDS)

Prepared by
Curt Marjaniemi
4/16/2008

Vendor Management
Page 2 of 31

Version:
1.0
Date: 4/16/2008

Table of Contents
1. Introduction
2. System Overview
3. Design Considerations
3.1. Assumptions and Dependencies
3.2. General Constraints
3.2.1. Requirements
3.2.2. Network Communications
3.2.3. Hardware Constraints
3.2.4. Software Requirements
3.3. Goals and Guidelines
3.4. Development Methods
4. Architectural Strategies
4.1. Architectural Style
5. System Architecture
5.1. Subsystem Architecture
5.1.1. Presentation Layer
5.1.2. Business Layer
5.1.3. Data Access Layer
6. Policies and Tactics
6.1. Microsoft .NET 3.5 and ASP.NET
6.2. Coding Conventions
6.3. Design Patterns
6.3.1. N-Tier design pattern
6.3.2. Provider model design pattern
6.4. Software Configuration Management (SCM)
6.5. Continuous Integration
7. Detailed System Design
7.1. Contract state machine
7.1.1. Contract states
7.1.2. Contract state transitions
7.2. Database Design
7.3. Class Diagrams
7.4. User Interface Design
7.4.1. Master Page Layouts
7.4.2. Themes, Style sheets, and Skins
8. Requirements Traceability
9. Appendix A Coding Conventions
9.1. General Notes
9.2. Comments
9.3. Class or Struct
9.4. Ordering Regions

Vendor Management
Page 3 of 31

Version:
1.0
Date: 4/16/2008

Revision History
Date
4/13/2008

Version
1.0

Description
Draft submitted to capstone
project committee.

Author
Curt Marjaniemi

Vendor Management
Page 4 of 31

Version:
1.0
Date: 4/16/2008

1. Introduction
The purpose of this software design specification (SDS) document is to clearly
describe the implementation design details of the Vendor Management
system and subsystems. This document assumes that the reader has reviews
the software requirements specifications (SRS) document for the Vendor
Management application.

2. System Overview
The Vendor Management application will provide a mechanism for
organizations to better manage their vendor relationships, with particular
regard to monitoring and managing the risk associated with critical vendors.
In todays business environment, where vendors can sometimes provide
essential services and house sensitive business data, managing critical
relationships with vendors is more important than ever. In the financial
sector, there is an increase in regulatory oversight surrounding proper vendor
management. The Vendor Management application specified in this
document intends to fill this business need for managing vendors and
providing an audit trail for regulators.
This application was initially designed for Ent and is based upon Ents vendor
management policies and procedures, and industry best practices. The
application is designed to be used by multiple institutions in a hosted
environment, with the intention that Ent would host this application for use by
other Credit Unions.
The application will be a web application built using the latest Microsoft
technologies, ASP.NET, C#, LINQ, and use a SQL Server 2005 backend
database.

3. Design Considerations
This section describes many of the issues that will need to be addressed or
resolved.

3.1. Assumptions and Dependencies

The application will be built using ASP.NET, .NET 3.5, C#.

Microsoft latest technology, LINQ will provide the object relational
database mapping.
The application will be partially meta-data driven application. Many of the
data elements in the application will be defined in the database, and can
be added, changed, or removed by the user interface.
The vendor review, contract due diligence, contract risk ratings, contract
review, and contract performance data elements will be completely metadata driven.

3.2. General Constraints

3.2.1. Requirements

Vendor Management
Page 5 of 31

Version:
1.0
Date: 4/16/2008

Refer to the Vendor Management Software Requirements Specifications

(SRS) document for the complete set of functional and non-functional
requirements.

3.2.2. Network Communications

The system is a web based application and will be delivered using
standard web protocols (HTTP/HTTPS).

3.2.3. Hardware Constraints

None.

3.2.4. Software Requirements

The system shall be designed to run on IIS 6.0, with .NET 3.5 installed
and configured to run on the server.
The backend database is SQL 2005.

3.3. Goals and Guidelines

No major software failures will be acceptable.

As much as possible, make the application meta-data driven.

3.4. Development Methods

The system will be developed using the following methods:
Test driven development
Iterative development using the Scrum approach
Utilized continuous integration

4. Architectural Strategies
4.1. Architectural Style
The system will utilize the modularity of a 3-logic tier architecture in order
to separate the concerns of these distinct functionalities (see Figure 1).
The business entities and data access layer will utilize the Microsoft
Language Integrated Query (LINQ) technology. LINQs builds all of the
business entities based off of the design of the database.
Test Driven Developed (TDD) is the development methodology utilized in
this project. Microsoft Test through Visual Studio 2008 will be utilized for
building the unit tests that will be used for the services layer, where the
majority of the business log resides.
One of the requirements is to allow the look and feel of the application to
change based on the institution using the application. Microsoft Master
Pages and themes will be used to implement this feature.
In general the design tries to take advantage as much as possible any
Microsoft functionality available. For example the authentication, object
relational mapping (ORM), navigation, exception management, themes,
and configuration management all utilize existing asp.net technologies.

Vendor Management
Page 6 of 31

Version:
1.0
Date: 4/16/2008

Application configuration settings will utilize the standard .NET

configuration management libraries, with the majority of the configuration
settings contained in the web.config. Common configuration settings (e.g.
database connection string) are contained in a sperate configuration file
called common.config, which is shared between the web application and
the test application, since they both need the same configuration
information.

5. System Architecture
The Vendor Management system is composed of three major logical layers
(see Figure 1): presentation layer, business layer, and data access layer.

Figure 1: 3-tier logical architecture

5.1. Subsystem Architecture

5.1.1. Presentation Layer
The presentation layer handles the presentation of the data to the end
user, and provides a mechanism for the user to interface with the data.

Vendor Management
Page 7 of 31

Version:
1.0
Date: 4/16/2008

This layer contains all of the web controls, pages, images, mater
pages, style sheets, etc.
In the Visual Studio solution for the Vendor Management application
the presentation layer is composed of the following projects:
VendorMgmt.Web Contains the actual web site including the page
definitions, images, master pages, and style sheets.
VendorMgmt.Controls - Any common UI functionality, like sortable
lists views, common base pages, and common UI utility functions,
have been moved into this project in the form of base pages, web
service controls, and static classes.
VendorMgmt.Resources Contains the majority of common string
messages, such as error messages, success messages, etc.

5.1.2. Business Layer

The business layer contains the service interface which is how the
presentation layer interacts with the various business entities (e.g.
Contracts, Vendors, etc). Any business rules are contained in the
business logic layer. The business workflows, in the form of a state
machine, are also contained in the business layer. For example, the
contract state machine which controls the lifecycle of a contract is
implemented in the business layer.
The business entities are entirely created by LINQ to SQL. LINQ reads
the database and generates the business entities. For example, in the
database there is a table called Contracts, which contains all of the
contract data elements. LINQ reads the database and creates a
Contract business entity, a Contracts collection, and the associations
between each of the other business entities. For example, each
Contract object has an associated contract owner. LINQ will create a
property on the Contract object called ContractOwner which is a
reference to a User object.
Any specific business rules that associated to a business entity and are
not represented by the database are implemented in C # partial
classes. For example, there is a business rule that contracts over $25K
need to have at least three competitive bids. This logic is contained in
the Contract partial class.
In the Visual Studio solution for the Vendor Management application
the business layer is contained in the following projects:
VendorMgmt.Services Contains the services that the UI uses for
interacting with the data, such as the Contracts service, Vendors
service, etc.
VendorMgmt.Data - Contains the LINQ data map
(VendorMgmt.dbml) which is used by LINQ to generate all of the
business entities. The generated code file is VendorMgmt.Designer.cs
(this generated code file is more than 10K lines of code). This project
contains the partial classes that contain specific business entity logic.

5.1.3. Data Access Layer

Vendor Management
Page 8 of 31

Version:
1.0
Date: 4/16/2008

The data access layer provides access to the persistent storage utilized
by the application. In the case of this application the persistent
storage takes the form of a SQL Server 2005 database.
LINQ handles all of the access to SQL, including connection
management, change tracking, transaction management, etc.
There is no specific code for the data access layer as LINQ handles this
layer entirely.

6. Policies and Tactics

6.1. Microsoft .NET 3.5 and ASP.NET
The system will be developed using the C# programming language, and
.NET 3.5. As mentioned previously Microsoft LINQ (which became
available in .NET 3.5 with designer support in Visual Studio 2008). LINQ
reduced the size of the project by an estimated 40% since it completed
generates the business entities from the database.

6.2. Coding Conventions

The system will be developed using Ents coding conventions, which are
basically the Microsoft standard coding conventions and are also
incorporate in FxCop. See Appendix A Coding Conventions for more
details.

6.3. Design Patterns

The Vendor Management application will utilize industry recognized,
design patterns where possible. The following design patterns will be
utilized:

6.3.1. N-Tier design pattern

The N-tier design pattern is utilized to separate concerns in an
application. Usually this design pattern is broken down into 3 logical
layers, presentation layer, business Layer, and data access layer.

6.3.2. Provider model design pattern

A provider is simply a contract between the API and the business
logic/data abstraction layer. The implementation of this contract in
.net is usually done using an interface. An interface will describe all of
what is required by the provider. Custom providers can be developed
and extended as long as they adhere to this interface. For more
information see http://msdn2.microsoft.com/enus/library/ms972319.aspx.
In the Vendor Management application the provider design patter was
mainly utilized in the presentation layer, for a customized role and
permission providers and a site map (navigation) provider.

6.4. Software Configuration Management (SCM)

All of the artifacts of this project, including source code, all documentation,
database schemas, etc will all be under source configuration management
utilization Microsoft Visual Source Safe (VSS).

Vendor Management
Page 9 of 31

Version:
1.0
Date: 4/16/2008

6.5. Continuous Integration

The system will utilize CruiseControl.NET for continuous integration. When
new source code is checked into the SCM system, cruse control will trigger
a build of the entire solution, will run all of the test cases, and run FxCop
against the solution. If the solution fails to build, or any test cases fail, or
the FxCop reports over a threshold of errors, CruiseControl will fail the
build.
On this project the development is being done by a single developer, so
the advantages of continuous integration cannot be fully realized, however
in the future the application may have multiple developers working on it
simultaneously.

7. Detailed System Design

7.1. Contract state machine
The contract lifecycle from initial implementation, until the termination or
expiration of the contract is represented in the following state diagram.

Figure 2: Contract state diagram

Vendor Management
Page 10 of 31

Version:
1.0
Date: 4/16/2008

7.1.1. Contract states

Each contract state (or node) is described below:
1. Unsubmitted The contract information is partially complete, and has
not been formally submitted for review approval.
2. Submitted The contract required information is complete, and has
been formally submitted for review and approval.
3. Action Required After reviewing the contract, Risk Management or
Senior Management has indicated that there is action required before
the contract can be approved. The contract owner must review the
required actions and re submitted the contract. An example of
required actions are to add addition clauses to the contract, or for the
contract owner to formal accept the risk of not having a clause in the
contract recommend by Risk Management.
4. Denied The contract is denied and no further action will be taken.
This is final state.
5. Approved The contract is formally approved, but may not
necessarily be signed and active yet.
6. Cancelled The contract is cancelled. This state is not to be confused
with a terminated contract. Cancelled in this case means the contract
was never active, and was cancelled for some reason. This is a final
state. Cancelled contracts are not displayed in the default view of the
application.
7. Active The contract is officially active. The contract official start
date and termination date (if applicable) must be set at this point.
8. Terminated/Expired The contract has been terminated or has
expired. This is a final state.

7.1.2. Contract state transitions

The contract state transitions are described below:
E1. Start -> Unsubmitted - A contract transitions from the start state to
the un-submitted state by a user entering in the contract data.
E2. Unsubmitted->Submitted - The contract is submitted, usually by the
contract owner.
E3. Submitted->Approved - Risk management has reviewed the
contract and provided feedback to the contract owner and there is no
action required. Once RM approves the contract and it will move to the
approved state.
E4. Active->Action Required - The contract owner is notified of a
pending review. If there are any actions required by RM, the contract
will move to the Action Required state.
E5. Action Required->Approved - If the contract owner performs the
action required, and RM approves that the necessary action was
completed, the contract moves to the approved state.
E6. Action Required->Denied - If the contract owner is not able to do
remediate the concerns posed by RM, the contract may move to the
denied state.
E7. Submitted->Denied - The contract was either denied by RM, senior
management, or the contract owner.
E8. Submitted->Action Required or Action Required -> Submitted Risk management has reviewed the contract and identified that some
action is required before the contract can be approved. Once the
contract owner has review the actions required, and possibly taken
steps to remediate the required actions (such as adding clauses into
the contract), the contract owner can re-submit the contract.

Vendor Management
Page 11 of 31

Version:
1.0
Date: 4/16/2008

E9. Active->Terminated/Expired - The contract can either be terminated

by RM or the contract owner, or expire if the contract was not renewed.
E10.
Approved->Active Once
a contract is signed and delivered to the vendor and is officially legally
active, the contract state moves into the active state.
E11.
Approved->Cancelled IT
is possible that an approved contract can move into the cancelled
state, if for some reason management decided not to proceed with the
contract, even after it has been approved by the necessary parties.
E12.
Submitted->Cancelled
After submitted a contract, the contract owner may decide to cancel
the contract.
E13.
Unsubmitted->Cancelled
A contract owner may decide to cancel a contract for any reason.
E14.
Finished state Transition
to the final state.

7.2. Database Design

The database design can be broken down into the following sub sections.

Vendor Management
Page 12 of 31

Version:
1.0
Date: 4/16/2008

Figure 3: Contract related tables

Vendor Management
Page 13 of 31

Version:
1.0
Date: 4/16/2008

Figure 4: Vendor related tables

Vendor Management
Page 14 of 31

Version:
1.0
Date: 4/16/2008

Figure 5: Worksheet related tables

Vendor Management
Page 15 of 31

Version:
1.0
Date: 4/16/2008

Figure 6: Permissions/Roles related tables

Vendor Management
Page 16 of 31

Version:
1.0
Date: 4/16/2008

Figure 7: Attachment related tables

Figure 8: Help/FAQs related tables

Vendor Management
Page 17 of 31

Version:
1.0
Date: 4/16/2008

Figure 9: Log related tables

7.3. Class Diagrams

The class diagrams can be broken down into the following sub sections
based on the namespace. For brevity, the class diagrams for the
business entities (Contract, Vendor, etc) have been excluded, since these
entities just match the database tables listed above.

Vendor Management
Page 18 of 31

Version:
1.0
Date: 4/16/2008

Figure 10: Base page related classes from the

VendorMgmt.Controls namespace

Vendor Management
Page 19 of 31

Version:
1.0
Date: 4/16/2008

Figure 11: Web server control related classes in the

VendorMgmt.Controls namespace.

Vendor Management
Page 20 of 31

Version:
1.0
Date: 4/16/2008

Figure 12: Web part related classes in the

VendorMgmt.Controls.WebParts namespace

Vendor Management
Page 21 of 31

Version:
1.0
Date: 4/16/2008

Figure 13: Utility related classes in the VendorMgmt.Controls

namespace

Vendor Management
Page 22 of 31

Version:
1.0
Date: 4/16/2008

Figure 14: Classes in the VendorMgmt.Services namespace

Vendor Management
Page 23 of 31

Version:
1.0
Date: 4/16/2008

Figure 15: Classes in the VendorMgmt.Resources namespace

7.4. User Interface Design

7.4.1. Master Page Layouts
The Vendor Management application takes advantage of a .NET
technology called master pages. Master pages allow the developer to

Vendor Management
Page 24 of 31

Version:
1.0
Date: 4/16/2008

create a consistent layout for the pages in the application. A master

page defines the look and feel and standard behavior for all of the
pages that utilize the master page. Users then create content pages
that merge with the master page to produce output that combines the
layout of the master page with the content from the content page.
There are two master pages that are used in the application, an
authenticated master page used for the logon and logoff pages, and
the non-authenticated master page used for all pages that are within a
logged in session. The authenticated master page has two different
layouts, which are used depending on the selected theme. The three
different screen layouts are depicted below:

Figure 16: Non-authenticated master page layout.

Vendor Management
Page 25 of 31

Version:
1.0
Date: 4/16/2008

Figure 17: Authenticated master page layout with vertical menu.

Vendor Management
Page 26 of 31

Version:
1.0
Date: 4/16/2008

Figure 18: Authenticated master page layout with horizontal menu

7.4.2. Themes, Style sheets, and Skins

Using the ASP.Net themes, skins and stylesheet functionality, a
completely different look and feel for the application can be
accomplished based on who the logged in user. An example of two
different themes is shown below.

Vendor Management
Page 27 of 31

Version:
1.0
Date: 4/16/2008

Figure 19: An example of the "Red" theme

Vendor Management
Page 28 of 31

Version:
1.0
Date: 4/16/2008

Figure 20: An example of the "Blue" theme

8. Requirements Traceability
The traceability from software requirements to the design is shown in the
following table.
Table 1: Requirements traceability matrix
Feature
ID
1

Description
Manage the contract lifecycle, including
contract submission, due diligence,
approval, monitoring, renewal, and
expiration.
Allow for multiple institutions to use the
vendor management application
independently.

Provide a mechanism for recording and

Design
Component
Contract state
machine
Master Page
Layouts
&Database
Design
specifically
the
InstitutionID
keys on
almost all
tables
Database

Vendor Management
Page 29 of 31

Version:
1.0
Date: 4/16/2008

monitoring risk related to a vendor contract. Design

specifically
the logging
tables
Provide a mechanism for recording and
Database
tracking vendor contract performance.
Design
specifically
the
worksheets
Provide a mechanism for periodically
Database
reviewing vendors and recording
Design
information such as vendor fiscal
specifically
performance, control objectives, regulatory the
audit reports (e.g. SAS 70), etc.
worksheets
Provide a permissions mechanism
Database
Design
specifically
the
roles/permissi
ons tables
Allow the site to have a different log and
Master Page
feel for different institutions.
Layouts

9. Appendix A Coding Conventions

9.1. General Notes
First character of all words are Upper Case and other
characters are lower case.
First character of all words, except the first word are Upper
Camel Casing
Case and other characters are lower case.
First word is lower case and defines the data type, all
Hungarian
subsequent words have Upper Case first character and all
Notation
other characters are lower case.
The C# file name should match the class/struct/enum it contains.
Indentation and Spacing. Set Visual Studio's tab size to 3 characters. Do not
replaces tabs with spaces.
Casing
o Pascal Case (ex. FirstName)
Constants, Classes, Structs, Methods, Properties, Events
Camel Case (ex. firstName)
o Parameters, Local Variables
Camel Case with leading underscore (ex. _firstName)
o Private Fields
Hungarian Notation
o Text Boxes (ex. txtFirstName)
o List Boxes (ex. lstSalutation)
o Check Boxes (ex. chkOption)
o Radio Buttons (ex. rdoGender)
Avoid having too large of files. If a file has more than 400 lines of code,
consider refactoring code into helper classes.
Pascal Casing

Vendor Management
Page 30 of 31

Version:
1.0
Date: 4/16/2008

Use enums wherever required. Do not use numbers or strings to indicate

discrete values.
All non-embedded classes/enums should be in their own *.cs file.
Never hardcode a path or drive name in code. Get the application path
programmatically and use relative paths.
If a missing or wrong value is encountered in a configuration file, the
application should throw an error or give a message indicating what the
expected value is.
Error messages should help the user to solve the problem. Never give error
messages like "Error in Application", "There is an error", "Stuff", etc. Instead
give specific messages like "Failed to update database. Please make sure the
login id and password are correct."

9.2. Comments

Do not write comments for every line of code and every variable declared.
Write comments wherever required. However, good readable code will
require very few comments. If all variables and method names are
meaningfull, that will make the code very readable and comments will only
be required to illuminate the more complex passages.
Fewer lines of comments will make the code more elegant. However, if the
code is not clean/readable and there are inadequate comments, that is
worse.
If you have to use some complex or weird logic for any reason, document
it very well with sufficient comments.
With the code regions (e.g. Private Methods, Public Methods) try to
balance using the code regions to split apart logical groups without having
a code region for everything.

9.3. Class or Struct

Structs versus classes have a considerable performance increase, so when
possible use structs. Here are some common guidelines:
Use a struct unless any of the following apply:
The data needs to be passed implicitly by reference
The data to be encapsulated is large
You don't need to access the data at all times
If you need to use inheritance (structs are implicitly sealed)
If you need a destructor (structs cannot have destructors)
If you need a parameterless constructor and initialize only some of the
instance fields (structs have to initialize all instance fields)

9.4. Ordering Regions

All C# classes and structs should be organized using regions. A typical
class file would contain the following regions:
Private Fields
Constructors
Public Properties
Public Methods
Private Methods
A more complicated class may contain the following regions:
Static

Vendor Management
Page 31 of 31

Fields / Constants
Constructor
Public Properties
Public Methods
Private Fields
Constructors
Public Properties
Public Methods
Private Methods
Embedded Classes/Structs/Enums

Version:
1.0
Date: 4/16/2008