[Saving the least creative (but just as important as all other steps), chapter until last.]

In this chapter we discuss a method for managing traceability between these requirement types using MS Office SharePoint Server (MOSS). Traceability tables are managed within SharePoint lists and different views are created to display traceability from the desired viewpoints.

Why SharePoint? I do not recommend using SharePoint for managing traceability, but in the absence of any alternative (except possibly MS Excel, Word or similar documentation tools), it does allow some automation of traceability. The following is a list of the functions that I expect my requirements traceability tool to provide.

· Links to requirements, that may be accessed from other tools, such as MS Word, Visio or even Excel. (Ideally, the toolset is a fully integrated development environment with full support for UML).

· The ability to be able to cross-reference requirements, hence forming traceability links.

· The ability to be able to flag traceability links as suspect, and automatic notification when one of the requirements in a traceability link has changed.

· The ability to add attributes to requirements, such as priority, assignation, notes etc.

· The ability to be able to enter a customizable traceability model into the tool and have the tool enforce the traceability and structure rules of the model. (Ideally, the tool can parse a traceability model built with UML and enforce the model relationships, classes and attribute types.)[1]

· traceability trees, showing links from top-level to all lower-level requirement types, and vice-versa,

This section describes one method for organizing requirements such that traceability tables may be created between them. Other structures and tools may prove more effective for different situations.

It describes the requirements repositories, the method used to trace each requirement type and processes used to manage changes to requirements and their traceability.

17.1 Overview

· Business Use Case Steps are linked to a SharePoint list, of Candidate Use Cases.

· Business Rules (BR) are entered directly into SharePoint lists and managed there.

· Application Use Cases (AUC) are managed within documents stored in SharePoint.

· Application Use Case Steps may be hyperlinked to a SharePoint list of software requirements (optional).

· Change Request (CR), Issue (ISS) and Risks (RSK) are entered directly into SharePoint lists.

17.2 CRs, ISSs and RSKs

The CR, ISS and RSK are not requirements by definition (i.e. they are not tested), but are types of ‘Item’ that may be traced from requirements. They may be managed in a similar manner to requirements using the same tools.[2]

Managing these items in SharePoint, (or a issue/bug/change request tracking tool) is outside of the scope of this work. I simply assume that they are managed within their own repository and make reference to the components in SharePoint that they impact.

All Issues, Change Requests and Risks for a application are shown as being stored in a single table[3], as in Figure 1:. The item is given an attribute identifying whether it is of type, ISS, CR or RSK. All items are linked to the a requirement that it impacts. The link is to the highest level requirement in the traceability tree. If multiple requirements are impacted, then only one entry is made in the table.

· Status – Proposed (no cost or date has been assigned), Approved (a cost and date has been assigned to the item), Implemented (the item has been completed and may be closed).

· Priority – Must Have (the item must be resolved prior to release of the product), Work Around (the product may be released without this item being resolved), Nice To Have (implemented if time and effort exists, but will not cause testing to fail).

· Cost – Estimate of how much it is going to cost to resolve this item; may be a $ or hour estimate.

· Assigned To – The person responsible for addressing the status of the item.

· Risks take additional attribute in the form of probability that the risk will occur. This is applied to the cost in order to identify the impact to the product.

· Action – The action to be taken, or taken to resolve the item. (For risks, this is often called mitigation.)

17.2.1 Change Requests

As the name suggests, these are generally requests from the business to change one or more requirements. CRs may come from other sources, but for the requirements, they are only necessary if the business has previously approved a requirement.

17.2.2 Issues

ISSs are questions about the requirements that need resolution. Generally, an issue prevents a requirement being approved, until the issue has been resolved.

17.2.3 Risks[5]

RSKs are generally identified early in the project, as issues that may affect the success of the project. A risk anticipates a situation that has not yet occurred. Risks do not need to trace to individual requirements, but will often impact the project as a whole.

17.3 The Traceability Tree

Every project requirements management plan should define a traceability model in order to track changes to project requirements.

We want to organize traceability according to the following structure, where a ‘Trace-From’ relationship indicates a child requirement traces from a parent, and a ‘Trace-To’ relationship indicates a parent to child traceability link.

17.3.1 BUC

Each business area has its own repository for BUCs. A BUC document is imported into the appropriate repository and assigned to a Subject Matter Expert (SME). It may also be assigned an status. The traceability attribute is a link to a table containing the automated steps of the BUC.

