Getting a JSON Object as a Parameter in a Jenkins Pipeline

1. Overview

JSON is a standard data representation format that is widely used to exchange information between systems like web applications and services. It is language-independent, and most programming languages have support for parsing and generating data in JSON format.

In this tutorial, we’ll explain how to work with JSON data in Jenkins by using a Jenkins parameter and parsing it inside a pipeline.

2. Creating Jenkins Parameter as a JSON Text

There’s no specific Jenkins parameter of type JSON that we can define. To create a parameter as JSON, we can simply use a multiline string parameter and input our JSON data:

In this step, we defined our parameter named student and provided a default value with JSON format that we’ll be using inside the pipeline. Let’s now create a pipeline script to print the value of our parameter:

pipeline {
    agent any
    stages{
        stage("print json parameter"){
            steps{
                echo student
            }
        }
    }
}

Here, we used an echo step to print our student parameter. Let’s trigger our pipeline and see the output:

Now, we can see the pipeline output shows the value of our parameter, which is in JSON structure.

3. Parsing the JSON Parameter

Working with the JSON data as a whole text won’t be that useful. We’ll normally need to access different attributes and values inside our JSON payload. To do this, we need to parse our JSON string and convert it into a usable object.

Now, let’s see how we can parse this JSON text in different ways in our pipeline.

3.1. Using the readJSON Step

Jenkins provides a readJSON step that we can use to read JSON data from an input parameter or a file. It’s a pipeline utility that can parse our JSON text and is the easiest way of working with JSON in our pipeline.

Let’s check this with an example:

pipeline {
    agent any
    stages{
        stage("parse json parameter"){
            steps{
                script{
                    def myobj = readJSON text: student
                    echo "The student name is $myobj.name"
                    echo "The subjects are ${myobj.subjects[0].name} and ${myobj.subjects[1].name}"
                }
            }
        }
    }
}

In the above pipeline script, we used readJSON and specified text as the input type and the student parameter as our text, and we stored the parsed object inside myobj. Then, we printed the name property of our parameter and the subject names by accessing myobj attributes.

Now, let’s trigger the pipeline and see the output:

And we can see here the value of our attributes printed to the pipeline output.

3.2. Using Groovy JsonSlurper

Another way of parsing JSON text is by using the Groovy JsonSlurper class. Because Jenkins allows using Groovy language in the pipeline syntax, we can import standard classes like the JsonSlurper and use them in our pipeline.

This means we can create a JsonSlurper object and access any methods or properties from the class in a normal programming style. Although this provides more flexibility and enables a lot of customization to the pipeline flow, it comes at the cost of complexity. So, it’s usually preferable to use declarative syntax when possible.

Now, let’s parse our text with the JsonSlurper:

import groovy.json.JsonSlurper
pipeline {
    agent any
    stages{
        stage("parse json parameter"){
            steps{
                script{
                    def myobj = new JsonSlurper().parseText(student)
                    echo "The student grade is $myobj.grade"
                    for (i=0; i<myobj.subjects.size(); i++)
                        if (myobj.subjects[i].passed){
                            echo "he passed the ${myobj.subjects[i].name}"
                        }
                        else{
                            echo "he failed the ${myobj.subjects[i].name}"
                        }
                }
            }
        }
    }
}

In this pipeline script, we first imported groovy.json.JsonSlurper to use the JsonSlurper class. Then, we used the parseText method to convert our student parameter to a JSON object and store it inside myobj. This is pretty much the same as what the readJSON step did before. Finally, we printed the grade attribute and the result of each subject whether passed or failed.

Let’s trigger our pipeline now:

And, as we can see here, the attributes we printed in our pipeline are displayed in the output, which means that the JsonSlurper parsed our JSON text correctly.

4. Conclusion

In this article, we’ve covered the basics of working with JSON strings in Jenkins. We showed how to create a Jenkins parameter with JSON text and then parse it using readJSON or JsonSlurper. The readJSON is a pipeline utility step that provides an easy way to parse JSON text in Jenkins declarative pipelines. The JsonSlurper is a standard Groovy class that we can import, and it provides different methods to work with JSON text.