Module: RemoteAPI

Included in:
JIRA::JIRAService
Defined in:
lib/jiraSOAP/api.rb

Overview

TODO:

logging

TODO:

code refactoring and de-duplication

TODO:

break the API down by task, like Apple’s developer documentation; I can break the tasks down by CRUD or by what they affect, or both

TODO:

progressWorkflowAction and friends [target v0.7]

Contains the API defined by Atlassian for the [JIRA SOAP service](docs.atlassian.com/software/jira/docs/api/rpc-jira-plugin/latest/com/atlassian/jira/rpc/soap/JiraSoapService.html).

There are several cases where this API diverges from the one defined by Atlassian; most notably, this API tries to be more idomatically Ruby by using snake case for method names.

Constant Summary collapse

RESPONSE_XPATH =

XPath constant to get a node containing a response array. This could be used for all responses, but is only used in cases where we cannot use a more blunt XPath expression.

'/node()[1]/node()[1]/node()[1]/node()[2]'

Instance Method Summary collapse

Instance Method Details

#add_base64_encoded_attachments_to_issue_with_key(issue_key, filenames, data) ⇒ true

TODO:

optimize building the message, try a single pass

Expect this method to be slow.

Parameters:

  • issue_key (String)
  • filenames ([String]) —

    names to put on the files

  • data ([String]) —

    base64 encoded data

Returns:

  • (true) 


535
536
537
538
539
540
541
542
543
544
545
546
547
 
# File 'lib/jiraSOAP/api.rb', line 535

def add_base64_encoded_attachments_to_issue_with_key(issue_key, filenames, data)
  invoke('soap:addBase64EncodedAttachmentsToIssue') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', issue_key
    msg.add 'soap:in2' do |submsg|
      filenames.each { |filename| submsg.add 'filenames', filename }
    end
    msg.add 'soap:in3' do |submsg|
      data.each { |datum| submsg.add 'base64EncodedData', datum }
    end
  }
  true
end

#add_comment_to_issue_with_key(issue_key, comment) ⇒ true

Parameters:

Returns:

  • (true) 


406
407
408
409
410
411
412
413
 
# File 'lib/jiraSOAP/api.rb', line 406

def add_comment_to_issue_with_key(issue_key, comment)
  invoke('soap:addComment') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', issue_key
    msg.add 'soap:in2' do |submsg| comment.soapify_for submsg end
  }
  true
end

#add_version_to_project_with_key(project_key, version) ⇒ JIRA::Version

New versions cannot have the archived bit set and the release date field will ignore the time of day you give it and instead insert the time zone offset as the time of day.

Remember that the @release_date field is the tentative release date, so its value is independant of the @released flag.

Descriptions do not appear to be included with JIRA::Version objects that SOAP API provides.

Parameters:

Returns:



286
287
288
289
290
291
292
293
 
# File 'lib/jiraSOAP/api.rb', line 286

def add_version_to_project_with_key(project_key, version)
  response = invoke('soap:addVersion') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', project_key
    msg.add 'soap:in2' do |submsg| version.soapify_for submsg end
  }
  JIRA::Version.new_with_xml response.document.xpath('//addVersionReturn').first
end

#create_issue_with_issue(issue) ⇒ JIRA::Issue

Some fields will be ignored when an issue is created.

- reporter - you cannot override this value at creation
- resolution
- attachments
- votes
- status
- due date - I think this is a bug in jiraSOAP or JIRA
- environment - I think this is a bug in jiraSOAP or JIRA

Parameters:

Returns:



232
233
234
235
236
237
238
239
240
 
# File 'lib/jiraSOAP/api.rb', line 232

def create_issue_with_issue(issue)
  response = invoke('soap:createIssue') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1' do |submsg|
      issue.soapify_for submsg
    end
  }
  JIRA::Issue.new_with_xml response.document.xpath('//createIssueReturn').first
end

#create_project_role_with_role(project_role) ⇒ JIRA::ProjectRole

Returns the role that was created.

Parameters:

Returns:



682
683
684
685
686
687
688
 
