Introducing the Templates Plugin

The Nectar 11.10 release that we just made has the Templates plugin, which I think is one of the very useful plugins that we added to Nectar that's not available in open-source Jenkins. So I wanted to talk about it a bit.

Many serious Jenkins users have had this common problem that they've got a lot of jobs that look similar. JENKINS-3157 , which is currently the most voted issue in JIRA, speaks to that same pain point. The Templates plugin is my answer to this problem.

What this plugin does, is to allow you to define a "model." A model is an abstract concept that fits your particular problem domain. You do this through defining a set of attributes, kind of like how you define a class with a set of properties in Java, or how you define a table with a set of columns in database. You then define a transformation, which converts this model into something that Jenkins understands.

This is all rather abstract, so let's look at a concrete example. We are going to define a hello world builder template, which lets you enforce the standard way to greet someone. You can then use this template to greet a lot of people in many jobs.

Installing this plugin, you get the "templates" menu on the left. You can click that and create a template:

You create a builder template from the same familiar wizard you use to create a job:

Then here is the main meat:

There are two main things to configure here: attributes and a transformer.

When you define a template, you first ask yourself, “What do I want my users to enter when they use my template?” The answer to that question becomes attributes. In this hello world builder, we want the user to configure who we are saying hello to, so we define one attribute named “target” for this purpose. The user should see the single text field for this, so we choose the type accordingly. The display name and inline help are self-explanatory. They control what the user will see when they are editing their free-style projects to use our new builder.

The second question you should ask when you define a template is, “How does it execute?” (or more generally, “How does it map to the terms Jenkins understands?”) The answer to that question becomes the transformer. In this tutorial, our builder will turn into a shell script that says hello (whereas your real template would probably turn into a shell script that gets some real work done, like building a component, running a test, etc.) So we’ll choose, “Generate a shell script to execute via Groovy.”

In the text area, we’ll fill the shell script that this build step is going to execute, but with expressions here and there of the form ${...} (because this is a Groovy template). ${target} refers to the actual value of the target attribute we defined above, and ${build.fullDisplayName} is a Groovy expression to access the getFullDisplayName() method (which returns the full name of the build) of the build object, which refers to the current build in progress. The ${build.fullDisplayName} needs to be quoted because this is going to look like test #1 , and # gets interpreted by shell as a comment sign unless you quote it.

Now that we have our first builder template, let’s create a free-style project that actually uses it. Go back to the Jenkins top page, and create a new free-style project. You’ll be taken to the configuration page. This part of Jenkins should already be familiar to you.

When you click “Add build step”, you should see the newly created “Say Hello World” builder. You click it, and you see the say Hello World builder added to your project. And you see the “target” attribute you defined in the configuration page.

I configured this to say hello to Kohsuke. If we save it and run it, lo and behold, you'll see that it works:

[workspace] $ /bin/sh -xe /tmp/hudson2322666548865862105.sh
+ echo Hello to Kohsuke from test #1
Hello to Kohsuke from test #1
Finished: SUCCESS

This allows you as the build guy to create and enfroce a certain way your stuff gets built/tested, and your users get shielded from all the gory details of how the build/test actually gets done. You can create a layer between Jenkins and your users, and make Jenkins talk in the language your users understand, instead of making them talk in the language Jenkins understands. This is one of the points of the template plugin.

Now, let’s change the definition of the template, and see how it affects the instances.
We’ll go back to the template definition by going back to the top page, clicking the “Templates” link in the left, and clicking the configuration icon on the right to the “Say Hello World” template.
Instead of saying hello, now we make it say good evening. Click “save” to save this new definition:

Now, when you update the template definition, all the use of this template automatically reflects the change you made. So without revisiting the configuration page of the freestyle job, let’s simply schedule another build and see its console output:

[workspace] $ /bin/sh -xe /tmp/hudson2322666548865862105.sh
+ echo Good evening to Kohsuke from test #2
Good evening to Kohsuke from test #2
Finished: SUCCESS

This is another point of the Templates plugin — when you change the definition, all the uses of this template get updated right away. So if you need to tweak how those high-level abstract concepts map to the lower level command sequences, you only need to edit it once and save it.

If you like what you've read so far (and I hope you do), please play with this. You can either download Nectar and play with it in a separate sandbox, or you can enable the secondary update center to install these plugins on your OSS Jenkins deployments.

And there's a lot more to the Templates plugin, which I hope to write about in a few days.
-- Kohsuke