Vender Management SDS

Document Sample
Vender Management SDS Powered By Docstoc
					Vendor Management            Version:     1.0
Page 1 of 29                 Date: 3/23/2012

        Vendor Management
    Software Design Specification

                              Prepared by

                          Curt Marjaniemi
Vendor Management                                    Version:     1.0
Page 2 of 29                                         Date: 3/23/2012

                                 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: 3/23/2012

                          Revision History
          Date       Version                  Description                               Author
4/13/2008           1.0        Draft submitted to capstone project           Curt Marjaniemi
Vendor Management                                                                 Version:     1.0
Page 4 of 29                                                                      Date: 3/23/2012

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
              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
Vendor Management                                                                 Version:     1.0
Page 5 of 29                                                                      Date: 3/23/2012

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

        3.2.3. Hardware Constraints

        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

    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: 3/23/2012

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: 3/23/2012

                  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.
Vendor Management                                                                 Version:     1.0
Page 8 of 29                                                                      Date: 3/23/2012

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

        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

    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.
Vendor Management                                                                Version:     1.0
Page 9 of 29                                                                     Date: 3/23/2012

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:
            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.
Vendor Management                                                               Version:     1.0
Page 10 of 29                                                                   Date: 3/23/2012

            4.   Denied – The contract is denied and no further action will be taken. This is final
            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
            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.
Vendor Management                                                             Version:     1.0
Page 11 of 29                                                                 Date: 3/23/2012

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

                                 Figure 3: Contract related tables
Vendor Management                                     Version:     1.0
Page 12 of 29                                         Date: 3/23/2012

                    Figure 4: Vendor related tables
Vendor Management                                        Version:     1.0
Page 13 of 29                                            Date: 3/23/2012

                    Figure 5: Worksheet related tables
Vendor Management                                                Version:     1.0
Page 14 of 29                                                    Date: 3/23/2012

                    Figure 6: Permissions/Roles related tables
Vendor Management                                         Version:     1.0
Page 15 of 29                                             Date: 3/23/2012

                    Figure 7: Attachment related tables

                    Figure 8: Help/FAQs related tables
Vendor Management                                                             Version:     1.0
Page 16 of 29                                                                 Date: 3/23/2012

                                    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: 3/23/2012

         Figure 10: Base page related classes from the VendorMgmt.Controls namespace
Vendor Management                                                         Version:     1.0
Page 18 of 29                                                             Date: 3/23/2012

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

      Figure 12: Web part related classes in the VendorMgmt.Controls.WebParts namespace
Vendor Management                                                             Version:     1.0
Page 20 of 29                                                                 Date: 3/23/2012

                Figure 13: Utility related classes in the VendorMgmt.Controls namespace
Vendor Management                                                    Version:     1.0
Page 21 of 29                                                        Date: 3/23/2012

                Figure 14: Classes in the VendorMgmt.Services namespace
Vendor Management                                                     Version:     1.0
Page 22 of 29                                                         Date: 3/23/2012

                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: 3/23/2012

        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: 3/23/2012

                Figure 17: Authenticated master page layout with vertical menu.
Vendor Management                                                             Version:     1.0
Page 25 of 29                                                                 Date: 3/23/2012

                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: 3/23/2012

                    Figure 19: An example of the "Red" theme
Vendor Management                                                              Version:     1.0
Page 27 of 29                                                                  Date: 3/23/2012

                             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                    Description
        1                Manage the contract lifecycle, including contract
                                                                                 Contract state
                         submission, due diligence, approval, monitoring,
                         renewal, and expiration.
        2                Allow for multiple institutions to use the vendor     Master Page
                         management application independently.                 Layouts
                                                                               Design –
                                                                               specifically the
                                                                               InstitutionID keys
                                                                               on almost all
        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: 3/23/2012

                         contract performance.                                   – specifically the
       5                 Provide a mechanism for periodically reviewing
                                                                                 Database Design
                         vendors and recording information such as vendor
                                                                                 – specifically the
                         fiscal performance, control objectives, regulatory
                         audit reports (e.g. SAS 70), etc.
       6                 Provide a permissions mechanism                         Database Design
                                                                                 – specifically the
       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
                        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
     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
Vendor Management                                                                Version:     1.0
Page 29 of 29                                                                    Date: 3/23/2012

        messages like "Failed to update database. Please make sure the login id and password
        are correct."

            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

    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

Shared By: