Class: JenkinsApi::Client::Job

Inherits:
Object
  • Object
show all
Defined in:
lib/jenkins_api_client/job.rb

Overview

This class communicates with the Jenkins “/job” API to obtain details about jobs, creating, deleting, building, and various other operations.

Instance Method Summary collapse

Constructor Details

#initialize(client) ⇒ Job

Initialize the Job object and store the reference to Client object

Parameters:

  • client (Client) —

    the client object



36
37
38
39
 
# File 'lib/jenkins_api_client/job.rb', line 36

def initialize(client)
  @client = client
  @logger = @client.logger
end

Instance Method Details

#add_downstream_projects(job_name, downstream_projects, threshold, overwrite = false) ⇒ String

Add downstream projects to a specific job given the job name, projects to be added as downstream projects, and the threshold

Parameters:

  • job_name (String)
  • downstream_projects (String)
  • threshold (String) —

    • failure, success, or unstable

  • overwrite (Boolean) (defaults to: false) —

    • true or false

Returns:

  • (String) —

    response_code return code from HTTP POST



1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
 
# File 'lib/jenkins_api_client/job.rb', line 1038

def add_downstream_projects(job_name,
                            downstream_projects,
                            threshold, overwrite = false)
  @logger.info "Adding #{downstream_projects.inspect} as downstream" +
    " projects for '#{job_name}' with the threshold of '#{threshold}'" +
    " and overwrite option of '#{overwrite}'"
  name, ord, col = get_threshold_params(threshold)
  xml = get_config(job_name)
  n_xml = Nokogiri::XML(xml)
  child_projects_node = n_xml.xpath("//childProjects").first
  if child_projects_node
    if overwrite
      child_projects_node.content = "#{downstream_projects}"
    else
      to_replace = child_projects_node.content +
        ", #{downstream_projects}"
      child_projects_node.content = to_replace
    end
  else
    publisher_node = n_xml.xpath("//publishers").first
    build_trigger_node = publisher_node.add_child(
      "<hudson.tasks.BuildTrigger/>"
    )
    child_project_node = build_trigger_node.first.add_child(
      "<childProjects>#{downstream_projects}</childProjects>"
    )
    threshold_node = child_project_node.first.add_next_sibling(
      "<threshold/>"
    )
    threshold_node.first.add_child(
      "<name>#{name}</name><ordinal>#{ord}</ordinal><color>#{col}</color>"
    )
  end
  xml_modified = n_xml.to_xml
  post_config(job_name, xml_modified)
end

#add_email_notification(params) ⇒ Object

Adding email notification to a job

Send email notification email for every unstable build

Parameters:

  • params (Hash) —

    parameters to add email notification

Options Hash (params):

  • :name (String) —

    Name of the job

  • :notification_email (String) —

    Email address to send

  • :notification_email_for_every_unstable (Boolean) 


339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
 
# File 'lib/jenkins_api_client/job.rb', line 339

def add_email_notification(params)
  raise "No job name specified" unless params[:name]
  raise "No email address specified" unless params[:notification_email]
  @logger.info "Adding '#{params[:notification_email]}' to be" +
    " notified for '#{params[:name]}'"
  xml = get_config(params[:name])
  n_xml = Nokogiri::XML(xml)
  if n_xml.xpath("//hudson.tasks.Mailer").empty?
    p_xml = Nokogiri::XML::Builder.new(:encoding => "UTF-8") do |b_xml|
      notification_email(params, b_xml)
    end
    email_xml = Nokogiri::XML(p_xml.to_xml).xpath(
      "//hudson.tasks.Mailer"
    ).first
    n_xml.xpath("//publishers").first.add_child(email_xml)
    post_config(params[:name], n_xml.to_xml)
  end
end

#add_skype_notification(params) ⇒ Object

Adding skype notificaiton to a job

Parameters:

  • params (Hash) —

    parameters for adding skype notification

    • :name name of the job to add skype notification

    • :skype_targets skype targets for sending notifications to. Use * to specify group chats. Use space to separate multiple targets. Example: testuser, *testgroup.

    • :skype_strategy skype strategy to be used for sending notifications. Valid values: all, failure, failure_and_fixed, change. Default: change.

    • :skype_notify_on_build_start Default: false

    • :skype_notify_suspects Default: false

    • :skype_notify_culprits Default: false

    • :skype_notify_fixers Default: false

    • :skype_notify_upstream_committers Default: false

    • :skype_message what should be sent as notification message. Valid: just_summary, summary_and_scm_changes, summary_and_build_parameters, summary_scm_changes_and_failed_tests. Default: summary_and_scm_changes



378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
 
# File 'lib/jenkins_api_client/job.rb', line 378

def add_skype_notification(params)
  raise "No job name specified" unless params[:name]
  raise "No Skype target specified" unless params[:skype_targets]
  @logger.info "Adding Skype notification for '#{params[:name]}'"
  xml = get_config(params[:name])
  n_xml = Nokogiri::XML(xml)
  if n_xml.xpath("//hudson.plugins.skype.im.transport.SkypePublisher").empty?
    p_xml = Nokogiri::XML::Builder.new(:encoding => "UTF-8") do |b_xml|
      skype_notification(params, b_xml)
    end
    skype_xml = Nokogiri::XML(p_xml.to_xml).xpath(
      "//hudson.plugins.skype.im.transport.SkypePublisher"
    ).first
    n_xml.xpath("//publishers").first.add_child(skype_xml)
    post_config(params[:name], n_xml.to_xml)
  end
