High Level Overview
In TeamSupport we are focused on helping your organization provide the best Customer & Product support possible. If you are using Microsoft Visual Studio Team Foundation Server to keep track of bugs and projects and your support team have identified a problem that needs to be reviewed by your development team, the integration between the two Products makes it very simple for your teams to collaborate and improve your customer’s experience.
Currently, the integration supports TFS version 2015 installed, and the latest Visual Studio Team System (VSTS) Cloud based version.
How it Works
Work Items in TFS can be synced with TeamSupport Tickets in the following ways:
- A single Work Item in TFS can be linked with multiple Tickets in TeamSupport.
- Comments created in the TFS Work Item will also be created in the linked TeamSupport Ticket as Actions.
- Actions created in the TeamSupport Ticket will also be created in the linked TFS Work Item as Comments. You can push all TeamSupport Action types to TFS, or only one as defined in the integration below.
- Any changes made to the State, Type, or any of the Custom Mapped fields (below) in a TFS Work Item will by also be changed in the linked TeamSupport Ticket.
- The TeamSupport Product and/or Product Version maps to the TFS Team Project. You may create a relationship between the TeamSupport Product and/or Product Version to the corresponding TFS Team Project by indicating the Project Name in the settings in the Project section. There is a Project Name field on both the Product level and the Version level. The mapping logic is explained in the TFS Project/Version mapping section below.
- A work item in TFS cannot create a ticket in TeamSupport.
- Changes in TeamSupport Tickets are never synced to TFS Work Items except for the Custom Fields in the Custom Mapping section below.
Log into TeamSupport with an account that has Administrator rights and go to Admin->Integration->Team Foundation Server. You should see a screen like this:
- Instance Name: Provide a name for this configuration.
- TFS Host Name: Required. Enter your full TFS Host Name as described below:
- For 2015 TFS installed system you should include the protocol (http or https) and the port number if required. e.g. https://[Your Server]:8080
- Example for VSTS Cloud based system: https://[Your Account].VisualStudio.com
- TFS User Name: The User Name and Password OR the API Token is required. Enter the TFS username/email that will be used to create Work Items as described below:
- For 2015 TFS installed systems your User Name includes your domain in this format: domain\username
- For VSTS Cloud based system your User Name will be an email address.
- TFS Password/Confirm Password: The User Name and Password OR the API Token is required. Enter the password for the TFS account in the Password and Confirm Password fields.
- For VSTS Cloud based systems it is necessary to use “Alternate Authentication Credentials” for a successful authentication.
- Use Network Credentials: This field is required to be checked if you are using the installed TFS 2015 version. Otherwise, you may leave this field unchecked.
- TFS API Token/Confirm TFS API Token: The User Name and Password OR the API Token is required. The TFS Security Token can be found in your TFS account. Here are the instructions for VSTS accounts. The API Token is not available in TFS 2015 installed systems.
- Default Project Name: This field selects a default TeamSupport Product which maps with the TFS Team Project. When no Product is assigned to a ticket and the ticket is linked with a new Work Item, we use the Project Name specified in this field.
- Actions type to push to TFS as comments: Select the “All Types” option if all actions needs to be sent to TFS, otherwise, select the an Action Type from the list.
- Update TeamSupport Tickets Statuses: If you need to update the TeamSupport Ticket Status whenever the TFS Work Item Status is updated, check this option. It is important to verify that the different TFS statuses are also listed in as a TeamSupport Ticket Status.
- Exclude the following: A multi-selection box will appear if the “Update TeamSupport Ticket Statuses” box is checked. You may select all status which do not map to your Team Foundation Server.
- Update TeamSupport Ticket Type: If you need to update the TeamSupport Ticket Type whenever the TFS Work Item Type is updated, check this option. If your Ticket Types and Work Item Types are named differently, you may map the fields to each other in the Custom Mappings section during setup.
- Synchronization Active: Sets the synchronization to active.
- Always Use Default Project Name: If you would like to always use the Default Project Name listed above, choose “Always Use Default Project Name”. Otherwise, we will use the Project/Product match described below.
- Use All Ticket Types: If you would like to allow all Ticket Types to be synced with TFS, leave “All Ticket Types” checked. If you would like to limit the Ticket Types, uncheck this box and the select only the Ticket Types that you would like to be allowed to sync with TFS. The TFS box will only show up on tickets that have the selected Ticket Types.
- Save: Click the save button to save your changes.
- Custom Field Mappings (Optional): After you mark your synchronization as “Active”, your Custom Field Mappings will appear to the right of your other settings. These will allow you to map additional Ticket fields other than the defaults listed above including Custom Fields and Ticket Types.
Default Field Mapping
Below are the list of fields that are mapped between TeamSupport and TFS.
|Description||Description, ReproSteps, ect|
|Ticket Type||Work Item Type|
TFS Team Project/Version Mapping
The TFS Team Project is mapped according to the following logic based on ticket fields/values:
- If the field “Always Use Default Project Name” is defined, the “Default Project Name” value will be used in the TFS mapping for all tickets.
- The ticket page has a field called “Reported Version”. If a Version is selected for this field, and that Version has a Project Name value defined, that value will be used in the TFS mapping for that ticket.
- If the ticket has a Product selection and that Product has a TFS Project Name value defined, that value will be used in the TFS mapping for that ticket.
- If the ticket has a Product selection, but that Product does not have a TFS Project Name value defined, the Product name will be mapped against the TFS Project Name for the TFS mapping for that ticket.
- Finally, if the ticket being sent to TFS does not have a product, and there is a Default Project Name value assigned, this value will be used in the TFS mapping for that ticket.
Additional Field Mappings (Optional)
After you mark your synchronization as “Active”, your Custom Field Mappings will appear to the right of your other settings. These will allow you to map additional Ticket fields other than the defaults listed above including Custom Fields.
- Mapping Type: You may choose between Ticket and Ticket Type. Ticket fields are Standard and Custom Ticket fields found within TeamSupport. Ticket Type will allow you to map your Ticket Types from TeamSupport to your Work Item Type in TFS.
- TFS Field: Enter the name for your TFS Field
- TeamSupport Field: Select the corresponding TeamSupport Field from the list
- Add Mapping Button: Click this button to add the mapping and the mappings will display below. The mapping can be deleted at any time by clicking the “x” to the right of the mapping as displayed in the image above.
Linking Tickets and Work Items from the Ticket Window
Once the integration page is setup as described above, a TFS link section will become available on the right hand side of an existing Ticket. This option is not available on a new Ticket.
If you do not see this option on the right hand side of an existing Ticket, or if you would like to change it’s position, you may do so in the Ticket Page Order menu.
Creating a New Work Item
Clicking the “New Work Item” button will add the ticket to the queue to sync and the Work Item Title will display “Pending…”. When this process is complete, the box will change from “Pending…” to the TFS Work Item ID with a link. The “Work Item ID” is equivalent to the “ID” field found within TFS. Default and Custom Mapped field values will be used on the new Work Item. If the Product listed on the Ticket has a Project Name relationship defined, the associated TFS Team Project will be used. Otherwise, the default Project Name will be used as defined above.
A new TFS Work Item will be created and a remote link to the synced TeamSupport ticket will be added in the new Work Item.
Linking an Existing TFS Work Item
Clicking in the “Existing Work Item” button will allow you to enter the Work Item ID to sync with. The “Work Item ID” is equivalent to the “ID” field within TFS.
Enter the number and click on the Save button. The Work Item will be displayed in black font without a link to TFS. Once the sync has taken place a new remote link will be added to the synced TFS Work Item. Additionally, the TeamSupport ticket will contain a link to the TFS Work Item.
Removing a Ticket sync to TFS
You may click the “x” at any time next to the sync in order to remove the link to TFS.
Once a sync has been made, if you need to make a change to the Product selection, you will be prompted to first remove the TFS sync from the ticket.
TFS Work Item changes in the mapped fields listed above will be applied to the TeamSupport ticket. New Work Item comments will generate new TeamSupport actions. New actions in the TeamSupport ticket will generate their equivalent new comments in the TFS Work Item.
The synchronization runs every 15 minutes. Wait for at least 15 minutes after saving. Once it is done you should be able to refresh your ticket and see the updated data.
Logging and Troubleshooting
If your tickets are not syncing, you may look for errors in the “CRM Sync Errors” report which can be found in the Reporting Section. Additionally, logging reports can be found in the CRM Sync Logs report.
Additionally, TFS errors may be logged in the Ticket History. Ticket History can be found on the Ticket Detail Page by clicking More -> Ticket History. However, errors will only be reported in the Ticket History if they are specific to the ticket. For example, if the ticket sync has failed due to an authentication issue, these errors can be found in the “CRM Sync Errors” report as described above.
Need more help with this?