Skip to the content

Help

Check a model from a watched folder

The BIMgravity local program watches a folder on your computer. When a trade’s new model lands there, the program checks it and records the run, with nobody at the screen.

Who can do this
Owners and managers create the API key. Anyone can then run the program on the computer that holds the folder.

Before you start

You need Node.js 20 or newer on that computer, the BIMgravity program files, and a folder that already receives the models (a synced project folder works).

  1. In BIMgravity, open Settings, the Integrations tab, then API keys, and create a key. Name it after the computer that will run the program. Copy the key now: it is shown once.
  2. On that computer, store the key in the environment variable BIMGRAVITY_API_KEY. Do not write it in a file inside the watched folder, and do not type it on the command line: it would stay in the command history.
  3. Open a terminal and start the program on the folder. Give the project and the trade the folder belongs to: bimgravity watch "C:\Projects\Riverside\Mechanical" --project "Riverside Medical Office Building" --trade "Mechanical"
  4. Leave the program running. Copy a model (.ifc) into the folder, or let your sync tool bring one.
  5. Read the line the program prints for the file. recorded means the run is stored, with the score of each check.
  6. In BIMgravity, open the Library. The run is listed with the others.

What you should see

One line when the program starts: “watching” with the folder, the project, the trade and the rule pack. One line when a file is noticed: “new file; waiting until it stops changing”. Then one line with the result: recorded RMOB_M_Mechanical_v4.ifc data 85.9 % · code data 93.9 % · handover 79.5 % · run 6f1c…

How a folder maps to a project and a trade

Two ways. The options on the command line win.

  • Options: --project and --trade, as in step 3.
  • A small file named bimgravity.json in the folder: { "project": "Riverside Medical Office Building", "trade": "Mechanical", "profile": { "occupancy": "B", "sprinklered": true, "codeEdition": "IBC2021", "phase": "construction", "authoringTool": "revit", "units": "imperial" } } With --recursive, each sub-folder can hold its own file. A model uses the nearest file above it. One project folder can then hold one sub-folder per trade.

The project and the trade are stored with the run as plain names. Give the project’s id instead of its name (shown on the project page in the expert view) and each check also runs the project’s approved requirements and compares the model with its documents, as a check in the browser does. The log line then adds the counts: matches, differs, not comparable.

What the program does with each file

  • It waits until the file has stopped changing. Sync tools write a file in pieces. Use --settle 15 if your sync tool is slow.
  • It checks one file at a time.
  • It checks a model once. A copy with another name is not checked again. A new version of the same name is.
  • It skips hidden and temporary files, and files that are not .ifc.
  • It never follows a link out of the folder, and never reads a file over 300 MB.

When something is wrong

Messages of the local program, what they mean and what to do
The line saysWhat it meansWhat to do
refused … is incompleteThe file stops before its end. It is probably still copying.Nothing. The complete file is checked when it arrives.
refused … holds no element to checkThe file has a project and levels but no element.Export the model again.
refused … is not an IFC modelThe file has the .ifc ending but is something else.Remove it.
refused … a text value longer than 4000 charactersOne property holds a very long text. It is not sent.Shorten the value in the authoring tool.
locked … in use by another programAnother program holds the file.Nothing. The program tries again.
failed … will try once more, then set-asideThe file could not be read twice.Export the model again. The file is tried again only if it changes.
waiting … trying again in 30 sThe server cannot be reached, is busy, or your firm has no checks left for now.Nothing. The pause grows up to 10 minutes and the file is not lost.
stopped … The API key was refusedThe key is wrong or was revoked.Create a new key and start the program again.

Nothing is recorded for a file that is refused, could not be read or is set aside.

Start the program when you sign in to Windows

No installation is needed: Task Scheduler is part of Windows.

  1. Open Task Scheduler and select Create Task.
  2. On General, name it “BIMgravity watched folder”. Choose Run only when user is logged on.
  3. On Triggers, add At log on for your user.
  4. On Actions, add Start a program. Program: the path of node.exe. Arguments: the path of bimgravity.mjs, then watch "C:\Projects\Riverside" --recursive.
  5. Set the key once for your user, in a terminal: setx BIMGRAVITY_API_KEY "your key". Also set BIMGRAVITY_URL to the address of BIMgravity. Sign out and in again.

To check on a schedule instead of all the time, use the trigger Daily, repeated every 15 minutes, and add --once to the arguments. The program then checks what is new and exits.

On macOS or Linux

Add one line to your user’s schedule with crontab -e. The key and the address are set in the lines above it: */15 * * * * /usr/local/bin/node /opt/bimgravity/bimgravity.mjs watch "/Users/me/Projects/Riverside" --recursive --once >> "$HOME/bimgravity-watch.log" 2>&1

What leaves your computer

Your model file never leaves your computer. The file name, its size and the property values the rules need are sent to check them. The AI receives the results of the check, never your model or its elements.

The program also sends the project and trade names you gave it, and a fingerprint of the file (a SHA-256 number that identifies the file and holds none of its content). It remembers the models already checked in a small file in your own user data folder, not in the watched folder, so whoever can write the folder cannot mark a model as checked. That file never holds your key or anything from inside a model.

Notes

A check from the watched folder counts as one check of your plan, like a check from the browser. If the program is not running, nothing is checked: open Check a model and drop the file in the browser instead.