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.
On September 10, 2018, Microsoft renamed Visual Studio Team Services (VSTS) to Azure DevOps Services. For more information about this change, see this blog post. Here is additional information about the transition. The affect of this change within TeamSupport is that it may be necessary to use your Azure Organization URL Hostname in the TeamSupport integration in order for the linking to work.
How it Works
Here is a simple diagram of how the TFS integration works:
Additional details regarding the integration:
- Linking Tickets to Work Items:
- A single Work Item in TFS can be linked with multiple Tickets in TeamSupport.
- A Work Item in TFS cannot create a Ticket in TeamSupport.
- You may link a TeamSupport Ticket to a new or existing TFS Work Item.
- When creating a New TFS Work Item, the TeamSupport Ticket Type must match the TFS Work Item Type. Please be aware that in TFS, Work Item Types may also be dependent on the selected Project. Therefore, a successful Ticket Type/Work Item match may also be dependent on a Product/Project match. If a Ticket Type/Work Item Type match is not found, the mapping will fail. For your convenience, you have the ability to map a TeamSupport Ticket Type to a TFS Work Item Type of a different name.
- Initial “push” of Custom Mapped Fields: When a New Work Item is created, Default and Custom Mapped fields are pushed from TeamSupport to TFS. This step does not happen when a Ticket is linked to a Existing TFS Work Item. Future updates made within TeamSupport to Custom Mapped Fields are not sent to TFS.
- Work Item updates “pushed” to Ticket: Any changes made to the Default and Custom Mapped fields in a TFS Work Item will also be changed in the linked TeamSupport Ticket. During setup, you may define the behavior regarding updates to Ticket Type and Ticket Status.
- Actions and Comments are kept in-sync:
- Comments created in the TFS Work Item will also be created in the linked TeamSupport Ticket as Actions. Updates to existing Work Items will not be updated in TeamSupport.
- Actions created in the TeamSupport Ticket will also be created in the linked TFS Work Item as Comments. Updates to existing Actions will not be updated in TeamSupport.
- Image attachments (jpg, png, ect.) and other types of files are pushed to TFS from TeamSupport. However, inline embedded images are not considered attachments and therefore not pushed to TFS.
- You can push all TeamSupport Action Types to TFS, or only one as defined in Setup.
- Product/Project Mapping: 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 Product 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.
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. It may be necessary to use the Azure Host Name URL, which must be set to “primary” and can be found in the TFS organization settings page. The format for the Azure Host Name is: https://dev.azure.com/[your organization].
- 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 defines a default TFS Project. If 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. The mapping logic is explained in the TFS Project/Version mapping section.
- Action Type to push to TFS as comments: Select the “All Types” option if all actions needs to be sent to TFS, otherwise, select one 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 States and your TeamSupport Statuses are named the same, otherwise the mapping will not occur.
- Exclude the following: A multi-selection box will appear if the “Update TeamSupport Tickets 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 Mapping 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”. Additiona Project/Product mapping logic is explained in the TFS Project/Version mapping section.
- 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: 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, including Custom Fields and Ticket Types.
Default Field Mapping
Below are the list of fields that are mapped between TeamSupport and TFS.
|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 to 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, including Custom Fields and Ticket Types.
- Mapping Type: You may choose between “Ticket” and “Ticket Type”.
- Choosing “Ticket” will allow you to map Standard and Custom Ticket fields found within TeamSupport.
- Choosing “Ticket Type” will allow you to map your Ticket Types from TeamSupport to your Work Item Types in TFS. Mapping these fields will allow you to have the mapped relationship even if your Ticket Types and Work Item Types are named differently.
- TFS Field: Enter the referencename 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 setup is complete, 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.
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.
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.
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.
The first synchronization will start after 15 minutes. The next cycle will begin no sooner than 15 minutes. The timing of each subsequent cycle depends on it’s place in the queue, which is affected by the number of other items that require processing. Typically the timing of the cycles range from 15 – 60 minutes. 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?