Using the Office Requirements Authoring Starter Kit (Part 1 of 2)
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
Applies to: Microsoft Visual Studio 2005 Tools for the Microsoft Office System, Microsoft Visual Studio 2005 Team System, Microsoft Visual Studio 2005 Team Foundation Server, Microsoft SQL Server 2005, Microsoft Windows SharePoint Services, Microsoft Office Word 2003
Summary: Learn how the Requirements Authoring Starter Kit (RASK) can help software development teams collect, interpret, distribute, and synchronize project requirements in a structured Word document using Microsoft Visual Studio 2005 Tools for the Microsoft Office System and the Microsoft Visual Studio 2005 Team Foundation Server. (10 printed pages)
The Requirements Authoring Starter Kit (RASK) provides a customizable requirements-authoring solution for software development teams. RASK serves two purposes. It provides the basis of a Requirements Authoring solution and illustrates how to access Microsoft Visual Studio 2005 Team Foundation Server programmatically from Microsoft Visual Studio 2005 Tools for the Microsoft Office System (Visual Studio 2005 Tools for Office). RASK has broad functionality that you can extend with minimal effort.
RASK integrates several Microsoft products into the solutions: Microsoft Office Word 2003, Visual Studio 2005 Tools for Office, Microsoft SQL Server 2005, and Microsoft Windows SharePoint Services. In addition, RASK uses Microsoft Visual Studio 2005 Team Suite and Visual Studio 2005 Team Foundation Server, which are part of the Microsoft Visual Studio 2005 Team System.
RASK is not a complete requirements-authoring application and is not intended to compete with existing requirements-management applications.
This article, Requirements Authoring Starter Kit (Part 1 of 2) introduces the features of the starter kit. The second article, Using the Office Requirements Authoring Starter Kit (Part 2 of 2) introduces the code that enables each RASK feature.
RASK illustrates a concept for authoring software-development requirements in a team environment. Because requirements inevitably change throughout a project life cycle, a shared view of requirement information is critical. For example, in a project where many people are responsible for collecting and interpreting requirements, changes can result from refinement of the design or from requests by the team members. In such an environment, the overhead of a large-scale, requirements-management system can be daunting, and teams resort to exchanging stand-alone requirements documents. This can lead to information overload and an inability to fully realize the impact of changes when they occur.
RASK takes a pragmatic middle ground between heavy process and improvised requirements management. It enables project managers to distribute the collection of requirements among many business analysts, each of whom works in familiar, structured Word documents. These documents are not ordinary, however. Requirements can be saved to a SQL Server database. This database becomes the point of consolidation, and Word serves as a fully featured formatting and data-entry tool. Contrast this to the awkward and time-consuming process of merging and reconciling multiple documents manually, which is often the norm.
With project requirements consolidated in a structured way, RASK connects them to indicate dependencies and relationships. When a requirement changes, team members are notified to review related requirements for potential impact. By moving change information to earlier in the process and providing it effectively, RASK can have a dramatic effect on project success and cost control.
From a SQL Server database, RASK automatically generates a consolidated Word document that contains all of the requirements from each source. RASK can do this whenever you modify a requirement. Having the requirements in document form facilitates review by team members, users, and project sponsors. In addition, they can print or format the document, or use it offline. Such capabilities contribute to convenient and accessible communication.
Using RASK, you can store requirements documents on a Windows SharePoint Services site, which makes them easy to locate on an organization's intranet. Using Windows SharePoint Services, team members can see document histories and version information, and they can submit comments within the body of a document.
Communication with Engineering Teams
Although project managers and business analysts typically lead requirement authoring, the process is also important to software engineers. Requirements determine the solution design and result in specific development tasks for engineers. Visual Studio Team Foundation Server, which is part of Visual Studio Team System, provides team-level information for engineers. It also provides the ability to manage work items for an entire team.
With RASK, you can synchronize requirements and work items so that engineers have one place to manage the project workload. RASK can create work items that represent specific requirements, and then embed a URL in a Word document that points to the requirement that is stored within a different Word document that resides on SharePoint site. The URL enables engineers to locate requirement details quickly. The URL is embedded in the Visual Studio Team Foundation Server Work Item (Links tab), and allows engineers to locate requirement details in context. As the project progresses, you can add other work items to clarify the true cost and complexity of additional requirements.
The following software is required to implement RASK:
Microsoft Office 2003 with Service Pack 2 (SP2); use an Edition that includes Word and Microsoft Office Outlook 2003
Microsoft Visual Studio 2005 Tools for the Microsoft Office System
Microsoft SQL Server 2005
Microsoft Windows SharePoint Services 2.0 with SP2
Microsoft Visual Studio Team Foundation Server
Microsoft Visual Studio 2005 Team Suite
Microsoft .NET Framework 2.0
RASK integrates several Microsoft products and technologies, as shown in Figure 1.
Figure 1. The RASK architecture
Word 2003 and Visual Studio 2005 Tools for Office
The RASK application is hosted in a Word document template as a custom task pane (also known as an action pane). Hosting is implemented using Visual Studio 2005 Tools for Office, which provides for design of the task pane using the same visual tools used to design Microsoft Windows Forms applications. It also provides the ability to interact with Word, or other Microsoft Office applications, through their exposed object models. This can all be done using managed code in any Microsoft .NET language, and in this case, using Microsoft Visual C#.
The key feature in Word 2003 that allows it to be used as a front end to Microsoft SQL Server is its ability to tie documents to XML Schema Definitions (XSD). This imposes enough structure on the document to get data into and out of it in a predictable, programmatic manner. To prevent users from breaking the structure, you must use the document-protection feature in Word to limit edits to areas within the structure.
A limitation of using Word out of the box is that if you choose to simply bind an XSD to a Word document and then turn on document protection, there are two obstacles you must to overcome. First, you need to turn off document protection to add new XML nodes. Secondly, most Word users probably do not even know what XML is. Therefore, you do not want to require them to add nodes at all. RASK provides user-friendly UI to add and remove nodes. The ability to create rich task panes easily in Visual Studio 2005 Tools for Office solves this problem. The document remains protected, but user-friendly buttons in the task pane add and delete XML nodes as appropriate. Behind the scenes, document protection is turned off and on, as required, to make these structural changes and maintain schema validation. Figure 2 shows the Word interface to RASK.
Figure 2. The Word interface to RASK
SQL Server 2005
Requirements flow between Word and Microsoft SQL Server to save requirements from many documents, and then consolidate them into a single document. Requirements are stored in WordprocessingML in the SQL database. This provides the ability to save all formatting and embedded objects that Word supports in full fidelity in the database.
Interaction with the database takes place through the native XML Web services interface to SQL Server, which is especially powerful in RASK because mapping between SQL Server and the XSD-bound Word document is easy. The Web service uses HTTP and SOAP to communicate between Word and the database.
In addition to XML Web services, RASK takes advantage of these new SQL Server 2005 capabilities:
Stored procedures use TRY/CATCH error-handling constructs.
Full-text indexing of XML data enables requirements searching.
PATH mode in FOR XML queries offers a simple way to create highly complex XML documents from SQL data.
OPENXML extracts data from XML documents for use in traditional Transact-SQL (T-SQL) queries. For more information about T-SQL, see Transact-SQL Overview.
Visual Studio 2005 Team Foundation Server
Visual Studio Team Foundation Server is part of the Visual Studio Team System. RASK integrates with Visual Studio Team Foundation Server to link requirements documents to team projects and to synchronize work items. Communication occurs through the Visual Studio Team System Extensibility Kit, which provides a programmatic interface to Visual Studio Team Foundation Server.
Windows SharePoint Services
RASK integrates with Windows SharePoint Services to use its document-storage and versioning features. Part of this integration requires no code development. That is, users can use built-in features to save requirements documents in a SharePoint document library. Documents can be conveniently stored on a SharePoint site automatically created for each team project by Visual Studio Team Foundation Server, or in any other SharePoint document library.
The other integration involves the synchronization of work items with Visual Studio Team Foundation Server, described above. Work items in Visual Studio Team Foundation Server have a Links tab where you can add different types of links, including URLs. We created a custom work item, called a Requirement work item, that includes the Links tab. When we create Requirement work items, we add a URL to the Links tab that points to the requirements document stored in a SharePoint document library. The Requirement work item includes a Word bookmark to the location in the document that has the matching requirement.
Integration with Outlook is demonstrated through a RASK feature that creates tasks and initiates task requests from within a Word document. This is accomplished by programmatically automating the Outlook object model.
Remember the overall RASK architecture as you read the following walkthroughs of each feature from a user's perspective. Using the Office Requirements Authoring Starter Kit (Part 2 of 2) provides code examples that demonstrate RASK features.
RASK organizes requirements by project: specifically, a team project in Visual Studio Team Foundation Server. To create requirements in RASK, you must first set up the team project in the Team Explorer pane in Visual Studio Team Foundation Server. The example shown in Figure 3 is Team Project 1.
Figure 3. A team project in Visual Studio Team Foundation Server
Next, you create a document in Word based on the Requirements Authoring.dot template. Notice the Document Actions pane to the right of the document. Select the team project that you previously set up in Visual Studio. Under the Actions button, select Create Template (Figure 4). This uses XSD to bind an empty Word document to the project so that business analysts can enter new requirements into it. This procedure is discussed in Part 2 of this article.
Figure 4. Under Actions, click Create Template
At this point, RASK links the document to the team project, which is ready to accept new requirements.
Adding and Editing Requirements
To add requirements, you first use the Document Actions task pane to establish the requirement, and then enter the requirement itself in Word. To establish the requirement, click the Requirement button, and then click the Add Requirement command, as shown in Figure 5. RASK has three types of requirements (Scenario, Quality of Service, and Task), all of which map to Requirement work item types in Visual Studio.
Figure 5. Under the Requirements menu, you can add new requirements
RASK then inserts a placeholder for the requirement into the body of the Word document. It also starts building an outline view of the requirements in the Document Actions task pane. Although RASK maps this outline to an XML Schema behind the scenes, the user only interacts with a user-friendly interface in the task pane of Word. The user enters the project requirement with rich formatting, embedded objects, or graphics using any feature Word offers to format text (Figure 6). Data entry is limited to within square brackets, which indicate unlocked areas in the document. Conversely, the locked areas protect the structure of the requirements to enable sending them to the database.
Figure 6. You can use all the typical Word features
After the user enters a requirement, other options appear on the Requirement menu:
To delete requirements
To add sub requirements up to three levels deep
To move requirements up and down in order
These commands work on the requirement currently selected in the Outline view in the Document Actions task pane (indicated in bold).
Saving Requirements to SQL Server 2005
You can store requirements in the database at any time using the Save to SQL Server 2005 command on the Project button (Figure 7). This saves the current content of the document, in a structured way, to the database using the native XML Web services interface. Because the content is stored in WordprocessingML, you do not lose formatting or embedded objects that you added in Word.
Figure 7. Under the Project menu, you can save your requirements
Because RASK is a multi-user system, users can work in separate Word documents attached to the same project. When they enter requirements in those documents and save them to the SQL Server 2005 database, RASK automatically consolidates the requirements.
Users can save the document itself to a disk. Although this does not update the database, it can be a useful way for the user to save work in progress, take the document offline between data store updates, or use document version history in Windows SharePoint Services.
Syncing Requirements with Visual Studio Team Foundation Server
To link the assignments of developers and test engineers to Requirement work items, you can synchronize requirements with Visual Studio Team Foundation Server. Doing so also provides reporting features.
To synchronize requirements, you must first save a copy of the requirements document to a server running SharePoint Portal Server, into the SharePoint site automatically created by Visual Studio Team Foundation Server for the project (Figure 8). Next, you must execute the Sync With Team Foundation command in Visual Studio Team Foundation Server (Figure 7).
Figure 8. Saving a copy of the requirements document on a document library
Requirements then appear as work items in Visual Studio, with a custom type named Requirement (Figure 9). On the Links tab, in the lower half of the screen, is a URL for each requirement. The link is a bookmark that links to the appropriate section in the Word document, enabling engineers to easily reference the original requirement.
Figure 9 Work items in Visual Studio
Double-clicking this link opens the Word document and displays the requirement (Figure 10).
Figure 10. Viewing the requirement in Word
Before you can create Requirement work items in Visual Studio Team Foundation Server, you must first create a custom Requirement work item in your team project. For more information about how to do so, see Adding and Editing Requirements.
Generating a Consolidated Requirements Document
To review requirements or share them beyond the immediate team, you can generate a consolidated document of all requirements in the database. First, you create a document in Word based on the Requirements Authoring.dot template, and then you use the Generate Document command under the Actions button. (Figure 4).
This feature is important if you have multiple users. (For example, if many analysts enter requirements and a project manager needs a consolidated report.)
Reusing requirements is important as the number of requirements grows. It is also an effective way to create a corporate repository of commonly used requirements. RASK provides search and copy features to help you locate requirements for reuse.
You use the Action button to access search features in RASK. You can search requirement names only or search both the requirement name and detail content (Figure 11). RASK displays results on the Global Requirements tab.
Figure 11. Search by requirement name and detail
To copy the content of requirements in the search results, select the requirement on the Global Requirements tab, and then select a requirement from the outline in the Project Manager tree view. You can then use the Copy Description to New Child Requirement command, and the text of the requirement is added as a new child requirement. You can name and edit the new requirement as you would any other requirement.
Creating Requirement Dependencies
As discussed previously, the earlier in the process that your team can realize the impact of change, the more successful your projects are likely to be. RASK can help you identify change early by explicitly defining requirement dependencies and storing dependency information in your project's database.
To create a dependency, you select a requirement from the tree view in the project summary. Then, you select a related requirement from the list on the Dependencies tab. Finally, you right-click that requirement, and then choose Create Link (Figure 12). The chain link icon that appears indicates that the dependency exists.
Figure 12. Linking requirements
You can use this procedure to create any number of dependencies for a requirement. The relationships are bidirectional. (For example, if requirement A depends on requirement B, RASK also considers requirement B to depend on requirement A.)
You can remove dependencies by following a similar procedure to unlink two requirements, by right-clicking and using the Sever Link command.
Flagging Requirements That Need Review
With requirement dependencies established, RASK can automatically notify users of requirements that need review when a related requirement changes. To do this, RASK looks for changes to requirements since the last time you generated a consolidated requirements document. If RASK finds changes, it flags related requirements in the Project Summary tree view with an icon (see Figure 13). The project manager or other reviewer can then assess what action is necessary and apply the appropriate edits to the document.
Figure 13. Changes are flagged
Sending Outlook Task Requests
Users can send an Outlook task request from the requirements document. To do this, the user verifies that the document is saved in a SharePoint document library so that the URL is accessible. When the user chooses the Task Request command on the Project button (Figure 7), a form opens for the user to type the task name and the recipient's e-mail address (Figure 14). RASK includes a URL to the document to make it easier for the recipient to reference the document after receiving the task.
Figure 14. Sending a task request
After the user clicks Send, the user sees a warning message asking for permission to automate Outlook. When the user grants permission, RASK adds the task to the user's task list in Outlook (Figure 15). It also creates a task request for the specified e-mail address and places it in the user's Outlook Outbox. In both cases, the task reflects the information entered in the Task dialog box, including the URL to the document on the SharePoint site.
Figure 15. Outlook integration
This article walks through how RASK integrates several Microsoft products to provide a requirements-authoring solution and illustrates how to connect to Visual Studio Foundation Server programmatically. Using the Office Requirements Authoring Starter Kit (Part 2 of 2) introduces the code that enables each RASK feature.
Visual Studio 2005 Tools for Office
Office Developer Center
Windows SharePoint Services