# File 'lib/jiraSOAP/api.rb', line 682

def create_project_role_with_role project_role
  response = invoke('soap:createProjectRole') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1' do |submsg| project_role.soapify_for submsg end
  }
  JIRA::ProjectRole.new_with_xml response.document.xpath('//createProjectRoleReturn').first
end

#create_project_with_project(project) ⇒ JIRA::Project

Requires you to set at least a project name, key, and lead. However, it is also a good idea to set other project properties, such as the permission scheme as the default permission scheme can be too restrictive in most cases.

Parameters:

Returns:



317
318
319
320
321
322
323
 
# File 'lib/jiraSOAP/api.rb', line 317

def create_project_with_project(project)
  response = invoke('soap:createProjectFromObject') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1' do |submsg| project.soapify_for submsg end
  }
  JIRA::Project.new_with_xml response.document.xpath('//createProjectFromObjectReturn').first
end

#create_user(username, password, full_name, email) ⇒ JIRA::User?

It seems that creating a user without any permission groups will trigger an exception on some versions of JIRA. The irony is that this method provides no way to add groups. The good news though, is that the creation will still happen; but the user will have no permissions.

Parameters:

  • username (String)
  • password (String)
  • full_name (String)
  • email (String)

Returns:

  • (JIRA::User, nil) —

    depending on your JIRA version, this method may always raise an exception instead of actually returning anythin



360
361
362
363
364
365
366
367
368
369
 
# File 'lib/jiraSOAP/api.rb', line 360

def create_user(username, password, full_name, email)
  response = invoke('soap:createUser') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', username
    msg.add 'soap:in2', password
    msg.add 'soap:in3', full_name
    msg.add 'soap:in4', email
  }
  JIRA::User.new_with_xml response.document.xpath('//createUserReturn').first
end

#delete_project_avatar_with_id(avatar_id) ⇒ true

TODO:

add tests for this method

Note:

You cannot delete the system avatar

Note:

You need project administration permissions to delete an avatar

Parameters:

  • avatar_id (#to_s)

Returns:

  • (true) 


612
613
614
615
616
617
618
 
# File 'lib/jiraSOAP/api.rb', line 612

def delete_project_avatar_with_id avatar_id
  invoke('soap:deleteProjectAvatar') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', avatar_id
  }
  true
end

#delete_project_role(project_role, confirm = true) ⇒ true

Note:

the confirm argument appears to do nothing (at least on JIRA 4.0)

Parameters:

Returns:

  • (true) 


706
707
708
709
710
711
712
713
 
# File 'lib/jiraSOAP/api.rb', line 706

def delete_project_role project_role, confirm = true
  invoke('soap:deleteProjectRole') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1' do |submsg| project_role.soapify_for submsg end
    msg.add 'soap:in2', confirm
  }
  true
end

#delete_project_with_key(project_key) ⇒ true

Parameters:

  • project_key (String)

Returns:

  • (true) 


599
600
601
602
603
604
605
 
# File 'lib/jiraSOAP/api.rb', line 599

def delete_project_with_key project_key
  invoke('soap:deleteProject') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', project_key
  }
  true
end

#delete_user_with_name(username) ⇒ true

Parameters:

  • username (String)

Returns:

  • (true) 


373
374
375
376
377
378
379
 
# File 'lib/jiraSOAP/api.rb', line 373

def delete_user_with_name(username)
  invoke('soap:deleteUser') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', username
  }
  true
end

#get_attachments_for_issue_with_key(issue_key) ⇒ [JIRA::Attachment]

Parameters:

  • issue_key (String)

Returns:

  • ([JIRA::Attachment]) 


264
265
266
267
268
269
270
271
272
 
# File 'lib/jiraSOAP/api.rb', line 264

def get_attachments_for_issue_with_key(issue_key)
  response = invoke('soap:getAttachmentsFromIssue') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', issue_key
  }
  response.document.xpath("#{RESPONSE_XPATH}/getAttachmentsFromIssueReturn").map {
    |frag| JIRA::AttachmentMetadata.new_with_xml frag
  }
