REST List Parameter

Version: 1.1.0Minimum Jenkins requirement: 2.235.5ID: rest-list-parameter
Installs: No usage data available
Last released:
Maintainers
h1dden-da3m0n

icon rest list parameter plugin 2020 rest list parameter plugin rest list parameter 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 or BEARER authentication)

  • Filter/Pars the values of the web response with Json-Path or xPath (depending on MIME type)

  • Filter the already filtered/parsed values via a REGEX

  • Set the per default preselected value

  • User-friendly error communication

  • Advanced configuration validation (v1.1.x+)

Configuration

Parameter configuration (Advanced collapsed)
Parameter configuration (Advanced expanded)
Demo Build (+ showcasing error messaging)

Json-Path configuration

Demo config for Json-Path

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

Demo config for xPath

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

Note
The Authentication header will be build and added based on the type of the selected credential type.

Parameter Config Validation (v1.1.x+)

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.

Successful Configuiration Validation
Faild Configuiration Validation

Definition in Pipeline

pipeline {
  agent any
  parameters {
    RESTList(
      name: 'REST_VALUE',
      description: '',
      restEndpoint: 'http://test.lan',
      credentialId: '',
      mimeType: 'APPLICATION_JSON',
      valueExpression: '$.*',
      defaultValue: '', // optional
      filter: '.*' // 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('$.*')
      defaultValue('') // optional
      filter('.*') // optional
    }
  }
  definition {
    cps {
      script("""
        pipeline {
            agent any

            stages {
                stage('Test') {
                    steps {
                        println env.REST_VALUE
                    }
                }
            }
        }
      """)
      sandbox()
    }
  }
}

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

gplv3 or later

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.

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.

ArchivesGet past versions
Links
Labels