Birst_Command

Birst Command is a Ruby gem that allows you to build Ruby scripts that interface with the Birst Web API.

Note: this is not an officially-sanctioned Birst project. I'm just a Birst user that needed to set up a very basic Ruby interface.

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 - Birst command line tool

Birst Command also installs a rudimentary command line tool for interacting with the Birst web API. It's still very simple. If you want more functionality, please drop me a line in the github repository.

To use the command line tool, put the config file created above in $HOME/.birstcl. Then run Birst commands using birstcl. You'll have to refer to the Birst Documentation for a full list of commands. All birst commands should be submitted using snake_case and arguments using the exact camelCase specified in the Birst documentation. See below for an explanation of this bizarre requirement. Here are some examples:

List spaces

birstcl -c list_spaces

Get list of sources for a space

birstcl -c get_sources_list -a '{ spaceID: "383nf0d7-3875-3829-3hff-faba8936180a" }'

Copy space with options

birstcl -c copy_space -a '{ spFromID: "9ab9865c-37a8-0586-e856-ddd3856a0371", spToID: "3957a9b7-38c1-175v-3985-1957f1836a93", mode: "replicate", options: "data;repository;settings-basic" }'

Usage - As Ruby library

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 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.