/ 
Jenkins-API-0.02
River stage one • 1 direct dependent • 1 total dependent
/ Jenkins::API

NAME

Jenkins::API - A wrapper around the Jenkins API

VERSION

Version 0.02

METHODS

SYNOPSIS

This is a wrapper around the Jenkins API.

use Jenkins::API;

my $jenkins = Jenkins::API->new({ base_url => 'http://jenkins:8080' });
my $status = $jenkins->current_status();
my @not_succeeded = grep { $_->{color} ne 'blue' } @{$status->{jobs}};
# {
#   'color' => 'red',
#   'name' => 'Test-Project',
#   'url' => 'http://jenkins:8080/job/Test-Project/',
# }

my $success = $jenkins->create_job($project_name, $config_xml);
...

check_jenkins_url

Checks the url provided to the api has a Jenkins server running on it. It returns the version number of the Jenkins server if it is running.

$jenkins->check_jenkins_url;
# 1.460

current_status

Returns the current status of the server as returned by the API. This is a hash containing a fairly comprehensive list of what's going on.

$jenkins->current_status();
# {
#   'assignedLabels' => [
#     {}
#   ],
#   'description' => undef,
#   'jobs' => [
#     {
#       'color' => 'blue',
#       'name' => 'Jenkins-API',
#       'url' => 'http://jenkins:8080/job/Jenkins-API/'
#     },
#   'mode' => 'NORMAL',
#   'nodeDescription' => 'the master Jenkins node',
#   'nodeName' => '',
#   'numExecutors' => 2,
#   'overallLoad' => {},
#   'primaryView' => {
#     'name' => 'All',
#     'url' => 'http://jenkins:8080/'
#   },
#   'quietingDown' => bless( do{\(my $o = 0)}, 'JSON::XS::Boolean' ),
#   'slaveAgentPort' => 0,
#   'useCrumbs' => $VAR1->{'quietingDown'},
#   'useSecurity' => $VAR1->{'quietingDown'},
#   'views' => [
#     {
#       'name' => 'All',
#       'url' => 'http://jenkins:8080/'
#     }
#   ]
# }

It is also possible to pass two parameters to the query to refine or expand the data you get back. The tree parameter allows you to select specific elements. The example from the Jenkins documentation , tree=> 'jobs[name],views[name,jobs[name]]' demonstrates the syntax nicely.

The other parameter you can pass is depth, by default it's 0, if you set it higher it dumps a ton of data.

$jenkins->current_status({ extra_params => { tree => 'jobs[name,color]' }});;
# {
#   'jobs' => [
#     {
#       'color' => 'blue',
#       'name' => 'Jenkins-API',
#     },
#   ]
# }

$jenkins->current_status({ extra_params => { depth => 1 }});
# returns everything and the kitchen sink.

It is also possible to only look at a subset of the data. Most urls you can see on the website in Jenkins can be accessed. If you have a job named Test-Project for example with the url /job/Test-Project you can specify the path_parts => ['job', 'Test-Project'] to look at the data for that job alone.

$jenkins->current_status({ 
    path_parts => [qw/job Test-Project/],
    extra_params => { depth => 1 },
});
# just returns the data relating to job Test-Project.
# returning it in detail.

The method will die saying 'Invalid response' if the server doesn't respond as it expects, or die with a JSON decoding error if the JSON parsing fails.

trigger_build

Trigger a build,

$success = $jenkins->trigger_build('Test-Project');

If you need to specify a token you can pass that like this,

$jenkins->trigger_build('Test-Project', { token => $token });

Note that the success response is simply to indicate that the build has been scheduled, not that the build has succeeded.

build_queue

This returns the items in the build queue.

$jenkins->build_queue();

This allows the same extra_params as the "current_status" call. The depth and tree parameters work in the same way. See the Jenkins api documentation for more details.

The method will die saying 'Invalid response' if the server doesn't respond as it expects, or die with a JSON decoding error if the JSON parsing fails.

load_statistics

This returns the load statistics for the server.

$jenkins->load_statistics();
# {
#   'busyExecutors' => {},
#   'queueLength' => {},
#   'totalExecutors' => {},
#   'totalQueueLength' => {}
# }

This also allows the same extra_params as the "current_status" call. The depth and tree parameters work in the same way. See the Jenkins api documentation for more details.

The method will die saying 'Invalid response' if the server doesn't respond as it expects, or die with a JSON decoding error if the JSON parsing fails.

create_job

Takes the project name and the xml for a config file and gets Jenkins to create the job.

my $success = $api->create_job($project_name, $config_xml);

project_config

This method returns the configuration for the project in xml.

my $config = $api->project_config($project_name);

set_project_config

This method allows you to set the configuration for the project using xml.

my $success = $api->set_project_config($project_name, $config);

delete_project

Delete the project from Jenkins.

my $success = $api->delete_project($project_name);

response_code

This method returns the HTTP response code from our last request to the Jenkins server. This may be useful when an error occurred.

response_content

This method returns the content of the HTTP response from our last request to the Jenkins server. This may be useful when an error occurrs.

AUTHOR

Colin Newell, <colin.newell at gmail.com>

BUGS

The API wrapper doesn't deal with jenkins installations not running from the root path. I don't actually know if that's an install option, but the internal url building just doesn't deal with that situation properly. If you want that fixing a patch is welcome.

Please report any bugs or feature requests to through the web interface at https://github.com/colinnewell/Jenkins-API/issues/new. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Jenkins::API

You can also look for information at:

SEE ALSO

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2012-3 Colin Newell.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.