Customizing MSF Process Guidance, Part 1: Overview

 

Allison Bokone
Microsoft Corporation

June 2006

Applies to:
   MSF for Agile Software Development v4.0 Process Guidance
   MSF for CMMI Process Improvement v4.0 Process Guidance

Summary: This is first of six companion articles. In this article we give an overview of the MSF Process Guidance and how to customize it. We explain what tools are required for customization, and we tell you where to find additional source files included in the MSF Process Guidance that can be used as part of your customization process.

Contents

Introduction
Required Tools for Customization
Edit Mode versus Run Mode
Overview of Microsoft InfoPath Process Guidance
Microsoft InfoPath Views
Process Guidance Source Files
Conclusion

Introduction

Process guidance is the content that documents your specific software development process. The process guidance complements the process template. For example, if a new WorkItemType is created in the process template, the process guidance should document the WorkItemType and how it relates to Roles and Activities. Team members refer to the process guidance to answer their questions about the process and what they should be doing on a team project.

Visual Studio® Team System 2005 includes two process templates: MSF for Agile Software Development and MSF for CMMI Process Improvement. Each of these processes may be customized and used to develop software in projects. As process templates are customized, the corresponding process guidance should be updated to address any changes that were made.

Workflow for Process Guidance Customization

There is a general set of activities to perform to update process guidance content. Shown here is an overview of these activities; for more information, see the five remaining articles in this series.

  1. Download the most recent version of the process guidance source XML files for the process you want to modify: MSF for Agile Software Development or MSF for CMMI Process Improvement.

  2. Update process guidance source XML files.

    Make your changes and customize the process guidance by editing the source XML files.

  3. Build HTML Pages.

    Use the MSFWinBuild tool to pre-render all the XML source content into HTML files. The HTML files open with static content and yield faster performance.

  4. Verify changes in a browser.

    As you make changes, you can view the changes in a browser to verify that they are correct.

  5. Update the manifest.

    If you created or deleted files during customization, update the manifest in wsstasks.xml to make sure that the correct process guidance files are installed when a new team project is created.

    **Note   **MSFWinBuild automatically updates wsstasks.xml to list the HTML files created by MSFWinBuild.

Required Tools for Customization

The MSF process guidance consists of XML, XSL, and HTML files. You need the following tools to customize the process guidance files.

  • Microsoft Office InfoPath 2003 with SP1.
  • An XML or XSL editor.
  • The MSFWinBuild tool.

Microsoft InfoPath

The source content for MSF process guidance is located in the \Windows SharePoint Services\Process Guidance\Source\XML\ folder where you downloaded and unzipped the process guidance source XML files. A Microsoft InfoPath template (template2.xsn) is provided in this folder to make editing the XML easier.

You can also use an XML editor, but you must understand the underlying XML process schema. Using Microsoft InfoPath and a template makes it easier to read the XML. Microsoft InfoPath is available in Microsoft Office 2003. You must also have the Microsoft Office Service Pack 1 with updates for Microsoft InfoPath. The service pack is available on the Microsoft Office Web site.

An XML or XSL Editor

There are some XSL files that contain content that you can customize. For example, the \Windows SharePoint Services\Process Guidance\Source\XSLs\Principles.xsl file contains the content that appears on the Principles page. You must use an XML or XSL editor to modify these files. You can also use Visual Studio as an XML editor.

The MSFWinBuild Tool

The XML files contain the process guidance source content. When in edit mode, the process guidance infrastructure code interprets the XML through a series of queries to render HTML that is viewed in a browser. However, querying XML becomes slower as the amount of process guidance content grows.

The MSFWinBuild tool builds a set of HTML files that represent all the possible views of the XML source. The HTML files are pre-rendered, so that they load and display more quickly than querying the XML source. This tool is downloadable from the MSF workbench.

Edit Mode versus Run Mode

MSF process guidance is rendered in a browser by infrastructure code that is a collection of JavaScript and XSL files. There are two sets of the infrastructure code and there are important differences between the two:

  • In the \Windows SharePoint Services\Process Guidance\Source folder, the infrastructure code is designed to operate in edit mode. When in edit mode, the infrastructure code interprets the XML through a series of queries to render HTML that is viewed in a browser.
  • In the \Windows SharePoint Services\Process Guidance\Supporting Files folder, the infrastructure code is designed to operate in compiled mode. When in compiled mode, the infrastructure code displays HTML files that are pre-rendered content that display much more quickly.

