jiraSOAP 0.6.1 → 0.7.1

data/lib/jiraSOAP/api/additions.rb

@@ -0,0 +1,22 @@
+module JIRA
+
+# Methods declared here do not directly map to methods defined in JIRA's
+# SOAP API javadoc. They are generally close to something from the javadoc
+# but with some extra conveniences.
+module RemoteAPIAdditions
+
+  # Returns the first field that exactly matches the given
+  # name, otherwise returns nil.
+  # @param [String] name
+  # @return [JIRA::Field,nil]
+  def get_custom_field_with_name name
+    get_custom_fields.each { |cf|
+      return cf if cf.name == name
+    }
+    nil
+  end
+
+  # @todo a method for getting attachments
+end
+
+end

data/lib/jiraSOAP/api/attachments.rb

@@ -0,0 +1,33 @@
+module JIRA
+module RemoteAPI
+  # @group Working with issue Attachments and their metadata
+
+  # @todo change method name to reflect that you only get metadata
+  # @param [String] issue_key
+  # @return [Array<JIRA::AttachmentMetadata>]
+  def get_attachments_for_issue_with_key issue_key
+    jira_call JIRA::AttachmentMetadata, 'getAttachmentsFromIssue', issue_key
+  end
+
+  # Expect this method to be slow.
+  # @param [String] issue_key
+  # @param [Array<String>] filenames names to put on the files
+  # @param [Array<String>] data base64 encoded data
+  # @return [Boolean] true if successful
+  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
+
+  # @endgroup
+end
+end

data/lib/jiraSOAP/api/avatars.rb

@@ -0,0 +1,64 @@
+module JIRA
+module RemoteAPI
+  # @group Working with Avatars
+
+  # Gets you the default avatar image for a project; if you want all
+  # the avatars for a project, use {#get_project_avatars_for_key}.
+  # @param [String] project_key
+  # @return [JIRA::Avatar]
+  def get_project_avatar_for_key project_key
+    JIRA::Avatar.new_with_xml call( 'getProjectAvatar', project_key ).first
+  end
+
+  # Gets ALL avatars for a given project with this method; if you
+  # just want the project avatar, use {#get_project_avatar_for_key}.
+  # @param [String] project_key
+  # @param [Boolean] include_default_avatars
+  # @return [Array<JIRA::Avatar>]
+  def get_project_avatars_for_key project_key, include_default_avatars = false
+    jira_call JIRA::Avatar, 'getProjectAvatars', project_key, include_default_avatars
+  end
+
+  # @note You cannot delete system avatars
+  # @note You need project administration permissions to delete an avatar
+  # @param [String] avatar_id
+  # @return [Boolean] true if successful
+  def delete_project_avatar_with_id avatar_id
+    call 'deleteProjectAvatar', avatar_id
+    true
+  end
+
+  # @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.
+  # @return [Boolean] true if successful
+  def set_project_avatar_for_project_with_key project_key, avatar_id
+    call 'setProjectAvatar', project_key, avatar_id
+    true
+  end
+
+  # @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.
+  # @param [String] project_key
+  # @param [String] mime_type
+  # @param [String] base64_image
+  # @return [Boolean] true if successful
+  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
+
+  # @endgroup
+end
+end

data/lib/jiraSOAP/api/comments.rb

@@ -0,0 +1,33 @@
+module JIRA
+module RemoteAPI
+  # @group Working with Comments
+
+  # @param [String] issue_key
+  # @param [JIRA::Comment] comment
+  # @return [Boolean] true if successful
+  def add_comment_to_issue_with_key issue_key, comment
+    call 'addComment', issue_key, comment
+    true
+  end
+
+  # @param [String] id
+  # @return [JIRA::Comment]
+  def get_comment_with_id id
+    JIRA::Comment.new_with_xml call( 'getComment', id ).first
+  end
+
+  # @param [String] issue_key
+  # @return [Array<JIRA::Comment>]
+  def get_comments_for_issue_with_key issue_key
+    jira_call JIRA::Comment, 'getComments', issue_key
+  end
+
+  # @param [JIRA::Comment] comment
+  # @return [JIRA::Comment]
+  def update_comment comment
+    JIRA::Comment.new_with_xml call( 'editComment', comment ).first
+  end
+
+  # @endgroup
+end
+end

data/lib/jiraSOAP/api/filters.rb

