Links Mapping (Excel) Internals - Readme

document

Table of Contents
Links Mapping (Excel) Internals - Readme document...............................................1
1. Overview................................................................................................................ 1
2. Links Mapping Internals Overview.......................................................................2
2.1 Restrictions........................................................................................................ 2
2.2 Sample workbooks explanation of relevant fields used in links mapping.......2
2.3 Configure Links Mapping................................................................................... 5
2.4 Supported link types......................................................................................... 8
2.5 Configure additional link types..........................................................................9
2.6 Storage of Links mapping metadata...............................................................10
2.7 Consolidated Excel pivot reports.....................................................................11
2.8 Troubleshooting Links...................................................................................... 16

1. Overview
With the RC2 release of this tool, we are adding to the Excel capabilities the ability
to migrate not just the Test case work item, but also Requirements and Bugs work
items hence the change in name of the executable to TestCaseMigratorPlus.exe.
Some of the salient features associated with this version of tool (for excel based
workflow) are as follows:

Migrates work items belonging to Test case, Requirement/User story and Bug
categories
Supports multi-pass migration process - i.e., each work item type has to be
migrated in a different invocation of the tool
Maintains links between work item types (Parent/Child, Related, Tested By,
Tests etc) across multiple passes
Provides ability to create Test suites for a test case work item type

The most significant aspect of this release is the ability to create links
between different work item types. This document goes into details of how the
Links are being created, maintained and tracked over multiple invocations/sessions
of the tool. It also provides an in-depth look at the metadata being used. This
internal knowledge will help you understand and (if needed) troubleshoot any issues
you may encounter during the processing of the links.

2. Links Mapping Internals Overview

The following sections go into the various aspects of Links Mapping starting with
restrictions associated with using this tool, followed by explaining relevant
fields/columns in the excel sample workbooks that are used in Links mapping,
followed by how to configure links mapping, the supported link types, how to
configure additional link types for migration, storage of links mapping metadata,
consolidated excel pivot reports for analyzing runs and finally a look at
troubleshooting issues with links.

2.1 Restrictions
There are certain restrictions that must be followed when using the Linking
functionality, which are:

Tool should not be used concurrently at the same time by two different users
for a single TFS server/project combination.

Tool should not be used concurrently at the same time from two different
machines (may or may not be by the same user) for a single server/project
combination.

Multiple invocations for a single server/project can cause the links metadata
to get messed up or corrupted (either by same user on multiple machines or
multiple users on multiple machines).

2.2 Sample workbooks explanation of relevant fields used in links mapping

Along with the binaries and source drops with the RC2 release, there is also a
samples package that is being provided for both Excel and MHT flows. The Excel
sample package can be downloaded from Samples-ExcelPackageRequirementsBugsTestCases.zip. This package contains the following files:

SampleTestCasesWorkbookWithRelationships.xlsx
SampleRequirementsWorkbookWithRelationships.xlsx
SampleDefectsWorkbookWithRelationships.xlsx

MyTestCaseSettingsFile.xml
MyRequirementsSettingsFile.xml
MyBugSettingsFile.xml

This section provides an explanation of all the fields/columns used in the above
sample excel files (for test cases, requirements, bugs). The fields used in Links
mapping are highlighted separately. It is not necessary that your excel file must
conform to the same layout or fields. As long as the highlighted fields are included
in your excel workbook, the respective links can be created using the Test Case
Migrator Plus tool.
2.2.1 Test Case record

Test Case Source ID: represents the test case id in the source system or
within the excel file. The source id is a required field for you to do any types
of linking between the work items. This field is used as the joining key
between work item types. You can map this field in the Links Mapping
dialog.

Test Name: represents the title of the test case. You can map this field in the
Fields mapping dialog, under Fields mapping section.

Test Description: represents the description of the test case. You can map this
field in the Fields mapping dialog, under Fields mapping section

Test Folder Hierarchy: represents the folder hierarchy of the test cases. You
can map this field in the Fields mapping dialog, under Test Suites section.

Assigned To: represents the person who has been assigned this test case. You
can map this field in the Fields mapping dialog, under Fields mapping
section

