F# isn’t really a black art, it’s just new, and it made for a catchy title. Revit journal scripting, on the other hand, is a black art. This was my very first exposure to them and this article barely qualifies as even touching the tip of the iceberg. In truth it’s not an area that I see a long term necessity for learning; considering that it’s undocumented, unsupported, and the .NET API is gaining momentum with every release. Until the .NET API is fully functional, however, this is a useful tool for the CAD manager and power user.
First a little background so you’ll understand what I’m doing and why I’m doing it. Each of our Revit models has multiple elevations in it. We use Revit’s design option feature to handle switching between them. Each elevation will have it’s own square footage chart, as the square footage will vary between every elevation. To handle this we must create a Revit area scheme, an area plan, and an area schedule for each elevation. At first we just created these on the fly as we added elevations to the model. However, we quickly identified this as a time consuming and error prone process that could be simplified by creating a template file with the area schemes and schedules pre-created, and then importing the schedules as needed. So I started gathering info on just how many schedules I needed to create in the template.
Our design team has standardized on 16 styles of elevations, with names like Arts & Crafts, Spanish Colonial, and the ever popular Traditional style. Each of those styles is assigned a two letter abbreviation. For the sake of brevity I’ll only use these three for the article.
|
Arts & Crafts |
AC |
|
Spanish Colonial |
SC |
|
Traditional |
TR |
They have also identified buyer profiles that a home is designed to target. For the sake of simplicity we’ll call them group1, group2, & group3. So a house designed for group1 could have a French Country, Spanish Colonial, and a Traditional elevation; or any number of the other 16 styles for that matter. Not only that, but it’s common for a house to have multiple elevations for any one style. To accommodate that scenario each group is assigned a range of elevation characters.
|
Group1 |
A – K |
|
Group2 |
L – T |
|
Group3 |
U – Z |
By combining the elevation abbreviation and an elevation character, we get elevation names for our plans. So Plan #1200 designed for group1 could have elevations ACA, ACB, SCA, & TRA. Plan #1300 designed for group3 may have elevations ACU, ACB, SCU, & TRU. Each elevation in the plan would have it’s own Square Footage chart. In order to build a template that has all possible elevations, how many schedules would I need to create? Let’s get out the calculator. There are 26 letters in the alphabet times 16 elevation styles. That’s 416 square footage tables. Revit doesn’t allow you to duplicate a schedule and then change the area scheme it applies to; and with our calculated fields, sorting and grouping entries, & formatting requirements, it takes a while to build a square footage table, which is what drove us to pre-create them in the first place. If I was able to create each table in 3 minutes, without a single interruption, it would have taken me about 20 hours to create them all. In reality, this project would have taken well over a week to complete and due to the monotonous nature of the task it’s more than likely that mistakes would be made. I didn’t have anyone on staff that I could pawn it off on and I didn’t have the time or the energy to do it myself. I made the decision to automate the process. Enter Revit journal files and F#.
Every time you open Revit it creates a journal file that records everything that you do in that session; look for the Journals folder under your Revit installation folder. Not only does it record what you do, it records it in a scripting language that Revit can read and execute. Drag a journal file onto your Revit icon and Revit will launch and execute the script, exactly mimicking the session that generated the script. Be *very* careful experimenting with these files. Running a journal script on a live Revit model could have disastrous effects unless you know what you’re doing. I’ll be the first to admit that I don’t. I will, however, share the assumptions that I made after opening and viewing a journal file. Below is an excerpt from one off my machine.
‘ 0:< Initial VM measure: 1945 MB available, 33 MB used
‘ 0:< 03-Jun-2009 11:34:34.179; started recording journal file
‘ Build: 20080602_1900
Dim Jrn
Set Jrn = CrsJournalScript
‘C 03-Jun-2009 11:34:34.195; 0:< ->InitInstance
‘ 0:< VM Delta: Available -257 MB -> 1688 MB, Used +92 MB -> 125 MB
‘ 0:< DBG_WARN: No Pantone interface: line 70 of .\DocView\ColorUtils.cpp.
‘C 03-Jun-2009 11:34:39.369; 0:< Protein : Register Preview Factories
‘C 03-Jun-2009 11:34:39.369; 0:< Protein : Create Fbx Manager
‘C 03-Jun-2009 11:34:39.369; 0:< Protein : Initialize the Renderer
‘C 03-Jun-2009 11:34:39.369; 0:< Protein : Before open Libraries
‘ 0:< VM Delta: Available -15 MB -> 1674 MB, Used +10 MB -> 135 MB
‘C 03-Jun-2009 11:34:40.010; 0:< Protein : Load fbxrenderermr Plugin
‘C 03-Jun-2009 11:34:40.026; 0:< Protein : After open Libraries
‘C 03-Jun-2009 11:34:40.026; 0:< Protein : 3rd Party plug-ins initialization
‘C 03-Jun-2009 11:34:40.057; 0:< Protein : EmitPluginsEvent
‘ 0:< VM Delta: Available -11 MB -> 1664 MB, Used +9 MB -> 145 MB
‘C 03-Jun-2009 11:34:41.573; 0:< Protein : Register Output Factory
‘ 0:< Revit Architecture 2009
‘ 0:< load point = C:\Program Files\Revit Architecture 2009\Program
‘ 0:< this journal = C:\Program Files\Revit Architecture 2009\Journals\journal.0001.txt
‘ 0:< Journal Init
‘H 03-Jun-2009 11:34:41.652; 0:<
Jrn.Directive "Version" _
, "2009.000", "1.811"
‘H 03-Jun-2009 11:34:41.652; 0:<
Jrn.Directive "Username" _
, "user 1"
My first assumption was that all lines starting with the ‘ character are comments. My second was that, considering my lack of understanding, I needed to be careful of what I changed in the file. Once those two assumptions where out of the way, I created my journal script. To do that I opened Revit and went through all the steps to create a single Square Footage table, including saving and closing the file. I then saved a copy of the journal file and started perusing it for what I needed to change to have it create all of my tables. I found the items I thought I would find, the name of the file to open and the name & description of the square footage table. These could easily be replaced with new names & descriptions. The only thing that gave me pause was adding the area scheme. Below is the section of the journal file that created the area scheme with the comments removed for clarity.
Jrn.Command "Menu" , "Area and Volume Calculation , ID_SETTING_AREACALCULATIONS"
Jrn.TabCtrl "Modal , Area and Volume Computations , 0" _
, "IDS_FIELD_USED_BY_CALC_VAL" _
, "Select" , "Computations"Jrn.TabCtrl "Modal , Area and Volume Computations , 0" _
, "IDS_FIELD_USED_BY_CALC_VAL" _
, "Select" , "Area Schemes"Jrn.PushButton "Page , Area Schemes , Dialog_Revit_AreaMeasure" _
, "New, Control_Revit_AreaMeasureNew"Jrn.Grid "Control; Page , Area Schemes , Dialog_Revit_AreaMeasure; Control_Revit_AreaMeasure" _
, "MoveCurrentCell" , "3" , "Name"Jrn.Grid "Control; Page , Area Schemes , Dialog_Revit_AreaMeasure; Control_Revit_AreaMeasure" _
, "PartialEdit" , "3" , "Name" , "Elevation ACA" , "13" , "13"Jrn.Grid "Control; Page , Area Schemes , Dialog_Revit_AreaMeasure; Control_Revit_AreaMeasure" _
, "MoveCurrentCell" , "3" , "Description"Jrn.Grid "Control; Page , Area Schemes , Dialog_Revit_AreaMeasure; Control_Revit_AreaMeasure" _
, "PartialEdit" , "3" , "Description" , "Arts & Crafts Group1" , "20" , "20"Jrn.Grid "Control; Page , Area Schemes , Dialog_Revit_AreaMeasure; Control_Revit_AreaMeasure" _
, "EditIfValid" , "3" , "Description" , "Arts & Crafts Group1"Jrn.PushButton "Modal , Area and Volume Computations , 0" _
, "OK, IDOK"Jrn.Data "Transaction Successful" _
, "Area and Volume Calculation"
You can follow through and see where it selects the Area and Volume Computations from the pull down menu and then navigates to the Area Schemes tab on the dialog box. Then it issues a Jrn.Grid command. The important parameters are “MoveCurrentCell”, “3”, “Name”. Looking at the dialog, you can surmise what it’s doing. It’s moving to the 3rd row and setting the “Name” column current. The next line issues a Jrn.Grid “PartialEdit” command to change the value to “Elevation ACA”. There are two additional parameters to this call, “13”, “13”, appear to be the length of the string being entered in the grid. The Jrn.Grid “MoveCurrentCell” and “PartialEdit” commands are then repeated for the Description field.
Armed with this information my plan was to write an F# application that would generate a list of all possible square footage tables, generate journal script files for each, and pass those scripts to Revit in a batch process, all while I sat back munching on some snackage watching the show. I’ll post the F# code in Part II.
Bobby C. Jones 