end

#get_comment_with_id(id) ⇒ JIRA::Comment

Parameters:

  • id (String)

Returns:



417
418
419
420
421
422
423
 
# File 'lib/jiraSOAP/api.rb', line 417

def get_comment_with_id(id)
  response = invoke('soap:getComment') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', id
  }
  JIRA::Comment.new_with_xml response.document.xpath('//getCommentReturn').first
end

#get_comments_for_issue_with_key(issue_key) ⇒ [JIRA::Comment]

Parameters:

  • issue_key (String)

Returns:



427
428
429
430
431
432
433
434
435
 
# File 'lib/jiraSOAP/api.rb', line 427

def get_comments_for_issue_with_key(issue_key)
  response = invoke('soap:getComments') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', issue_key
  }
  response.document.xpath("#{RESPONSE_XPATH}/getCommentsReturn").map {
    |frag| JIRA::Comment.new_with_xml frag
  }
end

#get_custom_fields ⇒ [JIRA::Field]

Returns:



64
65
66
67
68
69
70
71
 
# File 'lib/jiraSOAP/api.rb', line 64

def get_custom_fields
  response = invoke('soap:getCustomFields') { |msg|
    msg.add 'soap:in0', @auth_token
  }
  response.document.xpath("#{RESPONSE_XPATH}/getCustomFieldsReturn").map {
    |frag| JIRA::Field.new_with_xml frag
  }
end

#get_favourite_filters ⇒ [JIRA::Filter]

Retrieves favourite filters for the currently logged in user.

Returns:



494
495
496
497
498
499
500
501
 
# File 'lib/jiraSOAP/api.rb', line 494

def get_favourite_filters
  response = invoke('soap:getFavouriteFilters') { |msg|
    msg.add 'soap:in0', @auth_token
  }
  response.document.xpath("#{RESPONSE_XPATH}/getFavouriteFiltersReturn").map {
    |frag| JIRA::Filter.new_with_xml frag
  }
end

#get_issue_count_for_filter_with_id(id) ⇒ Fixnum

Parameters:

  • id (String)

Returns:

  • (Fixnum) 


521
522
523
524
525
526
527
 
# File 'lib/jiraSOAP/api.rb', line 521

def get_issue_count_for_filter_with_id(id)
  response = invoke('soap:getIssueCountForFilter') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', id
  }
  response.document.xpath('//getIssueCountForFilterReturn').to_i
end

#get_issue_types ⇒ [JIRA::IssueType]

Returns:



74
75
76
77
78
79
80
81
 
# File 'lib/jiraSOAP/api.rb', line 74

def get_issue_types
  response = invoke('soap:getIssueTypes') { |msg|
    msg.add 'soap:in0', @auth_token
  }
  response.document.xpath("#{RESPONSE_XPATH}/getIssueTypesReturn").map {
    |frag| JIRA::IssueType.new_with_xml frag
  }
end

#get_issue_types_for_project_with_id(project_id) ⇒ [JIRA::IssueType]

Parameters:

  • project_name (String)

Returns:



439
440
441
442
443
444
445
446
447
 
# File 'lib/jiraSOAP/api.rb', line 439

def get_issue_types_for_project_with_id(project_id)
  response = invoke('soap:getIssueTypesForProject') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', project_id
  }
  response.document.xpath("#{RESPONSE_XPATH}/getIssueTypesForProjectReturn").map {
    |frag| JIRA::IssueType.new_with_xml frag
  }
end

#get_issue_with_id(issue_id) ⇒ JIRA::Issue

Parameters:

  • issue_id (String)

Returns:



254
255
256
257
258
259
260
 
# File 'lib/jiraSOAP/api.rb', line 254

def get_issue_with_id(issue_id)
  response = invoke('soap:getIssueById') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', issue_id
  }
  JIRA::Issue.new_with_xml response.document.xpath('//getIssueByIdReturn').first
end

#get_issue_with_key(issue_key) ⇒ JIRA::Issue

Parameters:

  • issue_key (String)

