Analytics::Psw

Analytics-psw is a wrapper providing access to the Perceptive Cloud Platform Analytics service.

Installation

Add this line to your application's Gemfile:

gem 'analytics-psw'

And then execute:

$ bundle

Or install it yourself as:

$ gem install analytics-psw

Usage

require 'analytics-psw'
require 'yaml' #optional, for importing information used to connect to the Analytics service

Options in .rb file

opts = {}
opts['server_url'] = "http://my.server.url"     #required No trailing slash needed
opts['service'] = "MyServiceName"               #required Calling AnalyticsPSW::Analytics.new searches for your service.  It must exist prior to using the GEM.
opts['proxy'] = "http://proxy.server.address"   #optional Not required if you don't use a proxy server or if you set the http_proxy environment variable.  
                                                #required for multi-get (run multiple get requests in parallel)
opts['client_id'] = "fjdksl98s2jkljf"           #required for the GEM to manage your Oath2 token
opts['client_secret'] = "jkdsl89sf9s"           #required for the GEM to manage your Oath2 token
opts['event_types'] = ["event_one", "event_two", "event_three"] #optional Creates event types to associate with your service if they don't already exist
opts['dimensions'] = [{"dimension_name" => "string"}, {"dimension_2" => "integer"}] #optional Creates dimensions to describe your events if they don't already exist

ap = AnalyticsPSW::Analytics.new(opts)

Options in separate .yml file

ap = AnalyticsPSW.new(YAML.load_file(analytics_settings.yml))

Sample YAML file

---
server_url: http://127.0.0.1:3000
service: my_service

client_id=fjdksl98s2jkljf
client_secret=jkdsl89sf9s

event_types:
- event_one
- event_two

dimensions:
- dimension_one: string
- dimension_two: integer

Available Methods

ap.record_event(event_type, metadata = {}) # Send an event to the Analytics service. The event_type must already exist in the Analytics system.  'event_type' can either be a string or symbol

ap.query_analytics(query_parameters) # Send a hashmap query to the Analytics service and return an AnalyticsReport object. Required keys for query_parameters include one or more of :sum, :avg, :stddev, :fields. Optional keys are :customer, :where, :group_by, :order_by, :iterate_by, :limit. Use comma-separated strings for multiple values. The keys :sum, :avg, and :stddev return aggregates that prepend and append the key name with two underscores. For example, the sum aggregate would return as "__SUM__<field_name>".
ap.create_report(name, query_parameters) # Create a report query to run later.  Required keys for query_parameters include one or more of :sum, :avg,  :stddev, :fields. Optional keys are :customer, :where, :group_by, :order_by, :iterate_by, :limit. Use comma-separated strings for multiple values.
ap.list_reports # List all reports for a service
ap.report_criteria(report_name) # List the properties for a report. 'report_name' can either be a string or symbol
ap.run_report(report_name, where_criteria) # Run a stored report and return an AnalyticsReport object. The 'where_criteria' are options 'where' parameters to replace in the stored report when running.  'report_name' can either be a string or symbol
ap.delete_report(report_name) # Delete a stored report. 'report_name' can either be a string or symbol

ap.multi_query_analytics(query_parameters_array) # Run multiple simultaneous queries. Send an array of hashmaps of query parameters to return an array of AnalyticsReport objects.

ap.show_service_resource(service_name) # List available resources for a service. 'service_name' can either be a string or symbol
ap.show_service_metadata(service_name) # List the metadata for a service. 'service_name' can either be a string or symbol

ap.create_event_type(name, description = "") # Create an event type for a service. 'name' can either be a string or symbol
ap.list_event_types # List all event types for a service
ap.show_event_type(event_type_name) # List the metadata for an event type. 'event_type_name' can either be a string or symbol

ap.create_dimension(name, data_type, units = "", description = "") # Create a new dimension. Only name and data_type are required. 'name' can either be a string or symbol
ap.list_dimensions  # List all dimensions for a service
ap.show_dimension_resources(dimension_name) # List available resources for a dimension. 'dimension_name' can either be a string or symbol
ap.show_dimension_metadata(dimension_name)  # List metadata for a dimension. 'dimension_name' can either be a string or symbol

