jiraSOAP 0.8.1 → 0.8.2

data/.yardopts

@@ -5,5 +5,6 @@
 lib/**/*.rb
 -
 docs/GettingStarted.markdown
+docs/Examples.markdown
 ChangeLog
 LICENSE.txt

data/ChangeLog

@@ -1,16 +1,31 @@
+Version 0.8.2
+
+	* Added Issue#custom_field for getting custom field values
+	* Added a file of examples, ported from jira4r
+	* Add setters to attribute aliases
+	* Added a forgotten deprecation
+	* Updated ChangeLog with changes from 0.8.1
+	* Updated ChangeLog with changes from 0.8.0 (sorry!)
+
+Version 0.8.1
+
+	* Updated README and GettingStarted guide
+
 Version 0.8.0
 
 	* Deprecated the #get_ from methods that start with #get_
 	* Alias #login to #log_in and #logout to #log_out
 	* Added RemoteAPI#permission_to_edit_comment?
 	* Added UserGroup and related RemoteAPI methods
-	* Added RemoteAPI#add_worklog
+	* Added RemoteAPI#add_worklog (thanks @FDj)
+	* Added ability to initialize JIRA::FieldValue without an array (thanks @knut)
+
 	* Various documentation updates and tweaks
 
 	* Removed handsoap parsing abstraction (roflscale for parsing)
 	* Removed the YARD plugin in favour of YARD 0.7 DSL documenting stuff
 
-	* FIx setting the assignee during Issue creation
+	* Fix setting the assignee during Issue creation (thanks @ssmiech)
 
 Version 0.7.1
 

data/docs/Examples.markdown

