In TFS, there are several different types of links between system artifacts, and the Migration and Synchronization Toolkit provides a method to synchronize those links between TFS and the source system. Below are the descriptions of the various system components
and the linking engine work to synchronize links.
An artifact is an abstraction for any object used by the system. Any artifact has the following properties:
- URI. This is a string property that uniquely identifies artifact within all artifacts on the source system.
- Id. This is a string property that uniquely identifies artifact within artifacts of the same type (work item id, change list number, etc).
The need for having both id and URI is dictated by the implementation which uses ids for storing mappings between work items on both sides; change list numbers are used for storing mappings between change lists.
Artifact’s type (work item, hyperlink, change list, etc) is hardcoded in the URI; there’s no need to have a public property for it, as the linking engine does not require knowing the type for processing links.
Link is a relationship of certain kind between two artifacts. Two artifacts cannot be connected with two or more links of the same type, but they can be connected with any number of links of different types. For performance reasons linked artifacts (source,
target) are represented by URI’s, not by objects themselves, as instantiating these objects may require significant amount of time.
Link container is an artifact containing links to other artifacts. Link container has URI of the source artifact; this makes SourceUri property of each link from the container obsolete (it must be identical to URI of the container).
Note that the link container interface does not have a method for extracting links: links, obtained from a container, depend on link handlers, registered in the system.
Linking engine is a component providing support for the following operations:
- Getting all supported links from the given container
- Deferring a link by storing it in some internal database
- Accessing all deferred links
- Removing a deleted link
- Finding reflection of an artifact on the opposite side
- Extracting internal ID from the URI
Default Linking Engine
The default linking engine (LinkEngineBase class) uses conception of artifact handlers and link handlers. When getting all supported links from a link container, the engine passes the input to all registered link handlers giving them a chance to extract their
links. When working with artifacts, the engine passes the input to all registered artifact handlers until one of them recognizes and processes the data. This approach allows having links of different types between two artifacts (related/dependent/duplicate
links between work items, for example).
Artifact handlers are always registered in pairs (a handler per artifact type on each side). Artifact handlers are interfaces, link handlers are callback functions. The default implementation provider artifact and link handlers for TFS system, so users
wouldn’t have to implement them. However, it does not register them, so users may chose which artifacts they want to handle.
Every link handler must have an artifact handler for its source and target artifacts.
- WorkItemTrackingSession.Start(SyncObjects mode) starts processing specified objects (work items or deferred links) in the service (asynchronous) mode.
- WorkItemTrackingSession.ProcessDeferredLinks() processes all deferred links created within this session. This method is synchronous.
- Synchronizing work items analyzes their links and migrates/defers them. The config file must specify linking engine assembly to enable synchronization of links.