Custom Templates and branches in tcWebHooks

New release available

There is a new release of the TeamCity WebHooks plugin (tcWebHooks – 0.9.12.158).

1. Adds branch details to the top level of the WebHook Payload Content object (fixes missing branch info in the Name/Value Pairs format).
2. Fixes an incorrect link on the WebHooks tab of a build.

Download it from SourceForge

Feature Branches and tcWebHooks

I’ve spent the last few evenings working through various issues with the branch support I added a few releases ago. Because I don’t use a VCS that TeamCity supports for branch building, I have never had the opportunity to thoroughly test the feature.

With the help of Jeff, we worked through a number of issues with the Name/Value Pairs (nvpairs) format and my handling of the Branch interface that was added in TeamCity 7.0

The main problem was that the Branch object was being added to the WebHookPayloadContent, but as a child object. Therefore, structured payload formats like JSON and XML were serialising out the contents of the child object correctly, but the nvpairs format was not. It appears that most users are using the nvpairs format. Especially those POSTing to the HipChat webservice endpoint.

As a result of these changes, I have added the following items to the payload object and they are serialised out for all payload formats at the top level.

• branchDisplayName – A friendly name like “master” or “feature01”.
• branchName – A name used internally by TeamCity. In my testing, it shows as “<default>” for the “master” and “feature01” for the “feature01” branch.
• branchIsDefault – A Boolean (note the uppercase B), that can be null, true or false depending on whether the build has feature branches enabled (null if not), is the master (true) or a branch (false).
  

These names are gleaned straight from the “Branch” interface in the TeamCity OpenAPI. I note with interest that the actual TeamCity implementation has different names (myBranchName, myDisplayName), so the JSON payload actually looks like this.

  "branchName": "<default>",
  "branchDisplayName": "master",
  "branchIsDefault": true,
  "branch": {
    "@class": "jetbrains.buildServer.serverSide.impl.BranchImpl",
    "myBranchName": "<default>",
    "myDisplayName": "master"
  },

The upshot is that the WebHookPayloadContent bean is what the custom templates use for building up the htmlBuildStatus message. That means that when configuring a custom message, you can only expect to resolve variables from this bean (using the getters). If value is not set for this instance variable, you will get “null” back. If the getter does not exist, you will get “UNDEFINED”.

A gotcha with the Branch object supplied by TeamCity

The Branch object and the new payload variables are completely dependant on TeamCity passing a useful Branch object to the sRunningBuild.
Please be aware that you will only get a sensible set of branch variables if all the following are true:

1. You are running TeamCity version 7.1 or higher.
2. The VCS that the build is built from has support for feature branches provided by TeamCity (currently in TC8 this is only GIT and Mecurial).
3. You have configured feature branch support in your build so that TeamCity is aware that you have more than one branch that could potentially be used for versioning your build. For more information, please see: http://confluence.jetbrains.com/display/TCD7/Working+with+Feature+Branches

If any of these are not correct, you will get null values for the new branch variables supplied by tcWebhooks.

A list of the object variables in the WebHookPayloadContent bean

As of tcWebHooks verion 0.9.12.158, you should expect the following to be available to the buildStatusHtml template engine.

Variable Name	Example Value
projectId	GitTestBuilds
message	Build Git Test Builds :: Git Test Build has finished. This is build number 22, has a status of “success” and was triggered by Net Wolf
buildStatus	Tests passed: 2
buildId	76
buildStateDescription	finished
extraParameters	null
buildInternalTypeId	bt9
branchName	feature01
comment	null
class	class webhook.teamcity.payload.content.WebHookPayloadContent
projectExternalId	GitTestBuilds
agentHostname	localhost
text	Git Test Builds :: Git Test Build has finished. Status: success
buildExternalTypeId	GitTestBuilds_GitTestBuild
buildResultPrevious	success
projectName	Git Test Builds
buildTypeId	GitTestBuilds_GitTestBuild
rootUrl	http://myserver.company.com:8111
triggeredBy	Net Wolf
buildResult	success
buildRunners	[Maven]
agentOs	Linux, version 3.2.0-51-generic
agentName	Default Agent
buildName	Git Test Build
buildFullName	Git Test Builds :: Git Test Build
branchDisplayName	feature01
buildResultDelta	unchanged
buildStatusUrl	http://myserver.company.com:8111/viewLog.html?buildTypeId=GitTestBuilds_GitTestBuild&buildId=76
projectInternalId	project5
notifyType	buildFinished
buildNumber	22
branchIsDefault	false