Revit Plugin:User Editing History

This tool shows and manages all users’ editing history and other records that were created by End User Assistant. It also provide control over End User Assistant setting on local user’s machine.

See THIS POST to learn more about End User Assistant and what happens on local user’s machine. In this post, some work flow of End User Assistant is also mentioned as necessary.

To explain how this tool works, let’s break it down to some key concepts and functions:

Transaction

A “transaction” is a change applied to the model, such as creating a wall, or renaming a family type. Each transaction has a name assigned to it, and that is the same name we can see in the undo list.

One transaction often affects multiple elements, some might get created, others might get modified or deleted. EUA will record them as lists of unique ids. Sometimes the number of affected elements are so many that it is hard to make sense of all those records. Therefore EUA will also try to get user’s selection right before and after each transaction, so we can tell which element(s) the user was operating on. So, a total of five lists of relevant elements are linked with one transaction: added, modified, deleted, selection before, selection after.

User Work Session

A “user work session” contains all the records of a user between two save/sync. During one user work session, End User Assistant (EUA) gathers information right after each transaction. Right before a save/sync, EUA processes these transaction information, gather some more information from the model, reorganize them, and saved into the model. Then, User Editing History (UEH) simply reads these records from the model, and provide ways to search/filter/manage these records.

History Records per Element

UEH shows a list of records, and each record item shows what happened for one Revit element during one user work session, providing information about the element, the user, time, and a list of transactions that affected this element.

An element could have been created/modified/deleted during one user work session. If an element was created/deleted during one transaction, it will be shown as created/deleted, even if there are other transactions during which this element was modified.

There won’t be record for elements that are created and deleted during the same user work session.

“Id” vs. “Unique Id”

If you are a BIM Manager, you are probably familiar with element’s id. It is an integer number for identifying individual element. What you might not know is that element id is subject to change for the same element in a work-sharing environment. (learn more for why this happens) Therefore, Revit has another set of element identifiers called “unique id”, and they will never change. For UEH, you can see both Id and Unique Id been used, but keep in mind that different Ids could be pointing to the same element, and one Id could be used by multiple elements during different user sessions, but one Unique Id only marries with one element. That makes Unique Id the true identifier for Revit elements.

Selected Elements Before/After Transaction

EUA will request Revit for user’s selected element after each mouse click, because that’s the most common way elements are selected in Revit by end users. There are other ways to select elements, such as by element id, or through API, and EUA does not monitor selection change by these routes. After each transaction, EUA makes another request for user selection.

Here is what happens when a user deletes an element: user selects that element, EUA gets selection of one element, user hit delete key, Revit start and finish “delete selection” transaction, EUA gets selection after transaction (which should be empty).

One known issue here is that if Revit did not idle at all between the selecting by mouse and deleting by keyboard, because the user did these two in a very fast manor, EUA might not be able to get the correct selection before the deletion, simply because Revit didn’t have time to take any request from EUA. In this case, selection before might be wrong elements or empty, and selection after will be empty because the selection was deleted. This issue is only with deleting. Creation and modification will always show the correct user selection after the transaction.

Deleted Elements & Model Snapshot

EUA might show a progress window saying “Get model snapshot” right after sync and reload latest, and it might take 15-20 seconds to complete for large models. This is a necessary technical solution for recording deleted elements. Revit API only reports the id numbers of affected element during a transaction. By the time EUA tries to get more info of those elements, the ones deleted were already gone. That’s why old versions of UEH does not show any info of a deleted element other than its id number. What model snapshot does is scan and record basic information of all eligible elements in the model, so that when an element is deleted, EUA can look up its id here and get its other info.

As mentioned in “Id vs. Unique Id”, id numbers are subject to change, and this change could happen after sync/reload latest, when the local model merges data from the central. That’s why EUA needs to take model snapshot at these two events, so that id numbers are correctly mapped to unique ids.

When EUA takes model snapshot, it only looks for elements of certain categories, so we can concentrate on only those elements that we care about. It also helps shorten the time needed for taking a model snapshot. You can find this list here. Please feel free to let me know if you think there needs to be more or less categories.

Save & Load File

For each user work session, EUA creates one special Revit element called Data Storage, and save it into the model. This type of element is for storing data only and is only accessible through Revit API. Although the number of user work sessions shouldn’t be big enough to have impact on Revit performance, these data storage elements do have impact on the file size of the model. It is a good idea to save these data to an external file, and delete all record inside the model once in a while, so the file size does not swell. UEH provides ways to load, save and merge these files into or out-of the model.

User Control Center

in this module, UEH can control the end user’s ability to turn off EUA monitors by themselves. This control is per model, not per user or machine. Change to this setting needs a sync to central to take effect.

It also shows important user operations that are non-transactional, such opening the model, save, sync, reload latest, and turning on/off EUA monitors. The on/off status of EUA monitors are recorded with each user operation.

Future Release

As always, suggestions for future releases are most welcomed. Feel free to contact me if you want specific function in the plugin, or if your firm has special demands that could be best met by a more customized tool.

ACKNOWLEDGEMENT

Special thanks to Ryan Borszich, for his ideas and suggestions on the development of this plugin.