Customizing Team Foundation Server Project Portals

Article
08/13/2012

Phil Hodgson, Microsoft Corporation

May 2010

This article describes important concepts about project portals for Microsoft® Visual Studio® Team Foundation Server 2010 and provides guidance for process authors who customize process templates used to create project portals for team projects.

Team Foundation Server supports project portals that are matched to the out-of-the-box process templates. Process templates are designed to be customized to a team’s or organization’s specific needs. Similarly Team Foundation Server project portals can be customized to provision custom content or features to the portal site. Examples of customizations that may be considered are:

Changing the dashboards provisioned including adding new dashboards
Adding new Excel workbooks
Changing the Web Parts (or Web Part properties) on standard dashboards
Changing the visual appearance of the portal site
Activating custom SharePoint Features

Introduction

Overview of Project Portals

Customization Options

Example Customizations

Visual Studio Application Lifecycle Management encourages team collaboration by allowing team members to access team project data from a variety of tools and platforms. Team Foundation Server integrates with Microsoft SharePoint Products to enable SharePoint sites to present and modify team project data. A SharePoint site that is linked to a team project is referred to as the team project's project portal.

Project portals present and link information from the Team Foundation Server data stores, the team project's SQL Server Reporting Services site, Team Web Access and process guidance.

A project portal can be created in multiple ways. A common approach is to create the portal at the same time that the team project is created using the New Team Project Wizard from Visual Studio's Team Explorer window. Other creation options are available but may require more steps to complete the configuration.

Each of the process templates that are shipped with the product have a default SharePoint site definition that is designed to present information relevant to the process template. In addition, the out-of-the-box project portals support a variety of deployment scenarios and will choose the best set of features based on the configuration of Team Foundation Server and the version of SharePoint Products that is being used.

Project portals are intended to be customized to the team's or the organization's needs. Two types of customizations are available – changing individual portals and customizing the process template to affect portals created in the future. Customizing an existing portal is usually done through the user interface for SharePoint Products and requires less skills or access to complete. This document addresses the second type of customization because a deeper understanding of the components involved is needed.

To deploy process template customizations the user needs to be a member of the Project Collection Administrators group (or have the Manage process template permission). To deploy customizations for SharePoint Products, the user needs to be a member of the farm administrators group in SharePoint Products.

The intended audience of this document is process template authors who need to make changes to both the process template components and the project portal.

Overview of Project Portals

Team Foundation Server project portals are SharePoint sites that are able to present and link to data for a team project. Once a SharePoint Web application has been configured for use with a Team Foundation Server application-tier, SharePoint sites within the Web application can begin to incorporate access to team project data.

A project portal can present data from a team project using any or all of the following (depending on the capabilities of the environment):

Excel Web Access Web Parts that display Excel workbooks which are retrieving data from the Server SQL Server Analysis Services database for Team Foundation Server,
Team Web Access Web Parts that access data from the Team Foundation Server operational data store,
TfsRedirect application page that enables access to other team project resources such as the associated SQL Server Reporting Services report folder, Team Web Access site or process guidance.

Figure 1

Ff678492.Customizing_TFSProjectPortals_Fig1(en-us,VS.100).png

Figure 1 shows the flow of data from the Operational data stores, through the Data Warehouse and into the Analysis Services cube. From there the data can be retrieved and shown on the dashboards through a variety of methods.

Retrieval Method	Source	Dashboard Component
Team Foundation Server web services	Team Foundation Server operational data	Team Web Access Web Parts
SharePoint Products with Excel Services	Team Foundation Server data warehouse or SQL Server Analysis Services cube	Excel Web Access Web Part
SQL Server Reporting Services	Team Foundation Server data warehouse or SQL Server Analysis Services cube	Page Viewer Web Parts or Reporting Services Web Part

Project Portal Artifacts

The SharePoint site created through the New Team Project Wizard is a combination of artifacts and changes specified in the site definition configuration, the document libraries and content specified in the process template and the artifacts and changes made by any additional Features activated by the wizard (whose identifiers are specified in the process template).

Dashboard Document Library and Dashboard Pages

The "dashboard" pages in a project portal are Web Part Pages provisioned into a hidden document library (accessible from Quick Launch). The pages are provisioned by a number of SharePoint Features. The Features combine a custom ASPX layout page (which defines the Web Part Zones and dashboard toolbar) with details about the Web Parts on each dashboard.

The ASPX layout page is called dashboardlayouts.aspx and is deployed with the files for each Team Foundation Server SharePoint Feature that provisions dashboard pages. If you want to use the same layout for your pages you can take a copy of the dashboardlayouts.aspx page and include it in your own Feature.

The Team Foundation Server dashboards make use of the following Web Parts:

Windows SharePoint Services 3.0 or SharePoint Foundation 2010
- List View Web Part
- Content Editor Web Part
- Page Viewer Web Part
Microsoft Office SharePoint Server 2007 or SharePoint Server 2010
- Excel Web Access
Team Foundation Server Extensions for SharePoint Products
- Query Results Web Part
- Work Item Summary Web Part
- Completed Builds Web Part
- Recent Check-ins Web Part

Excel Reports Document Library

The Excel Reports document library holds the workbooks that retrieve data from the SQL Server Analysis Servicesdatabase for Team Foundation Server. When the reports are first provisioned the data connection to the cube is set. If the workbook contains a PivotTable report with a Team Project Hierarchy filter then the filter is set to the team project for the project portal.

A timer job for SharePoint Products periodically scans project portal sites to see if some aspects of the team project have changed that may affect the data connection or the Team Project Hierarchy filter. If it finds a change then it automatically updates all workbooks that are using the previous values.

The project portal's Quick Launch makes use of the TfsRedirect application page to direct users to URLs specific to the associated team project. The application page is located at ~site/_layouts/TfsRedirect.aspx. The resulting redirect URL depends on the query parameters passed to the application page. The following navigation links use TfsRedirect to find resources:

Team Web Access: Redirects to the team project's Team Web Access home page
Reports: Redirects to the team project's SQL Server Reporting Services folder
Process Guidance: Redirects to the team project's process guidance.

Other navigation entries include:

Dashboards: The document library that holds the dashboard Web Part Pages. Individual child entries are added for each dashboard during site creation and when a dashboard is copied.
Excel Reports: The document library that holds Excel workbooks that are shown on the dashboards via Excel Web Access Web Parts.
Documents child entries: Entries are added for the Wiki Pages document library, and for each of the out-of-the-box document libraries created by the process templates.
Lists child entry: The Calendar list.

The toolbar that appears on each dashboard page contains controls that provide access to team project data or perform operations on the dashboard and reports. The toolbar is defined in the dashboardlayouts.aspx page.

Process Template Content

Project portals may contain document libraries and documents specified in a process template. When using the New Team Project Wizard, after creation of the project portal from the specified template, the document libraries are created and content is uploaded. See Defining the Project Portal Plug-in for a Process Template for further details.

Team Foundation Server SharePoint Features

The artifacts provisioned within an out-of-the-box project portal are controlled by a set of SharePoint Features. A number of these are visible site-scoped Features whose action is to inspect the capabilities of the environment, determine which of the other Features best suit the environment and to activate them in the required order.

Project portals can be used with Team Foundation Server instances that have varying levels of features activated and versions of SharePoint Products that support different capabilities. For example, a Team Foundation Server instance may or may not be using the Reporting features. This would determine whether a data warehouse or SQL Server Analysis Services cube was available. As for SharePoint Products, the server may be running any of the following products:

Windows SharePoint Services 3.0
SharePoint Foundation 2010
Microsoft Office SharePoint Server 2007
SharePoint 2010 for Internet Sites, Standard
SharePoint 2010 for Internet Sites, Enterprise

The project portals can also be used with different process templates that require specific content (such as MSF Agile vs. MSF CMMI).

The Team Foundation Server Features recognize three levels of capability. Each level allows progressively more components to be provisioned:

