Metadata plugin

Skip to end of metadata
Go to start of metadata

Plugin Information

Plugin ID metadata Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
Dependencies
1.1.0b
Dec 16, 2013
1.509.3
maven-plugin (version:1.509.3)
Source Code
Issue Tracking
Maintainer(s)
GitHub
Open Issues
Robert Sandell (id: rsandell)
Tomas Westling (id: t_westling)
Usage Installations 2013-Apr 203
2013-May 213
2013-Jun 237
2013-Jul 259
2013-Aug 274
2013-Sep 273
2013-Oct 310
2013-Nov 327
2013-Dec 333
2014-Jan 336
2014-Feb 339
2014-Mar 360

This plugin allows metadata to be added to projects, builds and slaves in Jenkins.
Users can add metadata manually on a project or slave via the user interface. Metadata can also be added programmatically through a plugin.
Currently, this can be done when a build starts or when a build ends. The Metadata can then be searched for.

The main idea of the metadata plugin is to make searching for jobs and builds to behave more like a database, and act as an enabler for other plugins.
Once all the information about a project is gathered in one place, plugins can be developed to use this information, as well as to provide information.
The more plugins that provide information, the more usable data you can search for.
As an example of using the information, look at the External Resource Dispatcher plugin.

Metadata definitions and values

We differentiate between MetadataDefinitions and MetadataValues. The idea comes from the parameter setup in Jenkins.
A MetadataValue is what's set on the configuration page of a project or slave and is also what is saved for a build.

MetadataDefinitions are used by admins for making sure that certain metadata exist on all projects.
A MetadataDefinition is set up through a special configuration page, configuring a name and default value for the definition.
Once set, the MetadataDefinition will end up in all projects on the server, prompting the user to set a value for it when the project is configured.
MetadataDefinitions are then converted to MetadataValues.

Metadata types

  • StringMetadataDefinition/Value: Metadata containing string values.
  • NumberMetadataDefinition/Value: Metadata containing integer numbers.
  • DateMetadataDefinition/Value: Metadata containing date values with optional hour/minute/second values.
  • TreeNodeMetadataDefinition/Value: Metadata representing a tree of Metadata. Can contain any kind of Metadata as children, including other trees.

These are the metadata types currently available. More will be added, and plugin developers could add their own types.

Metadata for builds and environment variables.

All MetadataValues for a project will automatically get copied to each build on that project. Metadata for a project or a build can be
seen by clicking the "Metadata" link from the project or the build, respectively.

If "Expose to environment" is checked for a MetadataValue, the value will also be made available as an environment variable like this:
TreeNodeMetadataValue with name "my" with one child, a StringMetadataValue with name "string" and value "value".
This will be converted to an environment variable called MD_MY_STRING with value "value".
That is, MD (short for metadata) will be prepended, and each parent-child bond will be represented by an underscore.
These environment variables can then be used by the build.

Search

The search functionality is accessible through the "Metadata search" link.
Currently, only searching for projects is supported, but builds and slaves will be added.
Searching is done with the syntax metadatavaluename=value && othervaluename=value2
Equals, And and Or (||) are the operators supported so far.


Metadata search view and result.
You can also add a metadata filter to a view where you can provide a search string that will filter out the jobs matching that search.

Extendability

Plugin developers can add their own MetadataDefinitions and Values, by extending either AbstractMetadataDefinition/Value directly or
one of the subclasses. If possible, try to use the existing classes as much as possible when providing data from your plugin as there is
no value in lots of definitions/values that do almost the same thing but with different names.
Other than writing your own MetadataDefinitions and Values, the main way of extending the Metadata plugin is through the contributor classes.

JobMetadataContributor

This ExtensionPoint can be used when you want to automatically add Metadata to a project whenever the project is saved. Extend JobMetadataContributor,
add @Extension to your class, and implement the getMetaDataFor method. Return a list of MetadataValues which will then be added to the project.

BuildMetadataContributor

This ExtensionPoint can be used when you want to automatically add Metadata to a build whenever it is finished. Extend BuildMetadataContributor,
add @Extension to your class, and implement the getMetadataFor method. Return a list of MetadataValues which will then be added to the project.

Roadmap and future

Here is a list of features we would like to see in the Metadata plugin in the future:

  • Finalized definitions support. The definitions support isn't yet fully functional, the conversion to values needs to be done.
  • Search for builds and nodes based on specific metadata.
  • Search for projects with specific metadata in a build of that project.
  • More advanced search functionality
  • Search optimization
  • Support for plugins to add metadata to nodes
  • Advanced resource selection criteria
  • More definitions and values
  • Put the metadata into some kind of database

Change Log

Version 1.1.0b (released Dec 16, 2013)

Version 1.0b (released Nov 22, 2012)

Initial beta release

Labels

plugin-misc plugin-misc Delete
plugin-cli plugin-cli Delete
plugin-library plugin-library Delete
plugin-ui plugin-ui Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Jan 28, 2013

    Max Spring says:

    Is it possible to have mandatory fields? If a user hasn't populated a mandatory ...

    Is it possible to have mandatory fields?
    If a user hasn't populated a mandatory field, the job will fail.

    I'd like to even be able to add my own field validation.
    Use case: A mandatory "owner" field.
    My own validation logic would validate the user-entered value against my organization's LDAP directory.

    Just some ideas
    -Max

    1. Jan 29, 2013

      Robert Sandell says:

      Some good ideas :) We are currently working on what we call "preset values" Tho...

      Some good ideas :)

      We are currently working on what we call "preset values" Those are what the administrator defines on a separate config page.

      Then our first idea was to just enable you to mark them as "mandatory" i.e. the user must specify something other than the default or the job configuration can't be saved.

      Custom validation could be made possible with for example some groovy script or extension points maybe.

  2. Mar 15, 2013

    Ioannis Moutsatsos says:

    Have you considered generating dynamic metadata from a build? I really like your...

    Have you considered generating dynamic metadata from a build? I really like your 'query through metadata' ideas. For my case, I'm more interested of build level MD. I have parameterized build projects that work with file-parameter uploaded file. This file frequently contains important metadata that I would like to be able to search for later. I'm now waiting for the 'Search for builds based on specific metadata' milestone. Thank you!

    -Ioannis-