sem4r 0.1.1

data/lib/sem4r/cli/cli_request_report.rb

@@ -0,0 +1,104 @@
+# -------------------------------------------------------------------------
+# Copyright (c) 2009-2010 Sem4r sem4ruby@gmail.com
+# 
+# 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.
+# 
+# -------------------------------------------------------------------------
+
+module Sem4r
+
+  class CliRequestReport < CliCommand
+
+    def self.command
+      "request"
+    end
+
+    def self.description
+      "schedule a report"
+    end
+
+    def initialize(account)
+      @account = account
+    end
+
+    def command_opt_parser(options)
+      opt_parser = OptionParser.new
+      opt_parser.banner = "Usage #{self.class.command} [command_options ] <report_id>"
+      opt_parser.separator ""
+      opt_parser.separator "#{self.class.description}"
+      opt_parser.on("-h", "--help", "show this message") do
+        puts opt_parser
+        options.exit = true
+      end
+    end
+
+    def parse_and_run(argv)
+      options = OpenStruct.new
+      rest = command_opt_parser(options).parse( argv )
+      if options.exit
+        return false
+      end
+
+      report = @account.report do
+        name            'boh' 
+        type            'Url'
+        aggregation     'Daily'
+        cross_client    true
+        zero_impression true
+
+        start_day '2010-01-01'
+        end_day   '2010-01-30'
+
+        column "CustomerName"
+        column "ExternalCustomerId"
+        column "CampaignStatus"
+        column "Campaign"
+        column "CampaignId"
+        column "AdGroup"
+        column "AdGroupId"
+        column "AdGroupStatus"
+        column "QualityScore"
+        column "FirstPageCpc"
+        column "Keyword"
+        column "KeywordId"
+        column "KeywordTypeDisplay"
+        column "DestinationURL"
+        column "Impressions"
+        column "Clicks"
+        column "CTR"
+        column "CPC"
+        column "MaximumCPC"
+        column "Cost"
+        column "AveragePosition"
+      end
+
+      unless report.validate
+        puts "report not valid"
+        exit
+      end
+      puts "scheduled job"
+      job = report.schedule
+      job.wait(5) { |report, status| puts "status #{status}" }
+      report.download("test_report.xml")
+      account.adwords.p_counters
+    end
+
+  end
+end

data/lib/sem4r/cli/cli_sem.rb

@@ -0,0 +1,64 @@
+# -------------------------------------------------------------------
+# Copyright (c) 2009-2010 Sem4r sem4ruby@gmail.com
+#
+# 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.
+# -------------------------------------------------------------------
+
+# stdlib
+
+module Sem4r
+
+  class CliSem
+
+    def self.run
+      cli = self.new
+      cli.parse_and_run(ARGV)
+    end
+
+    def parse_and_run( argv )
+      common_args, command, command_args = CliCommand.split_args(argv)
+
+      #      $stderr.puts "debug -------------------"
+      #      $stderr.puts "common_args:  #{common_args}"
+      #      $stderr.puts "command:      #{command}"
+      #      $stderr.puts "command_args: #{command_args}"
+      #      $stderr.puts "debug -------------------"
+
+      cli_common_args = CliCommonArgs.new
+      success = cli_common_args.parse_and_run(common_args)
+      return false unless success
+
+      if command.nil?
+        puts "missing command try sem -h for help"
+        return false
+      end
+
+      begin
+        cmd = CliCommand.commands[command].new(cli_common_args)
+        return cmd.parse_and_run(command_args)
+      rescue Sem4rError
+        puts "I am so sorry! Something went wrong! (exception #{$!.to_s})"
+        return false
+      end
+    end
+
+  end
+
+end

data/lib/sem4r/common/operation.rb

