Module: JIRA::RemoteAPI

Included in:
JIRAService
Defined in:
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/comments.rb,
lib/jiraSOAP/api/projects.rb,
lib/jiraSOAP/api/versions.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

Working with User data collapse

Working with Issues collapse

Working with Avatars collapse

Working with Filters collapse

Working with Schemes collapse

Working with Comments collapse

Working with Projects collapse

Working with Versions collapse

Working with issue Attachments and their metadata collapse

Getting information about the server collapse

Working with Project Roles collapse

Working with issue attributes collapse

Instance Method Details

#add_base64_encoded_attachments_to_issue_with_key(issue_key, filenames, data) ⇒ Boolean

Expect this method to be slow.

Parameters:

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

    names to put on the files

  • data (Array<String>) —

    base64 encoded data

Returns:

  • (Boolean) —

    true if successful



17
18
19
20
21
22
23
24
25
26
27
28
29
 
# File 'lib/jiraSOAP/api/attachments.rb', line 17

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) ⇒ 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
  call 'addComment', issue_key, comment
  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:



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

def add_version_to_project_with_key project_key, version
  JIRA::Version.new_with_xml call( 'addVersion', project_key, version ).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:



64
65
66
 
# File 'lib/jiraSOAP/api/issues.rb', line 64

def create_issue_with_issue issue
  JIRA::Issue.new_with_xml call( 'createIssue', issue ).first
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 call( 'createProjectRole', project_role ).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:



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

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



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

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

#delete_project_avatar_with_id(avatar_id) ⇒ Boolean

Note:

You cannot delete system avatars

Note:

You need project administration permissions to delete an avatar

Returns true if successful.

Parameters:

  • avatar_id (String)

Returns:

  • (Boolean) —

    true if successful



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

def delete_project_avatar_with_id avatar_id
  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



34
35
36
37
 
# File 'lib/jiraSOAP/api/project_roles.rb', line 34

def delete_project_role project_role, confirm = true
  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



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

def delete_project_with_key project_key
  call 'deleteProject', project_key
  true
end

#delete_user_with_name(username) ⇒ Boolean

Returns true if successful.

Parameters:

  • username (String)

Returns:

  • (Boolean) —

    true if successful



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

def delete_user_with_name username
  call 'deleteUser', username
  true
end

#get_attachments_for_issue_with_key(issue_key) ⇒ Array<JIRA::AttachmentMetadata>

TODO:

change method name to reflect that you only get metadata

Parameters:

  • issue_key (String)

Returns:



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

def get_attachments_for_issue_with_key issue_key
  jira_call JIRA::AttachmentMetadata, 'getAttachmentsFromIssue', issue_key
end

#get_comment_with_id(id) ⇒ JIRA::Comment

Parameters:

  • id (String)

Returns:



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

def get_comment_with_id id
  JIRA::Comment.new_with_xml call( 'getComment', id ).first
end

#get_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 get_comments_for_issue_with_key issue_key
  jira_call JIRA::Comment, 'getComments', issue_key
end

#get_custom_fields ⇒ Array<JIRA::Field>

Returns:



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

def get_custom_fields
  jira_call JIRA::Field, 'getCustomFields'
end

#get_favourite_filters ⇒ Array<JIRA::Filter> Also known as: get_favorite_filters

Retrieves favourite filters for the currently logged in user.

Returns:



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

def get_favourite_filters
  jira_call JIRA::Filter, 'getFavouriteFilters'
end

#get_issue_count_for_filter_with_id(id) ⇒ Fixnum

Parameters:

  • id (String)

Returns:

  • (Fixnum) 


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

def get_issue_count_for_filter_with_id id
  call( 'getIssueCountForFilter', id ).to_i
end

#get_issue_types ⇒ Array<JIRA::IssueType>

Returns:



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

def get_issue_types
  jira_call JIRA::IssueType, 'getIssueTypes'
end

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

Parameters:

  • project_name (String)

Returns:



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

def get_issue_types_for_project_with_id project_id
  jira_call JIRA::IssueType, 'getIssueTypesForProject', project_id
end

#get_issue_with_id(issue_id) ⇒ JIRA::Issue

Parameters:

  • issue_id (String)

Returns:



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

def get_issue_with_id issue_id
  JIRA::Issue.new_with_xml call( 'getIssueById', issue_id ).first
end

#get_issue_with_key(issue_key) ⇒ JIRA::Issue

Parameters:

  • issue_key (String)

Returns:



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

def get_issue_with_key issue_key
  JIRA::Issue.new_with_xml call( 'getIssue', issue_key ).first
end

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



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

def get_issues_from_filter_with_id id, max_results = 500, offset = 0
  jira_call JIRA::Issue, 'getIssuesFromFilterWithLimit', id, offset, max_results
end

#get_issues_from_jql_search(jql_query, max_results = 2000) ⇒ Array<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:



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

def get_issues_from_jql_search jql_query, max_results = 2000
  jira_call JIRA::Issue, 'getIssuesFromJqlSearch', jql_query, max_results
end

#get_notification_schemes ⇒ Array<JIRA::NotificationScheme>

Returns:



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