No Reporting
Without reporting configured (i.e. without a Team Foundation Server data warehouse or SQL Server Analysis Services cube) the only data store available for access is the Team Foundation Server operational store. At this activation level only standard web parts for Team Web Access and SharePoint Products are provisioned.
Reporting
With a Team Foundation Server data warehouse or SQL Server Analysis Services cube available then SQL Server Reporting Services reports will also be available. If the server that is running SharePoint Products is running a version that does not include Excel Services (e.g. Windows SharePoint Services or SharePoint 2010 for Internet Sites, Standard), then this level of activation will provision Page Viewer Web Parts on dashboard pages that link to SQL Server Reporting Services reports. These are in addition to the Web Parts provisioned at the No Reporting level. Excel workbooks that contain reports link to the cube or data warehouse are also provisioned.
Enterprise
When the Team Foundation Server instance has reporting enabled and a version of SharePoint Products that supports Excel Services (e.g. SharePoint 2010 for Internet Sites, Enterprise) then Team Foundation Server will provision dashboards that contain Excel Web Access Web Parts which display the Excel workbooks provisioned at the Reporting level.

Activation Level	Pre-requisites	SharePoint Assets
No Reporting	Windows SharePoint Services	Team Web Access Web Parts SharePoint team site Web Parts My Dashboard Project dashboard
Reporting	Team Foundation Server data warehouse SQL Server Analysis Services cube SQL Server Reporting Services reports	Page Viewer Web Parts Excel workbooks Project dashboard
Enterprise	SharePoint Products with Excel Services	Excel Web Access Web Parts "Enterprise" dashboards

No Reporting

Windows SharePoint Services

Team Web Access Web Parts

SharePoint team site Web Parts

My Dashboard

Project dashboard

Reporting

Team Foundation Server data warehouse

SQL Server Analysis Services cube

SQL Server Reporting Services reports

Page Viewer Web Parts

Excel workbooks

Project dashboard

Enterprise

SharePoint Products with Excel Services

Excel Web Access Web Parts

"Enterprise" dashboards

To provide users with a project portal experience that best utilizes their environment the visible Features activate other hidden Features depending on the servers' configuration. The capability detection is done by a "top-level" Feature event receiver triggered from either the TfsDashboardAgileMoss (ID: 0D953EE4-B77D-485b-A43C-F5FBB9367207) or TfsDashboardCmmiMoss (ID: 3D0BA288-BF8E-47F0-9680-7556EDEF6318) Features. These are the ones referenced in the WssTasks.xml file of the out-of-the-box templates. The Features activated from the process templates can be changed to accommodate desired customizations. It is not required that the out-of-the-box Features be used, however they are designed to provide a great experience with the out-of-the-box process templates. The section Customization Options describes customizations that are available for the project portals.

The Team Foundation Server SharePoint Features can be grouped into the following categories:

Activation: Determine which Features should be activated
Infrastructure: Provisions content and makes site changes that other Features will rely upon
Content: Provision content such as dashboards and reports.
User Interface: Makes changes to the site's user interface

The tables below show the Features used in Team Foundation Server 2010.

Feature Name	Category	Template	Scope
TfsDashboardAgileWss	Activation	MSF Agile	Web
TfsDashboardAgileNoWh	Activation	MSF Agile	Web
TfsDashboardAgileMoss	Activation	MSF Agile	Web
TfsDashboardCmmiWss	Activation	MSF CMMI	Web
TfsDashboardCmmiNoWh	Activation	MSF CMMI	Web
TfsDashboardCmmiMoss	Activation	MSF CMMI	Web

Base Features (always activated)

Feature Name	Category	Template	Scope
TfsDashboardContentTypes	Infrastructure	Both	Site
TfsDashboardUpdate	Infrastructure	Both	Site
TfsDashboardBaseContent	Infrastructure	Both	Web
TfsDashboardBaseUI	User Interface	Both	Web
TfsDashboardAgileQuickLaunch	User Interface	MSF Agile	Web
TfsDashboardCmmiProcessDocLibraries	User Interface	MSF CMMI	Web
TfsDashboardBaseAgileContent	Content	Both	Web

No Reporting Features (activated if SQL Server Reporting Services is not used)

Feature Name	Category	Template	Scope
TfsDashboardNoWHAgileContent	Content	MSF Agile	Web
TfsDashboardNoWHCmmiContent	Content	MSF CMMI	Web

Reporting Features (activated if SQL Server Reporting Services is being used)

Feature Name	Category	Template	Scope
TfsDashboardWssBaseContent	Infrastructure	Both	Web
TfsDashboardAgileReports	Content	MSF Agile	Web
TfsDashboardWssAgileContent	Content	MSF Agile	Web
TfsDashboardCmmiReports	Content	MSF CMMI	Web
TfsDashboardWssCmmiContent	Content	MSF CMMI	Web

Enterprise Features (activated if SQL Server Reporting Services and SharePoint 2010 for Internet Sites, Enterprise, with Excel Services is used)

Feature Name	Category	Template	Scope
TfsDashboardMossAgileContent	Content	MSF Agile	Web
TfsDashboardMossCmmiContent	Content	MSF CMMI	Web

Team Foundation Server Site Definition

Team Foundation Server 2010 installs a site definition with two configurations that are designed to work with the process templates that are shipped with the product:

"TFS2010 Agile Dashboard" for the "MSF for Agile Software Development v5.0" process template, and
"TFS2010 CMMI Dashboard" for the "MSF for CMMI Process Improvement v5.0" process template.

Team Foundation Server Timer Job for SharePoint Products

Project portals may contain Excel workbooks that have a connection to the Team Foundation Server data stores. The administrator of a Team Foundation Server instance can change the reporting configuration for the instance. For example they could enable/disable reporting, change the location of the SQL Server Analysis Services cube or change the Enterprise Application Definition for sites within a given SharePoint Web application.

To keep these connections pointing to the correct location or to keep the Excel Services Authentication Settings matching the Enterprise Application Definition, a timer job for SharePoint Products runs on each SharePoint Web application that contains project portals. The timer job periodically scans the portal sites in the Web application and updates the workbook details if it finds that the connection or authentication details have changed.

If you are adding additional workbooks to a project portal and want their connections to be updated by the timer job then you should place them in the same document library as the Excel workbooks for Team Foundation Server. Note that the name of the connection in the workbook must be "TfsOlapReport" if it is to be updated by the timer job.

Portal Creation Scenarios

Project portals and the default site definition configurations are designed to work in three different activation scenarios. When designing customizations for the project portals you should consider how these scenarios are impacted.

Firstly, when creating a team project with the New Team Project Wizard a project portal can be created using the Team Foundation Server dashboard site definition. The Wizard will setup the connections between the team project and the project portal which are required for data to be available on the site. Without a connection to a team project many of the Team Foundation Server SharePoint components will not function as intended.

Secondly, a project portal site can be created through the UI for SharePoint Products using either of the site definition configurations, and then manually have the Team Foundation Server Dashboard Features activated. The difference here is that document libraries and content in the process template are not added to the site. Because a project portal site is connected to a team project if any of its containing (ancestor) sites are connected, this method is a convenient way for a team to create their own portal that still retrieves data from the same team project but has its own dashboards and reports.

Thirdly the Team Foundation Server SharePoint Features can be activated on a site created with a different site definition. The Features still require a connection to the team project before they can be activated. See Access a Team Project Portal and Process Guidance for more details.

Customization Options

There are a number of ways to customize Team Foundation Server to effect changes in future project portals. With the enhanced portal features available in Team Foundation Server 2010 come additional customization requirements. Customizations can now be made to the process templates, SharePoint Features or SharePoint site templates (with some restrictions).

Process Template Changes

Process templates define key aspects of a team project that affect how a team works. If a project portal is created using the New Team Project Wizard then the process template can control the following aspects of the project portal:

Which site definition configuration or global site template is used to create the site
Document libraries that are created within the project portal site
Documents that are uploaded to the document libraries
SharePoint Features that are activated on the site after creation

Customizations of the process template are covered in detail in the topic Customizing Team Projects and Processes.

To upload process template changes to Team Foundation Server requires the Manage process template permission on the team project collection. See the online documentation for more details on uploading a process template.

SharePoint Development

Aside from the process template customizations above, portal customization is essentially a customization task for SharePoint Products. The recommended method for packaging customizations of SharePoint Products is the SharePoint Feature. Since the wizard can activate Features on the site it is recommended that customizations be made by packaging them into one or more SharePoint Features and modifying the set of activated Features in the process template. It is not recommended that modifications be made to any of the files deployed from the Team Foundation Server solution packages (including Feature files) since during upgrade these modifications may be lost. Features can provision new content along-side Team Foundation Server standard content and execute any code needed to complete the site's setup. One approach to Feature development is to identify a Team Foundation Server content Feature that is similar to your needs, clone it and modify it as required.

Any customizations that rely on SharePoint Features need to be deployed to the SharePoint farm before they can be used. The Team Foundation Server or team project administrators may not have access to that farm so assistance from that farm's administrators may be required.

One of the key locations to be aware of when you develop SharePoint Features is the installation directory for SharePoint Products - commonly called "the hive". The hive is usually located in the following directory on the server that is running SharePoint Products:

%CommonProgramFiles%\Microsoft Shared\web server extensions\12

This path assumes that the server is running Windows SharePoint Services 3.0 or Microsoft Office SharePoint Server 2007. The path for SharePoint 2010 Products will use the "14" subdirectory instead of "12". For the remainder of this document we will refer to this path as [SPHive].

In order to deploy customizations to SharePoint Products you will need to be a member of the farm administrator’s group in SharePoint Products.

SharePoint Features

Features are a convenient method of deploying content to a SharePoint farm. They also have the ability to execute code that runs on the server. While content can be added to a site through the API for SharePoint Products, some aspects of content creation are only available through Features – such as "ghosting" of files.

Depending on the desired customizations you may wish to have the existing Team Foundation Server Features activated and then activate your own custom Features to add additional content or make API calls to modify the site. Additional Feature activations can be added to the process template.

Alternatively you may wish to take greater control over which of the Team Foundation Server Features are activated. One advantage of this is that the default Team Foundation Server Features attempt to provision as much applicable content to as site as the environment will support. If you wish to use your own content in place of certain Team Foundation Server content then avoiding unwanted activations may be a simpler approach.

When customizing which Features will be activated it is recommended that at a minimum you continue to activate the infrastructure Features listed in the section Team Foundation Server SharePoint Features.

Anatomy of Team Foundation Server SharePoint Features

The files that make up each Team Foundation Server Feature are structured in the following manner:

Figure 2:

Ff678492.Customizing_TFSProjectPortals_Fig2(en-us,VS.100).png

Feature.xml Files

The Feature.xml file details metadata for the Feature including its unique ID, title, visibility, scope and the code (if any) that should be run when the Feature is installed, activated, deactivated or uninstalled. It also specifies the list of element files or element manifests that define the Feature's content.

For details on Feature.xml files see the online documentation.

Feature Element Files

The Feature element files are referenced from the Feature.xml file using the ElementManifest element. These files contain the definitions of the atomic units of functionality that are applied to a site.

For the Team Foundation Server Features the Feature element files contain definitions for:

dashboard pages with their Web Part specifications
list/document library instances
custom actions
controls that are added to pages
content type specifications

When creating your own Features you can start with a copy of an example Feature element file and customize it for your own purposes.

Alternate Site Definition Configuration

A site definition configuration defines the initial content of a SharePoint site. If a project portal site is created through the SharePoint web interface then it will contain the artifacts defined in the definition (e.g. menus, list templates) and the Features for that site definition configuration will be activated.

If the customizations required can be achieved through a different site definition configuration then once this has been deployed to the SharePoint server the configuration can be referenced in the process template.

A custom site definition should at least activate the infrastructure Features listed in the section Team Foundation Server SharePoint Features.

Solution Packages

The preferred method of packaging SharePoint customizations for deployment is the solution package. This is a cabinet archive file with a ".wsp" extension. See Solutions Overview for more details.

Using Out-of-the-box Content as Your Starting Point

In many cases the out-of-the-box Team Foundation Server Features will provision content (e.g. dashboards or reports) that closely matches the types of artifacts that you want. Rather than starting Feature development from scratch it is often quicker to identify a Feature that is close to what you want and then use that as a base for development. For example, the XML for the My Dashboard page is stored in the following directory on a server that is running SharePoint Products:

[SPHive]\TEMPLATE\FEATURES\TfsDashboardBaseAgileContent\elements.xml

To use a Team Foundation Server Feature as your starting point:

Identify a candidate Feature and locate its definition in the [SPHive]\TEMPLATE\FEATURES directory on the server that is running SharePoint Products.
Copy the Feature's folder and edit details in the Feature.xml file to give the Feature a new ID and Title. You may also wish to change the Hidden property to make the Feature visible in the UI for SharePoint Products. You should also remove the ReceiverAssembly and ReceiverClass properties unless you explicitly want the same code executed when the Feature is used.
Make your changes to the Feature content
Deploy your Feature to the server and register it with the SharePoint farm using stsadm.exe (stsadm -o installfeature -name MyFeature).
Test it by activating the Feature on a site using stsadm.exe (stsadm -o activatefeature -name MyFeature -url http://myserver/MySite) or through the UI for SharePoint Products.

Replacing Out-of-the-box Content

When using the Feature method of provisioning replacing existing content is not supported.

Suppose that within a Feature's element manifest file there is a <Module> element with a <File> element that uses the same URL as an existing file. Depending on the value of the IgnoreIfAlreadyExists attribute of the <File> element, during activation of the Feature, SharePoint Products will either fail the Feature activation (if the attribute value was FALSE), or not provision the new content.

One method of achieving the desired result is to provision the new content to a temporary URL and then execute code to move the content to the desired location.

The following class implements the SharePoint Features receiver base class and provides some utility methods that simplify replacing existing content. It will be used later on in this white paper.

using System;
using System.Security.Permissions;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Navigation;
using Microsoft.SharePoint.Security;
using Microsoft.SharePoint.Utilities;

namespace Contoso.TfsPortals
{
  public class ContosoBaseFeatureReceiver : SPFeatureReceiver
  {
    // The fixed GUID for the TfsDashboardBaseContent Feature.
    const string TfsBaseContentGuid = "4E72D346-276F-47b3-8D10-56E474A4FE4A";

    // Name of the property that stores the default site-relative URL
    const string DefaultDashboardProperty = "teamfoundation.dashboards.DefaultDashboard";

    protected SPWeb Web { get; private set; }
    protected SPFeature Feature { get; private set; }

    public override void FeatureActivated(SPFeatureReceiverProperties properties)
    {
      Feature = properties.Feature;
      Web = Feature.Parent as SPWeb;
      OnActivate();
    }

    public override void FeatureDeactivating(SPFeatureReceiverProperties properties) { }

    public override void FeatureInstalled(SPFeatureReceiverProperties properties) { }

    public override void FeatureUninstalling(SPFeatureReceiverProperties properties) { }

    /// <summary>
    /// Override point for subclasses to handle activation
    /// </summary>
    protected virtual void OnActivate() { }

    /// <summary>
    /// Moves a file from one URL to another
    /// </summary>
    /// <param name="source">The site relative URL for the file to be moved.</param>
    /// <param name="target">The site relative URL to move the file to</param>
    /// <remarks>Move an existing file to a new URL, overwriting any existing file
    /// at the target location</remarks>
    protected void ReplaceFile(string source, string target)
    {
      SPFile sourceFile = Web.GetFile(source);
      if (sourceFile != null && sourceFile.Exists)
        sourceFile.MoveTo(target, true);
    }

    /// <summary>
    /// Mark the site so that the TFS Dashboard timer job will process Excel
    /// workbook connections and pivot table filters
    /// </summary>
    protected void MarkSiteForTimerJobProcessing()
    {
      // Clear the properties cached by the Team Foundation Server
      // Timer Job so it re-processes the site
      SPPropertyBag properties = Web.Properties;
      properties["teamfoundation.dashboards.CubeConnectcion"] = null; // spell as shown
      properties["teamfoundation.dashboards.ProjectMdxId"] = null;
      properties["teamfoundation.dashboards.Sso"] = null;
      properties.Update();
    }

    /// <summary>
    /// Add a reference to the dashboard specified by <paramref name="file"/> to 
    /// the Quick Launch under the Dashboards navigation item
    /// </summary>
    /// <param name="file">The file the references the dashboard</param>
    /// <exception cref="ArgumentNullException">If <paramref name="file"/> is
    /// <c>null</c></exception>
    /// <exception cref="ArgumentException">If the <paramref name="file"/> does not
    /// exist</exception>
    protected void AddDashboardNavigation(SPFile file)
    {
      if (file == null) throw new ArgumentNullException("file");
      if (!file.Exists) throw new ArgumentException("File does not exist. " + file.Url);

      SPNavigationNode node = Web.Navigation.GetNodeByUrl(file.Url);
      if (node == null)
      {
        // 1102 is the ID for the Dashboards navigation node
        SPNavigationNode parentNode = Web.Navigation.GetNodeById(1102);
        if (parentNode != null)
        {
          node = new SPNavigationNode(file.Title, file.Url);
          parentNode.Children.AddAsLast(node);
        }
      }
    }

    /// <summary>
    /// Set the default dashboard to be the <paramref name="file"/> passed in
    /// </summary>
    /// <param name="file">The file that will be the site's default dashboard</param>
    /// <exception cref="ArgumentNullException">If <paramref name="file"/> 
    /// is <c>null</c></exception>
    /// <exception cref="ArgumentException">If the <paramref name="file"/> does not
    /// exist</exception>
    protected void SetDefaultDashboard(SPFile file)
    {
      if (file == null) throw new ArgumentNullException("file");
      if (!file.Exists) throw new ArgumentException("File does not exist. " + file.Url);

      SPFeature feature = Web.Features[new Guid(TfsBaseContentGuid)];
      if (feature == null) return;

      SPFeatureProperty property = feature.Properties[DefaultDashboardProperty];
      if (property == null)
      {
        property = new SPFeatureProperty(DefaultDashboardProperty, file.Url);
        feature.Properties.Add(property);
      }
      else
      {
        property.Value = file.Url;
      }
      feature.Properties.Update();
    }
  }
}

SharePoint Site Templates

SharePoint site templates were used for the project portal solution in Team Foundation Server for Visual Studio Team System 2008. Site templates can still be as the base site for a project portal.

If you are going to create a site template for use as a project portal start by customizing a site but do not activate any of the Team Foundation Server Dashboard Features on the site. The Team Foundation Server Dashboard Features add properties and other artifacts to a site which may produce incorrect results if those changes are saved into the site template. Once you have saved the site as a site template, the STP archive can be added to the global site template gallery and then referenced from a process template.

You can test how your site template will work with the Team Foundation Server Dashboard Features by using it to create a sub-site underneath an existing project portal site and then manually activating the desired Team Foundation Server Dashboard Features.

Dashboard and Process Template Customizations

The following customizations are described in the remainder of this whitepaper.

Process Templates

Customization	Sections
Change work item type definitions	Updating the Work Item Type Definition
Change SQL Server Reporting Services reports	Updating SQL Server Reporting Services Reports
Change work item queries	Updating Work Item Queries
Activate SharePoint Features	Activating Features from the process template Activating Other Features

Excel Workbooks

Customization	Sections
Add or replace project portal Excel workbooks	Updating Project Portal Excel workbooks
Force update of Excel workbook data connections and filters	Updating Workbook Details

Dashboards

Customization	Sections
Create a new dashboard	Creating and Provisioning a Dashboard
Replace standard dashboard pages	Replacing Existing Dashboard Pages
Change Web Parts on standard dashboard pages	Editing Existing Dashboard Pages
Add links to Quick Launch	Adding links to Quick Launch
Set a default dashboard	Setting a Default Dashboard
Change the layout of dashboard pages	In-line Styling for Dashboards
Change the dashboard toolbar	Dashboard Toolbar

SharePoint Sites

Customization	Sections
Change the site logo	Site Logos
Change the site's appearance through a Theme	SharePoint Themes

Development of SharePoint Features

Customization	Sections
Create a Feature	SharePoint Features Feature.xml File
Package and deploy customizations of SharePoint Products	Packaging and Deploying the Solution Solution Packages Packaging and Deploying the Solution

Create a Feature

SharePoint Features

Feature.xml File

Package and deploy customizations of SharePoint Products

Packaging and Deploying the Solution

Solution Packages

Packaging and Deploying the Solution

Example Customizations

Having outlined the components that make up a project portal and discussed some of the customization options available we'll now take a walk through some example customization scenarios.

Meet Wesley. Wesley is the Team Foundation Server process author for Contoso and is responsible for designing and implementing the customizations required to support the company's development processes. Wesley is neither a Team Foundation Server administrator, nor a member of the farm administrator’s group for SharePoint Products in the production environments. He works with the appropriate administrators to deploy customizations. He does have his own development servers where he is an administrator.

As a process author, I want to use my own site definition configuration so that my users have a familiar environment

"The IT department has developed a custom SharePoint site definition with a single configuration called "Contoso Standard Site" that is used for all new SharePoint sites in the company. The site definition defines a customized look-and-feel for the site along with a number of standard lists and document libraries.

Wesley needs to customize the creation of project portals for new team projects so that the project portals use the Contoso site definition configuration. He also needs to understand and communicate to his team how the portal experience will be different from other sites created with company's site definition so that the team members can utilize the Team Foundation Server dashboard functionality."

To use the Contoso site definition configuration for a process template Wesley performs the following steps:

Identifies that the Contoso site definition's configuration is titled "Contoso Standard Site"

Follows the guidance for customizing the process template's portal plug-in to change the process template to use the site definition configuration. His portal task file (WssTasks.xml) now looks like:

<tasks>
  <task id="SharePointPortal"
        name="Create SharePoint Portal"
        plugin="Microsoft.ProjectCreationWizard.Portal"
        completionMessage="Project portal site created.">
    <dependencies />
    <taskXml>
        <Portal>
           <site template="Contoso Standard Site" language="1033" />
           . . . 
        </Portal>

Uploads the modified process template to his development Team Foundation Server instance and confirms that the Contoso site definition has been installed on his development server for SharePoint Products. He creates a new team project using the modified template.
After creation he confirms that the new site has used the correct Contoso site definition configuration and notes the differences compared to a standard SharePoint site for Contoso.
He sends the modified process template to the administrator of the production Team Foundation Server instance who uploads the new template to each of the production team project collections.

SharePoint Artifacts

In addition to the artifacts (lists, document libraries, etc.) created by a site definition for SharePoint Products, the process templates create a number of Document Libraries and Lists. Some of these are defined in the process templates, and some are defined in SharePoint Features which are activated by the process templates.

Wesley notes the following changes from the standard Contoso site.

Note

Contoso is using a modified version of the MSF for Agile Software Development v5.0 process template.

New Document Libraries or Lists:

Dashboards
Excel Reports
Process Guidance
Important Dates
Samples and Templates
Shared Documents

New Quick Launch navigation entries:

Documents (with child entries for each dashboard)
Team Web Access
Dashboards
Excel Reports
Reports
Process Guidance

As a process author I want to add a new state so that I can track in-progress work

"The Contoso development managers decide that all future projects should have a convenient means of identifying which work is currently in-progress. Wesley works with the teams and they agree that adding an "In Progress" state to their Task work item, and reflecting this in appropriate reports and queries would be the best solution.

Wesley reviews the team project artifacts to determine where changes will be required, and then identifies how those changes should be packaged for new projects."

Many teams find that the out-of-the-box Team Foundation Server process templates provide a good starting point. It is also common that some aspects of the process templates need to be modified to provide the best fit for an organization. Many of the components in a process template revolve around the definitions of the work item types. In particular most artifacts that users interact with for a team project relate to or depend on the work item type definitions.

Figure 3: Relationship between artifacts created for a team project

Ff678492.Customizing_TFSProjectPortals_Fig3(en-us,VS.100).png

For our scenario we look at what is required to add a new "State" to the Task work item type from the MSF Agile process template, and the flow-on changes needed to make that visible and useful to team members.

Changes are required to:

The Task work item type definition
SQL Server Reporting Services reports
Work item Queries
Project portal Excel workbooks
Project portal Team Web Access Web Parts

Updating the Work Item Type Definition

Adding a new state to the Task work item type definition requires adding the new In Progress state and adding transitions that allow the work item's state to change between it and the existing states Active and Closed.

Figure 4

Ff678492.Customizing_TFSProjectPortals_Fig4(en-us,VS.100).png

Follow the online guidance for How to: Change the Workflow of a Work Item Type

Updating SQL Server Reporting Services Reports

The SQL Server Reporting Services reports for a team project are specified in the process template. The RDL source files are located in the Reports folder.

"Wesley reviews the reports that reference the Task work item and determines that the only change required is to add a specific color to use for In Progress tasks in the Remaining Work report. He uses the SQL Server Business Intelligence Development Studio tool to open the Reports\Remaining Work.rdl file, makes the change and saves the results in place."

For more details on managing reports in the process template see the online guidance for Uploading Reports Using the Reports Plug-in.

For more details on customizing SQL Server Reporting Services reports for Team Foundation Server see Creating and Managing Reporting Services Reports for Visual Studio ALM.

Updating Work Item Queries

The work item queries that are provisioned under the "Team Queries" node for a team project are specified in the process template. The source files are located in the WorkItem Tracking\Queries folder.

"Wesley creates a new "Work In Progress" query and saves it into his working folder as WorkItem Tracking\Queries\WorkInProgress.wiq. He edits WorkItems.xml and adds an entry that references the new query source file and provisions it as "Work In Progress".

For more details on adding queries to process templates see Add a Query to a Process Template

Updating Project Portal Excel Workbooks

The Excel workbooks provisioned to a project portal using the out-of-the-box templates are located within two SharePoint Features, one for the MSF Agile template and one for the MSF Formal (CMMI) template. The files are deployed within a Feature because after deployment the data connections in the workbooks are updated to point to the SQL Server Analysis Services cube for the Team Foundation Server instance and pivot table filters are set to restrict results to the team project's data. Note that the out-of-the-box Excel workbooks are only included in a project portal if the Team Foundation Server instance has an associated data warehouse and SQL Server Analysis Services cube.

"Wesley decides to create one new Excel workbook to show which users have "in-progress" work items assigned to them and an updated version of the Task Progress workbook.

Because SharePoint does not allow existing content to be overwritten by files in a SharePoint Feature, Wesley needs to choose a unique URL for the updated Task Progress workbook and then copy it to its desired location."

He creates a new Feature ContosoReports which includes the following files:

feature.xml
elements.xml
In Progress Work.xlsx
Task Progress.xlsx

Feature.xml File

"Wesley references the elements.xml file and the two reports. He wants the workbooks to have their details (data connection, authentication settings and team project pivot table filter) updated so he references code through the ReceiverAssembly and ReceiverClass attributes that will execute after the Feature is activated:"

<Feature xmlns="https://schemas.microsoft.com/sharepoint/"
    Id="5A8979D8-2540-4443-A354-974ADF17E6C8"
    Title="Contoso Project Portal Reports"
    Version="1.0.0.0"
    Scope="Web"
    Hidden="FALSE"
    ReceiverAssembly="Contoso.TFSPortals, Version=1.0.0.0, Culture=neutral, PublicKeyToken=abcdef0123456789"
    ReceiverClass=" Contoso.TFSPortals.ContosoCustomReports">
  <ElementManifests>
    <ElementManifest Location="elements.xml" />
    <ElementFile Location="In Progress Work.xlsx" />
    <ElementFile Location="Task Progress.xlsx" />
  </ElementManifests>
</Feature>

Elements.xml File

"Wesley creates the elements.xml file to provision the workbooks into the correct location within the site:"

<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
  <Module Name="Workbooks" Url="Reports">
    <File Url="In Progress Work.xlsx" Type="GhostableInLibrary" />
    <File Url="Task Progress.xlsx" Name="Contoso Task Progress.xlsx" />
          Type="GhostableInLibrary"
  </Module>
</Elements>

Activating Features from the process template

To have the Feature activated during process creation a reference to its unique identifier (specified in the Feature.xml file) is placed in the WssTasks.xml file.

<?xml version="1.0" encoding="utf-8"?>
<tasks>
  <task id="SharePointPortal" ... >
    <taskXml>
      <Portal>
      ...
        <activateFeatures>
          <!-- TfsDashboardAgileMoss -->
          <feature featureId="0D953EE4-B77D-485b-A43C-F5FBB9367207" />
          <!-- TfsDashboardAgileQuickLaunch -->
          <feature featureId="1D363A6D-D9BA-4498-AD1A-9874ACA5F827" />
          <!-- ContosoReports -->
          <feature featureId="5A8979D8-2540-4443-A354-974ADF17E6C8" />
        </activateFeatures>
      </Portal>
    </taskXml>
  </task>
</tasks>

Updating Workbook Details

During activation of the out-of-the-box Features that provision workbooks, code is executed to set:

Connection to the Analysis Services database for Team Foundation Server
Excel Services Authentication Settings
Team Project Hierarchy filter for the PivotTable report

While this same code cannot be called from custom Features, you can use the Team Foundation Server timer job to do the same work. Periodically the timer job runs over sites looking for portals that need to have their connection details updated. Note that the name of the connection in the workbook must be "TfsOlapReport" if it is to be updated by the timer job.

To have the timer job re-process a site you need to clear the following properties on the SPWeb for the site:

teamfoundation.dashboards.CubeConnectcion [spelled exactly as shown]
teamfoundation.dashboards.ProjectMdxId
teamfoundation.dashboards.Sso

This can be done from a Feature event receiver within the FeatureActivated method. The code will need to be built into an assembly and provisioned to the global assembly cache for the server that is running SharePoint Products. You can provision this assembly either manually or through a solution package for SharePoint Products.

Once the Task Progress workbook has been provisioned to "Contoso Task Progress.xlsx" it can be moved to overwrite the out-of-the-box version during Feature activation.

"Wesley creates the following class to handle Feature activation events:

namespace Contoso.TfsPortals
{
  public class ContosoCustomReports : ContosoBaseFeatureReceiver
  {
    protected override void OnActivate()
    {
      ReplaceFile("Reports/Contoso Task Progress.xlsx",
                  "Reports/Task Progress.xlsx");
      MarkSiteForTimerJobProcessing();
    }
  }
}

Updating Project Portal Team Web Access Web Parts

"Wesley wants to change the Project Work Items Web Part on the My Dashboard page to show in progress Tasks. He considers whether he should replace the entire dashboard page with another that has the desired Web Parts, or whether he should write code to update the existing dashboard page after it has been provisioned.

He starts by creating a new Feature called ContosoDashboards."

Replacing Existing Dashboard Pages

One option is to provision his own version of the My Dashboard page and copy it over the out-of-the-box version from a Feature event receiver. To do this would require:

Creating a Feature that contained the definition for a dashboard file and provisioned it to a temporary name
A reference to a Feature event receiver that moved the file to "MyDashboards.aspx" and added a Quick Launch navigation entry for the updated dashboard.

The XML used to provision dashboard pages are stored in the Feature folders and could be used as a starting point when creating Features that provision customized dashboards. For example, the XML for the My Dashboard page is stored in the following directory on a server that is running SharePoint Products:

[SPHive]\TEMPLATE\FEATURES\TfsDashboardBaseAgileContent\elements.xml

The feature.xml for a possible Feature that achieves this is:

<Feature xmlns="https://schemas.microsoft.com/sharepoint/"
    Id="3BDED29A-F078-4E61-85F7-370A41B6DF08"
    Title="Contoso Custom Dashboard"
    Version="1.0.0.0"
    Scope="Web"
    Hidden="FALSE"
    ReceiverAssembly="Contoso.TFSPortals, Version=1.0.0.0, Culture=neutral, PublicKeyToken=abcdef0123456789"
    ReceiverClass=" Contoso.TFSPortals.ContosoCustomReports">
  <ElementManifests>
    <ElementManifest Location="elements.xml" />
    <ElementFile Location="dashboardlayouts.aspx" />
  </ElementManifests>
</Feature>

and the corresponding Feature event receiver:

using Microsoft.SharePoint;

namespace Contoso.TfsPortals
{
  class ContosoCustomDashboards : ContosoBaseFeatureReceiver
  {
    protected override void OnActivate()
    {
      SPFile file = ReplaceFile("Dashboards/Contoso MyDashboard.aspx",
                                "Dashboards/MyDashboard.aspx");
      AddDashboardNavigation(file);
    }
  }
}

The GUID for the ContosoDashboards Feature should also be added to the WssTasks.xml file so that it is activated by the New Team Project Wizard.

Editing Existing Dashboard Pages

Another customization option is to manipulate existing pages through the SharePoint object model after they have been provisioned. A Feature does not need to provision any actual content in order to have a Feature event receiver execute custom code, so this is an easy way to execute code in the context of a specific site.

In order to change a property on a Web Part on the My Dashboard page you would need to:

Get a reference to the SPFile object for the dashboard page
Get the Web Part Manager for the file
Iterate over the Web Parts in the manager and make any desired changes to the Web Parts
Save the changes.

A sample Feature event receiver that performs this is below:

using System.Web.UI.WebControls.WebParts;
using Microsoft.SharePoint;
using Microsoft.SharePoint.WebPartPages;

namespace Contoso.TfsPortals
{
  class ContosoUpdateRecentBuilds : ContosoBaseFeatureReceiver
  {
    protected override void OnActivate()
    {
      SPFile dashboard = Web.GetFile("Dashboards/MyDocuments.aspx");
      SPLimitedWebPartManager manager;
      using (manager = dashboard.GetLimitedWebPartManager(PersonalizationScope.Shared))
      {
        foreach (System.Web.UI.WebControls.WebParts.WebPart part in manager.WebParts)
        {
          using (part)
          {
            // make change to parts
            ///...
            // save changes
            manager.SaveChanges(part);
          }
        }
      }
    }
  }
}

"Wesley decides that replacing the My Dashboard page with his own definition is the best choice since it is simpler to code and makes future changes to the page easier."

Packaging and Deploying the Solution

"Wesley identifies all of his customizations. The process template changes include the modified work item type definitions, updated SQL Server Reporting Services reports, new work item queries and references to activating two new SharePoint Feature. He uploads the new process template to his team project collection.

The changes to SharePoint Products include the two new workbooks, an assembly to execute activation actions and the Feature definition files. He packages these into a solution package (a WSP file), uploads the WSP to the server that is running SharePoint Products and deploys it to the SharePoint farm.

Wesley then creates a new team project using the updated process template which in turn creates a project portal and activates the new ContosoReports and ContosoDashboards Features."

As a process author I want to change the default set of dashboard pages for new projects so that I get my process dashboards instead of Agile or CMMI

"The development teams have been successfully developing on Team Foundation Server 2010 for a while. The various teams have manually customized the dashboards in the project portals for their team projects and have come together for a review. The review identifies that there are a common set of dashboard changes which should be included in all future project portals. The changes include:

A new Executives dashboard containing three new Excel charts and two Team Web Access Query Web Parts. This should be the default project portal page.
Provision new versions of the standard Burndown, Quality and Test dashboards
Removal of the Build dashboard
Provisioning of the Project dashboard

Wesley reviews the list of requirements and identifies that he could use one Feature to:

Provision the new Executives dashboards
Ensure that the TfsDashboardWssAgileContent Feature is activated (which provisions the Project dashboard)
Execute code that will:
- Add Quick Launch links to the dashboard pages
- Set the default dashboard page to the Executives dashboard

Because there are quite a few changes to the dashboards normally provisioned for the Agile template, Wesley identifies that he doesn't want the default Team Foundation Server Feature (TfsDashboardAgileMoss) to be activated from the Template. Instead he will activate his own Feature that contains modified copies of some dashboards and control which other Team Foundation Server Features are activated."

Creating and Provisioning a Dashboard

To provision a Custom Dashboard as part of a solution it is often easiest to start with an out-of-the-box Feature and make required modifications. See Section 3.2.4 Using Out-of-the-box Content as Your Starting Point for more details..

Each dashboard is provisioned as a File in a Module. For details on the syntax available, see the online documentation for Modules.

To add Web Parts to a dashboard page you use the AllUserWebPart element. The basic structure of the element is:

<AllUsersWebPart WebPartZoneID="<ZoneID>" WebPartOrder="<Order>">
  <![CDATA[...]]>
</AllUsersWebPart>

The content of the CDATA section defines a single Web Part that is added to the specified Web Part Zone. If multiple Web Parts are added to the Web Part zone then they are ordered based on the WebPartOrder property. The CDATA section defines the full class name of the Web Part and the property values that should be set for that instance of the Web Part.

It can sometimes be tricky to get the property syntax correct, especially when dealing with non-trivial property types. One approach that works is to get SharePoint to do the work for you. First, manually create a Web Part Page in a site and add your desired Web Parts to the page. Ensure that the "Export Mode" Web Part property under the "Advanced" Web Part editor section is set to "Export all data".

Configure the value of the properties to your liking then use the "Export..." option for the Web Part.

Figure 5

Ff678492.Customizing_TFSProjectPortals_Fig5(en-us,VS.100).png

This should allow you to save a .webpart file that can be copied directly into the CDATA section. The .webpart file contains the current value of all of the Web Part's exportable properties, many of which you can delete if you wish to use the default values when provisioning your dashboard page.

Putting this together, to provision a custom dashboard titled "Executive Dashboard" that displays a single Excel report called "ExecutiveStatus.xlsx" you could create an elements file with the following:

<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
 <Module Name="ExecutivePage" List="101" Url="Dashboards">
  <File Name="Executive.aspx" Type="GhostableInLibrary" Url="dashboardlayouts.aspx">
   <Property Name="Title" Value="Executive Dashboard" />
   <AllUsersWebPart WebPartZoneID="<ZoneID>" WebPartOrder="<Order>">
    <![CDATA[
    <webParts>
     <webPart xmlns="https://schemas.microsoft.com/WebPart/v3">
      <metaData>
       <type name="Microsoft.Office.Excel.WebUI.ExcelWebRenderer, Microsoft.Office.Excel.WebUI, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" />
       <importErrorMessage>Cannot import this Web Part.</importErrorMessage>
      </metaData>
      <data>
      <properties>
       <property name="Width" type="string">285pt</property>
       <property name="WorkbookUri" type="string">~site/Reports/ExecutiveStatus.xlsx</property>
       <property name="AllowInteractivity" type="bool">False</property>
       <property name="AutoGenerateDetailLink" type="bool">True</property>
       <property name="AutoGenerateTitle" type="bool">False</property>
       <property name="Title" type="string">Executive Status</property>
       <property name="AllowParameterModification" type="bool">True</property>
       <property name="AllowNavigation" type="bool">False</property>
       <property name="ShowWorkbookParameters" type="bool">False</property>
       <property name="Height" type="string">188pt</property>
       <property name="ToolbarStyle" type="Microsoft.Office.Excel.WebUI.ToolbarVisibilityStyle, Microsoft.Office.Excel.WebUI, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c">None</property>
      </properties>
     </data>
    </webPart>
   </webParts>
   ]]>
   </AllUsersWebPart>
  </File>
 </Module>
</Elements>

A detailed discussion on the properties of various Web Parts is not within this document's scope. It is however worth pointing out some specific property values:

Excel Web Access Web Part

If either AllowInteractivity or AllowNavigation are set to True then the Excel Web Access Web Part generates additional browser cookies in the HTTP response. These cookies can hold a substantial amount of data. While the EWAs manage the total amount of data taken up by these cookies we have encountered scenarios where the data exceeds the available space in the HTTP header and causes a "Bad Request" response from the web server. If you don't specifically need the interactivity we suggest you set both properties to False.

The WorkbookUri property can include the "~site" token which is replaced by the path to your site during provisioning.

To avoid additional whitespace or unwanted scroll bars, we suggest that you set the Width and Height properties to match the dimensions of your chart.

Query Results Web Part

The Query and ServerQuery properties work in tandem. If ServerQuery is True then Query is the name of the Team Query on the server that will be executed (where the path start with "Team Queries/"). If ServerQuery is False then Query is the text of the Work Item Query that will be executed.

Rather than generating the WIQL text by hand it is usually easier to export the property values from a QueryResultsWebPart Web Part that has been configured to the correct values through the web UI.

The PersistenceStorage property affects how the query results are displayed in the Web Part. Without specifying this property the query results will have the columns and row order defined in the WIQL query and the result columns will have widths based on default values for their data types. By specifying this property you can change which columns are returned from the query (including dropping all the columns defined in the WIQL), what the sort order for the rows is, and specific column widths. Again, the simplest approach to getting this property value correct is to export a previously configured Web Part and copy the property value.

When working with a ServerQuery set to True the columns and sort order should be customized by manually resizing the column widths in the browser and using the dialog accessed from the "Column Options" toolbar button. After making the changes, select "Save Query Changes" from the Web Part's menu before exporting the .webpart file.

Figure 6

Ff678492.Customizing_TFSProjectPortals_Fig6(en-us,VS.100).png

When working with ServerQuery set to False the columns, widths and sort order should be customized through the Query Picker that is accessed from the Web Part's editor. After applying the changes you can export the .webpart file to get the property values.

It will probably be worth specifying the Width and Height properties for the Web Part. By default the Height of the result area is set to 600 pixels and the Width property is set to 100% (which collapses the Web Part to only show the Web Part title and any toolbar specified). If the Width property is set and a toolbar is used (either Minimal or Full) then the Width property should be set wide enough to avoid clipping off the toolbar.

Work Item Summary Web Part

The WorkItemSummaryWebPart summarizes the work items returned from a query by grouping and counting the results based on the Work Item Type and State fields. The actual columns and sort order of the underlying query are not used in the calculations of the totals, only the filters for top level work items. The underlying query's columns and sort order are used if a user clicks on one of the summary totals which then displays the query results for that particular State and/or Work Item Type.

"Wesley uses the approach above to generate the AllUsersWebPart entries for each of the five Web Parts on the Executive dashboard. The three Excel Web Access Web Parts display data from three new Excel workbooks which Wesley includes in the Feature.

For the modified Burndown, Quality and Test dashboards Wesley copies their definitions from the elements.xml file in the TfsDashboardMossAgileContent Feature into his own Feature and modifies their definitions accordingly."

Activating Other Features

Activating Features can be done in a variety of ways:

From the process template, by adding a new <feature> element
Through the API for SharePoint Products
By defining a Feature activation dependency

"Firstly Wesley changes the process template to avoid activating the TfsDashboardAgileMoss Feature. He does this by removing the corresponding element (<feature featureId="0D953EE4-B77D-485b-A43C-F5FBB9367207" />) from WssTasks.xml.

Wesley decides that activating the TfsDashboardWssAgileContent Feature should not be included as a direct dependency of his custom Feature so he scopes the activation to the process template by adding a new <feature> element

<feature featureId="0D953EE4-B77D-485b-A43C-F5FBB9367207" />

He also adds a <feature> element for his custom Feature."

Adding links to Quick Launch

"To add the dashboards to the site's Quick Launch navigation Wesley defines a Feature event receiver that calls the ContosoBaseFeatureReceiver.AddDashboardNavigation method.

using Microsoft.SharePoint;

namespace Contoso.TfsPortals
{
  class ContosoCustomDashboards : ContosoBaseFeatureReceiver
  {
    protected override void OnActivate()
    {
      AddDashboardNavigation(Web.GetFile("Dashboards/Executive.aspx"));
      AddDashboardNavigation(Web.GetFile("Dashboards/Burndown.aspx"));
      AddDashboardNavigation(Web.GetFile("Dashboards/Quality.aspx"));
      AddDashboardNavigation(Web.GetFile("Dashboards/Test.aspx"));
    }
  }
}

Setting a Default Dashboard

The Team Foundation Server dashboards include a control that allows redirection to a "default dashboard". The control is included in the "default.aspx" page which is provisioned by the TfsDashboardBaseUI Feature when using one of the Team Foundation Server site definition configurations.

When executing, the control looks to see if a default dashboard has been set. The default site-relative URL (if it exists) is stored in the Feature property bag for the TfsDashboardBaseContent Feature. If the property doesn't exist, then the control will look for the Dashboards document library and pick the first .aspx item in the list.

To set the default dashboard you can either set the Feature property or make a call to the SetDefaultDashboardPage.aspx page.

Setting the default dashboard through the API

To set a default dashboard URI through the API you need to:

Get the SPFeature instance for the TfsDashboardBaseContent Feature that is activated for your SPWeb
Get the properties for the SPFeature
Add or update the property that stores the default dashboard URL
Updated the Feature's properties

The code to do this is contained in the ContosoBaseFeatureReceiver. SetDefaultDashboard method defined earlier.

"Wesley decides to use this method to set the Executives dashboard as the default dashboard".

Setting the default dashboard through a web call

To set the default dashboard through a web call involves constructing a query string that contains the GUID for the Dashboard's document library and the Id of the item within the library.

The URL for the SetDefaultDashboardPage is:

~site/_layouts/Microsoft.TeamFoundation/SetDefaultDashboardPage.aspx?List={ListId}&Item={ItemId}

where ~site is the URL for the site, {ListID} is the GUID for the Dashboards document library using the "B" format specifier for the System.Guid structure and {ItemId} is the integer ID of the dashboard page within the document library (note that this is not the index of the item in the collection of items for the list).

void SetDefaultDashboard(SPListItem dashboard)
{
    string path = SPUrlUtility.CombineUrl(dashboard.Web.Url, "_layouts/Microsoft.TeamFoundation/SetDefaultDashboardPage.aspx");

    UriBuilder uri = new UriBuilder(path);
    uri.Query = String.Format("List={0:B}&Item={1}", dashboard.ParentList.ID, dashboard.ID);

    WebRequest request = WebRequest.Create(uri.Uri);
    HttpWebResponse response = (HttpWebResponse) request.GetResponse();
    // expect that response.StatusCode == HttpStatusCode.Redirect
}

Packaging and Deploying the Solution

"Wesley identifies all of his customizations.

His process template changes include changes to the Features activated by the process template. He uploads the new process template to his team project collection.

He has created one new Feature that:

Provisions three new Excel workbooks
Provisions the new Executives dashboard
Provisions customized copies of the Burndown, Quality and Test dashboards
Calls a Feature event receiver

He has created an assembly that implements the Feature's event receiver which on activation:

Adds Quick Launch entries for each dashboard
Sets the Executives dashboard as the default page for the site

He packages the assembly and the Feature files into a solution package (a WSP file), uploads the WSP to the server that is running SharePoint Products and deploys it to the SharePoint farm.

Wesley then creates a new team project using the updated process template which in turn creates a project portal and activates the new custom Feature."

As a process author I can change the visual appearance of the site so I can have my own branding

"Wesley is asked to consult for a Contoso customer who is starting to use Team Foundation Server. The customer likes the out-of-the-box Team Foundation Server sites but wants to change the branding to reflect their own colors and logos."

The branding for the project portals uses standard customization techniques in the UI for SharePoint Products. The branding consists of:

Deployment of image and CSS files through the WSP mechanism
Setting the site logo in a Feature event receivers
Deployment of a theme for SharePoint Products and applying that to the site
In-line CSS styles and HTML mark-up in the pages used to deploy Dashboards

Using the solution package deployment mechanism for SharePoint Products, files can be deployed to the file system of all Web front-end servers in a SharePoint farm. In particular files can be deployed into the "SharePoint hive" which has sub-folders for administrative pages ([SPHive]\TEMPLATE\LAYOUTS), Themes ([SPHive]\TEMPLATE\THEMES), images ([SPHive]\IMAGES), etc.

Site Logos

The site logo for a site is defined by a server-relative URL that points to the image file to use. For example, the default Team Site for Windows SharePoint Services 3.0 has its site logo path set to /_layouts/images/titlegraphic.gif. To change the logo for new sites, first have your logo deployed to a folder in the SharePoint hive. Setting the logo for the site can then be done through the API for SharePoint Products, or through the site definition.

To set the site logo through the API set the SPWeb.SiteLogoUrl property in a Feature event receiver that is activated during site setup. For more information about this property, see the following page on the Microsoft Web site: SPWeb.SiteLogoUrl Property (Microsoft.SharePoint). When working with project portals that use the Team Foundation Server branding, you need to use this method to set the SiteLogoUrl after the Team Foundation Server TfsDashboardBaseUI Feature has been activated; otherwise, it will get overwritten.

To set the site logo through a site definition file, first identify the ONET.xml file used for your site definition (usually under the SharePoint hive in [SPHive]\TEMPLATE\SiteTemplates\<TEMPLATENAME>\xml\ONET.xml). In this file the <Project> element allows a SiteLogoUrl attribute to be set.

Themes for SharePoint Products

When deployed on a server that is running Windows SharePoint Services 3.0 or Microsoft Office SharePoint Server 2007, the project portals apply a theme to SharePoint Products. Themes are collections of images and CSS files that can be linked to a site and override the default HTML styling. The project portals use a theme named "TFSDASHBOARDS" which is deployed under the SharePoint hive in [SPHive]\TEMPLATES\THEMES\TFSDASHBOARDS.

Guidance on creating themes for SharePoint Products is available online.

To set the Theme used for a project portal, ensure the Theme files have been deployed and then use a Feature event receiver to call the SPWeb.ApplyTheme(themeName) method.

When deployed to SharePoint Server 2010 the TFSDASHBOARDS theme is not used and the project portal uses the site's default styling.

In-line Styling for Dashboards

The layout and styling of the Team Foundation Server dashboard pages is determined by a dashboardslayout.aspx file that is deployed as part of the Team Foundation Server SharePoint Features. Each Feature that creates a Dashboard page provisions a "ghosted" copy of its dashboardslayout.aspx file, and then adds Web Part content to the page.

When provisioning your own Dashboard pages, you can take a copy of the file, incorporate it into your Feature and then deploy one or more Dashboard pages from this file. Because the pages are initially ghosted any changes to the dashboardlayouts.aspx file will be picked up immediately in the web browser.

The dashboardlayouts.aspx file defines the structure of the page including the Team Foundation Server dashboard toolbar and the location of the Web Part zones. It also defines a small number of CSS rules that help with spacing and alignment of the Web Parts. Most of the border or color information for the dashboard pages is set by the containing site.

The toolbar that appears on each dashboard page contains controls that provide access to team project data or perform operations on the dashboards and Excel reports. Three of the controls are provisioned as delegated controls:

Portal Link
New Work Item Link
Go To Work Item

The property values used for the controls are defined in the Element Manifest of the TfsDashboardBaseContent Feature. To change the text you can provision a new Control that will override the default version by specifying a lower sequence number (the dashboards use 50). For example to change the New Work Item control to use the name "Create Work Item" you would add the following to your Feature's element manifest file:

<Control
  Id="NewWorkItemLinks" Sequence="30"
  ControlAssembly="Microsoft.TeamFoundation.WebAccess.WebParts, Version=10.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
  ControlClass="Microsoft.TeamFoundation.WebAccess.WebParts.NewWorkItemLinksUserControl">
  <Property Name="ID">newWorkItemLinks</Property>
  <Property Name="TitleText">Create Work Item</Property>
  <Property Name="DisplayMode">PopupMenu</Property>
  <Property Name="TfsName">@default</Property>
</Control>

The text for the Copy Dashboard toolbar button can be changed by adding the Text attribute to the control within the dashboardslayout.aspx file.

The text for the New Excel Report toolbar button cannot be overridden.

Summary

"Wesley recommends that the customer creates a Solution Package (WSP) that contains:

the company's logo that will be deployed to [SPHive]\TEMPLATE\LAYOUTS\IMAGES
a theme for SharePoint Products that is based on the TFSDASHBOARDS Theme and modified to use the customer's branding colors;
an assembly that contains a class that acts as a Feature event receiver which, on activation, sets the site's logo and applies the Theme;
a SharePoint Feature that references the class as its Feature event receiver. The Feature will be activated after the out-of-the-box Team Foundation Server SharePoint Features by appending a <feature> element to the WssTasks.xml file.

Wesley advises that once the code changes are made, the new WSP is deployed to the server, and the modified process template is uploaded to the project collection, then new projects created with that template will get the updated branding."

Figure 7 shows a sample of the types of customizations that could be made, which include:

Changing the site logo
Applying a different Theme
Reorganizing the layout of the dashboard page
Changing names on the dashboard toolbar

Figure 7

Customized Dashboard

Team Foundation Server integrates with SharePoint Products to encourage collaboration between team members. Project portals provide access to Team Foundation Server data within a SharePoint site and the project portals can be customized to suit a team or organization.This document introduced important concepts about project portals. It described the components that work together to create the project portals used with the default Team Foundation Server process templates. It has shown a number of ways in which customizations can be developed so that new project portals will include those changes. The types of customizations illustrated include adding new content, removing or modifying standard content, and changes to the user interface for a project portal.

Share via

Customizing Team Foundation Server Project Portals

Overview of Project Portals

Project Portal Artifacts

Dashboard Document Library and Dashboard Pages

Excel Reports Document Library

Quick Launch Navigation

Dashboard Toolbar

Process Template Content

Team Foundation Server SharePoint Features

Team Foundation Server Site Definition

Team Foundation Server Timer Job for SharePoint Products

Portal Creation Scenarios

Customization Options

Process Template Changes

SharePoint Development

SharePoint Features

Anatomy of Team Foundation Server SharePoint Features

Feature.xml Files

Feature Element Files

Alternate Site Definition Configuration

Solution Packages

Using Out-of-the-box Content as Your Starting Point

Replacing Out-of-the-box Content

SharePoint Site Templates

Dashboard and Process Template Customizations

Example Customizations

As a process author, I want to use my own site definition configuration so that my users have a familiar environment

SharePoint Artifacts

As a process author I want to add a new state so that I can track in-progress work

Updating the Work Item Type Definition

Updating SQL Server Reporting Services Reports

Updating Work Item Queries

Updating Project Portal Excel Workbooks

Feature.xml File

Elements.xml File

Activating Features from the process template

Updating Workbook Details

Updating Project Portal Team Web Access Web Parts

Replacing Existing Dashboard Pages

Editing Existing Dashboard Pages

Packaging and Deploying the Solution

As a process author I want to change the default set of dashboard pages for new projects so that I get my process dashboards instead of Agile or CMMI

Creating and Provisioning a Dashboard

Excel Web Access Web Part

Query Results Web Part

Work Item Summary Web Part

Activating Other Features

Adding links to Quick Launch

Setting a Default Dashboard

Setting the default dashboard through the API

Setting the default dashboard through a web call

Packaging and Deploying the Solution

As a process author I can change the visual appearance of the site so I can have my own branding

Site Logos

Themes for SharePoint Products

In-line Styling for Dashboards

Dashboard Toolbar

Summary

See Also

Other Resources

Forums

Additional resources