clearconnect 0.0.3

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+doc/
+.yardoc

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in clearconnect.gemspec
+gemspec

data/README.md

@@ -0,0 +1,81 @@
+Usage
+-----
+
+The ClearConnect gem all starts with `ClearConnect::Client`. Initialize
+a client and then you can access the ClearConnect API methods via
+`Client#get` and `Client#post`. Pass all parameters to these methods
+as hashes, and make sure to include the action parameter to specify the
+API method to invoke. When a call is completed successfully, a plain
+Ruby structure (Array/Hash) with the retrieved information (or 
+confirmation information) is returned.
+
+```ruby
+client = ClearConnect::Client.new('myname', 'mypassword', 'sitename')
+client.get(action: 'getTemps', tempIdIn: 1000)
+# => [{"tempId"=>"1000", "homeRegion"=>"1", ...}]
+```
+
+Add/Update requests are no more difficult to execute than the get
+request demonstrated above. The Ruby structure passed to the method is
+converted directly to XML which is sent to the API endpoint. Take the
+`insertWorkHistory` API method as an example. Since it requires a root
+node of `workHistoryRecords` with multiple `workHistoryRecord`
+sub-nodes, we would construct a call to this method as follows:
+
+```ruby
+data = {
+  workHistoryRecords: [
+    { workHistoryRecord: {
+      tempId: 1000,
+      facility: 'Previous Employer 1',
+      startDate: '2013-04-09',
+      endDate: '2014-01-01'
+    }}
+  ]
+}
+client.post(action: 'insertWorkHistory', workHistoryRecords: data)
+```
+
+Configure
+---------
+
+The username, password, and sitename to use for authentication can be
+configured in a few ways. When used in a larger project with
+centralized configuration (e.g. a Rails application), the class method
+`ClearConnect#configure` allows you to set the information that will be
+used to authenticate the ClearConnect clients created. As an example, 
+you may create the file `config/initializers/clearconnect.rb` with the
+content:
+
+```ruby
+ClearConnect.configure do |config|
+  config.username = ENV['cc_username']
+  config.password = ENV['cc_password']
+  config.site_name = ENV['cc_sitename']
+end
+```
+
+In smaller applications or scripts, it may be easier to pass the info
+via the constructor of the `ClearConnect::Client`, like so:
+
+```ruby
+client = ClearConnect::Client.new('username', 'password', 'sitename')
+```
+
+Notes
+-----
+
+The `#get` method of `ClearConnect::Client` uses the http client library
+[HTTParty](https://github.com/jnunemaker/httparty). The `#post` method
+uses the SOAP client [Savon](https://github.com/savonrb/savon). The
+Savon client used internally is initialized when the first call is made
+that requires it because the initialization can take some time, but
+requests use the cached Savon client thereafter.
+
+Issues
+------
+
+Since the endpoint for the ClearConnect API uses SSL (i.e. is accessed
+via an https url), you may encounter the error `OpenSSL certificate
+verify failed`. The solution for this is relatively simple, and can be
+found [here](http://railsapps.github.io/openssl-certificate-verify-failed.html).

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/clearconnect.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "clearconnect/version"
+
+Gem::Specification.new do |s|
+  s.name = 'clearconnect'
+  s.version = ClearConnect::VERSION
+  s.platform = Gem::Platform::RUBY
+  s.authors = ["Christopher Hunt"]
+  s.email = 'chrahunt@gmail.com'
+  s.homepage = ''
+  s.summary = 'ClearConnect API Interface for Ruby'
+  s.description = ''
+
+  s.rubyforge_project = "clearconnect"
+  
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency 'httparty', '~> 0.10'
+  s.add_runtime_dependency 'savon', '~> 2.1.0'
+  s.add_runtime_dependency 'xml-simple', '~> 1.1.2'
+end

data/lib/clearconnect.rb

@@ -0,0 +1,18 @@
+require 'httparty'
+require 'savon'
+require 'xmlsimple'
+require 'json'
+
+# the clearconnect gem handles authentication and message passing between a 
+# Ruby/Rails application and the ClearConnect API offered by API Healthcare
+# as a supplement to their Contingent Staffing software.
+module ClearConnect
+  class NoFunctionError < StandardError; end
+  class AuthenticateError < StandardError; end
+end
+
+require 'clearconnect/client'
+require 'clearconnect/configuration'
+require 'clearconnect/rest_client'
+require 'clearconnect/soap_client'
+require 'clearconnect/version'

data/lib/clearconnect/client.rb

@@ -0,0 +1,69 @@
+module ClearConnect  
+  ## 
+  # This class is the interface to the ClearConnect API.
+  # 
+  # Authentication can be managed via configuration (see the documentation for ClearConnect::Configuration)
+  # or by passing the username, password, and sitename for the Contingent Staffing user directly to the client
+  # on initialization.
+  #
+  # example:
+  #   client = ClearConnect::Client.new('username', 'password', 'sitename')
+  #   client.get(action: 'getOrders') # => array of orders
+  class Client
+    def initialize(username = ClearConnect.configuration.username, 
+                   password = ClearConnect.configuration.password, 
+                   site_name = ClearConnect.configuration.site_name,
+                   session = (ClearConnect.configuration and ClearConnect.configuration.session))
+      # to ensure the endpoints are available
+      if !ClearConnect.configuration
+        ClearConnect.configure do |c|
+          c.username = username
+          c.password = password
+          c.site_name = site_name
+          c.session = session
+        end
+      end
+      @username = username
+      @password = password
+      @session = session
+    end
+
+    def soap_client
+      @soap_client ||= SoapClient.new(@username, @password)
+      @soap_client
+    end
+
+    def rest_client
+      @rest_client ||= RestClient.new(@username, @password)
+      @rest_client
+    end
+
+    # alias for ClearConnect::RestClient#get_request
+    def get(query)
+      rest_client.get_request(query)
+    end
+    
+    # alias for ClearConnect::SoapClient#post_request
+    def post(query)
+      soap_client.post_request(query)
+    end
+
+    # retrieves and sets session key for making requests, may raise
+    # exception if there is an error.
+    def get_session_key
+      response = rest_client.get_no_session(
+        action: 'getSessionKey').parsed_response[0]
+
+      if response['success'] == "1"
+        @sessionKey = response['sessionKey']
+        rest_client.set_session_key @sessionKey
+        # TODO: Incorporate sessions into Savon client.
+        #@soap_client.set_session_key @sessionKey if @soap_client
+      elsif response['errorCode']
+        raise "Session key retrieval failed with code: #{response['errorCode']}."
+      else
+        raise "Session key retrieval failed for an unknown reason."
+      end
+    end
+  end
+end

data/lib/clearconnect/configuration.rb

@@ -0,0 +1,64 @@
+module ClearConnect
+  class Configuration
+    attr_accessor \
+      :username,
+      :password,
+      :site_name,
+      :session,
+      :format
+
+    def initialize
+      @username = nil
+      @password = nil
+      @site_name = nil
+      @format = :json
+      @session = false
+      @endpoints = nil
+    end
+
+    def site_name=(site_name)
+      @site_name = site_name
+    end
+
+    #--
+    # do endpoints need to be set at any point?
+    #++
+    def endpoints
+      @endpoints ||= {
+        clearconnect: "https://agencystaffing.apihealthcare.com/#{@site_name}/clearConnect/2_0/index.cfm",
+        wsdl: "https://agencymedia001.apihealthcare.com/#{@site_name}/wsdl/staffingWebService.wsdl"
+      }
+    end
+
+    #--
+    # I don't think this is necessary
+    #++
+    def endpoints=(options = {})
+      if options.nil? 
+        @endpoints
+      end
+      @endpoints = options
+    end
+  end
+
+  class << self
+    attr_accessor :configuration
+  end
+
+  # Configure clearconnect someplace sensible,
+  # like config/initializers/clearconnect.rb
+  #
+  # @example
+  #   ClearConnect.configure do |c|
+  #     c.username = 'username'
+  #     c.password = 'password'
+  #     c.sitename = 'sitename'
+  #   end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    if block_given?
+      yield configuration
+    end
+  end
+end

data/lib/clearconnect/rest_client.rb

@@ -0,0 +1,49 @@
+class RestClient
+  include HTTParty
+  
+  def initialize(username, password)
+    self.class.base_uri ClearConnect.configuration.endpoints[:clearconnect]
+    self.class.default_params :resultType => ClearConnect.configuration.format.to_s
+    self.class.format ClearConnect.configuration.format
+    @username = username
+    @password = password
+    @session = false
+    @sessionKey = nil
+  end
+  
+  # Takes a query of the format { key: 'value', key2: 'value' } where the keys are symbols corresponding
+  # to the parameters passed to the ClearConnect REST API
+  def get_request(query)
+    if @session and @sessionKey.nil?
+      raise "Invalid session key. You must first acquire a session key by calling 'get_session_key' before executing requests."
+    elsif not @session
+      query = normalize_query(query.merge(:sessionKey => @sessionKey))
+      options = { :query => query }
+      self.class.get("", options)
+    else
+      get_no_session(query)
+    end
+  end
+
+  def get_no_session(query)
+    query = normalize_query(query.merge(:username => @username, :password => @password))
+    options = { :query => query }
+    self.class.get("", options)
+  end
+
+  def set_session_key(key)
+    puts "Setting session key: #{key}."
+    @session = true
+    @sessionKey = key
+  end
+
+  private
+  # Turns arguments that are arrays into comma-delimited strings
+  def normalize_query(query)
+    query.each_pair do |param, arg|
+      if arg.is_a? Array
+        query[param] = arg.join(',')
+      end
+    end
+  end
+end

data/lib/clearconnect/soap_client.rb

@@ -0,0 +1,71 @@
+class SoapClient
+  def initialize(username, password, session)
+    wsdl = HTTParty.get(ClearConnect.configuration.endpoints[:wsdl], :format => 'xml').parsed_response
+    @client = Savon::Client.new(
+      wsdl: wsdl, 
+      log_level: :info
+    )
+    @username = username
+    @password = password
+    @session = session
+    @default_params = {
+      :username => username,
+      :password => password,
+      :resultType => ClearConnect.configuration.format.to_s
+    }
+  end
+  
+  # Encodes request, packages into required node, sends, decodes response
+  def generic_request(message)
+    request = "<requestXmlString>#{xml_encode(message)}</requestXmlString>"
+    response = @client.call(:tss_request, message: request)
+    # :tss_request_response => {:tss_request_return => [ugly value to be decoded]}
+    # response.body
+    JSON.parse(response.body[:tss_request_response][:tss_request_return])[0]
+  end
+
+  # Takes a query of format { :key => 'value' } where :key is the properly formatted parameter and 'value' is the string value
+  # Parameters can be nested like so: { :tempRecords => { :tempRecord => [ { :key1 = 'value1', :key2 => 'value2' }, { :key1 => 'value3' } ] } }
+  # will produce <tempRecords><tempRecord><key1>value1</key1><key2>value2</key2></tempRecord><tempRecord><key1>value3</key1></tempRecord></tempRecords>
+  def post_request(query)
+    params = @default_params.merge(query)
+    post_data = XmlSimple.xml_out(params, RootName: 'clearviewRequest', NoAttr: true)
+    generic_request(post_data)
+  end
+  
+  def xml_encode(xml_string)
+    string = xml_string
+    characters = [
+      { find: '&', replacement: '&amp;' },
+      { find: '"', replacement: '&quot;' },
+      { find: '<', replacement: '&lt;' },
+      { find: '>', replacement: '&gt;' },
+      { find: "'", replacement: '&apos;' }
+    ]
+    characters.each do |set|
+      new_string = string.gsub(set[:find], set[:replacement])
+      if not new_string.nil?
+        string = new_string
+      end
+    end
+    return string 
+  end
+
+  def xml_decode(xml_string)
+    string = xml_string
+    characters = [
+      { replacement: '&', find: '&amp;' },
+      { replacement: '"', find: '&quot;' },
+      { replacement: '<', find: '&lt;' },
+      { replacement: '>', find: '&gt;' },
+      { replacement: "'", find: '&apos;' }
+    ]
+    characters.each do |set|
+      new_string = string.gsub(set[:find], set[:replacement])
+      if not new_string.nil?
+        string = new_string
+      end
+    end
+    return string 
+  end
+end

data/lib/clearconnect/version.rb

@@ -0,0 +1,3 @@
+module ClearConnect
+  VERSION = "0.0.3"
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: clearconnect
+version: !ruby/object:Gem::Version
+  version: 0.0.3
+  prerelease: 
+platform: ruby
+authors:
+- Christopher Hunt
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-05-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: savon
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.1.0
+- !ruby/object:Gem::Dependency
+  name: xml-simple
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.1.2
+description: ''
+email: chrahunt@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- clearconnect.gemspec
+- lib/clearconnect.rb
+- lib/clearconnect/client.rb
+- lib/clearconnect/configuration.rb
+- lib/clearconnect/rest_client.rb
+- lib/clearconnect/soap_client.rb
+- lib/clearconnect/version.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: clearconnect
+rubygems_version: 1.8.28
+signing_key: 
+specification_version: 3
+summary: ClearConnect API Interface for Ruby
+test_files: []
+has_rdoc: