eloqua 1.1.0

data/lib/eloqua/asset.rb

@@ -0,0 +1,31 @@
+require 'eloqua/remote_object'
+
+module Eloqua
+  
+  class Asset < RemoteObject
+    
+    self.remote_group = :asset
+
+    def add_member(entity)
+      member_operation(:add_group_member, entity)
+    end
+
+    def remove_member(entity)
+      member_operation(:remove_group_member, entity)
+    end
+    
+    private
+
+    def member_operation(method, entity)
+      unless (entity.is_a?(Eloqua::Entity))
+        raise(ArgumentError, "Must pass a Eloqua::Entity")
+      end
+      unless (entity.persisted?)
+        raise(ArgumentError, "Cannot add member Entity has not been saved. (!entity.persisted?")
+      end
+      api.send(method, remote_type, id, entity.remote_type, entity.id)
+    end
+
+  end
+  
+end

data/lib/eloqua/builder/templates.rb

@@ -0,0 +1,31 @@
+module Eloqua
+  module Builder
+
+    module Templates
+
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :builder_templates
+        self.builder_templates = {}
+      end
+
+      module ClassMethods
+
+        def builder_template(name, *args)
+          template = builder_templates[name]
+          Proc.new do |xml|
+            template.call(xml, *args)
+          end
+        end
+
+        def define_builder_template(name, &block)
+          builder_templates[name] = block
+        end
+      end
+
+    end
+
+
+  end
+end

data/lib/eloqua/builder/xml.rb

@@ -0,0 +1,129 @@
+require 'eloqua/builder/templates'
+
+module Eloqua
+
+  module Builder
+
+    # This could (and likely should) be submitted as a patch for
+    # the main builder class
+    class Xml < ::Builder::XmlMarkup
+
+      include Eloqua::Builder::Templates
+
+      # XML Templates
+
+      # For use with strings and integers may do strange
+      # things on the SOAP server side if given a float
+      define_builder_template :array do |xml, array|
+        array.each do |element|
+          tag = 'string'
+          if(element.is_a?(String))
+            tag = 'string'
+          elsif(element.is_a?(Numeric))
+            tag = 'int'
+          end
+          xml.arr(tag.to_sym, element)
+        end
+      end
+
+      define_builder_template :int_array do |xml, array|
+        array.each do |element|
+          unless(element.is_a?(Numeric))
+            element = element.to_i
+            if(element == 0 || !element)
+              next
+            end
+          end
+          xml.arr(:int, element)
+        end
+      end
+
+      # For use with add/remove membership
+      define_builder_template :object do |xml, object_type, type, id|
+        xml.tag!(object_type) do
+          xml.object_type!(object_type) do
+            xml.template!(:object_type, type)
+          end
+          xml.Id(id)
+        end
+      end
+
+      # For use with the entity function
+      define_builder_template :object_type do |xml, object|
+        xml.ID(object[:id])
+        xml.Name(object[:name])
+        xml.Type(object[:type])
+      end
+
+      # defines entity attribute fields for use in update/create
+      define_builder_template :fields do |xml, object_type, entity_attributes|
+        entity_attributes.each do |attribute, value|
+          xml.tag!("#{object_type.to_s.camelize}Fields") do
+            xml.InternalName(attribute.to_s)
+            xml.Value(value)
+          end
+        end
+      end
+
+      # Dynamic entity for update/create/etc...
+
+      define_builder_template :dynamic do |xml, object_type, type, id, attributes|
+        xml.tag!("#{object_type.to_s.camelize}Type") do
+          xml.template!(:object_type, type)
+        end
+
+        xml.FieldValueCollection do
+          xml.template!(:fields, object_type, attributes)
+        end
+
+        xml.Id(id) if id
+      end
+
+      delegate :builder_template, :to => self
+
+
+      def initialize(options = {}, &block)
+        super
+        @namespace = nil
+        @namespace = options[:namespace].to_sym if options[:namespace]
+        yield self if block_given?
+      end
+
+      def self.create(options = {}, &block)
+        new(options, &block).target!
+      end
+
+      def template!(template, *args)
+        builder_template(template, *args).call(self)
+      end
+
+      def dynamic_object!(sym, *args, &block)
+        tag!("Dynamic#{sym.to_s.camelize}", *args, &block)
+      end
+
+      def object_type!(sym, *args, &block)
+        tag!("#{sym.to_s.camelize}Type", *args, &block)
+      end
+
+      def object_type_lower!(sym, *args, &block)
+        tag!("#{sym}Type", *args, &block)
+      end
+
+      def object_collection!(sym, *args, &block)
+        tag!("#{sym.to_s.pluralize.downcase}", *args, &block)
+      end
+
+      # Extend to allow default namespace
+      def method_missing(sym, *args, &block)
+        if(@namespace && !args.first.kind_of?(Symbol))
+          args.unshift(sym.to_sym)
+          sym = @namespace
+        end
+        super(sym, *args, &block)
+      end
+
+    end
+
+  end
+
+end

