CloudBees
The template plugin ships with the following distinct attribute types. Attribute types are also extensible, allowing additional plugins to bring in more types.
This attribute type holds 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 arbitrary string value that can be edited through a multi-line text area. This is suitable for entering large chunk 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 the section called “Auxiliary Template” for more discussion.
It supports four different modes.
- Single value
- The attribute will hold one and only one instance of the specific auxiliary model. In the UI, the configuration of the nested auxiliary model is presented as-is, inline. Let’s say you created an auxiliary model that represents the access credential to your internal package repository called “PackServer Credential.” You then create “Acme Corp Pack Build” template that builds and deploys a binary to this package server. This template would want to have an attribute that holds a “Credential” auxiliary model as a nested value in the single mode, since you need one and the only one credential for each job.
- Single value (choice of subtypes)
- The attribute will hold one instance of the auxiliary model (if instantiable), or one of its (instantiable) subtypes.
- List of values
- The attribute will hold a list of instances. All the instances must come from a single auxiliary model, but users can add as many/few of them as they wish. A good example of this is the JDK configurations in the system configuration page (where JDK can be thought of as an auxiliary model, which in turns has attributes like name, home, installer, etc.) The UI of this mode will be just like that of the JDK configuration. A button to add/remove/reorder instances of the auxiliary model.
- List of values, including subtypes
- This is similar to the “list of values” mode above, except that the user can choose from all the instantiable subtypes of the specific nested model type. A good example of this is the build step configuration in a free-style project, where you can add any number of build steps (which are all subtypes of the base model called “Builder”.) This mode presents a drop-down menu button that allows the user to choose the specific auxiliary model type to instantiate.
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.)
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:
- To simplify the transformer definition. If your transformer keeps doing a similar manipulation of attribute values over and over again, it is often better to define such a manipulation as a computed attribute (for example, say you define an attribute for a subversion repository URL, and you want its last path component accessible as a separate attribute.)
- For polymorphic behavior in auxiliary models. Imagine you are defining a model for assembling a book from its chapters, where each chapter can be either a pre-existing PDF in your content repository or a docbook that needs a transformation. You define this as a base abstract auxiliary model called “Chapter” and then two concrete sub-models. Those sub-models likely define different set of parameters, but it’s often convenient for them to both have the attribute of the same name (say
shellScriptthat evaluates to the shell script that produces PDF) that yield very different values that are computed from other attributes.
At runtime, the actual type of the attribute depends on the expression.
This attribute type holds a configured instance of a model transformer. This is primarily introduced for defining the meta-model that the template plugin internally uses, and probably of limited use for typical models.
At the instance editing time, this attribute will be rendered as a drop-down box to choose available transformer type, which then unfolds whatever UI specific to the selected transformer type.
At runtime, this attribute is accessed as an instance of com.cloudbees.hudson.plugin.modeling.transformer.ModelTransformer Java type.
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 the section called “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.
This attribute type holds a reference to a model. This is primarily defined for the meta-model that the template plugin internally uses, and probably of limited use for typical models.
At the instance editing time, this attribute will ask the user to choose a model out of all the models defined in Jenkins.
At runtime, this attribute is accessed as an instance of com.cloudbees.hudson.plugin.modeling.Model Java type.
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.
<project>
<% if (jdk != null) { %>
<jdk><%= jdk.name %></jdk>
<% } %>
...
</project>
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.