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



32
33
34
 
# File 'lib/jenkins_api_client/job.rb', line 32

def initialize(client)
  @client = client
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 (Bool) (defaults to: false) —

    • true or false

Returns:

  • (String) —

    response_code return code from HTTP POST



798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
 
# File 'lib/jenkins_api_client/job.rb', line 798

def add_downstream_projects(job_name,
                            downstream_projects,
                            threshold, overwrite = false)
  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 (TrueClass|FalseClass) 


218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
 
# File 'lib/jenkins_api_client/job.rb', line 218

def add_email_notification(params)
  raise "No job name specified" unless params[:name]
  raise "No email address specified" unless params[:notification_email]
  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") { |xml|
      notification_email(params, xml)
    }
    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



255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/jenkins_api_client/job.rb', line 255

def add_skype_notification(params)
  raise "No job name specified" unless params[:name]
  raise "No Skype target specified" unless params[:skype_targets]
  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") { |xml|
      skype_notification(params, xml)
    }
    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



603
604
605
606
607
608
609
610
611
612
 
# File 'lib/jenkins_api_client/job.rb', line 603

def block_build_when_downstream_building(job_name)
  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



637
638
639
640
641
642
643
644
645
646
 
# File 'lib/jenkins_api_client/job.rb', line 637

def block_build_when_upstream_building(job_name)
  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 = {}) ⇒ String

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)
  • params (Hash) (defaults to: {})

Returns:

  • (String) —

    response_code return code from HTTP POST



526
527
528
529
530
531
532
 
# File 'lib/jenkins_api_client/job.rb', line 526

def build(job_name, params={})
  if params.empty?
    @client.api_post_request("/job/#{job_name}/build")
  else
    @client.api_post_request("/job/#{job_name}/buildWithParameters", params)
  end
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



910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
 
# File 'lib/jenkins_api_client/job.rb', line 910

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

  filtered_job_names = []
  if criteria.include?("all") || criteria.empty?
    filtered_job_names = job_names
  else
    log_msg = "[INFO] Criteria is specified. Filtering jobs..."
    puts log_msg if @client.debug
    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)
    msg = "[INFO] Adding <#{filtered_job_names[index+1]}> as a"
    msg << " downstream project to <#{job_name}> with <#{threshold}> as"
    msg << " the threshold"
    puts msg if @client.debug
    @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



588
589
590
591
592
593
594
595
 
# File 'lib/jenkins_api_client/job.rb', line 588

def change_description(job_name, 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



472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
 
# File 'lib/jenkins_api_client/job.rb', line 472

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

#create(job_name, xml) ⇒ Object

Create a job with the name specified and the xml given

Parameters:

  • job_name (String)
  • xml (XML) 


47
48
49
 
# File 'lib/jenkins_api_client/job.rb', line 47

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

#create_freestyle(params) ⇒ Object

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

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) —

    • :name name of the job

    • :keep_dependencies true or false

    • :block_build_when_downstream_building true or false

    • :block_build_when_upstream_building true or false

    • :concurrent_build true or false

    • :scm_provider type of source control. Supported: Git, SVN, and CVS

    • :scm_url remote url for scm

    • :scm_module Module to download. Only for CVS.

    • :scm_branch branch to use in scm. Uses master by default

    • :scm_tag tag to download from scm. Only for CVS.

    • :scm_use_head_if_tag_not_found Only for CVS.

    • :timer timer for running builds periodically.

    • :shell_command command to execute in the shell

    • :notification_email email for sending 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

    • :child_projects projects to add as downstream projects

    • :child_threshold threshold for child projects. success, failure, or unstable. Default: failure.



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/jenkins_api_client/job.rb', line 100

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

  # Set default values for params that are not specified.
  raise 'Job name must be specified' unless params[:name]
  if params[:keep_dependencies].nil?
    params[:keep_dependencies] = false
  end
  if params[:block_build_when_downstream_building].nil?
    params[:block_build_when_downstream_building] = false
  end
  if params[:block_build_when_upstream_building].nil?
    params[:block_build_when_upstream_building] = false
  end
  params[:concurrent_build] = false if params[:concurrent_build].nil?
  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 supported_scm.include?(params[:scm_provider]) ||
    params[:scm_provider].nil?
    raise "SCM #{params[:scm_provider]} is currently not supported"
  end
  if params[:scm_url].nil? && !params[:scm_provider].nil?
    raise 'SCM URL must be specified'
  end
  if params[:scm_branch].nil? && !params[:scm_provider].nil?
    params[:scm_branch] = "master"
  end
  if params[:scm_use_head_if_tag_not_found].nil?
    params[:scm_use_head_if_tag_not_found] = false
  end

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

  # Build the Job xml file based on the parameters given
  builder = Nokogiri::XML::Builder.new(:encoding => 'UTF-8') { |xml|
    xml.project {
      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 {
          xml.send("hudson.triggers.TimerTrigger") {
            xml.spec params[:timer]
          }
        }
      else
        xml.triggers.vector
      end
      xml.concurrentBuild "#{params[:concurrent_build]}"
      # Shell command stuff
      xml.builders {
        if params[:shell_command]
          xml.send("hudson.tasks.Shell") {
            xml.command "#{params[:shell_command]}"
          }
        end
      }
      # Adding Downstream projects
      xml.publishers {
        # 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]
      }
      xml.buildWrappers
    }
  }
  create(params[:name], builder.to_xml)
