Prerequisite

The Integration Pack for Microsoft Team Foundation Server 2010 (TFS IP) is developed using Opalis Quick Integration Kit (QIK).  Therefore, .NET framework 3.5 has to be installed.  In addition, dependencies of TFS 2010 DLL's need to be in the Global Assembly Cache (GAC) by either:

  • Install Visual Studio 2010 any version with Team Explorer, OR
  • Find a machine installed with above product, copy all files at %ProgramFiles (x86)%\Microsoft Visual Studio 10.0\Common7\IDE\ReferenceAssemblies\v2.0 to GAC using gacutil.exe (in Visual Studio 2010 or Windows platform SDK) or File Explorer (drag and drop to %windir%\Assembly).

The TFS IP is designed to work on both domain-joined trusted network or private machines in a workgroup.  Before using the IP, make sure the correct TFS server URL has been got from the sys admin, e.g. "http://scxtfs2:8080/tfs".

Installation

  1. Copy TFS 2010 assemblies shown in previous section to both the Designer Client and the Runbook Server (previously known as “Action Server”) machines.
  2. Download the latest version of the IP.
  3. Register the IP on the Management Server.
  4. Deploy the IP on the Runbook Server and the Designer Client.

Configuration

The prerequisite configuration for the IP can be accessed by Team Foundation Server on the Options menu. The Type of the configuration is "TFS Connection Settings".

  • Team Foundation Server URL: for instance "http://scxtfs2:8080/tfs".
  • Logon domain (RunAs), User name (RunAs), Password (RunAs): if the credential used to access the TFS is not the service account which is used to run the Runbook Server, one can use this setting to impersonate another user. For example, the machine is in corpnet, the logon user for the Runbook Server is REDMOND\scxsvc, but we want to use REDMOND\zhyao to query/file bugs, we will enter "REDMOND", "zhyao" and "(password here)" in the settings. This should work for cross-domain scenario as well.

Another way to pass the credential: if the Runbook Server machine is not in the same domain of the TFS access credential, for instance accessing http://scxtfs2:8080/tfs in REDMOND domain using SCX\scxsvc in untrusted SCX.COM domain, leave domain/username/password empty to disable the impersonation and add the access credential to the system by:

   cmdkey /add:scxtfs2 /user:REDMOND\zhyao /pass:PasswordOfZhyao

Then the code will automatically use this credential upon connecting to TFS server.

Activities for work item tracking

Get Work Item

This activity retrieves detailed information of a work item by ID, which can be a Bug, User Story, Task, Test Case, etc. The published data is a subset of WorkItem object information.

Parameters

Name Mandatory? Description
Work Item ID Yes ID of the work item being retrieved
Custom Field Name 0…9 No

All fields will be retrieved and published in "Field Name"/"Field Value" pairs. Some of them will be published separately. If other fields need to be retrieved and published, use this parameters.

Note that any empty or invalid Custom Field Name will be silently ignored.

Download all attachments at folder No If Specified, all attachments will be downloaded to this folder.

Published data

Name Description
Number Of Fields Number of fields in the following key value pairs

Field Name

Field Value

[array]

List of all fields being retrieved

Custom Field Name 0..9

Custom Field Value 0..9

 
Area Path Selected TFS fields
Changed By  
Changed Date  
Created By  
Created Date  
Description  
History  
Id  
Iteration Path  
Reason  
State  
Title  
Type Type of the work item, e.g. "Bug", "Test Case", etc.
Downloaded Files List of file attachments being downloaded, each file name per line.

Predefined error conditions

  • Work item ID is equal to or less than zero.
  • Work Item is not found on the server.

Query Work Items

This activity queries the server using the Work Item Query Language (WIQL). For more information about WIQL, refer to MSDN document at http://msdn.microsoft.com/en-us/library/bb130306(v=VS.100).aspx. For instance, to query all the test cases across all projects,

select * from WorkItems where [Work Item Type]='Test Case'

Although it is straightforward to write the query, there is another way to create WIQL using Visual Studio.

  1. Create a query using Visual Studio.
  2. Save the file on the disk, for instance abc.wiq.
  3. Rename the file to abc.xml
  4. Open the file using IE.
  5. Here is WIQL

Note that the WIQL from a saved query is parameterized and some of the parameters (“@project” for example) will have to be edited before the WIQL can be run in the IP.

Parameters

Name Mandatory? Description
Work Item Query Yes WIQL String

Published data

Name Description
Area Path  
Changed By  
Changed Date  
Created By  
Created Date  
Description  
Number Of Objects Number of work items being returned
History  
Id  
Iteration Path  
Reason  
State  
Title  
Type  

Note that some published data in Get Work Item are not available in this activity.

Predefined error conditions

  • Work Item Query string is empty.
  • Failed to query.

Set Work Item

This activity changes the fields or states of a work item. Resolving bugs, closing tasks and so on can be performed using this activity.

Parameters