Status: represents the status of the test case. You can map this field in the
Fields mapping dialog, under Fields mapping section.

Priority: represents the priority of the test case. You can map this field in the
Fields mapping dialog, under Fields mapping section.

Suites Hierarchy: represents the sets of suites the test case belongs to. If the
test case belongs to multiple suites, then they are separated by ;
(semicolons). You can map this field in the Fields mapping dialog, under
Test Suites section.

Related Test Case Source IDs: represents the related test cases for the current
test case. If test case is related to multiple other test cases, then the related
test case source ids are separated by ; (semicolons). You can map this field
in the Links mapping dialog, under the Links table.

Linked Requirement Source IDs: represents the linked requirements for the
current test case. If test case is related to multiple other requirements, then
the linked requirement source ids are separated by ; (semicolons). You can
map this field in the Links mapping dialog, under the Links table.

Step Name: represents the title of the test step name. You can map this field
in the Fields mapping dialog, under Fields mapping section.

Expected Result: represents the expected result for the particular test step.
You can map this field in the Fields mapping dialog, under Fields mapping
section.

2.2.2

Requirement record

Requirement Source Id: represents the requirement id in the source system or

within the excel file. The source id is a required field for you to do any types
of linking between the work items. This field is used as the joining key
between work item types. You can map this field in the Links Mapping
dialog.

Requirement Title: represents the title of the requirement. You can map this
field in the Fields mapping dialog, under Fields mapping section.

Parent Requirement Source ID: represents the parent requirement source id

for the current record. The parent source id must also exist in the source

system or within the excel file(s). You can map this field in the Links
Mapping dialog, under Links table.

Author: represents the person who has authored/assigned this requirement.

You can map this field in the Fields mapping dialog, under Fields mapping
section.

Requirement Folder Hierarchy: represents the folder hierarchy of the

requirements. You can map this field in the Fields mapping dialog, under
Fields mapping section.

Status: represents the status of the requirement. You can map this field in the
Fields mapping dialog, under Fields mapping section.

Priority: represents the priority of the requirement. You can map this field in
the Fields mapping dialog, under Fields mapping section.

2.2.3 Bug record

Defect Source ID: represents the defect id in the source system or within the
excel file. The source id is a required field for you to do any types of linking
between the work items. This field is used as the joining key between work
item types. You can map this field in the Links Mapping dialog.

Defect Title: represents the title of the defect. You can map this field in the
Fields mapping dialog, under Fields mapping section.

Assigned To: represents the person who has been assigned this defect. You
can map this field in the Fields mapping dialog, under Fields mapping
section.

Defect Folder Hierarchy: represents the folder hierarchy of the defect. You can
map this field in the Fields mapping dialog, under Fields mapping section.

Status: represents the status of the defect. You can map this field in the
Fields mapping dialog, under Fields mapping section

Priority: represents the priority of the defect. You can map this field in the
Fields mapping dialog, under Fields mapping section.

Defect Created by Test Source IDs: represents the test source id that was
used to created this defect. The created by test source id must also exist in
the source system or within the excel file(s). If multiple test cases found this

defect, then they are separated by ; (semicolons). You can map this field in
the Links Mapping dialog, under Links table.

2.3 Configure Links Mapping

The configuration of Links mapping using the Test Case Migrator Plus tool is
documented in the TestCaseMigratorPlus(Excel-MHT)-Readme.doc. This section is
repeated here for the sake of completeness.
2.3.1 Links mapping dialog

2.3.1.1 Purpose

Allows you to specify the different links within a particular work item type (ex:
Requirement::Requirement -Parent/Child) or links between work item types (ex:
Requirement::Test Case TestedBy). Since the migration of different work item
types can only be done in multiple invocations of the tool, the linking metadata
information is persisted across different sessions for a TFS Server/Project
combination.

2.3.1.2 Interactive fields

