yieldmanager 0.2.4 → 0.3.0

data/README.rdoc

@@ -23,6 +23,8 @@ To use in a Rails project, add this to config/environment.rb:
 
 === Creating a Yieldmanager::Client
 
+	require 'yieldmanager'
+	
 	@ym = Yieldmanager::Client.new(
 		:user => "bob",
 		:pass => "secret",
@@ -36,7 +38,7 @@ To use in a Rails project, add this to config/environment.rb:
 === Using a service
 
 	@ym.session do |token|
-		currencies = @ym.dictionary.getCurrencies(token)
+		@currencies = @ym.dictionary.getCurrencies(token)
 	end
 	
 === Pagination
@@ -55,6 +57,25 @@ the partial dataset on-the-fly or accumulating it for later use.
 		end
 	end
 
+
+=== Pulling reports
+
+Accessing reportware assumes you've used the "Get Report XML"
+functionality in the UI to get your request XML data, or have
+crafted one from scratch. Assuming it's in a variable called
+*request_xml*, you'd access the data this way:
+
+	@ym.session do |token|
+		report = @ym.pull_report(token, request_xml)
+		puts report.headers.join("\t")
+		report.data.each do |row|
+			puts row.join("\t")
+		end
+	end
+
+*NOTE* Any totals columns your xml requests will be interpreted
+as ordinary data.
+
 === session vs. start_session/end_session
 
 The +session+ method opens a session, gives you a token to use in your service

data/Rakefile

@@ -11,6 +11,7 @@ begin
     gem.homepage = "http://github.com/billgathen/yieldmanager"
     gem.authors = ["Bill Gathen"]
     gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_dependency "hpricot", ">= 0.8.2"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
   Jeweler::GemcutterTasks.new

data/TODO

@@ -9,7 +9,11 @@
 * DONE add pagination
 * add error-handling (timeouts, too many connections?)
 * add reporting
-** report(xml) method in Client
-** Yieldmanager::Report DTO
-*** headers array (for proper column ordering)
+** DONE pull_report(xml) method in Client
+** DONE Yieldmanager::Report DTO
+*** DONE headers array (for proper column ordering)
+*** DONE data as array of arrays
 *** data as array of hashes
+** DONE hpricot for parsing (http://github.com/hpricot/hpricot/)
+** how to handle subtotal/total rows?
+** cast columns to ruby types based on column[data_type]?

data/VERSION

@@ -1 +1 @@
-0.2.4
+0.3.0

data/lib/yieldmanager.rb

@@ -3,6 +3,7 @@ $LOAD_PATH.unshift dir unless $LOAD_PATH.include?(dir)
 # The module that contains everything Yieldmanager-related:
 #
 # * Yieldmanager::Client is the class used to interact with Yieldmanager.
+# * Yieldmanager::Report is the data object returned by ReportWare calls.
 # * Yieldmanager::Builder creates local copies of the YM service wsdls.
 #
 module Yieldmanager
@@ -10,3 +11,4 @@ end
 
 require 'yieldmanager/client'
 require 'yieldmanager/builder'
+require 'yieldmanager/report'

data/lib/yieldmanager/builder.rb

@@ -7,6 +7,9 @@ module Yieldmanager
   # These are used to dynamically-generate the service methods
   # and instance variables in Yieldmanager::Client.
   #
+  # This shouldn't need to be run by the end-user because the
+  # current version of the APIs are pre-generated in the gem.
+  #
   # At some point, the wsdls themselves will actually be used
   # to build the objects.
   class Builder

data/lib/yieldmanager/client.rb

@@ -1,7 +1,6 @@
-#!/usr/bin/env ruby -w
-
 require 'soap/wsdlDriver'
 require 'open-uri'
+require 'hpricot'
 
 module Yieldmanager
   # This is the frontend for using Yieldmanager programmatically.
@@ -9,15 +8,18 @@ module Yieldmanager
   # new instance and calling +service_name+ to access YM services.
   # For example:
   #
-  # ym = Yieldmanager::Client(
-  #   :user => "bob",
-  #   :pass => "secret",
-  #   :api_version => "1.30"
-  # )
+  #   ym = Yieldmanager::Client(
+  #     :user => "bob",
+  #     :pass => "secret",
+  #     :api_version => "1.30"
+  #   )
+  #
+  #   ym.session do |token|
+  #     currencies = @ym.dictionary.getCurrencies(token)
+  #   end
   #
-  # ym.session do |token|
-  #   currencies = @ym.dictionary.getCurrencies(token)
-  # end
+  # It also offers simple access to the ReportWare reporting engine
+  # via the #pull_report method.
   class Client
     # Yieldmanager user
     attr_reader :user
@@ -60,17 +62,11 @@ module Yieldmanager
       end.compact
     end
     
-    # Opens Yieldmanager session
-    def start_session
-      contact.login(@user,@pass,{'errors_level' => 'throw_errors','multiple_sessions' => '1'})
-    end
-    
-    # Closes Yieldmanager session
-    def end_session token
-      contact.logout(token)
-    end
-    
     # Manages Yieldmanager session
+    #
+    # Returns block with token string to be used in API/report calls
+    #
+    # Guarantees no hanging sessions except during system crashes
     def session
       token = start_session
       begin
@@ -80,6 +76,20 @@ module Yieldmanager
       end
     end
     
+    # Opens Yieldmanager session
+    #
+    # Use #session if possible: it guarantees no hanging sessions
+    def start_session
+      contact.login(@user,@pass,{'errors_level' => 'throw_errors','multiple_sessions' => '1'})
+    end
+    
+    # Closes Yieldmanager session
+    #
+    # Use #session if possible: it guarantees no hanging sessions
+    def end_session token
+      contact.logout(token)
+    end
+    
     # Allows looping over datasets too large to pull back in one call
     #
     # Block must return total rows in dataset to know when to stop!
@@ -92,12 +102,21 @@ module Yieldmanager
         page += 1
       end until (block_size * (page-1)) > total
     end
+    
+    # Pulls report from RightMedia, returned as Yieldmanager::Report
+    #
+    # Must be called within the context of a session
+    def pull_report token, xml
+      report = Yieldmanager::Report.new
+      report.pull(token, self.report, xml)
+      report
+    end
 
 private
     
     def wrap_services
       available_services.each do |s|
-        self.instance_variable_set("@#{s}", nil)
+        self.class.send(:attr_writer, s.to_sym)
         # create wrapper method to load it when requested
         self.class.send(:define_method, s) {
           unless self.instance_variable_get("@#{s}")
@@ -115,5 +134,4 @@ private
       SOAP::WSDLDriverFactory.new(wsdl_path).create_rpc_driver
     end
   end
-
 end

data/lib/yieldmanager/report.rb

@@ -0,0 +1,59 @@
+module Yieldmanager
+  # This is the data object for all reportware requests.
+  #
+  # The #pull method is typically called by Yieldmanager::Client#pull_report.
+  #
+  # Data is returned as an array of arrays.
+  # 
+  # Column order is stored in the *headers* array.
+  class Report
+    attr_accessor :headers, :data
+    
+    def initialize
+      self.headers = []
+      self.data = []
+    end
+    
+    def pull token, report, xml
+      report_token = request_report_token token, report, xml
+      report_url = retrieve_report_url token, report, report_token
+      retrieve_data report_url
+    end
+
+private
+    
+    def request_report_token token, report, xml
+      report.requestViaXML(token,xml)
+    end
+
+    def retrieve_report_url token, report, report_token
+      report_url = nil
+      60.times do |secs| # Poll until report ready
+        report_url = report.status(token,report_token)
+        break if report_url != nil
+        sleep(5)
+      end
+      report_url
+    end
+    
+    def retrieve_data url
+      doc = open(url) { |f| Hpricot(f) }
+      (doc/"header column").each do |col|
+        headers << col.inner_html
+      end
+      (doc/"row").each_with_index do |row,idx|
+        # TODO make data available as keyword hashes, too
+        # row_hash = {}
+        # (row/"column").each do |col|
+        #   row_hash[headers[idx]] = col.inner_html
+        # end
+        # data << row_hash
+        # TODO cast elements to appropriate types based on column attrs
+        data << (row/"column").collect do |col|
+          col.inner_html
+        end
+      end
+    end
+  end
+
+end

data/spec/yieldmanager/client_spec.rb

@@ -97,6 +97,17 @@ describe "A new Yieldmanager client" do
     end
   end
   
+  describe "A Yieldmanager report" do
+
+    before(:each) do
+      @ym = Yieldmanager::Client.new(login_args)
+    end
+    
+    it "returns data" do
+      request_xml.should include("advertiser_id")
+    end
+  end
+  
   def login_args
     unless ENV["YIELDMANAGER_USER"] &&
       ENV["YIELDMANAGER_PASS"] &&
@@ -109,4 +120,26 @@ describe "A new Yieldmanager client" do
       :api_version => ENV["YIELDMANAGER_API_VERSION"]
     }
   end
+
+  def request_xml
+    <<EOR
+<?xml version="1.0"?>
+<RWRequest clientName="ui.ent.prod">
+  <REQUEST domain="network" service="ComplexReport" nocache="n" contact_id="52798" remote_ip_address="99.62.255.163" entity="3" filter_entity_id="3" timezone="EST">
+    <ROWS>
+      <ROW type="group" priority="1" ref="entity_id" includeascolumn="n"/>
+      <ROW type="group" priority="2" ref="advertiser_id" includeascolumn="n"/>
+      <ROW type="total"/>
+    </ROWS>
+    <COLUMNS>
+      <COLUMN ref="advertiser_name"/>
+      <COLUMN ref="seller_imps"/>
+    </COLUMNS>
+    <FILTERS>
+      <FILTER ref="time" macro="yesterday"/>
+    </FILTERS>
+  </REQUEST>
+</RWRequest>
+EOR
+  end
 end

data/spec/yieldmanager/report_spec.rb

@@ -0,0 +1,102 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+NEED_ENV_ARGS_MSG = <<EOM
+Please set these environment variables to match your Yieldmanager account:
+* YIELDMANAGER_USER
+* YIELDMANAGER_PASS
+* YIELDMANAGER_API_VERSION
+* YIELDMANAGER_CONTACT_ID
+* YIELDMANAGER_IP_ADDRESS (your external IP address)
+EOM
+  
+describe "A Yieldmanager report request" do
+
+  before(:each) do
+    @ym = Yieldmanager::Client.new(login_args)
+  end
+  
+  it "returns report object" do
+    @ym.session do |token|
+      rpt = @ym.pull_report(token, request_xml)
+      rpt.should be_instance_of(Yieldmanager::Report)
+    end
+  end
+  
+  it "makes request and returns report token" do
+    @ym.session do |token|
+      rpt = Yieldmanager::Report.new
+      rpt.send(:request_report_token, token, @ym.report, request_xml).should_not be_nil
+    end
+  end
+  
+  it "uses report token to pull report url" do
+    @ym.session do |token|
+      rpt = Yieldmanager::Report.new
+      report_token = rpt.send(:request_report_token, token, @ym.report, request_xml)
+      report_url = rpt.send(:retrieve_report_url, token, @ym.report, report_token)
+      report_url.should_not be_nil
+    end
+  end
+  
+  it "uses report url to pull report" do
+    @ym.session do |token|
+      rpt = Yieldmanager::Report.new
+      report_token = rpt.send(:request_report_token, token, @ym.report, request_xml)
+      report_url = rpt.send(:retrieve_report_url, token, @ym.report, report_token)
+
+      rpt.send(:retrieve_data, report_url)
+      rpt.headers[0].should == "advertiser_name"
+    end
+  end
+  
+  it "offers data as array of arrays" do
+    @ym.session do |token|
+      report = @ym.pull_report(token, request_xml)
+      report.data[0][0].should_not be_nil
+    end
+  end
+  
+  it "complains if report token is nil"
+  
+  # need configurable pause and attempts to keep this from running 5 mins!
+  it "throws ReportTimeoutException if report data never returns"
+  
+  def login_args
+    unless ENV["YIELDMANAGER_USER"] &&
+      ENV["YIELDMANAGER_PASS"] &&
+      ENV["YIELDMANAGER_API_VERSION"]
+      raise(ArgumentError, NEED_ENV_ARGS_MSG)
+    end
+    @login_args ||= {
+      :user => ENV["YIELDMANAGER_USER"],
+      :pass => ENV["YIELDMANAGER_PASS"],
+      :api_version => ENV["YIELDMANAGER_API_VERSION"]
+    }
+  end
+
+  def request_xml
+    unless ENV["YIELDMANAGER_CONTACT_ID"] &&
+      ENV["YIELDMANAGER_IP_ADDRESS"]
+      raise(ArgumentError, NEED_ENV_ARGS_MSG)
+    end
+    <<EOR
+<?xml version="1.0"?>
+<RWRequest clientName="ui.ent.prod">
+  <REQUEST domain="network" service="ComplexReport" nocache="n" contact_id="#{ENV['YIELDMANAGER_CONTACT_ID']}" remote_ip_address="#{ENV['YIELDMANAGER_IP_ADDRESS']}" entity="3" filter_entity_id="3" timezone="EST">
+    <ROWS>
+      <ROW type="group" priority="1" ref="entity_id" includeascolumn="n"/>
+      <ROW type="group" priority="2" ref="advertiser_id" includeascolumn="n"/>
+      <ROW type="total"/>
+    </ROWS>
+    <COLUMNS>
+      <COLUMN ref="advertiser_name"/>
+      <COLUMN ref="seller_imps"/>
+    </COLUMNS>
+    <FILTERS>
+      <FILTER ref="time" macro="yesterday"/>
+    </FILTERS>
+  </REQUEST>
+</RWRequest>
+EOR
+  end
+end

data/yieldmanager.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{yieldmanager}
-  s.version = "0.2.4"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Bill Gathen"]
-  s.date = %q{2009-11-18}
+  s.date = %q{2009-11-21}
   s.description = %q{This gem offers full access to YieldManager's API tools (read/write) as well as ad-hoc reporting through the Reportware tool}
   s.email = %q{bill@billgathen.com}
   s.extra_rdoc_files = [
@@ -27,10 +27,12 @@ Gem::Specification.new do |s|
      "lib/yieldmanager.rb",
      "lib/yieldmanager/builder.rb",
      "lib/yieldmanager/client.rb",
+     "lib/yieldmanager/report.rb",
      "spec/spec.opts",
      "spec/spec_helper.rb",
      "spec/yieldmanager/builder_spec.rb",
      "spec/yieldmanager/client_spec.rb",
+     "spec/yieldmanager/report_spec.rb",
      "wsdls/1.30/prod/adjustment.wsdl",
      "wsdls/1.30/prod/advertiser.wsdl",
      "wsdls/1.30/prod/campaign.wsdl",
@@ -79,7 +81,8 @@ Gem::Specification.new do |s|
   s.test_files = [
     "spec/spec_helper.rb",
      "spec/yieldmanager/builder_spec.rb",
-     "spec/yieldmanager/client_spec.rb"
+     "spec/yieldmanager/client_spec.rb",
+     "spec/yieldmanager/report_spec.rb"
   ]
 
   if s.respond_to? :specification_version then
@@ -88,11 +91,14 @@ Gem::Specification.new do |s|
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
       s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
+      s.add_runtime_dependency(%q<hpricot>, [">= 0.8.2"])
     else
       s.add_dependency(%q<rspec>, [">= 1.2.9"])
+      s.add_dependency(%q<hpricot>, [">= 0.8.2"])
     end
   else
     s.add_dependency(%q<rspec>, [">= 1.2.9"])
+    s.add_dependency(%q<hpricot>, [">= 0.8.2"])
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: yieldmanager
 version: !ruby/object:Gem::Version 
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors: 
 - Bill Gathen
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-18 00:00:00 -05:00
+date: 2009-11-21 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -22,6 +22,16 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: 1.2.9
     version: 
+- !ruby/object:Gem::Dependency 
+  name: hpricot
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.8.2
+    version: 
 description: This gem offers full access to YieldManager's API tools (read/write) as well as ad-hoc reporting through the Reportware tool
 email: bill@billgathen.com
 executables: []
@@ -42,10 +52,12 @@ files:
 - lib/yieldmanager.rb
 - lib/yieldmanager/builder.rb
 - lib/yieldmanager/client.rb
+- lib/yieldmanager/report.rb
 - spec/spec.opts
 - spec/spec_helper.rb
 - spec/yieldmanager/builder_spec.rb
 - spec/yieldmanager/client_spec.rb
+- spec/yieldmanager/report_spec.rb
 - wsdls/1.30/prod/adjustment.wsdl
 - wsdls/1.30/prod/advertiser.wsdl
 - wsdls/1.30/prod/campaign.wsdl
@@ -117,3 +129,4 @@ test_files:
 - spec/spec_helper.rb
 - spec/yieldmanager/builder_spec.rb
 - spec/yieldmanager/client_spec.rb
+- spec/yieldmanager/report_spec.rb