@@ -0,0 +1,20 @@
+module JIRA
+module RemoteAPI
+  # @group Working with Filters
+
+  # Retrieves favourite filters for the currently logged in user.
+  # @return [Array<JIRA::Filter>]
+  def get_favourite_filters
+    jira_call JIRA::Filter, 'getFavouriteFilters'
+  end
+  alias_method :get_favorite_filters, :get_favourite_filters
+
+  # @param [String] id
+  # @return [Fixnum]
+  def get_issue_count_for_filter_with_id id
+    call( 'getIssueCountForFilter', id ).to_i
+  end
+
+  # @endgroup
+end
+end

data/lib/jiraSOAP/api/issue_data_types.rb

@@ -0,0 +1,51 @@
+module JIRA
+module RemoteAPI
+  # @group Working with issue attributes
+
+  # @return [Array<JIRA::Priority>]
+  def get_priorities
+    jira_call JIRA::Priority, 'getPriorities'
+  end
+
+  # @return [Array<JIRA::Resolution>]
+  def get_resolutions
+    jira_call JIRA::Resolution, 'getResolutions'
+  end
+
+  # @return [Array<JIRA::Field>]
+  def get_custom_fields
+    jira_call JIRA::Field, 'getCustomFields'
+  end
+
+  # @return [Array<JIRA::IssueType>]
+  def get_issue_types
+    jira_call JIRA::IssueType, 'getIssueTypes'
+  end
+
+  # @return [Array<JIRA::Status>]
+  def get_statuses
+    jira_call JIRA::Status, 'getStatuses'
+  end
+
+  # @return [Array<JIRA::IssueType>]
+  def get_subtask_issue_types
+    jira_call JIRA::IssueType, 'getSubTaskIssueTypes'
+  end
+
+  # @param [String] project_id
+  # @return [Array<JIRA::IssueType>]
+  def get_subtask_issue_types_for_project_with_id project_id
+    jira_call JIRA::IssueType, 'getSubTaskIssueTypesForProject', project_id
+  end
+
+  # I have no idea what this method does.
+  # @todo find out what this method does
+  # @return [Boolean] true if no exceptions were raised
+  def refresh_custom_fields
+    call 'refreshCustomFields'
+    true
+  end
+
+  # @endgroup
+end
+end

data/lib/jiraSOAP/api/issues.rb

@@ -0,0 +1,102 @@
+module JIRA
+module RemoteAPI
+  # @group Working with Issues
+
+  # 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.
+  # @param [String] jql_query JQL query as a string
+  # @param [Fixnum] max_results limit on number of returned results;
+  #  the value may be overridden by the server if max_results is too large
+  # @return [Array<JIRA::Issue>]
+  def get_issues_from_jql_search jql_query, max_results = 2000
+    jira_call JIRA::Issue, 'getIssuesFromJqlSearch', jql_query, max_results
+  end
+
+  # 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.
+  # @example Usage With A Normal Field
+  #  summary        = JIRA::FieldValue.new 'summary', ['My new summary']
+  # @example Usage With A Custom Field
+  #  custom_field        = JIRA::FieldValue.new 'customfield_10060', ['123456']
+  # @example Setting a field to be blank/nil
+  #  description = JIRA::FieldValue.new 'description'
+  # @example Calling the method to update an issue
+  #  jira_service_instance.update_issue 'PROJECT-1', description, custom_field
+  # @param [String] issue_key
+  # @param [JIRA::FieldValue] *field_values
+  # @return [JIRA::Issue]
+  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
+
+  # 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
+  # @param [JIRA::Issue] issue
+  # @return [JIRA::Issue]
+  def create_issue_with_issue issue
+    JIRA::Issue.new_with_xml call( 'createIssue', issue ).first
+  end
+
+  # @param [String] issue_key
+  # @return [JIRA::Issue]
+  def get_issue_with_key issue_key
+    JIRA::Issue.new_with_xml call( 'getIssue', issue_key ).first
+  end
+
+  # @param [String] issue_id
+  # @return [JIRA::Issue]
+  def get_issue_with_id issue_id
+    JIRA::Issue.new_with_xml call( 'getIssueById', issue_id ).first
+  end
+
+  # @param [String] id
+  # @param [Fixnum] max_results
+  # @param [Fixnum] offset
+  # @return [Array<JIRA::Issue>]
+  def get_issues_from_filter_with_id id, max_results = 500, offset = 0
+    jira_call JIRA::Issue, 'getIssuesFromFilterWithLimit', id, offset, max_results
+  end
+
+  # @param [String] issue_id
+  # @return [Time]
+  def get_resolution_date_for_issue_with_id issue_id
+    call( 'getResolutionDateById', issue_id ).to_date
+  end
+
+  # @param [String] issue_key
+  # @return [Time]
+  def get_resolution_date_for_issue_with_key issue_key
+    call( 'getResolutionDateByKey', issue_key ).to_date
+  end
+
+  # @endgroup
+end
+end

