Open-source, Ruby, Software, Thoughts

SWAN Manager 3.0

Ruby on Rails logoIts back to programming lately at my job. I have taken it upon myself to reinvent SWAN Manager (yet again). This is its third iteration, and has come a LONG ways since 1.0. I love the satisfaction in figuring something out, and then implementing the logic in code. It is creating something from nothing. Today I finished working on the audience builder for our Portal. The layout on the Portal side is terrible, spanning across an LDAP branch, and five different database tables. The logic cannot be inferred from the tables, and of course no source code or documentation is ever is provided on our Portal platform. The beauty is, now that is is done (100% mapped to our functions), I can determine whether any user can access any part of a channel, or announcement in Ruby.

In a (sparse) 150 lines of code, I have done what I would imagine has taken thousands of lines of fragmented thoughts stemming from many programmers in all written in Java code. There is a simplicity, and a poetry that I enjoy when writing in Ruby. Maybe someday, folks will see the light.

For this version of our management website, I had the idea while driving home from work, of making the interface for the Portal totally web service driven, and using sparse templates, and making the whole damn thing run in a few “administrative” channels inside the Portal. It seems like a perfect fit. To start with, how can I expect other departments, and other applications to integrate with the Portal if I am the administrator, and I don’t even do it? Besides, it is a management application for the Portal, so what better place? Also, I can verify that the web services are operating as expected, by having a living proof-of-concept.

