A plugin to implement a build configuration notifier

Hello James!

We have a short article on custom notifier implementation; at a minimum, you would have to implement Notificator (I suggest to extend NotificatorAdapter since this way you do not have to implement every notification event) and register implementation with NotificatorRegistry service. In the scenario you have outlined, you need to override/implement notifyBuildFailed, notifyBuildStarted, notifyBuildSuccessful methods - these will be called by server on the corresponding events. 

If you want Notifications build feature to recognize your notifier (so that you may set it up as a build feature rather than user-level notification rule), you would also need to implement BuildTypeNotifierDescriptor (please refer to the BuildTypeSlackNotifierDescriptor class in Slack plugin for implementation example). Otherwise, no further actions would be needed. 

NotificationEventListener - you do not have to implement this one. In theory, you could add one so our server-side class would look it up and fire its methods according to the server events, but Notificator implementations already do the same. 

AdHocNotifier is a different story. It is an interface added to implement https://youtrack.jetbrains.com/issue/TW-64920/Notifications-from-service-messages and https://youtrack.jetbrains.com/issue/TW-65097/Allow-to-use-configured-Slack-connection-during-a-build; currently it has just one implementable method which will be used by a corresponding service message. Right now, this interface is in the closed part of the API but we plan to move it into the OpenAPI shortly.

I hope this helps; for any questions or concerns, please do not hesitate to reach out.  

Hey Fedor!

Thanks for the reply.  That all makes sense to me - but I don't think the BuildTypeNotifierDescriptor is currently part of the OpenAPI?

For my use case, a personal notification doesn't make any sense - but that would be OK, I can just not have a UI for it if the BuildTypeNotifierDescriptor will mean I can send the notifications from the Build itself.

The AdHocNotifier sounds really interesting, and is actually the perfect use case for my plugin, which is primarily a Runner.  Sending service messages would give super fine control over the updates.

Hello James,

Yes indeed - BuildTypeNotifierDescriptor is also a part of the internal API. Speaking of the AdHocNotifier, I am working on the pull request now and hope to send it for review shortly. When this is done and interface is exposed (along with couple helper classes), I will provide you with an update and details on how the corresponding service message works. 

Please mind that this service message will only be a part of 2023.05 release which is planned in May - is it OK with you? 

Hey Fedor

That sounds good - the 2023.05 release would be great for the AdHoc. I look forward to hearing more!

Are there any plans to add the BuildTypeNotifierDescriptor part of the OpenAPI?  I'd be interested in that too if it was an possible (for a different notifier!)

Thanks

j

Hello James,

I am most sorry about prolonged delay with response here. The corresponding interface has been moved to OpenAPI and is available in org.jetbrains.teamcity:server-api:2023.05-SNAPSHOT artifact; it has also been renamed to ServiceMessageNotifier. The methods to be implemented are getServiceMessageNotifierType and sendBuildRelatedNotification. Former should return an unique type of your notifier that will be used in service message invocation. Latter accepts a message, an instance of running build and other parameters that were passed with the service message (see below for the details).

The service message to be used is 

##teamcity[notification notifier='<notifierType>' message='<message>' otherParam1='' otherParam2='' ...]

where notifierType is the type you return in getServiceMessageNotifierType, message is the message that will be passed to sendBuildRelatedNotification, and other params will be passed as a map of parameters into the same method. For example, here is how email notifications are currently being sent:

##teamcity[notification notifier='email' message='message' subject='subject' address='user@example.com,user2@example.com']

I strongly recommend to throw ServiceMessageNotificationException if your method fails to send a notification - TeamCity core will catch it and will write a warning in the build log.

This is about it; should you have any questions about implementation, please do not hesitate to reach out. The functionality you described sounds like it could be helpful to other users of TeamCity - if you would be willing to consider making an open-source plugin or publishing the binaries on our marketplace, I would be happy to assist with development. 

In regards to BuildTypeNotifierDescriptor - I will double-check with our devs on this and will circle back to you shortly. 

Hi there.

So it's taken a while, but I eventually got there.  I've also managed to get around to making the plugin public here:
https://github.com/jamescallin/teamcity-UEBuildGraph
Overall, this is part of a Runner to help with Unreal Engine builds that use Build Graph to drive the process.  The main part is to launch that process, and then to parse the logs as they are generated to better highlight errors and warnings.  It also finds additional information in the logs (for example, the Cook Stats) and displays them for each build.  I've only just published it, and i'll be adding in some screen grabs once I can make some that don't contain confidential information.

The AdHoc notifier is used to send updated to an Unreal Game Sync metadata server.  It turned out to be super simple to implement, once I'd gotten my head around how best to store the server address so it could be shared :-)