Returns:



244
245
246
247
248
249
250
 
# File 'lib/jiraSOAP/api.rb', line 244

def get_issue_with_key(issue_key)
  response = invoke('soap:getIssue') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', issue_key
  }
  JIRA::Issue.new_with_xml response.document.xpath('//getIssueReturn').first
end

#get_issues_from_filter_with_id(id, max_results = 500, offset = 0) ⇒ [JIRA::Issue]

Parameters:

  • id (String)
  • max_results (Fixnum) (defaults to: 500)
  • offset (Fixnum) (defaults to: 0)

Returns:



507
508
509
510
511
512
513
514
515
516
517
 
# File 'lib/jiraSOAP/api.rb', line 507

def get_issues_from_filter_with_id(id, max_results = 500, offset = 0)
  response = invoke('soap:getIssuesFromFilterWithLimit') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', id
    msg.add 'soap:in2', offset
    msg.add 'soap:in3', max_results
  }
  response.document.xpath("#{RESPONSE_XPATH}/getIssuesFromFilterWithLimitReturn").map {
    |frag| JIRA::Issue.new_with_xml frag
  }
end

#get_issues_from_jql_search(jql_query, max_results = 2000) ⇒ [JIRA::Issue]

This method is the equivalent of making an advanced search from the web interface.

During my own testing, I found that HTTP requests could timeout for really large requests (~2500 results). So I set a more reasonable upper limit; feel free to override it, but be aware of the potential issues.

The JIRA::Issue structure does not include any comments or attachments.

Parameters:

  • jql_query (String) —

    JQL query as a string

  • max_results (Fixnum) (defaults to: 2000) —

    limit on number of returned results; the value may be overridden by the server if max_results is too large

Returns:



178
179
180
181
182
183
184
185
186
187
 
# File 'lib/jiraSOAP/api.rb', line 178

def get_issues_from_jql_search(jql_query, max_results = 2000)
  response = invoke('soap:getIssuesFromJqlSearch') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', jql_query
    msg.add 'soap:in2', max_results
  }
  response.document.xpath("#{RESPONSE_XPATH}/getIssuesFromJqlSearchReturn").map {
    |frag| JIRA::Issue.new_with_xml frag
  }
end

#get_notification_schemes ⇒ [JIRA::NotificationScheme]

Returns:



94
95
96
97
98
99
100
101
 
# File 'lib/jiraSOAP/api.rb', line 94

def get_notification_schemes
  response = invoke('soap:getNotificationSchemes') { |msg|
    msg.add 'soap:in0', @auth_token
  }
  response.document.xpath("#{RESPONSE_XPATH}/getNotificationSchemesReturn").map {
    |frag| JIRA::NotificationScheme.new_with_xml frag
  }
end

#get_priorities ⇒ [JIRA::Priority]

Returns:



44
45
46
47
48
49
50
51
 
# File 'lib/jiraSOAP/api.rb', line 44

def get_priorities
  response = invoke('soap:getPriorities') { |msg|
    msg.add 'soap:in0', @auth_token
  }
  response.document.xpath("#{RESPONSE_XPATH}/getPrioritiesReturn").map {
    |frag| JIRA::Priority.new_with_xml frag
  }
end

#get_project_avatar_for_key(project_key) ⇒ JIRA::Avatar

Gets you the default avatar image for a project; if you want all the avatars for a project, use #get_project_avatars_for_key.

Parameters:

  • project_key (String)

Returns:



142
143
144
145
146
147
148
 
# File 'lib/jiraSOAP/api.rb', line 142

def get_project_avatar_for_key(project_key)
  response = invoke('soap:getProjectAvatar') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', project_key
  }
  JIRA::Avatar.new_with_xml response.document.xpath('//getProjectAvatarReturn').first
end

#get_project_avatars_for_key(project_key, include_default_avatars = false) ⇒ [JIRA::Avatar]

Gets ALL avatars for a given project with this method; if you just want the project avatar, use #get_project_avatar_for_key.

Parameters:

  • project_key (String)
  • include_default_avatars (true, false) (defaults to: false)

Returns:



155
156
157
158
159
160
161
162
163
164
 
# File 'lib/jiraSOAP/api.rb', line 155

def get_project_avatars_for_key(project_key, include_default_avatars = false)
  response = invoke('soap:getProjectAvatars') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', project_key
    msg.add 'soap:in2', include_default_avatars
  }
  response.document.xpath("#{RESPONSE_XPATH}/getProjectAvatarsReturn").map {
    |frag| JIRA::Avatar.new_with_xml frag
  }
end

#get_project_including_schemes_with_id(project_id) ⇒ JIRA::Project

TODO:

parse the permission scheme

Note: this method does not yet include the permission scheme.

Parameters:

  • project_id (String)

Returns:



395
396
397
398
399
400
401
 
# File 'lib/jiraSOAP/api.rb', line 395

def get_project_including_schemes_with_id(project_id)
  response = invoke('soap:getProjectWithSchemesById') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', project_id
  }
  JIRA::Project.new_with_xml response.document.xpath('//getProjectWithSchemesByIdReturn').first
end

#get_project_role_with_id(role_id) ⇒ JIRA::ProjectRole

Parameters:

  • role_id (#to_s)

Returns:



672
673
674
675
676
677
678
 
# File 'lib/jiraSOAP/api.rb', line 672

def get_project_role_with_id role_id
  response = invoke('soap:getProjectRole') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', role_id
  }
  JIRA::ProjectRole.new_with_xml response.document.xpath('//getProjectRoleReturn').first
end

#get_project_roles ⇒ [JIRA::ProjectRole]

Returns:



661
662
663
664
665
666
667
668
 
# File 'lib/jiraSOAP/api.rb', line 661

def get_project_roles
  response = invoke('soap:getProjectRoles') { |msg|
    msg.add 'soap:in0', @auth_token
  }
  response.document.xpath("#{RESPONSE_XPATH}/getProjectRolesReturn").map {
    |frag| JIRA::ProjectRole.new_with_xml frag
  }
end

#get_project_with_id(project_id) ⇒ JIRA::Project

Parameters:

  • project_id (String)

Returns:



383
384
385
386
387
388
389
 
# File 'lib/jiraSOAP/api.rb', line 383

def get_project_with_id(project_id)
  response = invoke('soap:getProjectById') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', project_id
  }
  JIRA::Project.new_with_xml response.document.xpath('//getProjectByIdReturn').first
end

#get_project_with_key(project_key) ⇒ JIRA::Project

You need to explicitly ask for schemes in order to get them. By default, most project fetching methods purposely leave out all the scheme information as permission schemes can be very large.

Parameters:

  • project_key (String)

Returns:



120
121
122
123
124
125
126
 
# File 'lib/jiraSOAP/api.rb', line 120

def get_project_with_key(project_key)
  response = invoke('soap:getProjectByKey') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', project_key
  }
  JIRA::Project.new_with_xml response.document.xpath('//getProjectByKeyReturn').first
end

#get_projects_without_schemes ⇒ [JIRA::Project]

Note:

This will not fill in JIRA::Scheme data for the projects.

Returns:



568
569
570
571
572
573
574
575
 
# File 'lib/jiraSOAP/api.rb', line 568

def get_projects_without_schemes
  response = invoke('soap:getProjectsNoSchemes') { |msg|
    msg.add 'soap:in0', @auth_token
  }
  response.document.xpath("#{RESPONSE_XPATH}/getProjectsNoSchemesReturn").map {
    |frag| JIRA::Project.new_with_xml frag
  }
end

#get_resolution_date_for_issue_with_id(issue_id) ⇒ Time

Parameters:

  • issue_id (#to_s)

Returns:

  • (Time) 


579
580
581
582
583
584
585
 
# File 'lib/jiraSOAP/api.rb', line 579

def get_resolution_date_for_issue_with_id issue_id
  response = invoke('soap:getResolutionDateById') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', issue_id
  }
  response.document.xpath('//getResolutionDateByIdReturn').to_date
