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).
- 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.
- 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. - 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" - Leave the program running. Copy a model (
.ifc) into the folder, or let your sync tool bring one. - Read the line the program prints for the file.
recordedmeans the run is stored, with the score of each check. - 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:
--projectand--trade, as in step 3. - A small file named
bimgravity.jsonin 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 15if 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
| The line says | What it means | What to do |
|---|---|---|
refused … is incomplete | The file stops before its end. It is probably still copying. | Nothing. The complete file is checked when it arrives. |
refused … holds no element to check | The file has a project and levels but no element. | Export the model again. |
refused … is not an IFC model | The file has the .ifc ending but is something else. | Remove it. |
refused … a text value longer than 4000 characters | One property holds a very long text. It is not sent. | Shorten the value in the authoring tool. |
locked … in use by another program | Another program holds the file. | Nothing. The program tries again. |
failed … will try once more, then set-aside | The file could not be read twice. | Export the model again. The file is tried again only if it changes. |
waiting … trying again in 30 s | The 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 refused | The 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.
- Open Task Scheduler and select Create Task.
- On General, name it “BIMgravity watched folder”. Choose Run only when user is logged on.
- On Triggers, add At log on for your user.
- On Actions, add Start a program. Program: the path of
node.exe. Arguments: the path ofbimgravity.mjs, thenwatch "C:\Projects\Riverside" --recursive. - Set the key once for your user, in a terminal:
setx BIMGRAVITY_API_KEY "your key". Also setBIMGRAVITY_URLto 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.