Custom Templates and branches in tcWebHooks

Posted on Updated on

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
Advertisements

22 thoughts on “Custom Templates and branches in tcWebHooks

    Domas said:
    September 26, 2013 at 10:04

    I’ve recently updated TeamCity to 8.0.1 (build 27435) and updated tcWebHooks plugin to 0.9.12.158.

    When I try to open WebHooks tab from project I get the following notice: ‘Request was redirected to use external project id “SomeBuildName” instead of internal project id “project1”.’ and page is redirected to “/webhooks/index.html?projectId=SomeBuildName”.

    Should this have been fixed as mentioned in “Fixes an incorrect link on the WebHooks tab of a build.” or are there some steps I need to take after all these updates?

      Domas said:
      September 26, 2013 at 15:35

      Apparently I haven’t removed old plugin version from “TeamCity\plugins\.unpacked”.

      Removing old unpacked plugin version resolved the issue.

        netwolfuk responded:
        September 27, 2013 at 11:09

        Ah. Glad it was an easy fix. Thanks for the update.

    Robert J. Berger (@rberger) said:
    October 16, 2013 at 01:35

    Is there an easy way to have dynamic parameters that are the result of the Teamcity job be passed into the parameters / json / body of the webhook HTTP POST? For instance the Teamcity job may product a new asset and put it into a repo. At least the version number will be dynamically created by the Teamcity job. Is there a way to get that into the Webhook POST?

    Thanks!

      netwolfuk responded:
      October 16, 2013 at 02:34

      There is some code to do something like that. I’m not sure it’s completely wired up. I’ll test it and let you know.

    atlantageek said:
    November 8, 2013 at 14:25

    I’ve inherited the teamcity build that we have and just got it working again. The only remaining issue is that hipchat shows the ‘message’ field and not the buildStatusHtml field. in the message. Is there any way to force this. I’ve verified with RequestBin that the buildStatusHtml is being populated.

      netwolfuk responded:
      November 8, 2013 at 17:43

      I’m not sure why hip chat is not using that field. Probably best to ask their support team. They are very helpful.

    Quazie Kwaselow said:
    December 13, 2013 at 21:18

    Any way that the hipchat endpoint can be configured to show which feature branch a build is running from?

      netwolfuk responded:
      December 13, 2013 at 22:17

      Yes. The message sent to HipChat is templated. You can modify it using the docs at http://sourceforge.net/apps/trac/tcplugins/wiki/TcWebHooksCustomTemplates

      Sorry, I should have mentioned that in this bog post.

        Quazie Kwaselow said:
        December 16, 2013 at 19:31

        Adding the following snippet to the message doesn’t seem to work for the default branch:

        ${branchDisplayName}

        It instead drops the from the URL – works just fine with non-default branches though – any idea whats up?

        Quazie Kwaselow said:
        December 16, 2013 at 19:32

        Adding the following snippet to the message doesn’t seem to work for the default branch:

        a href=”${rootUrl}/viewType.html?buildTypeId=${buildTypeId}&branch_${projectId}=${branchName}”>${branchDisplayName}</a

        It instead drops the from the URL – works just fine with non-default branches though – any idea whats up?

        Quazie Kwaselow said:
        December 16, 2013 at 19:33

        Adding the following snippet to the message doesn’t seem to work for the default branch:

        a href=”${rootUrl}/viewType.html?buildTypeId=${buildTypeId}&branch_${projectId}=${branchName}”>${branchDisplayName}</a

        It instead drops the default in brackets from the URL – works just fine with non-default branches though – any idea whats up?

    […] Prior to the latest release, additional parameters were static text only. This release adds the ability to template them in the same manner as the buildStatusHtml message Custom Templates detailed in a previous post. […]

    Mick said:
    August 14, 2014 at 23:46

    It would be great if you could override the payload body to integrate with other 3rd party plugins, e.g. Slack. They have a specific JSON payload in the POST, but we have to have a intermediary app that takes these and forwards them on.

    Benedek Farkas said:
    September 4, 2014 at 16:33

    Hi netwolfuk! We are using your tcWebHook plugin for almost a year and it’s working great (I just updated to the latest version). I would like to ask you if there’s a way to configure the webhook payload for all projects at once. We have four projects with webhooks set up at the moment and it would be nice to have only one config for all of them. Thanks for the cool stuff!

      netwolfuk responded:
      September 4, 2014 at 19:01

      I don’t think it’s possible from the ui, simply because I don’t want users to inadvertantly setup a webhook for all builds. We have 60 projects and hundreds of builds.

      It might be possible to copy the webhook configuration from a project plugins settings XML file to the root project XML file. I’ve not tested that use case.

      Thanks for your complementary remarks.

    farkasb said:
    September 5, 2014 at 09:30

    “It might be possible to copy the webhook configuration from a project plugins settings XML file to the root project XML file. I’ve not tested that use case.”
    Yep, that’s what I was thinking about as well. I’ll post here my results when I’ll have any.

    So it’s not possible to configure the payload on the TeamCity UI, only by changing contents of the XML files, right?

      netwolfuk responded:
      September 5, 2014 at 09:35

      Yes. That’s right. But as I said I’ve not actually tested that use case. I’ll test it over the weekend. If it doesn’t work I’ll have a look through the code and see why not.

    […] was recently asked in the comments whether it is possible to add a webhook to trigger for all builds in all […]

    […] is a full list of the variables […]

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s