data/lib/jiraSOAP/api/project_roles.rb

@@ -0,0 +1,49 @@
+module JIRA
+module RemoteAPI
+  # @group Working with Project Roles
+
+  # @return [Array<JIRA::ProjectRole>]
+  def get_project_roles
+    jira_call JIRA::ProjectRole, 'getProjectRoles'
+  end
+
+  # @param [String] role_id
+  # @return [JIRA::ProjectRole]
+  def get_project_role_with_id role_id
+    JIRA::ProjectRole.new_with_xml call( 'getProjectRole', role_id ).first
+  end
+
+  # @param [JIRA::ProjectRole] project_role
+  # @return [JIRA::ProjectRole] the role that was created
+  def create_project_role_with_role project_role
+    JIRA::ProjectRole.new_with_xml call( 'createProjectRole', project_role ).first
+  end
+
+  # @note JIRA 4.0 and 4.2 returns an exception if the name already exists
+  # Returns true if the name does not exist.
+  # @param [String] project_role_name
+  # @return [Boolean] true if successful
+  def project_role_name_unique? project_role_name
+    call( 'isProjectRoleNameUnique', project_role_name ).to_boolean
+  end
+
+  # @note the confirm argument appears to do nothing (at least on JIRA 4.0)
+  # @param [JIRA::ProjectRole] project_role
+  # @param [Boolean] confirm
+  # @return [Boolean] true if successful
+  def delete_project_role project_role, confirm = true
+    call 'deleteProjectRole', project_role, confirm
+    true
+  end
+
+  # @note JIRA 4.0 will not update project roles, it will instead throw
+  #  an exception telling you that the project role already exists
+  # @param [JIRA::ProjectRole] project_role
+  # @return [JIRA::ProjectRole] the role after the update
+  def update_project_role_with_role project_role
+    JIRA::ProjectRole.new_with_xml call( 'updateProjectRole', project_role ).first
+  end
+
+  # @endgroup
+end
+end

data/lib/jiraSOAP/api/projects.rb

@@ -0,0 +1,67 @@
+module JIRA
+module RemoteAPI
+  # @group Working with Projects
+
+  # 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.
+  # @param [String] project_key
+  # @return [JIRA::Project]
+  def get_project_with_key project_key
+    JIRA::Project.new_with_xml call( 'getProjectByKey', project_key ).first
+  end
+
+  # 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.
+  # @param [JIRA::Project] project
+  # @return [JIRA::Project]
+  def create_project_with_project project
+    JIRA::Project.new_with_xml call( 'createProjectFromObject', project ).first
+  end
+
+  # 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.
+  # @param [JIRA::Project] project
+  # @return [JIRA::Project]
+  def update_project_with_project project
+    JIRA::Project.new_with_xml call( 'updateProject', project ).first
+  end
+
+  # @param [String] project_id
+  # @return [JIRA::Project]
+  def get_project_with_id project_id
+    JIRA::Project.new_with_xml call( 'getProjectById', project_id ).first
+  end
+
+  # @todo parse the permission scheme
+  # @note This method does not yet include the permission scheme.
+  # @param [String] project_id
+  # @return [JIRA::Project]
+  def get_project_including_schemes_with_id project_id
+    JIRA::Project.new_with_xml call( 'getProjectWithSchemesById', project_id ).first
+  end
+
+  # @param [String] project_name
+  # @return [Array<JIRA::IssueType>]
+  def get_issue_types_for_project_with_id project_id
+    jira_call JIRA::IssueType, 'getIssueTypesForProject', project_id
+  end
+
+  # @note This will not fill in JIRA::Scheme data for the projects.
+  # @return [Array<JIRA::Project>]
+  def get_projects_without_schemes
+    jira_call JIRA::Project, 'getProjectsNoSchemes'
+  end
+
+  # @param [String] project_key
+  # @return [Boolean] true if successful
+  def delete_project_with_key project_key
+    call 'deleteProject', project_key
+    true
+  end
+
+  # @endgroup
+end
+end