Wrangling Revisions with Ruby

Here is a write-up by Andy Holmes, Integration Specialist at OPX design consultancy on a Ruby project that uses a lot of different Revit API features, e.g., revisions on sheet, DMU updaters, Idling and document events, and creating a Ruby 'add-in' by using an application-level macro that has no macros in it.

This write-up will soon be made available on the redesigned OPX website, and the code is already freely available on GitHub.

Andy adds that Mat is colleague who works with Revit and came up with the idea. Andy said it was doable (and did it). He also notes that got frustrated with the API a number of times and that might be noticeable in the tone. :-)

So here goes:

Revit API: Wrangling Revisions with Ruby

OPXer Mat Hart came up with an idea for managing Revit project sheets: he wanted to have a master schedule log that would keep track of all of the revisions for every sheet, like this:

Annotated sheet log

The problem is that, as of Revit 2014, you can’t make Revisions be columns in a schedule – it’s just not something that Revit can do. In the picture above, the Revisions columns aren’t really Revisions, they are actually Fields added to a sheet list Schedule from Parameters that were given the exact same names as Revisions.

What Mat wanted was for the sheet list Schedule (henceforth being referred to as the 'Sheet Log') to automatically stay in sync with the columns that are named after Revisions:

  1. If you added a new Revision to the project, the Sheet Log would automatically get a new column added with the name of the Revision.
  2. Checking or unchecking a Revision column for a sheet would automatically update that sheet’s Revisions on Sheet parameter AND Title Block Revision schedule, as shown here:
  3. Annotated sheet
  4. Adding/deleting Revision Cloud to a sheet or checking/unchecking values in a sheet’s Revisions on Sheet parameter would automatically update the Sheet Log.

So, in other words, the goal for this effort was to allow the Sheet Log to be a single master list of all sheets showing which sheets are part of each Revision. Automating all of this would avoid the human errors that come from having to manually keep track of the relationships between sheet revisions and a master sheet log.

Revit 2014 API: A Must-Have for Revisions and Ruby

It turns out that this project would not have been possible prior to Revit 2014, since only in 2014 did Autodesk add to the Revit API the ability to access and manipulate Revisions on Sheet. Fortunately, they did add Revisions on Sheet to the 2014 API, so we were in luck.

Also, the 2014 API (via the SharpDevelop API development tool provided with Revit) added the ability to develop Revit macros in Ruby (rather than C# or Python), so Ruby was used to develop the functionality. (IronRuby, the Microsoft .NET specific Ruby version needed for Revit API development, is actually no longer under development by Microsoft, but it works for Revit development).


The resulting project, opxRevisionAndSheetLogUpdater, is a set of Ruby files that can be used by copying them into the Revit 2014 macros directory. That very long directory is something like:


This is where new macros are created when using the Macro Manager.

The Ruby code for this project is available from the opxRevisionAndSheetLogUpdater GitHub repository. You can download the code and explore it. You can also email questions about the project to aholmes@opxglobal.com.


Some key hurdles that were cleared in creating this project:

Invaluable Assistance

These sources were hugely useful in developing this code:

Installation Addendum

A quick Revit Ruby addendum on Installing Revit 2014 API add-ins.

I’m adding this since I just spent a while on this potential hiccup for Revit Ruby users. See the linked document for details (step 5 of the RevitRubyShell install steps). The short version is that installing a recent version of standalone IronPython breaks IronRuby, so Revit Ruby macros and the RevitRubyShell won’t work.

I’m probably the only person who installed IronPython and then started using the Revit Ruby API, but it was so painful to figure out I decided to share it anyway, just in case ... :-)

Also, thanks for RevitLookup! I use it constantly.