analytics-psw 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9690e2147d8783257c8dac2434b4aaeefc43e685
-  data.tar.gz: ac1356c8a0a8eda726162ee4140d48a3a143c570
+  metadata.gz: d4fa2b78f7161b203949aaec9147366adac7386d
+  data.tar.gz: 0751907236b4d8818631a3d05abaa7e921f17ee2
 SHA512:
-  metadata.gz: 4910eea5494ffd59db4dbb55df02172ed2b8fc366116d576b60fda4de474401be469cafb189fe4a6b4c9094bb176b6b2605bd5a727d727e126d64e6faec9bc63
-  data.tar.gz: 14776571c8758a048240c65d56025638ee1807a67e73d035eb99de42cd4c885cc003dd2b360c1a7706d0fd82768e66f4fd1d97e65aee603a48741ad5aed90f53
+  metadata.gz: 5ceb1eda25f11c5d400f64f89f062673c68b8d9e188a7dc2d3a9ac6767201b8f5f943e50f81b9c3ccf2962673f82c901b498cc2936abfeb0c5b6cb5a338ec5ea
+  data.tar.gz: 89e882fa97e60d5b6f037eb6134698820c8f8b3d8b9625e0ee2a73f0fe5b473e761637762ce9754f3058a46f700bcb7a3dea839691eed052006ad5995918423e

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Jordan Keyes
+
+MIT License
+
+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,133 @@
+# 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
+
+``` ruby
+require 'analytics-psw'
+require 'yaml' #optional, for importing information used to connect to the Analytics service
+```
+###Options in .rb file
+
+``` ruby
+opts = {}
+opts['server_url'] = "http://my.server.url"     #required. No trailing slash needed
+opts['service'] = "MyServiceName"               #required. Calling AnalyticsPSW.new will search for your service, and if it isn't found, create it
+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
+opts['event_types'] = ["event_one", "event_two", "event_three"] #optional, will create event types to associate with your service if they don't already exist
+opts['dimensions'] = [{"dimension_name" => "string"}, {"dimension_2" => "integer"}] #optional, will create dimensions to describe your events if they don't already exist
+
+ap = AnalyticsPSW.new(opts)
+```
+
+### Options in separate .yml file
+``` ruby
+ap = AnalyticsPSW.new(YAML.load_file(analytics_settings.yml))
+```
+
+### Sample YAML file
+```
+---
+server_url: http://127.0.0.1:3000
+service: my_service
+event_types:
+- event_one
+- event_two
+
+dimensions:
+- dimension_one: string
+- dimension_two: integer
+```
+
+## Available Methods
+
+``` ruby
+ap.record_event(event_type, metadata = {}) # sends an event to the Analytics service. Event_type must exist on the Analytics system
+
+ap.query_analytics(query_parameters) # sends a hashmap query to the Analytics service. Possible keys include: required: one or more of :sum, :avg, :fields, optional: :customer, :where, :group_by, :order_by, :iterage_by. Use comma-separated strings if multiple values are needed
+ap.create_report(name, query_parameters) # create a report query to be ran later.  'query_parameters' same as above.
+ap.list_reports # list all reports for a service
+ap.show_report(report_id) # list the properties for a report
+ap.run_report(report_id, where_criteria) # run a stored report.  'where_criteria' are options 'where' paramters to replace in the stored report when running.
+ap.delete_report(report_id) # delete a stored report
+
+ap.create_service(name)  # creates a new service
+ap.list_service # list all available services
+ap.show_service_resource(service_id) # list available resources for a service
+ap.show_service_metadata(service_id) # list the properties of a service
+ap.delete_service(service_id) # delete a report
+
+ap.create_event_type(name, description = "") # creates an event type for the service being used
+ap.list_event_types #list all event types for a service
+ap.show_event_type(event_type_id) # list properties of an event type
+
+ap.create_dimension(name, data_type, units = "", description = "") # creates a new dimension (field that describes an event, but isn't tied to any one event). Only name and data_type are required.
+ap.list_dimensions  # list all dimensions for a service
+ap.show_dimension_resources(dimension_id) # list available resources for a dimension
+ap.show_dimension_metadata(dimension_id)  # list metadata for a dimension
+
+ap.create_dimension_properties(dimension_name, dimension_value, property_hash) # adds properties to a dimension value. This will return status=409 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) # updates 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) # adds propertie to a dimension value if they already exist. Updates the properties otherwise.  This will return status=409 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.show_dimension_properties(dimension_name, dimension_value) # get the properties currently set for a dimension value.  The body will be json.
+ap.list_dimension_properties(dimension_name) # list all values that have properties set.  This will return a json object with an array of json/location pairs.
+```
+
+## 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" } `                                                      |
+| ` fields `         | ` any mapped dimension `                   | ` { "fields" => "user_name } or { "fields" => "user_name,location" } `                                             |
+| ` customer `       | ` any customer associated with a service ` | ` { "customer" => "lexmark" } `                                                                                    |
+| ` 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 `                     |                                                                                                                    |
+| ` - - ls  `        | ` 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" ] }`                                                                            |
+| ` 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`, and/or `fields`
+
+**Optional** `customer`, `where`, `group_by`, `order_by`, and `iterate_by`
+
+Note: `iterate_by` always uses the global `event_time` dimension.
+
+**Examples**
+``` ruby
+ { "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
+
+2013 Lexmark International Technology S.A. All rights reserved.

data/lib/analytics_dimension_properties.rb

@@ -0,0 +1,87 @@
+module AnalyticsDimensionProperties
+
+  SERVICE_NAME_PARAM = 'service_name'
+  DIMENSION_NAME_PARAM = 'dimension_name'
+  DIMENSION_PROPERTY_VALUE_PARAM = 'dimension_property_value'
+
+  def list_dimension_properties(dimension_name)
+    response = request_uri_to_dimension_properties(dimension_name)
+    if valid_uri_response?(response)
+      uri = uri_from_uri_response(response)
+      response = get_with_hash(uri)
+    end
+    parse_json_response(response)
+  end
+
+  def show_dimension_properties(dimension_name, dimension_value)
+    response = request_uri_to_dimension_properties(dimension_name, dimension_value)
+    if valid_uri_response?(response)
+      uri = uri_from_uri_response(response)
+      response = get_with_hash(uri)
+    end
+    parse_json_response(response)
+  end
+
+  def create_dimension_properties(dimension_name, dimension_value, properties = {})
+    metadata = create_dimension_properties_metadata(dimension_value, properties)
+    response = request_uri_to_dimension_properties(dimension_name)
+    if valid_uri_response?(response)
+      uri = uri_from_uri_response(response)
+      response = post_json(uri, "dimension_property", metadata)
+    end
+    parse_json_response(response)
+  end
+
+  def update_dimension_properties(dimension_name, dimension_value, properties = {})
+    metadata = create_dimension_properties_metadata(dimension_value, properties)
+    response = request_uri_to_dimension_properties(dimension_name, dimension_value)
+    if valid_uri_response?(response)
+      uri = uri_from_uri_response(response)
+      response = put_json(uri, "dimension_property", metadata)
+    end
+    parse_json_response(response)
+  end
+
+  def create_or_update_dimension_properties(dimension_name, dimension_value, properties = {})
+    response = request_uri_to_dimension_properties(dimension_name, dimension_value)
+    if valid_uri_response?(response)
+      return update_dimension_properties(dimension_name, dimension_value, properties)
+    end
+    create_dimension_properties(dimension_name, dimension_value, properties)
+  end
+
+  private
+
+  def create_dimension_properties_metadata(dimension_value, properties)
+    dimension_properties_body = {'value' => dimension_value, 'properties' => {}}
+    properties.each do |key, value|
+      dimension_properties_body['properties'][key] = value unless value == ""
+    end
+    dimension_properties_body
+  end
+
+  def request_uri_to_dimension_properties(dimension_name, dimension_value = nil)
+    uri_path = "#{@server_url}/uris/dimension_property"
+    uri_path_query_params = dimension_property_uri_query_params(dimension_name, dimension_value)
+    get_with_hash(uri_path, uri_path_query_params)
+  end
+
+  def valid_uri_response?(uri_response)
+    uri_response.status == 200
+  end
+
+  def uri_from_uri_response(uri_response)
+    parsed_json_body = JSON.parse(uri_response.body)
+    parsed_json_body['uri']['location']
+  end
+
+  def dimension_property_uri_query_params(dimension_name, dimension_value)
+    query_params = {
+      SERVICE_NAME_PARAM => @service_name,
+      DIMENSION_NAME_PARAM => dimension_name,
+    }
+    query_params[DIMENSION_PROPERTY_VALUE_PARAM] = dimension_value unless dimension_value.nil?
+    query_params
+  end
+
+end

data/lib/analytics_dimensions.rb

@@ -0,0 +1,24 @@
+module AnalyticsDimensions
+
+  def create_dimension(name, data_type, units = "", description = "")
+    metadata = create_metadata({:name => name, :description => description, :data_type => data_type, :units => units})
+    resp = post_json("#{@service_location}/dimensions", "dimension", metadata)
+    parse_json_response(resp)
+  end
+
+  def list_dimensions
+    resp = get_with_hash("#{@service_location}/dimensions")
+    parse_json_response(resp)
+  end
+
+  def show_dimension_resources(dimension_id)
+    resp = get_with_hash("#{@service_location}/dimensions/#{dimension_id}")
+    parse_json_response(resp)
+  end
+
+  def show_dimension_metadata(dimension_id)
+    resp = get_with_hash("#{@service_location}/dimensions/#{dimension_id}/metadata")
+    parse_json_response(resp)
+  end
+
+end

data/lib/analytics_event_types.rb

@@ -0,0 +1,19 @@
+module AnalyticsEventTypes
+
+  def create_event_type(name, description = "")
+    metadata = create_metadata({:name => name, :description => description})
+    resp = post_json("#{@service_location}/event_types", "event_type", metadata)
+    parse_json_response(resp)
+  end
+
+  def list_event_types
+    resp = get_with_hash("#{@service_location}/event_types")
+    parse_json_response(resp)
+  end
+
+  def show_event_type(event_type_id)
+    resp = get_with_hash("#{@service_location}/event_types/#{event_type_id}")
+    parse_json_response(resp)
+  end
+
+end

data/lib/analytics_reports.rb

@@ -0,0 +1,35 @@
+module AnalyticsReports
+
+  def query_analytics(query_parameters)
+    resp = get_with_hash("#{@service_location}/reports/query.json", query_parameters)
+    raise "Problem with your query. Please check the required parameters and try again" if resp.status == 400
+    parse_json_response(resp)
+  end
+
+  def create_report(name, query_parameters)
+    query_parameters[:name] = name
+    resp = post_json("#{@service_location}/reports", "report", query_parameters )
+    parse_json_response(resp)
+  end
+
+  def list_reports
+    resp = get_with_hash("#{@service_location}/reports")
+    parse_json_response(resp)
+  end
+
+  def show_report(report_id)
+    resp = get_with_hash("#{@service_location}/reports/#{report_id}")
+    parse_json_response(resp)
+  end
+
+  def run_report(report_id, where_criteria = {})
+    resp = get_with_hash("#{@service_location}/reports/#{report_id}/results", where_criteria)
+    parse_json_response(resp)
+  end
+
+  def delete_report(report_id)
+    resp = delete_resource("#{@service_location}/reports/#{report_id}")
+    parse_json_response(resp)
+  end
+
+end

data/lib/analytics_services.rb

@@ -0,0 +1,26 @@
+module AnalyticsServices
+
+  def create_service(name)
+    create_service_private(name)
+  end
+
+  def list_services
+    resp = get_with_hash("/services")
+    parse_json_response(resp)
+  end
+
+  def show_service_resources(service_id)
+    resp = get_with_hash("/services/#{service_id}")
+    parse_json_response(resp)
+  end
+
+  def show_service_metadata(service_id)
+    resp = get_with_hash("/services/#{service_id}/metadata")
+    parse_json_response(resp)
+  end
+
+  def delete_service(service_id)
+    resp = delete_resource("/services/#{service_id}")
+    parse_json_response(resp)
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: analytics-psw
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Jordan Keyes
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-20 00:00:00.000000000 Z
+date: 2014-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -89,6 +89,13 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/analytics-psw.rb
+- lib/analytics_dimension_properties.rb
+- lib/analytics_dimensions.rb
+- lib/analytics_event_types.rb
+- lib/analytics_reports.rb
+- lib/analytics_services.rb
+- LICENSE.txt
+- README.md
 homepage: 
 licenses:
 - 3-Clause BSD