Overview and Technical Design

Insurance Agent Portal, “Pomegranate”

This document describes the features and technical design of the

exemplar code-named “Pomegranate”. This application is a
SharePoint (ASP.Net) web portal for use by Insurance Agents to
manger customer’s policies and claims.

Todd Snyder
6/27/2008
 Vision/Scope Document
2008

Contents
Introduction ................................................................................................................................................................3
Application Overview .................................................................................................................................................4
Dashboard View .....................................................................................................................................................4
Customer Details View ...........................................................................................................................................5
Quote and Customer Views....................................................................................................................................6
Technical Notes ......................................................................................................................................................6
Architecture and Technical Design .............................................................................................................................7
Technology .............................................................................................................................................................7
Microsoft SharePoint Service (WSS) 3.0 SP1 ......................................................................................................8
Net Advantage for ASP.NET 2008.2 ....................................................................................................................9
Windows 2003 Server...................................................................................................................................... 11
SQL Server 2005............................................................................................................................................... 11
Layers................................................................................................................................................................... 12
Design Patterns and Principals ............................................................................................................................ 12
Principals ......................................................................................................................................................... 13
MVP Pattern .................................................................................................................................................... 13
Adapter Pattern ............................................................................................................................................... 16
Repository Pattern........................................................................................................................................... 17
Provider Model Pattern ................................................................................................................................... 19
AJAX and SharePoint ........................................................................................................................................... 21
Summary.................................................................................................................................................................. 23

Copyright © 2008 Infragistics, Inc. 2

 Vision/Scope Document
2008

Introduction
Pomegranate is an insurance agent portal SharePoint exemplar (Reference Application). The application is built
using Windows SharePoint Services SP1, ASP.NET 2.0 and the Net Advantage for ASP.NET version 2008.2/Aikido
June CTP. The portal application utilizes a backend SQL Server 2005 (Express) database to store customer
information and Key Performance Indicators (KPI).

The design philosophy we used to build the exemplar was a pragmatic SCRUM approach. The application was
build over the course of several small 1 to 2 weeks sprints. Each sprint focused on building out a different set of
features. To help facilitate this approach we applied several design best practices including Test Driven
Development, refactoring, design patterns and principals.

This document Is broken down into two sections:

Application Overview: Gives an overview of the different screens in the application and their features.
Architecture and Technical Design: Examines the technology and design approach used to build the
application.

The exemplar can be viewed at the following URL: http://sharepoint.infragistics.com.

Copyright © 2008 Infragistics, Inc. 3

 Vision/Scope Document
2008

Application Overview
The applications include two main screens. A dashboard view that displays six web parts: Company News,
Pending Quotes, New Policies Per Year, Active Polices by Type, Quote to Bind Ratio, and Agent Summary. The
second screen is a customer detail view that is displayed as a popup dialog when a user clicks on one of the
customers listed the pending quotes web part.

Dashboard View
The dashboard view display six web parts that an insurance agent uses to track pending customer quotes and
other customer based KPI(s).

Figure 1: Dashboard Screen

Web Parts:

Company News: Displays the latest company news.

Pending Quotes: Displays a list of pending quotes for the agent’s customers.
New Policy per Year: Displays the number of new policies that the agent has sold per year for the
current and last two fiscal years.
Active Policy by Type: Displays a chart showing the percent of each active policy type within a specified
date range. The user can filter the percent shown by adjusting the starting/ending expiration date filter.

Copyright © 2008 Infragistics, Inc. 4

 Vision/Scope Document
2008

Quote to Bind Ratio: Displays the current quote to bind ratio (Percent of Accepted Quotes) for one or
more policy types. The user can filter the policy types used by selecting one or more types.

Agent Summary: Displays several KPI for the agent including: # of Customers, Direct Loss, Expense, and
Loss Ratio (Direct Loss + Expense / total customer premium).

Customer Details View

The customer detail screen is displayed when a user selects one of the customers listed in the pending quotes
web part. The screen is hosted in a dialog control and it displays detail information (Bio, Polices & Claims) about
a customer.

Figure 2: Customer Detail Dialog

Copyright © 2008 Infragistics, Inc. 5

 Vision/Scope Document
2008

Quote and Customer Views

These screens are not implemented and only exist to display additional links in the application’s main menu.

Figure 3: Screen not implemented