end

#block_build_when_downstream_building(job_name) ⇒ String

Block the build of the job when downstream is building

Parameters:

  • job_name (String)

Returns:

  • (String) —

    response_code return code from HTTP POST



832
833
834
835
836
837
838
839
840
841
842
843
 
# File 'lib/jenkins_api_client/job.rb', line 832

def block_build_when_downstream_building(job_name)
  @logger.info "Blocking builds of '#{job_name}' when downstream" +
    " projects are building"
  xml = get_config(job_name)
  n_xml = Nokogiri::XML(xml)
  node = n_xml.xpath("//blockBuildWhenDownstreamBuilding").first
  if node.content == "false"
    node.content = "true"
    xml_modified = n_xml.to_xml
    post_config(job_name, xml_modified)
  end
end

#block_build_when_upstream_building(job_name) ⇒ String

Block the build of the job when upstream is building

Parameters:

  • job_name (String)

Returns:

  • (String) —

    response_code return code from HTTP POST



870
871
872
873
874
875
876
877
878
879
880
881
 
# File 'lib/jenkins_api_client/job.rb', line 870

def block_build_when_upstream_building(job_name)
  @logger.info "Blocking builds of '#{job_name}' when upstream" +
    " projects are building"
  xml = get_config(job_name)
  n_xml = Nokogiri::XML(xml)
  node = n_xml.xpath("//blockBuildWhenUpstreamBuilding").first
  if node.content == "false"
    node.content = "true"
    xml_modified = n_xml.to_xml
    post_config(job_name, xml_modified)
  end
end

#build(job_name, params = {}, return_build_number = false) ⇒ String, Integer

Build a job given the name of the job You can optionally pass in a list of params for Jenkins to use for parameterized builds

Parameters:

  • job_name (String) —

    the name of the job

  • params (Hash) (defaults to: {}) —

    the parameters for parameterized builds

  • return_build_number (Boolean) (defaults to: false) —

    whether to wait and obtain the build number

Returns:

  • (String, Integer) —

    the response code from the build POST request if return_build_number is not requested and the build number if the return_build_number is requested. nil will be returned if the build number is requested and not available. This can happen if there is already a job in the queue and concurrent build is disabled.



691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
 
# File 'lib/jenkins_api_client/job.rb', line 691

