WebHook Templates : Anatomy of a Template

WebHook Template Anatomy

A WebHook Template consists of some attributes about a template and a set of build event templates which are mapped to teamcity build events.

WebHook Template structure as tree

• id - used to link from webhook to template
• description - shown in UI
• enabled - future usage
• rank - determines order in webhook format drop down
• format - only jsonTemplate supported at the moment
• status - bundled, user defined, etc. See below
• build event templates
  • default build event template (optional)
    • non-branch template content
      • useTemplateTextForBranch
    • branch template content
  • additional template 1
    • non-branch template content
      • useTemplateTextForBranch
    • branch template content
    • build event states
      • buildStarted
        • enabled
      • buildSuccessful
        • enabled
      • other states
  • ...
  • additional template n
    • non-branch template content
      • useTemplateTextForBranch
    • branch template content
    • build event states
      • buildStarted
        • enabled
      • buildSuccessful
        • enabled
      • other states

The above information is covered in more detail below.

WebHook Template structure as XML

It may be easier to see the structure as XML. This is how the templates are stored in webhook-templates.xml.

It's possible to view this by viewing /app/rest/webhooks/templates/id:<template-id>/rawConfig

<webhook-template id="test01" enabled="true" rank="1" format="jsonTemplate">
    <default-template use-for-branch-template="false">
    {
     "buildFullName" : "${buildFullName}" 
    }
    </default-template>
    <default-branch-template>
    {
     "buildFullName" : "${buildFullName}",
     "branch_display_name": "${branchDisplayName}"
    }
    </default-branch-template>
    <template-description>A Test Template</template-description>
    <template-tool-tip>A tempalte for Testing on 9.1.7</template-tool-tip>
    <preferred-date-format/>
    <templates max-id="0">
      <template id="0">
        <template-text use-for-branch-template="false">
        {
         "buildFullName" : "${buildFullName}",
         "build_finish_time": "${currentTime}"
         }
        </template-text>
        <branch-template-text>
        {
         "buildFullName" : "${buildFullName}",
         "branch_display_name": "${branchDisplayName}",
         "build_finish_time": "${currentTime}"
         }
        </branch-template-text>
        <states>
          <state type="buildSuccessful" enabled="true"/>
          <state type="buildFailed" enabled="true"/>
          <state type="buildFixed" enabled="true"/>
          <state type="buildBroken" enabled="true"/>
        </states>
      </template>
    </templates>
</webhook-template>

WebHook Template Detail

WebHook Template Statuses

A WebHook Template can have one of five states.

Status	Description
PROVIDED	This template was bundled with tcWebHooks. It will not exist in webhook-templates.xml
OVERRIDDEN	Template was bundled, but has been modified. The modified version will exist in webhook-templates.xml
USER_DEFINED	This template was defined by a local user. It will exist only in webhook-templates.xml
DISABLED	Has been disabled. The disabled version will exist in webhook-templates.xml Not yet implemented
UNKNOWN	If tcWebHooks can't determined from whence it came (unlikely)

Any PROVIDED template can be edited. It will be copied to webhook-templates.xml and any changes stored there and its status will change to OVERRIDDEN.

WebHook Template Attributes

Name	Type	Example Value	Description
id	string	slack.com-compact	A unique id for this template. Used to link webhooks to templates
enabled	bool	true	Disabling a template prevents it from being available for webhooks (to be implemented)
rank	int	100	Determines a templates place in the list when creating a webhook (smallest at the top)
format	string	jsonTemplate	Format of template content. Only jsonTemplate is supported

Build Event Templates

A template can contain multiple build event templates. A build event template contains the webhook payload and a list build events to which it relates. Eg, If the same payload is to be sent for both buildStarted and changesLoaded, then the build event template would contain references to both build events. A build event can only belong to one build event template at a time.

There is a special type of build event called the "default build event template". This optional template is the one used if no other template has a build event attached to it. If no default build event template is defined, then the webhook template will only support build events for which there is build event template attached.

WebHook Build Event Template Attributes

Name	Type	Example Value	Description
id	int	1	Used internally to identify build event templates
template	string	{ "buildState" : "${buildState}" }	The payload content
branch-template	string	{ "buildState" : "${buildState}", "branchName" : "${branchName}" }	The payload content for builds which run from a VCS with Feature Branch support enabled
use-template-for-branch-template	bool	false	Use the template for all builds, and ignore branch-template.
states	list	buildSuccessful, buildFailed	A list of states to which this build event template is attached