Technical Notes
The following Net Advantage for ASP.Net controls are used
o WebChart
o WebDialog
o WebDataGrid - Currently using the June CTP release
o WebGauge
o WebGrid - Used on the Customer Detail Screen
o Web Slider
The active By Policy and Quote to Bind Ratio web parts use MS AJAX (Update Panels) to support dynamic live
filtering of data.
The user Interface (UI) has been branded using a custom SharePoint theme (CSS, Images, Etc…)

Copyright © 2008 Infragistics, Inc. 6

 Vision/Scope Document
2008

Architecture and Technical Design

This section goes into detail about the architecture and technical designed used to build the application.

Technology
There are several technical components used to build the exemplar. One of the key first decisions when
designing a system is to identify when to built VS buy components. The approach we took in the exemplar was
to utilize 3rd party components to address the core features of the system and write custom code that integrated
the pre-built components.

Key Components Used:

Microsoft SharePoint Service (WSS) 3.0 SP1

Net Advantage for ASP.NET 2008.2
Windows 2003 Server
SQL Server 2005

Copyright © 2008 Infragistics, Inc. 7

 Vision/Scope Document
2008

Microsoft SharePoint Service (WSS) 3.0 SP1

WSS is a free add-on component to Windows 2003/2008. It is a web application framework for building
collaborate based solutions. If you need more advanced features you can switch over to using the Microsoft
Office SharePoint Sever (MOSS). MOSS is a full blown enterprise platform that includes advanced features for
content management, search, and form based data entry. The exemplar will run find of either version of
SharePoint.

The main features of WSS that are used by the exemplar include site provisioning, branding, and application
hosting. WSS includes additional feature that maybe used by a future version of the exemplar including custom
lists, workflows, and reporting capabilities.

Once you decided to use SharePoint that are two key technical design decisions that need to be made. First, you
need to determine which type of server farm you want to use and second you need to define the information
taxonomy needed to meet your requirements.

For the exemplar we want with a simple approach for both of these: On the hosted version of the example.
http://sharepoint.infragistics.com we are using a single server configuration and single top level site. For a more
advance solution you may want to consider one of the other serve farm types and typically most applications
require a much more advance information taxonomy.

Figure 4: Pomegranate Online Server Topology

References:

SharePoint Deployment
SharePoint Application Planning and Architecture

Copyright © 2008 Infragistics, Inc. 8

 Vision/Scope Document
2008

Net Advantage for ASP.NET 2008.2

The exemplar takes advanced of several of the features (data visualization, data presentation, and filtering
capabilities) included in the Net Advantage for ASP.NET control suite. By using this approach we were able to
focus on the business problem that needed to be solved; while harnessing the power of Net Advantage for
ASP.NET for building application with great user experience (UX).

Data Visualization

Figure 5: WebChart showing Key Performance Indicators (KPI)

Figure 6: WebGauge showing Key Performance Indicators (KPI)

Copyright © 2008 Infragistics, Inc. 9

 Vision/Scope Document
2008

Figure 7: WebSlider used to filter data

Figure 8: Presenting data in the WebDataGrid

Copyright © 2008 Infragistics, Inc. 10

 Vision/Scope Document
2008

Figure 9: WebDialog displaying Customer Detail Screen

Windows 2003 Server

This is a required component for running Windows SharePoint services. If you prefer you could install the
exemplar on a Windows 2008 server.

Reference: Details about Windows 2003

SQL Server 2005

This is a required component for running Windows SharePoint services. For production systems it is recommend
running the standard or enterprise version of SQL server. But, for simple solutions you can use SQL Express.

Reference: SQL Server 2005

Copyright © 2008 Infragistics, Inc. 11

 Vision/Scope Document
2008

Layers
This section gives a quick overview of the logical view (Layers) of the application. The core design approach used
to build the exemplar was to build out a custom web part framework. The framework uses the Model View
Presenter pattern to separate the concerns for each web part into three components: View (Custom Web Part),
Model (Custom Business Classes: Customer, Policy, Claim), and Presenter (Controller that orchestrates the
communication between the view and the model).

Figure 10: The design of the custom web part framework used in the exemplar.

The View is responsible for instantiating its presenter. Once the view is ready it notifies its presenter; which
loads the model and binds it to the view.