Name Mandatory? Description
Work Item ID Yes  
Area path no  
Description no  
Assigned To no  
History no  
Iteration Path no  
State no  
Title no  
Custom Field Name 0…9
Custom Field Value 0…9
no  
File attachment to be added no specify this to attach a file on the local machine.
File attachment to be removed no Remove the specified file attachment

Published data

Same as “Get Work Item”.

Predefined error conditions

  • Work Item ID is equal to or less than zero.
  • Custom Field Name cannot be found in the fields of the work item.
  • Failed to query the work item.

New Work Item

This activity creates a new work item, such as Bug, Test Case, User Story, or Task.

Parameters

Name Mandatory? Description
Project Yes The team project where the work item will be created
Type Yes Type of the work item, e.g. “Bug”, “Task”, “Issue”, etc.
Title Yes  
Assigned To no  
Area Path no  
Description no  
History no  
Iteration Path no  
Custom Field Name 0…9
Custom Field Value 0…9
no  
File attachment to be added no  

Published data

Same as “Get Work Item”.

Predefined error conditions

  • Work Item ID is equal to or less than zero.
  • Custom Field Name cannot be found in the fields of the work item.
  • Failed to query the work item.
  • Some fields have invalid values. In this case, those field will be listed along with their values.

Monitor Work Items Query

This activity periodically poll the work item store using the given Work Item Query and triggers when the number of query result changes. It uses WorkItemStore.QueryCount method and theoretically consumes less amount of resource than WorkItem.Query.

Parameters

Name Mandatory? Description
Work Item Query Yes  
Query Interval no.  Default=60 seconds  
Get Changed Work Item no.  Default=False

When it is set to False, the activity will periodically query the work item store and get the count if the query is executed. If the count changes, the activity is triggered and the count is published.

When it is set to True, before the query of count, the activity will execute the query and get the list of work items. After the count changes, the query will be executed again, and the difference will tell which work items have changed.

If the user only cares if the query count changes but not any details, this input should be set to False

Published data

Name Description
Work Item Query  
Number Of Objects Number of results would be returned using “Query Work Items” activity

Activities for version control

List Version Control Items

This activity lists all items (files and folders) on the version control server under the given folder recursively or non-recursively. No workspace is needed for running this activity.

Parameters

Name Mandatory? Description
Version Control Server Path Yes

