woodwing_elvis 0.0.1

data/lib/woodwing/elvis/rest/relations.rb

@@ -0,0 +1,24 @@
+module WoodWing
+  class Elvis
+    module Rest
+
+
+      # https://elvis.tenderapp.com/kb/api/rest-create_relation
+      def create_relation(options={})
+        url = base_url + "create_relation"
+        response = get_response(url, options)
+      end # create_relation
+
+
+      # https://elvis.tenderapp.com/kb/api/rest-remove_relation
+      def remove_relation(options={})
+        url = base_url + "remove_relation"
+        response = get_response(url, options)
+      end # remove_relation
+
+      alias :delete_relation :remove_relation
+
+
+    end # module Rest
+  end # class Elvis
+end # module WoodWing

data/lib/woodwing/elvis/rest/search.rb

@@ -0,0 +1,156 @@
+module WoodWing
+  class Elvis
+    module Rest
+
+
+      # https://elvis.tenderapp.com/kb/api/rest-search
+      # Search assets in Elvis using all of the powerful search functions provided
+      # by the Elvis search engine. You can execute all possible queries and even
+      # use faceted search.
+      #
+      # Returned information can be formatted as JSON, XML or HTML to support any
+      # kind of environment for clients.
+      #
+      # Apart from all sorts of metadata about the assets, the results returned
+      # by a search call also contain ready-to-use URLs to the thumbnail, preview
+      # and original file. This makes it extremely easy to display rich visual results.
+      #
+      # http://yourserver.com/services/search
+      #     ?q=<query>
+      #     &start=<first result>
+      #     &num=<max result hits to return>
+      #     &sort=<comma-delimited sort fields>
+      #     &metadataToReturn=<comma-delimited fields>
+      #     &facets=<comma-delimited fields>
+      #     &facet.<field>.selection=<comma-delimited values>
+      #     &format=<json|xml|html>
+      #     &appendRequestSecret=<true|false>
+      #
+      # Options
+      #   q   (Required) The query to search for, see the query syntax guide
+      #       for details.  https://elvis.tenderapp.com/kb/technical/query-syntax
+      #       Recap:  supports wildcards: *? logical: AND && OR ||
+      #               prefix terms with + to require - to remove
+      #               suffix terms with ~ to include similar (eg. spelling errors)
+      #               terms seperated by spaces default to an AND condition
+      #               use "double quotes" to search for phrases.
+      #               All searches are case insensitive.
+      #
+      #   start   First hit to be returned. Starting at 0 for the first hit. Used
+      #           to skip hits to return 'paged' results. Optional. Default is 0.
+      #
+      #   num   Number of hits to return. Specify 0 to return no hits, this can be
+      #         useful if you only want to fetch facets data. Optional. Default is 50.
+      #
+      #   sort  The sort order of returned hits. Comma-delimited list of fields to
+      #         sort on.  By default, date/time fields and number fields are sorted
+      #         descending. All other fields are sorted ascending. To explicitly
+      #         specify sort order, append "-desc" or "-asc" to the field.
+      #           Some examples:
+      #             sort=name
+      #             sort=rating
+      #             sort=fileSize-asc
+      #             sort=status,assetModified-asc
+      #         A special sort case is "relevance". This lets the search engine
+      #         determine sorting based on the relevance of the asset against
+      #         the search query. Relevance results are always returned descending.
+      #         Optional. Default is assetCreated-desc.
+      #
+      # metadataToReturn  Comma-delimited list of metadata fields to return in hits.
+      #                   It is good practice to always specify just the metadata
+      #                   fields that you need. This will make the searches faster
+      #                   because less data needs to be transferred over the network.
+      #                   Example: metadataToReturn=name,rating,assetCreated
+      #                   Specify "all", or omit to return all available metadata.
+      #                   Example:  metadataToReturn=all
+      #                             metadataToReturn=
+      #                   Optional. Default returns all fields.
+      #
+      # facets  Comma-delimited list fields to return facet for.
+      #         Example: facets=tags,assetDomain
+      #         Selected values for a facet must be specified with a
+      #         "facet.<field>.selection" parameter. Do not add selected items to
+      #         the query since that will cause incorrect facet filtering.
+      #         Note: Only fields that are un_tokenized or tokenized with
+      #         pureLowerCase analyzer can be used for faceted search
+      #         Optional. Default returns no facets.
+      #
+      # facet.<field>.selection   Comma-delimited list of values that should
+      #                           be 'selected' for a given facet.
+      #                           Example:  facet.tags.selection=beach
+      #                                     facet.assetDomain.selection=image,video
+      #                           Optional.
+      #
+      # format  Response format to return, either json, xml or html.
+      #         json  format is lightweight and very suitable for consumption
+      #               using AJAX and JavaScript.
+      #         html  format is the easiest way to embed results in HTML pages,
+      #               but is heavier and less flexible than using a HitRenderer
+      #               from our open-source JavaScript library.
+      #         xml   format is the same as returned by the Elvis SOAP webservice
+      #               search operation. This format is suitable for environments
+      #               that do not support JSON parsing and work better with XML.
+      #               When you use format=xml, error responses will also be returned
+      #               in xml format.
+      #         Optional. Default is json.
+      #
+      #   appendRequestSecret   When set to true will append an encrypted code to
+      #                         the thumbnail, preview and original URLs. This is
+      #                         useful when the search is transformed to HTML by an
+      #                         intermediary (like a PHP or XSLT) and is then served
+      #                         to a web browser that is not authenticated against
+      #                         the server.
+      #                         Optional. Default is false.
+      #
+      # RETURNED VALUE
+      # ==============
+      #
+      # An array of hits in JSON, XML or HTML format. Each item in the array has
+      # the following properties.
+      #
+      #   firstResult     Index of the first result that is returned.
+      #   maxResultHits   Maximum number of hits that are returned.
+      #   totalHits       Total hits found by the search.
+      #
+      # hits
+      #
+      #   id            Unique ID of the asset in Elvis.
+      #   permissions   String that indicates the permissions the current user has
+      #                 for the asset.
+      #   thumbnailUrl  A ready to use URL to display the thumbnail of an asset.
+      #                 Only available for assets that have a thumbnail.
+      #   previewUrl    A ready to use URL to display the default preview of an
+      #                 asset. The type of preview depends on the asset type.
+      #                 Only available for assets that have a preview.
+      #   originalUrl   A ready to use URL to download the original asset.
+      #                 This URL will only work if the user has the 'use original'
+      #                 permission for this asset. This can be checked with the
+      #                 'permissions' property.
+      #   metadata      An object with metadata that was requested to be returned.
+      #                 Some metadata will always be returned.
+      #
+      # Fields that have date or datetime values and the field fileSize contain
+      # both the actual numerical value and a formatted value.
+
+      def search(options={})
+
+        Utilities.demand_required_options!( :search, options )
+        url = base_url + "search"
+
+        # NOTE: One element of metadata is 'textContent' for books and
+        #       large articles that is a LOT of text. The following
+        #       line changes the default from 'all' to 'status,name'.
+        #       If you want all metadata then you have to request
+        #       'all' in your options.
+
+        options   = { metadataToReturn: 'status,name' }.merge(options)
+        response  = get_response(url, options)
+
+      end # search
+
+      alias :find :search
+
+
+    end # module Rest
+  end # class Elvis
+end # module WoodWing

