Triggering a Jenkins job using API call and passing parameters

Jenkins is one of the important tool in DevOps and most of the time we would require to execute Jenkins job using remote REST API call. Jobs can either be parameterized or non parameterized. A Parameterized job will need certain input from user side for execution. Here we will discuss how to call both types of jobs using REST API.

We will discuss on following steps.

1. Setting Jenkins Job respond to REST API
2. Finding out the API URL for the Job
3. Handling Authentication
4. Building REST API request
5. How to trigger a non-parametrized Job.
6. Triggering paremeterized job by sending values in URL
7. Triggering parametrized Job by sending values in JSON file

Introduction to Jenkins API

[From Jenkins Documentation] “Jenkins is the market leading continuous integration system, originally created by Kohsuke Kawaguchi. This API makes Jenkins even easier to use by providing an easy to use conventional python interface.”

——————- advertisements ——————-  

———————————————————

Jenkins provides rich set of REST based APIs. 

Setting Jenkins Job to respond REST API

The REST API feature can be enabled per Job basis. To enable REST API trigger for a Job, Navigate to Your JobName ->Configure -> Build triggers TAB and Check on ‘Trigger build remotely’.

Find out the API URL for the Job

Once you enabled the check box to trigger build remotely , Jenkins will show you the URL to access the particular Job and gives an option to provide the API token for the build. Consider my Jenkins server URL is 10.10.10.100:8080 and my job name is ‘test-job’ , then the URL will be as follows

‘ http://10.10.10.100:8080/job/test-job/build?token=MyTestAPIToken’ -> For non parameterized build

‘ http://10.10.10.100:8080/job/test-job/buildWithParameters?token=MyTestAPIToken’ -> For parameterized build

——————- advertisements ——————-  

———————————————————

Handling Authentication

Jenkins using combination of user credential based authentication and API token authentication. We can build token for each build as shown above. In user credential authentication, you can either pass the usename+password or username+token . To access the token for your username, login with your user account , navigate to Manage Jenkins -> Manage Users ->Select User name -> Click Add New Token ->Give Token Name -> Click generate . This will display token for your user . Copy this token and save on safe place as this token can not be recovered in future.

Building REST API request

There are two steps involved in making a successful API request. The first step is to send authentication request and get the CRUMB variable. This crumb data required to be send as header on further API requests. Jenkins use this to prevent Cross Site Forgery. The second one include the actual job request where you will specify job name and parameters for the job. Following are the example for getting CRUMB data using CURL query

——————- advertisements ——————-  

———————————————————

Getting CRUMB data :

Format : crumb=$(curl -vvv -u “username:passsword” -s ‘http://jenkinsurl/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,”:”,//crumb)’)

Example using password :

crumb=$(curl -vvv -u “apiuser:test@123″ -s ‘http:// 10.10.10.100 :8080/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,”:”,//crumb)’)

Example using User Token :

crumb=$(curl -vvv -u “apiuser: 1104fbd9d00f4e9e0240365c20a358c2b7 ” -s ‘http:// 10.10.10.100 :8080/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,”:”,//crumb)’)

Triggering a Non-parameterized Job :

Triggering a non-parameterized job will be easy as there is no requirement of sending any additional data for the build. Below are the example for the API request. Assume we have got crumb data from the above step.

curl -H $crumb –user apiuser: 1104fbd9d00f4e9e0240365c20a358c2b7 -X POST http://10.10.10.100:8080/job/test-job/build?token=MyTestAPIToken

Where ‘test-job’ is name of my Job and ‘ MyTestAPIToken ‘ is the token keyword which i have set manually on Job configure page. Refer ‘Find out the API URL for the Job’ section above to understand for setting up token keyword.

——————- advertisements ——————-  

———————————————————

How to create Parameterized Job:

Consider a Jenkins Job where i am asking user inputs before executing Job, these type of jobs are called parameterized job. We can enable parameter request by checking ‘This Job Parameterized’ option under the general tab. Here i am enabling paramerized option for the job name ‘test-job’ and adding two string parameters ‘message1’ and ‘message2’.

Click on Job name -> Configure ->click on General Tab -> enable ‘This project is parameterized’ -> click add parameter and select ‘String Parameter’ from the drop down box. You can see multiple input parameter types which you can use as per your requirement.

On the upcoming window, enter the name as message1 and give the description. Click ‘add parameter’ and repeat the steps for ‘message2’ as well.

——————- advertisements ——————-  

———————————————————

Execute the Job by selecting your job name and clicking ‘Build with parameters’. This will prompt for user input before initiating the build. You can use the data provided by the user inside your build bash script or pipeline steps using ‘$message1’ format

Eg: echo Message 1 to the user $message1

echo Message 2 to the user $message2

 

Triggering Parametrized Job:

You can trigger parametrized job using API call and pass values. You can pass values in a URL encoded format or as part of a JSON file if you have many parameters. 

Passing parameters using URL encoded :

Step 1: Collect the CRUMB data 

——————- advertisements ——————-  

———————————————————

See the above section ‘Building REST API request’

Step 2: Send the parameters in URL

curl -v -H $crumb –user apiuser:apiuser -X POST ‘http://10.10.10.100:8080/job/testjob/buildWithParameters?token=MyTestAPIToken&message1=’hai’&message2=’hello’

Note : Message1 and message2 are the name of the parameter , please see above 

Passing parameters using URL encoded JSON format:

Step 1: Collect the crumb data 

See the above section ‘Building REST API request’

Step 2: Send the parameters in URL encoded Json format 

curl -v –user apiuser:apiuser -X POST http://10.10.10.100:8080/job/testjob/build –data token=MyTestAPIToken –data-urlencode json='{“parameter”:[{“name”:”message1″,”value”:”hai”},{“name”:”message2″,”value”:”hello”}]}’

 

Passing parameters using file:

Step 1: create a JSON file with all the parameters in the following format 

[root@web01 ~]# cat testapi.json
json={
“parameter”:[{“name”:”message1″,”value”:”hai”},{“name”:”message2″,”value”:”hello”}]
}
[root@web01 ~]#

Step 2: Collect the crumb data 

See the above section ‘Building REST API request’

Step 3: Send the api request by specifying file name . 

curl -v –user apiuser:apiuser -X POST http://10.10.10.100:8080/job/testjob/build –data “@testapi.json” -H “Accept: application/json”

 

Hope this helped you. Share your queries/feedback in the comments section below.