cherby 0.0.1

data/.gitignore

@@ -0,0 +1,6 @@
+.ruby-version
+.ruby-gemset
+coverage/*
+Gemfile.lock
+doc/*
+.yardoc/*

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format doc
+--pattern "spec/**/*_spec.rb"

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 1.9.3
+

data/.yardopts

@@ -0,0 +1,4 @@
+--readme README.md
+--markup markdown
+lib/**/*.rb
+-

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gem 'bundler'
+
+# Get all other dependencies from cherby.gemspec
+gemspec

data/README.md

@@ -0,0 +1,83 @@
+Cherby
+======
+
+Cherby is a Ruby wrapper for the
+[Cherwell Web Service](http://cherwellsupport.com/webhelp/cherwell/index.htm#1971.htm).
+
+[Full documentation is on rdoc.info](http://rubydoc.info/github/a-e/cherby/master/frames).
+
+[![Build Status](https://secure.travis-ci.org/a-e/cherby.png?branch=dev)](http://travis-ci.org/a-e/cherby)
+
+
+Usage
+-----
+
+Connect to a Cherwell server by providing the URL of the web service:
+
+    url = "http://my.server/CherwellService/api.asmx"
+    cherwell = Cherby::Cherwell.new(url)
+
+Login by providing username and password, either during instantiation, or later
+when calling the `#login` method:
+
+    cherwell = Cherby::Cherwell.new(url, 'sisko', 'baseball')
+    cherwell.login
+    # => true
+
+    # or
+
+    cherwell = Cherby::Cherwell.new(url)
+    cherwell.login('sisko', 'baseball')
+    # => true
+
+Fetch an Incident:
+
+    incident = cherwell.incident('12345')
+    # => #<Cherby::Incident:0x...>
+
+View as a Hash:
+
+    incident.to_hash
+    # => {
+    #   'IncidentID' => '12345',
+    #   'Status' => 'Open',
+    #   'Priority' => '7',
+    #   ...
+    # }
+
+Make changes:
+
+    incident['Status'] = 'Closed'
+    incident['CloseDescription'] = 'Issue resolved'
+
+Save back to Cherwell:
+
+    cherwell.save_incident(incident)
+
+
+Copyright
+---------
+
+The MIT License
+
+Copyright (c) 2014 Eric Pierce
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

data/Rakefile

@@ -0,0 +1,12 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+Bundler.setup
+
+require 'rake'
+
+Dir.glob('tasks/*.rake').each { |r| import r }
+
+task :default => [:spec]
+

data/cherby.gemspec

@@ -0,0 +1,29 @@
+Gem::Specification.new do |s|
+  s.name = "cherby"
+  s.version = "0.0.1"
+  s.summary = "Cherwell-Ruby bridge"
+  s.description = <<-EOS
+    Cherby is a Ruby wrapper for the Cherwell Web Service.
+  EOS
+  s.authors = ["Eric Pierce"]
+  s.email = "wapcaplet88@gmail.com"
+  s.homepage = "http://github.com/a-e/cherby"
+  s.platform = Gem::Platform::RUBY
+
+  s.add_dependency "httpclient"
+  s.add_dependency 'savon', '>= 2.3.0'
+  s.add_dependency 'yajl-ruby'
+  s.add_dependency 'nokogiri'
+  s.add_dependency 'mustache'
+
+  s.add_development_dependency "rake"
+  s.add_development_dependency "simplecov"
+  s.add_development_dependency "pry"
+  s.add_development_dependency "rspec"
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'redcarpet'
+
+  s.files = `git ls-files`.split("\n")
+  s.require_path = 'lib'
+end
+

data/lib/cherby.rb

@@ -0,0 +1,11 @@
+require 'cherby/business_object'
+require 'cherby/client'
+require 'cherby/incident'
+require 'cherby/journal_note'
+require 'cherby/task'
+require 'cherby/cherwell'
+require 'cherby/exceptions'
+
+module Cherby
+end
+

data/lib/cherby/business_object.rb

@@ -0,0 +1,159 @@
+require 'mustache'
+require 'nokogiri'
+
+module Cherby
+  # Cherwell BusinessObject wrapper, with data represented as an XML DOM
+  class BusinessObject
+
+    # Override this with the value of the BusinessObject's 'Name' attribute
+    @object_name = ''
+    # Override this with the name of the Mustache XML template used to render
+    # your BusinessObject
+    @template = ''
+    # Fill this with default values for new instances of your BusinessObject
+    @default_values = {}
+
+    class << self
+      attr_accessor :object_name, :template, :default_values, :template_path
+    end
+
+    # Create a new BusinessObject subclass instance from the given hash of
+    # options.
+    # FIXME: Make this method accept CamelCase string field names instead of
+    # just :snake_case symbols, as part of a larger strategy to treat field names
+    # consistently throughout (using Cherwell's CamelCase strings everywhere)
+    def self.create(options={})
+      if self.template.empty?
+        # TODO: Exception subclass
+        raise RuntimeError, "No template defined for BusinessObject"
+      end
+      Mustache.template_path = File.join(File.dirname(__FILE__), 'templates')
+      xml = Mustache.render_file(
+        self.template, self.default_values.merge(options))
+      return self.new(xml)
+    end
+
+    # Instance methods
+
+    attr_reader :dom
+
+    # Create a new instance populated with the given XML string
+    def initialize(xml)
+      @dom = Nokogiri::XML(xml)
+    end
+
+    # Return the XML representation of this BusinessObject
+    def to_xml
+      return @dom.to_xml
+    end
+
+    # Return the node of the field with the given name.
+    def get_field_node(field_name)
+      selector = "BusinessObject > FieldList > Field[@Name=#{field_name}]"
+      return @dom.css(selector).first
+    end
+
+    # Return a hash of field names and values
+    def to_hash
+      result = {}
+      selector = "BusinessObject > FieldList > Field"
+      @dom.css(selector).each do |node|
+        result[node['Name']] = node.content
+      end
+      return result
+    end
+    alias :field_values :to_hash # For backwards compatibility
+
+
+    # Parse a Cherwell date/time string and return a DateTime object in UTC.
+    #
+    # This method mostly exists to work around the fact that Cherwell does
+    # not report a time zone offset in its datestamps. Since a BusinessObject
+    # may be initialized from a Jira entity (which *does* store time zone
+    # offset), any dt_string that includes a time zone offset at the end is
+    # correctly included in the result.
+    #
+    # @param [String] dt_string
+    #   The date/time string to parse. May or may not include a trailing
+    #   [+-]HH:MM or [+-]HHMM.
+    #
+    # @param [Integer] tz_offset
+    #   Offset in hours (positive or negative) between UTC and the given
+    #   `dt_string`. For example, Eastern Time is `-5`. This is ONLY used if
+    #   `dt_string` does NOT include a trailing offset component.
+    #
+    def self.parse_datetime(dt_string, tz_offset=-5)
+      begin
+        result = DateTime.parse(dt_string)
+      rescue
+        raise ArgumentError, "Could not parse date/time '#{dt_string}'"
+      end
+      # If offset was part of the dt_string, use new_offset to get UTC
+      if dt_string =~ /[+-]\d\d:?\d\d$/
+        return result.new_offset(0)
+      # Otherwise, subtract the numeric offset to get UTC time
+      else
+        return result - Rational(tz_offset.to_i, 24)
+      end
+    end
+
+    # Return the last-modified date/time of this BusinessObject
+    # (LastModDateTime converted to DateTime)
+    def modified
+      last_mod = self['LastModDateTime']
+      if last_mod.nil?
+        raise RuntimeError, "BusinessObject is missing LastModDateTime field."
+      end
+      begin
+        return BusinessObject.parse_datetime(last_mod)
+      rescue(ArgumentError)
+        raise RuntimeError, "Cannot parse LastModDateTime: '#{last_mod}'"
+      end
+    end
+
+    # Return the last-modified time as a human-readable string
+    def mod_s
+      return modified.strftime('%Y-%m-%d %H:%M:%S')
+    end
+
+    # Return True if this BusinessObject was modified more recently than
+    # another BusinessObject.
+    def newer_than?(business_object)
+      return modified > business_object.modified
+    end
+
+    # Return the content in the field with the given name.
+    # TODO: Exception for unknown field name
+    def [](field_name)
+      if field = get_field_node(field_name)
+        return field.content
+      end
+    end
+
+    # Modify the content in the field with the given name.
+    # TODO: Exception for unknown field name
+    def []=(field_name, value)
+      if field = get_field_node(field_name)
+        field.content = value.to_s
+      end
+    end
+
+    # Copy designated fields from one BusinessObject to another.
+    #
+    # @example
+    #   object_a.copy_fields_from(object_b, 'Status', 'Description')
+    #   # object_a['Status']      = object_b['Status']
+    #   # object_a['Description'] = object_b['Description']
+    #
+    # @param [BusinessObject] other_object
+    #   The object to copy field values from
+    # @param [Array<String>] field_names
+    #   Names of fields whose values you want to copy
+    #
+    def copy_fields_from(other_object, *field_names)
+      field_names.each do |field|
+        self[field] = other_object[field]
+      end
+    end
+  end
+end

data/lib/cherby/cherwell.rb

@@ -0,0 +1,230 @@
+require 'savon'
+require 'nokogiri'
+require 'cherby/client'
+require 'cherby/incident'
+require 'cherby/task'
+require 'cherby/exceptions'
+
+module Cherby
+  # Top-level Cherwell interface
+  class Cherwell
+    attr_reader :url, :username, :client
+
+    # Connect to a Cherwell server.
+    #
+    # @param [String] web_service_url
+    #   Full URL to the Cherwell web service API (typically ending in
+    #   `api.asmx`)
+    # @param [String] username
+    #   Default Cherwell user ID to use
+    # @param [String] password
+    #   Default Cherwell password to use
+    #
+    def initialize(web_service_url, username=nil, password=nil)
+      @url = web_service_url
+      @url.chop! if @url =~ /\/$/   # Remove any trailing slash
+      @username = username
+      @password = password
+      @client = Cherby::Client.new(@url)
+    end
+
+    # Login to Cherwell using the given credentials. Return true if
+    # login succeeded, or raise `LoginFailed` if login failed.
+    #
+    # @param [String] username
+    #   User ID to login with. If omitted, the username that was passed to
+    #   `Cherwell.new` is used.
+    # @param [String] password
+    #   Password to login with. If omitted, the password that was passed to
+    #   `Cherwell.new` is used.
+    #
+    # @return [Boolean]
+    #   `true` if login was successful
+    #
+    # @raise [LoginFailed]
+    #   If login failed for any reason
+    #
+    def login(username=nil, password=nil)
+      creds = {
+        :userId => username || @username,
+        :password => password || @password,
+      }
+      begin
+        response = @client.call(:login, :message => creds)
+      rescue => e
+        # This can happen if a bad URL is given
+        raise LoginFailed, e.message
+      else
+        if response.body[:login_response][:login_result] == true
+          # FIXME: Using the workaround described in this issue:
+          #   https://github.com/savonrb/savon/issues/363
+          # because the version recommended in the documentation:
+          #   auth_cookies = response.http.cookies
+          # does not work, giving:
+          #   NoMethodError: undefined method `cookies' for #<HTTPI::Response:0x...>
+          @client.globals[:headers] = {"Cookie" => response.http.headers["Set-Cookie"]}
+          return true
+        # This can happen if invalid credentials are given
+        else
+          raise LoginFailed, "Cherwell returned false status"
+        end
+      end
+    end
+
+    # Log out of Cherwell.
+    #
+    # @return [Boolean]
+    #   Logout response as reported by Cherwell.
+    #
+    def logout
+      return @client.logout
+    end
+
+    # Get the Cherwell incident with the given public ID, and return an
+    # Incident object.
+    #
+    # @return [Incident]
+    #
+    def incident(id)
+      incident_xml = get_object_xml('Incident', id)
+      return Incident.new(incident_xml.to_s)
+    end
+
+    # Get the Cherwell task with the given public ID, and return a Task
+    # object.
+    #
+    # @return [Task]
+    #
+    def task(id)
+      task_xml = get_object_xml('Task', id)
+      return Task.new(task_xml.to_s)
+    end
+
+    # Get a business object based on its public ID or RecID, and return the
+    # XML response.
+    #
+    # @example
+    #   incident_xml = cherwell.get_object_xml(
+    #     'Incident', '12345')
+    #
+    #   note_xml = cherwell.get_object_xml(
+    #     'JournalNote', '93bd7e3e067f1dafb454d14cb399dda1ef3f65d36d')
+    #
+    # @param [String] object_type
+    #   What type of object to fetch, for example "Incident", "Customer",
+    #   "Task", "JournalNote", "SLA" etc. May also be the `IDREF` of an
+    #   object type. Cherwell's API knows this as `busObNameOrId`.
+    # @param [String] id
+    #   The public ID or RecID of the object. If this is 32 characters or
+    #   more, it's assumed to be a RecID. For incidents, the public ID is a
+    #   numeric identifier like "50629", while the RecID is a long
+    #   hexadecimal string like "93bd7e3e067f1dafb454d14cb399dda1ef3f65d36d".
+    #
+    # This invokes `GetBusinessObject` or `GetBusinessObjectByPublicId`,
+    # depending on the length of `id`. The returned XML is the content of the
+    # `GetBusinessObjectResult` or `GetBusinessObjectByPublicIdResult`.
+    #
+    # @return [String]
+    #   Raw XML response string.
+    #
+    def get_object_xml(object_type, id)
+      # Assemble the SOAP body
+      body = {:busObNameOrId => object_type}
+
+      # If ID is really long, it's probably a RecID
+      if id.to_s.length >= 32
+        method = :get_business_object
+        body[:busObRecId] = id
+      # Otherwise, assume it's a public ID
+      else
+        method = :get_business_object_by_public_id
+        body[:busObPublicId] = id
+      end
+
+      begin
+        result = @client.call_wrap(method, body)
+      rescue Savon::Error => e
+        raise SoapError, e.message
+      else
+        return result
+      end
+    end
+
+
+    # Update a given Cherwell object by submitting its XML to the SOAP
+    # interface.
+    #
+    # @param [String] object_type
+    #   The kind of object you're updating ('Incident', 'Task'), or the
+    #   IDREF of the object type.
+    # @param [String] id
+    #   The public ID of the object
+    # @param [String] xml
+    #   The XML body containing all the updates you want to make
+    #
+    def update_object_xml(object_type, id, xml)
+      @client.update_business_object_by_public_id({
+        :busObNameOrId => object_type,
+        :busObPublicId => id,
+        :updateXml => xml
+      })
+      return last_error
+    end
+
+    # Save the given Cherwell incident
+    def save_incident(incident)
+      update_object_xml('Incident', incident.id, incident.to_xml)
+    end
+
+    # Save the given Cherwell task
+    def save_task(task)
+      update_object_xml('Task', task.id, task.to_xml)
+    end
+
+    # Create a new Cherwell incident with the given data. If creation
+    # succeeds, return the Incident instance; otherwise, return `nil`.
+    #
+    # @example
+    #   create_incident(
+    #     :service => 'Consulting Services',
+    #     :sub_category => 'New/Modified Functionality',
+    #     :priority => '4',
+    #   )
+    #
+    # @param [Hash] data
+    #   Incident fields to initialize. All required fields must be filled
+    #   in, or creation will fail. At minimum this includes `:service`,
+    #   `:sub_category`, and `:priority`.
+    #
+    # @return [Incident, nil]
+    #   The created incident, or `nil` if creation failed.
+    #
+    def create_incident(data)
+      incident = Incident.create(data)
+      result = @client.create_business_object({
+        :busObNameOrId => 'Incident',
+        :creationXml => incident.to_xml
+      })
+
+      # Result contains the public ID of the new incident, or nil if the
+      # incident-creation failed.
+      if !result.nil?
+        incident['IncidentID'] = result
+        return incident
+      else
+        return nil
+      end
+    end
+
+    # Get the last error reported by Cherwell.
+    #
+    # @return [String, nil]
+    #   Text of the last error that occurred, or `nil` if there was no error.
+    #
+    def last_error
+      return @client.get_last_error
+    end
+
+  end # class Cherwell
+end # module Cherby
+