When you modify the source XML files, you should do so in the \Windows SharePoint Services\Process Guidance\Source\XML folder. The source folder is where all process guidance source is located. There is one XML file for each Workstream and files for the WorkItemTypes, Reports, Queries, and Roles. These files are merged together by MSFWinBuild into a single file, ProcessGuidance.xml. You can check your changes by opening the \Windows SharePoint Services\Process Guidance\Source\ProcessGuidance.htm file. You can modify the ProcessGuidance.xml file to try changes in edit mode. However, know that any permanent changes should be written back to the individual XML files as this file will be overwritten when MSFWinBuild is run again.

When you complete your changes, you should run the MSFWinBuild tool to build and merge all the pre-rendered HTML files that are located in the \Windows SharePoint Services\Process Guidance\Supporting Files folder. You can still make final content checks by opening the \Windows SharePoint Services\Process Guidance\ProcessGuidance.htm file. This file, and all files and folders under \Windows SharePoint Services\Process Guidance\Supporting Files are copied to the team project Web Site when a new team project is created. You can replace these files manually to update an existing project with new process guidance.

Overview of Microsoft InfoPath Process Guidance Template

The easiest way to update the XML source files is to use Microsoft InfoPath and the provided Microsoft InfoPath template. When you open a process guidance XML file in Microsoft InfoPath, you see a row of buttons across the top of a form. Each button represents a view that organizes the content to make it easier to work with specific parts of the content.

The following views are available:

  • Content Item    This view displays content items where each content item reflects a page in the rendered HTML, such as a Workstream page or Activity page. For more information, see Content Item View.
  • Bullet Menu   This view displays the descriptions shared by the index and Roles views; for example, a description of a WorkItemType. For more information, see Bullet Menu View.
  • Glossary   This view displays glossary terms and definitions. For more information, see Glossary View.
  • Image Menu   This view displays a mapping between images and their file locations. For more information, see Image Menu View.

Common Sections

When you work with content items, you see that there are common sections that appear across most of the content types. The following tables show which sections should be completed for each content type.

Common to MSF for Agile Software Development and MSF for CMMI Process Improvement

Content Item Part Type Section RACIType Section Criteria Type Section Cross Type Section
Activity

See Customizing MSF Process Guidance, Part 2: Activities, Workstreams, and WorkItemTypes.

Name and describe how to complete a Step required for the Activity. Name and describe a Role for the Activity, and define the Role as Responsible, Accountable, Consulted, or Informed. Name and describe Entry or Exit criteria for the Activity. Name, define, and describe links to internal or external content. For more information, see Customizing MSF Process Guidance, Part 5: Adding Cross Referencing and CMMI Adherence.
WorkItem

See Customizing MSF Process Guidance, Part 2: Activities, Workstreams, and WorkItemTypes.

Name and describe a Field for the WorkItemType. N/A N/A Name, define, and describe links to internal or external content. For more information, see, Customizing MSF Process Guidance, Part 5: Adding Cross Referencing and CMMI Adherence.
Query

See Customizing MSF Process Guidance, Part 4: Reports, Queries, Views, and Overview.

N/A N/A N/A N/A
Report

See Customizing MSF Process Guidance, Part 4: Reports, Queries, Views, and Overview Pages.

Name and describe a DataSeries or ImageMenuReference for the Report. N/A N/A Name, define, and describe links to internal or external content. For more information, see Customizing MSF Process Guidance, Part 5: Adding Cross Referencing and CMMI Adherence.
Workstream

See Customizing MSF Process Guidance, Part 2: Activities, Workstreams, and WorkItemTypes.

Associate and describe an Activity as a Step required for the Workstream. Name and describe a Role for the Workstream, and define the Role as Responsible, Accountable, Consulted, or Informed. Name and describe Entry or Exit criteria for the Workstream. Name, define, and describe links to internal or external content. For more information, see Customizing MSF Process Guidance, Part 5: Adding Cross Referencing and CMMI Adherence.
Role

See Customizing MSF Process Guidance, Part 3: Roles, RoleGroups, HowTos, HowToProcedures, and WorkProducts.

N/A N/A N/A N/A
HowTo

See Customizing MSF Process Guidance, Part 3: Roles, RoleGroups, HowTos, HowToProcedures, and WorkProducts.

Associate and describe a HowToProcedure as a Step required for the HowTo. N/A N/A N/A
HowToProcedure

See Customizing MSF Process Guidance, Part 3: Roles, RoleGroups, HowTos, HowToProcedures, and WorkProducts.

Name and describe how to complete a Step required for the HowToProcedure. N/A N/A N/A
Overview

See Customizing MSF Process Guidance, Part 4: Reports, Queries, Views, and Overview Pages.

Associate a Step or an ImageMenuReference with an Overview content item. N/A N/A Name, define, and describe links to internal or external content. For more information, see Customizing MSF Process Guidance, Part 5: Adding Cross Referencing and CMMI Adherence.
WorkProduct

See Customizing MSF Process Guidance, Part 3: Roles, RoleGroups, HowTos, HowToProcedures, and WorkProducts.

Associate an image with a WorkProduct using the ImageMenuReference part type. N/A N/A Name, define, and describe links to internal or external content. For more information, see Customizing MSF Process Guidance, Part 5: Adding Cross Referencing and CMMI Adherence.
Disciplines

See "Adding New Views to the MSF Process Guidance" in Customizing MSF Process Guidance, Part 4: Reports, Queries, Views, and Overview Pages.

N/A N/A N/A Name, define, and describe links to internal or external content. For more information, see Customizing MSF Process Guidance, Part 5: Adding Cross Referencing and CMMI Adherence.
Qualities of Service

See "Adding New Views to the MSF Process Guidance" in Customizing MSF Process Guidance, Part 4: Reports, Queries, Views, and Overview Pages.

N/A N/A N/A Name, define, and describe links to internal or external content. For more information, see Customizing MSF Process Guidance, Part 5: Adding Cross Referencing and CMMI Adherence.
Cycles

See "Adding New Views to the MSF Process Guidance" in Customizing MSF Process Guidance, Part 4: Reports, Queries, Views, and Overview Pages.

N/A N/A N/A Name, define, and describe links to internal or external content. For more information, see Customizing MSF Process Guidance, Part 5: Adding Cross Referencing and CMMI Adherence.
Tracks

See "Adding New Views to the MSF Process Guidance" in Customizing MSF Process Guidance, Part 4: Reports, Queries, Views, and Overview Pages.

N/A N/A N/A Name, define, and describe links to internal or external content. For more information, see Customizing MSF Process Guidance, Part 5: Adding Cross Referencing and CMMI Adherence

MSF for CMMI Process Improvement Only

Content Item Part Type Section RACIType Section Criteria Type Section Cross Type Section
AlternativePractice

See Customizing MSF Process Guidance, Part 5: Adding Cross Referencing and CMMI Adherence

Define steps for the standard and AlternativePractice. N/A N/A Cross-reference the AlternativePractice to the CMMI practice it is replacing. For more information, see Customizing MSF Process Guidance, Part 5: Adding Cross Referencing and CMMI Adherence
RoleGroup

See Customizing MSF Process Guidance, Part 3: Roles, RoleGroups, HowTos, HowToProcedures, and WorkProducts.

Associate and describe a Role as a Step, or member, of a RoleGroup. N/A N/A N/A

Note   The content types CMMIDiscipline and CMMIProcessArea should not be modified.

Unused Sections

There are certain values in sections of Microsoft InfoPath that are not currently supported for process guidance customization. The following table lists these values and in what section they occur.

Section Unused value
View Help Map
View Index
View Menu
Content Type ManageWorkItem
Part Type State
Part Type Transition
Cross Type BreadCrumb
Cross Type WebLink
Cross Type MSDN
Cross Type Help
Cross Type WorkItemState
Cross Type WorkProduct
Cross Type Other
Criteria Type Entry

Microsoft InfoPath Views

When you open a process guidance XML file in Microsoft InfoPath, you see a row of buttons across the top of a form. Each button represents a view that organizes the content to make it easier to work with specific parts of the content. The first view that you see is the content view. The content view presents a list of content items. A content item represents an HTML page in the rendered content.