@@ -0,0 +1,78 @@
+# -------------------------------------------------------------------------
+# Copyright (c) 2009-2010 Sem4r sem4ruby@gmail.com
+# 
+# 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.
+# 
+# -------------------------------------------------------------------------
+
+module Sem4r
+
+  class Operation
+    include SoapAttributes
+
+    enum :Operations, [
+      :ADD,
+      :REMOVE,
+      :SET]
+
+    attr_reader :operation_type
+    g_accessor :operator
+
+    def add(operand)
+      operator "ADD"
+      @operand = operand
+      self
+    end
+
+    def remove(operand)
+      operator "REMOVE"
+      @operand = operand
+      self
+    end
+
+    def set(operand)
+      operator "SET"
+      @operand = operand
+      self
+    end
+
+    def to_xml(tag)
+      if @operand == nil
+        raise Sem4rError, "Missing Operand"
+      end
+
+      xml = ""
+      if tag
+        xml += "<#{tag} xsi:type='#{operation_type}'>"
+      end
+      xml +=<<-EOS
+        <operator>#{operator}</operator>
+        #{@operand.to_xml('operand')}
+      EOS
+
+      if tag
+        xml += "</#{tag}>"
+      end
+      xml
+    end
+
+  end
+
+end

data/lib/sem4r/credentials.rb

@@ -0,0 +1,86 @@
+# -------------------------------------------------------------------
+# Copyright (c) 2009-2010 Sem4r sem4ruby@gmail.com
+#
+# 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.
+# -------------------------------------------------------------------
+
+module Sem4r
+  
+  class Credentials
+
+    attr_reader :environment
+    attr_reader :email
+    attr_reader :password
+    attr_reader :client_email
+    attr_reader :developer_token
+    attr_reader :useragent
+
+    def mutable?;    @mutable; end
+    def sandbox?;    @environment != "production" end
+    def production?; !sandbox?; end
+
+    def initialize( opts, client_email = nil )
+      case opts
+      when Hash
+        @environment=         opts[:environment].dup.freeze
+        @email=               opts[:email].dup.freeze
+        @password=            opts[:password].dup.freeze
+        @useragent=           "Sem4r Adwords Ruby Client Library (http://github.com/sem4r/sem4r)"
+        @developer_token=     opts[:developer_token].dup.freeze
+        @mutable=             opts[:mutable] ? true : false
+      when Credentials
+        @credentials = opts
+        @environment=         @credentials.environment
+        @email=               @credentials.email
+        @password=            @credentials.password
+        @useragent=           @credentials.useragent
+        @developer_token=     @credentials.developer_token
+        @mutable=             @credentials.mutable?
+      end
+
+      if client_email
+        @client_email = client_email.dup.freeze
+      end
+    end
+
+    def to_s
+      if @client_email
+        "client account: #{@email} - #{@client_email} (#{@mutable ? "mutable" : "read only"})"
+      else
+        "master account: #{@email} (#{@mutable ? "mutable" : "read only"})"
+      end
+    end
+
+    def connector=(connector)
+      @connector= connector
+    end
+
+    def authentication_token
+      return @authentication_token if @authentication_token
+      if @credentials
+        return @authentication_token = @credentials.authentication_token
+      end
+      raise "no connector in credentials! use credentials.connector="  unless @connector
+      @authentication_token = @connector.authentication_token(@email, @password)
+      @authentication_token
+    end
+
+  end
+end

data/lib/sem4r/extensions.rb