Also, new in this version, I have reimplemented the way Targeted Announcements are sent. Before we had a Java class (that I threw a fit about until a certain company gave me the source code), that we modified to accept switches when called for the parameters. This class (and its 10MB of dependencies were “jarred up” (fuck you to Java), and placed in our management website. When someone filled out the nice announcement form, I would take all the parameters, and build the switches on the fly, scp the jar files over to the server, and run a Java command from the bash shell. Needless to say, this sucked. Ruby and Java should never mingle. If I wanted to change the way the class was implemented, it was back to Java, and mucking around with an API I didn’t understand (once again because the company is TERRIBLE at documentation).

I finally got smart, and decided to use Wireshark (thanks James!) and “listen” to the mysterious SOAP traffic occurring from my machine to the server and back. After a few minutes of isolating the traffic, the mystery was revealed as little more than a few dozen lines of XML. A lightbulb went off in my head, and I decided to use Ruby’s REXML library to construct this procedurally based on the form (from earlier) the user fills out and submits. The end result is a cleaner interface, no Java, no scp, or Bash environment, and best of all 9.99MB less space. Hold your applause.

I also decided to really take a good, hard look at all of my models and associations and made the startling discovery that the first significant portion of your project should be ironing out these associations. If you skimp here, your entire application will suffer. Badly. That is because you are laying the foundation here, and if you do it wrong, or half-assed you have really missed the power of Rails.

After a few wonderful hours at home, self-medicated on NyQuil, I managed to get a “user” to be created with just a username. For instance, “User.create(:username => ‘bsimpson’)”. This in turn, spawned off a frenzy of associated activities, including building roles the user belongs to, checking community groups the user is a member of, and building a list announcements the user has authored. It is nice to build an application, thinking about the associations between models first and foremost. The semantics pay off quick, with actions such as “user.groups”, “user.announcement_authorships”, “user.channels”, etc.

Hopefully in a few more weeks, we will have the version 3.0 in production, and in use by a few of our channels.

Computers, Ruby, Software, Web

Rails and SOAP – A Dirth of Information

Scrubbing Bubble

I am writing this post to both vocalise the success of my first encounter with SOAP in Rails, as well as explain the process. For anyone working on a Rails application with SOAP for the first time, its probably become apparent that there is little documentation for the first time users out there.  Read on to learn more about Rails, SOAP, and hopefully gather enough to get your application up and running.

Introduction to SOAP

I will assume that if you are still with me, then you have some experience with Rails. I mean, we do have to start somewhere. I always viewed SOAP as one of the legacies that Java has left on this world. And by legacy, I mean like how Herpes never really goes away. SOAP used to stand for Simple Object Access Protocol, which in English means absolutely nothing more than being a clever acronym. SOAP in layman’s terms is a way that two bases of code can communicate with each other regardless of the Operating System, language, or anything else proprietary. SOAP also allows outside users to make changes to your application while enforcing a level of security.

In SOAP implementations, there are two parts – the client and the server. The client connects to the server to either query for information, or to request changes to that information. The methods that are available for a client to use are entirely up to the server’s definition. This definition is a very real file named the WSDL. Yeah thats right – another clever acronymn. The WSDL file is the Web Services Description Language. This is where methods, their documentation, and what parameters they take in, and spit out are recorded. This file is a plain-Jane XML file, so you can view it on your own if you so desire.

A little trick that I have seen several SOAP server implementations pull is securing this WSDL file from the outside world. Typically this is via Basic Authentication, which we will need to handle with Ruby when connecting. Regardless of the security implementation, we will need to have access to this WSDL file for our Rails application to consume. More on this in a minute.

Speaking of consumption, if you glanced at the WSDL file, you probably had a hard time swallowing it. Those of you familiar with Java will quickly recognize this as a signature feature of the language in general. Simply, the WSDL file was never really intended to be made sense of by mere humans. Most languages have a SOAP parser that will read this XML, and construct classes and methods in its native code to make life a bit easier. For example, Microsoft Visual Studio allows a user to “Add a web service” which will read the file, and generate C# or VB.NET code. Aren’t they smart cookies?

Rails and SOAP Together

Rails is no stranger to the SOAP game, and offers its own way to use web services. To start with, you will need to acquire a few files. Specifically, you will need to obtain the wsdl2ruby script which is part of soap4r.  This can be obtained from their website, but downloading stuff directly is a bit old school now-a-days. Instead, we will use the gem package manager to fetch this file and its dependencies. From a terminal, issue:

gem install soap4r

This will fetch the gem, and its dependencies. Now, you should have a utility named “wsdl2ruby” accessible from your terminal. An important note: soap4r comes bundled with Ruby, but it is a much older version. To you will need to be explicit in which version you want to use. This means in IRB, or in your Rails model, you need to place ‘gem soap4r‘ at the top of your files. This loads the new soap4r gem instead of using the bundled soap4r code.

There are two main ways in which to use wsdl2ruby in your Rails application. The first is calling in the library to parse SOAP files (via “require”), and generating your methods on-the-fly. This is a really good approach for keeping your code as terse as possible, however it makes development a little slower, since the methods you can call are not readily apparent. The second method calls wsdl2ruby manually from a terminal, and generates a driver file, and example code for how to use it in your application. I recommend doing both, the former for your actual application, and the latter for reference during development. After you are finished developing, you can simply delete the generated files without any side-effects.

Generating Client Files for Web Service

The usage syntax for wsdl2ruby is a little ugly, but here is the simplified version of what it can do:

Usage: /ruby/bin/wsdl2ruby.rb --wsdl wsdl_location [options]
  wsdl_location: filename or URL

  For client side:
    /ruby/bin/wsdl2ruby.rb --wsdl myapp.wsdl --type client

  --wsdl wsdl_location
  --type server|client

You can see from the usage above, that we can run wsdl2ruby against a WSDL file location, and have it generate the classes and methods needed for our rails application. An example might be (substituting your own WSDL file of course):

wsdl2ruby --wsdl --type client --force

The “–wsdl” argument indicates that we want to generate files based on a WSDL definition. The “–type client” argument indicates that we want to generate a “driver” file, as well as see a sample client library to show how one might use the driver. The “–force” argument makes the parsing of WSDL a little more robust when building the Ruby code. When you run this, it will create 4 files in your current working directory. Of these, the file we are most concerned with is the “xxxClient.rb” file. This is your sample code to use as a reference.

Take a gander at this file, and you will see something similar to the following:

#!/usr/bin/env ruby
require 'defaultDriver.rb'

endpoint_url = ARGV.shift
obj =

# run ruby with -d to see SOAP wiredumps.
obj.wiredump_dev = STDERR if $DEBUG

#   getUnread(parameters)
#   parameters      GetUnread - {}getUnread
#   parameters      GetUnreadResponse - {}getUnreadResponse
parameters = nil
puts obj.getUnread(parameters)

The name of my Web Service is getMBXUnread. Each method available for use is shown by the synopsis section. For example, my first method shown here is the “getUnread” method. I can see that it takes a parameter (which parameter is mysteriously omitted, but we can find it easy enough), and returns a value in the property “getUnreadResult” when called. To find out the name of the parameter it is expecting, look at the default.rb file. In my example, I see the following class (named the same as my method in the Synopsis above:

require 'xsd/qname'

# {}getUnread
#   strUsername - SOAP::SOAPString
class GetUnread
  attr_accessor :strUsername

  def initialize(strUsername = nil)
    @strUsername = strUsername

I can now see that this method takes a value for “attr_accessor :strUsername” upon creation. This means that I can say “…getUnread(:strUsername => ‘username’)” in my Rails application. This is what we need to get started programming.

SOAP in your Rails Application

Open up one of your Rails models and get ready to roll up your sleeves. At the top, we will need to require a file to be loaded to make the SOAP functions accessible from the model class. Place the following at the very top of the model:

require 'soap/wsdlDriver'

Now, you can create a new method, and reference your WSDL resource we were playing with earlier. I will need to initialize my SOAP client like so:

soap_client ="").create_rpc_driver

The URL that I have as a parameter will need to reflect your WSDL location. The “create_rpc_driver” method will instruct Ruby to read this resource, and construct the classes we already saw earlier. The only difference is now it is doing it on-the-fly instead of creating files in the working directory. Now that our client is ready, we can query our SOAP server for information:

soap_client.getUnread(:strUsername => username).getUnreadResult

I called the “getUnread” method on my client and passed in the parameter it was expecting from earlier. This is still available to reference in your “xxxClient.rb” file if you want to refer back to it. Next, I pass in a username variable as the parameter in a hash format. At this point, I now have a SOAP object, and barring any errors connecting, I should be able to retrieve the “getUnreadResult” property of this request.

Basic Authentication

Earlier, I mentioned that some SOAP server implementation may make use of Basic Authentication (prompting for a username / password) before allowing access to the WSDL file. This is handled by soap4r (and thus wsdl2ruby) by using a property file on startup. You will need to create this property file inside a folder named “soap” somewhere on you application’s load path. For IRB, this load path is configured using the “-I” switch, and specifying a directory following. For example, if I am working out of “C:”, then I could create the file “C:soapproperty”, and load this file in IRB by issuing “irb -I ‘C:“. In Rails, you can place this soap/properties in a number of locations, but I would recommend sticking it inside the vendor folder.

Inside this property file, we can associate URLs with credentials. Here is an example property file listing:

client.protocol.http.basic_auth.1.url = http://example/path/to/wsdl
client.protocol.http.basic_auth.1.userid = username
client.protocol.http.basic_auth.1.password = PaSsWoRd

Note that this file does not have an “.rb” extension – that is because this is a property file and is not valid Ruby syntax! You can also create multiple basic authorization definitions by incrementing the group number. The first group shown above is “1”.

If you are working with SSL, then check out this article. You can use the same property file above, with some added settings.


SOAP isn’t easy. In fact, I read in the Enterprise Integration with Ruby book that SOAP now doesn’t stand for Simple Object Access Protocol because it is no longer simple. SOAP just means SOAP.  As the complexity of your WSDL file increases so do the odds of wsdl2ruby choking on it. A lot of this has to do with mapping classes to Ruby equivalent objects. wsdl2ruby has made remarkable ground, but it still isn’t perfect.

If you get stuck, try generating the client files, or viewing the “methods” of your soap_client inside of a Rails console, or IRB. The help out there isn’t great, but try checking out “”, for the soap4r API upon which wsdl2ruby is based.

The book Enterprise Integration with Ruby has about five pages talking about wsdl2ruby in particular, and an entire chapter talking about RPC calls with Ruby, including how to create your own SOAP server.

Good luck!