CloudBees
When working with large installations using many templates or many templatized jobs, it is often useful to be able to perform bulk operations using scripts. (Many of these operations are available only in the 4.0 and later versions of the plugin.)
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:
- If you have a reference to job or folder template (
com.cloudbees.hudson.plugins.modeling.impl.entity.EntityModel), you can call reconfigureInstances() to regenerate any instances after updating its definition (or otherwise changing what the transformers would produce). - If you have a reference to a templatized job, you can call EntityInstance.from(Item) to obtain an instance object. This is mainly used to call setValue(String, Object) to change attributes, and save() to run the transformer and update the job definition.
You can create a new templatized job or folder as well. If
gis a ModifiableTopLevelItemGroup (such as Jenkins root, or a Folder), you can callg.createProject(model.asDescriptor(), "new-job-name", true)
to create a new item. If you need any additional attributes (beyond
name), you can use the steps given above starting with EntityInstance.from to define and save them.