yardi 4.0.8

data/lib/yardi/request_section.rb

@@ -0,0 +1,24 @@
+module Yardi
+  # ALL REQUEST SECTIONS* must define a #generate method which builds their
+  # corresponding XML
+  # #generate returns a Nokogiri::DocumentFragment.
+  # Example:
+  # class TestSectionFoo
+  #   def generate
+  #     foo_fragment = Nokogiri::XML::DocumentFragment.parse('')
+  #
+  #     Nokogiri::XML::Builder.with(foo_fragment) do |foo_xml|
+  #       foo_xml.Foo 'foo_value'
+  #     end
+  #
+  #     foo_fragment
+  #   end
+  # end
+  #
+  # * the auth section has a different signature for #generate because it is
+  # the only section that is namespaced.
+  module RequestSection
+  end
+
+  private_constant :RequestSection
+end

data/lib/yardi/request_section/authentication.rb

@@ -0,0 +1,24 @@
+require 'yardi/request_section'
+
+module Yardi
+  module RequestSection
+    # Generate the auth section of a Yardi request
+    class Authentication
+      attr_reader :credential
+
+      def initialize(credential)
+        @credential = credential
+      end
+
+      def generate(xml_builder)
+        xml_builder['itf'].UserName credential.username
+        xml_builder['itf'].Password credential.password
+        xml_builder['itf'].ServerName credential.server
+        xml_builder['itf'].Database credential.database
+        xml_builder['itf'].Platform Yardi.config.platform
+        xml_builder['itf'].InterfaceEntity Yardi.config.entity
+        xml_builder['itf'].InterfaceLicense Yardi.config.license_key
+      end
+    end
+  end
+end

data/lib/yardi/request_section/lead_management.rb

