eloqua 1.1.0

data/.gitignore

@@ -0,0 +1,11 @@
+eloqua_initializer.rb
+.DS_Store
+irb.rb
+.bundle
+.idea
+doc
+.yardoc
+test.rb
+spec/reports
+*.gem
+.rvmrc

data/.yardopts

@@ -0,0 +1,2 @@
+--title "Eloqua API"
+-m markdown

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+## 0.2.3
+ - Added last_request, last_response to Eloqua::API
+
+ - Added wrapper around the Savon SOAP and HTTP exceptions.
+   Savon should disable its error handling and let Eloqua raise its own
+   errors by using `Savon::configure {|config| config.raise_errors =
+   false }`. This allows us to capture last_request and last_response
+   even when there is a Soap or HTTP fault
+
+## 0.2
+ - Abstracted out majority of requests into Eloqua::Api::Service
+
+ - Added Eloqua::Api::Service for a lightweight interface to Eloqua used
+	 by other components like RemoteObject, Entity and Asset
+
+ - Eloqua::Query advanced Query builder with support for paging through
+	 the entire set of records spanning multiple requests
+
+
+## 0.1
+ - Initial Release
+
+ - Support for Service Api

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,81 @@
+PATH
+  remote: .
+  specs:
+    eloqua (1.1.0)
+      activemodel
+      activesupport (= 3.0.6)
+      builder
+      i18n (= 0.5.0)
+      savon
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.0.6)
+      activesupport (= 3.0.6)
+      builder (~> 2.1.2)
+      i18n (~> 0.5.0)
+    activesupport (3.0.6)
+    archive-tar-minitar (0.5.2)
+    builder (2.1.2)
+    ci_reporter (1.6.4)
+      builder (>= 2.1.2)
+    columnize (0.3.6)
+    crack (0.1.8)
+    diff-lcs (1.1.2)
+    flexmock (0.9.0)
+    gyoku (0.4.2)
+      builder (>= 2.1.2)
+    httpi (0.9.2)
+      ntlm-http (>= 0.1.1)
+      rack
+    i18n (0.5.0)
+    linecache19 (0.5.12)
+      ruby_core_source (>= 0.1.4)
+    mocha (0.9.12)
+    ntlm-http (0.1.1)
+    rack (1.2.2)
+    rspec (2.5.0)
+      rspec-core (~> 2.5.0)
+      rspec-expectations (~> 2.5.0)
+      rspec-mocks (~> 2.5.0)
+    rspec-core (2.5.1)
+    rspec-expectations (2.5.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.5.0)
+    ruby-debug-base19 (0.11.25)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby_core_source (>= 0.1.4)
+    ruby-debug19 (0.11.6)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby-debug-base19 (>= 0.11.19)
+    ruby-fsevent (0.2.1)
+    ruby_core_source (0.1.5)
+      archive-tar-minitar (>= 0.5.2)
+    savon (0.8.6)
+      builder (>= 2.1.2)
+      crack (~> 0.1.8)
+      gyoku (>= 0.3.0)
+      httpi (>= 0.7.8)
+    savon_spec (0.1.4)
+      mocha (>= 0.9.8)
+      rspec (>= 2.0.0)
+      savon (~> 0.8.0)
+    timecop (0.3.5)
+    watchr (0.7)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  ci_reporter
+  eloqua!
+  flexmock
+  rspec
+  ruby-debug19
+  ruby-fsevent
+  savon_spec
+  timecop
+  watchr