end

#get_resolution_date_for_issue_with_key(issue_key) ⇒ Time

Parameters:

  • issue_key (String)

Returns:

  • (Time) 


589
590
591
592
593
594
595
 
# File 'lib/jiraSOAP/api.rb', line 589

def get_resolution_date_for_issue_with_key issue_key
  response = invoke('soap:getResolutionDateByKey') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', issue_key
  }
  response.document.xpath('//getResolutionDateByKeyReturn').to_date
end

#get_resolutions ⇒ [JIRA::Resolution]

Returns:



54
55
56
57
58
59
60
61
 
# File 'lib/jiraSOAP/api.rb', line 54

def get_resolutions
  response = invoke('soap:getResolutions') { |msg|
    msg.add 'soap:in0', @auth_token
  }
  response.document.xpath("#{RESPONSE_XPATH}/getResolutionsReturn").map {
    |frag| JIRA::Resolution.new_with_xml frag
  }
end

#get_server_configuration ⇒ JIRA::ServerConfiguration

Returns:



559
560
561
562
563
564
 
# File 'lib/jiraSOAP/api.rb', line 559

def get_server_configuration
  response = invoke('soap:getConfiguration') { |msg|
    msg.add 'soap:in0', @auth_token
  }
  JIRA::ServerConfiguration.new_with_xml response.document.xpath('//getConfigurationReturn').first
end

#get_server_info ⇒ JIRA::ServerInfo

The @build_date attribute is a Time value, but does not include a time.

Returns:



551
552
553
554
555
556
 
# File 'lib/jiraSOAP/api.rb', line 551

def get_server_info
  response = invoke('soap:getServerInfo') { |msg|
    msg.add 'soap:in0', @auth_token
  }
  JIRA::ServerInfo.new_with_xml response.document.xpath('//getServerInfoReturn').first
end

#get_statuses ⇒ [JIRA::Status]

Returns:



84
85
86
87
88
89
90
91
 
# File 'lib/jiraSOAP/api.rb', line 84

def get_statuses
  response = invoke('soap:getStatuses') { |msg|
    msg.add 'soap:in0', @auth_token
  }
  response.document.xpath("#{RESPONSE_XPATH}/getStatusesReturn").map {
    |frag| JIRA::Status.new_with_xml frag
  }
end

#get_subtask_issue_types ⇒ [JIRA::IssueType]

Returns:



461
462
463
464
465
466
467
468
 
# File 'lib/jiraSOAP/api.rb', line 461

def get_subtask_issue_types
  response = invoke('soap:getSubTaskIssueTypes') { |msg|
    msg.add 'soap:in0', @auth_token
  }
  response.document.xpath("#{RESPONSE_XPATH}/getSubTaskIssueTypesReturn").map {
    |frag| JIRA::IssueType.new_with_xml frag
  }
end

#get_subtask_issue_types_for_project_with_id(project_id) ⇒ [JIRA::IssueType]

Parameters:

  • project_id (String)

Returns:



472
473
474
475
476
477
478
479
480
 
# File 'lib/jiraSOAP/api.rb', line 472

def get_subtask_issue_types_for_project_with_id(project_id)
  response = invoke('soap:getSubTaskIssueTypesForProject') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', project_id
  }
  response.document.xpath("#{RESPONSE_XPATH}/getSubtaskIssueTypesForProjectReturn").map {
    |frag| JIRA::IssueType.new_with_xml frag
  }
end

#get_user_with_name(user_name) ⇒ JIRA::User

Parameters:

  • user_name (String)

Returns:



130
131
132
133
134
135
136
 
# File 'lib/jiraSOAP/api.rb', line 130

def get_user_with_name(user_name)
  response = invoke('soap:getUser') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', user_name
  }
  JIRA::User.new_with_xml response.document.xpath('//getUserReturn').first
end

#get_versions_for_project(project_key) ⇒ [JIRA::Version]

Parameters:

  • project_key (String)

Returns:



105
106
107
108
109
110
111
112
113
 
