Revit add-in multi-project re-implementation of the FireRating SDK sample using the firerating cloud-based MongoDB node.js web server
C#
Latest commit 0b659bc Jun 26, 2016 @jeremytammik added forge

README.md

FireRatingCloud

FireRatingCloud is a C# .NET Revit add-in.

It is a multi-project re-implementation of the FireRating SDK sample.

It uses a REST API to access a cloud-based database managed by the fireratingdb node.js MongoDB web server.

This repo also includes two other projects:

  • FireRatingClient, a stand-alone Windows forms executable implementing a read-write fireratingdb client that you can use to remotely edit the BIM without entering or even installing Revit.
  • FireRating, a shared library used by both FireRatingClient and FireRatingCloud.

Connecting desktop and cloud

FireRatingCloud is a member of the suite of samples connecting the desktop and the cloud.

Each of the samples consists of a C# .NET Revit API desktop add-in and a web server:

  • RoomEditorApp and the roomeditdb CouchDB database and web server demonstrating real-time round-trip graphical editing of furniture family instance location and rotation plus textual editing of element properties in a simplified 2D representation of the 3D BIM.
  • FireRatingCloud and the fireratingdb node.js MongoDB web server demonstrating real-time round-trip editing of Revit element shared parameter values.
  • Roomedit3dApp and the roomedit3d Forge Viewer extension demonstrating translation of furniture family instances in the viewer and updating the Revit BIM in real time via a socket.io broadcast.

Context and Architecture

Here is an image showing the links and relationships between BIM, cloud, Revit, node.js and MongoDB and explaining how and where fireratingdb and the three FireRatingCloud components fit into the picture:

fireratingcloud_architecture

I created this drawing using draw.io, and the source XML file is provided.

All REST API calls on the desktop are handled by the shared .NET class library FireRating.dll and passed to the firerating database in MongoDB via the node.js web server. It contains one single collection doors containing door data JSON documents. Other clients can connect to that server as well, from any kind of device. Both the node web server and the mongodb database can actually be run either in the cloud or locally on your own system, even on the Windows system running Revit. These two choices are controlled by Boolean flags in the FireRating library and web server, respectively.

Only a few technical users will interact with full-fledged Revit and the BIM. A much larger number of all kinds of users can be provided access to relevant subsets of the BIM data using this technology. This and others samples demonstrate how that access can include real-time editing and BIM updating, if you so please. The FireRatingCloud sample is intentionally kept simple and limited to managing and providing access to one single shared parameter value. The RoomEditorApp shows how you can extract and interact with graphical data as well, including graphical interaction on any mobile device with a simplified 2D view rendered using SVG in the browser.

More Information and Full Description of all Development Steps

For more information, please refer to The 3D Web Coder, The Building Coder and the detailed articles describing the entire project implementation and evolution, including first learning steps using mongo, implementing a REST API for it, and using that from a C# .NET desktop app:

Installation

To install:

  • Fork the repository.
  • Clone to your local system.
  • Load the solution file in Visual Studio.
  • Compile the add-in, producing the .NET assembly DLL FireRatingCloud.dll.
  • Install by copying the add-in manifest file and the .NET DLL assembly to on of the standard Revit add-in locations, for example C:\Users\tammikj\AppData\Roaming\Autodesk\Revit\Addins\2017.

If you do not know what this means, please refer to the GitHub and Revit programming getting started guides.

As explained above, FireRatingCloud interacts with the fireratingdb node.js web server and MongoDB database.

You can run both the web server and the database either locally, on your own system, or on the web, for instance using Heroku to host the web server and mongolab for the database.

For the web server, this choice is made by the C# Revit add-in and its the Boolean variable Util.UseLocalServer, which toggles the base URL being used between these two constants:

const string _base_url_local = "http://127.0.0.1:3001";
const string _base_url_global = "http://fireratingdb.herokuapp.com";

The web server in turn decides where to look for the database, again by setting the appropriate URL like this in server.js:

var localMongo = false;

if(localMongo) {
  // local database
  var mongo_uri = 'mongodb://localhost/firerating';
} else {
  // mongolab hosted
  var mongo_uri = 'mongodb://revit:revit@ds047742.mongolab.com:47742/firerating';
}

If you host both the web server and the database on the web, i.e., both UseLocalServer and localMongo are set to false, you have no more to set up.

If you are running some components locally, you need to install and run MongoDB and/or Node and the fireratingdb app itself on your system.

Good luck and have fun!

Quick Test

Just to check whether the node.js mongodb web server is up and running and see its version number, navigate to fireratingdb.herokuapp.com.

The online database is hosted on mLab. Look at the doors collection in the firerating database.

You can filter for your specific test data by setting the Revit Mark under Identity data in the BIM properties, and search for it in the database under the tag property, e.g. {"tag": "jeremy"}.

Commands

FireRatingCloud implements five commands:

firerating_2017_ribbon_tab

  • Create and bind shared parameter – Cmd_1_CreateAndBindSharedParameter
  • Export shared parameter values one by one – Cmd_2a_ExportSharedParameterValues
  • Export shared parameter values in batch – Cmd_2b_ExportSharedParameterValuesBatch
  • Import shared parameter values – Cmd_3_ImportSharedParameterValues
  • Subscribe to real-time BIM update – Cmd_4_Subscribe

Create and Bind Shared Parameter

This standard procedure is unchanged from the original FireRating Revit SDK sample.

Export Shared Parameter Values One by One

Gather the door data element by element and export each data record to a MongoDB JSON document.

If a corresonding document already exists in the dtabase, it is updated.

If not, a new document is created.

This requires a separate REST call for each door element.

Export Shared Parameter Values in Batch

Export all door data records for the entire project to MongoDB JSON documents in one single batch call.

No possibility to update existing documents was found, so all existing documents related to this project are first deleted.

In other words, this export operation requires two REST calls: one to delete existing records, and one to export the data.

As soon as more than two doors are present in the project, the batch export will be faster than the individual export.

Import Shared Parameter Values

All door fire rating values for the entire project are read from the database in one single REST call and used to update the existing element data.

Subscribe to real-time BIM update

This command implements a Revit ribbon toggle button that switches back and forth between Subscribe and Unsubscribe.

When subscribing, a continuous database polling loop is started that checks the database for updated door data documents pertaining to the current Revit project every 500 milliseconds or so.

When updated documents are detected, an external event is raised. The event handler provides a valid Revit API context in which the updates can be applied to the BIM.

The detailed implemenation is discussed in the post on real-time BIM update with FireRatingCloud 2017.

Todo

  • Subscribe to a push notification event from fireratingdb to trigger the external event whenever changes are made, instead of continuous polling like the room editor. Does this exist at all? Is it possible? This subscription is obviously project specific; only documents realted to the current project are of interest.
  • On document change, update the fireratingdb push notification subscriptionn to the new current document.
  • The stand-alone FireRatingClient displays data from all projects and therefore needs a different global subscription, not tied to a specific project.

Done

  • Implement batch upload. Previously, data upload was only processed element by element, whereas download is implemented using one single much more effective batch call.
  • Implement an external event for real-time BIM update subscription like the room editor.

Authors

License

This sample is licensed under the terms of the MIT License. Please see the LICENSE file for full details.