data/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2011 Sahaja James Lal
+
+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,245 @@
+# Eloqua API for Ruby
+
+Currently supports the majority of the ServiceAPI for Eloqua.
+
+The Service API supports the CURD of Entities (Contacts, etc..) and Assets (ContactGroups)
+
+Through {Eloqua::Query} supports advanced queries spanning multiple
+requests.
+
+## At a low level
+
+For low level requests we offer the {Eloqua::Api::Service} (other Api's
+soon) with the "api" you can make calls like this:
+
+		Eloqua::Api::Service.describe_type(:asset, 'ContactGroup')
+
+The majority of the functions in the api require a "group" which
+is either :entity or :asset.
+
+The other common object you will need to have on hand is the "type"
+both entities and assets in Eloqua have types. Types look like this:
+
+		{
+			:id => 1,
+			:type => 'Base',
+			:name => 'Contact'
+		}
+
+The most important thing is the :type. See
+ {Eloqua::Api::Service.describe} and {Eloqua::Api::Service.describe_type}
+eloqua provides describe and describe_type for gathering information of
+types the what fields those types provide. Types are similar to SQL
+tables.
+
+Also see {Eloqua::Api.remote_type} a helper method for generating the
+hash above.
+
+Here is an example of a find request (which requires a group and type)
+
+		group = :entity
+		type = Eloqua::Api.remote_type('Contact') 
+		# => {:id => 1, :type => 'Base', :name => 'Contact'}
+
+		# Executes a Retreive SOAP call
+		record = Eloqua::Api::Service.find_object(
+			group,
+			type,
+			1 # object id
+		)
+		
+		record
+		# Keys are internal_name of fields
+		# => {:id => 1, :C_EmailAddress => 'email@address.com', ...}
+
+Through the low level api we offer the following Eloqua SOAP methods
+
+
+### Supported low level requests
+
+- CURD (+ Find)
+	- Retrieve[Asset] => {Eloqua::Api::Service.find_object}
+	- Update[Asset] => {Eloqua::Api::Service.update_object}
+	 - Create[Asset] => {Eloqua::Api::Service.create_object}
+	- Delete[Asset] => {Eloqua::Api::Service.delete_object}
+
+- Describing Fields and Types
+	- Describe[Asset|Entity]Type => {Eloqua::Api::Service.describe_type}
+	- Describe[Asset|Entity] => {Eloqua::Api::Service.describe}
+	- List[Asset|Entity]Types => {Eloqua::Api::Service.list_types}
+
+- Memberships (Contact Groups)
+	 - AddGroupMember  => {Eloqua::Api::Service.add_group_member}
+	 - RemoveGroupMember => {Eloqua::Api::Service.remove_group_member}
+	 - ListGroupMembership => {Eloqua::Api::Service.list_memberships}
+
+## At a high level (Models)
+
+Through {Eloqua::Entity} and {Eloqua::Asset} we offer base classes
+for modeling both entities and assets. 
+
+Both inherit from {Eloqua::RemoteObject} which implements a number of
+ActiveModel features (persistance, dirty attributes, validations mass
+assignment security)
+
+To create a model (Sorry, no generator yet!) its as simple as inheriting
+from entity or asset and then specifying a type.
+
+		class Contact < Eloqua::Entity
+			self.remote_type = api.remote_type('Contact')
+		end
+
+With just this you have instant access to the data with familiar
+{Eloqua::RemoteObject#save save}, {Eloqua::RemoteObject#update_attributes update attributes}, {Eloqua::RemoteObject#persisted? persisted?}, {Eloqua::RemoteObject etc}
+
+Magic accessor are also created for "map(ped)" attributes or objects
+that where retreived remotely. See below
+
+### Attribute Mapping
+
+
+First you should note that C\_ (thats `/^C\_/`) is replaced from
+all attribute names and they are underscored (`.underscore`) for instance:
+
+		eloqua_does_this = 'C_EmailAddress'
+		you_do_this = your_model.email_addres
+
+Because of the naming schema for Eloqua "internal_name" there where many
+times where I felt I would rather use a different name that was easier
+to type and remember. With this in mind I created attribute mapping.
+
+Here we map C_EmailAddress to email
+
+		class Contact < Eloqua::Entity
+			self.remote_type = api.remote_type('Contact')
+			# use the FULL original name including C_ and CamelCase
+			map :C_EmailAddress => :email
+		end
+
+Now we can reference our contacts email with `.email`
+
+### Saving your data
+
+When you retrieve object from Eloqua through {Eloqua::RemoteObject#find
+find} or through {Eloqua::Query} that object will be aware of all of its 
+attributes (or the ones selected in the query) and will map them back to
+Eloqua's original `internal_name` scheme during the save. 
+
+When you create a new object however you need define those fields through map.
+
+		class Contact < Eloqua::Entity
+			self.remote_type = api.remote_type('Contact')
+		end
+
+		record = Contact.new
+		record.email_address = 'new@email.com' # ERROR
+
+		class Contact < Eloqua::Entity
+			self.remote_type = api.remote_type('Contact')
+			map :C_EmailAddress => :email_address
+		end
+
+		record = Contact.new
+		record.email= 'new@email.com'
+		record.save # SUCCESS
+		
+		# This will successfuly map .email => C_EmailAddress
+
+### What about class methods?
+
+Models support all functionality provided in {Eloqua::Api::Service}
+through {Eloqua.delegate_with_args}.
+
+Where a group is argument is needed by the low level api the
+model will provide it with its group (entity or asset). 
+Where a type is needed the model will provide the models
+{Eloqua::RemoteObject.remote_type remote_type}
+
+		
+		# delegates to Eloqua::Api::Service.describe(:entity, Contact.remote_type)
+		Contact.describe 
+
+		# delegates to Eloqua::Api::Service.describe_type(:entity, 'Contact')
+		# Notice that the second argument is now the first and is required
+		Contact.describe_type('Contact')
+
+
+## Queries
+
+Eloqua provides a method for accessing your data.
+
+There are a few important things you need to know about this first.
+
+1. You may only query 200 records at once. You may pull in more via
+	 pages in a seperate request (pagination)
+
+2. You may only make a Query request once per second.
+	 (Concurency is a no-go in some situations)
+
+3. I would highly recommend limiting the returned rows. 
+	 The limit on other requests is very high so you can make many more
+	 find/update/create/delete, etc.. requests then you can queries.
+
+	 I would reccomend gathering EloquaIDs through query and then manipulating
+	 data through those EloquaIDs in other operations
+
+Through {Eloqua::Query} you can search through your Eloqua database.
+
+Given we have this Contact class:
+
+
+		class Contact < Eloqua::Contact
+			self.remote_type = api.remote_type('Contact')
+			
+			map :C_EmailAddress => :email
+			map :C_DateCreated => :created_at
+			map :C_DateModified => :updated_at
+
+		end
+
+We can then search for all email addresses in the lightsofapollo.com
+domain. 
+
+		# Entity.where is an alias for Eloqua::Query.new(Contact)
+		query = Contact.where
+		query.on(:email, '=', '*@lightsofapollo.com') # * is a wildcard
+		query.all # makes request returns Array
+
+Or all contacts created today
+
+		query.clear_conditions! # resets request
+		query.on(:created_at, '>', Time.now.strftime('%Y-%m-%d'))
+		query.each do |record| # this will also make request and iterator through results
+			...
+		end
+
+Or something more complex
+
+		query.clear_conditions!
+		query.on(:email, '=', '*@lightsofapollo.com').\ # email search
+				  on(:updated_at, '>', '2011-01-01').\ # updated at >
+					limit(1).\ # we only want one record
+					fields([:email, 'ContactID']) # only return a record with the email and id fields populated
+
+		query.all
+
+As you might have guessed query will return an Array of Objects of the
+type given. 
+
+		# Will return ContactGroup.new(s)
+		Eloqua::Query.new(ContactGroup)
+
+
+### For queries that match over 200 records
+
+For queries that span multiple requests (and you want all records at once) 
+use {Eloqua::Query#each_page} each page functions just like each but
+will make consecutive requests to fetch all pages. It also takes an
+optional max pages parameter which allows you to limit the number of
+pages to fetch and/or pause and resume requests.
+
+## TODO
+
+  - (inline) Docs [DONE FOR QUERY]
+  - Guide
+  - Email API (ongoing)

data/Rakefile

@@ -0,0 +1,13 @@
+require 'rake'
+require 'rake/tasklib'
+require 'rubygems'
+require 'bundler'
+
+Bundler::GemHelper.install_tasks
+Bundler.setup(:default, :test)
+
+
+Dir["lib/tasks**/*.rake"].each do |file|
+  puts file
+  load(file)
+end

data/TODO.md

@@ -0,0 +1,8 @@
+- Improved SSL for specifying the map of the element and what
+  importer/export to use.
+
+- Rename 'map' to 'field'
+
+- Shared Spec helper for better BDD. Currently I run into issues from
+  duplicating from 'map' and the fact there is no easy way to test the
+  mappings themselves.

data/eloqua.gemspec

@@ -0,0 +1,32 @@
+$:.push File.expand_path("../lib", __FILE__)
+require "eloqua/version"
+
+Gem::Specification.new do |s|
+                       s.name = 'eloqua'
+                       s.version = Eloqua::VERSION
+                       s.date = '2012-07-04'
+                       s.authors = ["Brian Jou", "Ryan Caught", "James Lal"]
+                       s.email = 'brian@vidyard.com'
+                       s.files = ["lib/eloqua.rb"]
+                       s.summary = 'Eloqua API for Ruby'
+                       s.description = 'An Eloqua API Wrapper for Ruby'
+
+                       s.add_runtime_dependency 'savon'
+                       s.add_runtime_dependency 'builder'
+                       s.add_runtime_dependency 'activemodel'
+                       s.add_runtime_dependency 'activesupport', '= 3.0.6'
+                       s.add_runtime_dependency 'i18n', '= 0.5.0'
+                       s.add_development_dependency 'watchr'
+                       s.add_development_dependency 'ruby-fsevent'
+                       s.add_development_dependency 'ruby-debug19'
+                       s.add_development_dependency 'savon_spec'
+                       s.add_development_dependency 'rspec'
+                       s.add_development_dependency 'flexmock'
+                       s.add_development_dependency 'timecop'
+                       s.add_development_dependency 'ci_reporter'
+
+                       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"]
+end