# File 'lib/jiraSOAP/api.rb', line 105

def get_versions_for_project(project_key)
  response = invoke('soap:getVersions') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', project_key
  }
  response.document.xpath("#{RESPONSE_XPATH}/getVersionsReturn").map {
    |frag| JIRA::Version.new_with_xml frag
  }
end

#login(user, password) ⇒ true

The first method to call; other methods will fail until you are logged in.

Parameters:

  • user (String) —

    JIRA user name to login with

  • password (String)

Returns:

  • (true) 


22
23
24
25
26
27
28
29
30
31
 
# File 'lib/jiraSOAP/api.rb', line 22

def (user, password)
  response = invoke('soap:login') { |msg|
    msg.add 'soap:in0', user
    msg.add 'soap:in1', password
  }
  # cache now that we know it is safe to do so
  @user       = user
  @auth_token = response.document.xpath('//loginReturn').first.to_s
  true
end

#logout ⇒ true, false

You only need to call this to make an explicit logout; normally, a session will automatically expire after a set time (configured on the server).

Returns:

  • (true, false) —

    true if successful, otherwise false



36
37
38
39
40
41
 
# File 'lib/jiraSOAP/api.rb', line 36

def logout
  response = invoke('soap:logout') { |msg|
    msg.add 'soap:in0', @auth_token
  }
  response.document.xpath('//logoutReturn').to_boolean
end

#project_role_name_unique?(project_role_name) ⇒ true, false

Note:

JIRA 4.0 returns an exception if the name already exists

Returns true if the name does not exist.

Parameters:

  • project_role_name (String)

Returns:

  • (true, false) 


694
695
696
697
698
699
700
 
# File 'lib/jiraSOAP/api.rb', line 694

def project_role_name_unique? project_role_name
  response = invoke('soap:isProjectRoleNameUnique') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', project_role_name
  }
  response.document.xpath('//isProjectRoleNameUniqueReturn').to_boolean
end

#refresh_custom_fields ⇒ true

TODO:

find out what this method does

I have no idea what this method does.

Returns:

  • (true) 


485
486
487
488
489
490
 
# File 'lib/jiraSOAP/api.rb', line 485

def refresh_custom_fields
  invoke('soap:refreshCustomFields') { |msg|
    msg.add 'soap:in0', @auth_token
  }
  true
end

#release_state_for_version_for_project(project_name, version) ⇒ true

You can set the release state for a project with this method.

Parameters:

Returns:

  • (true) 


329
330
331
332
333
334
335
336
 
# File 'lib/jiraSOAP/api.rb', line 329

def release_state_for_version_for_project(project_name, version)
  invoke('soap:releaseVersion') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', project_name
    msg.add 'soap:in2' do |submsg| version.soapify_for submsg end
  }
  true
end

#set_archive_state_for_version_for_project(project_key, version_name, state) ⇒ true

The archive state can only be set to true for versions that have not been released. However, this is not reflected by the return value of this method.

Parameters:

  • project_key (String)
  • version_name (String)
  • state (true, false)

Returns:

  • (true) 


301
302
303
304
305
306
307
308
309
 
# File 'lib/jiraSOAP/api.rb', line 301

def set_archive_state_for_version_for_project(project_key, version_name, state)
  invoke('soap:archiveVersion') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', project_key
    msg.add 'soap:in2', version_name
    msg.add 'soap:in3', state
  }
  true
end

#set_new_project_avatar_for_project_with_key(project_key, mime_type, base64_image) ⇒ true

Note:

You need project administration permissions to edit an avatar

Use this method to create a new custom avatar for a project and set it to be current avatar for the project.

The image, provided as base64 encoded data, should be a 48x48 pixel square. If the image is larger, the top left 48 pixels are taken, if it is smaller then it will be upscaled to 48 pixels. The small version of the avatar image (16 pixels) is generated automatically. If you want to switch a project avatar to an avatar that already exists on the system then use #set_project_avatar_for_project_with_key instead.

