Birst_Command 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e0ee23d32e4fa3869a26a0cc73406eb49759998a
+  data.tar.gz: 5625f8e217f41f750ef6d59b6c62398edc869e9c
+SHA512:
+  metadata.gz: 2ffdf314e6da5db90dd83298a5b2c1023541f6d90913057b43b3068d489629105cdf5b55aace2c8f74ff0977e8ae15546ca5c5dad968e59c680a3145afd18c48
+  data.tar.gz: 96dcb93b1b2e2f752c97e2840edb5bd339821772a42ad8ad51423f7af077fa7de5775e47ae4b555f75b6e9be6e6136ac28679f9fb54e0647808910d0614d6c8b

data/.bundle/config

@@ -0,0 +1,2 @@
+---
+BUNDLE_DISABLE_SHARED_GEMS: '1'

data/.gitignore

@@ -0,0 +1,3 @@
+*~
+/vendor
+/config.json

data/.ruby-version

@@ -0,0 +1 @@
+2.0.0-p353

data/Birst_Command.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+
+require 'Birst_Command/version'
+
+Gem::Specification.new do |s|
+  s.name        = "Birst_Command"
+  s.version     = Birst_Command::VERSION
+  s.authors     = ["Sterling Paramore"]
+  s.email       = ["gnilrets@gmail.com"]
+  s.homepage    = "https://github.com/gnilrets"
+  s.license     = "MIT"
+  s.summary     = "Birst Command"
+  s.description = "Ruby interface to Birst web API"
+
+  s.rubyforge_project = "Birst_Command"
+  s.add_runtime_dependency "savon", ["~> 2.0"]
+  s.add_runtime_dependency "httpclient", ["~> 2.3"]
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+gem 'savon', '~> 2.0'
+gem 'httpclient'

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Sterling Paramore
+
+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,127 @@
+Birst_Command
+====================
+
+Birst Command is a Ruby gem that allows you to build Ruby scripts that interface
+with the Birst Web API.
+
+
+# Installation & Setup
+
+Install the gem using `gem install Birst_Command` or using rvm or
+rbenv/bundler as you prefer.
+
+After installing, you'll need to create a Birst Command config file that contains
+the credentials you'll use to connect to Birst.  This config file should look like,
+
+    {
+        "wsdl": "https://login.bws.birst.com/CommandWebService.asmx?WSDL",
+        "endpoint": "https://login.bws.birst.com/CommandWebService.asmx",
+        "username": "name@myplace.com",
+        "password": "obfuscated pwd"
+    }
+
+Most users should only need to modify the username and password.  Since I have a strong
+aversion to storing passwords in plaintext, the password in the config file needs to
+be an obfuscated password.  Birst Command comes with a password obfuscator that can be
+executed via
+
+    $ obfuscate_pwd.rb mypassword
+    0x8GOZ5nA3oRSSS8ao1l6Q==
+
+Copy and paste the obfuscated password into the config file and **save
+to a secure location**.  If any attacker is able to get your
+obfuscated password and knows it was created using this program, it
+would be trivial to get your Birst login credentials.
+
+
+# Usage
+
+In your Ruby program, include the Birst Command gem and load the config file via
+
+    require 'rubygems'
+    require 'bundler/setup'
+    require 'Birst_Command'
+
+    Birst_Command::Config.read_config(File.join(File.dirname(__FILE__),"config.json"))
+
+Birst commands are submitted in session blocks, which automatically perform the
+process of logging in, tracking the login token, and logging out.  For example,
+to list all spaces that you have rights to, you can submit the following code
+
+    Birst_Command::Session.start do |bc|
+      spaces = bc.list_spaces
+      puts "#{JSON.pretty_generate spaces}"
+    end
+
+Which would return something like
+
+    {
+      "user_space": [
+        {
+          "name": "MyGreatSpace",
+          "owner": "name@myplace.com",
+          "id": "b413207d-3fe2-4309-1b4a-ac8e961daad2"
+        },
+        {
+          "name": "MyOtherGreatSpace",
+          "owner": "name@myplace.com",
+          "id": "a113207d-3fe2-4310-1b4a-b58e961da123"
+        }
+      ]
+    }
+
+The `spaces` variable is a Ruby hash parsed from the SOAP response.
+The structure of the returned hash follows the structure that Birst
+returns.
+
+
+## Helper Methods
+
+I find some of the Birst API responses to be rather cumbersome.  For
+example, why do I need hash with a single `user_space` key?  I'd
+rather have an array of hashes here.  To that end I find it convenient
+to define helper methods that extend the Session class to simplify
+some of this.  To override the return value of the native
+`list_spaces` command, you can do the following
+
+    class Birst_Command::Session
+      def list_spaces(*args)
+        result = command __method__, *args
+        [result[:user_space]].flatten
+      end 
+    end
+
+You can then execute the same `list_spaces` command above, but you get
+an array of hashes rather than hash with a key that points to an array
+of hashes.
+
+I have not included any of these helper methods in the Birst Command
+gem because what I find helpful, you may not.  Birst Command just
+provides the basic interface.
+
+## Command arguments
+
+Some Birst API commands require arguments.  All arguments are supplied as an argument
+hash.  For example, to create a new space,
+
+    Birst_Command::Session.start do |bc|
+      new_space_id = bc.create_new_space :spaceName => "myNewSpace",
+                                         :comments => "Just testing",
+                                         :automatic => "false"
+    end
+
+## camelCase/snake_case issues
+
+Birst Command uses [Savon](http://savonrb.com/version2/client.html) as
+the underlying framework used to communicate with the Birst SOAP API.
+Savon expects commands in snake_case format and converts them into
+camelCase when submitted to the Birst API (e.g., `list_spaces` is
+converted to `listSpaces`).  This behavior is *not* configurable.
+Savon also has options for converting the arguments of parameters from
+snake_case into camelCase.  Unfortunately, the Birst Web API is not
+entirely consistent in its use of camelCase for arguments (e.g.,
+`spaceId` is used in `deleteSpace` but `spaceID` is used in
+`listUsersInSpace`).  This inconsistency requires us to **submit
+commands as snake_case and arguments as the camelCase that Birst
+uses.**
+

data/Rakefile

@@ -0,0 +1,14 @@
+# -*- mode: ruby -*-
+
+require 'rake/testtask'
+
+task :default => [:test_all]
+
+# Run a specific unit test with `rake test TEST=test/Datalib/test_datalib.rb`
+Rake::TestTask.new do |t|
+
+  t.libs << "test"
+  t.test_files = FileList['test/*/test_*.rb']
+  t.verbose = true
+
+end

data/bin/obfuscate_pwd.rb

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+require File.join(File.dirname(__FILE__),"..","lib","birst_command")
+
+begin
+  puts Obfuscate.obfuscate(ARGV[0])
+rescue
+  puts "USAGE: ./obfuscate_pwd <plaintxt password>"
+end
+

data/config.json_template

@@ -0,0 +1,6 @@
+{
+    "wsdl": "https://login.bws.birst.com/CommandWebService.asmx?WSDL",
+    "endpoint": "https://login.bws.birst.com/CommandWebService.asmx",
+    "username": "name@myplace.com",
+    "password": "obfuscated pwd"
+}

data/lib/birst_command.rb

@@ -0,0 +1,10 @@
+require 'savon'
+require 'httpclient'
+require 'openssl'
+require 'base64'
+require 'json'
+
+require 'birst_command/config'
+require 'birst_command/obfuscate'
+require 'birst_command/session'
+

data/lib/birst_command/config.rb

@@ -0,0 +1,25 @@
+module Birst_Command
+  module Config
+    extend self
+
+    attr_accessor :config_full_path
+    @config_full_path = File.join(File.dirname(__FILE__),"../../config.json")
+
+    attr_accessor :options
+    @options = {
+      :soap_log_level => :error,
+      :soap_log => false
+    }
+
+    def read_config(config_full_path = @config_full_path)
+      @options = @options.merge!(JSON.parse(IO.read(config_full_path), :symbolize_names => true))
+    end
+    
+    def set_debug
+      @options = @options.merge!({
+                                  :soap_log_level => :debug,
+                                  :soap_log => true
+                                })
+    end
+  end
+end

data/lib/birst_command/obfuscate.rb

@@ -0,0 +1,35 @@
+module Birst_Command
+  module Obfuscate
+    extend self
+
+    @crypt_pwd = "BirstIsAwesome"
+    @salt = "31415927"
+    @cypher = "AES-128-CBC"
+
+    def obfuscate(pwd)
+      # Returns a base64-obfuscated password to be stored in the config.json file
+      encrypter = OpenSSL::Cipher::Cipher.new @cypher
+      encrypter.encrypt
+      encrypter.pkcs5_keyivgen @crypt_pwd, @salt
+
+      encrypted = encrypter.update pwd
+      encrypted << encrypter.final
+
+      Base64.encode64(encrypted).chomp
+    end
+
+
+    def deobfuscate(obfuscated_pwd)
+      # Returns a plaintext password
+      decrypter = OpenSSL::Cipher::Cipher.new @cypher
+      decrypter.decrypt
+      decrypter.pkcs5_keyivgen @crypt_pwd, @salt
+
+      plain = decrypter.update Base64.decode64(obfuscated_pwd)
+      plain << decrypter.final
+
+      plain
+    end
+
+  end
+end

data/lib/birst_command/session.rb

@@ -0,0 +1,70 @@
+module Birst_Command
+  class Session
+    def initialize
+      @options = Birst_Command::Config.options
+
+      @client = Savon.client(
+        wsdl: @options[:wsdl],
+        endpoint: @options[:endpoint],
+        convert_request_keys_to: :none,
+        soap_version: 1,
+        pretty_print_xml: true,
+        filters: [:password],
+        log_level: @options[:soap_log_level],
+        log: @options[:soap_log]
+      )
+
+      @response = nil
+      @token = nil
+      @auth_cookies = nil
+    end
+
+    attr_reader :token
+    attr_reader :auth_cookies
+    attr_reader :response
+
+
+    def self.start(&b)
+      session = self.new
+      session.login
+      session.execute_block(&b)
+    ensure
+      session.logout
+    end
+
+
+    def login
+      @response = @client.call(:login,
+        message: {
+          username: @options[:username], 
+          password: Obfuscate.deobfuscate(@options[:password])
+        })
+
+      @auth_cookies = @response.http.cookies
+      @token = @response.hash[:envelope][:body][:login_response][:login_result]      
+    end
+
+
+    def execute_block(&b)
+      yield self
+    end
+
+
+    def method_missing(command_name, *args)
+      command command_name, *args
+    end
+
+
+    def command(command_name, *args)
+      response_key = "#{command_name}_response".to_sym
+      result_key = "#{command_name}_result".to_sym
+
+      message = args.last.is_a?(Hash) ? args.pop : {}
+      result = @client.call command_name,
+                            cookies: @auth_cookies,
+                            message: { :token => @token }.merge(message)
+
+      result.hash[:envelope][:body][response_key][result_key]
+    end
+  end
+end

data/lib/birst_command/version.rb

@@ -0,0 +1,3 @@
+module Birst_Command
+  VERSION = "0.1.0"
+end

data/test/.gitignore

@@ -0,0 +1 @@
+/config_test.json

data/test/config_test.json_template

@@ -0,0 +1,8 @@
+{
+    "test": {
+        "test_add_user_to_space": {
+            "username": "mytestuser@company.com",
+            "space_id": "MYTESTSPACEID"
+        }
+    }
+}

data/test/standard/resources/config_test.json

@@ -0,0 +1,4 @@
+{
+    "username": "name@myplace.com",
+    "password": "obfuscated pwd"
+}

data/test/standard/test_add_user_to_space.rb

@@ -0,0 +1,49 @@
+require "test_birst_command"
+
+class Test_add_user_to_space < Test::Unit::TestCase
+
+  def setup
+    Birst_Command::Config.read_config
+    Birst_Command::Config.read_config(File.join(File.dirname(__FILE__),"../config_test.json"))
+    @test_options = Birst_Command::Config.options[:test][:test_add_user_to_space]
+  end
+
+
+  def teardown
+  end
+
+
+  def user_exists?
+    result = nil
+    Session.start do |bc|
+      users = bc.list_users_in_space :spaceID => @test_options[:space_id]
+      result = [users[:string]].flatten.include? @test_options[:username]
+    end
+    result
+  end
+
+
+  def test_add_user_to_space
+    Session.start do |bc|
+      bc.add_user_to_space :userName => @test_options[:username],
+                           :spaceID => @test_options[:space_id],
+                           :hasAdmin => "false"
+    end
+
+    assert user_exists?, "User #{@test_options[:username]} not added!"
+  end
+
+
+  def test_remove_user_from_space
+    test_add_user_to_space if !user_exists?
+
+    Session.start do |bc|
+      bc.remove_user_from_space :userName => @test_options[:username],
+                                :spaceID => @test_options[:space_id]
+    end
+
+    assert !user_exists?, "User #{@test_options[:username]} should no longer exist!"
+  end
+end
+
+

data/test/standard/test_command_helper.rb

@@ -0,0 +1,44 @@
+require "test_birst_command"
+
+class Test_command_helper < Test::Unit::TestCase
+
+  # Decided that commands should return whatever the Birst API returns.
+  # However, for user code, it would be helpful to customize returns for
+  # specific use cases
+
+  class Session < Birst_Command::Session
+    def list_spaces(*args)
+      result = command __method__, *args
+      [result[:user_space]].flatten
+    end 
+    def list_users_in_space(*args)
+      result = command __method__, *args
+      [result[:string]].flatten
+    end
+ end
+
+
+  def setup
+    Birst_Command::Config.read_config
+    Birst_Command::Config.read_config(File.join(File.dirname(__FILE__),"../config_test.json"))
+  end
+
+  def teardown
+  end
+
+  def test_add_user_to_space
+    test_options = Birst_Command::Config.options[:test][:test_add_user_to_space]
+
+    spaces = nil
+    users = nil
+    Session.start do |bc|
+      spaces = bc.list_spaces
+      users = bc.list_users_in_space :spaceID => test_options[:space_id]
+    end
+
+    assert spaces.is_a?(Array), "list_spaces helper did not return an array"
+    assert !spaces[0].has_key?(:user_space), "list_spaces helper should not give :user_space"
+  end
+end
+
+

data/test/standard/test_copy_space.rb

@@ -0,0 +1,55 @@
+require "test_birst_command"
+
+class Test_copy_space < Test::Unit::TestCase
+
+  def setup
+    Birst_Command::Config.read_config
+    Birst_Command::Config.read_config(File.join(File.dirname(__FILE__),"../config_test.json"))
+    @new_space_id = nil
+  end
+
+  def teardown
+    Session.start do |bc|
+      bc.delete_space :spaceId => @new_space_id
+    end
+  end
+
+  def test_copy_space
+    test_options = Birst_Command::Config.options[:test][:test_copy_space]
+
+    Session.start do |bc|
+      @new_space_id = bc.create_new_space :spaceName => "test_copy_space",
+                                          :comments => "",
+                                          :automatic => "false"
+
+      puts "#{JSON.pretty_generate bc.list_spaces}"
+      job_token = bc.copy_space :spFromID => test_options[:from_space_id],
+                                :spToID => @new_space_id,
+                                :mode => "copy",
+                                :options => "data;settings-permissions;settings-membership;repository;birst-connect;custom-subject-areas;dashboardstyles;salesforce;catalog;CustomGeoMaps.xml;spacesettings.xml;SavedExpressions.xml;DrillMaps.xml;connectors;datastore-aggregates;settings-basic"
+
+
+      i = 0
+      loop do
+        i += 1
+        if i < 60
+          status = bc.get_job_status :jobToken => job_token
+          puts "#{JSON.pretty_generate status}"
+
+          is_job_complete = bc.is_job_complete :jobToken => job_token
+          puts "COMPLETE? #{is_job_complete}"
+          sleep 1
+
+          break if is_job_complete
+        else
+          raise "Copy job timed out"
+        end
+      end
+
+
+    end
+
+    assert_equal 36, @new_space_id.length, "Got an invalid space id #{@new_space_id}"
+  end
+end
+

data/test/standard/test_deobfuscate.rb

@@ -0,0 +1,23 @@
+require "test_birst_command"
+
+class Test_deobfuscate < Test::Unit::TestCase
+
+  def setup
+    @pwd = "mysecretpass"
+    @obs_pwd = "IQX4os6wCE7rl+JuSYL2Iw=="
+  end
+
+  def teardown
+  end
+
+  def test_obfuscate
+    assert_equal @obs_pwd, Obfuscate.obfuscate(@pwd), "Expecting password #{@obs_pwd}"
+  end
+
+  def test_deobfuscate
+    assert_equal @pwd, Obfuscate.deobfuscate(@obs_pwd), "Expecting password #{@pwd}"
+  end
+
+end
+
+

data/test/standard/test_list_spaces.rb

@@ -0,0 +1,24 @@
+require "test_birst_command"
+
+class Test_list_spaces < Test::Unit::TestCase
+
+  def setup
+    Birst_Command::Config.read_config
+  end
+
+  def teardown
+  end
+
+  def test_list_spaces
+    spaces = nil
+    Session.start do |bc|
+      unclean_spaces = bc.list_spaces
+      spaces = [unclean_spaces[:user_space]].flatten
+    end
+
+    assert spaces.is_a?(Array), "Expecting spaces to be an array"
+    assert spaces[0].is_a?(Hash), "Expecting spaces to be an array of hashes"
+  end
+end
+
+

data/test/standard/test_login.rb

@@ -0,0 +1,23 @@
+require "test_birst_command"
+
+class Test_login < Test::Unit::TestCase
+
+  def setup
+    Birst_Command::Config.read_config
+  end
+
+  def teardown
+  end
+
+  def test_login
+    token = ""
+    Session.start do |bc|
+      token = bc.token
+    end
+
+    assert_equal 32, token.length, "Got an invalid token #{token}"
+  end
+
+end
+
+

data/test/standard/test_read_config.rb

@@ -0,0 +1,18 @@
+require "test_birst_command"
+
+class Test_read_config < Test::Unit::TestCase
+
+  def setup
+  end
+
+  def teardown
+  end
+
+  def test_read_config
+    Birst_Command::Config.read_config(File.join(File.dirname(__FILE__),"resources/config_test.json"))
+    assert_equal "name@myplace.com", Birst_Command::Config.options[:username], "Error with config file"
+  end
+
+end
+
+

data/test/test_birst_command.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'birst_command'
+require 'test/unit'
+require 'benchmark'
+
+Birst_Command::Config.set_debug
+
+include Birst_Command

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: Birst_Command
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sterling Paramore
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-03-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: savon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: httpclient
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.3'
+description: Ruby interface to Birst web API
+email:
+- gnilrets@gmail.com
+executables:
+- obfuscate_pwd.rb
+extensions: []
+extra_rdoc_files: []
+files:
+- .bundle/config
+- .gitignore
+- .ruby-version
+- Birst_Command.gemspec
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- bin/obfuscate_pwd.rb
+- config.json_template
+- lib/birst_command.rb
+- lib/birst_command/config.rb
+- lib/birst_command/obfuscate.rb
+- lib/birst_command/session.rb
+- lib/birst_command/version.rb
+- test/.gitignore
+- test/config_test.json_template
+- test/standard/resources/config_test.json
+- test/standard/test_add_user_to_space.rb
+- test/standard/test_command_helper.rb
+- test/standard/test_copy_space.rb
+- test/standard/test_deobfuscate.rb
+- test/standard/test_list_spaces.rb
+- test/standard/test_login.rb
+- test/standard/test_read_config.rb
+- test/test_birst_command.rb
+homepage: https://github.com/gnilrets
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: Birst_Command
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Birst Command
+test_files:
+- test/config_test.json_template
+- test/standard/resources/config_test.json
+- test/standard/test_add_user_to_space.rb
+- test/standard/test_command_helper.rb
+- test/standard/test_copy_space.rb
+- test/standard/test_deobfuscate.rb
+- test/standard/test_list_spaces.rb
+- test/standard/test_login.rb
+- test/standard/test_read_config.rb
+- test/test_birst_command.rb