[Inside TeamCompanion 2.2] Customizing the Work Item Preview

One of the new features introduced in the TeamCompanion 2.2 is the ability to customize the new work item preview.

There are three ways to influence the content of the work item preview:

a) declarative – the list of the fields to be included or excluded form the preview is saved in the registry

b) programmatic – you override the xsl file used for formatting the xml generated by the TeamCompanion. You can do anything you like there.

c) mixed - above options combined.

Included/Excluded lists

Included lists are used to specify all the fields you want included in the Work Item Preview. Excluded lists specify all the fields you want excluded from the Work Item Preview. Included or excluded lists are semicolon separated lists of work item fields Reference Names. For example: „System.State;System.CreatedDate;System.CreatedBy;System.IterationPath;“.

It is an error to use both Included and Excluded lists at the same level/priority in registry. In that case TeamCompanion will use Excluded list.

The order of work item fields in the list is important.

Saving Included/Excluded lists in the registry

There are different locations where the Included/Excluded lists may be saved in the registry.

These locations define the scope of the setting, whereby the scope may be:

a) one particular server (global setting that would span multiple servers is currently not supported) – applies to all projects and all work item types in that server;

b) one particular project – applies to all work item types in that project;

c) one particular work item type in one particular project and server.

Registry root folder ( path : „HKEY_CURRENT_USER\Software\Ekobit\TeamCompanion.Outlook“
    <server_name>
        [IncludedPreviewFields] or [ExcludedPreviewFields] – the option a
            <project_name> 
                [IncludedPreviewFields] or [ExcludedPreviewFields] – the option b
                    <work_item_type_name>
                        [IncludedPreviewFields] or [ExcludedPreviewFields] – the option c

<server_name>, <project_name> and <work_item_type_name> represent Registry keys named after the server, project or work item type containing settings for a specific server_name, project_name or work_item_type_name respectively.

<server_name> is the name of the TFS server as it is displayed in the TeamCompanion’s UI (tree control): TFS_FQDN.PortNumber. e.g. tfs.test.com.8080 (notice that there is a DOT between the server name and the port number).

In the scheme shown above, "[IncludedPreviewFields] or [ExcludedPreviewFields]" are all valid places where „IncludedPreviewFields“ and „ExcludedPreviewFields“ lists can be put.

Each of these three places defines different validity scope. If for particular work item type, project and server there are settings defined on different levels, the setting on the lowest level will apply (work item level takes precedence over project level which takes precedence over server level). For some Work Item first will be used list specified in its key. If it isn't present, then the list in project key will be used. If that one also isn't present, the one in server key will be used. If there is no list that apply to that Work Item type, project and server, the default settings will be used.

We might provide proper UI for these settings in some future version.

Using your own XSL  file

Full path to the alternative Xsl file must be saved in registry in

HKEY_CURRENT_USER\Software\Ekobit\TeamCompanion.Outlook\WorkItemPreviewXslFilePath.

For example, „D:\MyFolder\CustomXSL.xsl“. In case of any error while using that file, TeamCompanion will fall back to the default embedded XSL.

Attached you can find a sample xml (normally dynamically generated on the fly by the TeamCompanion) and sample xsl that is used to transform the xml in order to produce the work item preview.

There is one additional setting that influences the work item preview content: Removing Empty Fields in Work Item Preview

This setting can be edited from the TeamCompanion UI using the checkbox check box named „Remove empty fields from Work Item preview„ available in the Work Item Preview tab of the TeamCompanion options dialog.

If it is checked, empty fields will be removed (exception from this is if the field with the empty value is explicitly listed in the appropriate IncludedPreviewFields list, in which case they will not be removed).

[Update] Users having work item query folders where some work items already exist, need to remove and reload these work items for the new preview settings to become effective. This can be done by selecting all work items and deleting them by pressing Delete key on the keyboard. Don’t worry – your work items will remain intact. This will only delete cashed offline information about them. Execute the query once again (by executing Refresh command from the folder’s context menu) or, if you have scheduled execution of this query, wait for the schedule, and all work items will appear once again, this time with the preview formatted in accordance with your new settings.

Download File - Sample