data/lib/woodwing/elvis/rest/stub.rb

@@ -0,0 +1,11 @@
+module WoodWing
+  class Elvis
+    module Rest
+
+
+      def stub(); end
+
+
+    end # module Rest
+  end # class Elvis
+end # module WoodWing

data/lib/woodwing/elvis/soap.rb

@@ -0,0 +1,18 @@
+###################################################
+###
+##  File: soap.rb
+##  Desc: SOAP API definitions for WoodWing's Elvis
+#
+
+module WoodWing
+  class Elvis
+    module Soap
+
+      require_relative 'soap/stub'
+
+    end # module Soap
+
+    include Soap
+
+  end # class Elvis
+end # module WoodWing

data/lib/woodwing/elvis/soap/stub.rb

@@ -0,0 +1,11 @@
+module WoodWing
+  class Elvis
+    module Soap
+
+
+      def stub(); end
+
+
+    end # module Soap
+  end # class Elvis
+end # module WoodWing

data/lib/woodwing/elvis/utilities.rb

@@ -0,0 +1,80 @@
+###################################################
+###
+##  File: utilities.rb
+##  Desc: Utilitie methods for working with the REST API
+##        for WoodWing's Elvis product
+#
+
+require_relative 'utilities/pmask'
+
+module WoodWing
+  class Elvis
+    class Utilities
+      class << self
+
+=begin
+      # SMELL: Is this really necessary with RestClient ?
+      def url_encode_options(options)
+        raise "Invalid parameter class: expected Hash" unless Hash == options.class
+        a_string  = ''
+        first_one = true
+        options.each_pair do |k, v|
+          if first_one
+            a_string += '?'
+            first_one = false
+          else
+            a_string += '&'
+          end
+          # a_string += "#{k}=#{String == v.class ? v.gsub(' ','%20') : v}"
+          a_string += "#{k}=#{URI::encode(v)}"
+        end # options.each_pair
+        #debug_me{:a_string} if debug?
+        return a_string
+      end # url_encode_options
+
+=end
+
+        # encode the username and password for use on the URL for login
+
+        # SMELL: This is not necessary with a session-based logon/off system
+        #        HOWEVER, it might still be useful for some cases.  Can this
+        #        scheme and a session management scheme work together?
+
+        def encode_login(username='guest', password='guest')
+
+          {
+            authcred:     UrlSafeBase64.encode64("#{username}:#{password}"),
+            authpersist:  'true',
+            authclient:   'api_ruby'
+          }
+
+        end # def encode_login(username='guest', password='guest')
+
+
+        # raise ArgumentError if required options are not present
+
+        def demand_required_options!(command, options)
+
+          raise ArgumentError unless Symbol == command.class
+          raise ArgumentError unless Hash == options.class
+          raise ArgumentError unless WW::Elvis::COMMANDS.include?(command)
+
+          required_options = WW::Elvis::COMMANDS[command][1]
+
+          answer = true
+
+          return(answer) if required_options.empty?
+
+          required_options.each do |ro|
+            answer &&= options.include?(ro)
+          end
+
+          raise "ArgumentError: #{caller.first.split().last} requires #{required_options.join(', ')}" unless answer
+
+        end # def demand_required_options!(command, options)
+
+      end # eigenclass
+    end # class Utilities
+  end # class Elvis
+end # module WoodWing
+

