Vendor Management Version: 1.

0
Page 1 of 29 Date: 4/16/2008

Vendor Management
Software Design
Specification (SDS)

Prepared by

Curt Marjaniemi
4/16/2008
Vendor Management Version: 1.0
Page 2 of 29 Date: 4/16/2008

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

Revision History
Date Version Description Author
4/13/2008 1.0 Draft submitted to capstone project Curt Marjaniemi
committee.
Vendor Management Version: 1.0
Page 4 of 29 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 today’s 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 Ent’s 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 meta-data driven.

3.2. General Constraints

3.2.1. Requirements
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).
Vendor Management Version: 1.0
Page 5 of 29 Date: 4/16/2008

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. LINQ’s 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.

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.
Vendor Management Version: 1.0
Page 6 of 29 Date: 4/16/2008

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. 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.
Vendor Management Version: 1.0
Page 7 of 29 Date: 4/16/2008

 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

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
Vendor Management Version: 1.0
Page 8 of 29 Date: 4/16/2008

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 Ent’s 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/en-us/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).

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.
Vendor Management Version: 1.0
Page 9 of 29 Date: 4/16/2008

Figure 2: Contract state diagram

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
Vendor Management Version: 1.0
Page 10 of 29 Date: 4/16/2008

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.
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 Version: 1.0
Page 11 of 29 Date: 4/16/2008

Figure 3: Contract related tables

Vendor Management Version: 1.0
Page 12 of 29 Date: 4/16/2008

Figure 4: Vendor related tables

Vendor Management Version: 1.0
Page 13 of 29 Date: 4/16/2008

Figure 5: Worksheet related tables

Vendor Management Version: 1.0
Page 14 of 29 Date: 4/16/2008

Figure 6: Permissions/Roles related tables

Vendor Management Version: 1.0
Page 15 of 29 Date: 4/16/2008

Figure 7: Attachment related tables

Figure 8: Help/FAQs related tables

Vendor Management Version: 1.0
Page 16 of 29 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 Version: 1.0
Page 17 of 29 Date: 4/16/2008

Figure 10: Base page related classes from the VendorMgmt.Controls namespace
Vendor Management Version: 1.0
Page 18 of 29 Date: 4/16/2008

Figure 11: Web server control related classes in the VendorMgmt.Controls namespace.
Vendor Management Version: 1.0
Page 19 of 29 Date: 4/16/2008

Figure 12: Web part related classes in the VendorMgmt.Controls.WebParts namespace

Vendor Management Version: 1.0
Page 20 of 29 Date: 4/16/2008

Figure 13: Utility related classes in the VendorMgmt.Controls namespace

Vendor Management Version: 1.0
Page 21 of 29 Date: 4/16/2008

Figure 14: Classes in the VendorMgmt.Services namespace

Vendor Management Version: 1.0
Page 22 of 29 Date: 4/16/2008

Figure 15: Classes in the VendorMgmt.Resources namespace

7.4. User Interface Design

7.4.1. Master Page Layouts
Vendor Management Version: 1.0
Page 23 of 29 Date: 4/16/2008

The Vendor Management application takes advantage of a .NET technology called

master pages. Master pages allow the developer to 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 Version: 1.0
Page 24 of 29 Date: 4/16/2008

Figure 17: Authenticated master page layout with vertical menu.

Vendor Management Version: 1.0
Page 25 of 29 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 Version: 1.0
Page 26 of 29 Date: 4/16/2008

Figure 19: An example of the "Red" theme

Vendor Management Version: 1.0
Page 27 of 29 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
Design
Feature ID Description
Component
1 Manage the contract lifecycle, including contract
Contract state
submission, due diligence, approval, monitoring,
machine
renewal, and expiration.
2 Allow for multiple institutions to use the vendor Master Page
management application independently. Layouts
&Database
Design –
specifically the
InstitutionID keys
on almost all
tables
3 Provide a mechanism for recording and monitoring risk Database Design
related to a vendor contract. – specifically the
logging tables
4 Provide a mechanism for recording and tracking vendor Database Design
Vendor Management Version: 1.0
Page 28 of 29 Date: 4/16/2008

contract performance. – specifically the

worksheets
5 Provide a mechanism for periodically reviewing
Database Design
vendors and recording information such as vendor
– specifically the
fiscal performance, control objectives, regulatory
worksheets
audit reports (e.g. SAS 70), etc.
6 Provide a permissions mechanism Database Design
– specifically the
roles/permissions
tables
7 Allow the site to have a different log and feel for Master Page
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
Pascal Casing
case.
First character of all words, except the first word are Upper Case and other
Camel Casing
characters are lower case.
Hungarian First word is lower case and defines the data type, all subsequent words
Notation have Upper Case first character and all 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.
 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."
Vendor Management Version: 1.0
Page 29 of 29 Date: 4/16/2008

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
 Fields / Constants
 Constructor
 Public Properties
 Public Methods
 Private Fields
 Constructors
 Public Properties
 Public Methods
 Private Methods
 Embedded Classes/Structs/Enums