ap.create_dimension_properties(dimension_name, dimension_value, property_hash) # Add properties to a dimension value. This returns a 409 message if properties already exist. Use this method to add mutable string data to dimensions. For example, add a title to a video by adding a title property to the video's guid.
ap.update_dimension_properties(dimension_name, dimension_value, property_hash) # Update properties created for a dimension value.  The hash replaces all properties currently set.
ap.create_or_update_dimension_properties(dimension_name, dimension_value, property_hash) # Add properties to a dimension value if they already exist. Updates the properties otherwise. Use this method to add mutable string data to dimensions. For example, add a title to a video by adding a title property to the video's guid.
ap.show_dimension_properties(dimension_name, dimension_value) # List the properties currently set for a dimension value. The body will be JSON.
ap.list_dimension_properties(dimension_name) # List all properties for a dimension. This returns a JSON object with an array of JSON/location pairs.

AnalyticReport object

AnalyticsReport:

:status # Return code from the REST call.
:rows # An array of hashes containing AnalyticsReportField objects. Each hash is a "row".
:error_message # Error returns from persistence layer if query/report was unsuccessful.

AnalyticsReportField:

:name # Name of the field returned
:is_aggregate # Boolean used to determine if the :value is an aggregate
:value # Value of the field returned. If it's an aggregate, the :value is a hash. Example:  { 'sum' => 20, 'avg' => 4, 'stddev' => 1.32 } 
 sum() # Method to return the 'sum' value of the field. If none exists, the method returns zero.
 avg() # Method to return the 'avg' value of the field.  If none exists, the method returns zero.
 stddev() # Method to return the 'stddev' value of the field.  If none exists, the method returns zero.

Example Code:

report = ap.query_analytics(query_parameters)

field_value = report.rows[0][:field].value

report.rows.each do |row|
  row.each do |field_name, field_object|
    if field_object.is_aggregate
       value = field_object.sum
    else
       value = field_object.value
    end   
  end
end

Query Parameters

Parameter Values Examples
sum any event or number dimension { "sum" => "plays" } or { "sum" => "plays,process_time" }
avg any event or number dimension { "avg" => "plays" } or { "avg" => "plays,process_time" }
stddev any event or number dimension { "stddev" => "plays" } or { "stddev" => "plays,process_time" }
fields any mapped dimension { "fields" => "user_name } or { "fields" => "user_name,location" }
customer any customer(s) associated with a service { "customer" => "lexmark" } or { "customer" => "lexmark,perceptive"
where <dimension> <operator> <value> { "where" => [ "begin_date gt 2013-12-10", "end_date lt 2013-12-20", "user_name eq bob", "location is null" ] }
   <dimension> any mapped dimension
   <operator> any valid operator
     lt less than operator { "where" => [ "end_date lt 2013-12-10" ] }
     gt greater than operator { "where" => [ "begin_date gt 2013-12-10" ] }
     eq equal to operator { "where" => [ "user_name eq bob" ] }
     lte less than equal to operator { "where" => [ "begin_date gte 2013-12-10" ] }
     gte greater than equal to operator { "where" => [ "end_date lte 2013-12-10" ] }
     in in operator for multiple values { "where" => [ "user_name in bob,ted,allen" ] }
     is is operator for Boolean and null value { "where" => [ "awesome is true" ] }
       empty no data has been written { "where" => [ "username is empty" ] }
       defined data written but could be nil { "where" => [ "username is defined" ] }
     is_not is not operator for Boolean and null value { "where" => [ "awesome is_not null" ] }
group_by any mapped dimension(s) { "group_by" => "user_name" } or { "group_by" => "user_name,location" }
order_by <dimension> <ascending or descending> { "order_by" => "user_name ascending" } or { "order_by" => "user_name descending" }
iterate_by YEAR, MONTH, DAY, or HOUR { "iterate_by" => "MONTH" } or { "iterate_by" => "HOUR" }
limit any integer value { "limit" => 10 }

Required sum, avg, stddev, and/or fields

Optional customer, where, group_by, order_by, and iterate_by

Note: iterate_by always uses the global event_time dimension.

Examples

 { "sum" => "plays", "customer" => "lexmark", "where" => [ "begin_date gt 2013-12-10", "end_date lt 2013-12-20"], "group_by" => "location", "order_by" => "location descending"  }
 { "sum" => "plays,download", "avg" => "process_time", "where" => [ "location in kentucky,kansas,california"], "group_by" => "location", "order_by" => "location descending"  }
 { "fields" => "location,user_name", "company" => "lexmark"}
 { "avg" => "plays", "customer" => "lexmark", "where" => [ "event_time gt 2013-12-10", "event_time lt 2013-12-20"], "iterate_by" => "DAY", "order_by" => "event_time descending"  }

License

2014 Lexmark International Technology S.A. All rights reserved.