data/lib/woodwing/elvis/utilities/pmask.rb

@@ -0,0 +1,52 @@
+ ###################################################
+###
+##  File: pmask.rb
+##  Desc: Utility class to check permissions 'mask' for available permissions
+#
+
+module WoodWing
+  class Elvis
+    class Utilities
+
+      # Utility class to check permissions 'mask' for available permissions.
+      # The permissions mask consists of a string with one character for
+      # every permission available in Elvis: VPUMERXCD
+
+      class Pmask
+
+        PERMISSIONS = {
+          'V' => 'VIEW',
+          'P' => 'VIEW_PREVIEW',
+          'U' => 'USE_ORIGINAL',
+          'M' => 'EDIT_METADATA',
+          'E' => 'EDIT',
+          'R' => 'RENAME',
+          'X' => 'MOVE',
+          'C' => 'CREATE',
+          'D' => 'DELETE',
+        }
+
+        def initialize(pmask='')
+          @pmask = pmask
+        end
+
+        def verbose
+          v=[]
+          @pmask.each_char{|c| v<<PERMISSIONS[c]}
+          return v.join(', ')
+        end
+
+        define_method('can_view?')          { @pmask.include? 'V' }
+        define_method('can_view_preview?')  { @pmask.include? 'P' }
+        define_method('can_use_original?')  { @pmask.include? 'U' }
+        define_method('can_edit_metadata?') { @pmask.include? 'M' }
+        define_method('can_edit?')          { @pmask.include? 'E' }
+        define_method('can_rename?')        { @pmask.include? 'R' }
+        define_method('can_move?')          { @pmask.include? 'X' }
+        define_method('can_create?')        { @pmask.include? 'C' }
+        define_method('can_delete?')        { @pmask.include? 'D' }
+
+      end # class Pmask
+    end # class Utilities
+  end # class Elvis
+end # module WoodWing