@@ -0,0 +1,148 @@
+require 'yardi/request_section'
+
+module Yardi
+  module RequestSection
+    # Generate the LeadManagement section of a Yardi request
+    class LeadManagement
+      def initialize(agent:, lead_source:, property:, reason:, user:)
+        @agent = agent
+        @lead_source = lead_source
+        @property = property
+        @reason = reason
+        @user = user
+      end
+
+      def generate(xml_builder)
+        xml_builder.LeadManagement do |lead_management_xml|
+          lead_management_xml.Prospects do |prospects_xml|
+            prospect_xml(prospects_xml)
+          end
+        end
+      end
+
+      private
+
+      attr_reader :agent, :lead_source, :property, :reason, :user
+
+      def prospect_xml(xml_builder)
+        xml_builder.Prospect do |prospect_xml|
+          customers_xml(prospect_xml)
+          preferences_xml(prospect_xml)
+
+          prospect_xml.Events do |events_xml|
+            first_contact_event_xml(events_xml)
+            tour_xml(events_xml) unless property.tour_time.nil?
+          end
+        end
+      end
+
+      def customers_xml(xml_builder)
+        xml_builder.Customers do |customers_xml|
+          customers_xml.Customer('Type' => 'prospect') do |customer_xml|
+            # ID nodes are empty nodes with attributes
+            customer_xml.Identification(apartmentlist_id_attributes) {}
+            customer_xml.Identification(yardi_id_attributes) {}
+            name_xml(customer_xml)
+            contact_information_xml(customer_xml)
+          end
+        end
+      end
+
+      def name_xml(xml_builder)
+        xml_builder.Name do |name_xml|
+          name_xml.FirstName user.first_name
+          name_xml.LastName user.last_name
+        end
+      end
+
+      def contact_information_xml(xml_builder)
+        phone_xml(user.contact_info.home_phone, 'home', xml_builder)
+        phone_xml(user.contact_info.cell_phone, 'cell', xml_builder)
+        xml_builder.Email user.contact_info.email
+      end
+
+      def phone_xml(number, type, xml_builder)
+        if number
+          xml_builder.Phone('PhoneType' => type) do |phone_xml|
+            phone_xml.PhoneNumber number
+          end
+        end
+      end
+
+      def apartmentlist_id_attributes
+        {
+          'IDType' => 'ThirdPartyID',
+          'IDValue' => user.id, # AL User ID
+          'OrganizationName' => 'Apartment List'
+        }
+      end
+
+      def yardi_id_attributes
+        {
+          'IDType' => 'PropertyID',
+          'IDValue' => property.remote_id,
+          'OrganizationName' => 'Yardi'
+        }
+      end
+
+      def preferences_xml(xml_builder)
+        xml_builder.CustomerPreferences do |preferences_xml|
+          preferences_xml.TargetMoveInDate user.move_in_date.to_s
+          preferences_xml.DesiredFloorplan user.preferred_floorplan_id
+          # Rent and bedrooms are empty nodes with attributes for values.
+          # Yardi doesn't like having an empty string for either of these
+          # attributes, so we leave the node out if we don't have any data.
+          unless user.price.nil?
+            preferences_xml.DesiredRent('Exact' => user.price) {}
+          end
+
+          unless user.beds.nil?
+            preferences_xml.DesiredNumBedrooms('Exact' => user.beds) {}
+          end
+
+          preferences_xml.Comment user.preference_notes
+        end
+      end
+
+      def first_contact_event_xml(xml_builder)
+        event_attrs = {
+          'EventDate' => property.first_contact_time.iso8601,
+          'EventType' => 'Email'
+        }
+        xml_builder.Event(event_attrs) do |event_xml|
+          agent_xml(event_xml)
+          event_xml.EventReasons reason
+          event_xml.FirstContact true
+          event_xml.Comments user.message
+          event_xml.TransactionSource lead_source
+        end
+      end
+
+      def agent_xml(xml_builder)
+        xml_builder.Agent do |agent_xml|
+          agent_xml.AgentName do |agent_name_xml|
+            agent_name_xml.FirstName agent.first_name
+            agent_name_xml.LastName  agent.last_name
+          end
+        end
+      end
+
+      def tour_xml(xml_builder)
+        event_attrs = {
+          'EventDate' => property.tour_time.iso8601,
+          'EventType' => 'Appointment'
+        }
+        tour_id_attrs = {
+          'IDValue' => property.tour_remote_id || 0,
+          'IDType' => user.preferred_unit_id
+        }
+        xml_builder.Event(event_attrs) do |event_xml|
+          event_xml.EventID(tour_id_attrs)
+          agent_xml(event_xml)
+          event_xml.EventReasons reason
+          event_xml.Comments property.tour_notes
+        end
+      end
+    end
+  end
+end

data/lib/yardi/request_section/prospect.rb

@@ -0,0 +1,27 @@
+require 'yardi/request_section'
+
+module Yardi
+  module RequestSection
+    # Generate the data needed for a ProspectSearch
+    class Prospect
+      attr_reader :property_id, :prospect
+
+      def initialize(property_id:, prospect:)
+        @property_id = property_id
+        @prospect = prospect
+      end
+
+      # Even though we may not send data for some fields, Yardi needs empty
+      # nodes or the request fails.
+      def generate(xml_builder)
+        xml_builder['itf'].YardiPropertyId property_id
+        xml_builder['itf'].FirstName prospect.first_name
+        xml_builder['itf'].LastName prospect.last_name
+        xml_builder['itf'].EmailAddress prospect.email
+        xml_builder['itf'].PhoneNumber prospect.phone
+        xml_builder['itf'].ThirdPartyId prospect.yardi_prospect_id
+        xml_builder['itf'].FederalId
+      end
+    end
+  end
+end

data/lib/yardi/request_section/residents.rb

@@ -0,0 +1,18 @@
+require 'yardi/request_section'
+
+module Yardi
+  module RequestSection
+    # Generate the data needed for a GetResidents call
+    class Residents
+      attr_reader :property_id
+
+      def initialize(property_id:)
+        @property_id = property_id
+      end
+
+      def generate(xml_builder)
+        xml_builder['itf'].YardiPropertyId property_id
+      end
+    end
+  end
+end