data/lib/eloqua/entity.rb

@@ -0,0 +1,72 @@
+require 'eloqua/remote_object'
+
+module Eloqua
+  
+  class Entity < RemoteObject
+    
+    self.remote_group = :entity
+
+    # Returns an :id indexed list of memberships for contact
+    # 
+    #     # Example output
+    #     {'1' => {:id => '1', :name => 'Contact Group Name', :type => 'ContactGroup}}
+    #
+    # @return [Hash] Integer => Hash
+    def list_memberships
+      self.class.list_memberships(id)
+    end
+
+    def add_membership(asset)
+      asset.add_member(self)
+    end
+
+    def remove_membership(asset)
+      asset.remove_member(self)
+    end
+
+    class << self
+
+      # Returns an :id indexed list of memberships for given contact id
+      # 
+      #     # Example output
+      #     {'1' => {:id => '1', :name => 'Contact Group Name', :type => 'ContactGroup}}
+      #
+      # @param [String, Integer] contact id
+      # @return [Hash] Integer => Hash
+      def list_memberships(id)
+        memberships = api.list_memberships(remote_type, id)
+
+        if(memberships && !memberships.empty?)
+          memberships.inject({}) do |map, membership|
+            map[membership[:id]] = membership
+            map
+          end
+        else
+          memberships || {}
+        end
+          
+      end
+
+      def where(conditions = nil, fields = [], limit = 200, page = 1)
+				if(conditions)
+					query = where
+					conditions.each do |key, value|
+						query.on(key, '=', value)
+					end
+					query.fields(fields) if fields
+					query.limit(limit)
+					query.page(page)
+					results = query.all
+					if(results.blank?)
+						false
+					else
+						results
+					end
+				else
+					Eloqua::Query.new(self)
+				end
+      end      
+    end
+    
+  end
+end

data/lib/eloqua/exceptions.rb

@@ -0,0 +1,5 @@
+class Eloqua::RemoteError < StandardError; end
+class Eloqua::DuplicateRecordError < Eloqua::RemoteError; end
+
+class Eloqua::SoapError < Savon::SOAP::Fault; end
+class Eloqua::HTTPError < Savon::HTTP::Error; end

data/lib/eloqua/helper/attribute_map.rb

@@ -0,0 +1,78 @@
+module Eloqua
+  module Helper
+
+    module AttributeMap
+
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :attribute_map, :attribute_map_reverse
+
+        attr_reader :instance_reverse_keys
+
+        self.attribute_map = {}.with_indifferent_access
+        self.attribute_map_reverse = {}.with_indifferent_access
+
+        class << self
+          alias_method_chain :inherited, :clone_attributes
+        end
+
+      end
+
+      module ClassMethods
+
+        def inherited_with_clone_attributes(klass)
+          klass.attribute_map = attribute_map.clone
+          klass.attribute_map_reverse = attribute_map_reverse.clone
+          inherited_without_clone_attributes(klass) if method_defined?(:inherited_without_clone_attributes)
+        end
+
+        def eloqua_attribute(attribute)
+          (attribute_map_reverse.fetch(attribute) { attribute }).to_s
+        end
+
+        def map_attribute(attribute)
+          attribute_map.fetch(attribute) { attribute.to_s }
+        end
+
+         # This shoud always be used over directly editing attribute_map
+         def map(hash)
+           hash.each do |key, value|
+             value = value.to_sym
+             key = key.to_sym
+
+             attribute_map[key] = value
+             attribute_map_reverse[value] = key
+          end
+        end
+
+      end
+
+      module InstanceMethods
+
+        def map_attributes(attributes)
+          @instance_reverse_keys ||= attribute_map_reverse.clone
+          results = {}.with_indifferent_access
+
+          attributes.each do |key, value|
+            formatted_key = attribute_map.fetch(key) { key.to_s.gsub(/^C_/, '').underscore }
+            @instance_reverse_keys[formatted_key] = key
+            results[formatted_key] = value
+          end
+          results
+        end
+
+        def reverse_map_attributes(attributes)
+          results = {}.with_indifferent_access
+          attributes.each do |key, value|
+            results[@instance_reverse_keys.fetch(key){key}] = value
+          end
+          results
+        end
+
+      end
+
+    end
+
+  end
+end