@@ -0,0 +1,62 @@
+module Sem4r #:nodoc:
+  module CoreExtensions #:nodoc:
+    module Hash #:nodoc:
+      # Return a new hash with all keys converted to strings.
+      def stringify_keys
+        inject({}) do |options, (key, value)|
+          options[key.to_s] = value
+          options
+        end
+      end
+
+      # Destructively convert all keys to strings.
+      def stringify_keys!
+        keys.each do |key|
+          self[key.to_s] = delete(key)
+        end
+        self
+      end
+
+      # Return a new hash with all keys converted to symbols.
+      def symbolize_keys
+        inject({}) do |options, (key, value)|
+          options[(key.to_sym rescue key) || key] = value
+          options
+        end
+      end
+
+      # Destructively convert all keys to symbols.
+      def symbolize_keys!
+        self.replace(self.symbolize_keys)
+      end
+
+      alias_method :to_options,  :symbolize_keys
+      alias_method :to_options!, :symbolize_keys!
+
+      # Validate all keys in a hash match *valid keys, raising ArgumentError on a mismatch.
+      # Note that keys are NOT treated indifferently, meaning if you use strings for keys but assert symbols
+      # as keys, this will fail.
+      #
+      # ==== Examples
+      #   { :name => "Rob", :years => "28" }.assert_valid_keys(:name, :age) # => raises "ArgumentError: Unknown key(s): years"
+      #   { :name => "Rob", :age => "28" }.assert_valid_keys("name", "age") # => raises "ArgumentError: Unknown key(s): name, age"
+      #   { :name => "Rob", :age => "28" }.assert_valid_keys(:name, :age) # => passes, raises nothing
+      def assert_valid_keys(*valid_keys)
+        unknown_keys = keys - [valid_keys].flatten
+        raise(ArgumentError, "Unknown key(s): #{unknown_keys.join(", ")}") unless unknown_keys.empty?
+      end
+
+      #
+      # Giovanni
+      #
+      def assert_check_keys(*mkeys)
+        missing_keys = [mkeys].flatten - keys
+        raise(ArgumentError, "Missing key(s): #{missing_keys.join(", ")}") unless missing_keys.empty?
+      end
+    end
+  end
+end
+
+class Hash #:nodoc:
+  include Sem4r::CoreExtensions::Hash
+end

data/lib/sem4r/geo_location/geo_location_service.rb

@@ -0,0 +1,59 @@
+# -------------------------------------------------------------------
+# Copyright (c) 2009-2010 Sem4r sem4ruby@gmail.com
+#
+# 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.
+# -------------------------------------------------------------------
+
+module Sem4r
+  class GeoLocationService
+    include SoapCall
+
+    def initialize(connector)
+      @connector = connector
+
+      @header_namespace  = "https://adwords.google.com/api/adwords/cm/v201003"
+      @service_namespace = @header_namespace
+
+      @sandbox_service_url    = "https://adwords-sandbox.google.com/api/adwords/cm/v201003/GeoLocationService"
+      @production_service_url = "https://adwords.google.com/api/adwords/cm/v201003/GeoLocationService"
+    end
+
+    soap_call_v2009 :get
+
+    ################
+
+    private
+
+    def _get(xml)
+      <<-EOFS
+      <s:get>
+        <s:selector>
+          <addresses>
+            <streetAddress>Via Nazionale,10</streetAddress>
+            <cityName>Rome</cityName>
+            <countryCode>IT</countryCode>
+          </addresses>
+        </s:selector>
+      </s:get>
+      EOFS
+    end
+
+  end
+end

data/lib/sem4r/info/info_service.rb