On each view, a list of items is displayed. At the bottom of the list is an editing form. You can edit any item by selecting it in the list. As soon as it is selected, the content for that item appears in the form at the bottom of the list. Then you can make changes in the form.

Four views are used for process guidance customization: Content Item, Bullet Menu, Glossary, and Image Menu.

Content Item View

This view displays content items where each content item reflects a page in the rendered HTML; such as a Workstream page or Activity page. Content items describe and define all entities in the MSF metamodel and let you define your own process guidance elements based on the MSF metamodel. There are many types of content items; such as Roles, WorkProducts, Reports, Activities, Queries, HowTo items, HowToProcedures, and WorkItemTypes.

The content item view is where you document content items and associate them with steps, images, states, transitions, or cross-references. This is also where you assign RACI (Responsible, Accountable, Consulted, Informed) information to specific Roles. For example, in the content view you can insert and describe a new Workstream and all its Activities. You can then add individual steps to each Activity, and add the Activities as steps to the Workstream. You can assign different Roles to different Activities, and also to the Workstream by establishing RACI criteria. Finally, you can create cross-references to link the Activity or Workstreams to internal or external content.

Bullet Menu View

This view displays the descriptions shared by the index and Roles views in process guidance; for example, the description of a WorkItemType. It also displays the side menus that appear in the process guidance. You can easily modify the descriptions and the names of the menus by opening Nav.xml (located in \Windows SharePoint Services\Process Guidance\Source\XML) in Microsoft InfoPath and clicking the Bullet Menu view.

You can add a new side menu, but this requires writing your own XSL, and is outside the scope of these articles.

Glossary View

This view displays glossary terms and definitions.

To add a term to the glossary

  • For MSF for Agile Software Development, open General.xml (located in \MSF for Agile Software Development\Windows SharePoint Services\Process Guidance\Source\XML) in Microsoft InfoPath.

    For MSF for CMMI Process Improvement, open Glossary.xml (located in \MSF for CMMI Process Improvement\Windows SharePoint Services\Process Guidance\Source\XML) in Microsoft InfoPath.

  1. Click the Glossary view.

  2. On the Insert menu, click Section, and then click GlossaryItem.

    A new glossary item section appears at the bottom of the form.

  3. In the Term field, type the name of the new glossary term.

  4. In the Definition field, type the definition of the term.

  5. Save your changes.

Image Menu View

This view displays a mapping between images and their file locations. Image files must be located in the Process Guidance\Supporting Files\images folder and also to the \Windows SharePoint Services\Process Guidance\Source\images folder. As soon as an Image Menu item is defined, it can be referenced from many different content items.

To add an image menu item

  1. Open General.xml in Microsoft InfoPath, and then click the Image menu view.

  2. On the Insert menu, click Section, and then click ImageMenu.

    The new image menu appears at the bottom of the image list.

  3. In the image menu form, set the Menu Name field to a unique name that identifies the image. For example, "unhealthyproductivity" is a name that identifies an example image of an unhealthy productivity report. Consider making the name all lowercase to make it easier to reference later.

  4. Set the Menu Image field to the folder and file name of the image. All images must be located in \Windows SharePoint Services\Process Guidance\Source\images and in Process Guidance\Supporting Files\images. For example, if the unhealthyproductivity.gif file is in the images folder, you would set the Menu Image field to "images/unhealthyproductivity.gif."

  5. In the Menu Description field, type a description of the image.

  6. Save your changes.

    Note   You must associate the image with a content item with which you want it to display. Unless the image is associated with a content item, it will not be displayed.

Process Guidance Source Files

Process guidance has many files associated with it, and some of them you may want to customize to meet the needs of your software development process.

CMMI Process Design Source Files

Before your team starts writing XML files to define a process, it is helpful to map out all the Workstreams and Tracks in the process. This allows for your team to visualize the process, and identify areas where the process is weak or disconnected. Each Workstream and Track in your process should be diagrammed and documented.

Diagrams

Every Workstream and Track for your CMMI process should be mapped out before your team starts writing the XML to implement the process. These mappings can be visualized easily with diagramming programs such as Microsoft Visio. MSF for CMMI Process Improvement currently uses the notation proposed in the document UML Profile for Enterprise Distributed Object Computing.

Documents

As soon as you have a diagram of a Workstream or Track, you should make the mapping complete by adding information to the diagram in a document by using an editor such as Microsoft Word. Copy and paste the diagram into a new file and add sections for information pertinent to that Workstream or Track.