end

#delete(job_name) ⇒ Object

Delete a job given the name

Parameters:

  • job_name (String) 


285
286
287
 
# File 'lib/jenkins_api_client/job.rb', line 285

def delete(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



294
295
296
 
# File 'lib/jenkins_api_client/job.rb', line 294

def delete_all!
  list_all.each { |job| delete(job) }
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



672
673
674
675
676
677
678
679
680
681
 
# File 'lib/jenkins_api_client/job.rb', line 672

def execute_concurrent_builds(job_name, 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) 


383
384
385
 
# File 'lib/jenkins_api_client/job.rb', line 383

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) 


575
576
577
578
579
 
# File 'lib/jenkins_api_client/job.rb', line 575

def get_build_details(job_name, build_num)
  build_num = get_current_build_number(job_name) if build_num == 0

  @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



690
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
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
 
# File 'lib/jenkins_api_client/job.rb', line 690

def get_build_params(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) 


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

def get_builds(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



540
541
542
 
# File 'lib/jenkins_api_client/job.rb', line 540

def get_config(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



344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
 
# File 'lib/jenkins_api_client/job.rb', line 344

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) ⇒ Number

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:

  • (Number) —

    build_unumber current build number of the given job



514
515
516
 
# File 'lib/jenkins_api_client/job.rb', line 514

def get_current_build_number(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



502
503
504
505
 
# File 'lib/jenkins_api_client/job.rb', line 502

def get_current_build_status(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) 


452
453
454
455
 
# File 'lib/jenkins_api_client/job.rb', line 452

def get_downstream_projects(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) 


560
561
562
563
564
565
566
567
568
 
# File 'lib/jenkins_api_client/job.rb', line 560

def get_test_results(job_name, build_num)
  build_num = get_current_build_number(job_name) if build_num == 0

  @client.api_get_request("/job/#{job_name}/#{build_num}/testReport")
rescue Exceptions::NotFoundException
  # 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) 


443
444
445
446
 
# File 'lib/jenkins_api_client/job.rb', line 443

def get_upstream_projects(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) 


411
412
413
414
415
416
417
418
419
420
421
422
 
# File 'lib/jenkins_api_client/job.rb', line 411

def list(filter, ignorecase = true)
  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



372
373
374
375
376
377
 
# File 'lib/jenkins_api_client/job.rb', line 372

def list_all
  response_json = @client.api_get_request("")
  jobs = []
  response_json["jobs"].each { |job| jobs << job["name"] }
  jobs.sort!
end

#list_all_with_details ⇒ Object

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



426
427
428
429
 
# File 'lib/jenkins_api_client/job.rb', line 426

def list_all_with_details
 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: []) 


393
394
395
396
397
398
399
400
401
402
403
404
 
# File 'lib/jenkins_api_client/job.rb', line 393

def list_by_status(status, jobs = [])
  jobs = list_all if jobs.empty?
  xml_response = @client.api_get_request("", "tree=jobs[name,color]")
  filtered_jobs = []
  xml_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) 


435
436
437
 
# File 'lib/jenkins_api_client/job.rb', line 435

def list_details(job_name)
  @client.api_get_request("/job/#{job_name}")
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



551
552
553
 
# File 'lib/jenkins_api_client/job.rb', line 551

def post_config(job_name, xml)
  @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) 


323
324
325
326
327
 
# File 'lib/jenkins_api_client/job.rb', line 323

def recreate(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



838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
 
# File 'lib/jenkins_api_client/job.rb', line 838

def remove_downstream_projects(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.



277
278
279
 
# File 'lib/jenkins_api_client/job.rb', line 277

def rename(old_job, 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



872
873
874
875
876
877
878
879
880
881
882
883
884
885
 
# File 'lib/jenkins_api_client/job.rb', line 872

def restrict_to_node(job_name, node_name)
  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) 


306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/jenkins_api_client/job.rb', line 306

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
  # 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



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

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



620
621
622
623
624
625
626
627
628
629
 
# File 'lib/jenkins_api_client/job.rb', line 620

def unblock_build_when_downstream_building(job_name)
  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



654
655
656
657
658
659
660
661
662
663
 
# File 'lib/jenkins_api_client/job.rb', line 654

def unblock_build_when_upstream_building(job_name)
  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



891
892
893
894
895
896
897
 
# File 'lib/jenkins_api_client/job.rb', line 891

def unchain(job_names)
  job_names.each do |job|
    log_msg = "[INFO] Removing downstream projects for <#{job}>"
    puts log_msg if @client.debug
    remove_downstream_projects(job)
  end
end