reps_client 0.0.1 → 0.1.0

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+## 0.1.0 (2011-12-30)
+
+* Add configuration option to enable or disable debug logging.
+  It is disabled by default (previously, it was always enabled).
+
+    ``` ruby
+    RepsClient.configure do |config|
+      config.debug = true
+    end
+    ```
+
+*  When logging is enabled, it defaults to logging to STDOUT, but you can
+   configure a custom logger.
+
+    ``` ruby
+    RepsClient.configure do |config|
+      config.logger = Logger.new('my.log')
+    end
+    ```
+
+* Add support for ws-addressing. The REPS production environment requires
+  these headers on all requests.
+
+* Flesh out logic around the return value of `RepsClient::Client#save_lead`.
+  It will return true when successful and false otherwise (previously, the
+  return value was meaningless).
+
+* Update documentation.
+
+## 0.0.1 (2011-12-09)
+
+* Initial release

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (C) 2011 G5
+
+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

@@ -4,9 +4,11 @@ This adapter provides a simple wrapper around a SOAP client for the [MDI Achieve
 
 ## Installation ##
 
-To use this library prior to the initial release, add this to your Gemfile:
+The gem is available on [RubyGems][rubygems] and can be installed via:
 
-        gem 'reps_client', :git => 'git@github.com:g5search/reps_client.git', :branch => 'development'
+    ```
+    gem install reps_client
+    ```
 
 ## Basics ##
 
@@ -14,49 +16,73 @@ For more details on any topic, see the [RDocs][rdocs].
 
 ### Configuration ###
 
-Most commonly, you will only need to supply the enterprise key in order to access the service.
-
 Configuration options can be set at the module level to automatically apply it to all client instances:
 
-        RepsClient.configure do |config|
-          config.enterprise_key = 'mykey'
-        end
+    ```ruby
+    RepsClient.configure do |config|
+      config.enterprise_key = 'mykey'
+    end
 
-        client = RepsClient::Client.new
+    client = RepsClient::Client.new
+    ```
 
 Or you can set it on each individual client instance:
 
-        client = RepsClient::Client.new(:enterprise_key => 'mykey')
+    ```ruby
+    client = RepsClient::Client.new(:enterprise_key => 'mykey')
+    ```
 
-### Examples ###
+The external service always requires an enterprise key. Optionally, you
+may also wish to change settings such as the service endpoint (which defaults
+to the REPS test server) and configure debug logging (which is disabled by default).
+
+    ```ruby
+    RepsClient.configure do |config|
+      config.enterprise_key = 'mykey'
+      config.endpoint = 'http://my.hosted.endpoint.com/lead.asmx'
+      config.debug = true
+      config.logger = Logger.new('my.log')
+    end
+    ```
 
-To retrieve a list of communities that belong to this enterprise:
+For a full list of configuration options, see {RepsClient::Configuration}.
+
+### Examples ###
 
-        communities = client.get_communities
-        # => [#<RepsClient::Community address1="123 Anywhere Ln" city="Somewhere" community_id="2" name="Pine View Terrace" state="AK" zip="12345">, #<RepsClient::Community community_id="8" name="The Hills at Dale Valley">]
+To retrieve a list of communities that belong to this enterprise in REPS:
 
+    ```ruby
+    communities = client.get_communities
+    # => [#<RepsClient::Community address1="123 Anywhere Ln" city="Somewhere" community_id="2" name="Pine View Terrace" state="AK" zip="12345">, #<RepsClient::Community community_id="8" name="The Hills at Dale Valley">]
+    ```
 To retrieve a list of enumerated data types (e.g. relationship type, ad source) that are available for a particular community:
 
-        pick_lists = client.get_pick_lists(2)
-        # => {:prefix => [#<RepsClient::Prefix prefix_id="1" value="Mr.">, #<RepsClient::Prefix prefix_id="2" value="Ms.">],
-        #     :suffix => [#<RepsClient::Suffix suffix_id="200" value="Jr.">, #<RepsClient::Suffix suffix_id="99" value="M.D">],
-        #     :relationship_type => [#<RepsClient::RelationshipType relationship_type_id="42" name="Self">],
-        #     :source => [#<RepsClient::Source source_id="99" code="WEB" description="From the community website">]}
-
-To save a lead, which include a contact and prospect. A very simple lead might look like this:
-
-        contact = RepsClient::Contact.new(:prefix => 'Mr.',
-                                          :first_name => 'Fred',
-                                          :last_name => 'Rogers',
-                                          :email => 'misterrogers@neighborhood.com',
-                                          :relationship_to_prospect_id => 2,
-                                          :source_id => 99)
-        prospect = RepsClient::Prospect.new(:prefix => 'Mr.',
-                                            :first_name => 'Fred',
-                                            :last_name => 'Rogers',
-                                            :email => 'misterrogers@neighborhood.com',
-                                            :notes => 'Request for Brochure')
-        client.save_lead(2, contact, prospect)
+    ```ruby
+    pick_lists = client.get_pick_lists(2)
+    # => {:prefix => [#<RepsClient::Prefix prefix_id="1" value="Mr.">, #<RepsClient::Prefix prefix_id="2" value="Ms.">],
+    #     :suffix => [#<RepsClient::Suffix suffix_id="200" value="Jr.">, #<RepsClient::Suffix suffix_id="99" value="M.D">],
+    #     :relationship_type => [#<RepsClient::RelationshipType relationship_type_id="42" name="Self">],
+    #     :source => [#<RepsClient::Source source_id="99" code="WEB" description="From the community website">]}
+    ```
+
+To save a simple lead:
+
+    ```ruby
+    community_id = 2
+    contact = RepsClient::Contact.new(:prefix => 'Mr.',
+                                      :first_name => 'Fred',
+                                      :last_name => 'Rogers',
+                                      :email => 'misterrogers@neighborhood.com',
+                                      :relationship_to_prospect_id => 2,
+                                      :source_id => 99)
+    prospect = RepsClient::Prospect.new(:prefix => 'Mr.',
+                                        :first_name => 'Fred',
+                                        :last_name => 'Rogers',
+                                        :email => 'misterrogers@neighborhood.com',
+                                        :notes => 'Request for Brochure')
+    client.save_lead(community_id, contact, prospect)
+    ```
 
  [mdi]: http://mdiachieve.com
  [rdocs]: http://rubydoc.info/gems/reps_client
+ [rubygems]: http://rubygems.org/gems/reps_client

data/lib/reps_client/client.rb

@@ -1,4 +1,5 @@
 require 'savon'
+require 'uuidtools'
 
 require 'reps_client/community'
 require 'reps_client/errors'
@@ -6,7 +7,7 @@ require 'reps_client/pick_list'
 require 'reps_client/lead'
 
 module RepsClient
-  # TODO: document RepsClient::Client
+  # RepsClient::Client is the main object for connecting to the remote REPS service.
   class Client
     include CommunityMethods
     include PickListMethods
@@ -20,15 +21,76 @@ module RepsClient
       define_method(opt) { get_value(opt) }
     end
 
+    # @attr [String] endpoint the service endpoint URL
+    # @attr [String] username the username for authentication
+    # @attr [String] password the password for authentication
+    # @attr [String] namespace the namespace for SOAP requests
+    # @attr [String] enterprise_key the corporate key required for all REPS requests
+    # @attr [true,false,String] debug set to true or 'true' to enable debug logging (defaults to false)
+    # @attr [Logger] logger the custom logger instance for debug logging (defaults to STDOUT)
+
+    def debug=(val)
+      @debug = val
+      Savon.log = self.debug?
+    end
+
+    def debug?
+      self.debug.to_s == 'true'
+    end
+
+    def logger=(val)
+      @logger = val
+      Savon.logger = self.logger
+    end
+
     # Initializes the client.
     #
+    # By default, the new client instance will take all of its configuration values from the
+    # module-level configuration, but these can be overridden at the client-level.
+    #
+    # @example Using module-level configuration values
+    #   RepsClient.configure do |config|
+    #     config.enterprise_key = 'my_key'
+    #   end
+    #
+    #   client1 = RepsClient::Client.new
+    #   client1.enterprise_key
+    #   # => "my_key"
+    #
+    #   client2 = RepsClient::Client.new
+    #   client2.enterprise_key
+    #   # => "my_key"
+    #
+    # @example Selectively overriding configuration values at the client level
+    #   RepsClient.configure do |config|
+    #     config.enterprise_key = 'my_key'
+    #     config.debug = 'true'
+    #   end
+    #
+    #   client1 = RepsClient::Client.new
+    #   client1.enterprise_key
+    #   # => "my_key"
+    #   client1.debug?
+    #   # => true
+    #
+    #   client2 = RepsClient::Client.new(:debug => false)
+    #   client2.enterprise_key
+    #   # => "my_key"
+    #   client2.debug?
+    #   # => false
+    #
     # @param [Hash] options
     # @option options [String] :username The username for authenticating to the web service
     # @option options [String] :password The password for authenticating to the web service
     # @option options [String] :enterprise_key The enterprise key for authentication to the web service
     # @option options [String] :endpoint The address for connecting to the web service
     # @option options [String] :namespace The XML namespace to use for requests
+    # @option options [true,false] :debug true enabled debug logging (defaults to false)
+    # @option options [Logger] :logger a custom logger instance (defaults to STDOUT)
+    # @see RepsClient::Configuration
     def initialize(options={})
+      self.debug = nil
+      self.logger = nil
       options.each { |k,v| self.send("#{k}=", v) if self.respond_to?("#{k}=") }
     end
 
@@ -44,14 +106,18 @@ module RepsClient
         wsdl.namespace = self.namespace.to_s
         wsse.credentials self.username, self.password, false
 
-        # We have to override the wsse timestamp method to force UTC
+        wsse.timestamp = true
+
+        # We have to override some of the timestamps to force UTC
         # (the reps service cacks on any other timezone)
+        wsse.created_at = Time.now.utc
         class << wsse
           define_method(:timestamp, lambda { @timestamp ||= Time.now.utc.xs_datetime })
         end
       end
     end
 
+    private
     # Sends a SOAP request to the remote service. This method takes care of
     # constructing the SOAP envelope and headers as well as common parameters
     # for REPS (e.g. the enterprise key)
@@ -72,15 +138,19 @@ module RepsClient
 
         response = soap_client.request :wsdl, camelcase_action do
           soap.element_form_default = :qualified
+          qualified_soap_action = URI.join(self.namespace, camelcase_action).to_s
+
+          soap.namespaces['xmlns:wsa'] = 'http://schemas.xmlsoap.org/ws/2004/08/addressing'
+          soap.header = ws_addressing_headers(qualified_soap_action)
+          http.headers['SOAPAction'] = %{"#{qualified_soap_action}"}
+
           soap.body = {:enterprise_key => self.enterprise_key}.merge(soap_parameters)
-          http.headers['SOAPAction'] = %{"#{URI.join(self.namespace, camelcase_action)}"}
         end
       rescue Savon::SOAP::Fault => f
         raise RepsClient::ServiceError.translate_fault(f)
       end
     end
 
-
     # Retrieves an attribute value. If the attribute has not been set
     # on this object, it is retrieved from the global configuration.
     #
@@ -89,7 +159,17 @@ module RepsClient
     # @param [Symbol] attribute the name of the attribute
     # @return [String] the value of the attribute
     def get_value(attribute)
-      instance_variable_get("@#{attribute}") || RepsClient.send(attribute)
+      local_val = instance_variable_get("@#{attribute}")
+      local_val.nil? ? RepsClient.send(attribute) : local_val
+    end
+
+    # Manually constructs the ws-addressing soap headers required by the REPS production
+    # web service. It would be nice to add ws-addressing support to savon eventually.
+    def ws_addressing_headers(soap_action)
+      { 'wsa:Action' => soap_action,
+        'wsa:To' => self.endpoint,
+        'wsa:ReplyTo' => {'wsa:Address' => 'http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous'},
+        'wsa:MessageID' => "urn:uuid:#{UUIDTools::UUID.random_create.to_s}" }
     end
   end
 end

data/lib/reps_client/community.rb

@@ -1,18 +1,39 @@
 require 'modelish'
 
 module RepsClient
-  # A community (i.e. location) as configured in the MDI REPS service.
+  # A community (i.e. location) as configured in the MDI Achieve REPS service.
   class Community < Modelish::Base
+    # @return [Integer] the unique identifier for the community in REPS.
+    # @note This ID will be required as an argument in most service calls.
     property :community_id, :from => :community_idy, :type => Integer
+
+    # @return [String] the name of the community
     property :name, :type => String
+
+    # @return [String] the first line of the community's street address
     property :address1, :from => :community_address1, :type => String
+
+    # @return [String] the second line of the community's street address
     property :address2, :from => :community_address2, :type => String
+
+    # @return [String] the city where the community is located
     property :city, :from => :community_city, :type => String
+
+    # @return [String] the state or territory where the community is located
     property :state, :from => :community_state, :type => String
+
+    # @return [String] the zip or postal code of the community
     property :zip, :from => :community_zip, :type => String
+
+    ignore_unknown_properties!
   end
 
   module CommunityMethods
+    # Retrieves a list of communities from the REPS web service.
+    # Note that all of the other service methods require a community ID
+    # that is returned by this method.
+    #
+    # @return [Array<RepsClient::Community>] the list of REPS communities
     def get_communities
       response = send_soap_request(:get_communities)
       communities = response.to_hash[:get_communities_response][:get_communities_result][:diffgram][:document_element][:community]

data/lib/reps_client/configuration.rb

@@ -1,34 +1,60 @@
 require 'configlet'
+require 'logger'
 
 module RepsClient
-  # All valid configurations options
-  VALID_CONFIG_OPTIONS = [:endpoint, :username, :password, :namespace, :enterprise_key]
+  # All possible configuration options
+  VALID_CONFIG_OPTIONS = [:endpoint, :username, :password, :namespace, :enterprise_key,
+                          :debug, :logger]
 
-  DEFAULT_ENDPOINT = 'https://repssuite.mdiachieve.com/webservices/lead.asmx?wsdl'
+  # The default endpoint (points to the REPS test server)
+  DEFAULT_ENDPOINT = 'https://repssuite.mdiachieve.com/webservices/lead.asmx'
+
+  # The default namespace for SOAP requests
   DEFAULT_NAMESPACE = 'http://www.mdiachieve.com/'
 
   module Configuration
     include Configlet
- 
+
     def self.extended(base)
       # Default configuration - happens whether or not .configure is called
       base.config :reps_client do
         default :endpoint => DEFAULT_ENDPOINT
         default :namespace => DEFAULT_NAMESPACE
+        default :debug => 'false'
       end
     end
 
-    # Mutators and accessors for configuration options
+    # Dynamically define mutators and accessors for configuration options
     VALID_CONFIG_OPTIONS.each do |config_opt|
       define_method(config_opt) do
         self[config_opt]
       end
 
       define_method("#{config_opt}=".to_sym) do |val|
-        self[config_opt] = val
+        self[config_opt] = val.nil? ? nil : val.to_s
       end
     end
 
+    # @attr [String] endpoint the service endpoint URL (defaults to RepsClient::DEFAULT_ENDPOINT)
+    # @attr [String] username the username for authentication
+    # @attr [String] password the password for authentication
+    # @attr [String] namespace the namespace for SOAP requests (defaults to RepsClient::DEFAULT_NAMESPACE)
+    # @attr [String] enterprise_key the corporate key required for all REPS requests
+    # @attr [true,false,String] debug set to true or 'true' to enable debug logging (defaults to false)
+
+    # @return [true,false] true if debug logging is enabled; false otherwie.
+    def debug?
+      self[:debug] == 'true'
+    end
+
+    # Sets the logger to use for debug messages
+    attr_writer :logger
+
+    # @return [Logger] the logger to use for debug messages (defaults to STDOUT)
+    def logger
+      @logger ||= Logger.new(STDOUT)
+    end
+
     # Configures this module through the given +block+.
     # Default configuration options will be applied unless 
     # they are explicitly overridden in the +block+.
@@ -48,6 +74,8 @@ module RepsClient
     #     config.endpoint = 'http://my.endpoint.com'
     #     config.namespace = 'http://my.namespace.com'
     #     config.enterprise_key = 'my_key'
+    #     config.debug = true
+    #     config.logger = Logger.new('my.log')
     #   end
     # @return [RepsClient] _self
     # @see VALID_CONFIG_OPTIONS

data/lib/reps_client/lead.rb

@@ -25,12 +25,12 @@ module RepsClient
   #                                     :state => 'CA',
   #                                     :zip_code => '12345')
   class Contact < Modelish::Base
-    # @attribute [rw] 
+    # @attribute [rw]
     # @return [String] the contact's salutation (e.g. "Mr.", "Ms.", "Dr.", etc.)
     # @see RepsClient::PickListMethods#get_pick_lists
     property :prefix, :type => String, :max_length => 30
 
-    # @attribute [rw] 
+    # @attribute [rw]
     # @return [String] the contact's first name
     # @note This attribute is required on initialization.
     property :first_name, :type => String, :required => true, :max_length => 30
@@ -88,11 +88,15 @@ module RepsClient
     property :email, :type => String, :max_length => 100
 
     # @attribute [rw]
-    # @return [int] the relationship type id describing the contact's relationship to the prospect
-    # @note The relationship type is determined based on the contact's answer to the question 'What
-    # is your relationship to the prospect?' For instance, if a contact was acting on behalf of their
-    # mother, the relationship type name might be 'Child'. Valid relationship types are available from
+    # @return [int] the relationship type id describing the relationship of the contact to the prospect
+    # @note REPS requires the "direction" of the relationship type to be the opposite of what most users expect.
+    #
+    # The relationship type is determined based on the contact's answer to the question "What
+    # is your relationship to the prospect?" For instance, if a contact was acting on behalf of their
+    # mother, the relationship type name might be "Child" or "Son" or "Daughter" (but definitely
+    # *not* "Mother" or "Parent"). Valid relationship types are available from
     # the remote service.
+    #
     # @see RepsClient::PickListMethods#get_pick_lists
     property :relationship_to_prospect_id, :type => Integer
 
@@ -105,7 +109,7 @@ module RepsClient
     property :include_in_emailings, :default => false, :type => lambda { |v| !!v }
 
     # @attribute [rw]
-    # @return [int]
+    # @return [int] the identifier for the lead source in REPS
     # @see RepsClient::PickListMethods#get_pick_lists
     # @note This attribute is required on initialization.
     property :source_id, :type => Integer, :required => true, :validate_type => true
@@ -269,7 +273,7 @@ module RepsClient
     # @param [Integer] community_id the REPS ID of the community
     # @param [RepsClient::Contact] contact the contact person for the lead
     # @param [RepsClient::Prospect] prospect the prospective resident (if different than contact)
-    #
+    # @return [true,false] true if the lead was saved succesfully; false otherwise
     def save_lead(community_id,contact,prospect=nil)
       LeadMethods.validate_required!(:community_id => community_id,
                                      :contact => contact)
@@ -285,7 +289,9 @@ module RepsClient
         soap_params[:order!] << :new_prospect
       end
 
-      send_soap_request(:save_lead, soap_params)
+      response = send_soap_request(:save_lead, soap_params).to_hash
+
+      response[:save_lead_response][:save_lead_result][:diffgram][:document_element].nil?
     end
   end
 end

data/lib/reps_client/pick_list.rb

@@ -1,25 +1,65 @@
 require 'modelish/validations'
 
 module RepsClient
+  # A name prefix from the REPS service.
+  # Equates to the dropdown list labeled "Prefix" on the Leads -> Contact and
+  # Prospect pages in REPS.
   class Prefix < Modelish::Base
+    # @return [int] the id of the prefix
     property :prefix_id, :from => :user_list_idy, :type => Integer
+
+    # @return [String] the display value of the prefix (e.g. "Mr.")
     property :value, :from => :list_value, :type => String
+
+    ignore_unknown_properties!
   end
 
+  # A name suffix from the REPS service.
+  # Equates to the dropdown list labeled "Suffix" on the Leads -> Contact and
+  # Prospect pages in REPS.
   class Suffix < Modelish::Base
+    # @return [int] the id of the suffix
     property :suffix_id, :from => :user_list_idy, :type => Integer
+
+    # @return [String] the display value of the suffix (e.g. "Jr.")
     property :value, :from => :list_value, :type => String
+
+    ignore_unknown_properties!
   end
 
+  # A type of relationship from the REPS service.
+  # Equates to the dropdown list labeled 'Relation to Resident' on the
+  # Leads -> Contact page in REPS.
+  #
+  # Note: Be careful of the direction of the relationship type. Many web pages
+  # ask about the relationship of the prospect to the contact (Q: For whom are
+  # you inquiring? A: Mother), but REPS uses the relationship of the contact
+  # to the prospect (Q: What is your relationship to the prospective resident?
+  # A: Daughter).
   class RelationshipType < Modelish::Base
+    # @return [int] the id of the relationship type
     property :relationship_type_id, :from => :relationship_type_idy, :type => Integer
+
+    # @return [String] the display name of the relationship type (e.g. "Daughter")
     property :name, :from => :relationship_name, :type => String
+
+    ignore_unknown_properties!
   end
 
+  # A lead source (e.g. print advertising, direct mail, referral, etc.)
+  # Equates to the dropdown list labeled 'Source 1' on the Leads -> Contact
+  # page in REPS.
   class Source < Modelish::Base
+    # @return [int] the id of the lead source
     property :source_id, :from => :source_idy, :type => Integer
+
+    # @return [String] the unique human-readable code identifying the source (e.g. 'KOIN-TV')
     property :code, :type => String
+
+    # @return [String] the description of the lead source (e.g. 'KOIN television ad campaign')
     property :description, :type => String
+
+    ignore_unknown_properties!
   end
 
   module PickListMethods
@@ -41,14 +81,15 @@ module RepsClient
     def get_pick_lists(community_id)
       PickListMethods.validate_required!(:community_id => community_id)
 
-      response = send_soap_request(:get_pick_lists, :community_id => community_id, :order! => [:enterprise_key,:community_id])
+      response = send_soap_request(:get_pick_lists, :community_id => community_id,
+                                   :order! => [:enterprise_key,:community_id])
       lists = response.to_hash[:get_pick_lists_response][:get_pick_lists_result][:diffgram][:pick_lists]
 
       result = {}
       [:prefix, :suffix, :relationship_type, :source].each do |k|
         result[k] = process_pick_list(k, lists)
       end
-    
+
       result
     end
 

data/lib/reps_client/version.rb

@@ -1,3 +1,4 @@
 module RepsClient
-  VERSION = '0.0.1'
+  # The current version of this library
+  VERSION = '0.1.0'
 end

data/lib/reps_client.rb

@@ -5,8 +5,4 @@ module RepsClient
   extend Configuration
 
   require 'reps_client/client'
-
-  Modelish.configure do |config|
-    config.ignore_unknown_properties = true
-  end
 end

data/reps_client.gemspec

@@ -14,13 +14,14 @@ Gem::Specification.new do |s|
 
   s.files = `git ls-files`.split("\n")
   s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
-  
+
   s.require_paths = ["lib"]
 
   s.add_dependency('modelish', '>=0.1.3')
   s.add_dependency('configlet', '~>2.1')
-
+  s.add_dependency('uuidtools', '~>2.1.2')
   s.add_dependency('savon', '~>0.9.7')
+
   s.add_development_dependency('savon_spec', '~>0.1')
 
   s.add_development_dependency('rspec', '~>2.6')