data/lib/eloqua/query.rb

@@ -0,0 +1,291 @@
+require 'eloqua/api/service'
+require 'eloqua/remote_object'
+
+module Eloqua
+  class Query
+
+    delegate :api, :to => :remote_object
+
+    attr_reader :collection, :remote_object, :conditions, :total_pages
+    attr_internal :current_page, :query_started
+
+
+    # The amount of time in seconds to wait before sending another request to Eloqua
+    @@request_delay = 1
+    cattr_accessor :request_delay
+
+    # Create a new query to attach conditions to.
+    #
+    #     class Contact < Eloqua::Entity
+    #       remote_type = api.remote_type('Contact')
+    #     end
+    #
+    #     Eloqua::Query.new(Contact)
+    #
+    # @param [Eloqua::RemoteObject] or one of its descendants
+    def initialize(remote_object)
+      unless(remote_object.is_a?(Class) && Eloqua::RemoteObject >= remote_object)
+        raise(ArgumentError, 'must provide an Eloqua::RemoteObject or one of its descendants')
+      end
+
+      @page = 1
+      @limit = 200
+      @collection = []
+      @remote_object = remote_object
+      @conditions = []
+      @fields = nil
+      @has_requested = false
+    end
+
+
+    ## CHAIN-ABLES they reset the has_requested? but do not clear the collection
+
+    # Sets or gets limit
+    #
+    #     query.limit(5) # sets limit returns self
+    #     query.limit # returns 5
+    #
+    # @param [Integer]
+    # @return [self, Integer]
+    def limit(value = nil); end
+
+    # Sets or gets page
+    #
+    #     query.page(5) # sets limit returns self
+    #     query.page # returns 5
+    #
+    # @param [Integer]
+    # @return [self, Integer]
+    #
+    def page(value = nil); end
+
+    # Sets or gets the array of fields to find.
+    # Can use a literal string or a symbol of a {Eloqua::RemoteObject#map mapped} attribute
+    #
+    #     query.fields([:email, 'Date'])
+    #     query.fields # returns [:email, 'Date']
+    #
+    # @see Eloqua::RemoteObject::map
+    # @param [Array]
+    # @return [self, Array]
+    def fields(value = nil); end
+
+
+    # This mess defines the limit and page getter/setter methods
+    # when they are set they will also set #has_requested? to false
+    [:fields, :limit, :page].each do |attr|
+      class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
+        remove_method(:#{attr})
+        def #{attr}(value = nil)
+          if(value.nil?)
+            @#{attr}
+          else
+            @has_requested = false
+            @#{attr} = value
+            self
+          end
+        end
+      RUBY
+    end
+
+    # Clears all conditions added by {on}
+    #
+    #                       query.on(:id, '>', '1')
+    #                       query.clear_conditions!
+    #
+    def clear_conditions!
+      @has_requested = false
+      conditions.clear
+    end
+
+    # Adds a condition to the query; may be chained.
+    #
+    #     query.on(:email, '=', 'value').on('created_at', '>', '2011-04-20')
+    #
+    # @param [String, Symbol] field name
+    # @param [String] operator can use: `[ =, !=, <, >, >=, <=]`
+    # @param [String] value to search for
+    # @return self
+    def on(field, operator, value)
+      @has_requested = false
+      @conditions << {
+        :field => field,
+        :type => operator,
+        :value => value
+      }
+      self
+    end
+
+
+    # Send the built request to eloqua
+    #
+    #     query.on(:email, '=', '*') # wildcard
+    #     query.request!
+    #     query.collection # Array of results
+    #     query.current_page # Current page
+    #     query.total_pages # Number of pages
+    #
+    # @return self
+    def request!
+      return if has_requested?
+      sleep_for = wait_for_request_delay
+      if(sleep_for)
+        sleep(sleep_for)
+      end
+      xml_query = api.builder do |xml|
+        xml.eloquaType do
+          xml.template!(:object_type, remote_object.remote_type)
+        end
+        xml.searchQuery(build_query)
+
+        # This won't harm anything but it is changing the
+        # fields to its mapped elouqa name.
+        if(!fields.blank? && fields.is_a?(Array))
+          fields.map! do |field|
+            field = remote_object.eloqua_attribute(field)
+          end
+          xml.fieldNames do
+            xml.template!(:array, fields)
+          end
+        end
+
+        xml.pageNumber(page)
+        xml.pageSize(limit)
+      end
+
+      # Add timestamp of when we made request
+      @_query_started = Time.now
+      result = api.request(:query, xml_query)
+
+      # Clear collection
+      collection.clear
+
+      # Mark as requested
+      @has_requested = true
+
+
+      if(result[:entities])
+        @total_pages = result[:total_pages].to_i
+        entities = Eloqua.format_results_for_array(result, :entities, :dynamic_entity)
+        records = entities.inject([]) do |records, entity|
+          record_attrs = {}
+          entity_id = entity[:id]
+          entity[:field_value_collection][:entity_fields].each do |entity_attr|
+            record_attrs[entity_attr[:internal_name]] = entity_attr[:value]
+          end
+          record_attrs[remote_object.primary_key] = entity_id
+          record_object = remote_object.new(record_attrs, :remote)
+
+          collection << record_object
+        end
+        collection
+      else
+        @total_pages = 0
+        false
+      end
+    end
+
+    def wait_for_request_delay
+      if(request_delay && query_started)
+        now = Time.now
+        wait_until = Time.at((request_delay + query_started.to_f))
+        if(wait_until > now)
+          wait_until - now
+        end
+      else
+        false
+      end
+    end
+
+
+    # Has the request been made yet?
+    #
+    #     query.has_requested? # false
+    #     query.on(:email, '=', '*').request!
+    #     query.has_requested? # true
+    #
+    # @return [Boolean]
+    def has_requested?
+      @has_requested
+    end
+
+    # Sends request if not already set and iterates through result
+    #
+    #                       query.each do |record|
+    #                               record.class # query.remote_object
+    #                       end
+    #
+    # Currently this is a shortcut for
+    #
+    #                       query.all.each do |record|
+    #                               ...
+    #                       end
+    #
+    # @param [Proc] a block iterator
+    def each(&block)
+      all.each(&block)
+    end
+
+    # Sends request and returns collection
+    #
+    #     query.on(:email, '=', '*').all # => [Eloqua::RemoteObject.new(), ...]
+    #
+    # @return [Array] collection of Eloqua::RemoteObject
+    def all
+      request!
+      collection
+    end
+
+    # Iterates through each page up to max_pages
+    # when max_pages is nil (default) will iterate through
+    # each page yielding a block with a record.
+    #
+    # with max_pages you could and then resume the loop through
+    # pages
+    #
+    #                       query.each_page(2) |record|
+    #                               query.total_pages # 10
+    #                               query.page # 1 ... 2
+    #                       end
+    #
+    #                       ...
+    #
+    #                       query.each_page(2) |record|
+    #                               query.total_pages # 10
+    #                               query.page # 3 ... 4
+    #                       end
+    #
+    # @see Query#each
+    # @param [Integer] max pages to iterate through
+    def each_page(max_pages = nil, &block)
+      each(&block)
+      while(total_pages > page)
+        break if max_pages && page >= max_pages
+        page(page + 1)
+        each(&block)
+      end
+    end
+
+    protected
+
+    # Builds query from conditions
+    # conditions are assembled by their field, type and then value as below
+    #
+    #     #{field}#{type}'#{value}'
+    #
+    # then joined by AND which acts more like an SQL "OR" in Eloqua
+    # > and < are escaped with &gt; and &lt;
+    def build_query
+      conditions.inject([]) do |parts, cond|
+        part = ""
+        part << remote_object.eloqua_attribute(cond[:field])
+        part << cond[:type].to_s
+        part << "'#{cond[:value]}'"
+        parts << part
+      end.join(" AND ")
+    end
+
+
+  end
+end
+