We’re growing. You may have heard that we were acquired in 2012. You might also have heard that we’ve been spun out again as a core part of a new company that shares part of our name. From when I started at Pivotal Labs back in 2009, we’ve grown by a factor of six just within ‘Labs and we’re now part of an organization that’s twelve hundred strong. If you were watching our org chart during this time you might have wondered where we got the magic beans for that growing bean stalk.

When I started four years ago we all “reported” to one person, and we talked a lot about being a “flat” organization. Then we got multiple offices, and added a local director layer. Then office head count grew beyond one director having a close relationship with all of the pivots and keeping up with director duties, so we added managers. Then we got enough managers and head count still growing that we needed associate directors. At the same time we got two more levels added on top of the head of our company when we were spun out. Given all of this change, you can relate to my astonishment when just last week I heard a pivot say, “We’re a flat organization.” Double woah.

For a pivot, one who is eight degrees of separation away from the head of the company, to say “we’re flat” means he’s feeling something that isn’t reflected in an org chart. As he talked more about it, he clarified that in terms of day-to-day individual, pair, and team activities there is still the same huge amount of autonomy. There’s no boss or manager in the traditional sense telling you what to do. You get to decide as a team what the right priorities are. You and your pair get to decide if you should do this refactoring now, or raise it up to the rest of the team as part of a larger effort. In terms of how you work on your project, you have as much influence as anyone else. The flatness is still the same in many ways as it was four years and a thousand people ago.

Moving up, let’s say you want to affect some change at the office level. Your first option is to go one step up the on-paper org chart, but really it’s a lateral move: Talk to your manager. At Pivotal Labs, your manager is more of a buddy or coach. Your manager is not on your project, your manager does not assign you work. He’s there to help you process feedback, help you find new ways to use your skills that also help the company, and navigate the company infrastructure so that you don’t have to keep it all in your head. Your manager might give you some advice on things to try, people to talk to, or green light some pizza budget so you can host an event after hours. Otherwise he might encourage you to talk directly to the office director who always has a door open for pivots who want to make their workplace better – and note that you’re skipping right over the manager and associate director levels.

From there, if you’re looking to make some cross office improvements, you’re just one door away from the COO of Pivotal Labs. At this point you probably can’t just drop in and instead you’ll have to schedule something on his calendar, but he’s the kind of guy that’s easy to trust. What I always find fascinating is that I have yet to surprise him – like you might expect a COO to do, he’s always thinking about making the company better and he’s good at finding ways to put passionate pivots to use. Similarly, you can get lunch or coffee with our founder who is a great example of an active listener.

Moving up to the company level I haven’t had any direct experience with those folks, but I know they expect the Pivotal Labs Way to become the Pivotal Way the same that we’ve always expected the Pivotal Labs Way to become the way our clients do software development. The way we’ve accomplished that in the past is by pairing with them on their projects. It is for this reason that I’ve asked to do a rotation on CloudFoundry, one of our core projects from Pivotal. By sharing my practices, I hope they carry them forward as they engage with other parts of Pivotal and those teams with the teams they overlap with, and so on.

Yes, the org chart is a lot deeper now than it once was. It’s clear though that pivots still have a voice and they still have all the autonomy to manage their own day-to-day. What’s interesting is that now my lever arm is potentially even longer than it was before because I’m now at the center of an organization that is designed around the way I work and I have an opportunity to shape the way more people make software than ever before.

Google has a ton of APIs, and a fistful of authentication methods to match – everything from  3-legged OAuth2 to proprietary protocols like AuthSub. I’m in the middle of building out a One-click installable Google App for Enterprise/Education (ya know, when your company uses their domain but you get all the niceness of GMail and related Google tools) but I found the Ruby documentation lacking and even misleading. Furthermore, the existing gems that are available are too often focused on non-Google Apps development or return you an unparsed Atom feed, barely giving you any functionality beyond making a Net::HTTP request yourself. Despite all this, I’ve persevered, and what follows is the summation of my findings.

First off, make a new app in the Google Apps Marketplace. The documentation on this is pretty decent. It involves creating a couple of XML files. The openIdRealm is relevant. I set mine to my production URL and had no trouble in development (localhost:3000). What is important though is that your openIdRealm is different from the domain that you’re using to install the app. Initially, I was using loopb.ac as my openIdRealm (and thus my production URL), and it was the same domain I was using for GMail. I ran in to timeout issues when I went to production. I changed my openIdRealm and production URL to app.loopb.ac and things started working smoothly again.

Once you’ve got an app (no need to submit it for approval yet) you can get your OAuth credentials.

This is where you get the OAuth credentials for your app

After you click the link, you’ll want to grab the “Consumer Key” and the “Consumer Key Secret”.

You’re going to be using 2-legged OAuth. This is a bit different than if you’ve used Twitter for SSO. In Twitter’s case you’re most likely using 3-legged OAuth to act on behalf of the individual user. In the case of Google Apps, you’re asking for privileges when the domain admin (aka the IT person at example.com) when s/he installs your app for all of the users in the domain. That way, you don’t have to make each user in the domain decide if it is okay for your app to read their calendar appointments.

