issue_centre 0.0.1

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Jason Holloway
+
+MIT License
+
+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/README.md

@@ -0,0 +1,74 @@
+# IssueCentre
+
+This library is designed to help Ruby/Rails based applications
+communicate with the publicly available API for IssueCentre, as
+provided by First Option Software (http://www.bespokesoftware.com/).
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'issue_centre'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install issue_centre
+
+## Usage
+
+Basic usage:
+
+```ruby
+require 'rubygems'
+require 'issue_centre'
+
+# Create an authentication client connection to authenticate session
+auth_conn = IssueCentre::AuthConnection.new( "<IssueCentre Auth URL>")
+
+# Collect all applicable contracts
+contracts = auth_conn.get_contracts( "<username>", "<password>")
+
+
+# Obtain a session key for a relevant contract
+session_key = auth_conn.generate_key( "<username>", "<password>", contracts.last[:id])
+
+# Create a customer connection (note this is usually a different URL)
+cust_conn = IssueCentre::CustomerConnection.new( "<IssueCentre Customer URL>"), session_key)
+
+# Grab a list of all companies (you can also search with a wildcard)
+companies = cust_conn.get_companies( session_key)
+
+# or using a wildcard to find companies beginning with "British"...
+companies = cust_conn.get_companies( session_key, "British*")
+
+# Grab a list of all contacts (you can also search with a wildcard)
+contacts = cust_conn.get_contacts( session_key)
+
+# Grab a list of all countries
+countries = cust_conn.get_countries( session_key)
+
+# Create a ticket connection (note this is usually a different URL)
+ticket_conn = IssueCentre::TicketConnection.new( "<IssueCentre Ticket URL>", session_key)
+
+# Grab a list of open tickets for the specified company
+open_tickets = ticket_conn.get_open_tickets( session_key, companies.first[:id], 100, 1)
+
+# Grab a list of closed tickets for the specified company
+closed_tickets = ticket_conn.get_closed_tickets( session_key, companies.first[:id], 100, 1)
+
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/kitebuggy/issue_centre/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList[ 'test/test_*.rb']
+end
+

data/issue_centre.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'issue_centre/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "issue_centre"
+  spec.version       = IssueCentre::VERSION
+  spec.authors       = ["Jason Holloway"]
+  spec.email         = ["jason_holloway@mac.com"]
+  spec.summary       = %q{Gem to wrap the IssueCentre API.}
+  spec.description   = %q{Gem to wrap the IssueCentre API.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+
+  spec.add_development_dependency "minitest"
+  spec.add_development_dependency "vcr"
+  spec.add_development_dependency "webmock"
+
+  spec.add_dependency "faraday"
+  spec.add_dependency "savon", "~> 2.0"
+  spec.add_dependency "activesupport"
+end

data/lib/issue_centre.rb

@@ -0,0 +1,15 @@
+require 'bundler/setup'
+require 'savon'
+require 'active_support/core_ext/string/inflections'
+
+$: << File.expand_path( File.dirname(__FILE__))
+
+require 'issue_centre/version'
+require 'issue_centre/exception'
+
+require 'issue_centre/generic_connection'
+require 'issue_centre/auth_connection'
+require 'issue_centre/customer_connection'
+require 'issue_centre/ticket_connection'
+require 'issue_centre/response'
+

data/lib/issue_centre/auth_connection.rb

@@ -0,0 +1,50 @@
+module IssueCentre
+  class AuthConnection < GenericConnection
+
+    # Connection client for authenticating and retrieving contracts
+    # from IssueCentre
+    #
+    # @param [String] endpoint_url IssueCentre endpoint url
+    #   (e.g. {https://support.callclosed.net/issuecentre/Connection})
+    # @param [Hash] options Other options to pass to the constructors
+    #
+    # @return [AuthConnection] Instance of AuthConnection client
+    #
+    def initialize( auth_url, options = {})
+      super( auth_url, options)
+    end
+
+    # Obtain possible contracts from IssueCentre for this user
+    #
+    # @param [String] username A valid user in IssueCentre
+    # @param [String] password A valid password in IssueCentre
+    #
+    # @return [Response] A Response object
+    #    
+    def get_contracts( username, password)
+      response_xml = self.call( :get_contracts, message: {
+                                  arg0: username,
+                                  arg1: password
+                                })
+      response = IssueCentre::Response.parse( response_xml)
+    end
+
+    # Generate a contract-specific session key for this user from IssueCentre
+    #
+    # @param [String] username A valid user in IssueCentre
+    # @param [String] password A valid password in IssueCentre
+    # @param [String] contract A valid contract for this user
+    #
+    # @return [Array] Nokogiri::XML::Element array of return values
+    #    
+    def generate_key( username, password, contract)
+      response_xml = self.call( :generate_key, message: {
+                                  arg0: username,
+                                  arg1: password,
+                                  arg2: contract
+                                })
+      response = IssueCentre::Response.parse( response_xml,
+                                              {contract_id: contract})
+    end
+  end
+end

data/lib/issue_centre/customer_connection.rb

@@ -0,0 +1,77 @@
+module IssueCentre
+  class CustomerConnection < GenericConnection
+
+    # Connection client for authenticating and retrieving customer
+    # information from IssueCentre
+    #
+    # @param [String] endpoint_url IssueCentre endpoint url
+    #   (e.g. {https://support.callclosed.net/issuecentre/Customer})
+    # @param [String] session_key SessionKey for this session
+    # @param [Hash] options Other options to pass to the constructors
+    #
+    # @return [CustomerConnection] Instance of CustomerConnection client
+    #
+    def initialize( customer_url, session_key, options = {})
+      # @session_key = session_key
+      super( customer_url, options)
+    end
+
+
+    # Create companies from IssueCentre for this contract
+    #
+    # @param [String] session_key SessionKey for this session
+    #
+    # @param [String] wildcard The wildcard used to match the company
+    # names.  E.g. 'a*', 'Brit?sh'.  The wildcard is case
+    # insensitive. An empty string will return all companies.
+    #
+    # @return [Response] A Response object
+    #    
+    def get_companies( session_key, wildcard = '')
+      response_xml = self.call( :get_companies, message: {
+                                  arg0: session_key,
+                                  arg1: wildcard
+                                })
+      response = IssueCentre::Response.parse( response_xml)
+    end
+
+    
+    # Create contacts from IssueCentre for this contract
+    #
+    # @param [String] session_key SessionKey for this session
+    #
+    # @param [Integer] company_id The numeric ID of the company for
+    # which to return contacts for.  Defaults to returning all
+    # contacts for all companies.
+    #
+    # @param [String] wildcard The wildcard used to match the contact
+    # names.  E.g. 'Ala?', 'Jas*'.  The wildcard is case
+    # insensitive. An empty string will return all contacts.
+    #
+    # @return [Response] A Response object
+    #    
+    def get_contacts( session_key, company_id = 0, wildcard = '')
+      response_xml = self.call( :get_contacts, message: {
+                                  arg0: session_key,
+                                  arg1: company_id,
+                                  arg2: wildcard
+                                })
+      response = IssueCentre::Response.parse( response_xml)
+    end
+
+    
+    # Create countries from IssueCentre for this contract
+    #
+    # @param [String] session_key SessionKey for this session
+    #
+    # @return [Response] A Response object
+    #    
+    def get_countries( session_key)
+      response_xml = self.call( :get_countries, message: {
+                                  arg0: session_key,
+                                  arg1: ''
+                                })
+      response = IssueCentre::Response.parse( response_xml)
+    end
+  end
+end

data/lib/issue_centre/exception.rb

@@ -0,0 +1,10 @@
+module IssueCentre
+  class Error < StandardError
+  end
+
+  class ParseError < Error
+  end
+
+  class AuthenticationError < Error
+  end
+end

data/lib/issue_centre/generic_connection.rb

@@ -0,0 +1,31 @@
+module IssueCentre
+  class GenericConnection < Savon::Client
+
+    # Never used directly. Use sub-classes instead.
+    # @see AuthConnection
+    # @see CustomerConnection
+    #
+    # @param [String] endpoint_url IssueCentre endpoint url
+    #   (e.g. {https://support.callclosed.net/issuecentre/Connection})
+    # @param [String] username A valid IssueCentre username
+    # @param [String] password A valid IssueCentre password
+    # @param [Hash] options Other options to pass to the constructors
+    #
+    # @return [Connection] instance of Connection
+    #
+    def initialize( base_url, options = {})
+
+      @log = options[:log] || false
+      @log_level = options[:log_level] || :info
+      @wsdl_suffix = options[:wsdl_suffix] || "?wsdl"
+      @endpoint_url = options[:endpoint] || base_url
+      @issue_centre_url = base_url + @wsdl_suffix
+
+      super( wsdl: @issue_centre_url,
+             endpoint: @endpoint_url,
+             log_level: @log_level,
+             log: @log
+           )
+    end
+  end
+end

data/lib/issue_centre/response.rb

@@ -0,0 +1,125 @@
+module IssueCentre
+  class Response
+    
+    class << self
+      
+      # Parse the response retrieved during any request.
+      #
+      # @param [XML] savon_response Savon's representation of the
+      # response
+      #
+      # @param [Hash] options Any default attributes that should be
+      # added to the model
+      # 
+      # @return [Array] Array of hashes with combined response details
+      #
+      def parse( savon_response, options = {})
+
+        # retrieve the embedded xml
+        embedded_xml = savon_response.xpath( '//return')
+      
+        # check for responses we don't understand
+        if embedded_xml.blank?
+          raise IssueCentre::ParseError.new( savon_response.body.keys.first)
+        end
+
+        # parse the embbeded xml
+        doc = Nokogiri::XML.parse( embedded_xml.text)
+        model_name = which_model( doc)
+        
+        case doc.internal_subset.name
+        when 'generateKey'
+          # special case for session keys
+          return doc.text
+        else                    
+          if doc.root.name == 'return'
+            # Embedded XML within an embedded XML. Yuk.
+            raise IssueCentre::AuthenticationError.new( doc.text)
+          end
+        end
+
+        arr, obj = [], {}
+        arr, obj = recurse_and_build_model( doc, model_name, arr, obj)
+        arr << obj unless obj.empty?
+        return arr
+      end
+
+      
+      # Traverse through the namespace tree, building the object(s)
+      # along the way
+      #
+      # @param [Nokogiri::XML] fragment Fragment of the XML tree
+      # @param [String] model_name IssueCentre model being built
+      # @param [Array] arr Array of object hashes built so far
+      # @param [Hash] obj Object to be built (or being built)
+      # 
+      # @return [Array] Array of hashes representing the XML objects
+      # @return [Hash] Hash representing the last object being built
+      # (which may be empty)
+      #
+      def recurse_and_build_model( fragment, model_name, arr, obj)
+        fragment.elements.each do |element|
+          arr, obj = recurse_and_build_model( element, model_name, arr, obj)
+        end
+        fragment.attribute_nodes.each do |attr|
+          case attr.name
+          when 'defaultContract'
+            obj[ :id] = attr.value.to_i
+            obj[ :default_contract] = true
+            obj[ :name] = 'defaultContract'
+          when 'company'
+            obj[ :company_name] = attr.value
+          when 'country'
+            obj[ :country_id] = attr.value
+          when 'isDefault'
+            obj[ :is_default] = attr.value == "1"
+          when 'ticketCount', 'changeType', 'supportType'
+            # skip (we don't need summaries)
+          else
+            obj[ attr.name.underscore.to_sym] = attr.value
+          end
+        end
+        if fragment.attribute_nodes.empty? && fragment.elements.empty?
+          # We're now close to the leaves themselves
+          fragment.children.each do |child|
+            if child.text?
+              case fragment.name
+              when 'date', 'dateclosed'
+                obj[ fragment.name.underscore.to_sym] =
+                  Time.at( child.text.to_i / 1000)
+              else
+                obj[ fragment.name.underscore.to_sym] = child.text
+              end
+            end
+          end
+        end
+        if fragment.name == model_name
+          arr << obj unless obj.empty?
+          obj = {}
+        end
+        return arr, obj
+      end
+
+      private
+
+      # Returns the model name corresponding to the supplied
+      # Nokogiri::XML document.
+      #
+      # @param [Nokogiri::XML] doc Nokogiri document of the XML tree
+      # 
+      # @return [String] The IssueCentre model name for this XML object.
+      #
+      def which_model( doc)
+        # Convert pluralised string into model name,
+        # e.g. "contracts" => "Contract"
+        model_name = doc.root.internal_subset.name.classify
+
+        if model_name == 'GenerateKey'
+          model_name = 'SessionKey'
+        end
+
+        model_name.downcase
+      end
+    end
+  end
+end