Marjaniemi SDS VendorManagement

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

Vendor Management Software Design

Specification (SDS)

Prepared by

Curt Marjaniemi4/16/2008


Table of Contents1. Introduction 42. System Overview 43. Design Considerations 4

3.1. Assumptions and Dependencies 43.2. General Constraints 4

3.2.1. Requirements 43.2.2. Network Communications 43.2.3. Hardware Constraints 53.2.4. Software Requirements 5

3.3. Goals and Guidelines 53.4. Development Methods 5

4. Architectural Strategies 54.1. Architectural Style 5

5. System Architecture 65.1. Subsystem Architecture 6

5.1.1. Presentation Layer 65.1.2. Business Layer 75.1.3. Data Access Layer 7

6. Policies and Tactics 86.1. Microsoft .NET 3.5 and ASP.NET 86.2. Coding Conventions 86.3. Design Patterns 8

6.3.1. N-Tier design pattern 86.3.2. Provider model design pattern 8

6.4. Software Configuration Management (SCM) 86.5. Continuous Integration 8

7. Detailed System Design 97.1. Contract state machine 9

7.1.1. Contract states 97.1.2. Contract state transitions 10

7.2. Database Design 117.3. Class Diagrams 167.4. User Interface Design 22

7.4.1. Master Page Layouts 227.4.2. Themes, Style sheets, and Skins 25

8. Requirements Traceability 279. Appendix A – Coding Conventions 28

9.1. General Notes 289.2. Comments 299.3. Class or Struct 299.4. Ordering Regions 29


Revision HistoryDate Version Description Author

4/13/2008 1.0 Draft submitted to capstone project committee.

Curt Marjaniemi


1. IntroductionThe 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 OverviewThe 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 ConsiderationsThis 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. RequirementsRefer to the Vendor Management Software Requirements Specifications (SRS) document for the complete set of functional and non-functional requirements.

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


3.2.3. Hardware ConstraintsNone.

3.2.4. Software RequirementsThe 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 MethodsThe 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 StyleThe 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 ArchitectureThe 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 LayerThe 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 LayerThe 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 LayerThe 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.NETThe 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 ConventionsThe 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 PatternsThe Vendor Management application will utilize industry recognized, design patterns where possible. The following design patterns will be utilized:

6.3.1. N-Tier design patternThe 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 patternA 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 IntegrationThe 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 machineThe contract lifecycle from initial implementation, until the termination or expiration of the contract is represented in the following state diagram.

http://msdn2.microsoft.com/en-us/library/ms972319.aspx


Figure 2: Contract state diagram

7.1.1. Contract statesEach 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 transitionsThe 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 DesignThe 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 DiagramsThe 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.


Figure 18: Authenticated master page layout with horizontal menu

7.4.2. Themes, Style sheets, and SkinsUsing 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.


Figure 19: An example of the "Red" theme


Figure 20: An example of the "Blue" theme

8. Requirements TraceabilityThe traceability from software requirements to the design is shown in the following table.

Table 1: Requirements traceability matrix

Feature ID Description Design Component

1 Manage the contract lifecycle, including contract submission, due diligence, approval, monitoring, renewal, and expiration.

Contract state machine

2 Allow for multiple institutions to use the vendor management application independently.

Master Page Layouts &Database Design – specifically the InstitutionID keys on almost all tables

3 Provide a mechanism for recording and monitoring risk related to a vendor contract.

Database Design – specifically the logging tables

4 Provide a mechanism for recording and tracking vendor Database Design


contract performance. – specifically the worksheets

5 Provide a mechanism for periodically reviewing vendors and recording information such as vendor fiscal performance, control objectives, regulatory audit reports (e.g. SAS 70), etc.

Database Design – specifically the worksheets

6 Provide a permissions mechanism Database Design – specifically the roles/permissions tables

7 Allow the site to have a different log and feel for different institutions.

Master Page Layouts

9. Appendix A – Coding Conventions

9.1. General Notes

Pascal Casing First character of all words are Upper Case and other characters are lower case.

Camel Casing First character of all words, except the first word are Upper Case and other characters are lower case.

Hungarian Notation

First word is lower case and defines the data type, all subsequent words 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."


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 StructStructs 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 RegionsAll 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

Documents

Marjaniemi SDS VendorManagement