Setting up a TFS Integration

TFS integration with ProdPad uses a window service TFS ProdPad to mediate between a TFS server and ProdPad. There are several parts to getting the TFS integration for ProdPad set up:

  1. Install and set up TFS ProdPad windows service
    Download the .zip file here
  2. Create an integration within ProdPad for the TFS server

Prerequisites

  1. ProdPad Premium or Enterprise account
  2. TFS server
  3. .NET Framework
  4. Optional SSL certificate
  5. Open/public port suitable for SSL connections

Install and set up TFS ProdPad windows service

The TFS ProdPad service manages login to the TFS server in two ways:

  1. Username & password
  2. Impersonation

Username & password

With the username & password, each user that needs to interact with the TFS server from ProdPad will need to enter their username and password into the TFS ProdPad service panel to generate a unique key. The TFS ProdPad service will then use the username/password to create item & update items in the user’s name.

Impersonation

With impersonation a single username & password needs to be entered which has access to the TFS service. Each user who needs to interact with the TFS ProdPad service will have their TFS username entered into the TFS ProdPad service panel which generates the unique user key for ProdPad. TFS ProdPad service will then use TFS’s impersonation feature to create and update the work items in teh user’s name.

For this approach to be used TFS impersonation feature needs to be enabled on the TFS server. You can read more about impersonation here.

Additionally the proxy account needs to have permission “make requests on others behalf” set. Follow the instructions in the section “Setting Permissions for Proxy Account” below to set this permission.

Note:
ProdPad TFS Web API is a windows service. It does not require IIS. You can self-host a web API in your own host process.

Set up process


  • Specify a secured port number you intend running the Web API Service.
  • Check "Is Https" option if you wish to have ProdPad connect to the TFS         ProdPad service using SSL.

    Note: You’ll need to have a valid SSL certificate for the server the TFS ProdPad service is running on if you use this option.

  • Enter Team foundation server’s local URL. Click on Test connection to try it.
  • Click Save
  • Write down the "ProdPad Key"
  • Open tab User Accounts to manage TFS users

 

  • Enter TFS Domain of user’s TFS account
  • Enter TFS user’s username
  • Enter TFS user’s password. If you are using impersonation, only one of the accounts needs to have their password entered, all the others can be blank. If you are not using impersonation, then all the accounts will need to have their password entered.
  • Check "Log on", if this user account will log into TFS server. If you are using Impersonation one of the entered accounts will need this option checked. If you are not using impersonation all of the accounts will need to have this option checked.
  • Repeat steps 9 to 13 for each additional user
  • Click Save
    nb: If you wish to edit existing users, you can edit their domain, username and password in grid by double clicking on cell and clicking Save button under the grid.
    nb. If you wish to delete existing user, select its row, press delete key and click Save
  • Copy the ProdPad User Key for the user you want to set up for the ProdPad integration
  • If using impersonation, the proxy account (the one doing the impersonation) needs to have the following permission: "make requests on behalf of others". Follow the instructions in the section "Setting Permissions for Proxy Account" below.
  • Go back to the general settings page and click "Test Connection". If there is an problem please check the following:
    • Did you enter at least one user with option "Log on" checked?
    • Are the "Log on" account's credentials correctly entered into the user accounts tab?
    • Does the "Log on" account have valid permissions?
    • Is windows service running under valid TFS account? ProdPadTFSWebAPI service must run under account with valid TFS permissions. You can apply such account in windows services panel properties
    • Still having issues? Please check the trouble shooting section below for other possibilities
  • Go to Service tab to start or stop ProdPad TFS API windows service

 

  • Click Start

The TFS ProdPad service has now been installed and the security tokens (ProdPad Key & ProdPad User Key) have been created for use in the final part of the setup.

If you wish to check your Port and WAN access go to tabs Port Access and Wan Access in the TFS ProdPad service panel. Port Access tab will check if selected Web API port is opened and WAN Access tab will check if Web API is publicly available through this port!

Here is a video of the set up process as an additional reference should you need it:
Video: TFS Set up process

Creating Integration within ProdPad

This part sets up ProdPad so it knows when to send the information when you push an idea or user story.

  1. Click on Integrations menu option in ProdPad
  2. Click on the "TFS" option to start the creation process.
  3. Fill in the form adding in the name for the integration, the URL that the TFS ProdPad can be accessed at and the two keys generated in setting up TFS ProdPad service.
  4. Click "Create Integration"
  5. Next select which project you want the work item to be created in and the type of work item
  6. Next select which ProdPad fields are mapped to work item fields
  7. Next select which ProdPad statues map to the states in TFS

