End User Assistant

The purpose of this tool is to run at the background of a Revit work session, monitor user’s operations, gather and save data for other tools to use. As of right now, it works with other 2 plugins from DZ studio: Revision Cloud Manager and User Editing History.

See THIS POST about how User Editing History (UEH) works. In this post UEH is also mentioned and explained as needed.

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

 

Revision Cloud Monitor

This monitor makes sure the user is aware that he needs to use the “Comments” property of revision cloud to describe what this cloud is about, so Revision Cloud Manager can use the info to generate a narrative.

Work Session Monitor

This monitor records non-transactional operations during a user work session. Right now it will record the following operations: open/create model, sync, reload latest, turn on/off monitors.

Editing History Monitor

This monitor records transactional operations that changes the model. Right now this monitor does the heavy work, and the rest of this post talks about how this monitor works.

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.

EDITING HISTORY RECORDS

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.

Turn Off Monitors

In a work-shared model, EUA monitors are turned on and cannot be turned off by default. Use UEH to setup control mechanism for the model, and choose if users are allowed to turn off monitors by themselves.

 

FUTURE RELEASES

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.