CSI Revit (Part I): How to read the crime scene.

Do you know what a journal file is? If you have dealt with Autodesk support on an extended issue you may have been asked to submit journal files, but you may still not quite know what they are.

Quite simply journal files record all your actions during a Revit session, Revit creates a new journal file whenever you start it, and stops writing when you close it. Under the general tab of the options dialog [Settings menu >> Options] are two choices for how many and for how long you keep journal files. Revit always writes its journal files to the same location; Windows XP c:\Program Files\Revit version\Journals. I would assume that Vista installs maintain a similar structure/relationship. Journals are simple text files (in fact their extension is .txt) and can easily be opened with a program like "Notepad" (my preferred editor for such things). They are always named in the same format "journal.xxxx.txt", where the x's are four digit sequence.

Journal files are pretty interesting things, and can prove handy, particularly when troubleshooting. The reason Autodesk or Revit support likes to get their hands on journal files is because it gives them a window into what the user is/was doing, how the file is behaving, and how the computer is performing. Journal files not only record the user's interactions with the Revit file, but they also record vital computer statistics like how much memory is available, the video card installed, etc; all of which is useful when troubleshooting a problem.

The particularly nice thing about journal files is they can also be "read" by a human. While there is some esoteric code that shows up, it is actually generally possible to read a journal file and understand the actions a user is/was taking. Of course we're not talking about reading a good novel, but as you become more familiar with them, you start to understand the pattern of the language, and thus how to read it. Most commands are listed with simple descriptors like this:

Jrn.Command "DesignBar" ,
"Create a wall , ID_OBJECTS_WALL" Jrn.Directive "JournalDataChainOption" , "Walls", 1
Jrn.MouseMove 0 , 503 , 368
Jrn.LButtonDown 1 , 503 , 368
Jrn.MouseMove 1 , 504 , 367
Jrn.LButtonUp 0 , 504 , 367
Jrn.MouseMove 0 , 936 , 371
Jrn.LButtonDown 1 , 936 , 371
Jrn.Data "Transaction Successful" , "Wall"

To the uninitiated, this looks like a lot of gobbly gook (perhaps à la The Matrix), but if we break it down, we can understand what is happening in Revit. First, the command initiated is the wall tool on the design bar: Jrn.Command "DesignBar" , "Create a wall , ID_OBJECTS_WALL"

Next are any options related to the wall command in this case the chain option is checked. Then, there is a mouse move, presumably to locate the cursor where we want to start drawing the wall, after that there is a Left Mouse button click at the same location to initiate the process of creating a wall, apparently the user's hand was slightly unsteady as there is a mouse move registered before the button is released up again. After that, there is another mouse move to the end point of the wall, then another click to complete the wall. We know that the creation of the wall, and therefore the end of this particular command was completed successfully as there is a "Transaction Successful" line with the key "Wall" to indicate the wall command finished.

Almost all other commands in a journal file follow a similar pattern, I usually try to start by looking for the transaction successful line and working backwards, but you don't have to, particularly if you learn to read the journal files.

Now you might find you journal files tend to look like this:

This is quite messy, but all the lines that start with an apostrophe ( ' ) are comments, also automatically recorded, however they have nothing to do with actual Revit commands, they may just serve to provide additional information, like memory statistics, or the date time code of when a command took place. It is actually possible to scrub a journal file of much of this additional information, but, while I know it can be done, I don't know the details of how it is done.

So you say, what am I to do? Well, you can use the find command (available in even lowly Notepad) to search for specific things. Since journal files are recorded in plain English so to speak generally searching for a keyword related to the command you are looking for is a good start. So a search for "window" will start to turn up any instances of interactions with the window command, or window objects.

If you want to learn more about journals, you might want to start by starting Revit, creating a blank file, then performing some simple actions, like creating a few walls, placing a door or two, make a section, etc. When you finish, close Revit, then go find the most recently created journal file. See if you can trace your actions through the file. You should be able to identify code for every specific command you take. I will warn you that when you switch views, or modify them, you get a ton of additional code that has to do with what the window is doing, you can generally ignore most of that, and keep tracing your commands.

In my next post we'll actually take a look at doing some useful detective work with the journal file, and a real life casefile that I have to share. We'll follow that up with something that I think a great number of people will find extremely useful, so stayed tuned, the season finale is around the corner...