For example, the Workstream "Perform Quality Assurance" contains the following sections: Roles, Timing, Inputs, Outputs, CMMI Cross Reference, and Miscellaneous. The Roles section is where RACI criteria is assigned to specific roles. Certain work items and work products are listed under inputs, and others are listed as outputs together with reports and queries. CMMI levels, goals, and practices associated with the "Perform Quality Assurance Workstream" are listed in the CMMI Cross Reference section. Any other information your team wants to document would go under Miscellaneous.

Images, XML, and XSLs

Process guidance has many files associated with it, and some of them you may want to customize to meet the needs of your software development process. The GIF images, source Microsoft Visio diagrams, XML files, and XSL files for process guidance are located in their respective folders under \Windows SharePoint Services\Process Guidance\Source.

Images Folder

This folder contains the GIF images for all the diagrams and images that are used for MSF process guidance. You may want to modify these images and diagrams. The Microsoft Visio files for the diagrams are located in the Images\Source folder. Use these files to modify the more complex GIF images. Images that do not have corresponding Visio files can be edited in a graphics editor such as Microsoft Paint.

Source Folder

This folder contains the Microsoft Visio file for MSF process guidance diagrams. To modify these diagrams, open the file in Microsoft Visio and make your changes. Then export the diagram as a GIF file and save it in the Images folder. Save the Microsoft Visio diagram in the Images\Source folder.

XML Folder

The process guidance is split into multiple XML files to help Microsoft InfoPath run more efficiently. The files are organized by the content item type definitions they contain, and are named accordingly.

Typically, each Workstream in a process is represented in its own XML file. All the Activities associated with a Workstream are declared in the same XML file as the Workstream. The XML file is named WorkstreamName.xml. To create a new Workstream, you should create a new XML file from the file Blank.xml. For more information, see Blank.xml.

Additionally, other content items are grouped together in XML files that contain definitions for only one content item type, such as Reports.xml and WorkProducts.xml. HowTo.xml contains all the definitions for HowTos and their corresponding HowToProcedures. Other content items are grouped together in similarly named files, or they are defined in General.xml.

Template2.xsn is the Microsoft InfoPath Form Template that you must have to open the process guidance XML files in Microsoft InfoPath.

XSLs Folder

This folder contains XSL Stylesheet documents for MSF process guidance. XSL files control the look-and-feel of content and also have content in them; such as text descriptions that display in the process guidance that you may want to customize.

Blank.xml

Each Workstream typically has its own XML file that contains definitions for the Workstream and all its Activities. Having multiple XML files for process guidance allows for Microsoft InfoPath to run more efficiently. Process guidance XML files are located in \Windows SharePoint Services\Process Guidance\Source\XML.

Using Blank.xml to Create a New Workstream

To create a new Workstream for your software development process you should use the Blank.xml file. Open the file in Microsoft InfoPath, click Save As, and rename the file Workstream Name.xml in the \Windows SharePoint Services\Process Guidance\Source\XML folder. Then you can use Microsoft InfoPath to add a Workstream content item and Activities. For more information, see Customizing MSF Process Guidance, Part 2: Activities, Workstreams, and WorkItemTypes. Reuse Blank.xml every time that you want to create a new Workstream.

Process Guidance Version File

Every process guidance has a version file located in the \Windows SharePoint Services\Process Guidance directory. There is also a separate version file for the process template located in the root folder of the process template.

Each process guidance version file contains a GUID uniquely identifying the process guidance content. When you customize the process guidance content, you must modify the corresponding version file to give it a custom GUID unique to your custom process guidance content.

**Note   **If you do not give your custom process content a custom GUID, the installer may overwrite your customized content with the standard version.

The process guidance version file also contains a version number that you can modify to keep track of your updates and changes.

Syntax

Type=guid
Version=N.NN. NNNN.NN

Parameters

Type is a GUID that uniquely identifies the process guidance content.

Version is a number that identifies the version of the process guidance or content.

Conclusion

In this first of a six part series, we have given you an overview of process guidance customization and explained what tools are required to modify your process guidance. See the following articles for more information about how to customize your MSF Process Guidance:

© Microsoft Corporation. All rights reserved.