Create links between work items: Check this option if you need to create any
types of links in current OR future invocations of the tool. If this option is checked,
then the tool maintains a record of all the invocations of the tool for a project/server
combination. This allows the links to be created between work items even if they
may have been migrated over a period of time. Checking this option also ensures
that the consolidated reports (excel pivot reports) get generated. Hence, make sure
that you check this option if you want any type of links to be created ever for a
project/server combination. By default, this checkbox is checked.
Field containing unique source work item ids: select a field/column in the
excel worksheet that uniquely identifies the work item record in the source system
(either excel or some other 3rd party system). This value will be used to define and
track the links between work item types. If the source file does not contain a unique
value for the work item record, then links cannot be created using this tool.
Link Type: This field shows the list of default link types you can create either within
the same work item type or across work item types. The values in this field differ
depending upon the currently selected work item type in the Destination page. If
you are using CMMI project, then text of Requirement shows up, if you are using
an Agile project, then text of User story shows up in the links text below.
Requirement/User Story work item category/type:
Source Work
Item

Link Type

Destination work
item

User Story is

Tested By

Test Case

User Story has

Parent

User Story

User Story is

Related to

User Story

User Story is

Related to

Bug

Test case work item category/type:

Source Work
Item

Link Type

Destination work
item

Test Case

Tests

User Story

Test Case

Tests

Bug

Test Case is

Related to

Test Case

Bug work item category/type:

Source Work
Item

Link Type

Destination work
item

Bug is

Tested By

Test Case

Bug is

Related to

Bug

Bug is

Related to

User Story

Field containing linked work item ids: Select a field/column in the excel
worksheet that represents the values for the links that need to be created for the
selected source work item id. This field can either have a single value (in case of
Parent/Child relationship between requirements) or can have multiple values (in
case of related bugs for a test case). When multiple values are specified in the excel
field, they need to be separated by ; (semicolon). If no value is specified, then
links will not be processed in the current invocation of the tool.
Adding custom link types: If you need to support any additional link types apart
from the ones mentioned above, you can directly add them to the corresponding
settings file you have created. Once it has been added to the settings file, those link
types will appear in the links mapping UI page. This allows you to now save the
additional link types into the settings file for later use.
Refer to LinksMapping(Excel)-Internals-Readme.doc for internal details on how to
add custom link types or learn how the links are tracked and created across multiple
sessions/invocations of the Test Case Migrator Plus tool.

2.4 Supported link types

The different types of link types supported in the Test Case Migrator Plus tool are:

Parent/Child links
o Parent/Child links between Requirement::Requirement
Related links
o Related links between Requirement::Requirement
o Related links between Test Case::Test Case
o Related links between Bug::Bug
o Related links between Requirement::Bug
Tested By/Tests links
o Tested By/Tests links between Requirement::Test Case
o Tested By/Tests links between Bug::Test Case

Another way of looking at the supported link types is to look at with using the work
item type as a pivot. In such case, the different link types supported are as follows:

Note: If you are using Agile project, then text of User Story appears in tables
below; if you are using CMMI project, then replace user story with text of
Requirement in the tables below.
Requirement/User Story work item category/type:
Source Work
Item

Link Type

Destination work
item

User Story is

Tested By

Test Case

User Story has

Parent

User Story

User Story is

Related to

User Story

User Story is

Related to

Bug

Test case work item category/type:

Source Work
Item

Link Type

Destination work
item

Test Case

Tests

User Story

Test Case

Tests

Bug

Test Case is

Related to

Test Case

Bug work item category/type:

Source Work
Item

Link Type

Destination work
item

Bug is

Tested By

Test Case

Bug is

Related to

Bug

Bug is

Related to

User Story

2.5 Configure additional link types

If you want to process additional link types that already exist on the server/project
using the Test Case Migrator Plus tool, then you modify the corresponding Setting
file and update the LinkTypes section. For example, if I wanted to add Duplicate
as a new link type (assuming Duplicate link type already exists on my TFS server

and Duplicate Bug IDs already exists as a column in my excel source workbook),
then I would add the following lines to the settings file:
<LinkTypes>
<LinkType SourceField=" Duplicate Bug IDs" LinkTypeName="Duplicate"
LinkedWorkItemType="Bug" Description="Duplicate Bugs" />
</LinkTypes>

So the final settings file with the Duplicate and Tested By links would look as
follows:
<LinkTypes>
<LinkType SourceField="Defect Created by Test Source IDs" LinkTypeName="Tested By"
LinkedWorkItemType="Test Case" Description="" />
<LinkType SourceField="Duplicate Bug IDs" LinkTypeName="Duplicate"
LinkedWorkItemType="Bug" Description="Duplicate Bugs" />
</LinkTypes>