def get_notification_schemes
  jira_call JIRA::NotificationScheme, 'getNotificationSchemes'
end

#get_permission_schemes ⇒ Array<JIRA::PermissionScheme>

Returns:



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

def get_permission_schemes
  jira_call JIRA::PermissionScheme, 'getPermissionSchemes'
end

#get_priorities ⇒ Array<JIRA::Priority>

Returns:



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

def get_priorities
  jira_call JIRA::Priority, 'getPriorities'
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:



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

def get_project_avatar_for_key project_key
  JIRA::Avatar.new_with_xml call( 'getProjectAvatar', project_key ).first
end

#get_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 #get_project_avatar_for_key.

Parameters:

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

Returns:



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

def get_project_avatars_for_key project_key, include_default_avatars = false
  jira_call JIRA::Avatar, 'getProjectAvatars', project_key, include_default_avatars
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:



42
43
44
 
# File 'lib/jiraSOAP/api/projects.rb', line 42

def get_project_including_schemes_with_id project_id
  JIRA::Project.new_with_xml call( 'getProjectWithSchemesById', project_id ).first
end

#get_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 get_project_role_with_id role_id
  JIRA::ProjectRole.new_with_xml call( 'getProjectRole', role_id ).first
end

#get_project_roles ⇒ Array<JIRA::ProjectRole>

Returns:



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

def get_project_roles
  jira_call JIRA::ProjectRole, 'getProjectRoles'
end

#get_project_with_id(project_id) ⇒ JIRA::Project

Parameters:

  • project_id (String)

Returns:



34
35
36
 
# File 'lib/jiraSOAP/api/projects.rb', line 34

def get_project_with_id project_id
  JIRA::Project.new_with_xml call( 'getProjectById', project_id ).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:



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

def get_project_with_key project_key
  JIRA::Project.new_with_xml call( 'getProjectByKey', project_key ).first
end

#get_projects_without_schemes ⇒ Array<JIRA::Project>

Note:

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

Returns:



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

def get_projects_without_schemes
  jira_call JIRA::Project, 'getProjectsNoSchemes'
end

#get_resolution_date_for_issue_with_id(issue_id) ⇒ Time

Parameters:

  • issue_id (String)

Returns:

  • (Time) 


90
91
92
 
# File 'lib/jiraSOAP/api/issues.rb', line 90

def get_resolution_date_for_issue_with_id issue_id
  call( 'getResolutionDateById', issue_id ).to_date
end

#get_resolution_date_for_issue_with_key(issue_key) ⇒ Time

Parameters:

  • issue_key (String)

Returns:

  • (Time) 


96
97
98
 
# File 'lib/jiraSOAP/api/issues.rb', line 96

def get_resolution_date_for_issue_with_key issue_key
  call( 'getResolutionDateByKey', issue_key ).to_date
end

#get_resolutions ⇒ Array<JIRA::Resolution>

Returns:



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

def get_resolutions
  jira_call JIRA::Resolution, 'getResolutions'
end

#get_server_configuration ⇒ JIRA::ServerConfiguration

Returns:



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

def get_server_configuration
  JIRA::ServerConfiguration.new_with_xml call( 'getConfiguration' ).first
end

#get_server_info ⇒ JIRA::ServerInfo

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

Returns:



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

def get_server_info
  JIRA::ServerInfo.new_with_xml call( 'getServerInfo' ).first
end

#get_statuses ⇒ Array<JIRA::Status>

Returns:



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

def get_statuses
  jira_call JIRA::Status, 'getStatuses'
end

#get_subtask_issue_types ⇒ Array<JIRA::IssueType>

Returns:



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

def get_subtask_issue_types
  jira_call JIRA::IssueType, 'getSubTaskIssueTypes'
end

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

Parameters:

  • project_id (String)

Returns:



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

def get_subtask_issue_types_for_project_with_id project_id
  jira_call JIRA::IssueType, 'getSubTaskIssueTypesForProject', project_id
end

#get_user_with_name(user_name) ⇒ JIRA::User

Parameters:

  • user_name (String)

Returns:



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

def get_user_with_name user_name
  JIRA::User.new_with_xml call( 'getUser', user_name ).first
end

#get_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 get_versions_for_project project_key
  jira_call JIRA::Version, 'getVersions', project_key
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



26
27
28
 
# File 'lib/jiraSOAP/api/project_roles.rb', line 26

def project_role_name_unique? project_role_name
  call( 'isProjectRoleNameUnique', project_role_name ).to_boolean
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



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

def refresh_custom_fields
  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



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

def release_state_for_version_for_project project_name, version
  call 'releaseVersion', project_name, version
  true
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



33
34
35
36
 
# File 'lib/jiraSOAP/api/versions.rb', line 33

def set_archive_state_for_version_for_project project_key, version_name, state
  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



57
58
59
60
 
# File 'lib/jiraSOAP/api/avatars.rb', line 57

def set_new_project_avatar_for_project_with_key project_key, mime_type, base64_image
  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



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

def set_project_avatar_for_project_with_key project_key, avatar_id
  call 'setProjectAvatar', project_key, avatar_id
  true
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 call( 'editComment', comment ).first
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 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:



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

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:



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

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



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

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