What is an Issue Connector?
Issue Connectors are used as a simple way of generating hyperlinks to your issue tracking system. Once an Issue Connector is created, you can assign it to a repository you've previously setup in Continua. Whenever the next build is started, the issue connector will get the change sets associated with the build then parse those change set commit messages for issue id's. It will then take those issue id's from the commit message and generate a hyperlink to that issue in your issue tracking system. The list of hyperlinks will be displayed in the "Issues" tab when viewing a build. Issue Connectors do not interact with your issue tracking system, they just generate hyperlinks to it! It won't open or close issues or require any kind of login to your system.
Why use an Issue Connector?
Suppose you have created a Configuration that builds your product using source code from a Repository. To make this happen you would need to attach that Repository to the Configuration. Once the Repository is attached to the Configuration it will start attaching change sets from that Repository to the Configuration. When the Configuration is next built it will get the relevant change sets from the Repository and attach them to the build. Lets say you've set up a Repository Trigger so every time a check in is made to the Repository the Configuration is built. In this scenario, the build will have the change set that triggered the build. If your companies' policy is to have meaningful commit messages that make references to your issue tracking system, then an Issue Connector can help out. The idea is that when something is checked into your Repository you insert the issue id into the commit message. With an Issue Connector, you can give it a regular expression to parse the issue id. By also providing an Issue Server URL, you can tell the issue connector to take the id it parsed out of the commit message and insert it into the Issuer Server URL and make a hyperlink out of it.
Example:
Set up an Issue Connector like so:
Issue Sever URL: http://www.issues.com/issue/{id}
Commit Message Regex: #(?<id>\d+)
Assuming a user commits something to the repository with the message "Fixed annoying deadlock bug, solves issue #29981". The Issue Connector would extract the value "29981" out of the commit message and use the Issue Server URL to generate the link "http://www.issues.com/issue/29981".
Issue Connector Rules and Restrictions
For an Issue Connector to work, the Commit Message Regex must have an id group.
The regular expression used to extract id's takes advantage of named groups. Whenever you use a named group in the regular expression it must have a corresponding tag in the Issue Server URL.
The example above has the id in both fields... the highltighed text shows the matching pair:
Issue Sever URL: http://www.issues.com/issue/{id}
Commit Message Regex: #(?<id>\d+)
You can have multiple groups in an Issue Sever URL/Commit Message Regex
If you have an issue tracking system that also takes in a project, it's possible to modify the regular expression to handle it.
Suppose your commit message is: "Fixed bug for issue #myawesomeproject-29981"
You could setup your Issue Connector like so:
Issue Sever URL: http://www.issues.com/{project}/issue/{id}
Commit Message Regex: #(?<project>\w+)-(?<id>\d+)
This would generate the URL: http://www.issues.com/myawesomeproject/issue/29981
You can have multiple issue id's in a commit message
Taking our first example's Issue Connector settings, a commit message "Fixed annoying deadlock bug, solves issues #29981, #44412 and #9881" would generate three links:
http://www.issues.com/issue/29981
http://www.issues.com/issue/44412
http://www.issues.com/issue/9881
Creating an Issue Connector
Click the icon that represents a hammer and spanner in the upper right hand corner of the page. It will bring up the Administration Menu, click "Builds".
On the left hand side of the page, under the section "Builds", click "Issue Connectors". It will display a list of Issue Connectors and a button which you can use to create a new one.
Click the "New Issue Connector" button to launch the new issue connector dialog.
The Name of the Issue Connector is used to reference the Issue Connector throughout the Continua UI. The Issue System is a drop down list of the more popular issue tracking systems. The option you select from the Issue System drop down has no effect on the Issue Connector, it simply pre-populates the "Commit Message Regex" and "Issue Server URL" fields. You could just as easily select "Custom" from the drop down and fill out the other fields with your settings. The two important fields are "Commit Message Regex" and "Issue Server URL".
Commit Message Regex
The Commit Message Regex is a regular expression that tells the issue connector to extract certain data out of commit messages and store them in a named group. To properly construct a regular expression to your needs, determine what your repository commit message will contain then write the regex to extract the issue id out of it. When extracting the id, make sure you use regular expression named groups to name that issue id match to the group "id". You may also add other named groups to your regex which can then be used when generating the URL.
Issue Server URL
The Issue Server URL is a template URL for generating links to your issue system. A simple way to construct the URL is to take a link to a certain issue in your issue system then substitute the issue id field in it with {id}. When the issue id's are parsed out of the commit message using the commit message regex, they'll then be substituted into the template URL where the {id} field was placed.