data/lib/woodwing/version.rb

@@ -0,0 +1,5 @@
+# TODO: indicate the version of the API
+
+module WoodWing
+  VERSION = "0.0.1"   # This is just the version of this gem.
+end # module WoodWing

data/test/elvis_search.rb

@@ -0,0 +1,416 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+##########################################################
+###
+##  File: elvis_search.rb
+##  Desc: Search Elvis for stuff
+##        can produce an XML file for use with Carrot2 clustering
+##  By:   Dewayne VanHoozer (dvanhoozer@gmail.com)
+#
+
+require 'debug_me'
+include DebugMe
+
+require 'pathname'
+require_relative '../lib/woodwing'
+
+
+me        = Pathname.new(__FILE__).realpath
+my_dir    = me.parent
+my_name   = me.basename.to_s
+
+$options = {
+  verbose:          false,
+  debug:            false,
+  show_text:        false,
+  show_dates:       false,
+  cluster_results:  false,
+  cluster_filename: nil,
+  cluster_file:     nil,
+  elvis_api_url:  ENV['ELVIS_API_URL']  || 'http://localhost:8080/services/',
+  elvis_user:     ENV['ELVIS_USER']     || 'guest',
+  elvis_pass:     ENV['ELVIS_PASS']     || 'guest',
+  meta_fields:    '',
+  query:          ''  # syntax identical to Elvis UI search box
+}
+
+def verbose?
+  $options[:verbose]
+end
+
+def debug?
+  $options[:debug]
+end
+
+def show_text?
+  $options[:show_text]
+end
+
+def show_dates?
+  $options[:show_dates]
+end
+
+def cluster_results?
+  $options[:cluster_results]
+end
+
+$KNOWN_MFIELDS = %w[  assetCreator
+  assetDomain
+  assetFileModifier
+  assetModifier
+  assetPath
+  assetPropertyETag
+  assetType
+  basicDataETag
+  cf_PrayerFocus
+  cf_Theme
+  cf_TFTD
+  cf_LongReading
+  cf_Citation
+  contentETag
+  extension
+  filename
+  fileSize
+  fileType
+  folderPath
+  indexRevision
+  metadataComplete
+  mimeType
+  name
+  previewETag
+  previewState
+  sceArchived
+  sceUsed
+  status
+  textContent
+  versionETag
+versionNumber ]
+
+usage = <<EOS
+
+Search Elvis for stuff
+
+Usage: #{my_name} [options] 'query'
+
+Where:
+
+  options               Do This
+    -h or --help        Display this message
+    -v or --verbose     Display progress
+    -d or --debug       Sets $DEBUG
+    -m or --meta        Display these metadata fields
+      field_names+        one of more metadata field
+                          names seperated by commas
+          --dates       Shows creation and modification
+                          dates and users
+          --text        Shows text around the search term(s)
+                          for the first "hit" in the document
+
+          --cluster     User document clustering
+            out_filename  filename into which the search
+                          results are stored
+
+  'query'               The search query constrained by
+                        single quotes.
+
+NOTE:
+
+  The single quotes around the search query are required to
+  defeat the command line file glob/wildcard facility.
+
+  The '-m or --meta' option can be used many times as needed.
+  The following list contains the known (case-SENSITIVE)
+  metadata fields:
+
+  #{$KNOWN_MFIELDS.join(', ')}
+
+EOS
+
+# Check command line for Problems with Parameters
+$errors   = []
+$warnings = []
+
+
+# Get the next ARGV parameter after param_index
+def get_next_parameter(param_index)
+  unless Fixnum == param_index.class
+    param_index = ARGV.find_index(param_index)
+  end
+  next_parameter = nil
+  if param_index+1 >= ARGV.size
+    $errors << "#{ARGV[param_index]} specified without parameter"
+  else
+    next_parameter = ARGV[param_index+1]
+    ARGV[param_index+1] = nil
+  end
+  ARGV[param_index] = nil
+  return next_parameter
+end # def get_next_parameter(param_index)
+
+
+# Get $options[:out_filename]
+def get_out_filename(param_index)
+  filename_str = get_next_parameter(param_index)
+  $options[:out_filename] = Pathname.new( filename_str ) unless filename_str.nil?
+end # def get_out_filename(param_index)
+
+
+# Display global warnings and errors arrays and exit if necessary
+def abort_if_errors
+  unless $warnings.empty?
+    STDERR.puts
+    STDERR.puts "The following warnings were generated:"
+    STDERR.puts
+    $warnings.each do |w|
+      STDERR.puts "\tWarning: #{w}"
+    end
+    STDERR.print "\nAbort program? (y/N) "
+    answer = (gets).chomp.strip.downcase
+    $errors << "Aborted by user" if answer.size>0 && 'y' == answer[0]
+  end
+  unless $errors.empty?
+    STDERR.puts
+    STDERR.puts "Correct the following errors and try again:"
+    STDERR.puts
+    $errors.each do |e|
+      STDERR.puts "\t#{e}"
+    end
+    STDERR.puts
+    exit(-1)
+  end
+end # def abort_if_errors
+
+
+# Display the usage info
+if  ARGV.empty?               ||
+  ARGV.include?('-h')       ||
+  ARGV.include?('--help')
+  puts usage
+  exit
+end
+
+%w[ -v --verbose ].each do |param|
+  if ARGV.include? param
+    $options[:verbose]        = true
+    ARGV[ ARGV.index(param) ] = nil
+  end
+end
+
+%w[ -d --debug ].each do |param|
+  if ARGV.include? param
+    $options[:debug]          = true
+    $DEBUG                    = true
+    ARGV[ ARGV.index(param) ] = nil
+  end
+end
+
+%w[ -m --meta ].each do |param|
+  while ARGV.include?(param) do
+    $options[:meta_fields] += ',' unless $options[:meta_fields].empty?
+    $options[:meta_fields] += get_next_parameter(ARGV.index(param))
+  end
+end
+
+%w[ --dates ].each do |param|
+  if ARGV.include? param
+    $options[:show_dates]     = true
+    $options[:meta_fields]   += ',' unless $options[:meta_fields].empty?
+    $options[:meta_fields]   += "assetCreated,assetCreator,assetModified,assetModifier,versionNumber"
+    ARGV[ ARGV.index(param) ] = nil
+  end
+end
+
+%w[ --text ].each do |param|
+  if ARGV.include? param
+    $options[:show_text]      = true
+    ARGV[ ARGV.index(param) ] = nil
+  end
+end
+
+%w[ --cluster ].each do |param|
+  if ARGV.include? param
+    $options[:cluster_results]    = true
+    next_param = get_next_parameter(param)
+    unless next_param.nil?
+      $options[:cluster_filename]   = Pathname.new(next_param)
+      $warnings << "File already exists: #{$options[:cluster_filename].realpath}" if $options[:cluster_filename].exist?
+    end
+  end
+end
+
+
+ARGV.compact!
+
+debug_me(){ :ARGV }
+
+
+if ARGV.empty?
+  $errors << "No search query was specified."
+end
+
+$options[:query] = ARGV.shift
+
+unless ARGV.empty?
+  $errors << "The search query is malformed - may not be enclosed in quotes."
+end
+
+abort_if_errors
+
+max_mfield_size = 0
+
+unless $options[:meta_fields].empty?
+  $options[:meta_fields] = $options[:meta_fields].split(',')
+  $options[:meta_fields].each do |mf|
+    max_mfield_size = mf.size if mf.size > max_mfield_size
+  end
+  max_mfield_size += 2
+end
+
+
+if cluster_results?
+  $options[:cluster_file] = File.new($options[:cluster_filename],'w')
+end
+
+
+######################################################
+# Local methods
+
+
+
+
+######################################################
+# Main
+
+at_exit do
+  begin
+    $elvis.logout
+  rescue
+    # eat it
+  end
+  puts
+  puts "Done."
+  puts
+end
+
+$elvis = WoodWing::Elvis.new
+$elvis.login
+
+if debug?
+  puts
+  pp $options
+  puts
+  pp $elvis
+  puts
+end
+
+options = {
+  q:                    $options[:query],
+  appendRequestSecret: 'true'
+}
+
+options[:metadataToReturn] = $options[:meta_fields].join(',') unless $options[:meta_fields].empty?
+
+
+response = $elvis.search options
+
+if debug?
+  puts "======= Full Response ======="
+  pp response
+end
+
+puts
+
+unless response.include?(:totalHits)
+  puts "ERROR: response does not include :totalHits"
+  exit
+end
+
+puts
+puts "Total Hits:   #{response[:totalHits]}"
+puts "First Result: #{response[:firstResult]}"
+puts "Max. Results: #{response[:maxResultHits]}"
+puts
+
+if cluster_results?
+  $options[:cluster_file].puts <<ENDXML
+<?xml version="1.0" encoding="UTF-8"?>
+<searchresult>
+  <query>#{$options[:query]}</query>
+ENDXML
+
+end
+
+if response[:totalHits] > 0
+  result_number = 0
+  response[:hits].each do |hit|
+
+    $options[:cluster_file].puts '<document>' if cluster_results?
+
+    metadata = hit[:metadata]
+    puts
+    puts "="*45
+    puts "== Result # #{result_number+=1}   ID: #{hit[:id]}"
+    puts
+    puts "originalUrl:  #{hit[:originalUrl]}"
+    puts "Asset Path:   #{metadata[:assetPath]}"
+    puts "Status:       #{metadata[:status]}"
+
+    unless $options[:meta_fields].empty?
+      puts
+      $options[:meta_fields].each do |mf|
+        mf_label = "#{mf}:" + ' '*(max_mfield_size-mf.size)
+        puts "#{mf_label} #{metadata[mf.to_sym]}"
+      end
+    end
+
+    if show_dates?
+      puts
+      puts "Created on:   #{metadata[:assetCreated][:formatted]}  by: #{metadata[:assetCreator]}"
+      puts "Modified on:  #{metadata[:assetModified][:formatted]}  by: #{metadata[:assetModifier]}  Version Number # #{metadata[:versionNumber]}"
+    end
+
+    if show_text?
+      puts
+      puts "highlightedText:  #{hit[:highlightedText]}"
+    end
+
+    puts
+
+    if cluster_results?
+      $options[:cluster_file].puts <<ENDXML
+  <title>#{metadata[:assetPath]}</title>
+  <snippet>#{hit[:highlightedText].gsub('<B>','').gsub('</B>','').gsub('<','').gsub('>','')}</snippet>
+  <url>http://localhost#{metadata[:assetPath]}</url>
+</document>
+ENDXML
+
+    end # if cluster_results?
+
+  end # response[:hits].each do |hit|
+end # if response[:totalHits] > 0
+
+
+if cluster_results?
+  $options[:cluster_file].puts "</searchresult>"
+  $options[:cluster_file].close
+  # TODO: invokl carrot2 CLI
+  # TODO: retrieve carrot2 generated XML file
+  # TODO: display document clusters
+end
+
+__END__
+
+# To interface with Carrot2 document clustering workbench this kind of xml
+# file needs to be generated with 1 document entry for each 'hit' of
+# the query.
+
+<?xml version="1.0" encoding="UTF-8"?>
+<searchresult>
+  <query>seattle</query>
+  <document>
+    <title>City of Seattle</title>
+    <snippet>Official site featuring a guide to living in Seattle and information on doing business, city services, and visitor's resources.</snippet>
+    <url>http://www.seattle.gov/</url>
+  </document>
+</searchresult>
+