Server Side Extensions

Server-side plugin organization and deployment



To write a server-side plugin, you'll need to include jar libraries from <TeamCity web application>/WEB-INF/lib directory to your classpath. Default TeamCity web application is "<TeamCity home>/webapps/ROOT.

Server-side plugins are delivered as a set of jar files, one of which contains the plugin descriptor file. Such plugins can process data which is logged from build agents in some specific way, provide additional web content, create custom notifiers, etc.

The plugin code should be active - plugin components should register themselves in various TeamCity managers and components. Corresponding TeamCity managers should be passed via constructor (they will be passed by Spring framework via autowiring, see Descriptor section below)

If you are extending the Web UI, please also refer to Web UI Extensions.

Descriptor



The plugin descriptor file is named build-server-plugin-<unique_plugin_name>.xml and contains component definitions according to Spring configuration file syntax.

Base configuration of the server can be found in /WEB-INF/lib/server.jar!/META-INF/buildServerSpring.xml and /WEB-INF/buildServerSpringWeb.xml files.

Example descriptor:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">

<beans default-autowire="constructor">
  <bean id="emailNotificator"
        class="jetbrains.buildServer.notification.email.EMailNotificator"/>
  <bean id="emailNotificatorSettingsController"
        class="jetbrains.buildServer.controllers.email.EMailNotificatorSettingsController"/>
</beans>

Deployment



Put the jar files with server side plugins into the /WEB-INF/lib/ directory on the server.

Writing Server-side Extensions



Build server listeners



Should extend jetbrains.buildServer.serverSide.BuildServerListener interface and register itself using SBuildServer.addListener() method. There is also a convenient jetbrains.buildServer.serverSide.BuildServerAdapter class to write such listeners.

public class MyListener extends BuildServerAdapter {
  public MyListener(SBuildServer server) {
     server.addListener(this);
  }

  // Your overridden methods go here
}

Server-side extension points



TeamCity server has a number of extension points, where a plugin can provide some additional functionality. An extension point is defined in terms of interface, which extends jetbrains.buildServer.serverSide.ServerExtension. There are several such interfaces/extension points. To register an extension, a plugin should invoke method jetbrains.buildServer.serverSide. ServerExtensionHolder #registerExtension(extension_class, pluginCode, extensionObject).

Here is a list of some extension points:

• jetbrains.buildServer.serverSide.ParametersPreprocessor allows to modify build and run parameters which are sent to TeamCity server before build start

• jetbrains.buildServer.serverSide.DataCleaner allows to register additional clean-up hooks for the case when build is removed

• jetbrains.buildServer.serverSide.GeneralDataCleaner allows to register global additional cleanup procedures which are called once per cleanup

• jetbrains.buildServer.serverSide.MainConfigProcessor allows to read/write global TeamCity data, which are saved in XML file main-config.xml

• jetbrains.buildServer.serverSide.TextStatusBuilder allows to modify build status description line, like Tests passed: 343, Fitnesse: 23

Some core components



jetbrains.buildServer.serverSide.SBuildServer



This is one of the core components of the TeamCity server-side support. It manages many aspects of TeamCity, for instance:

• Access to TeamCity installation information, system and configuration directories

• Global TeamCity listener, which is notified about most events in TeamCity BuildServerAdapter

• Global build history access via appropriate findNNN methods

• Access to various TeamCity managers (but it is much better to use dependency injection provided by Spring to achive this, because these getXXXManager methods may disappear in the future)

• Extension of TeamCity via various extension points, see ServerExtensionHolder (please also use DI)

• TeamCity server version, build number

• Executor service for short-time processes.

jetbrains.buildServer.serverSide.ProjectManager



This component provides access to TeamCity project structure, allows to list all available projects and build configurations, as well as modify their settings. See also jetbrains.buildServer.serverSide.SProject and jetbrains.buildServer.serverSide.SBuildType

jetbrains.buildServer.serverSide.RunningBuildsManager



Manager for currently running builds. See also jetbrains.buildServer.serverSide.SRunningBuild

jetbrains.buildServer.serverSide.BuildHistory



Provides access to build history (you can also access historical builds for a build configuration using methods in jetbrains.buildServer.serverSide.SBuildType)

jetbrains.buildServer.users.UserModel



Manager of various user-oriented operations in TeamCity, allows to list/find user accounts, create user accounts etc.

jetbrains.buildServer.vcs.VcsManager



A basic starting point for various VCS-related operations, including, but not limited to:

• VcsSupport management (add your VCS support here!)

• Obtain file contents

• Create/Edit VCS root, check its status

• Find committers between particular builds