The view is loosely coupled from the presenter because the presenter only uses the view’s interface to
communicate with the view. This allows the highest level of unit testing because you can create unit tests
without requiring the ASP.Net process to be loaded. In addition, you can minimize the dependencies between
the view and the model.

Design Patterns and Principals

The key to successfully building enterprise based system is to utilize proven best practices and design
approaches. While building the exemplar we utilize several industry best practices for building enterprise .NET
applications.

Copyright © 2008 Infragistics, Inc. 12

 Vision/Scope Document
2008

Principals
Separation of Concerns: This is a principal where you separate the concerns for a use case into several
different classes. For example the Model View Presenter (MVP) Pattern separates code into views,
models, and presenters.
Single responsibility principal: This is a principal where you focus on making classes have high cohesion
and try to avoid overloading the reasonability of the class.
Test Driven Development: This is a design approach where you write test first to help drive out the
design of a system.
Refactoring: This is a design technique for restructuring an existing body of code, altering its internal
structure without changing its external behavior.

MVP Pattern
The Model View Presenter (MVP) pattern is a variation of the Model View Controller (MVC) pattern. Both
patterns promote separating the concern for a use case across three distinct types of classes: Model, Presenter
(Controller), and View. The major differences between the MVP and MVC pattern is that the MVP pattern
focuses more on separating the dependencies between the different components (Model, View, Presenter). By
doing this you can increase the testability of the overall solution.

Reference:
http://en.wikipedia.org/wiki/Model_View_Presenter

How it’s used in the Exemplar:

The following code listing illustrates how the MVP pattern is implemented in the exemplar.

Figure 11: Example interface used to implement the MVP Pattern

Copyright © 2008 Infragistics, Inc. 13

 Vision/Scope Document
2008

Figure 12: View (Web Part) implements the view interface

Figure 13: View (Web Part) instantiates its presenter

Copyright © 2008 Infragistics, Inc. 14

 Vision/Scope Document
2008

Figure 14: Presenter loads the model and binds it to the view.

Copyright © 2008 Infragistics, Inc. 15

 Vision/Scope Document
2008

Adapter Pattern
The adapter pattern promotes establishing a simpler interface between two components that depend on each
other. This is used a lot when implementing the MVP pattern to simply the interface used between the views
and its presenter. In addition an adapter pattern maybe used to consolidate communication between multi
classes or hide the complexity of one class that has lot of dependencies with other components.

Reference:
http://en.wikipedia.org/wiki/Adapter_pattern

How it’s used in the Exemplar:

The diagram below illustrates how the adapter pattern is used in the exemplar to isolate the presenter from the
WebChart Control. By using this approach we can assign the responsibility for binding the model to the
WebChart to the presenter. This will allow us to better test the behavior of loading data from the model into the
chart.

When the unit test is created the presenter will talk to a mock chart adapter that will simulate the process of
creating data series and data points on the chart. The purpose of the test is to validate the presenter can handle
binding the model to the chart (via its adapter).

Figure 15: Adapter pattern used to separate the presenter from underling control type used by the view.

Copyright © 2008 Infragistics, Inc. 16

 Vision/Scope Document
2008

Repository Pattern
The repository pattern is a data access pattern that promotes loosely coupling the model from its data source(s).
The main goal of the pattern is to act as an in memory data repository that uses data mapper type classes to
load data into and out of the model.

By using this approach you can achieve a higher level of persist ignorance; which will increase the overall
testability of your code. In addition you can easily handle adding additional data sources or changing data access
technology (e.g. from ADO.NET to LINQ or NHibernate) without impacting the core (View & Model) of your
application.

Reference:
http://martinfowler.com/eaaCatalog/repository.html

How it’s used in the Exemplar:

The diagram & code listing below illustrate how the repository pattern is used by the exemplar. Because most of
the data used in the exemplar is “read only” we went with a simply repository implementation that mapped
ADO.Net data readers/data commands to and from our domain model.

Note: The adapter pattern was used to wrap the standard ADO.Net classes (Connection, Command, Parameters,
& data readers). This allowed us to better unit test the mapping code used by the repository.

Figure 16: Key classes used by the exemplar to implement the repository pattern

Copyright © 2008 Infragistics, Inc. 17

 Vision/Scope Document
2008

Figure 17: Example of a repository mapping a data reader to a domain model.