When you load this setting file in the Links Mapping section, a new row is now
shown in the Links table.

2.6 Storage of Links mapping metadata

2.6.1 Storage of metadata file

From the above sections, it is clear that the Links Mapping metadata information is
the key to a successful migration of data from Excel to TFS for different work item
types while maintaing the links between work items. As such, preserving this file
across sessions becomes critical. The Test Case Migrator Plus tool does this by
storing the Links Metadata file in TFS.

The Links Metadata file is generated for a TFS Server/Project combination.

The file name is generated as follows:

Linksfile<URLofTFSServerProjectCollection><ProjectName>.xml.

When the Create Links checkbox is checked in Links Mapping page, then
the tool creates a new Task work item in the above
Server/ProjectCollection/Project.

The task is created with the following name:

<DONOTDELETEORCHANGE><TestCaseMigratorPlus><LinksMetaData><St
ored as a Task work item>.

This Links metadata file gets stored as an attachment to this Task workitem
in the Server/ProjectCollection/Project.

If a task & the attachment already exists from prior runs, then the
attachment is updated with the data from the current run.

For every run, the links metadata file is first copied from the TFS task work
item to the current report directory, then read and updated locally during the
migration process. Once the migration is completed, the local file is then
stored back into TFS by deleting & adding the new attachment on the Task
work item.

Even if you stop the migration in the middle, the steps of writing to local
metadata file and then updating it on the TFS server is not stopped. This
ensures that the data is always updated in TFS for every invocation of the
tool for a server/project combination.

2.6.2 Advantages of this approach

Some of the advantages of the above approach of storing the links metadata file as
an attachment to Task work item are as follows:

The links metadata file is always stored in TFS, which ensures that data is
persisted along with the rest of the TFS data which gets you the
advantages of the backup/restore mechanisms in place.

Without this, if the links metadata file was stored on the machine from where
the tool was invoked, then any system failures on that machine would put
the entire migration & links metadata at risk.

2.7 Consolidated Excel pivot reports

The consolidated excel pivot report shows you the consolidated report across
sessions. It contains the raw data table along with different pivot reports that use
the raw table data.
2.7.1 Raw Data Table:

Shows the underlying raw data captured across sessions (until the last session).

The different columns in this worksheet are:

SNo: captures the record count.

SessionID: captures the id for each invocation of the tool for a server/project
combination.

MigrationResult: captures the status of the migration of the work items.

Values include passed, failed or blank (when the record tracks the links result
instead of migration result).

LinksMapingResult: captures the status of the linking of the work items.

Values include passed, failed, warning or blank (when the record tracks the
migration result instead of links result).

StartWorkItemType: captures the work item type that was used in the Excel
source file for migration/links purpose.

StartWorkItemSourceID: captures the unique id for the work item record in

the excel source file. This is specified in the Links mapping page. As
mentioned earlier, if the unique source id is not specified, then the
consolidated report cannot be generated.

StartWorkItemTfsID: captures the work item id that was created in TFS post
migration. Value of -1 indicates that migration was attempted, but it failed.

LinkType: captures the type of link that was used to link the
StartWorkItemType and EndWorkItemType records.

EndWorkItemTfsType: captures the work item type that was used in the TFS
destination for creating links.

EndWorkItemSourceID: captures the unique set of values specified in the

excel source file that were used to link the startworkitemtype to
endworkitemtfstype.

EndWorkItemTfsID: captures the work item id that was created in TFS post
migration and post linking.

IsExistsInTFS: captures whether the link has been created in TFS or not. This
is used only for the linkmapping record, not for the migration record.

Message: captures any error or warning message received from TFS either at
time of migration or at the time of creating links.

The good part of the raw table is that it allows you to create any additional custom
pivot reports in addition to the default set that come out of the box. The raw table
also allows you to slice/dice the data by applying the different excel filters present
in the worksheet.

2.7.2 Migration Summary Report

