You are viewing the documentation of TeamCity 10.x and 2017.x, which is not the most recently released version of TeamCity.
View this page in TeamCity 2018.x documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

Skip to end of metadata
Go to start of metadata

To report custom server health items, do the following:

  • Create your own reporter
  • Create a custom page extension to render items reported by you

Reporting Server Health Items

To make a reporter, create a subclass of jetbrains.buildServer.serverSide.healthStatus.HealthStatusReport.

Particulary, you must override method jetbrains.buildServer.serverSide.healthStatus.HealthStatusReport#report(jetbrains.buildServer.serverSide.healthStatus.HealthStatusScope, jetbrains.buildServer.serverSide.healthStatus.HealthStatusItemConsumer).

The items should be reported according to the analisys scope passed as a parameter to this method using the appropriate method of resultConsumer.
If you try to consume an object which is not in the scope of the current analysis, it will be filtered out by the consumer and will not appear in the report.

This method is always called with system privileges (in all permissions mode). Any permissions checks should be avoided here.

While reporting items, additional data required for further items presentation could be provided.

Presenting Server Health Items to User

To present reported items, provide a custom page extension and connect it to PlaceId.HEALTH_STATUS_ITEM.
The simplest way to do it is to create a subclass of jetbrains.buildServer.web.openapi.healthStatus.HealthStatusItemPageExtension.

Handling Current User Permissions

To handle permissions of the user viewing the reported items, use the subclass of HealthStatusItemPageExtension.
In order to do it, override the jetbrains.buildServer.web.openapi.healthStatus.HealthStatusItemPageExtension#isAvailable
You can also limit the set of pages where your items should be presented to the Administration area of the Web UI by setting FALSE to jetbrains.buildServer.web.openapi.healthStatus.HealthStatusItemPageExtension#setVisibleOutsideAdminArea

The particular strategy of handling permissions depends on the report details. The proposed behaviour is to completely hide items from the user only if none of related objects is available. In other cases it makes sense to show the item, but filter all inaccesible objects.

Switching between Display Modes

There are the following places in the Web UI where Server Health items could be presented:

  • the report page (Administration | Server Health)
  • the notes section at the top of all pages (global items with severity more than 'info')
  • in-place (in the popups appearing on some pages).

To define in what display mode a server health item is presented, use
jetbrains.buildServer.web.openapi.healthStatus.HealthStatusItemDisplayMode. The HealthStatusItemDisplayMode.GLOBAL value is passed to the request when an item is shown on the report page, HealthStatusItemDisplayMode.IN_PLACE is used in other cases.

Here is an example of handling the display mode in a JSP page.

Presenting Results In-place

While presenting results in-place, it might be nesessary to know the ID of an object being viewed at the moment. The ID can be retrieved using the following requests:

  • on the Edit the VCS root settings page
  • on the Edit the Build Configuration setting page
  • on the Edit the Build Configuration Template settings page
  • No labels