Parameters:

  • project_key (String)
  • mime_type (String)
  • base64_image (#to_s)

Returns:

  • (true) 


650
651
652
653
654
655
656
657
658
 
# File 'lib/jiraSOAP/api.rb', line 650

def set_new_project_avatar_for_project_with_key project_key, mime_type, base64_image
  invoke('soap:setNewProjectAvatar') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', project_key
    msg.add 'soap:in2', mime_type
    msg.add 'soap:in3', base64_image
  }
  true
end

#set_project_avatar_for_project_with_key(project_key, avatar_id) ⇒ true

Note:

You need project administration permissions to edit an avatar

Note:

JIRA does not care if the avatar_id is valid

Change the project avatar to another existing avatar. If you want to upload a new avatar and set it to be the new project avatar use #set_new_project_avatar instead.

Returns:

  • (true) 


626
627
628
629
630
631
632
633
 
# File 'lib/jiraSOAP/api.rb', line 626

def set_project_avatar_for_project_with_key project_key, avatar_id
  invoke('soap:setProjectAvatar') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', project_key
    msg.add 'soap:in2', avatar_id
  }
  true
end

#update_comment(comment) ⇒ JIRA::Comment

Parameters:

Returns:



451
452
453
454
455
456
457
458
 
# File 'lib/jiraSOAP/api.rb', line 451

def update_comment(comment)
  response = invoke('soap:editComment') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1' do |submsg| comment.soapify_for submsg end
  }
  frag = response.document.xpath('//editCommentReturn').first
  JIRA::Comment.new_with_xml frag
end

#update_issue(issue_key, *field_values) ⇒ JIRA::Issue

This method can update most, but not all, issue fields. Some limitations are because of how the API is designed, and some are because I have not yet implemented the ability to update fields made of custom objects (things in the JIRA module).

Fields known to not update via this method:

- status - use {#progress_workflow_action}
- attachments - use {#add_base64_encoded_attachments_to_issue_with_key}

Though JIRA::FieldValue objects have an id field, they do not expect to be given id values. You must use the name of the field you wish to update.

Examples:

Usage With A Normal Field

summary        = JIRA::FieldValue.new 'summary', ['My new summary']

Usage With A Custom Field

custom_field        = JIRA::FieldValue.new 'customfield_10060', ['123456']

Setting a field to be blank/nil

description = JIRA::FieldValue.new 'description'

Calling the method to update an issue

jira_service_instance.update_issue 'PROJECT-1', description, custom_field

Parameters:

Returns:



211
212
213
214
215
216
217
218
219
220
 
# File 'lib/jiraSOAP/api.rb', line 211

def update_issue(issue_key, *field_values)
  response = invoke('soap:updateIssue') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1', issue_key
    msg.add 'soap:in2'  do |submsg|
      field_values.each { |fv| fv.soapify_for submsg }
    end
  }
  JIRA::Issue.new_with_xml response.document.xpath('//updateIssueReturn').first
end

#update_project_role_with_role(project_role) ⇒ JIRA::ProjectRole

Note:

JIRA 4.0 will not update project roles, it will instead throw an exception telling you that the project role already exists

Returns the role after the update.

Parameters:

Returns:



719
720
721
722
723
724
725
 
# File 'lib/jiraSOAP/api.rb', line 719

def update_project_role_with_role project_role
  response = invoke('soap:updateProjectRole') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1' do |submsg| project_role.soapify_for submsg end
  }
  JIRA::ProjectRole.new_with_xml response.document.xpath('//updateProjectRoleReturn').first
end

#update_project_with_project(project) ⇒ JIRA::Project

The id of the project is the only field that you cannot update. Or, at least the only field I know that you cannot update.

Parameters:

Returns:



342
343
344
345
346
347
348
 
# File 'lib/jiraSOAP/api.rb', line 342

def update_project_with_project(project)
  response = invoke('soap:updateProject') { |msg|
    msg.add 'soap:in0', @auth_token
    msg.add 'soap:in1' do |submsg| project.soapify_for submsg end
  }
  JIRA::Project.new_with_xml response.document.xpath('//updateProjectReturn').first
end