You’re going to need two gems, oauth, and omniauth-google-apps. I didn’t seem to need the oauth gem till I deployed to Heroku.

gem 'oauth'
gem 'omniauth-google-apps'

Then, configure omniauth. Make a new file, config/initializers/omniauth.rb with the following contents:

require 'openid/store/filesystem'
Rails.application.config.middleware.use OmniAuth::Builder do
  provider :google_apps, :store => OpenID::Store::Filesystem.new('./tmp')
end

The store option is… optional. But if you’re going out to Heroku you’ll want to include it and make sure that the path is ./tmp so as to work with Heroku’s read-only file system.

You can implement a pretty standard looking ApplicationController. See the gist at the end for an example. Basically to sign in you’ll need to redirect the user to /auth/google_apps. You’ll also want a callback endpoint for Google to hit. In your routes.rb:

match "/auth/:provider/callback" => "sessions#create"

Fill in your sessions controller to handle the information in the params and sign the user in. There’s an example in the gist. Next, we’ll need a client class to talk to Google’s APIs. Nothing too unexpected here, but this is where the ID and Secret are used – since the domain admin approved your app, you use the app’s credentials, not the user’s to access information. All of Google’s APIs that I’ve needed return Atom feeds, so this’ll parse them in to REXML docs, or raise a 500 if something went wrong.

#lib/google/client.rb
require 'oauth'
require 'rexml/document'

module Google

  class Client
    attr_accessor :version

    def self.get(base, query_parameters, version = '2.0')
      make_request(:get, url(base, query_parameters), version)
    end

    private

    def self.make_request(method, url, version)
      oauth_consumer = OAuth::Consumer.new(GOOGLE_APP_ID, GOOGLE_APP_SECRET)
      access_token = OAuth::AccessToken.new(oauth_consumer)

      response = access_token.request(method, url, {'GData-Version' => version})
      if response.is_a?(Net::HTTPFound)
        return make_request(method, response['Location'], version)
      end
      return unless response.is_a?(Net::HTTPSuccess)
      feed = REXML::Document.new(response.body)
      throw :halt, [500, "Unable to query feed"] if feed.nil?
      feed
    end

    def self.url(base, query_parameters={})
      url = base
      unless query_parameters.empty?
        url += '?'
        query_parameters.each { |key, value| url += "#{CGI::escape(key)}=#{CGI::escape(value)}&" }
        url.chop!
      end
      url
    end
  end
end

Great, so how about we get a user’s private contacts? No problem! Here’s the Contact class that uses our client:

#lib/google/contact.rb
module Google
  class Contact
    attr_accessor :full_name, :first_name, :last_name, :email, :company, :title, :notes

    def self.all(email)
      feed = Google::Client.get("https://www.google.com/m8/feeds/contacts/default/full", {
          'xoauth_requestor_id' => email
      }, '3.0')

      feed.elements.collect('//entry') do |entry|
        new(
            :full_name => entry.elements["gd:name"].elements["gd:fullName"].text,
            :first_name => entry.elements["gd:name"].elements["gd:givenName"].text,
            ...
        )
      end
    end

    def initialize(options = {})
      @full_name = options[:full_name]
      @first_name = options[:first_name]
      ...
    end
  end
end

Modstly a lot of boilerplate to pull out the meaningful attributes form the XML. The one thing to notice is the query param we pass to the client,

'xoauth_requestor_id' => email

In the case of a lot of the Google Data APIs, we need this parameter so the API knows who’s contacts we’re going after. For example, a Calendar class would look almost identical save the differing XML fields. Don’t get too comfortable though, what you probably want is to get a list of all users in this domain, not the personal contacts of a particular user. In that case you’ll want to use the Google Provisioning API. At first read of the docs, you see that it too supports the 2-legged auth that we used for contacts, but if you make a carbon copy you’re going to get an “Invalid Token” error. Uhhh, what? Turns out, the xoauth_requestor_id is not only not needed, it’ll cause problems if you include it. The email address isn’t required at all, which makes sense as you’re getting all the users in a domain and don’t really care who the current user is:

#lib/google/user.rb
module Google
  class User
    attr_accessor :login, :first_name, :last_name
    def self.all(domain)
      feed = Google::Client.get("https://apps-apis.google.com/a/feeds/#{domain}/user/2.0", {
          'get' => 'all'
      })
      feed.elements.collect('//entry') { |e| new_from_entry(e) }
    end
 
    def initialize(options ={})
      ...
    end
 
    private
 
    def self.new_from_entry(entry)
      new(
          ...
      )
    end
  end
end

There you have it. Hopefully I’ve saved you the countless hours of reading documentation, Googling for “Google”, and beating your head against any vertical surface as I did. Happy App development!

See the full gist here. Comments and pull requests welcome!