[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

TeamCompanion for Outlook v 2.2 released

Earlier this week Ekobit released the TeamCompanion for Outlook v2.2. This is a minor .x version and as such it comes with some new features and many improvements of existing ones that complement and enhance existing functionality. In this version we address many usability obstacles in order to ensure smooth and efficient usage patterns throughout the application.

This release is a free update for all existing customers.

Following is the list of the most important new and improved features of TeamCompanion in v2.2:
• Better offline support and support for occasionally connected clients
• Improved Work item edit form
• Improved Work item preview (Support for history; preview is now fully customizable)
• Improved Work item from Mail action
• Improved Open related object action – for emails multiple related objects are offered; related work item for Outlook Appointments
• Improved Reports support (new conversion formats for Reports; support for Canceling )
• Improved Send Work Item as Mail action (‘with attachments’ option including attaching created mail back to the Work Item)
• Improved usability/ease of use
• TFS 2010 Beta support
• TeamCompanion v2.2 is compatible with Windows 7

Let's describe each of above points in more detail:
1. Better offline support and support for occasionally connected clients
Separate TeamCompanion’s offline mode doesn’t exit any more – we’ve merged it with Outlook’s offline mode switch (File\Work Offline menu option). Previously TeamCompanion’s offline mode was available in the Options dialog which wasn’t discoverable. We have heard the feedback and reorganized both internal logic and UI.
We deal with occasionally connected situations much better than before – using logic running in the background TeamCompanion detects if the Outlook is online or not and adapts itself. Actions that automatically connect to the server (like scheduled work item query execution) are executed only if Outlook is really online.

2. Improved Work item edit form
Work Item edit form is obviously one central piece of UI in TeamCompanion. There are some new actions in the form’s toolbar (new buttons in yellow):

Refresh/Undo actions are supported now.

There are different new ways to send work item as mail. Four alternatives are supported: send work item as mail with or without attachments and with or without subsequent attaching of the mail back to the work item after the mail is sent.

The default 'Send Work Item as Email' action type can be set in the appropriate options dialog.

Two new buttons in the upper right corner of the work item form make it very easy to find emails related to the work item – they search for mails containing either work item Id or Title. By default all mail folders are searched, but the search can be done in just some specific mail folders (configurable in Options dialog). The result of the search is the usual mail list UI in which we can execute all standard mail related actions.

3. Improved Work item preview (Support for history; preview is now fully customizable)
Workitem HTML preview is fully customizable. There are three ways to influence the content of the work item preview:
• declarative – the list of the fields to be included or excluded from the preview is saved in the registry
• programmatic – you override the xsl file used for formatting the xml generated by the TeamCompanion. You can do anything you like there.
• mixed - above options combined.
Details of preview customization are beyond the scope of this overview and will be covered in some future blog entry.

Second new feature of the HTML preview is the support for the work item history. This can be switched on and off in appropriate Options dialog tab. Additionally, for performance reasons, user can set the number of history entries that will be available in the preview.


Upgrade users having work item query folders where some work items already exist, need to remove and reload these work items for the History to become visible in the work item preview. 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 history in the preview.

4. Improved Work item from Mail action
In addition to mapping email fields and work item fields used when creating a work item based on an email, it is now possible to fill email fields with constant values. Internally, we call this feature “poor man’s work item templates”. It is especially usable to set the current iteration and (at least a part of) area information.
With this little feature, in many occasions, just one click is enough to create fully populated and valid work item from mail.


5. Improved Open related object action – for emails multiple related objects are offered; related work item for Outlook Appointments
Open related object action was introduced in TeamCompanion 2.1. This feature makes it easy to open TFS objects mentioned in an email (work item, changeset or build). In 2.1 we were able to offer just one most significant object and in v2.2 as long as there are multiple objects referred to in a mail, we will offer all of them. There are different methods we use to find object references (like parsing object urls, different patterns in the mail content etc.). If you believe we should be able to find a reference to an object in some mail of yours and we don’t, please contact me directly and hopefully we will support it in some future version.


6. Improved Reports support (new conversion formats for Reports; support for Canceling)
Two new conversion formats for reports are supported- embedded HTML and Web Archive. Embedded HTML is the new default. This way the text in the report description isn’t just a part of the image anymore and can be selected, copied etc.
Cancelling report execution is also supported.


7. Improved Send Work Item as Mail action (‘with attachments’ option including attaching created mail back to the Work Item)
There are four ways to send a work Item as Mail – with or without attaching Work Item attachments to the mail and with or without subsequent attaching the mail to the Work Item after the mail was sent. Wherever there are Work Items in the TeamCompanion’s UI they can be sent as mail.
The content of the mail is completely configurable (but that is not new in v2.2).

8. Improved usability/ease of use
There are many small usability enhancements
o Indicator during query execution – the text “(Working…)” is appended to the Query name during the query execution
o Ability to select server and project while creating wi from mail or attaching mail to existing work item

o Work Item form size and position remembered
o Better default work Item Query result grid column widths
o More responsive UI due to the asynchronous execution of following actions
- Scheduled query execution
- Opening a work item
- Creating new work item from Outlook items or attaching mail to work item
- Export to Excel and Project
o Reasign To combo supports auto complete – we filter the list of available people as you type which is especially helpful for large teams i.e. if there are hundreds or thousands of people in the list
o Work Item Field lists (e.g. in the Work Item Query Editor) support type ahead – similar as above

9. TFS 2010 Beta support
TeamCompanion v2.2 works with prerelease versions of TFS 2010 using the Team Explorer 2008 SP1 upward compatibility support. The restrictions imposed by the scope of compatibility support are described here.
In order to connect to the TFS 2010 server it is important to enter the whole url of the server including virtual folder and project collection like this:
http(s)://[serverName]:[port]/[vdir]/[collectionName]
Where the is an optional, server level argument.
Example connection Strings looks like: http://myserver:8080/tfs/Collection or http://server:8080/tfs.

If the server virtual folder is defined during the server installation it must be included in the server url. If you don't explicitly put project Collection name in the server url, you will be connected to the Default Collection.

With TFS 2010 server, most of the features work as expected. Some notable exceptions are listed here:
-Execution of hierarchical work item queries; work item query results are only flat lists
-Reports don't work (for this we need 2008 compatibility bits that should be available in the Beta 2 timeframe)
-New work item controls (Test steps etc.) are not displayed

Expect this compatibility issues to be solved in future TeamCompanion versions.

10. Compatibility with Microsoft CRM Outlook Addin
Microsoft CRM Outlook Addin seems to be relatively fragile and in some cases it refused to load if TeamCompanion was present. TeamCompanion v2.2 behaves the way CRM Addin expects, waits for it until it is initialized and only then it loads itself. This way these two Outlook Addins can coexist peacefully.

11. TeamCompanion v2.2 is compatible with Windows 7

TeamCompanion is tested for compatibility and reliability on Windows 7.

For this version, the UI has had considerable amount of improvements. We engaged SSW to do a Software Audit for UI usability and Adam Cogan was great as we went back over 4 iterations. We hope you notice the difference. If you are interested in learning more see SSW's User Interface rules or have an auditor performed on your own software.

There are many others that have helped shaping TeamCompanion v2.2, but I would personally like to thank Gregg Boer from the Team Foundation Server’s development team, who was willing to use various prerelease versions in his daily work and to test them thoroughly. Gregg suggested many features that in the end appeared in the above list.

Hopefully this rather long blog entry gives you a quick flavour of TeamCompanion 2.2 and where we are going with this release. As soon as you try it out, we would love to hear what you think of it.

TeamCompanion for Outlook v 2.1 released

Earlier this week Ekobit released The TeamCompanion for Outlook v2.1. Although numbered as a minor .1 release this version brings not only bug fixes, improved performance and enhancements to existing features, but also some exciting new features. This way TeamCompanion fulfills its goal to provide the general purpose TFS client integrated in Outlook with rich feature set aimed at nontechnical users, but useful to anyone wanting to combine Outlook’s collaboration and communication features with the ability to access TFS artifacts.

This release is a free update for all existing customers.

Following is the list of new and improved features of TeamCompanion:
• Reports (including multiple saved parameter sets for each report)
Support for reports in TeamCompanion lets you use all standard TFS reports directly from Outlook including the ability to send the report as mail or create an Outlook task or an appointment with the report inside. This feature also lets you save the parameters with which you usually execute each report, so that you can access already configured report with just one click. For each report you can save multiple parameter sets. My favorite usage pattern is to add such preconfigured report to the favorite folder and have it there available for fast and easy access. Read more here.


• „Query by example“ Work Item Query editor (including full-text search support)
Query by Example (QBE) is a simplified Work Item Query editor that makes it easier to define usual everyday Work Item Queries. Queries are defined by entering values in already available placeholders for specific most frequently used Work Item Fields (like State, Priority, Iteration or Area Path etc.). QBE also supports full text search in any text or html work item field. There is full two way synchronization between QBE and standard grid based Query Editor so that you can edit search criteria in any of these two editors and freely switch between them. Read more here.

• Powerful online and offline work item search capabilities including desktop search integration
With Query by Example query editor for full text online search and desktop search integration for full text offline search in any work item field, TeamCompanion gives you all the tools you need to find the information you need.

• Attaching mails to work items using drag-n-drop
Just drag a mail to the work item’s attachment tab and drop it there. TeamCompanion will take care of the rest. You can also attach files with drag-n-drop or paste pictures easily too.

• Open related object (work item, changeset or build) action for notification mails
Whenever you receive a notification mail from the TFS that refers to some TFS object this feature will let you open that object with just one click. This works not only for work items, but also for changesets and builds. Opening a changeset from a notification mail is my personal favorite, since it gives you the ability to follow source code changes directly from Outlook – you receive a notification, open the changeset, in the list of changed files open the difference and there you have the view of the source code changes. All without leaving Outlook.

• Work Item Query management
Configuring "Group by" columns is now a part of the work item query editor. This setting doesn’t change the query itself of course. It rather defines the way the query result will be displayed in Outlook.

• Scheduled Work Item queries
With scheduled query feature introduced in TeamCompanion 2.0 end users can configure work item queries to be automatically executed periodically. With this release administrators get the ability to control how frequently queries may be executed to prevent too frequent execution that may cause heavy load on the Team Foundation Server.

For the complete list of features visit the TeamCompanion’s homepage.
TeamCompanion is available as a free 90-days fully functional trial.