data/lib/yardi/utils.rb

@@ -0,0 +1,6 @@
+module Yardi
+  module Utils
+  end
+
+  private_constant :Utils
+end

data/lib/yardi/utils/configuration_validator.rb

@@ -0,0 +1,17 @@
+require 'yardi/utils'
+
+module Yardi
+  module Utils
+    class ConfigurationValidator
+      def validate!
+        missing_keys = Yardi::CONFIG_KEYS.select do |key|
+          Yardi.config.send(key).nil?
+        end
+        unless missing_keys.empty?
+          raise Error::InvalidConfiguration,
+                "Missing configuration for #{missing_keys.join(', ')}"
+        end
+      end
+    end
+  end
+end

data/lib/yardi/utils/phone_parser.rb

@@ -0,0 +1,23 @@
+require 'yardi/utils'
+
+module Yardi
+  module Utils
+    class PhoneParser
+      # A single prospect/resident can have have 0 to many <Phone> nodes, so
+      # prospect/resident['Phone'] can have three different types:
+      #   nil if there's no phone included
+      #   a Hash representing a single phone number if there's one phone
+      #   an Array if there are multiple phones
+      # @param phone [nil|Hash|Array]
+      # @return [Array<String>] if at least one `PhoneNumber` exists, or nil
+      #   otherwise.
+      def self.parse(phone)
+        if phone.is_a?(Array)
+          phone.map { |ph| ph['PhoneNumber'] }.compact
+        elsif phone && phone['PhoneNumber']
+          [phone['PhoneNumber']]
+        end
+      end
+    end
+  end
+end

data/lib/yardi/utils/request_fetcher.rb

@@ -0,0 +1,47 @@
+require 'faraday'
+
+require 'yardi/utils'
+require 'yardi/utils/configuration_validator'
+
+module Yardi
+  module Utils
+    # Send a SOAP request to Yardi
+    class RequestFetcher
+      # @param generator [RequestGenerator] an instance of a RequestGenerator,
+      #   which responds to #generate.
+      # @param connection [Faraday::Connection] The connection we'll use to
+      #   make the request
+      def initialize(connection:, endpoint:, generator:)
+        @connection = connection
+        @endpoint = endpoint
+        @generator = generator
+      end
+
+      # @return [String] the XML response from Yardi
+      def fetch
+        ConfigurationValidator.new.validate!
+
+        response = perform!
+
+        if response.status == 404
+          raise Yardi::Error::ResourceNotFound, response.body
+        end
+
+        response.body
+      end
+
+      private
+
+      attr_reader :connection, :endpoint, :generator
+
+      def perform!
+        connection.post(endpoint) do |request|
+          request.body = generator.body
+          request.headers = generator.headers
+        end
+      rescue Errno::EADDRNOTAVAIL => error
+        raise Yardi::Error::ConnectionError, error.message
+      end
+    end
+  end
+end

data/lib/yardi/utils/request_generator.rb

