Details on Modifying Out of the Box SharePoint Site Templates for TFS 2008

For a long time I have wanted to get around to writing precise instructions on how to modify the out of the box MSF for Agile Software Development and MSF for CMMI Process Improvement process templates with respect to the SharePoint sites they generate. Based on questions from recent TFS 2008 consulting engagements, I believe the time is now. Typically, my customers want to change three things about the SharePoint site:

1. Default document libraries

2. Default document templates within document libraries

3. Add additional sites, such as a Team Wiki page

In this blog post I will outline step by step precisely how to accomplish this, which will mean making modifications to an existing process template as well as modifying an existing site collection and saving it out as a SharePoint template. These instructions will not include any other modifications to the process template such as adding/modifying work item templates, or adding new queries. I will hopefully be able to address these in a future blog.

The first idea to get into our heads is that the final portal site is actually a combination of two components: content in the site template + content in the process template.  The details of this combination between these two will be outlined in this post.

Step 1 – Downloading the Process Template and Changing the Name

First, from the Team menu, select Team | Team Foundation Server Settings | Process Template Manager. This will show the following dialog:

From this dialog, choose your desired template and select the Download button. From the subsequent Download Process Template dialog, select a folder and save out the process template (the folder saved will have the same name as the title of the process template above). Now open the process template folder and locate the ProcessTemplate.xml file. Open this file with Notepad. Look for the <name> element and modify this name to something unique. This is the name that will show up in the dialog just above. This is an example of what you should see in the file, presuming you have chosen the MSF for CMMI template:

<name>MSF for CMMI Process Improvement - v4.2</name>

You won’t need to modify anything else in this file, so go ahead and save it, and then close the file.

Step 2 – Modifying Default Work Items

Have you noticed that when you perform the All Work Items query after a TFS project is first created, that it has a set of default tasks? We will now see how you can modify these default tasks to your liking. Presuming you still have the top level folder open for the process template, you will see a folder named WorkItem Tracking. Open this folder. You will find the workitems.xml file. Open this file. You will find the default task entries beginning with the following for MSF Agile:

<WORKITEMS>

  <WI type="Task">

    <FIELD refname="System.Title" value="Setup: Set Permissions" />

    <FIELD refname="System.Description" value="Add team members to one of the four security groups: Build Services, Project Administrators, Contributors, or Readers. To configure security, right-click the team project in Team Explorer, and select 'Team Project Settings,' and then select 'Group Membership'." />

    <FIELD refname="System.IterationPath" value="$$PROJECTNAME$$\Iteration 0" />

    <FIELD refname="System.State" value="Proposed" />

    <FIELD refname="System.Reason" value="New" />

  </WI>

…

Modify or delete these entries as desired, and afterwards close the file.

Note that in this file you can also specify new work item types or delete the existing work item types. The actual work items and queries are in the folders below.  We won’t be covering this in this post.

Step 3 – Modify the SharePoint Site and Save as a Template

Within Visual Studio, select a TFS project consistent with the process template that you selected above (specifically, a test project whose SharePoint structure you don’t mind modifying), and right-click on the TFS project node. Select the Show Project Portal option from the context menu, which will launch the corresponding project portal. Modify the site structure as desired, which could mean, for example, deleting the existing document libraries and adding your own consistent with your project methodology phases. Also add any sites you desire, such as a Team Wiki. Before doing this, though, there is a key task that you need to accomplish, as well as decide on a route for originating site content which highlights the fact that elements in the SharePoint site may be driven either from the process template or the SharePoint site template. Click on the Documents link in the Quick Launch bar on the left, which will take you to the All Site Content page. You should see the following for the MSF for CMMI template:

Notice the Process Guidance document library. This will cause a problem for you when you attempt to export the site template because the limit to the size of a SharePoint template is 10MB. You will have to delete this, and there are no worries because all of the process guidance is actually in the process template itself that you previously downloaded, thus the process template provides this so it doesn’t need to be included in the SharePoint template that you export. In order to see where the actual Process Guidance content is, navigate to the Windows SharePoint Services folder of the process template you exported. You will see a folder named Process Guidance beneath this folder.

Now notice that you will see other subfolders in the Windows SharePoint Services folder of your exported process template that directly correspond to the default folders in the SharePoint site as seen below, which is a snapshot of the MSF for CMMI process template Windows SharePoint Services folder::

What this demonstrates is a combination of routes you can take to decide what document libraries and documents show up in SharePoint and how, which is a bit confusing. As the out of the box templates stand, the documents are actually stored in the process template and are uploaded to the appropriate document library when a SharePoint site is generated. However, even though the document libraries are enumerated in the process template (in the WSSTasks.xml file as shown), they also exist in the site template. I think the reason for this is because document libraries created from the process template can’t be added to the Quick Launch links on the SharePoint site. Thus, the decision was made to manually add the document libraries to the site template, specifying that each document library would show up in the Quick Launch. So basically, the document libraries are redundant in the out of box process templates. As for you, you can add your own document libraries to the process template instead of the site template and they will be created, but they just won’t show up in the Quick Launch.

The supposed advantage to driving the creation of document libraries from the process template is that if you want to use one site template with multiple process templates, then you could just put all process-specific document libraries and documents in the process template. If you instead choose to have the same document structure in all site templates, then you can load the documents and document libraries in the site template and not have them in the process template. You would generally just leave the Process Guidance alone, unless you didn’t want that to be available for some reason.

My preference would be to take the default route where the process template drives all site content, but given the fact that you can’t generate Quick Launch links from the schema in the process template, the realistic alternative is to create the document libraries in your site template and add them to the Quick Launch. If you want to include additional sites such as a Project Wiki, go ahead and create that in the site as well. Below is how my site looked after preparing it for export:

Now, to export the site, here are the steps:

1. Click on the Site Actions | Site Settings menu, which will take you to the Site Settings page.

2. Under the Look and Feel heading, select the Save Site as a Template link.

3. Provide a file name, name, description, and select include content if you have added any document libraries or sites that you would like to be in all sites.

4. Select OK to save the site template. When you save your site as a site template it, gets saved into your site collection's site template gallery.

5. Under the Galleries heading of the Site Settings page, select the Site Settings link, which takes you to the Site Template gallery.

6. Click on the name of your site template and it should ask you to download a file (which will be an .stp file). Go ahead and save the file.

7. You will now need to upload the site template to the global site template gallery so TFS can find it when it creates the SharePoint site. This will require the stsadm.exe command line tool.

8. Open a command line running with Administrator privileges.

9. Navigate to C:\Program Files\Common Files\microsoft shared\Web Server Extensions\12\BIN, and copy the .stp file into this folder.

10. Run the following command: stsadm.exe -o addtemplate -filename yoursite.stp -title "Your Site Name" -description "Description of Your TFS Site" . For the site name, the convention for the out of box templates is to name them VSTS_MSF_<type>, such as VSTS_MSF_CMMI and VSTS_MSFAgile (okay, in the second case, not quite).

11. Now we need to verify the upload of the site template. Go to Start | Administrative Tools | SharePoint 3.0 Central Administration.

12. Click on the Application Management tab and under the SharePoint Site Management heading, click the Create site collection link.

13. In the Template Selection section, select the Custom tab. You should see the template you uploaded to the global site template gallery.

Okay, so now we have the template uploaded. Now we must continue modification of the process template to point to this new SharePoint site template.

Step 4 – Modifying Windows SharePoint Files and Folders in the Process Template

Now we will modify the process template to suit. Once you understand the process that TFS uses to assemble the final SharePoint site, you will see how flexible TFS is in terms of dealing with default content that shows up in the SharePoint portal. First, navigate to the Windows SharePoint Services folder under the top level folder of the process template, just as you did for the WorkItem Tracking folder. Here you will find the WssTasks.xml file. Open this file and note the following element near the top of the file:

<site template="VSTS_MSF_CMMI" language="1033" />

This site template name is the name of the SharePoint template that TFS uses to generate the portal for each TFS project. Modify the name of the site template to exactly match site name used when you ran stsadm.exe above (which is the same name you verified in the global site template gallery above). For example, your site template name might be VSTS_MSF_Custom_SDC.

Next, inspect the <documentLibraries> section immediate below the <site> element:

<documentLibraries>

    <documentLibrary name="Solution Design" description="Documents for the architect team" />

    <documentLibrary name="Build and Stabilize" description="Documents for the test team and developers" />

    <documentLibrary name="Project Management" description="Documents for the project management team" />

    <documentLibrary name="General Documents" description="General documents for the team" />

    <documentLibrary name="Requirements" description="Documents for the business analyst team" />

    <documentLibrary name="Process Guidance" description="Process Guidance for the team documents" />

</documentLibraries>

You can modify these as needed to produce the document libraries you desire. If you want to put actual documents in these document libraries, you will do so in <files> section below, which we will discuss next.

Notice now that most of the remainder of the file is taken up by entries for the Process Guidance files, all of which point to each individual file in the Process Guidance folder. Additionally, towards the bottom of the file, you will also find entries for General Documents. If you don’t want the General Documents, then you will need to delete the <documentLibrary> element above and all of the corresponding <file> elements in the document.

Immediately below the General Documents <file> elements you will find any files destined for the other document libraries. For example, the MSF for CMMI process template has a single entry as seen below:

<file source="Windows SharePoint Services\Test\Test Approach.doc" documentLibrary="Test" target="Test Approach.doc" />

You can delete this and add your own files to the Test document library. Just make sure you place the documents in the appropriate folder, which should map relatively to the <file> element entries in the document as shown above. If you have created new document libraries, you will have to create the appropriate folders and put your documents in the folders. If you delete any of the existing <file> entries, you’re not required to actually delete the files themselves in the process template folder structure. TFS will only install the files in the template that are specified in the WssTasks.xml document.

You are now done editing the WssTasks.xml file, so you can close it. Next, we will upload your new template and try it out.

Step 5 – Upload and Test Customized Process Template

From the Team menu in Visual Studio 2008, select Team | Team Foundation Server Settings | Process Template Manager. Select the Upload button and point to your updated process template folder. TFS will then begin the upload. When the upload has completed, you will see your new process template in the list.

Now we will create a TFS project using the new and improved process template. Right-click on the server node at the top of Team Explorer, and select New Team Project. Provide a name, click ‘Next,” and then select your new template. Accept all defaults and select Finish to begin creating the new TFS project. After a few minutes you will have your new site template. Congratulations, and I’m confident this will be much easier for you the next time.

Addendum: Key Differences with Team Foundation Server 2010

With Team Foundation Server 2010, process guidance for the out-of-the-box templates is distributed as MSDN online content. By default, (and to support older TFS Clients) a small number of HTML files that redirect users to online guidance are provisioned to the project portal. You could do a similar thing and either redirect users to online guidance or take the existing process guidance from a project portal, host it somewhere central to your sites and then provision HTML redirect files that point to your hosted location.

The name and paths of the files are important because they are expected by the Team Foundation Server clients when opening process guidance for individual work item types.

The structure expected in the process guidance document library is:

[Process Guidance Document Library]

ProcessGuidance.html

Supporting Files\

    ProcessGuidance.htm

    AboutWorkItems.htm

    [Work-item-name].htm

Each Work Item Type has a corresponding HTML file which is displayed when process guidance is selected for a work item. The AboutWorkItems.htm file is used instead if the HTML file for the specific work item can't be found.