The integration is now set up and ready to use. You’ll be able to push ideas or user stories to the TFS server from the idea canvas.

Notes on Usage:

  • The workitems will be created in TFS with the "created by" set to the user that the ProdPad User Key matches. Each person that is going to integrate ProdPad with TFS in your team will need their own ProdPad User Key
  • An admin can create a TFS integration and make it teamwide. Others can then copy this integration, enter their own details (ProdPad Key & ProdPad User Key) and create a new integration with the same mapping as the one that was setup by the admin.
  • The admin must have access to the entire project directly or via a group. This could be either being added as a direct member for the project or being added to the “project administrators” group or “contributors” group. 
  • The API port is the port that the TFS ProdPad service will listen to for data from ProdPad. This port will need to be accessible from the public internet in order for ProdPad to communicate with TFS ProdPad service
  • The API port number doesn’t matter as long as it is not being used by another application.
  • The URL to enter for the integration in ProdPad is the publicly accessible URL with the port number that you entered above

Setting Permissions for Proxy Account

In order for impersonation to work, the proxy account needs to have permission to make requests of behalf of another user. To set this permission follow these steps:

  1. Go to the "Team Foundation Server Administrative Console"
  2. Select the Team Project Collections
  3. Select Administer Security
  4. Under Global Security, add the Proxy account
  5. Select the proxy account and check the "make requests on behalf of others" option. See the section "Setting Permissions for Proxy Account" above for instructions on how to do this.

 

Troubleshooting

  • Ensure that the API port is open to the public internet and no other application is using that port
  • If you get a Unknown SSL error then make sure the API port is properly bound.
  • Ensure that the SSL certificate being used is not self-signed
  • If using impersonation, ensure the proxy account has the permission "make requests of behalf of others"

SSL, Port Binding for TFS ProdPad service

For Secure Sockets Layer (SSL) communications, an HTTP server must have a certificate registered for each socket (IP address/port combination) that it is enabling for use with SSL.

1) Enable port binding

This command will enable “everyone” on this server to bind and listen on port 9000.

  1. open Command Prompt as Administrator
  2. type in: netsh http add urlacl url=https://+:9000/ user=\Everyone

Note: Replace the port number (9000) with the port number that you wish to use for ProdPad API.
Note: If you are transitioning from HTTP to HTTPS then you will need to remove the current port binding by running the following command before running the command above:

  • netsh http delete urlacl url=http://+:9000/

2) Import server certificate

Next you need to import a server certificate that will be used to provide SSL transport. If such certificate already exists, verify that it is trusted by the server itself, that it is not expired, and that the server has corresponding private key. Verifying that certificate is trusted is especially important if you are using self-signed certificates.
To import a certificate:

    1. Open MMC, then go to File – Add/Remove snap-in – select and add Certificates snap in – when prompted, select Computer Account and then Local Computer
    2. Expand Personal certificate store
    3. Right-click on the Personal certificate store, click All Tasks – Import
    4. Go through the wizard and make sure to select the following options:
      1. Make private key exportable = no
      2. Automatically select store locations for certificates = yes
    5. Once certificate is imported, double click on it and confirm that it is trusted, that private key is in the store, and that it is not expired

3) Configure port binding to use SSL certificate

Run the following command to add server certificate to your port listener:
netsh http add sslcert ipport=0.0.0.0:9000 certhash=1dca86867481b22c8f15a134df62af649cc3343a clientcertnegotiation=enable appid={02639d71-0935-35e8-9d1b-9dd1a2a34627}
Note that in this command we specify certificate hash value as a HEX string without spaces. This is our certificate’s thumbprint value. Apply any random GUID to AppId

 

WAN Address did not succeed error

The WAN tab gets the host's public address (public IP) with help of external "whatsmyip" service. It then adds the port number to it and tries to connect. If it fails (page not found or similar) then the host can not be reached through the public IP found by external service (for reasons like firewall rules, router not forwarding port to API host, etc).

You can also manually check it by entering http(s)://yourIP:port/collections in the the browser and see if you get a response!

You only need to check the “Is Https” option on the general settings if a certificate has been applied. Otherwise, leave that option unchecked.

 

Have more questions? Submit a request

Comments