@@ -0,0 +1,115 @@
+# -------------------------------------------------------------------
+# Copyright (c) 2009-2010 Sem4r sem4ruby@gmail.com
+#
+# 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.
+# -------------------------------------------------------------------
+
+#  <env:Body>
+#    <n3:get xmlns:n3="https://adwords.google.com/api/adwords/info/v200909">
+#      <n3:selector>
+#        <n3:dateRange xmlns:n4="https://adwords.google.com/api/adwords/cm/v200909">
+#          <n4:min>20090101</n4:min>
+#          <n4:max>20091030</n4:max>
+#        </n3:dateRange>
+#        <n3:apiUsageType>UNIT_COUNT</n3:apiUsageType>
+#      </n3:selector>
+#    </n3:get>
+#  </env:Body>
+#</env:Envelope>
+
+
+module Sem4r
+  class InfoService
+    include SoapCall
+
+    def initialize(connector)
+      @connector = connector
+      @header_namespace  = "https://adwords.google.com/api/adwords/cm/v201003"
+      @service_namespace = "https://adwords.google.com/api/adwords/info/v201003"
+
+      @production_service_url = "https://adwords.google.com/api/adwords/info/v201003/InfoService"
+      @sandbox_service_url    = "https://adwords-sandbox.google.com/api/adwords/info/v201003/InfoService"
+    end
+
+
+    soap_call_v2009 :unit_cost
+
+    def _unit_cost( usage_type )
+      <<-EOFS
+      <s:get>
+        <s:selector>
+          <s:dateRange>
+            <min>20090101</min>
+            <max>20091105</max>
+          </s:dateRange>
+          <s:apiUsageType>#{usage_type}</s:apiUsageType>
+        </s:selector>
+      </s:get>
+      EOFS
+    end
+
+
+    # Total units used since the beginning of the year: 0
+    #    def old_unit_cost(credentials)
+    #
+    #      soap_message = @connector.message_v2009(credentials, @header_namespace, @service_namespace )
+    #      soap_message.body = "soap_body_content"
+    #
+    #
+    #      soap_message.instance_eval do
+    #        def build_soap_message
+    #          str = <<-EOFS
+    #<?xml version="1.0" encoding="utf-8" ?>
+    #  <env:Envelope
+    #    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+    #    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    #    xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
+    #    xmlns="https://adwords.google.com/api/adwords/cm/v200909"
+    #    xmlns:s="https://adwords.google.com/api/adwords/info/v200909">
+    #    <env:Header>
+    #      <s:RequestHeader env:mustUnderstand="0">
+    #        <authToken>#{@credentials.authentication_token}</authToken>
+    #        <userAgent>adwords4r: Sample User Agent</userAgent>
+    #        <developerToken>#{@credentials.developer_token}</developerToken>
+    #      </s:RequestHeader>
+    #    </env:Header>
+    #    <env:Body  >
+    #      <s:get>
+    #        <s:selector>
+    #          <s:dateRange>
+    #            <min>20090101</min>
+    #            <max>20091105</max>
+    #          </s:dateRange>
+    #          <s:apiUsageType>UNIT_COUNT</s:apiUsageType>
+    #        </s:selector>
+    #      </s:get>
+    #    </env:Body>
+    #  </env:Envelope>
+    #EOFS
+    #          str
+    #        end
+    #      end
+    #
+    #      result_xml = soap_message.send(@sandbox_service_url)
+    #      result_xml
+    #    end
+
+  end
+end

data/lib/sem4r/report_definition/report_definition.rb

@@ -0,0 +1,104 @@
+# -------------------------------------------------------------------------
+# Copyright (c) 2009-2010 Sem4r sem4ruby@gmail.com
+# 
+# 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.
+# 
+# -------------------------------------------------------------------------
+
+module Sem4r
+
+  class ReportDefinition < Base
+
+    attr_reader :id
+
+    g_accessor :name
+
+    def initialize(account, name = nil, &block)
+      super( account.adwords, account.credentials )
+      @account = account
+      self.name = name
+      if block_given?
+        @inside_initialize = true
+        block.arity < 1 ? instance_eval(&block) : block.call(self)
+      end
+      @inside_initialize = false
+    end
+
+    def inside_initialize?
+      @inside_initialize
+    end
+
+    def to_s
+      "'#{@name}'"
+    end
+
+    def to_xml(tag)
+      builder = Builder::XmlMarkup.new
+      builder.tag!(tag) do |t|
+        t.reportName    @name
+      end
+    end
+
+
+    ###########################################################################
+
+    def self.from_element(account, el)
+      new(account) do
+        @id          = el.elements["id"].text.strip.to_i
+        name           el.elements["name"].text.strip
+        status         el.elements['status'].text.strip # ACTIVE, PAUSED, DELETED
+        serving_status el.elements['servingStatus']
+        start_date     el.elements['startDate']
+        end_date       el.elements['endDate']
+      end
+    end
+
+    def self.create(account, &block)
+      new(account, &block).save
+    end
+
+    def save
+      unless @id
+        op = ReportDefinitionOperation.new
+        op.add(self)
+        puts op.to_xml "operations"
+        soap_message = service.report_definition.mutate(credentials, op.to_xml("operations"))
+        add_counters( soap_message.counters )
+        rval = REXML::XPath.first( soap_message.response, "//mutateResponse/rval")
+        id = REXML::XPath.match( rval, "value/id" ).first
+        @id = id.text.strip.to_i
+      end
+      self
+    end
+
+    def delete
+      soap_message = service.campaign.delete(credentials, @id)
+      add_counters( soap_message.counters )
+      @id = -1 # logical delete
+    end
+
+    ###########################################################################
+
+    def empty?
+      _ad_groups.empty?
+    end
+
+  end
+end