17.3.2 BUC Step

BUC steps include hyperlinks to entries in a SharePoint traceability table. Opening the hyperlink displays the table entry, as shown in Figure 5:. In the following example, Figure 4:, hyperlinked steps have a single underline.

Steps of the use case are entered into the traceability table for the BUC. The step is given the name of its associated Candidate Use Case.

Each automated step of the BUC has an associated entry in the traceability table, shown in Figure 6:. Each entry references the associated system and AUC that implements the step. Entries may be marked as ‘suspect’ if either the step or the AUC changes.

Where a BUC step is implemented by several AUCs, the AUC ID attribute takes multiple values (one for each AUC implementing the step)[6].

17.3.3 BR

BRs are entered into a business rule table for the business area that they impact.

17.3.4 AUC

AUC documents are entered into a document repository for the application that they impact.

AUCs are assigned a responsible analyst and an attribute indicating whether the use case has an impact on the application architecture.

17.3.5 AUC Step

17.3.6 SR

Supplementary requirements are managed within a list for the application in SharePoint.

17.3.7 SWR

If developed, software requirements may be captured within a SharePoint table for the application that they impact.

17.4 Traceability Matrices

BUCs are the root of the traceability tree. Traceability from BUCs to BUC steps is implied from the BUC document. (A BUC step may exist in exactly one BUC.)

BRs are traced from BUC steps. The BUC step is the parent, since if the BR does not have a parent BUC step to trace from, it is assumed that the BR is not of interest to the project. A BR may trace to many BUC steps (or even the whole BUC), and a BUC may have many BRs traced from it.

An AUC is a child requirement of one or more BUC steps. A BUC step may trace to one or more

AUCs. If a BUC step changes, the whole AUC must be assessed for changes. This is probably a better situation than trying to maintain traceability to individual AUC steps. The choice is a trade-off between whether the frequency of change to the BUC is worth the effort of tracing individual AUC steps.

SRs trace from AUC steps . Similar to the BUC step – BR relationship, AUC steps may trace to many SRs. SRs may trace to the whole AUC, in which case the effort involved with finding the steps that are impacted when a SR changes is increased. Again, it is a trade-off between maintaining traceability, against the risk that the SR is going to change.

SWRs may trace from AUC steps. This relationship can be maintained through the use case realization.[7]

CRs, ISSs and RSKs item types, may trace from any requirement type (or repository of requirements) in the project. This allows maximum flexibility, and the additional work of maintaining the trace may be at the discretion of the project.

For each traceability link, we create a traceability table, as shown in the following traceability implementation, Figure 12:.

The ‘Traced In’ links indicate where a traceability relationship is maintained. Each relationship is described in more detail, as follows.

17.4.1 BUC To BUC Step

The traceability is simply a containment relationship, captured by the step being inside the BUC document.

17.4.2 BR From BUC

The business rule, is captured within a SharePoint table. A link to the BR is captured in the business rules section of the BUC document. A cross-reference to impacted requirements may accompany this link within the BUC document. A simple MS Word table can be used to capture the traceability as follows:

Business rule entries are links to the actual business rule in SharePoint. Step numbers are cross-references to the actual BUC step.

17.4.3 BUC Step To AUC

For each BUC create a table in SharePoint that will be used to trace the BUC steps to AUCs. The columns of this table are BUC Step Name, Application ID and AUC Id. Populate the BUC Step Name with names that represent the BUC steps. (I have chosen to use a candidate AUC name and label the BUC step column to explicitly state this.) Populate the application column from a dropdown list of all applications impacted by the BUC. Populate the AUC Id list with a dropdown list of all AUCs for those applications. For example, the Eat Lunch BUC traceability table might appear as follows:

Each Candidate Use Case Name entry is a 1-to-1 reference from a BUC step. The Application ID and AUC ID columns are populated from drop down lists.

17.4.4 SR From AUC Step

The supplementary requirement column contains links to the SUPs in SharePoint. The AUC Step column contains cross-references to AUC steps.

17.4.5 SWR From AUC Step

Within our requirements environment it was be nice if the AUC step to software requirement traceability could be maintained within the use case realizations. Each message in the realization could map a use case step to a software requirement, and the message flagged as suspect if either changes.

[In the absence of this automation, we may add an attribute to each SWR in the table shown in Figure 11: that references the AUC step that it traces from.]

