This gem should serve as a convenient way, how to work with user hierarchies. This was specifically tailored for the model used in Salesforce because we work a lot with it. If you are not familiar with it the user is stored in Salesforce db like this

Name,ID,ManagerID
Joe,1,2
Bob,2,3
Jim,3,

This is called adjacency list. This gem wraps these lines in a model and enables to express the relationships in reasonable methods so even a mediocre guy should be able to get something out of it if he knows enough ruby. The problem with adjacency lists are that they are quite nice to work with in programming languages but rather unpleasant to use in SQL like languages (if they do not implement recursion that is). To see this in action.

In SOQL you can very effectively write something like

SELECT Name, Manager.Name where ID = 1

But it is very tricky to get list of all managers/subordinates of Joe or to determine if Jim and Bob are on the same level in the hierarchy. Generally without recursion you cannot achieve easily similar results in SQL. The same problem is much easier in a general programming language like Ruby. And with nice API it can be even easy to read.

require 'user_hierarchies'

GoodData::UserHierarchies::UserHierarchy.load_users_from_sf("login", "pass") do |hierarchy|
  hierarchy.users.each do |user|
      puts "#{user.Email} => #{user.all_subordinates.map {|s| s.Email}.join(", ")}" if user.manager?
  end
end

This script will download the hierarchy from SF account with credentials you provide and prints all subordinates of a person if that person has any. You can do the same for a file

GoodData::UserHierarchies::UserHierarchy.read_from_csv('sample_hierarchy.csv', {
  :user_id => 'Id',
  :manager_id => 'ManagerId'
}) do |hierarchy|
  hierarchy.users.each do |user|
      puts "#{user.name} => #{user.all_subordinates.map {|s| s.name}.join(", ")}" if user.manager?
  end
end

The code is not exactly the same as before but the only additional thing is to provide hints about the fields which are used to identify each user and the field that identifies the manager.

The default is ID and MANAGERID so you can omit the definition if you conform to that.

• Arbitrary fields

On top of that that there is little meta programming magic built in so if you have for example some additional information that you would like to use say

name,user_id,manager_id,some_arbitrary_info
Joe,1,2,Foo
Bob,2,3,Bar
Jim,3,,Baz

It is very easy to use this information in your program

GoodData::UserHierarchies::UserHierarchy.read_from_csv("file_name") do |hierarchy|
    hierarchy.users.each do |user|
        puts "#{user.name} => #{user.some_arbitrary_info}"
    end
end

As you can see the method name is based on the header of csv

• Interactive Usage

Sometimes it is nice to just dive inside the hierarchy and literally live inside it. You can easily do this with this gem

GoodData::UserHierarchies::UserHierarchy.from_sf(login, password) do |hierarchy|
    hierarchy.go_interactive
end

when you run this script you will be able to use REPL with all the stuff preloaded. You can then interactively play with the hierarchy. This uses awesome gem pry behind the scenes. You can do all the crazy stuff there (of course this can also be used in non interactive mode)

joe = find_user("1231safdas432")
bob = find_user("123123wqe2423")

joe.manager?
bob.manager?

bob.manager_of? joe
bob.subordinate_of? joe

# direct subordinates
bob.subordinates

# all subordinates
bob.all_subordinates.size

# if you want only emails (or other field)
bob.all_subordinates.map {|s| s.Email}

# you can use a shorthand for this
bob.all_subordinates(["Email"])

bob.has_manager?
bobs_manager = bob.managers

bobs_subordinate = bob.subordinates.first

# Take advantage of awsome ruby expresivness
# List all people that has more than 10 subordinates
hierarchy.users.find_all {|u| u.all_subordinates.count > 10}

• Salesforce

I use this mostly with salesforce so there are some things to make this even easier. First of all you can tap in directly to the SF in an interactive mode by using the combination of above mentioned techniques. Moreover the gem comes with a little command line tool that lets you jack in directly from your terminal session.

user_hiererachies jack_in_sf -l login -p password

Wait couple of seconds before the data downloads and boom you are in.

Speed

I do not know if the library is fast or not. For the biggest customer I have used this which has like 9000 users this was fast enough (under 1 second to generate what I needed. I bet there might be done some improvements. If you have some suggestions let me know.

• Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet

• Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it

• Fork the project

• Start a feature/bugfix branch

• Commit and push until you are happy with your contribution

• Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.

• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright © 2011 Tomas Svarovsky. See LICENSE.txt for further details.