Shows the summary view of migration status with sessionid as pivot filter,
migrationresult as column labels, Startworkitemtype as row labels and count of
S.No as the aggregrating values.

2.7.3 Migration Details Report

Shows the drilldown of migration records with sessionid & migrationresult as

pivot filters, message & startworkitemsourceid as row labels and count of
S.No as the aggregating values.

2.7.4 Links Mapping Summary Report

Shows the summary view of links mapping status with sessionid as pivot filter,
linksmappingresult as column labels, startworkitemtype & linktype as row
labels and count of S.No as the aggregating values.
2.7.5 Links Mapping Success Report

Shows the drilldown of successful linked records with sessionid,

startworkitemtype & linksmappingresult=passed as pivot filters, linktype as
column labels, startworkitemsourceid as row labels and count of S.No as the
aggregating values
2.7.6 Links Mapping Warnings Report

Shows the drilldown of warning linked records with sessionid, startworkitemtype

& linksmappingresult=warning as pivot filters, linktype as column labels,
message & startworkitemsourceid as row labels and count of S.No as the
aggregating values.
2.7.7 Links Mapping Failed Report

Shows the drilldown of warning linked records with sessionid &

linksmappingresult=failed as pivot filters, linktype as column labels,

startworkitemtype, message & startworkitemsourceid as row labels and

count of S.No as the aggregating values.
2.7.8 Links Mapping Per Source Work Item Report

Shows the drilldown linking report for particular source work item id with
startworkitemsourceid as pivot filter, linksmappingresult as column labels,
linktype as row labels and count of S.No as the aggregating values.

2.8 Troubleshooting Links

From the above sections, it is clear that the core aspect of Links Mapping is
dependent on you specifying two pieces of information in the Links Mapping dialog:
a. Source ID for the work item being migrated.
b. Different Link Rules in the links table.
This section walkthroughs the scenarios where one/more of the above information
has not been provided or has been done incorrectly and what corrective actions
need to be taken to troubleshoot such cases. The different set of scenarios can be
summarized in the below table:

Disclaimer: Under no circumstances should you be altering any of the following

data that is used by the Test Case Migrator Plus tool Failure to comply with this
can lead to data loss or corruption of links.

The TASK work item that gets created for a server/project combination.
o

Title should not be changed.

Task work item should not be destroyed.

The attachment file present on the task work item that contains the links
metadata information.
o

Attachment name should not be altered.

Attachment file should not be deleted.

Contents of the attachment file should not be modified.

Scenario#1

Scenario#2

Scenario#3

Scenari
o#4

Operation undertaken
Migration of work
item completed

Yes

Yes

Yes

Yes

Source ID specified in
Links dialog

No

Yes

Yes

No

Link Rule(s) specified

in Links dialog

No

No

Yes, but
incorrect link
rule(s) were
provided

Yes

State of artifacts created

Work Item created in
TFS

Yes

Yes

Yes

Yes

Task work item with

attachment created
in TFS

No

Yes

Yes

Not a
possible
scenario

Destroy
migrated
work item(s).

Not a
possible
scenario

Resolution Summary
Resolution

(optional)
Destroy
migrated work
items (if you do
not want
duplicates
has no effect
on new links to
be created)
Rerun Test
Case Migrator
Plus tool by
specifying the
Source ID and
Link Rules.

More Info

See scenario#1
below

Rerun Test
Case Migrator
Plus tool by
specifying the
Link Rule(s).

Rerun Test
Case Migrator
Plus tool by
specifying the
correct Link
Rules

See
scenario#2

See
scenario#3

Not a
possible

below

below

scenario

2.8.1 Scenario#1:

Operation undertaken: Work items were successfully migrated using the tool.
However, you forgot to turn on the Links Mapping checkbox and did not specify
the Source ID or any of the Links Rule(s).
State of artifacts: Work item has been migrated into TFS. However, no TASK work
item was ever created in TFS and no links metadata file was added as an
attachment to the task work item. This means that the system has no knowledge
about the invocation of the tool in prior runs for this server/project combination.
Resolution steps: Just rerun the Test Case Migrator Plus tool with the same excel
source data again but this time remember to turn on the Links Mapping
checkbox, specify the Source ID and the corresponding Link Rule(s). This would
recreate a new instance of the work items in TFS and now create appropriate links.
The original set of work items created in prior runs will still be present in the
destination. If you do not want duplicates to be present, then delete the original set
of work items using the TFS command line utility witadmin destroywi. Refer to
Permanentaly removing Work Items for how to use this utility.
2.8.2 Scenario#2:

Operation undertaken: Work items were successfully migrated using the tool. You
also specified the Source ID by enabling the Links Mapping checkbox, but you
forgot to add one or more Link Rule(s).
State of artifacts: Work item has been migrated into TFS. The TASK work item was
also created in TFS. The links metadata file was also attached to this task work
item. However, this metadata file does not contain any link rules. This means that
the system has knowledge about the invocation of the tool in prior runs for this
server/project combination, but does not contain any link rules.
Resolution steps: Just rerun the Test Case Migrator Plus tool with the same excel
source data again but this time remember to specify the corresponding Link
Rule(s) you missed in prior runs. The tool will skip the migration of the work items,
and only process the link creation phase in this scenario.
2.8.3 Scenario#3:

Operation undertaken: Work items were successfully migrated using the tool. You
also specified the Source ID by enabling the Links Mapping checkbox, and also
enabled certain link rules. However, you provided incorrect Link rules (by specifying
the incorrect fields from the excel file). As a result, incorrect links have now been
created in the destination.

State of artifacts: Work item has been migrated into TFS. The TASK work item was
also created in TFS. The links metadata file was also attached to this task work
item. The metadata file contains the Links mapping section as well. However, this
links mapping section contains incorrect values. This means that the system has
knowledge about the invocation of the tool in prior runs for this server/project
combination, but contains incorrect link rules.
Resolution steps: Since the system contains incorrect links to work items, you first
need to identify the work items that need to be deleted/destroyed. You dont
necessarily have to redo the entire migration process. For example, you have
already run four different sessions of the tool. However, in the 4 th instance, you
provided incorrect link fields/rules. In such case, you only need to identify the work
items created in session#4 and then destroy them using the TFS command line
utility witadmin destroywi. Refer to Permanentaly removing Work Items for how
to use this utility. The first 3 session data can still remain in the destination server.
Once the problematic work items have been deleted/destroyed, just rerun the Test
Case Migrator Plus tool with the same excel source data again but this time
remember to specify the correct Link Rule(s). The tool will skip the migration of the
work items that are still present in the destination TFS, but recreate work items that
were destroyed, re-process all the links again by deleting links for the destroyed
work items and creating new links for the newly migrated work item records.
2.8.4 Scenario#4:

Operation undertaken: Work items were successfully migrated using the tool.
However, you forgot to turn on the Links Mapping checkbox and did not specify
the Source ID, but specified the Links Rule(s). This scenario is not possible using the
tool. You can only enable the link rules if & only if the Links mapping checkbox has
been enabled and Source ID has been specified.
State of artifacts: Not a possible scenario.
Resolution steps: Not a possible scenario.
2.8.5 Scenario#5:

Operation undertaken: This scenario is not directly related to issues with Links
Mapping but applies to situations where you forgot to add some fields in the
Fields Mapping page. For example, your excel file contained 6 columns, but in field
mapping, you only specified 4 columns. As a result, data from the other two
columns did not make it into the database. This is assuming that the 2 columns you
missed were not Test Steps or Expected Step Results.
Resolution steps: From the Team Explorer, run a query to identify all the records you
just migrated using the Test Case Migrator Plus tool. Right click on all the records
returned in the query, and select Open selection in Microsoft Excel. This would
open all the selected records in Excel. Now from the Team addin, click on Choose
columns, select the columns from TFS where you forgot to map the data and add it

to the excel sheet. Now, open your original excel source data, copy the data from
the missing columns and paste it into the two columns in the new excel worksheet
you opened from Team Explorer. Then click on Publish to publish the newly added
column data to TFS.
All the above will work as long as the missing columns were not the Test Steps or
Expected Step Results column for a Test Case work item. If these were the two
columns you missed, you will have to either destroy the original work items and
rerun the tool OR add the missing column data manually from Microsoft Test
Manager client.