Copyright © 2008 Infragistics, Inc. 18

 Vision/Scope Document
2008

Provider Model Pattern

The provider model pattern promotes loosely coupling components in a system using the concept of
dependency injection (DI). Dependency injection is used to separate dependencies between one or more
components. Instead of two components having a hard reference between them; components rely on a DI
container to inject the dependency at runtime. For the exemplar we are using the built in DI capabilities of the
.Net framework that use reflection to load a configured provider up when an application loads.

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

How it’s used in the Exemplar:

The diagram below contains the key classes used by the exemplar to implement the provider model. The
exemplar has a portal data provider that is used for accessing the customer KPI(s) data. The data provider used
is configured in the exemplars (SharePoint) web.config. This approach allows us to easily support additional data
sources in the future without requiring major changes to the application.

Figure 18: Classes used to implement the provide model pattern.

Copyright © 2008 Infragistics, Inc. 19

 Vision/Scope Document
2008

Figure 19: Entry in web.config used for defining the portal data provider

Copyright © 2008 Infragistics, Inc. 20

 Vision/Scope Document
2008

AJAX and SharePoint

One the biggest technical hurdles to overcome when working with SharePoint is integrating AJAX features into
an application. AJAX is a powerful technology that allows a web application to talk back to its “host” server
without requiring a full page post back. By utilizing the Microsoft ASP.NET AJAX Extensions 1.0 toolkit it is pretty
easy to integrate AJAX capabilities into an ASP.Net application. Unfortunately, getting the ASP.NET Extensions to
work with SharePoint is not as easy.

The major differences between incorporating AJAX into a standard ASP.NET web site and a SharePoint web site
is that inside of SharePoint the developer does not have full control over the ASPX pages used. Instead the
developer creates custom features (Web Parts, Field Controls, etc…) that are hosted in SharePoint. In addition
it’s typical that a SharePoint site may be running other web parts created by Microsoft or a 3rd party vender on
the same page as your custom web parts. Because of this you need to need to use caution in how and when you
use AJAX on a SharePoint web site.

How it’s used in the Exemplar:

Out of the box SharePoint does not automatically support AJAX and there were few things we had to do to get
AJAX setup to run properly under SharePoint. First we had to create a custom default.master page that
contained an ASP.NET AJAX Script manager control (Note: this control is required to use the Net Advantage for
ASP.NET Aikido controls) and then we had to write some custom JavaScript that allows SharePoint to properly
handle AJAX calls.

In additional we minimized the use of AJAX to only web parts that required on demand filtering. The web parts
that require this type of functionality use an ASP.NET UpdatePanel control that is setup to do partial page
rendering. The UpdatePanel is a powerful control that allows you to easily incorporate AJA X functionality into a
web site. But, it’s important to remember that using them comes with some caveats. When an Update Panel
fires an AJAX calls it still triggers the full page life cycle inside of ASP.NET page. This means that all the web parts
on a page will do normal processing (e.g. access a data source) unless you verify which update panel trigger the
async call and limited the processing only to them.

One other major issue we ran into incorporating AJAX into SharePoint was always getting the pages to properly
fire AJAX calls. The custom JavaScript code that we used to fire AJAX calls has some limitations that prevent it
from working properly when a SharePoint page does not contain at least one of the out of the box SharePoint
web part. Fortunately, to work around this limitation you can get the AJAX calls to work by adding a list view
web part control. Once the control is on the web page the custom JavaScript properly fires AJAX calls. If you
prefer not to display the normal SharePoint web parts you can mark them as hidden. Hidden web parts still will
allow the AJAX call to work properly.

Copyright © 2008 Infragistics, Inc. 21

 Vision/Scope Document
2008

Figure 20: Setting up update panel and registering JavaScript to make AJAX work

Figure 21: JavaScript code required to make AJAX calls work with SharePoint. See link for more details
http://support.microsoft.com/kb/941955

Copyright © 2008 Infragistics, Inc. 22

 Vision/Scope Document
2008

Summary
The Pomegranate exemplar is a great reference application that shows how to build custom web parts that run
inside of SharePoint. This document outlined the approach we took for building out the application as well as
how we were able to utilize Net Advantage for ASP.NEt to enhance the capabilities of the SharePoint platform.

Copyright © 2008 Infragistics, Inc. 23