REST-List Parameter Plugin
Introduction
This Plugin provides parameter type that can request a REST endpoint and offer a list of values parsed from the response value at build start time. The REST responses may contain Json or XML, which can be parsed with Json-Path and xPath respectively. If the REST endpoint requires authentication, then either Basic or Bearer authentication can be used.
Changelog
Release notes can be found in the GitHub Releases
Features
-
Specify any REST/Web endpoint that returns either a Json or XML response with values to select from for a build
-
Authenticate against the endpoint if required (either with
BASIC
orBEARER
authentication) -
Filter/Pars the values of the web response with Json-Path or xPath (depending on MIME type)
-
Set a per-selected default value (as long as that value is within the received value list)
-
User-friendly error communication
-
Response value caching
-
Advanced configuration validation
-
Optional value post processing
-
Filter the already parsed values via a REGEX
-
Apply a sort order to the values
-
Configuration
Json-Path configuration
If you expect the response of the specified endpoint to produce a Json response and need to utilize Json-Path, then you have to set the MIME type to APPLICATION_JSON (this will also send this MIME as ACCEPT
header) and provide the desired Json-Path in the Value Expression field.
The result of such a configuration will be the application of the Json-Path on the response Json to pars the string values later provided in the Build with Parameter dropdown of this parameter.
xPath configuration
If you expect the response of the specified endpoint to produce an XML response and need to utilize xPath, then you have to set the MIME type to APPLICATION_XML (this will also send this MIME as ACCEPT
header) and provide the desired xPath in the Value Expression field.
The result of such a configuration will be the application of the xPath on the response XML to pars the string values later provided in the Build with Parameter dropdown of this parameter.
Authentication configuration
Depending on the authentication requirement for the REST/Web endpoint there are three supported methods:
-
NONE
if there is no authentication requirement simply don’t select any Credential ID -
BASIC
if this authentication type is required, then simply select any Username and Password credential in the Credential ID field -
BEARER
if this authentication type is required, then simply select any Secret Text credential in the Credential ID field
Important
|
The Authentication header will be build and added based on the type of the selected credential type. |
Parameter Config Validation
Note
|
Added in v1.1.0 |
The configuration page of this plugin features supportive form validation (which was already present in a basic form in v1.0.x).
With v1.1.x+ the validation got expanded to be more helpful and prevent the constant switch from the configuration to a build and back, just to validate the configuration.
The most notable expansion in validation was the REST Endpoint
field validation, which now works similar to the validation found for the SCM fields (Endpoint and credential).
Additionally, a Test Configuration
button got added, which once pressed, attempts to query the endpoint and list the number of parsed values as well as the first value in the list.
Value Caching
Note
|
Added in v1.2.0 |
The ability to use value caching allows for great performance improvements in cases of repetitive building and querying the same REST endpoints.
Additionally, it drastically decreases the amount of endpoint queries, which is especially useful for rate limited endpoints.
Per default caching is disabled for new and old REST List Parameter
, but can be activated at any time by setting how many minutes the values should stay cached for.
Additionally, there are global configuration values now, that give the user control over the global cache size (default 50 MiB), as well as the default value for the cache max age (default 0 minutes). These values can be overwritten within the UI or via the ConfigurationAsCode plugin and applying a config with this added.
Optional Value Ordering
Note
|
Added in v1.2.0 |
This option in the "Advanced" section of the parameter configuration allows the user to apply a sort order on the values received from the endpoint specified.
The default value of this option is NONE
, so no additional sporting gets applied on the values received.
The other two options offer tha ability to apply either an ascending or descending sort order to the received values.
Definition in Pipeline
pipeline {
agent any
parameters {
RESTList(
name: 'REST_VALUE',
description: '',
restEndpoint: 'http://test.lan',
credentialId: '',
mimeType: 'APPLICATION_JSON',
valueExpression: '$.*',
cacheTime: 10, // optional
defaultValue: '', // optional
filter: '.*', // optional
valueOrder: 'ASC' // optional
)
}
stages {
stage('Test') {
steps {
println env.REST_VALUE
}
}
}
}
Definition in JobDsl
pipelineJob('DemoJob') {
parameters {
RESTList {
name('REST_VALUE')
description('TEST')
restEndpoint('http://test.lan')
credentialId('credID')
mimeType('APPLICATION_JSON')
valueExpression('$.*')
cacheTime(10) // optional
defaultValue('') // optional
filter('.*') // optional
valueOrder('NONE') // optional
}
}
definition {
cps {
script("""
pipeline {
agent any
stages {
stage('Test') {
steps {
println env.REST_VALUE
}
}
}
}
""")
sandbox()
}
}
}
Set Global Options via JCasC
unclassified:
# ...
restListParam:
cacheSize: 50 # in mebibyte, needs to be greater than 0
cacheTime: 0 # in minutes, 0 => per default don't use cache
# ...
Contributing
I welcome all contributions and pull requests! If you have a larger feature in mind please open an issue, so we can discuss the implementation before you start.
Note
|
I prefer GitHub Issues over Jira Issues, but I check both regularly. |
For further contributing info please have a look at the JenkinsCI contribution guidelines.
Licence
Bundled Project Sources
Note
|
Bundled as of v1.3.0 |
Project | Version | Licence | Description |
---|---|---|---|
|
An amazingly simple to use jQuery replacement for select boxes (used to offer a filterable select dropdown) Replaced with the Select2 Api Plugin in 1.4.x |
||
|
A CSS theme for Select2, when used in Bootstrap4 apps |
Development
Requirements
-
Java 8 or newer
-
Maven 3 or newer
-
(optional) a test Jenkins instance to deploy the plugin SNAPSHOT to for testing
Build
$ # build, test and package to hpi (hpi can be deployed to test Jenkins)
$ mvn -B package --file pom.xml
$ # build, test, package and launch test Jenkins
$ mvn -B hpi:run --file pom.xml
Release a new Version
Note
|
This Plugin uses SemVer to version its releases |
To creat a new release follow the instruction found for the Incremental tools to create a release whilst incrementing the correct position of the SemVer.