17.5 Traceability Activities

The following processes provide maintenance of requirements traceability captured within our homemade requirements repository, in MOSS. Using a true requirements management tool should provide automation to assist with these activities.

The different types of requirement that we need to consider are; the Item type, the BR, the BUC step, the SUP, the AUC and the SWR.

Ideally, all changes to requirements are propagated through a top-down process. That is, changes to an AUC for example will occur as a result of a parent BUC changing in some way, otherwise we know that changing the AUC has no impact upon the business process, in any way. If you have implemented and are using an approved change control process this should occur naturally. The following recommendations assume that this is the case.

17.5.1.1 Item

We create a CR, RSK or ISS directly into the appropriate project repository. The item is then hyperlinked to the highest level requirement that it impacts. If it impacts more than one requirement, then hyperlink to the lowest level folder that contains all of the requirements that it impacts.

For example, when an ISS item is created in the Issue Item repository, as follows:, it is linked to requirements that it impacts.

The first item raises issues about the number of categories on the menu. This has an impact on the Order From Menu AUC.

The second item raises issues about the restaurant hours, and impacts the Serve Customer BUC.

The third issue raises questions about the new process that is being adopted. This impacts the whole requirements development repository.

The Impacted Items column contains links to the repository containing the impacted item. When a new item is created this field is blank. If an item is deleted, no other changes should be necessary.

There is no way to know if the linked item changes in any way, so a manual checking process (weekly status update of changed items, for example – ugh!) will be needed.

17.5.1.2 Business Rule

The BR is created directly into the repository database. Links to the BR come from the BUC documents that it impacts. This in turn references the steps of the BUC that are impacted. If the BR changes then it may be flagged as suspect. This ‘suspect’ flag remains until all BUCs that reference the BR have been checked for impacts[8].

Deleting a BR removes all references to the BR from the BUC documents. This will cause links from the documents to be broken. A better method may be to retain the BR and set its status to deleted, then delete all references to the BR from the respective documents. See Figure 15:.

The Service Objective is a new business rule whose impacts have not been investigated yet and is therefore marked as ‘suspect’.

17.5.1.3 BUC Step

Creating, changing or deleting a BUC step should cause all links from the step to become suspect. The change is made within a BUC document. At the same time that the step is changed or created, the CUC link in the BUC Step traceability table is set to suspect[9].

If deleting a step, simply remove the step from the BUC document, and the status of the CUC in SharePoint to set to ‘deleted’. All references to the CUC SharePoint link now need to be checked for consistency.

In Figure 16: the Order From Menu BUC step has changed and is marked as ‘suspect’. The Print Receipt use case step has been taken out of scope and has been marked as ‘deleted’.

Addendum: Changing a BR that impacts a BUC step may also have an impact on AUCs that trace from the BUC step. Therefore, every time a BR link is deleted from a BUC document, you should flag the associated step as suspect. This indicates that traced AUC documents also need to be checked to determine if the deletion of the BR affects the application requirements in any way.

17.5.1.4 Supplementary Requirement

Similar to maintaining BRs, the SR is created and modified in the SharePoint repository.

It is initially marked as ‘suspect’, until its impact has been assessed, when the ‘suspect’ attribute is cleared (set to ‘no’). If it changes then the ‘suspect’ attribute is set to ‘yes’ until all requirements referencing the SR have been checked for consistency changes.

17.5.1.5 Application Use Case

AUC document changes may impact supplementary requirements and software requirements. If the document changes, mark the entry in the SharePoint document repository as suspect. Now every SR reference within the document needs to be checked for consistency.

Similarly if an AUC is deleted from scope. Mark the document in the repository as ‘deleted’. Now all referencing SRs can be checked for consistency with the system requirements now that the AUC has been deleted.

Figure 18: shows that the Print Receipt AUC has been taken out of scope of the project.

17.5.1.6 Software Requirement

It is not recommended that Software requirements are maintained in a SharePoint repository. The software requirements will therefore only change as the result of an analysis of the AUCs. The SWR repository in SharePoint is only then updated as a result of this analysis, as described in Chapter 16.

17.6 Other Traceability

Outside the scope of this discussion other artifacts that you will probably wish to consider adding to a traceability model are:

17.6.1 Activity diagrams

