Page 1 of 29 / Date: 4/15/2008
Vendor Management
Software Design Specification (SDS)
Prepared by
Curt Marjaniemi
4/15/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
Revision History
Date / Version / Description / Author4/13/2008 / 1.0 / Draft submitted to capstone project committee. / Curt Marjaniemi
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).
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.
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.
- 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 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
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.
Figure 2: Contract state diagram
7.1.1.Contract states
Each contract state (or node) is described below:
- Unsubmitted – The contract information is partially complete, and has not been formally submitted for review approval.
- Submitted – The contract required information is complete, and has been formally submitted for review and approval.
- 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.
- Denied – The contract is denied and no further action will be taken. This is final state.
- Approved – The contract is formally approved, but may not necessarily be signed and active yet.
- 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.
- Active – The contract is officially active. The contract official start date and termination date (if applicable) must be set at this point.
- 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.
Figure 3: Contract related tables
Figure 4: Vendor related tables
Figure 5: Worksheet related tables
Figure 6: Permissions/Roles related tables
Figure 7: Attachment related tables
Figure 8: Help/FAQs related tables
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.
Figure 10: Base page related classes from the VendorMgmt.Controls namespace
Figure 11: Web server control related classes in the VendorMgmt.Controls namespace.
Figure 12: Web part related classes in the VendorMgmt.Controls.WebParts namespace
Figure 13: Utility related classes in the VendorMgmt.Controls namespace
Figure 14: Classes in the VendorMgmt.Services namespace
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 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.
Figure 17: Authenticated master page layout with vertical menu.