Module: JIRA::RemoteAPI

Included in:
JIRAService
Defined in:
lib/jiraSOAP/api.rb,
lib/jiraSOAP/api/users.rb,
lib/jiraSOAP/api/issues.rb,
lib/jiraSOAP/api/avatars.rb,
lib/jiraSOAP/api/filters.rb,
lib/jiraSOAP/api/schemes.rb,
lib/jiraSOAP/api/worklog.rb,
lib/jiraSOAP/api/comments.rb,
lib/jiraSOAP/api/projects.rb,
lib/jiraSOAP/api/versions.rb,
lib/jiraSOAP/api/components.rb,
lib/jiraSOAP/api/attachments.rb,
lib/jiraSOAP/api/server_info.rb,
lib/jiraSOAP/api/project_roles.rb,
lib/jiraSOAP/api/issue_data_types.rb

Overview

Contains the API defined by Atlassian for the JIRA SOAP service.

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, default values, varargs, etc..

Logging in/out collapse

Users collapse

Issues collapse

Avatars collapse

Filters collapse

Schemes collapse

Worklogs collapse

Comments collapse

Projects collapse

Versions collapse

Components collapse

Attachments collapse

Server Information collapse

Project Roles collapse

Issue attributes collapse

Instance Method Details

#add_attachments_to_issue_with_key(issue_key, *attachments) ⇒ Boolean

Note:

Expect this method to be slow.

Uploads attachments to an issue using the addBase64EncodedAttachmentsToIssue SOAP method.

The metadata is not automatically refreshed by this method. To get the updated metadata (e.g., file_size and content_type), call #attachments_for_issue_with_key.

Parameters:

  • issue_key (String)
  • attachments (JIRA::Attachment) —

    files to be uploaded; their content attributes should populated with the data

Returns:

  • (Boolean) —

    true if successful



35
36
37
38
39
40
41
42
43
44
45
46
47
 
# File 'lib/jiraSOAP/api/attachments.rb', line 35

def add_attachments_to_issue_with_key issue_key, *attachments
  invoke('soap:addBase64EncodedAttachmentsToIssue') { |msg|
    msg.add 'soap:in0', self.auth_token
    msg.add 'soap:in1', issue_key
    msg.add 'soap:in2' do |submsg|
      attachments.each { |attachment| submsg.add 'filenames', attachment.filename }
    end
    msg.add 'soap:in3' do |submsg|
      attachments.each { |attachment| submsg.add 'base64EncodedData', [attachment.content].pack('m0') }
    end
  }
  true
end

#add_base64_encoded_attachments_to_issue_with_key(issue_key, filenames, data) ⇒ Boolean

Deprecated.

This will be removed in the next release (either 0.11 or 1.0)

(see #add_attachments_to_issue_with_key)

Parameters:

  • issue_key (String)
  • filenames (Array<String>) —

    array of names for attachments

  • data (Array<String>) —

    base64 encoded data for upload

Returns:

  • (Boolean) —

    true if successful, otherwise an exception is raised



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/jiraSOAP/api/attachments.rb', line 58

def add_base64_encoded_attachments_to_issue_with_key issue_key, filenames, data
  $stderr.puts <<-EOM
RemoteAPI#add_base64_encoded_attachments_to_issue_with_key is deprecated and will be removed in the next release.
Please use RemoteAPI#add_attachments_to_issue_with_key instead.
  EOM

  invoke('soap:addBase64EncodedAttachmentsToIssue') { |msg|
    msg.add 'soap:in0', self.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) ⇒ Boolean

Returns true if successful.

Parameters:

Returns:

  • (Boolean) —

    true if successful



8
9
10
11
 
# File 'lib/jiraSOAP/api/comments.rb', line 8

def add_comment_to_issue_with_key issue_key, comment
  jira_call 'addComment', issue_key, comment
  true
end

#add_user_to_group(group, user) ⇒ Boolean

Returns true if successful.

Parameters:

Returns:

  • (Boolean) —

    true if successful



45
46
47
48
 
# File 'lib/jiraSOAP/api/users.rb', line 45

def add_user_to_group group, user
  jira_call 'addUserToGroup', group, user
  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:



25
26
27
 
# File 'lib/jiraSOAP/api/versions.rb', line 25

def add_version_to_project_with_key project_key, version
  JIRA::Version.new_with_xml jira_call( 'addVersion', project_key, version )
end

#add_worklog_and_auto_adjust_remaining_estimate(issue_key, worklog) ⇒ Object

Adds a worklog to the given issue.

Parameters:



10
11
12
 
# File 'lib/jiraSOAP/api/worklog.rb', line 10

def add_worklog_and_auto_adjust_remaining_estimate issue_key, worklog
  JIRA::Worklog.new_with_xml jira_call( 'addWorklogAndAutoAdjustRemainingEstimate', issue_key, worklog )
end

#attachments_for_issue_with_key(issue_key) ⇒ Array<JIRA::Attachment>

TODO:

change method name to reflect that you only get metadata

Parameters:

  • issue_key (String)

Returns:



17
18
19
 
# File 'lib/jiraSOAP/api/attachments.rb', line 17

def attachments_for_issue_with_key issue_key
  array_jira_call JIRA::Attachment, 'getAttachmentsFromIssue', issue_key
end

#available_actions(issue_key) ⇒ Array<JIRA::NamedEntity>

Returns workflow actions available for an issue.

Parameters:

  • issue_key (String)

Returns:



166
167
168
 
# File 'lib/jiraSOAP/api/issues.rb', line 166

def available_actions issue_key
  array_jira_call JIRA::NamedEntity, 'getAvailableActions', issue_key
end

#comment_with_id(id) ⇒ JIRA::Comment

Parameters:

  • id (String)

Returns:



15
16
17
 
# File 'lib/jiraSOAP/api/comments.rb', line 15

def comment_with_id id
  JIRA::Comment.new_with_xml jira_call( 'getComment', id )
end

#comments_for_issue_with_key(issue_key) ⇒ Array<JIRA::Comment>

Parameters:

  • issue_key (String)

Returns:



21
22
23
 
# File 'lib/jiraSOAP/api/comments.rb', line 21

def comments_for_issue_with_key issue_key
  array_jira_call JIRA::Comment, 'getComments', issue_key
end

#components_for_project_with_key(project_key) ⇒ Array<JIRA::Component>

Lists a project's components

Parameters:

  • project_key (String)

Returns:



9
10
11
 
# File 'lib/jiraSOAP/api/components.rb', line 9

def components_for_project_with_key project_key
  array_jira_call JIRA::Component, 'getComponents', project_key
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:



100
101
102
 
# File 'lib/jiraSOAP/api/issues.rb', line 100

def create_issue_with_issue issue
  JIRA::Issue.new_with_xml jira_call( 'createIssue', issue )
end

#create_issue_with_issue_and_parent(issue, parent_id) ⇒ JIRA:Issue Also known as: create_issue_with_parent

Parameters:

Returns:

  • (JIRA:Issue) 


107
108
109
 
# File 'lib/jiraSOAP/api/issues.rb', line 107

def create_issue_with_issue_and_parent issue, parent_id
  JIRA::Issue.new_with_xml jira_call('createIssueWithParent', issue, parent_id)
end

#create_project_role_with_role(project_role) ⇒ JIRA::ProjectRole

Returns the role that was created.

Parameters:

Returns:



18
19
20
 
# File 'lib/jiraSOAP/api/project_roles.rb', line 18

def create_project_role_with_role project_role
  JIRA::ProjectRole.new_with_xml jira_call( 'createProjectRole', project_role )
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:



49
50
51
 
# File 'lib/jiraSOAP/api/projects.rb', line 49

def create_project_with_project project
  JIRA::Project.new_with_xml jira_call( 'createProjectFromObject', project )
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 anything



23
24
25
26
 
# File 'lib/jiraSOAP/api/users.rb', line 23

def create_user username, password, full_name, email
  fragment = jira_call( 'createUser', username, password, full_name, email )
  JIRA::User.new_with_xml fragment
end

#create_user_group(group_name, user = nil) ⇒ JIRA::UserGroup

Create a new user group. You can initialize the group with a user if you wish.

Parameters:

  • group_name (String)
  • user (JIRA::User) (defaults to: nil)

Returns:



65
66
67
68
 
# File 'lib/jiraSOAP/api/users.rb', line 65

def create_user_group group_name, user = nil
  frag = jira_call 'createGroup', group_name, user
  JIRA::UserGroup.new_with_xml frag
end

#custom_fields ⇒ Array<JIRA::Field>

Returns:



16
17
18
 
# File 'lib/jiraSOAP/api/issue_data_types.rb', line 16

def custom_fields
  array_jira_call JIRA::Field, 'getCustomFields'
end

#delete_project_avatar_with_id(avatar_id) ⇒ Boolean

Note:

You cannot delete system avatars, and you need project administration permissions to delete other avatars.

Returns true if successful.

Parameters:

  • avatar_id (String)

Returns:

  • (Boolean) —

    true if successful



32
33
34
35
 
# File 'lib/jiraSOAP/api/avatars.rb', line 32

def delete_project_avatar_with_id avatar_id
  jira_call 'deleteProjectAvatar', avatar_id
  true
end

#delete_project_role(project_role, confirm = true) ⇒ Boolean

Note:

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

Returns true if successful.

Parameters:

Returns:

  • (Boolean) —

    true if successful



39
40
41
42
 
# File 'lib/jiraSOAP/api/project_roles.rb', line 39

def delete_project_role project_role, confirm = true
  jira_call 'deleteProjectRole', project_role, confirm
  true
end

#delete_project_with_key(project_key) ⇒ Boolean

Returns true if successful.

Parameters:

  • project_key (String)

Returns:

  • (Boolean) —

    true if successful



65
66
67
68
 
# File 'lib/jiraSOAP/api/projects.rb', line 65

def delete_project_with_key project_key
  jira_call 'deleteProject', project_key
  true
end

#delete_user_group(group_name, swap_group) ⇒ Boolean

TODO:

Find out the semantics of swap_group

Returns true if successful.

Parameters:

  • group_name (String)
  • swap_group (String)

Returns:

  • (Boolean) —

    true if successful



76
77
78
79
 
# File 'lib/jiraSOAP/api/users.rb', line 76

def delete_user_group group_name, swap_group
  jira_call 'deleteGroup', group_name, swap_group
  true
end

#delete_user_with_name(username) ⇒ Boolean

Returns true if successful.

Parameters:

  • username (String)

Returns:

  • (Boolean) —

    true if successful



30
31
32
33
 
# File 'lib/jiraSOAP/api/users.rb', line 30

def delete_user_with_name username
  jira_call 'deleteUser', username
  true
end

#favourite_filters ⇒ Array<JIRA::Filter> Also known as: favorite_filters

Retrieves favourite filters for the currently logged in user.

Returns:



9
10
11
 
# File 'lib/jiraSOAP/api/filters.rb', line 9

def favourite_filters
  array_jira_call JIRA::Filter, 'getFavouriteFilters'
end

#group_with_name(group_name) ⇒ JIRA::UserGroup

Parameters:

  • group_name (String)

Returns:



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

def group_with_name group_name
  frag = jira_call 'getGroup', group_name
  JIRA::UserGroup.new_with_xml frag
end

#issue_count_for_filter_with_id(id) ⇒ Fixnum

Parameters:

  • id (String)

Returns:

  • (Fixnum) 


16
17
18
 
# File 'lib/jiraSOAP/api/filters.rb', line 16

def issue_count_for_filter_with_id id
  jira_call( 'getIssueCountForFilter', id ).to_i
end

#issue_types ⇒ Array<JIRA::IssueType>

Returns:



21
22
23
 
# File 'lib/jiraSOAP/api/issue_data_types.rb', line 21

def issue_types
  array_jira_call JIRA::IssueType, 'getIssueTypes'
end

#issue_types_for_project_with_id(project_id) ⇒ Array<JIRA::IssueType>

Parameters:

  • project_id (String)

Returns:



27
28
29
 
# File 'lib/jiraSOAP/api/issue_data_types.rb', line 27

def issue_types_for_project_with_id project_id
  array_jira_call JIRA::IssueType, 'getIssueTypesForProject', project_id
end

#issue_with_id(issue_id) ⇒ JIRA::Issue

Parameters:

  • issue_id (String)

Returns:



120
121
122
 
# File 'lib/jiraSOAP/api/issues.rb', line 120

def issue_with_id issue_id
  JIRA::Issue.new_with_xml jira_call( 'getIssueById', issue_id )
end

#issue_with_key(issue_key) ⇒ JIRA::Issue

Parameters:

  • issue_key (String)

Returns:



114
115
116
 
# File 'lib/jiraSOAP/api/issues.rb', line 114

def issue_with_key issue_key
  JIRA::Issue.new_with_xml jira_call( 'getIssue', issue_key )
end

#issues_from_filter_with_id(id, max_results = 500, offset = 0) ⇒ Array<JIRA::Issue>

Parameters:

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

Returns:



128
129
130
 
# File 'lib/jiraSOAP/api/issues.rb', line 128

def issues_from_filter_with_id id, max_results = 500, offset = 0
  array_jira_call JIRA::Issue, 'getIssuesFromFilterWithLimit', id, offset, max_results
end

#issues_from_jql_search(jql_query, max_results = 2000) ⇒ Array<JIRA::Issue>

Note:

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

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

The 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:



20
21
22
 
# File 'lib/jiraSOAP/api/issues.rb', line 20

def issues_from_jql_search jql_query, max_results = 2000
  array_jira_call JIRA::Issue, 'getIssuesFromJqlSearch', jql_query, max_results
end

#login(username, password) ⇒ String Also known as: log_in

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

Parameters:

  • username (String) —

    JIRA user name to login with

  • password (String)

Returns:

  • (String) —

    auth_token if successful, otherwise raises an exception



17
18
19
20
21
 
# File 'lib/jiraSOAP/api.rb', line 17

def  username, password
  response    = soap_call 'login', username, password
  @user       = username
  @auth_token = response.first.content
end

#logout ⇒ Boolean Also known as: log_out

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:

  • (Boolean) —

    true if successful, otherwise false



28
29
30
31
32
33
 
# File 'lib/jiraSOAP/api.rb', line 28

def logout
  jira_call( 'logout' ).to_boolean.tap do |_|
    @user       = nil
    @auth_token = nil
  end
end

#notification_schemes ⇒ Array<JIRA::NotificationScheme>

Returns:



6
7
8
 
# File 'lib/jiraSOAP/api/schemes.rb', line 6

def notification_schemes
  array_jira_call JIRA::NotificationScheme, 'getNotificationSchemes'
end

#permission_schemes ⇒ Array<JIRA::PermissionScheme>

Returns:



11
12
13
 
# File 'lib/jiraSOAP/api/schemes.rb', line 11

def permission_schemes
  array_jira_call JIRA::PermissionScheme, 'getPermissionSchemes'
end

#permission_to_edit_comment?(comment) ⇒ Boolean

Parameters:

Returns:

  • (Boolean) 


32
33
34
 
# File 'lib/jiraSOAP/api/comments.rb', line 32

def permission_to_edit_comment? comment
  jira_call( 'hasPermissionToEditComment', comment ).to_boolean
end

#priorities ⇒ Array<JIRA::Priority>

Returns:



6
7
8
 
# File 'lib/jiraSOAP/api/issue_data_types.rb', line 6

def priorities
  array_jira_call JIRA::Priority, 'getPriorities'
end

#progress_workflow_action(issue_key, action_id, *field_values) ⇒ JIRA::Issue

This method acts like #update_issue except that it also updates the status of the issue.

The action_id parameter comes from the id of an available action. Normally you will use this method in conjunction with #available_actions to decide which action to take.

Parameters:

  • issue_key (String)
  • action_id (String) —

    this is the id of workflow action

  • field_values (JIRA::FieldValue)

Returns:



156
157
158
159
 
# File 'lib/jiraSOAP/api/issues.rb', line 156

def progress_workflow_action issue_key, action_id, *field_values
  JIRA::Issue.new_with_xml jira_call('progressWorkflowAction',
                                     issue_key, action_id, field_values)
end

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

Parameters:

  • project_key (String)

Returns:



11
12
13
 
# File 'lib/jiraSOAP/api/avatars.rb', line 11

def project_avatar_for_key project_key
  JIRA::Avatar.new_with_xml jira_call('getProjectAvatar', project_key)
end

#project_avatars_for_key(project_key, include_default_avatars = false) ⇒ Array<JIRA::Avatar>

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

Parameters:

  • project_key (String)
  • include_default_avatars (Boolean) (defaults to: false)

Returns:



22
23
24
 
# File 'lib/jiraSOAP/api/avatars.rb', line 22

def project_avatars_for_key project_key, include_default_avatars = false
  array_jira_call JIRA::Avatar, 'getProjectAvatars', project_key, include_default_avatars
end

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



28
29
30
 
# File 'lib/jiraSOAP/api/projects.rb', line 28

def project_including_schemes_with_id project_id
  JIRA::Project.new_with_xml jira_call( 'getProjectWithSchemesById', project_id )
end

#project_role_name_unique?(project_role_name) ⇒ Boolean

Note:

JIRA 4.0 and 4.2 returns an exception if the name already exists

Returns true if the name does not exist.

Parameters:

  • project_role_name (String)

Returns:

  • (Boolean) —

    true if successful



29
30
31
 
# File 'lib/jiraSOAP/api/project_roles.rb', line 29

def project_role_name_unique? project_role_name
  jira_call( 'isProjectRoleNameUnique', project_role_name ).to_boolean
end

#project_role_with_id(role_id) ⇒ JIRA::ProjectRole

Parameters:

  • role_id (String)

Returns:



12
13
14
 
# File 'lib/jiraSOAP/api/project_roles.rb', line 12

def project_role_with_id role_id
  JIRA::ProjectRole.new_with_xml jira_call( 'getProjectRole', role_id )
end

#project_roles ⇒ Array<JIRA::ProjectRole>

Returns:



6
7
8
 
# File 'lib/jiraSOAP/api/project_roles.rb', line 6

def project_roles
  array_jira_call JIRA::ProjectRole, 'getProjectRoles'
end

#project_with_id(project_id) ⇒ JIRA::Project

Parameters:

  • project_id (String)

Returns:



18
19
20
 
# File 'lib/jiraSOAP/api/projects.rb', line 18

def project_with_id project_id
  JIRA::Project.new_with_xml jira_call( 'getProjectById', project_id )
end

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



12
13
14
 
# File 'lib/jiraSOAP/api/projects.rb', line 12

def project_with_key project_key
  JIRA::Project.new_with_xml jira_call( 'getProjectByKey', project_key )
end

#projects ⇒ Array<JIRA::Project> Also known as: projects_without_schemes

Note:

This will not fill in Scheme data for the projects.

Returns:



36
37
38
 
# File 'lib/jiraSOAP/api/projects.rb', line 36

def projects
  array_jira_call JIRA::Project, 'getProjectsNoSchemes'
end

#refresh_custom_fields ⇒ Boolean

TODO:

find out what this method does

I have no idea what this method does.

Returns:

  • (Boolean) —

    true if no exceptions were raised



53
54
55
56
 
# File 'lib/jiraSOAP/api/issue_data_types.rb', line 53

def refresh_custom_fields
  jira_call 'refreshCustomFields'
  true
end

#release_state_for_version_for_project(project_name, version) ⇒ Boolean

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

Parameters:

Returns:

  • (Boolean) —

    true if successful



48
49
50
51
 
# File 'lib/jiraSOAP/api/versions.rb', line 48

def release_state_for_version_for_project project_name, version
  jira_call 'releaseVersion', project_name, version
  true
end

#remove_user_from_group(group, user) ⇒ Boolean

Parameters:

Returns:

  • (Boolean) 


53
54
55
56
 
# File 'lib/jiraSOAP/api/users.rb', line 53

def remove_user_from_group group, user
  jira_call 'removeUserFromGroup', group, user
  true
end

#resolution_date_for_issue_with_id(issue_id) ⇒ Time

Parameters:

  • issue_id (String)

Returns:

  • (Time) 


134
135
136
 
# File 'lib/jiraSOAP/api/issues.rb', line 134

def resolution_date_for_issue_with_id issue_id
  jira_call( 'getResolutionDateById', issue_id ).to_iso_date
end

#resolution_date_for_issue_with_key(issue_key) ⇒ Time

Parameters:

  • issue_key (String)

Returns:

  • (Time) 


140
141
142
 
# File 'lib/jiraSOAP/api/issues.rb', line 140

def resolution_date_for_issue_with_key issue_key
  jira_call( 'getResolutionDateByKey', issue_key ).to_iso_date
end

#resolutions ⇒ Array<JIRA::Resolution>

Returns:



11
12
13
 
# File 'lib/jiraSOAP/api/issue_data_types.rb', line 11

def resolutions
  array_jira_call JIRA::Resolution, 'getResolutions'
end

#server_configuration ⇒ JIRA::ServerConfiguration

Returns:



14
15
16
 
# File 'lib/jiraSOAP/api/server_info.rb', line 14

def server_configuration
  JIRA::ServerConfiguration.new_with_xml jira_call( 'getConfiguration' )
end

#server_info ⇒ JIRA::ServerInfo

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

Returns:



9
10
11
 
# File 'lib/jiraSOAP/api/server_info.rb', line 9

def server_info
  JIRA::ServerInfo.new_with_xml jira_call( 'getServerInfo' )
end

#set_archive_state_for_version_for_project(project_key, version_name, state) ⇒ Boolean

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 (Boolean)

Returns:

  • (Boolean) —

    true if successful



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

def set_archive_state_for_version_for_project project_key, version_name, state
  jira_call 'archiveVersion', project_key, version_name, state
  true
end

#set_new_project_avatar_for_project_with_key(project_key, mime_type, base64_image) ⇒ Boolean

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 (String)

Returns:

  • (Boolean) —

    true if successful



70
71
72
73
 
# File 'lib/jiraSOAP/api/avatars.rb', line 70

def set_new_project_avatar_for_project_with_key project_key, mime_type, base64_image
  jira_call 'setNewProjectAvatar', project_key, mime_type, base64_image
  true
end

#set_project_avatar_for_project_with_key(project_key, avatar_id) ⇒ Boolean

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_for_project_with_key instead.

Returns:

  • (Boolean) —

    true if successful



46
47
48
49
 
# File 'lib/jiraSOAP/api/avatars.rb', line 46

def set_project_avatar_for_project_with_key project_key, avatar_id
  jira_call 'setProjectAvatar', project_key, avatar_id
  true
end

#statuses ⇒ Array<JIRA::Status>

Returns:



32
33
34
 
# File 'lib/jiraSOAP/api/issue_data_types.rb', line 32

def statuses
  array_jira_call JIRA::Status, 'getStatuses'
end

#subtask_issue_types ⇒ Array<JIRA::IssueType>

Returns:



37
38
39
 
# File 'lib/jiraSOAP/api/issue_data_types.rb', line 37

def subtask_issue_types
  array_jira_call JIRA::IssueType, 'getSubTaskIssueTypes'
end

#subtask_issue_types_for_project_with_id(project_id) ⇒ Array<JIRA::IssueType>

Parameters:

  • project_id (String)

Returns:



43
44
45
 
# File 'lib/jiraSOAP/api/issue_data_types.rb', line 43

def subtask_issue_types_for_project_with_id project_id
  array_jira_call JIRA::IssueType, 'getSubTaskIssueTypesForProject', project_id
end

#update_comment(comment) ⇒ JIRA::Comment

Parameters:

Returns:



27
28
29
 
# File 'lib/jiraSOAP/api/comments.rb', line 27

def update_comment comment
  JIRA::Comment.new_with_xml jira_call( 'editComment', comment )
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:

Though FieldValue objects have an id field, they do not expect to be given id values. You must use the camel cased name of the field you wish to update, such as 'fixVersions' to update the fix_versions for an issue.

However, there is at least one exception to the rule; when you wish to update the affected versions for an issue, you should use 'versions' instead of 'affectsVersions'. You need to be careful about these cases as it has been reported that JIRA will silently fail to update fields it does not know about.

Updating nested fields can be tricky, see the example on cascading select field's to see how it would be done.

A final note, some fields only should be passed the id in order to update them, as shown in the version updating example.

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.update_issue 'PROJECT-1', description, custom_field

Setting the value of a cascading select field


part1 = JIRA::FieldValue.new 'customfield_10285',   'Main Detail'
part2 = JIRA::FieldValue.new 'customfield_10285:1', 'First Subdetail'
jira.update_issue 'PROJECT-1', part1, part2

Changing the affected versions for an issue


version = jira.versions_for_project.find { |x| x.name = 'v1.0beta' }
field   = JIRA::FieldValue.new 'versions', version.id
jira.update_issue 'PROJECT-1', field

Parameters:

Returns:



83
84
85
 
# File 'lib/jiraSOAP/api/issues.rb', line 83

def update_issue issue_key, *field_values
  JIRA::Issue.new_with_xml jira_call('updateIssue', issue_key, field_values)
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:



50
51
52
 
# File 'lib/jiraSOAP/api/project_roles.rb', line 50

def update_project_role_with_role project_role
  JIRA::ProjectRole.new_with_xml jira_call( 'updateProjectRole', project_role )
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:



59
60
61
 
# File 'lib/jiraSOAP/api/projects.rb', line 59

def update_project_with_project project
  JIRA::Project.new_with_xml jira_call( 'updateProject', project )
end

#user_with_name(user_name) ⇒ JIRA::User

Parameters:

  • user_name (String)

Returns:



7
8
9
 
# File 'lib/jiraSOAP/api/users.rb', line 7

def user_with_name user_name
  JIRA::User.new_with_xml jira_call( 'getUser', user_name )
end

#versions_for_project(project_key) ⇒ Array<JIRA::Version>

Parameters:

  • project_key (String)

Returns:



7
8
9
 
# File 'lib/jiraSOAP/api/versions.rb', line 7

def versions_for_project project_key
  array_jira_call JIRA::Version, 'getVersions', project_key
end