Absolute path of the folder/file with wild card on the server. For instance: $/zzSandbox/*.cs for all C# files under zzSandbox folder, $/SC_Orchestration

Recursion Type Yes
  • Full: recursively list all items.
  • None:
  • OneLevel: Recurse one level only

Published data

Name Description
Number of Objects Number of files and/or folders
Item Type File or directory
Server Path Absolute path of the item on the version control server
Content Length Length of file, or 0 for folder
Changeset ID  
Check-in Date  

Predefined error conditions

  • Version Control Server Path is empty.

Download File

This activity downloads a file from the version control server to the local machine directly. No workspace is needed.

Parameters

Name Mandatory? Description
Server Path Yes Absolute path of the item on the version control server
Local Path Yes Absolute path of the file on the local machine

Published data

None.

Update Workspace

This activity updates the workspace on the local machine to the latest version and reports number of items being updated, etc. Note that a workspace needs to be created before running this activity.

Parameters

Name Mandatory? Description
Workspace Path Yes Absolute path of the workspace on the local machine

Published data

Name Description
Number Of Updated  
Number Of Conflicts  
Number of Failures  
Number of Warnings  

Check Out

This activity checks out an item recursively or non-recursively for editing, deleting, or adding. Note that a workspace needs to be created before running this activity.

Parameters

Name Mandatory? Description
Workspace Path Yes  
Local Path Yes  
Check Out Action Yes
  • Add
  • Delete
  • Edit
Recursion Type Yes  

Published data

None

Check In

This activity checks in the pending changes in the local workspace recursively or non-recursively. Note that a workspace needs to be created before running this activity.

Parameters

Name Mandatory? Description
Workspace Path Yes  
Local Path Yes  
Check In Comment Yes  
Recursion Type Yes  

Published data

None

Get Changeset

This activity retrieves details of a changeset.

Parameters

Name Mandatory? Description
Changeset ID Yes  

Published data

Items marked with "*" will be grouped as an Object if multiple build definitions are returned.

Name - Description
Changeset ID    

Check-in Note Name

Check-in Note Value

* Key-value pairs of check-in note.
Check-in comment    
Committer   User name who committed the check-in
Creation Date    
Owner   User name of the changeset owner

Property Name

Property Value

* Key-value pairs of changeset properties.
Work Item ID * work items associated with the changeset.
Title    
Change Type *  
Item Server Path * Server paths of files/directories in the changeset.

Activities for Team Build

Get Build Definitions

This activity retrieves all the build definitions for a given team project.

Parameters

Name Mandatory? Description
Project Yes Name of team project.
Build Definition Name No  

Published data

Items marked with "*" will be grouped as an Object if multiple build definitions are returned.

Name - Description
Project    
Number Of Objects   Number of build definitions being returned
Build Definition Name *  
Build Definition URI *  
Build Controller URI *  
Default Drop Location *  
Description *  
Enabled *  
Full Path *  
Last Build URI *  
Last Good Build Label *  
Last Good Build URI *  

Get Build Details

This activity retrieves all builds for the given build definition on the team project.

Parameters

Name Mandatory? Description
Project Yes Name of the team project
Build Definition Name Yes  
Maximum Builds Per Definition No. Default=5  
Build Number no  
Build Quality no  
Build Status no None, InProgress, Succeeded, PartiallySucceeded, Failed, Stopped, NotStarted, All
Finished After no  
Finished Before no  

Published data

Items marked "*" will be grouped as an Object if multiple builds are returned.

Name - Description
Project    
Maximum Builds Per Definition    
Finished After    
Finished Before    
Build Definition Name *  
Build Label Name *  
Build Number *  
Build Quality *  
Build Controller URI *  
Build Finished *  
Compilation Status *  
Drop Location *  
Drop Location Root *  
Finish Time *  
Log Location *  
Build Reason *  
Requested By *  
Requested For *  
Shelveset Name *  
Source Get Version *  
Start Time *  
Build Status *  
Test Status *  
Build URI *  
Associated Changesets * List of changesets associated with the build. Only ID and check-in user name are shown. Different changeset is deliminated by semicolon.

Request Build

This activity requests a new build and puts it in the queue for a given build definition on a team project.

Parameters

Name Mandatory? Description
Project Yes Name of team project
Build Definition Name Yes  
Drop Location no  
Priority no High, AboveNormal, Normal, BelowNormal, Low
Reason no None, Manual, IndividualCI, BatchedCI, Schedule, ScheduleForced, UserCreated, ValidateShelveset, CheckInShelveset, Triggered, All
Requested For no  
Shelveset Name no  

Published data

Name Description
Project  
Build Definition Name  
Drop Location  
Priority  
Reason  
Requested For  
Shelveset Name  

Set Build Details

This activity changes the properties of existing build details.

Parameters

Name Mandatory? Description
Build URI Yes URI of the build. This can be retrieved using “Get Build Details”
Build Number no  
Drop Location no  
Build Label Name no  
Log Location no  
Build Quality no  
Build Status no None, InProgress, Succeeded, PartiallySucceeded, Failed, Stopped, NotStarted, All
Test Status no Unknown, Failed, Succeeded

Published data

Same as published data for “Get Build Details”.

Monitor Build

This activity monitors queued builds and triggers when the status is changing or changed. When it is executed, all build details which status is InProgress will be retrieved and handlers will be set to capture the status changed/changing events. If no build is in progress (i.e. all are completed, or the queue is empty), the activity will wait for 10 seconds and query again.

Parameters

Name Mandatory? Description
Project Yes Team project where the build is defined
Build Definition Name Yes  

Published data

Name Description
Build Label Name  
Build Number  
Build Event StatusChanged or StatusChanging

Logging

Instead of using TraceLogger, Team Foundation Server IP uses the standard Event Tracing for Windows for the logging. Here is the list of parameters:

  • Provider GUID: {2FAF39E7-673B-4D89-BB89-E2CDADE0EA13}
  • Listener Name: TeamFoundationServerIP Listener
  • Provider Name: TeamFoundationServerIPProvider

One can

either use logman or netsh to collect the ETW logs. For instance:

Create trace:

   logman create trace TFSIP -o %windir%\Temp\TFSIP -p "{2FAF39E7-673B-4D89-BB89-E2CDADE0EA13}”

Start tracing:

   logman start TFSIP

Stop tracing:

   logman stop TFSIP

*.ETL saved at %windir%\TEMP can then be opened using XPerf or converted to XML using tracerpt:

   tracerpt -o out.xml -of xml %windir%\Temp\TFSIP_00001.etl

For more information on logman, refer to TechNet document at http://technet.microsoft.com/en-us/library/bb490956.aspx.

Last edited Aug 23, 2011 at 8:15 AM by Yao, version 3

Comments

nayanapriyankara Dec 1 at 1:00 PM 
Hi, I need to check the changes happening in the TFS bugs and write the changed work item titles to a text files. I tried monitor work item query to do that. But it did not succeeded. Is there any way to do it

JimBob_SF Aug 29 at 10:32 PM 
I'm testing this IP against TFS 2013 and it seems to work (mostly) so far. The key was using the VS 2010 Team Explorer on the runbook server. VS 2013 would not work. I've been following/commenting in this thread. I'm not a guru, so forgive the bumping it's taken me to get this far.

http://opalis.wordpress.com/2012/08/06/automating-the-export-and-tfs-check-in-of-workflows/

PatrickSeidl Nov 22, 2013 at 10:30 AM 
Today at 11:23 AM

Hi!

Will the IP support TFS 2013 or will there be an IP in (near-time) future?

Thanks and best regards,
Patrick