Plugin Utilities API

Jenkins GitHub Actions Jenkins Plugin Installslink=https://plugins.jenkins.io/warnings-ng

This Jenkins plug-in provides utility classes that can be used to accelerate plugin development. It can be used in conjunction with several JS based UI plug-ins to improve the user experience of your plug-ins as well. For more details please refer to the blog post or meetup video of the general topic "Hands On: Beautify the UI of Jenkins reporter plugins".

How to use the plugin

In order to use this small library, add a maven dependency to your pom:

<dependency>
  <groupId>io.jenkins.plugins</groupId>
  <artifactId>plugin-util-api</artifactId>
</dependency>

This plugin is included in Jenkins BOM, so there is no need to specify the exact version to include.

General structure of a reporter

In this section I will explain some fundamentals of the design of Jenkins, i.e. the Java model and the associated user interface elements. If you are already familiar on how to implement the corresponding extension points of a reporter plugin (see section Extensibility in Jenkins' developer guide), then you can skip this section and head directly to Extending Jenkins object model.

Jenkins organizes projects using the static object model structure shown in Figure 1.

Jenkins design
Figure 1. Jenkins design - high level view of the Java model

The top level items in Jenkins user interface are jobs (at least the top level items we are interested in). Jenkins contains several jobs of different types (Freestyle jobs, Maven Jobs, Pipelines, etc.).

Each of these jobs contains an arbitrary number of builds (or more technically, runs). Each build is identified by its unique build number. Jenkins' plug-ins can attach results to these builds, e.g. build artifacts, test results, analysis reports, etc. In order to attach such a result, a plugin technically needs to implement and create an action that stores these results.

These Java objects are visualized in several views, which are described in more detail in the following sections. The top-level view that shows all available Jobs is shown in Figure 2.

Jobs
Figure 2. Jenkins view showing all available jobs

Plugins can also contribute UI elements in these views, but this is out of scope of this guide, see Hands On: Beautify the UI of Jenkins reporter plugins for more details.

Each job has a detail view, where plugins can extend corresponding extension points and provide summary boxes and trend charts. Typically, summary boxes for reporters are not required on the job level, so I describe only trend charts in more detail, see ECharts Jenkins plugin.

Job details
Figure 3. Jenkins view showing details about a job

Each build has a detail view as well. Here plugins can provide summary boxes similar to the boxes for the job details view. Typically, plugins show here only a short summary and provide a link to detailed results, see Figure 4 for an example.

Build details
Figure 4. Jenkins view showing details about a build

The last element in the view hierarchy actually is a dedicated view that shows the results of a specific plugin. E.g., there are views to show the test results, the analysis results, and so on. It is totally up to a given plugin what elements should be shown there. In the next few sections I will introduce some new UI components that can be used to show the corresponding results in a pleasant way.

Extending Jenkins object model

Since reporters typically are composed in a similar way, I extended Jenkins' original object model(see Figure 1) with some additional elements, so it will be much simpler to create or implement a new reporter plugin. This new model is shown in Figure 5. The central element is a build action that will store the results of a plugin reporter. This action will be attached to each build and will hold (and persist) the results for a reporter. The detail data of each action will be automatically stored in an additional file, so the memory footprint of Jenkins can be kept small if the details are never requested by users. Additionally, this action is also used to simplify the creation of project actions and trend charts, for details see the ECharts Jenkins plugin.

Jenkins reporter design
Figure 5. Jenkins reporter design - high level view of the model for reporter plugins

You can find several examples of Jenkins plugins that use this library, e.g. the Warnings Next Generation plugin or the Forensics plugin.