What's an Issue Connector?
An Issue Connector is a simple way to connect your repository to your issue tracking system. After setting up an Issue Connector and connecting it to a Repository you've set up, every check in made to that repository will have its commit message parsed by the Issue Connector. The Issue Connector will take the commit message and apply a regex to parse the information the issue connector needs to generate a link to your issue tracker. The links generated are displayed in the build those change sets were applicable for.
How to Setup an Issue Connector
Issue Connectors are setup in Step 2 of the Project Wizard.
Click Create to open the dialog for creating a new Issue Connector. When choosing an Issue System, it's not too important to choose the correct one. The options in the Issue System drop down box are purely there to provide default values for the Server URL and Regex. The only fields that affect what the Issue Connector generates are Server URL and Regex. As long as those two fields are correct it doesn't matter which Issue System is selected.
How the Server URL and Regex work
When constructing a Server URL, you need to specify what parts of the commit message will be inserted into a generated URL. Lets assume you have a bug tracking system that requires a project and an id to be able to generate a URL for it. I would setup my Issue Connector like so:
In the above image I have created a Server URL with two substitution fields, {project} and {id}. Doing this means I must construct a Regex that will parse a project and id value out of commit messages. The regex engine we use allows named regex groups, so to take advantage of that we must match up the fields in the Server URL (project and id) with the named groups in the Regex. A named group in Regex is defined by using the <name> format. As you can see, the Regex string I've entered contains both a <project> and <id> field. I can now optionally verify if the Regex will generate a link from a commit message by supplying a dummy commit message and clicking Verify. The result is the URL that would be generated.
Note: The Server URL and Regex fields must contain an id field otherwise the Issue Connector is invalid and won't be saved.
Verifying the Regex also protects you from the Server URL wanting more group values than the Regex is told to match and return. For example, the following image shows what happens when the Regex is told to match only one group but the Server URL requires two. Notice how the Regex field does not contain a <project> group.
Finally, Verifying is most handy for checking your Regex validity. In this example, I've set my Regex to match any amount of numbers preceded by a # character. The dummy commit message I've supplied however does not have that pattern any where in it so I get no matches.