@@ -0,0 +1,119 @@
+# Examples
+
+These snippets showcase ways to interact with a JIRA server via JIRA's
+SOAP interface. The script was originally adapted from an example
+script for jira4r.
+
+## The first thing you need to do
+
+Always start by creating a new {JIRA::JIRAService}, with the argument
+being the base URL to your JIRA server
+(e.g. http://confluence.atlassian.com):
+
+    jira = JIRA::JIRAService.new 'http://jira.atlassian.com:8080'
+
+Then you need to log in:
+
+    jira.login 'soaptester', 'password'
+
+Now the rest of the API is available to you.
+
+## Server Information
+
+You can get information about the server, such as its version, and
+also information about its configuration, such as whether or not
+voting on issues is allowed:
+
+    baseurl = jira.server_info.base_url
+    puts "Base URL: #{baseurl} \n"
+
+    if jira.server_configuration.voting_allowed?
+      puts 'Voting is allowed on this server'
+    else
+      puts 'Voting is not allowed on this server'
+    end
+
+## Project Information
+
+Getting information about projects is also very easy, except for
+information about schemes (i.e. permissions, etc.).
+
+    # get every project
+    projects = jira.projects.each { |project| puts project.inspect }
+
+    # get a specific project
+    project_key = 'DEMO'
+    project = jira.project_with_key project_key
+    puts "Details for project #{project_key}: #{project.inspect}"
+
+### Project Versions
+
+    version = JIRA::Version.new
+    version.name = 'version 99'
+    new_version = jira.add_version_to_project_with_key project.key, version
+    puts "Added version #{new_version.name} to #{project.name}\n"
+
+## Issues
+
+There are many ways to get and issue from the server, I think the
+easiest is to use the issue key.
+
+    issue_key = 'TST-10392'
+    issue = jira.issue_with_key issue_key
+    puts "Retrieved issue: #{issue.key}: #{issue.summary}\n"
+
+### Get the value of a custom field
+
+I find that I often need to get information from an issue's custom fields.
+
+    custom_field_id = jira.custom_field_with_name('Reported on behalf of').id
+    custom_field_value = issue.custom_field(custom_field_id)
+    puts "Value of issue #{issue.key}'s custom field with ID #{custom_field_id}: " +
+      "#{custom_field_value}\n"
+
+### Comment on an issue
+
+It is also pretty easy to add a comment to an issue.
+
+    comment = JIRA::Comment.new
+    comment.body = 'commented from jiraSOAP'
+    jira.add_comment_to_issue_with_key issue.key, comment
+
+### Update a field for an issue
+
+Updating an issue is easy, but has some caveats, so you should see the
+documentation as well ({JIRA::RemoteAPI#update_issue}).
+
+    summary = JIRA::FieldValue.new('summary', 'new summary info from jiraSOAP')
+    jira.update_issue issue.key, summary
+    puts "Updated issue #{issue.key}'s field #{summary.name}\n"
+
+## User Information
+
+CRUD operations for user information are also available.
+
+    begin
+      password = rand(1000000000000).to_s(16)
+      user = jira.create_user('jon', password, 'Jon Happy', 'jon@usa.com')
+      puts "Created user #{user.username} with password: #{password}\n"
+    rescue
+    end
+
+### User groups
+
+    # get details about a user group
+    group = jira.group_with_name 'jira-users'
+    puts "Retrieved details for group jira-users: #{group.inspect}\n"
+
+    # add a user to a group
+    newuser = JIRA::User.new
+    newuser.name = user.name
+    jira.add_user_to_group group, user
+    puts "Added user #{user.name} in group #{group.name}\n"
+
+## Don't forget to log out
+
+Your session will timeout, but for security purposes it is always a
+good idea to log out when you are done.
+
+    jira.logout

data/docs/GettingStarted.markdown

@@ -33,6 +33,8 @@ Don't forget to log out when you are done:
 
    db.logout
 
+See {file:docs/Examples.rb} for more examples.
+
 To find out what APIs are available, check out the {JIRA::RemoteAPI}
 module, as well as the {JIRA::RemoteAPIAdditions} module for
 conveniences that `jiraSOAP` has added.

data/lib/jiraSOAP/api/additions.rb

@@ -10,11 +10,12 @@ module JIRA::RemoteAPIAdditions
   #
   # @param [String] name
   # @return [JIRA::Field,nil]
-  def get_custom_field_with_name name
+  def custom_field_with_name name
     get_custom_fields.each { |cf|
       return cf if cf.name == name
     }
     nil
   end
+  alias_method :get_custom_field_with_name, :custom_field_with_name
 
 end

data/lib/jiraSOAP/api/issue_data_types.rb

@@ -26,6 +26,13 @@ module JIRA::RemoteAPI
   end
   alias_method :get_issue_types, :issue_types
 
+  # @param [String] project_name
+  # @return [Array<JIRA::IssueType>]
+  def issue_types_for_project_with_id project_id
+    array_jira_call JIRA::IssueType, 'getIssueTypesForProject', project_id
+  end
+  alias_method :get_issue_types_for_project_with_id, :issue_types_for_project_with_id
+
   # @return [Array<JIRA::Status>]
   def statuses
     array_jira_call JIRA::Status, 'getStatuses'

data/lib/jiraSOAP/api/issues.rb

@@ -38,9 +38,9 @@ module JIRA::RemoteAPI
   # update.
   #
   # @example Usage With A Normal Field
-  #  summary      = JIRA::FieldValue.new 'summary', ['My new summary']
+  #  summary      = JIRA::FieldValue.new 'summary', 'My new summary'
   # @example Usage With A Custom Field
-  #  custom_field = JIRA::FieldValue.new 'customfield_10060', ['123456']
+  #  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

data/lib/jiraSOAP/api/projects.rb

@@ -14,28 +14,6 @@ module JIRA::RemoteAPI
   end
   alias_method :get_project_with_key, :project_with_key
 
-  ##
-  # 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 jira_call( 'createProjectFromObject', project )
-  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 jira_call( 'updateProject', project )
-  end
-
   # @param [String] project_id
   # @return [JIRA::Project]
   def project_with_id project_id
@@ -54,21 +32,36 @@ module JIRA::RemoteAPI
   end
   alias_method :get_project_including_schemes_with_id, :project_including_schemes_with_id
 
-  # @param [String] project_name
-  # @return [Array<JIRA::IssueType>]
-  def issue_types_for_project_with_id project_id
-    array_jira_call JIRA::IssueType, 'getIssueTypesForProject', project_id
-  end
-  alias_method :get_issue_types_for_project_with_id, :issue_types_for_project_with_id
-
   ##
   # @note This will not fill in {JIRA::Scheme} data for the projects.
   #
   # @return [Array<JIRA::Project>]
-  def projects_without_schemes
+  def projects
     array_jira_call JIRA::Project, 'getProjectsNoSchemes'
   end
-  alias_method :get_projects_without_schemes, :projects_without_schemes
+  alias_method :get_projects, :projects
+
+  ##
+  # 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 jira_call( 'createProjectFromObject', project )
+  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 jira_call( 'updateProject', project )
+  end
 
   # @param [String] project_key
   # @return [Boolean] true if successful

data/lib/jiraSOAP/entities/attachment_metadata.rb

@@ -10,10 +10,12 @@ class JIRA::AttachmentMetadata < JIRA::NamedEntity
   # @return [String]
   add_attribute :file_name, 'filename', :content
   alias_method :filename, :file_name
+  alias_method :filename=, :file_name=
 
   # @return [String]
   add_attribute :mime_type, 'mimetype', :content
   alias_method :content_type, :mime_type
+  alias_method :content_type=, :mime_type=
 
   ##
   # Measured in bytes

data/lib/jiraSOAP/entities/avatar.rb

@@ -19,10 +19,12 @@ class JIRA::Avatar < JIRA::DynamicEntity
   # @return [String]
   add_attribute :mime_type, 'contentType', :content
   alias_method :content_type, :mime_type
+  alias_method :content_type=, :mime_type=
 
   # @return [String]
   add_attribute :base64_data, 'base64Data', :content
   alias_method :data, :base64_data
+  alias_method :data=, :base64_data=
 
   ##
   # Indicates if the image is the system default

data/lib/jiraSOAP/entities/field_value.rb

@@ -24,7 +24,9 @@ class JIRA::FieldValue
     end
   end
 
+  ##
   # @todo soapify properly for custom objects (JIRA module).
+  #
   # @param [Handsoap::XmlMason::Node] message the node to add the object to
   # @param [String] label name for the tags that wrap the message
   # @return [Handsoap::XmlMason::Element]

data/lib/jiraSOAP/entities/issue.rb

@@ -74,6 +74,16 @@ class JIRA::Issue < JIRA::DynamicEntity
   # @return [Array<String>]
   add_attribute :attachment_names, 'attachmentNames', :contents_of_children
 
+  ##
+  # Get the value of a custom field given the custom field id, returns
+  # nil if the issue does not have a value for that field.
+  #
+  # @param [String] id the custom field id (e.g. 'customfield_10150')
+  # @return [JIRA::CustomFieldValue,nil]
+  def custom_field id
+    custom_field_values.find { |field_value| field_value.id == id }
+  end
+
   ##
   # @todo see if we can use the simple and complex array builders
   #

data/lib/jiraSOAP/entities/issue_type.rb

@@ -8,5 +8,6 @@ class JIRA::IssueType < JIRA::IssueProperty
   # @return [Boolean]
   add_attribute :subtask, 'subTask', :to_boolean
   alias_method :sub_task, :subtask
+  alias_method :sub_task=, :subtask=
 
 end

data/lib/jiraSOAP/entities/username.rb

@@ -6,5 +6,7 @@ class JIRA::UserName < JIRA::Entity
 
   # @return [String]
   add_attribute :username, 'name', :content
+  alias_method :name, :username
+  alias_method :name=, :username=
 
 end

data/lib/jiraSOAP/version.rb

@@ -1,3 +1,3 @@
 module JIRA
-  VERSION = '0.8.1'
+  VERSION = '0.8.2'
 end

metadata

@@ -2,7 +2,7 @@
 name: jiraSOAP
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.8.1
+  version: 0.8.2
 platform: ruby
 authors: 
 - Mark Rada
@@ -80,6 +80,7 @@ extra_rdoc_files:
 - LICENSE.txt
 - .yardopts
 - docs/GettingStarted.markdown
+- docs/Examples.markdown
 files: 
 - lib/jiraSOAP/api/additions.rb
 - lib/jiraSOAP/api/attachments.rb
@@ -147,6 +148,7 @@ files:
 - LICENSE.txt
 - .yardopts
 - docs/GettingStarted.markdown
+- docs/Examples.markdown
 homepage: http://github.com/Marketcircle/jiraSOAP
 licenses: 
 - MIT