def build(job_name, params={}, return_build_number = false)
  msg = "Building job '#{job_name}'"
  msg << " with parameters: #{params.inspect}" unless params.empty?
  @logger.info msg
  build_endpoint = params.empty? ? "build" : "buildWithParameters"
  raw_response = return_build_number
  response =@client.api_post_request(
    "/job/#{job_name}/#{build_endpoint}",
    params,
    raw_response
  )
  # If return_build_number is enabled, obtain the queue ID from the location
  # header and wait till the build is moved to one of the executors and a
  # build number is assigned
  if return_build_number
    if response["location"]
      task_id_match = response["location"].match(/\/item\/(\d*)\//)
      task_id = task_id_match.nil? ? nil : task_id_match[1]
      unless task_id.nil?
        @logger.debug "Queue task ID for job '#{job_name}': #{task_id}"
        Timeout::timeout(@client.timeout) do
          while @client.queue.get_item_by_id(task_id)["executable"].nil?
            sleep 5
          end
        end
        @client.queue.get_item_by_id(task_id)["executable"]["number"]
      else
        nil
      end
    else
      nil
    end
  else
    response
  end
end

#build_freestyle_config(params) ⇒ String

Builds the XML configuration based on the parameters passed as a Hash

Parameters:

  • params (Hash) —

    the parameters for building XML configuration

Returns:

  • (String) —

    the generated XML configuration of the project

Raises:

  • (ArgumentError) 


219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
 
# File 'lib/jenkins_api_client/job.rb', line 219

def build_freestyle_config(params)
  # Supported SCM providers
  supported_scm = ["git", "subversion", "cvs"]

  # Set default values for params that are not specified.
  raise ArgumentError, "Job name must be specified" \
    unless params.is_a?(Hash) && params[:name]

  [
    :keep_dependencies,
    :block_build_when_downstream_building,
    :block_build_when_upstream_building,
    :concurrent_build
  ].each do |param|
    params[param] = false if params[param].nil?
  end

  if params[:notification_email]
    if params[:notification_email_for_every_unstable].nil?
      params[:notification_email_for_every_unstable] = false
    end
    if params[:notification_email_send_to_individuals].nil?
      params[:notification_email_send_to_individuals] ||= false
    end
  end

  # SCM configurations and Error handling.
  unless params[:scm_provider].nil?
    unless supported_scm.include?(params[:scm_provider])
      raise "SCM #{params[:scm_provider]} is currently not supported"
    end
    raise "SCM URL must be specified" if params[:scm_url].nil?
    params[:scm_branch] = "master" if params[:scm_branch].nil?
    if params[:scm_use_head_if_tag_not_found].nil?
      params[:scm_use_head_if_tag_not_found] = false
    end
  end

  # Child projects configuration and Error handling
  if params[:child_threshold].nil? && !params[:child_projects].nil?
    params[:child_threshold] = "failure"
  end

  @logger.debug "Creating a freestyle job with params: #{params.inspect}"

  # Build the Job xml file based on the parameters given
  builder = Nokogiri::XML::Builder.new(:encoding => 'UTF-8') do |xml|
    xml.project do
      xml.actions
      xml.description
      xml.keepDependencies "#{params[:keep_dependencies]}"
      xml.properties
      # SCM related stuff
      if params[:scm_provider] == 'subversion'
        # Build subversion related XML portion
        scm_subversion(params, xml)
      elsif params[:scm_provider] == "cvs"
        # Build CVS related XML portion
        scm_cvs(params, xml)
      elsif params[:scm_provider] == "git"
        # Build Git related XML portion
        scm_git(params, xml)
      else
        xml.scm(:class => "hudson.scm.NullSCM")
      end
      # Restrict job to run in a specified node
      if params[:restricted_node]
        xml.assignedNode "#{params[:restricted_node]}"
        xml.canRoam "false"
      else
        xml.canRoam "true"
      end
      xml.disabled "false"
      xml.blockBuildWhenDownstreamBuilding(
        "#{params[:block_build_when_downstream_building]}")
      xml.blockBuildWhenUpstreamBuilding(
        "#{params[:block_build_when_upstream_building]}")
      if params[:timer]
        xml.triggers.vector do
          xml.send("hudson.triggers.TimerTrigger") do
            xml.spec params[:timer]
          end
        end
      else
        xml.triggers.vector
      end
      xml.concurrentBuild "#{params[:concurrent_build]}"
      # Shell command stuff
      xml.builders do
        if params[:shell_command]
          xml.send("hudson.tasks.Shell") do
            xml.command "#{params[:shell_command]}"
          end
        end
      end
      # Adding Downstream projects
      xml.publishers do
        # Build portion of XML that adds child projects
        child_projects(params, xml) if params[:child_projects]
        # Build portion of XML that adds email notification
        notification_email(params, xml) if params[:notification_email]
        # Build portion of XML that adds skype notification
        skype_notification(params, xml) if params[:skype_targets]
      end
      xml.buildWrappers
    end
  end
  builder.to_xml
end

#chain(job_names, threshold, criteria, parallel = 1) ⇒ Array

Chain the jobs given based on specified criteria

Parameters:

  • job_names (Array) —

    Array of job names to be chained

  • threshold (String) —

    threshold for running the next job

  • criteria (Array) —

    criteria which should be applied for picking the jobs for the chain

  • parallel (Integer) (defaults to: 1) —

    Number of jobs that should be considered for parallel run

Returns:

  • (Array) —

    job_names Names of jobs that are in the top of the chain



1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
 
# File 'lib/jenkins_api_client/job.rb', line 1152

def chain(job_names, threshold, criteria, parallel = 1)
  raise "Parallel jobs should be at least 1" if parallel < 1
  unchain(job_names)

  @logger.info "Chaining jobs: #{job_names.inspect}" +
    " with threshold of '#{threshold}' and criteria as '#{criteria}'" +
    " with #{parallel} number of parallel jobs"
  filtered_job_names = []
  if criteria.include?("all") || criteria.empty?
    filtered_job_names = job_names
  else
    job_names.each do |job|
      filtered_job_names << job if criteria.include?(
        @client.job.get_current_build_status(job)
      )
    end
  end

  filtered_job_names.each_with_index do |job_name, index|
    break if index >= (filtered_job_names.length - parallel)
    @client.job.add_downstream_projects(
      job_name, filtered_job_names[index + parallel], threshold, true
    )
  end
  if parallel > filtered_job_names.length
    parallel = filtered_job_names.length
  end
  filtered_job_names[0..parallel-1]
end

#change_description(job_name, description) ⇒ String

Change the description of a specific job

Parameters:

  • job_name (String)
  • description (String)

Returns:

  • (String) —

    response_code return code from HTTP POST



816
817
818
819
820
821
822
823
824
 
# File 'lib/jenkins_api_client/job.rb', line 816

def change_description(job_name, description)
  @logger.info "Changing the description of '#{job_name}' to '#{description}'"
  xml = get_config(job_name)
  n_xml = Nokogiri::XML(xml)
  desc = n_xml.xpath("//description").first
  desc.content = "#{description}"
  xml_modified = n_xml.to_xml
  post_config(job_name, xml_modified)
end

#color_to_status(color) ⇒ String

This method maps the color to status of a job

Parameters:

  • color (String) —

    color given by the API for a job

Returns:

  • (String) —

    status status of the given job matching the color



628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
 
# File 'lib/jenkins_api_client/job.rb', line 628

def color_to_status(color)
  case color
  when "blue"
    "success"
  when "red"
    "failure"
  when "yellow"
    "unstable"
  when /anime/
    "running"
  # In the recent version of Jenkins (> 1.517), jobs that are not built
  # yet have a color of "notbuilt" instead of "grey". Include that to the
  # not_run condition so it is backward compatible.
  when "grey", "notbuilt"
    "not_run"
  when "aborted"
    "aborted"
  else
    "invalid"
  end
end

#copy(from_job_name, to_job_name = nil) ⇒ Object

Copy a job

Parameters:

  • from_job_name (String)
  • to_job_name (String) (defaults to: nil) 


472
473
474
475
476
477
478
 
# File 'lib/jenkins_api_client/job.rb', line 472

def copy(from_job_name, to_job_name=nil)
  to_job_name = "copy_of_#{from_job_name}" if to_job_name.nil?
  @logger.info "Copying job '#{from_job_name}' to '#{to_job_name}'"
  @client.api_post_request(
    "/createItem?name=#{to_job_name}&mode=copy&from=#{from_job_name}"
  )
end

#create(job_name, xml) ⇒ String

Create a job with the name specified and the xml given

Parameters:

  • job_name (String) —

    the name of the job

  • xml (String) —

    the xml configuration of the job

Returns:

  • (String) —

    the HTTP status code from the POST request

See Also:



75
76
77
78
 
# File 'lib/jenkins_api_client/job.rb', line 75

def create(job_name, xml)
  @logger.info "Creating job '#{job_name}'"
  @client.post_config("/createItem?name=#{job_name}", xml)
end

#create_freestyle(params) ⇒ String

Create a freestyle project by accepting a Hash of parameters. For the parameter description see #create_of_update_freestyle

Examples:

Create a Freestype Project

create_freestyle(
  :name => "test_freestyle_job",
  :keep_dependencies => true,
  :concurrent_build => true,
  :scm_provider => "git",
  :scm_url => "git://github.com./arangamani/jenkins_api_client.git",
  :scm_branch => "master",
  :shell_command => "bundle install\n rake func_tests"
)

Parameters:

  • params (Hash) —

    the parameters for creating a job

Returns:

  • (String) —

    the HTTP status code from the POST request

See Also:



192
193
194
195
 
# File 'lib/jenkins_api_client/job.rb', line 192

def create_freestyle(params)
  xml = build_freestyle_config(params)
  create(params[:name], xml)
end

#create_or_update(job_name, xml) ⇒ String

Create or Update a job with the name specified and the xml given

Parameters:

  • job_name (String) —

    the name of the job

  • xml (String) —

    the xml configuration of the job

Returns:

  • (String) —

    the HTTP status code from the POST request

See Also:



57
58
59
60
61
62
63
 
# File 'lib/jenkins_api_client/job.rb', line 57

def create_or_update(job_name, xml)
  if exists?(job_name)
    update(job_name, xml)
  else
    create(job_name, xml)
  end
end

#create_or_update_freestyle(params) ⇒ String

Create or Update a job with params given as a hash instead of the xml This gives some flexibility for creating/updating simple jobs so the user doesn’t have to learn about handling xml.

Parameters:

  • params (Hash) —

    parameters to create a freestyle project

Options Hash (params):

  • :name (String) —

    the name of the job

  • :keep_dependencies (Boolean) — default: false —

    whether to keep the dependencies or not

  • :block_build_when_downstream_building (Boolean) — default: false —

    whether to block build when the downstream project is building

  • :block_build_when_upstream_building (Boolean) — default: false —

    whether to block build when the upstream project is building

  • :concurrent_build (Boolean) — default: false —

    whether to allow concurrent execution of builds

  • :scm_provider (String) —

    the type of source control. Supported providers: git, svn, and cvs

  • :scm_url (String) —

    the remote url for the selected scm provider

  • :scm_module (String) —

    the module to download. Only for use with “cvs” scm provider

  • :scm_branch (String) — default: master —

    the branch to use in scm.

  • :scm_tag (String) —

    the tag to download from scm. Only for use with “cvs” scm provider

  • :scm_use_head_if_tag_not_found (Boolean) —

    whether to use head if specified tag is not found. Only for “cvs”

  • :timer (String) —

    the timer for running builds periodically

  • :shell_command (String) —

    the command to execute in the shell

  • :notification_email (String) —

    the email for sending notification

  • :skype_targets (String) —

    the skype targets for sending notifications to. Use * to specify group chats. Use space to separate multiple targets. Note that this option requires the “skype” plugin to be installed in jenkins. Example: testuser *testgroup

  • :skype_strategy (String) — default: change —

    the skype strategy to be used for sending notifications. Valid values: all, failure, failure_and_fixed, change.

  • :skype_notify_on_build_start (Boolean) — default: false —

    whether to notify skype targets on build start

  • :skype_notify_suspects (Boolean) — default: false —

    whether to notify suspects on skype

  • :skype_notify_culprits (Boolean) — default: false —

    whether to notify culprits on skype

  • :skype_notify_fixers (Boolean) — default: false —

    whether to notify fixers on skype

  • :skype_notify_upstream_committers (Boolean) — default: false —

    whether to notify upstream committers on skype

  • :skype_message (String) — default: summary_and_scm_changes —

    the information to be sent as notification message. Valid: just_summary, summary_and_scm_changes, summary_and_build_parameters, summary_scm_changes_and_failed_tests.

  • :child_projects (String) —

    the projects to add as downstream projects

  • :child_threshold (String) — default: failure —

    the threshold for child projects. Valid options: success, failure, or unstable.

Returns:

  • (String) —

    the HTTP status code from the POST request

See Also:



162
163
164
165
166
167
168
 
# File 'lib/jenkins_api_client/job.rb', line 162

def create_or_update_freestyle(params)
  if exists?(params[:name])
    update_freestyle(params)
  else
    create_freestyle(params)
  end
end

#delete(job_name) ⇒ Object

Delete a job given the name

Parameters:

  • job_name (String) 


410
411
412
413
 
# File 'lib/jenkins_api_client/job.rb', line 410

def delete(job_name)
  @logger.info "Deleting job '#{job_name}'"
  @client.api_post_request("/job/#{job_name}/doDelete")
end

#delete_all! ⇒ Object

Note:

This method will remove all jobs from Jenkins. Please use with caution.

Deletes all jobs from Jenkins



420
421
422
423
 
# File 'lib/jenkins_api_client/job.rb', line 420

def delete_all!
  @logger.info "Deleting all jobs from jenkins"
  list_all.each { |job| delete(job) }
end

#disable(job_name) ⇒ Object

Disable a job given the name of the job

Parameters:

  • job_name (String) 


752
753
754
755
 
# File 'lib/jenkins_api_client/job.rb', line 752

def disable(job_name)
  @logger.info "Disabling job '#{job_name}'"
  @client.api_post_request("/job/#{job_name}/disable")
end

#enable(job_name) ⇒ Object

Enable a job given the name of the job

Parameters:

  • job_name (String) 


743
744
745
746
 
# File 'lib/jenkins_api_client/job.rb', line 743

def enable(job_name)
  @logger.info "Enabling job '#{job_name}'"
  @client.api_post_request("/job/#{job_name}/enable")
end

#execute_concurrent_builds(job_name, option) ⇒ String

Allow or disable concurrent build execution

Parameters:

  • job_name (String)
  • option (Bool) —

    true or false

Returns:

  • (String) —

    response_code return code from HTTP POST



909
910
911
912
913
914
915
916
917
918
919
920
 
# File 'lib/jenkins_api_client/job.rb', line 909

def execute_concurrent_builds(job_name, option)
  @logger.info "Setting the concurrent build execution option of" +
    " '#{job_name}' to #{option}"
  xml = get_config(job_name)
  n_xml = Nokogiri::XML(xml)
  node = n_xml.xpath("//concurrentBuild").first
  if node.content != "#{option}"
    node.content = option == true ? "true" : "false"
    xml_modified = n_xml.to_xml
    post_config(job_name, xml_modified)
  end
end

#exists?(job_name) ⇒ Boolean

Checks if the given job exists in Jenkins

Parameters:

  • job_name (String)

Returns:

  • (Boolean) 


532
533
534
 
# File 'lib/jenkins_api_client/job.rb', line 532

def exists?(job_name)
  list(job_name).include?(job_name)
end

#get_build_details(job_name, build_num) ⇒ Object

Obtain detailed build info for a job

Parameters:

  • job_name (String)
  • build_num (Number) 


801
802
803
804
805
806
807
 
# File 'lib/jenkins_api_client/job.rb', line 801

def get_build_details(job_name, build_num)
  build_num = get_current_build_number(job_name) if build_num == 0
  @logger.info "Obtaining the build details of '#{job_name}'" +
    " Build ##{build_num}"

  @client.api_get_request("/job/#{job_name}/#{build_num}/")
end

#get_build_params(job_name) ⇒ Array

Obtain the build parameters of a job. It returns an array of hashes with details of job params.

Parameters:

  • job_name (String)

Returns:

  • (Array) —

    params_array Array of parameters for the given job



929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
 
# File 'lib/jenkins_api_client/job.rb', line 929

def get_build_params(job_name)
  @logger.info "Obtaining the build params of '#{job_name}'"
  xml = get_config(job_name)
  n_xml = Nokogiri::XML(xml)
  params = n_xml.xpath("//parameterDefinitions").first
  params_array = []
  if params
    params.children.each do |param|
      param_hash = {}
      case param.name
      when "hudson.model.StringParameterDefinition",
           "hudson.model.BooleanParameterDefinition",
           "hudson.model.TextParameterDefinition",
           "hudson.model.PasswordParameterDefinition"
        param_hash[:type] = 'string' if param.name =~ /string/i
        param_hash[:type] = 'boolean' if param.name =~ /boolean/i
        param_hash[:type] = 'text' if param.name =~ /text/i
        param_hash[:type] = 'password' if param.name =~ /password/i
        param.children.each do |value|
          param_hash[:name] = value.content if value.name == "name"
          if value.name == "description"
            param_hash[:description] = value.content
          end
          if value.name == "defaultValue"
            param_hash[:default] = value.content
          end
        end
      when "hudson.model.RunParameterDefinition"
        param_hash[:type] = 'run'
        param.children.each do |value|
          param_hash[:name] = value.content if value.name == "name"
          if value.name == "description"
            param_hash[:description] = value.content
          end
          if value.name == "projectName"
            param_hash[:project] = value.content
          end
        end
      when "hudson.model.FileParameterDefinition"
        param_hash[:type] = 'file'
        param.children.each do |value|
          param_hash[:name] = value.content if value.name == "name"
          if value.name == "description"
            param_hash[:description] = value.content
          end
        end
      when "hudson.scm.listtagsparameter.ListSubversionTagsParameterDefinition"
        param_hash[:type] = 'list_tags'
        param.children.each do |value|
          if value.name == "name"
            param_hash[:name] = value.content
          end
          if value.name == "description"
            param_hash[:description] = value.content
          end
          if value.name == "tagsDir"
            param_hash[:tags_dir] = value.content
          end
          if value.name == "tagsFilter"
            param_hash[:tags_filter] = value.content
          end
          if value.name == "reverseByDate"
            param_hash[:reverse_by_date] = value.content
          end
          if value.name == "reverseByName"
            param_hash[:reverse_by_name] = value.content
          end
          if value.name == "defaultValue"
            param_hash[:default] = value.content
          end
          param_hash[:max_tags] = value.content if value.name == "maxTags"
          param_hash[:uuid] = value.content if value.name == "uuid"
        end
      when "hudson.model.ChoiceParameterDefinition"
        param_hash[:type] = 'choice'
        param.children.each do |value|
          param_hash[:name] = value.content if value.name == "name"
          param_hash[:description] = value.content \
            if value.name == "description"
          choices = []
          if value.name == "choices"
            value.children.each do |value_child|
              if value_child.name == "a"
                value_child.children.each do |choice_child|
                  choices << choice_child.content.strip \
                    unless choice_child.content.strip.empty?
                end
              end
            end
          end
          param_hash[:choices] = choices unless choices.empty?
        end
      end
      params_array << param_hash unless param_hash.empty?
    end
  end
  params_array
end

#get_builds(job_name) ⇒ Object

Obtain build details of a specific job

Parameters:

  • job_name (String) 


616
617
618
619
620
 
# File 'lib/jenkins_api_client/job.rb', line 616

def get_builds(job_name)
  @logger.info "Obtaining the build details of '#{job_name}'"
  response_json = @client.api_get_request("/job/#{job_name}")
  response_json["builds"]
end

#get_config(job_name) ⇒ String

Obtain the configuration stored in config.xml of a specific job

Parameters:

  • job_name (String)

Returns:

  • (String) —

    XML Config.xml of the job



763
764
765
766
 
# File 'lib/jenkins_api_client/job.rb', line 763

def get_config(job_name)
  @logger.info "Obtaining the config.xml of '#{job_name}'"
  @client.get_config("/job/#{job_name}")
end

#get_console_output(job_name, build_num = 0, start = 0, mode = 'text') ⇒ Hash

Get progressive console output from Jenkins server for a job

Parameters:

  • job_name (String) —

    Name of the Jenkins job

  • build_num (Number) (defaults to: 0) —

    Specific build number to obtain the console output from. Default is the recent build

  • start (Number) (defaults to: 0) —

    start offset to get only a portion of the text

  • mode (String) (defaults to: 'text') —

    Mode of text output. ‘text’ or ‘html’

Returns:

  • (Hash) —

    response

    • output console output of the job

    • size size of the text. This can be used as ‘start’ for the next call to get progressive output

    • more more data available for the job. ‘true’ if available and nil otherwise



495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
 
# File 'lib/jenkins_api_client/job.rb', line 495

def get_console_output(job_name, build_num = 0, start = 0, mode = 'text')
  build_num = get_current_build_number(job_name) if build_num == 0
  if build_num == 0
    puts "No builds for this job '#{job_name}' yet."
    return nil
  end
  if mode == 'text'
    mode = 'Text'
  elsif mode == 'html'
    mode = 'Html'
  else
    raise "Mode should either be 'text' or 'html'. You gave: #{mode}"
  end
  get_msg = "/job/#{job_name}/#{build_num}/logText/progressive#{mode}?"
  get_msg << "start=#{start}"
  raw_response = true
  api_response = @client.api_get_request(get_msg, nil, nil, raw_response)
  #puts "Response: #{api_response.header['x-more-data']}"
  response = {}
  response['output'] = api_response.body
  response['size'] = api_response.header['x-text-size']
  response['more'] = api_response.header['x-more-data']

  response
end

#get_current_build_number(job_name) ⇒ Integer

Obtain the current build number of the given job This function returns nil if there were no builds for the given job.

Parameters:

  • job_name (String)

Returns:

  • (Integer) —

    current build number of the given job



671
672
673
674
 
# File 'lib/jenkins_api_client/job.rb', line 671

def get_current_build_number(job_name)
  @logger.info "Obtaining the current build number of '#{job_name}'"
  @client.api_get_request("/job/#{job_name}")['nextBuildNumber'].to_i - 1
end

#get_current_build_status(job_name) ⇒ String

Obtain the current build status of the job By defaule Jenkins returns the color of the job status icon This function translates the color into a meaningful status

Parameters:

  • job_name (String)

Returns:

  • (String) —

    status current status of the given job



658
659
660
661
662
 
# File 'lib/jenkins_api_client/job.rb', line 658

def get_current_build_status(job_name)
  @logger.info "Obtaining the current build status of '#{job_name}'"
  response_json = @client.api_get_request("/job/#{job_name}")
  color_to_status(response_json["color"])
end

#get_downstream_projects(job_name) ⇒ Object

List downstream projects of a specific job

Parameters:

  • job_name (String) 


606
607
608
609
610
 
# File 'lib/jenkins_api_client/job.rb', line 606

def get_downstream_projects(job_name)
  @logger.info "Obtaining the down stream projects of '#{job_name}'"
  response_json = @client.api_get_request("/job/#{job_name}")
  response_json["downstreamProjects"]
end

#get_test_results(job_name, build_num) ⇒ Object

Obtain the test results for a specific build of a job

Parameters:

  • job_name (String)
  • build_num (Number) 


785
786
787
788
789
790
791
792
793
794
 
# File 'lib/jenkins_api_client/job.rb', line 785

def get_test_results(job_name, build_num)
  build_num = get_current_build_number(job_name) if build_num == 0
  @logger.info "Obtaining the test results of '#{job_name}'" +
    " Build ##{build_num}"
  @client.api_get_request("/job/#{job_name}/#{build_num}/testReport")
rescue Exceptions::NotFound
  # Not found is acceptable, as not all builds will have test results
  # and this is what jenkins throws at us in that case
  nil
end

#get_upstream_projects(job_name) ⇒ Object

List upstream projects of a specific job

Parameters:

  • job_name (String) 


596
597
598
599
600
 
# File 'lib/jenkins_api_client/job.rb', line 596

def get_upstream_projects(job_name)
  @logger.info "Obtaining the upstream projects of '#{job_name}'"
  response_json = @client.api_get_request("/job/#{job_name}")
  response_json["upstreamProjects"]
end

#list(filter, ignorecase = true) ⇒ Object

List all jobs that match the given regex

Parameters:

  • filter (String) —

    • a regex

  • ignorecase (Boolean) (defaults to: true) 


561
562
563
564
565
566
567
568
569
570
571
572
573
 
# File 'lib/jenkins_api_client/job.rb', line 561

def list(filter, ignorecase = true)
  @logger.info "Obtaining jobs matching filter '#{filter}'"
  response_json = @client.api_get_request("")
  jobs = []
  response_json["jobs"].each do |job|
    if ignorecase
      jobs << job["name"] if job["name"] =~ /#{filter}/i
    else
      jobs << job["name"] if job["name"] =~ /#{filter}/
    end
  end
  jobs
end

#list_all ⇒ Object

List all jobs on the Jenkins CI server



523
524
525
526
 
# File 'lib/jenkins_api_client/job.rb', line 523

def list_all
  response_json = @client.api_get_request("", "tree=jobs[name]")["jobs"]
  response_json.map { |job| job["name"] }.sort
end

#list_all_with_details ⇒ Object

List all jobs on the Jenkins CI server along with their details



577
578
579
580
581
 
# File 'lib/jenkins_api_client/job.rb', line 577

def list_all_with_details
  @logger.info "Obtaining the details of all jobs"
  response_json = @client.api_get_request("")
  response_json["jobs"]
end

#list_by_status(status, jobs = []) ⇒ Object

List all Jobs matching the given status You can optionally pass in jobs list to filter the status from

Parameters:

  • status (String)
  • jobs (Array) (defaults to: []) 


542
543
544
545
546
547
548
549
550
551
552
553
554
 
# File 'lib/jenkins_api_client/job.rb', line 542

def list_by_status(status, jobs = [])
  jobs = list_all if jobs.empty?
  @logger.info "Obtaining jobs matching status '#{status}'"
  json_response = @client.api_get_request("", "tree=jobs[name,color]")
  filtered_jobs = []
  json_response["jobs"].each do |job|
    if color_to_status(job["color"]) == status &&
       jobs.include?(job["name"])
      filtered_jobs << job["name"]
    end
  end
  filtered_jobs
end

#list_details(job_name) ⇒ Object

List details of a specific job

Parameters:

  • job_name (String) 


587
588
589
590
 
# File 'lib/jenkins_api_client/job.rb', line 587

def list_details(job_name)
  @logger.info "Obtaining the details of '#{job_name}'"
  @client.api_get_request("/job/#{job_name}")
end

#poll(job_name) ⇒ String

Programatically schedule SCM polling for the specified job

Parameters:

  • job_name (String) —

    the name of the job

Returns:

  • (String) —

    the response code from the HTTP post request



734
735
736
737
 
# File 'lib/jenkins_api_client/job.rb', line 734

def poll(job_name)
  @logger.info "Polling SCM changes for job '#{job_name}'"
  @client.api_post_request("/job/#{job_name}/polling")
end

#post_config(job_name, xml) ⇒ String

Post the configuration of a job given the job name and the config.xml

Parameters:

  • job_name (String)
  • xml (String)

Returns:

  • (String) —

    response_code return code from HTTP POST



775
776
777
778
 
# File 'lib/jenkins_api_client/job.rb', line 775

def post_config(job_name, xml)
  @logger.info "Posting the config.xml of '#{job_name}'"
  @client.post_config("/job/#{job_name}/config.xml", xml)
end

#recreate(job_name) ⇒ Object

Re-create the same job This is a hack to clear any existing builds

Parameters:

  • job_name (String) 


460
461
462
463
464
465
 
# File 'lib/jenkins_api_client/job.rb', line 460

def recreate(job_name)
  @logger.info "Recreating job '#{job_name}'"
  job_xml = get_config(job_name)
  delete(job_name)
  create(job_name, job_xml)
end

#remove_downstream_projects(job_name) ⇒ String

Remove all downstream projects of a specific job

Parameters:

  • job_name (String)

Returns:

  • (String) —

    response_code return code from HTTP POST



1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
 
# File 'lib/jenkins_api_client/job.rb', line 1081

def remove_downstream_projects(job_name)
  @logger.info "Removing the downstream projects of '#{job_name}'"
  xml = get_config(job_name)
  n_xml = Nokogiri::XML(xml)
  n_xml.search("//hudson.tasks.BuildTrigger").each do |node|
    child_project_trigger = false
    node.search("//childProjects").each do |child_node|
      child_project_trigger = true
      child_node.search("//threshold").each do |threshold_node|
        threshold_node.children.each do |threshold_value_node|
          threshold_value_node.content = nil
          threshold_value_node.remove
        end
        threshold_node.content = nil
        threshold_node.remove
      end
      child_node.content = nil
      child_node.remove
    end
    node.content = nil
    node.remove
  end
  publisher_node = n_xml.search("//publishers").first
  publisher_node.content = nil if publisher_node.children.empty?
  xml_modified = n_xml.to_xml
  post_config(job_name, xml_modified)
end

#rename(old_job, new_job) ⇒ Object

Rename a job given the old name and new name

Parameters:

  • old_job (String) —

    Name of the old job

  • new_job (String) —

    Name of the new job.



401
402
403
404
 
# File 'lib/jenkins_api_client/job.rb', line 401

def rename(old_job, new_job)
  @logger.info "Renaming job '#{old_job}' to '#{new_job}'"
  @client.api_post_request("/job/#{old_job}/doRename?newName=#{new_job}")
end

#restrict_to_node(job_name, node_name) ⇒ String

Resctrict the given job to a specific node

Parameters:

  • job_name (String)
  • node_name (String)

Returns:

  • (String) —

    response_code return code from HTTP POST



1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
 
# File 'lib/jenkins_api_client/job.rb', line 1116

def restrict_to_node(job_name, node_name)
  @logger.info "Restricting '#{job_name}' to '#{node_name}' node"
  xml = get_config(job_name)
  n_xml = Nokogiri::XML(xml)
  if (node = n_xml.xpath("//assignedNode").first)
    node.content = node_name
  else
    project = n_xml.xpath("//scm").first
    project.add_next_sibling("<assignedNode>#{node_name}</assignedNode>")
    roam_node = n_xml.xpath("//canRoam").first
    roam_node.content = "false"
  end
  xml_modified = n_xml.to_xml
  post_config(job_name, xml_modified)
end

#stop_build(job_name, build_number = 0) ⇒ Object

Stops a running build of a job This method will stop the current/most recent build if no build number is specified. The build will be stopped only if it was in ‘running’ state.

Parameters:

  • job_name (String)
  • build_number (Number) (defaults to: 0) 


442
443
444
445
446
447
448
449
450
451
452
453
 
# File 'lib/jenkins_api_client/job.rb', line 442

def stop_build(job_name, build_number = 0)
  build_number = get_current_build_number(job_name) if build_number == 0
  raise "No builds for #{job_name}" unless build_number
  @logger.info "Stopping job '#{job_name}' Build ##{build_number}"
  # Check and see if the build is running
  is_building = @client.api_get_request(
    "/job/#{job_name}/#{build_number}"
  )["building"]
  if is_building
    @client.api_post_request("/job/#{job_name}/#{build_number}/stop")
  end
end

#to_s ⇒ Object

Return a string representation of the object



43
44
45
 
# File 'lib/jenkins_api_client/job.rb', line 43

def to_s
  "#<JenkinsApi::Client::Job>"
end

#unblock_build_when_downstream_building(job_name) ⇒ String

Unblock the build of the job when downstream is building

Parameters:

  • job_name (String)

Returns:

  • (String) —

    response_code return code from HTTP POST



851
852
853
854
855
856
857
858
859
860
861
862
 
# File 'lib/jenkins_api_client/job.rb', line 851

def unblock_build_when_downstream_building(job_name)
  @logger.info "Unblocking builds of '#{job_name}' when downstream" +
    " projects are building"
  xml = get_config(job_name)
  n_xml = Nokogiri::XML(xml)
  node = n_xml.xpath("//blockBuildWhenDownstreamBuilding").first
  if node.content == "true"
    node.content = "false"
    xml_modified = n_xml.to_xml
    post_config(job_name, xml_modified)
  end
end

#unblock_build_when_upstream_building(job_name) ⇒ String

Unblock the build of the job when upstream is building

Parameters:

  • job_name (String)

Returns:

  • (String) —

    response_code return code from HTTP POST



889
890
891
892
893
894
895
896
897
898
899
900
 
# File 'lib/jenkins_api_client/job.rb', line 889

def unblock_build_when_upstream_building(job_name)
  @logger.info "Unblocking builds of '#{job_name}' when upstream" +
    " projects are building"
  xml = get_config(job_name)
  n_xml = Nokogiri::XML(xml)
  node = n_xml.xpath("//blockBuildWhenUpstreamBuilding").first
  if node.content == "true"
    node.content = "false"
    xml_modified = n_xml.to_xml
    post_config(job_name, xml_modified)
  end
end

#unchain(job_names) ⇒ Object

Unchain any existing chain between given job names

Parameters:

  • job_names (Array) —

    Array of job names to be unchained



1136
1137
1138
1139
 
# File 'lib/jenkins_api_client/job.rb', line 1136

def unchain(job_names)
  @logger.info "Unchaining jobs: #{job_names.inspect}"
  job_names.each { |job| remove_downstream_projects(job) }
end

#update(job_name, xml) ⇒ String

Update a job with the name specified and the xml given

Parameters:

  • job_name (String) —

    the name of the job

  • xml (String) —

    the xml configuration of the job

Returns:

  • (String) —

    the HTTP status code from the POST request

See Also:



90
91
92
93
 
# File 'lib/jenkins_api_client/job.rb', line 90

def update(job_name, xml)
  @logger.info "Updating job '#{job_name}'"
  post_config(job_name, xml)
end

#update_freestyle(params) ⇒ String

Update a job with params given as a hash instead of the xml. For the parameter description see #create_or_update_freestyle

Parameters:

  • params (Hash)

Returns:

  • (String) —

    the HTTP status code from the POST request

See Also:



208
209
210
211
 
# File 'lib/jenkins_api_client/job.rb', line 208

def update_freestyle(params)
  xml = build_freestyle_config(params)
  update(params[:name], xml)
end

#wipe_out_workspace(job_name) ⇒ Object

Wipe out the workspace for a job given the name

Parameters:

  • job_name (String) 


429
430
431
432
 
# File 'lib/jenkins_api_client/job.rb', line 429

def wipe_out_workspace(job_name)
  @logger.info "Wiping out the workspace of job '#{job_name}'"
  @client.api_post_request("/job/#{job_name}/doWipeOutWorkspace")
end