@@ -0,0 +1,88 @@
+require 'nokogiri'
+require 'yardi/utils'
+
+module Yardi
+  module Utils
+    # Generate a SOAP request for a specific action and sections
+    class RequestGenerator
+      URL_BASE = 'http://tempuri.org/YSI.Interfaces.WebServices'.freeze
+
+      # @param soap_action [String] the action to request from Yardi.
+      # @param sections [Array<RequestSection>] the section generators that will
+      #   be used to generate the body of the XML request
+      def initialize(soap_action, sections, interface)
+        @soap_action = soap_action
+        @sections = sections
+        @interface = interface
+      end
+
+      # @return [String] the XML request for the specified action and sections
+      def body
+        xml_env = build_envelope do |xml_builder|
+          # This section is the only one inside of the itf namespace
+          xml_builder['itf'].send(soap_action) do
+            sections[:soap_body].each do |section|
+              section.generate(xml_builder)
+            end
+
+            xml_builder['itf'].XmlDoc 'REPLACE_ME' if xml_doc_sections?
+          end
+        end
+
+        # This is a hack to handle Nokogiri's behavior with namespaces and still
+        # build XML that adheres to Yardi's spec.
+        # https://github.com/sparklemotion/nokogiri/issues/425
+        # When inserting a child node, it will automatically inherit its
+        # parent's namespace. Unfortunately, Yardi only wants a select bunch of
+        # the parent nodes to be namespaced and the bulk of the child nodes
+        # (everything inside of the namespaced <itf:XmlDoc> node) to be without
+        # a namespace. In order to make this happen, we build the bulk of the
+        # xml inside #xml_doc_body, then do a string replace to plop it into
+        # the properly namespaced parent node.
+        xml_doc_sections? ? xml_env.sub('REPLACE_ME', xml_doc_body) : xml_env
+      end
+
+      def xml_doc_body
+        return nil if sections[:xml_doc].nil?
+        body_fragment = Nokogiri::XML::DocumentFragment.parse('')
+        Nokogiri::XML::Builder.with(body_fragment) do |xml_builder|
+          sections[:xml_doc].each do |section|
+            section.generate(xml_builder)
+          end
+        end
+        body_fragment.to_xml
+      end
+
+      def build_envelope(&block)
+        Nokogiri::XML::Builder.new do |xml|
+          xml.Envelope(envelope) do
+            xml.parent.namespace = xml.parent.namespace_definitions.first
+            xml['soapenv'].Body(&block)
+          end
+        end.to_xml
+      end
+
+      def headers
+        {
+          'Content-Type' => 'text/xml; charset=utf-8',
+          'SOAPAction' => "#{URL_BASE}/#{interface}/#{soap_action}"
+        }
+      end
+
+      private
+
+      attr_reader :soap_action, :sections, :interface
+
+      def xml_doc_sections?
+        !sections[:xml_doc].empty?
+      end
+
+      def envelope
+        {
+          'xmlns:soapenv' => 'http://schemas.xmlsoap.org/soap/envelope/',
+          'xmlns:itf' => "#{URL_BASE}/#{interface}"
+        }.freeze
+      end
+    end
+  end
+end

data/lib/yardi/validator.rb

@@ -0,0 +1,6 @@
+module Yardi
+  module Validator
+  end
+
+  private_constant :Validator
+end

data/lib/yardi/validator/empty_response.rb

@@ -0,0 +1,43 @@
+require 'yardi/validator'
+
+module Yardi
+  module Validator
+    # Ensure that the response contains data. Sometimes Yardi will respond with
+    # just the outer shell of XML. For an example, @see empty_response.xml.
+    # We will also raise an error if Yardi returns a completely empty response.
+    class EmptyResponse
+      # @param parsed_response [Hash<String, Object>] the XML response parsed
+      #   into a Hash
+      # @param action [String] The SOAP action this response is for. Yardi's
+      #   responses have nodes whose names include the SOAP action for the
+      #   request that was made.
+      def initialize(action:, parsed_response:)
+        @action = action
+        @response = parsed_response
+      end
+
+      # @raise [Yardi::Error::EmptyResponse] if the response is effectively
+      #   empty
+      def validate!
+        return unless error?
+        raise Error::EmptyResponse, 'Yardi response contains no Result node.'
+      end
+
+      private
+
+      attr_reader :action, :response
+
+      def error?
+        return true if response.empty?
+
+        envelope = response['soap:Envelope']
+        return true if envelope.nil?
+
+        body = envelope['soap:Body']
+        # Fault responses will be handled by the FaultResponse validator
+        return false unless body['soap:Fault'].nil?
+        body["#{action}Response"]["#{action}Result"].nil?
+      end
+    end
+  end
+end