If a BUC or an AUC changes, how do you maintain consistency between the use case details and the associated activity diagram? If the use case changes, do you somehow mark the activity diagram as ‘suspect’ or do you simply decide not to maintain the diagram until the next release of the application, when the diagram is redrawn? Ideally, I want my use case steps and other details to be automatically created from the diagram. That way, I never have to change the document, on the diagram and its supporting information.[10]

17.6.2 Messaging Events

It would be really nice if we could link the messages in our use case realization ( sequence diagram) to the steps of the use case, or even the flows in the associated activity diagram. These in turn could also be linked to the events shown in the class state transition diagrams. In fact drawing one of these three items could potentially create a shell for the other 2 types of diagram which we manipulate and fill in the details.

17.6.3 Actions

Similar to events, it would be nice to be able to link the activity diagram actions to states in the class state transition diagrams.

17.6.4 Operations

As described during the analysis of a use case, the operations come from actions in state transition diagrams and these drive the messages on a use case realization and eventually the software requirements. It would be nice to be able to link these 3 items and have the sequence diagram messages trace back to the activity diagram for the use case. Then if the AUC changes we know exactly what to check in the realization, the class/state model and the software requirements.

17.6.5 Classes

Classes are obtained from the initial recognition of objects in the use case activity diagram details. Tracing objects in an activity diagram (for both the business and the application use cases) to classes in the logical model, is a feature that many UML modeling tools already support[11].

17.7 Reports

Producing traceability reports, beyond exporting the SharePoint tables and lists to MS Excel, is beyond the scope of this work.[12], If you wish to dive into the SharePoint database and produce exotic SQL queries, some of the things to consider might be:

· Generating a traceability tree from BUC Steps to AUCs to Software Requirements.

· Performing an analysis report of Business Rules that have no Software Requirement implementation.

· Performing an analysis report of Supplementary Requirements that have no Software Requirement implementation.

17.8 Summary

Why we use requirements management and modeling tools to perform business and systems analysis.

· Managing changes to BUCs – To ensure that only approved changes are made to the business requirements.

· Managing changes to BUC steps – To ensure that changes to business use cases are propagated to the appropriate application artifacts.

· Changes to BRs – To ensure that changes to business rules are captured in the application requirements.

· Identifying CUCs – Allows traceability from the business requirements to the application requirements to be established.

· Tracing BUCs to AUCs – To ensure that what is being implemented is that which is required by the business.

· Managing changes to SUPs – To ensure that all associated application requirements are updated when a supplementary requirement changes.

· Tracking classes and attributes – Ensures that all the required data is captured and consistent with the AUCs.

· Tracing operations to AUCs – To ensure that the software requirements are consistent with the AUCs.

By customizing and adding functionality to a MOSS environment it is possible to perform all of these tasks. Alternatively, any COTS requirements management toolset should have these capabilities built-in.

[1] I have only witnessed one requirements management tool that attempts to provide this functionality, and no, I do not remember its name.

[2] Ideally, your development toolset is customized to allow management of these items.

[3] This may be a single table per project, per application or one table for the whole business. The trade-off is between is between managing a large number of items in a single table, or managing many tables.

[4] These attributes and their values are a proposed minimum. The more attribute values, the more complicated the model becomes, therefore I suggest not adding an attribute or value until someone has requested it as necessary.

When assigning attributes, I highly recommend using values that have a meaning to the project. Assigning a value between 1 and 10 does not allow me to set this attribute without an explanation of what each value means. Similarly ‘High’, ‘Medium’ and ‘Low’ offer little more value.

[5] If risks are handled differently to change requests and issues, these may be tracked within their own table.

[6] The AUC reference is taken from a selectable list. It would be nice if the list entries could link to the AUC in SharePoint. Unfortunately, only a single AUC may be referenced in this manner, with my version of SharePoint.

[7] Each sequence diagram message represents a SWR. Linking the control flow in the use case to the messages in the sequence diagram provides traceability from AUC steps to SWRs.

[8] The method for monitoring suspect links is a task for the Project Manager to enforce.

[9] If creating the step, the CUC will also need to be created in the table.

[10] I once wrote a script to parse an activity diagram in Rational Rose that would generate the use case details from the diagram. As you can imagine, this placed very strict and stringent rules on the activity diagram notation.

[11] Unfortunately, not my version of Visio.

[12] Meaning, I don’t have the knowledge to talk in detail on this subject.