README.adoc

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.

• Introduction
• Changelog
• Features
• Configuration
  • Json-Path configuration
  • xPath configuration
  • Authentication configuration
  • Parameter Config Validation
  • Value Caching
  • Optional Value Ordering
  • Definition in Pipeline
  • Definition in JobDsl
  • Set Global Options via JCasC
• Contributing
• Licence
• Bundled Project Sources
• Development
  • Requirements
  • Build
  • Release a new Version

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 or BEARER 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.

Display value configuration

Note	Added in v1.5.x thanks to rolaca11

The optional 'display value' configuration, hidden within the advanced configuration, allows the use of a REST service that returns full Json objects that get pased into the Pipeline run but to display only an identifying value within the select dropdown.

Example JSON returned by REST endpoint

[
  {
    "name": "v10.7.7",
    "zipball_url": "https://api.github.com/repos/jellyfin/jellyfin/zipball/v10.7.7",
    "tarball_url": "https://api.github.com/repos/jellyfin/jellyfin/tarball/v10.7.7",
    "commit": {
      "sha": "53186c766bddf954483d7b40e385b382eabd0d8e",
      "url": "https://api.github.com/repos/jellyfin/jellyfin/commits/53186c766bddf954483d7b40e385b382eabd0d8e"
    },
    "node_id": "MDM6UmVmMTYxMDEyMDE5OnJlZnMvdGFncy92MTAuNi40"
  },
  {
    "...": "..."
  }
]

With a Value Expression such as $.* and a Display Expression such as $.name the values in the dropdown would only show up as the name property of each JSON object (i.e. v10.7.7).

xPath configuration

Important

If you are a user of this functionality please have a look at the pined issue #99

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

Just if the badge from shields.io and the LICENSE file do not make it obvious enough, this project is licenced under the GPLv3 or later.

Bundled Project Sources

Note	Bundled as of v1.3.x, updated as of v1.4.x

Project	Version	Licence	Description
Select2-Bootstrap4-Theme	v1.5.2	MIT	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.