CloudBees Template plugin

With this plugin enabled, when you select New Job among other options there are several kinds of templates you can create. Create a template you can use as a builder, akin to "Execute shell script", "Execute Windows batch file", or "Invoke Ant", that you can use in configuring freestyle projects.

On your instance, select New item  Builder Template.

The name you enter here will be used as an identifier referred to from jobs using the template, as well as a default display name. There are no particular characters that are banned from this name, but it is good practice to use simple punctuation and no spaces. Just as with jobs, you can set a more pleasant display name later.

In this tutorial, we name the template "Say Hello World", and click "OK."

The next page that appears is the configuration page for this template. 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 editing freestyle 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. (Your real template would probably turn into a shell script that gets some real work done—or your template can translate into any other builders, but see the rest of the user guide for that.) So we’ll choose "generate a shell script to execute via Groovy".

In the text area, we’ll enter the shell script that this build step is going to execute, echo Hello to "${target}" from "${build.fullDisplayName}":

${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.

Configuring a hello world builder captures this template configuration. When you are done, click "Save" to save this template. Your template is now ready.

Now that we have our first builder template, let’s create a freestyle project that actually uses it. Go back to the Jenkins top page, and create a new freestyle 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. You also see the "target" attribute you defined in the configuration page, as depicted in Using a hello world builder.

This project is configured to say hello to "Kohsuke". Click save and schedule a new build. In its console output, you should see something like this:

So the template is running as expected.

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 dashboard, selecting the Say Hello World template, and Configure on the left in the template screen.

Instead of saying hello, we will now make it say good evening. Click "Save" to save this new definition:

Now, when you update the template definition, all the uses of this template automatically reflect 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:

Our change was indeed reflected in the output.

First, we go to the top of the page, click the New Job link, and select Job Template and provide a name. If our template were for building Jenkins plugins, we might call it "Jenkins plugin".

Note: Be aware that, by default, there is an Attribute already created that cannot be deleted. It is Name and refers to the name of the job item which will implement this job template. Do not override it, leave it as it is.

As with the previous tutorial, we just ask ourselves "What does the user [such as a plugin developer] need to configure", and in our case it just involves one question, which is whether the sources are in Git or still in Subversion. (Set aside from the name attribute, which is there by default.)

So in the attribute, we define the "scm" attribute to be a choice between Git and Subversion as shown in "SCM" attribute in the template:

Further down below, we configure the template to refer to jobs as "plugins." While this change is purely cosmetic and only affects what’s shown in the HTML for humans, it nonetheless makes it easier for users to understand, because in this context, "plugin" is a well-defined technical term that has specific meaning, while "job" is not.

Unlike the previous tutorial where we defined a builder template in terms of the transformation into a shell script that we execute, defining a transformation for a job template is more complicated.

The idea here is that we need to tell the CloudBees Template plugin how our model definition (that consists of the name attribute and the scm attribute) maps to the actual job definition that Jenkins understands (in our case that’s Maven2 job type). We do this by defining a transformation from the model into the XML persisted form of the Maven2 job type. The CloudBees Template plugin uses this transformation to obtain the XML, then load it up to Jenkins so that it understands how to run it.

So in this tutorial, we use "Jelly based transformation". Jelly is a template language that generates an XML. It is similar to JSTL (the tag library for Java Server Pages), and as long as your transformation doesn’t have a complex computation, it’s a reasonable choice.

The best way to define this transformation is by doing "programming by example" — that is, we manually configure one representative project, then obtain its XML representation. Let us assume you are starting with a Maven project which checks out code from a Git server. We’ll obtain its XML representation by simply adding config.xml to the job’s URL such as http://your-jenkins/job/this-job/config.xml. (Some web browsers fail to display the actual XML when browsing such URLs. Try using View Source or Save functions in such cases, or use a separate download tool like curl or wget.) Later we will see that there is a shortcut, the Load Prototype button (currently only supported for Groovy transformations).

Next, we take this XML and insert variables where appropriate. For example, you see an occurrence of some-repo in the Git configuration, so we replace that with ${name} as below:

There’s one more reference of some-repo down in the root module, but this is an inferred value. (We can tell because we are never asked to enter this information in the configuration page.) So we can simply remove the entire <rootModule> element. Unless you know the internals of Jenkins, this is a bit of a trial-and-error. Similarly, if you want to keep XML concise, you can remove a large number of elements from the configuration XML and Jenkins will still read it and provide default values. (Again, this involves a bit of trial-and-error in the general case, although there are some rules of thumb. For example, boolean fields are always safe to remove, as are most string fields.)

We also need another XML from a plugin that’s building in Subversion to complete this transformation. You can spot the section that configures Subversion, so we do the same variable insertion, and the result is as follows:

Now, to switch between two fragments depending on the value of the scm attribute. To do this, we use a tag library from Jelly that does the switch/case equivalent, called choose/when (XSLT has the same elements that do the same thing.) So where we had the scm tag, we add the following fragment:

See Jelly tag library reference for more about these tags. The entire transformation Jelly script will look something like this:

Now we save the configuration, and our job template is ready.

Go back to the top page, and click New Job. You’ll see the newly created template as one of the options:

So we type in the name of the plugin that we want to build, say "git", then click OK. The configuration page of this job cannot be any simpler:

The git plugin lives in the Git repository, so choose that, and save. Let’s schedule a new build, and see it build the plugin.

Models are hierarchical and can extend other models. This can be used to create some common usage templates, that are not designed for direct usage and will not be instantiated by users, or create concrete templates by specializing them for a dedicated task. When one model inherits another, it inherits all the attributes that are defined in the base model.

For example, a common utility template can handle connection and authentication to enterprise infrastructure, and child templates can use this basis to expose high-level tasks, like deploying a new release.

Template hierarchy is a useful way to manage templates of growing complexity and make attribute definitions mutual.

Templates can be configured as being instantiable by users, or as only ways to encapsulate configurations to be used from other templates by inheritance.

Templates have a dedicated entry in the top page, where the administrator will set up and maintain the templates.

All templates are based on generating Jenkins configuration from a reduced set of attribute, that the user will provide to apply the template for a dedicated job. This major reduction in complexity makes configuring new jobs simple for new users and reduces the risk of misconfiguration.

Each attribute represents a fragment of data that constitutes a template, along with how it gets presented in the UI to the users. For example, you might define an attribute called "product code", which stores a string represented in the single-line text field.

Each attribute consists of the following data model:

This attribute type holds an arbitrary string value that can be edited through a single line text field. It is the most general purpose attribute type.

Transformers access these values as java.lang.String values.

This attribute type holds an arbitrary string value that can be edited through a multi-line text area. This is suitable for entering large chunks of text.

Transformers access these value as java.lang.String values.

Checkbox holds a boolean value that can be edited through an HTML checkbox.

Transformers access these values as boolean values.

A nested auxiliary model allows a model to compose other models. See Auxiliary Template for more discussion.

It supports four different modes.

Transformers access these values as an instance (or as a java.util.List of instances) of auxiliary models. In the pack server / credential example above, you could access it like i.credential.username (where i is the instance of the outer model, credential is the ID of the attribute, and username is the ID of an attribute of the "Credential" auxiliary model.)

In the modes allowing a choice of subtypes, you can use attrName.model.id (or elementOfAttr.model.id in the case of a list) to identify the actual auxiliary model chosen. (As usual, before the template instance has been saved, attrName will be null, so you must check for this first.) The ID will be a fully-qualified path name to the model, such as topFolder/subFolder/my-aux-model. However rather than listing all possible subtypes using if-then or switch statements in your transformer, you can use Computed Value to obtain some information from the chosen model in a consistent format. (The analogy in object-oriented programming would be using a virtual method rather than querying the implementation type of an object.)

This attribute type is like an enumeration type. The designer of a model can specify a list of name/value pairs, and the user of the model gets to choose one of the pairs as the value. The UI will show the name part of the pair, and the transformers will see the value part of the pair, which mimics how the <select> tag works in HTML.

The designer of a model can choose different UI presentation for the attribute.

This is a special type of attribute, whose value is a result of evaluating a JEXL expression, which is specified during the model definition. The value isn’t editable in the instance configuration screen. This is somewhat akin to defining a getter method (whereas the regular attribute definitions are like defining fields); it lets you specify a program that computes the value, typically based on the value of other attributes.

There are a number of use cases for such a property:

At runtime, the actual type of the attribute is opaque; use attrName.toString() to get a string representation of the value within Groovy code. Normally this is done implicitly by a template transformer, for example in ${attrName}.

This advanced attribute type allows a model to hold a collection of arbitrary Describable instances. The discussion of the Describable class and its role in Jenkins goes beyond the scope of this document, but this allows models to reuse plethora of information fragments defined in plugins large and small (such as Subversion checkout location, builders, …​)

Of various attribute types that deal with Describables, this attribute type holds a list of them, and it allows all the subtype Describables for the specified base type. A good example of this is the build step configuration in a freestyle project, where users can insert any build steps of various types, so long as they extend the base "build step" type.

This attribute type is a flavor of Heterogeneous components from descriptors. This version also holds a list of Describables, but it only allows up to one instance from one type. A good example of this is the post-build action configuration in a freestyle project, where users can activate an arbitrary number of publishers of various types, but only up to one per type.

Attributes of this type can hold a single Describable rather than a list.

This attribute type holds a reference to an item in Jenkins. "Item" is the generalization of the top level elements of Jenkins, like Maven and freestyle jobs, matrix jobs, folders, etc.

This attribute type can be further constrained by the kind of item it can refer to. This can be done in terms of the job type in Jenkins, or the template it is created from. For example, if you are modeling a test job to be run after a build job, your test job model should refer not just to arbitrary items in Jenkins, but items created from the build job model.

At runtime, this attribute is accessed as an instance of hudson.model.Item.

This attribute type holds a reference to a tool installation, which is a specifically configured instance of JDK, Maven, Ant, etc. plugins that you are using might have added other types.

When you define an attribute, you’ll choose the specific type of the tool (say, Ant), and instances will choose one of the configured installations from this specific kind (say Ant1.6 and Ant1.7, assuming that your system configuration has these two Ant installations configured.)

Most often attributes of this type are used in job and builder templates. For example, if you define the attribute called jdk in a job template, your Groovy transformer can use the following code to inject the chosen JDK into the job configuration. Most other tool installations (including Ant and Maven) are referenced from within the specific Builders. You can figure this out through programming-by-example as described in the tutorial.

At runtime, this attribute is accessed as an instance of hudson.tools.ToolInstallation. As you see above, a ToolInstallation is normally referenced through its name property.

This attribute type holds a reference to credentials defined by the Credentials plugin. The control shows a pull-down with available credentials offered.

This attribute type can be further constrained by the kind of credentials it can refer to. For example, you can restrict the credentials to username/password combinations.

If the template instance is inside a folder, the user will be offered credentials defined in that folder, parent folders, or globally in Jenkins.

At runtime, this attribute is accessed as an instance of com.cloudbees.plugins.credentials.common.IdCredentials, or a more specific type if you have requested one. It would normally be used in XML configuration by calling getId() to retrieve an ID, typically stored in a field called credentialsId.

The new item wizard offers a few options, including that of creating a new Builder Template. The template configuration allows the administrator to define the execution details of any custom tool, which will be exposed to users as a new build step.

The transformer controls how your Builder Template maps to the actual builder that carries out the build.

One way to define a transformer is to use one of the standard transformers that takes an instance and produces XML. (In this case, the XML should match that saved for a build step in a job configuration.) As we discussed in the tutorial, a good way to do this is programming by example, where you manually create a freestyle project and configure it, then observe what XML it is producing.

The other way to do this, which is often preferable, is to use one of the specialized transformers that only work with builder templates, which we’ll discuss below.

Job templates need to produce a full job XML definition as a result of the transformation. As discussed in the tutorial, often the simplest way to get this done is "programming by example". You manually create a project (or a few), configure it with all the desired options, and then get the config.xml file by adding config.xml to the URL, then insert expressions and statements where you need to reflect actual values from instances.

A job template will also maintain a list of projects that are using the template, so that an administrator can quickly check the project that follows the success of project structure standardization.

A folder template controls the configuration of a folder itself (that is, everything that appears in the configuration page of the folder), such as the name, the icon, views, and access control matrix.

A folder template also allows you to specify a set of activities that are to be performed when a new instance of the template is created, such as creating jobs inside the new folder, as can be seen in the screenshot below:

But beyond the initial creation, jobs inside a folder aren’t controlled by templates. So with sufficient permissions, users can add/remove jobs and the template change will not void those changes. If this is undesirable and you prefer to lock things down further, you can use job templates for jobs in a folder template (to restrict the configuration freedom) and use access control to prevent creation/deletion (see RBAC documentation for more details.)

There are several features in the folder plugin that work really nicely when combined with a folder template.

When you define a model that contains instances of auxiliary models, your transformation will want to access these attributes. See Nested auxiliary models for more details.

Jelly is an XML-based template engine. Firstly, it allows you to insert arbitrary Java-like expressions in the ${…​} syntax (see JEXL for the reference of this syntax), and secondly, it allows you to use tags to do basic control-flow operations, such as conditional block, for-loop, switch/case, etc. See Jelly core tag library reference for more details.

Another benefit of Jelly is that it is guaranteed to produce a well-formed XML, and anything short of that is detected while you are defining a transformer. This reduces the chance of invalid transformer configuration.

Through these tags, Jelly can be abused as a programming language, but that is not really what Jelly is designed for (although at times this is handy.) If you start finding yourself using more Jelly tags than literal XML elements, consider using other transformers, such as Groovy template transformation, which offers more concise syntax.

This transformer is based on Groovy template, which is essentially a JSP in Groovy syntax + ${…​} style expression, such as the following:

The benefit of this transformation is that the Groovy syntax, with its close alignment with the Java syntax, makes it easier for Java programmers to perform complex transformation.

Take care to escape dollar signs with backslashes in XML snippets you copy, so they are not misinterpreted as Groovy expressions; for example, one line copied from a folder XML configuration should read:

Normally, for reasons of safety and robustness, XML metacharacters like < in expression values are escaped before being emitted to the output. If you intend some attribute or computed value to be treated as raw XML inlined into the job configuration, wrap it in the xml function:

In many cases one of your template attributes is actually a Jenkins component (or array of them). To embed it in a job config.xml you must first serialize it. The Templates plugin (as of 4.0) offers a few more helper functions to make this easy. Most simply, if you have a single component like a hudson.tasks.Publisher that you want to emit, use the serialize function:

If you have a collection of components (including an array), for example because you let the user configure zero or more hudson.tasks.Builders, use the serializeAll function:

Finally, if you have a single component that you want to bind to a field of a more generic type, the XStream library used by Jenkins for serialization has a special syntax. To emit a component bound to that field, you need to also specify the field name. For example, to let the user configure a hudson.scm.SCM instance and bind that to the scm field as <scm class="hudson.scm.SubversionSCM">…</scm>, use the serializeOption function:

The first, and simpler, security system is to allow any kind of script to be run, but only with an administrator’s approval. There is a globally maintained list of approved scripts which are judged to not perform any malicious actions.

When an administrator saves a template configuration, any scripts it contains are automatically added to the approved list. They are ready to run with no further intervention. ("Saving" usually means from the web UI, but could also mean uploading a new configuration via REST or CLI. See Scripting templates.)

When a non-administrator saves a template configuration, a check is done whether any contained scripts have been edited from an approved text. (More precisely, whether the requested content has ever been approved before.) If it has not been approved, a request for approval of this script is added to a queue. (A warning is also displayed in the configuration screen UI when the current text of a script is not currently approved.)

An administrator may now go to Manage Jenkins » In-process Script Approval where a list of scripts pending approval will be shown. Assuming nothing dangerous-looking is being requested, just click Approve to let the script be run henceforth.

Builder and publisher templates using unapproved scripts (mainly Groovy or Jelly transformers, but also JEXL computed values) present no special issue: unless and until the script is approved, trying to run a build using that build step will fail. You may retry once the script has been approved.

Job and folder templates using unapproved transformer scripts are a little trickier. Existing template instances will continue to use the former script definition; as soon as the script is approved, they will be updated. New jobs or folders cannot be created from the template until its script is approved. (Currently unapproved computed values will just be left as null, but there is no such fallback option in general for job template transformers.)

Waiting for an administrator to approve every change to a script, no matter how seemingly trivial, could be unacceptable in a team spread across timezones or during tight deadlines. As an alternative option, the Templates plugin lets Groovy scripts be run without approval so long as they limit themselves to operations considered inherently safe. This limited execution environment is called a sandbox. (Currently no sandbox implementations are available for the Jelly or JEXL languages, so all such scripts must be approved if configured by non-administrators.)

To switch to this mode, simply check the box Use Groovy Sandbox below the Groovy script’s entry field. Sandboxed scripts can be run immediately by anyone. (Even administrators, though the script is subject to the same restrictions regardless of who wrote it.) When the script is run, every method call, object construction, and field access is checked against a list of approved operations. If an unapproved operation is attempted, the script is killed and the template cannot be used.

The Templates plugin ships with a small default allowlist: enough to print the values of template attributes (including those from auxiliary models), and not much else. The Script Security plugin, or other plugins, may offer other allowlisted operations by default.

But you are not limited to the default allowlist: every time a script fails before running an operation that is not yet allowed, that operation is automatically added to another approval queue. An administrator can go to the same page described above for approval of entire scripts, and see a list of pending operation approvals. If Approve is clicked next to the signature of an operation, it is immediately added to the allowlist and available for sandboxed scripts.

Most signatures be of the form method class.Name methodName arg1Type arg2Type…, indicating a Java method call with a specific "receiver" class (this), method name, and list of argument (or parameter) types. (The most general signature of an attempted method call will be offered for approval, even when the actual object it was to be called on was of a more specific type overriding that method.) You may also see staticMethod for static (class) methods, new for constructors, and field or staticField for field accesses (get or set).

As with unapproved scripts, sandboxed scripts using illegal operations pose no special issue for builder and publisher templates; just try rerunning the build. New job or folder instances again cannot be created from the template until it uses only allowed operations. Existing job or folder templates instances also will not be updated before all operations run by the script are approved; unlike whole-script approval, in this case the instances are not automatically refreshed just because the allowlist has been expanded. To trigger a refresh, re-save the template (or of course you may edit its script to not invoke unapproved operations).

Administrators in security-sensitive environments should carefully consider which operations to allow. Operations which change state of persisted objects (such as Jenkins jobs) should generally be denied (and these have no legitimate use in templates anyway). Most getSomething methods are harmless.

Be aware, however, that even some "getter" methods are designed to check specific permissions, whereas scripts are often run by a system pseudo-user to whom all permissions are granted. So, for example, method hudson.model.AbstractItem getParent (which obtains the folder containing a job) is in and of itself harmless, but the possible follow-up call method hudson.model.ItemGroup getItems (which lists jobs by name within a folder) checks Job/Read. This second call would be dangerous to allow unconditionally, because it would mean that a user who is granted Job/Create in a folder would be able to read at least some information from any jobs in that folder, even those which are supposed to be hidden according to, for example, RBAC role filtering; it would suffice to create a job template using a Groovy transformer like this:

When instantiated as a throwaway job, its description would display at least the names of supposedly secret projects. You may instead click Approve assuming permission check for getItems; this will permit the call when run as an actual user (for example when someone saves the templatized job), while forbidding it when run as the system user (for example when someone saves the template and its instances are updated in the background). In this case, getItems will actually return only those jobs which the current user has access to, so if run in the former case (by saving the templatized job), the description will show just those jobs they could see anyway. This more advanced button is shown only for method calls (and constructors), and should be used only where you know that Jenkins is doing a permission check.

Sophisticated templates require accessing information available in the rest of the Jenkins object model. For example, let’s say your "test" job template has an attribute that refers to the corresponding "build" job, and you’d want the test job to change its behaviours based on the configuration of the build job.

This kind of template can be best written as "Groovy-based transformer", since it provides concise syntax to navigate around the object model and access information. In order to work with the Jenkins object model you need some basic familiarity with that API; Jenkins Javadoc is the starting point.

The Instance type refers to a Map-like object that retains the values of attributes for a model, and during the transformation, the current instance is always accessible as the instance variable.

When those instances are from templates that map to jobs in Jenkins (such as job template and folder template), these instances are of the com.cloudbees.hudson.plugins.modeling.impl.entity.EntityInstance class, which defines the item property that lets you access the corresponding hudson.model.Item instance (such as FreeStyleProject object and a Folder object.) So for example, instance.item.isDisabled() would check if the job is disabled or not.

Conversely, those items that are created from their templates have the instance property that allows you to navigate back to the instance. In other words, instance.item.instance==instance. For items that are not created from any templates, this property returns null. Also note that this property is defined in Groovy, and not in Java, and therefore it is only accessible when using Groovy transformers.

One of the useful technique to eliminate redundancy in job templates is to access information of the folder that contains jobs. For example, you might define a folder property that specifies the name of the branch, then templatize jobs inside this folder so that it uses this information to determine where to check out.

To facilitate such an use case, there’s the parent property accessible during a transformation of templates that map to jobs in Jenkins (such as job template and folder template.) This property refers to the instance of ItemGroup, which is typically com.cloudbees.hudson.plugins.folder.Folder instance (that represents the folder that contains the job) or Jenkins (if the job isn’t contained in any folder but a top-level.)

While the parent property can be used to access the parent Folder itself, if you have a Job template as a child of a Folder template it can be very useful to access the attributes of the Folder template directly from the Job template. For this use case the parentInstance variable is analogous to the instance variable only it allows accessing the attributes of the parent Folder template.

Unlike other techniques mentioned above, to use parentInstance you need know nothing about the Jenkins object model, since you have direct access to the template attributes which are exposed as simple objects.

There are a number of issues to be aware of when using the parentInstance variable:

Therefore, when using the parentInstance variable it is necessary to ensure that it is used defensively, as any NullPointerException thrown when attempting to instantiate the Job template can cause the folder template to fail to instantiate also.

When using the parentInstance variable, it is recommended to use the Groovy transformer for the Job template as that provides both the "Elvis" operator (?:) and the safe navigation operator (?.) both of which combine to allow safer template instantiation, e.g. ${parentInstance?.someAttribute?:"someDefault"} is a safe Groovy expression to return the value of the someAttribute attribute of the parent template instance, falling back to someDefault if the job is either instantiated outside of a Folder template or while the value of someAttribute has not been defined by the user.

If you will be repeating multiple references to the same attribute within the same Job template, it would make sense to create a Computed attribute in the Job template and use a JEXL expression to evaluate the value to use as that makes it easier to refactor the expression, e.g. if you need to change the default value. In the context of JEXL expressions, JEXL also supports the "Elvis" operator and performs safe navigation by default, e.g. ${parentInstance.someAttribute?:"someDefault"} is a safe JEXL expression to return the value of the someAttribute attribute of the parent template instance, falling back to someDefault if the job is either instantiated outside of a Folder template or while the value of someAttribute has not been defined by the user.

There are a couple of additional points you may want to consider:

The most important operation involving templates is creating and updating instances. For builder and publisher templates (and any auxiliary templates they use), there is no special support in Jenkins: the usual REST methods to create and update job configuration (/config.xml) work. Refer to an existing job using such templates for an example of the syntax.

Job and folder templates, however, are special and have a dedicated REST API. A single endpoint (URL) is used for creating and updating job and folder templates: /instantiate, which is added to the URL of the template (never the job). You may POST to this URL, giving it a query parameter job with the full path to the intended or actual templatized job. The message body must be an XML document with root element values; the child element names and text contents define attributes to set on the template instance. This single API can be used to create a job (or folder) from a template; update the attributes of an existing templatized job (using this template); or even to convert a job using a different template, or no template at all. Refer to the REST API link on the template’s index page for details and examples.

(You may also use most regular REST APIs to work with templatized jobs. /createItem can be used to create a templatized job; you must specify the <com.cloudbees.hudson.plugins.modeling.impl.jobTemplate.JobPropertyImpl> section giving the template and attributes, and the main body of the job such as <project>, but the transformer will be run to fill in the details. GET /config.xml works fine, though POST to this same URL does not currently rerun the transformer automatically. /api/xml and the like can be used to obtain information about the associated template and attributes as well.)

Since templates are stored as regular items in the Jenkins folder tree as of 4.0, regular REST APIs for CRUD (create/read/update/delete) of templates themselves work as with anything else. Also, POST to /config.xml on a job/folder template will automatically rerun the transformer on any instances, just as if you had saved it from the UI. You can also use /api/xml and similar to obtain information about a template, such as its attributes or supertype.

Access control is similar to interactive use: you must have Job/Read permission on the template for most operations, Job/Create on a folder to create a templatized job in it, Job/Configure to change the configuration of a templatized job.

The Jenkins CLI is often more convenient to use from scripts than the REST API. There is a command instantiate which has the same capabilities as the REST /instantiate. First give the command the path and name of the (desired or existing) templatized job. You can then add -t specifying the path and name of the template (only necessary when creating a new job, or converting to this template). Then give -a with a name=value pair for each attribute you wish to set.

As with the REST API, there is no special syntax for CRUD on templates themselves. The same commands used for regular jobs work on templates (at least in Jenkins 1.538 and later). Again as a convenience, update-job applied to a job/folder template will reconfigure any instances.

Sometimes using the Groovy script console (/script), the Scriptler plugin, etc. is the easiest way to work with templates. Most operations with templates or templatized jobs will not require any special APIs. There are two things you might want to call directly in the Templates plugin when working with job or folder templates:

The CloudBees View Creation Filter plugin allows you to specify that a view may only contain certain item types. To use it, when creating a new view, pick Restrict what can be created in this view from the Add Job Filter pulldown. Then you can select a list of item types; only items of those types will be permitted to be added to the view via the New Item menu.

While these types might be built-in types such as Freestyle project, you will also see your own job templates listed as choices.

You may also want to use the Template Type Filter to add all instances of a given template by default. Currently you cannot prevent other kinds of items from being added via the Jobs checkbox list (tracked as CJP-1501).

The CloudBees Groovy View plugin provides a Groovy Script View you can select when creating a new view in a Jenkins folder or at top level. It allows you to generate any content you like in the view (subject to the limitations of the system’s configured markup language).

To create interesting content, you can refer to the folder as ${it} and calculate some contents. But when used with a templatized folder, you can also use ${instance} to the refer to the template instance, from which you can get the values of template attributes. This is useful since your folder template can predefine a Groovy script view which generates a dynamic view according to both the current contents of the folder and its templatized configuration.