> For the complete documentation index, see [llms.txt](https://platform-aec.gitbook.io/platform-aec-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://platform-aec.gitbook.io/platform-aec-docs/readme.md). # TRACE Documentation **TRACE is a coordination platform for construction teams, built in two parts:** * **TRACE Sync** - the bidirectional pipe between Bluebeam Studio Sessions and Autodesk Construction Cloud (ACC, now also branded Autodesk Forma) Issues. It creates native ACC Issues with 2D sheet pins from your Bluebeam markups, and writes resolved status back to Bluebeam when ACC Issues close. * **TRACE Weave** - the coordination layer on top of Sync. It threads related review comments and model issues into a single **Coordination Item**, so a design decision and everything it touches stay connected across the review-to-model workflow. Weave is a tab in the same dashboard; it reads the issues Sync already tracks and never changes how Sync runs. Reviewers keep working in Bluebeam, modelers keep working in Revit, and TRACE keeps them in sync - no manual re-keying. **TRACE runs on your own Windows machine (self-hosted) - your markup data and credentials never leave your network.** If you would rather we host it for you, a managed **Cloud** option is also available (see [Cloud Mode](#cloud-mode-platform-aec-hosts-the-engine)). *** ## What is TRACE Sync TRACE Sync creates native ACC Issues with 2D sheet pins directly from Bluebeam Studio Session markups, and writes resolved status back to Bluebeam when ACC Issues are closed. No manual data entry. No duplicate tracking. No workflow changes. **The full resolved loop:** Bluebeam markup (Rejected) -> TRACE -> ACC Issue with 2D sheet pin -> Autodesk Issues Add-in -> modeler resolves in Revit -> ACC Issue closes -> TRACE -> Bluebeam status "Completed" *** ## What is TRACE Weave Sync moves each markup to its own ACC Issue. **Weave connects them.** A single design decision usually spans several issues - a reviewer's cloud on the plan, the model change it drives, and the follow-on problems that change creates. Weave threads those into one **Coordination Item** so nothing gets lost between the review and the model. * **Coordination Items** group related issues (each item is `CI-NNN` plus the list of its markups' comments). An item stays open until all of its issues resolve. * **Human-curated links.** You draw the connection between two issues - "related to" (the honest default) or a directional "caused by." TRACE may *suggest* a link, but it never asserts a cause for you; a person always decides. Nothing is auto-merged and nothing is faked. * **Two planes of issues.** The **review plane** (human Bluebeam markups) and the **model-check plane** (automatic model clashes and model-health checks) - so a review comment, the clash it exposes, and the model-quality issue behind it can all live on one thread. Both planes are live. The model-check plane reads clashes from Autodesk Model Coordination, which requires a BIM Collaborate seat; without one, the review plane works normally on its own. * **Never loses a name.** Every human note, link, and grouping stays attached to its issue even when the model is republished or a new review cycle starts - the failure that quietly renames and orphans issues in other tools. Weave is **on by default** and appears as the **Weave** tab next to **Sync** in your dashboard. It only reads what Sync already tracks and writes to its own file - it can never affect the sync itself. *** ## How TRACE Sync Works (Self-Hosted) In self-hosted mode, the entire TRACE engine runs on your Windows machine - the same machine that runs Bluebeam Revu. Nothing is sent to Platform AEC; the engine talks only to your Bluebeam Studio Session and your ACC project. (Weave rides on the same engine and the same dashboard - see [What is TRACE Weave](#what-is-trace-weave).) **Forward sync (Bluebeam -> ACC):** The engine polls your active Studio Session every 15 seconds via the Bluebeam API. For each supported markup, it creates a native ACC Issue at the markup's exact 2D sheet pin coordinates, and renders a faithful sheet thumbnail through your local Bluebeam Revu and attaches it to the Issue. **ACC -> Revit (handled natively by Autodesk):** The Autodesk Issues Add-in (v5.2+, Revit 2022+) surfaces ACC Issues directly inside Revit. Modelers open the model from ACC Docs, see the issues, and resolve them in the model. No TRACE involvement. **Reverse sync (ACC -> Bluebeam):** When an ACC Issue is closed, the engine detects the status change on the next poll and writes the resolved status back to the corresponding Bluebeam markup (routed through Revu so it never disconnects you from your Studio Session). > **Bidirectional sync is live.** Both directions run end-to-end today: forward (Bluebeam markups -> ACC Issues with 2D pins and thumbnails) and reverse (an ACC Issue closes -> TRACE writes the resolved status back to the Bluebeam markup automatically). > **Eventually-consistent thumbnails:** the ACC Issue, pin, and status are created instantly over the API. The thumbnail is rendered by your local Revu a moment later. If Revu is briefly closed or its MCP integration is off, the Issue is still created on time - TRACE pauses thumbnail rendering, shows a clear banner on the dashboard, and resumes automatically once Revu is back. Nothing is ever lost. *** ## System Requirements | Component | Requirement | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Windows | Windows 10 or Windows 11 (64-bit) - the machine that runs Revu | | Bluebeam Revu | Revu with an active Studio Session, and the **MCP integration enabled** (for thumbnail rendering) | | Autodesk Construction Cloud | Build Essentials tier or higher, with Docs and Issues modules active | | Autodesk Revit | Revit 2022+ with Issues Add-in v5.2+ (for the modeler loop) | | Nonica AI Connector for Revit | **Optional.** Only for **Capture fix** (recording which model element a modeler fixed). The **free** NonicaTab tier is sufficient. Published on the Autodesk App Store by Nonica. Without it, everything else works and Capture fix shows as unavailable with an explanation. | | Autodesk Model Coordination | **Optional.** Only for the **model-check plane** (clashes). Requires a BIM Collaborate seat, sold by Autodesk. Review markups do not need it. | | Node.js | **Not required** - the installer bundles its own Node.js runtime | | Admin rights | **Not required** - installs per-user, no Windows service, no UAC | | Stays on | For continuous sync, leave this machine on and signed in - the engine auto-starts at login and runs hidden | *** ## Installation TRACE ships as a single installer that supports both self-hosted and cloud modes. There is nothing to install on a server - the whole engine is in this one package. 1. Download `TRACE-installer.zip` (provided by Platform AEC) 2. Extract the **entire** zip to a local folder, for example `C:\TRACE` (do not run it from inside OneDrive or a synced folder) 3. Open the folder and double-click **`install.bat`** 4. When prompted, choose **`2` - Self-hosted** (the full engine runs on this machine; your data stays local) 5. The setup wizard opens in your browser to connect your project (next section) 6. When the wizard finishes, the engine starts immediately, runs hidden, and auto-starts at every Windows login No Node.js, no admin prompt, no Windows service. To remove it later, run `uninstall.bat`. *** ## Setup Wizard The wizard opens automatically in your browser at **`http://localhost:3030`** during install (you can also reopen setup any time from the status tray). It guides you through: 1. **License** - paste your TRACE license key (validates before connecting) 2. **Bluebeam** - sign in to the Bluebeam account that owns the markups (one-time; uses Bluebeam OAuth) 3. **Session Selection** - choose the active Studio Session to sync 4. **Autodesk** - sign in to your Autodesk Construction Cloud account, then pick the ACC project 5. **Sheet Mapping** - map each Bluebeam sheet to its corresponding ACC sheet view 6. **Done** - the engine starts syncing and the dashboard opens at `http://localhost:3000` > **Sheet mapping matters.** Each Bluebeam PDF page is mapped to a specific ACC sheet. Markups on a mapped page sync to that ACC sheet; markups on a page you did not map are skipped (never lost - map the page later and they sync). Map only the sheets you are actively using. The wizard auto-matches sheets by name to make this easy. > **One Bluebeam account is all you need.** TRACE signs in to the **same** Bluebeam account you already use in Revu. It reads and writes through the Bluebeam API, which is not a second Revu "client", so it never triggers Bluebeam's "another computer" disconnect - that only happens if the same account joins a Session from two *Revu* instances at once. No separate service account or extra Bluebeam seat is required. **Starting a new project** automatically gives you a clean dashboard - TRACE clears the previous project's synced history when you select a different session or ACC project. Reconfiguring the same project (for example, adding sheets) keeps your history. *** ## Dashboard Your TRACE dashboard runs locally at **`http://localhost:3000`** on the machine running the engine. It has two tabs in the header - **Sync** (this page) and **Weave** (the coordination view, see [What is TRACE Weave](#what-is-trace-weave)). The Sync page shows: * Live sync health (% healthy, error count) and a live heartbeat * The five metric cards: Sync Ticks, Markups Tracked (with a scrollable sheet list), BB -> ACC, ACC -> BB, Errors * A sortable table of every markup with its sheet name, ACC Issue number, and status * An activity feed with timestamped, direction-colored events (blue = BB -> ACC, green = ACC -> BB) * An alert banner if Revu's MCP renderer becomes unreachable (so you know thumbnails are paused) * **One-click reconnect** buttons in the header for Bluebeam and Autodesk (see below) > **One-click reconnect.** If a sign-in ever expires, the dashboard shows a **Reconnect Bluebeam** (and, in cloud mode, **Reconnect Autodesk**) button - and a pulsing alert banner when a token refresh fails. Click it to re-authorize the provider right from the dashboard; no terminal, no reinstall. The engine picks up the new sign-in on its next cycle. (In self-hosted mode the Autodesk reconnect button is hidden; reconnect Bluebeam from the dashboard, and re-run the wizard if you ever need to re-authorize Autodesk.) *** ## Published Version Both the **Sync** and **Weave** pages have a **Published Version** button in the header, next to **Bluebeam Session**. An ACC pin belongs to the **published version of the sheet it was placed on**. If someone republishes that sheet, existing pins stay on the version they were created against - Autodesk provides no way to move them. TRACE therefore makes the version visible and lets you choose it, rather than guessing. * The button shows which version new issues will pin to, for example **Published Version v2**. * If that is not the newest published version, the button turns amber and reads **Published Version v2 - latest v8**. This is information, not an error: you may be deliberately pinned to the version your reviewers are marking up. * Click it to see every published version of your mapped sheets, with dates, and pick which one new issues should pin to. TRACE validates your choice against the real version list. * The markup table has a **Version** column showing which version each issue's pin belongs to, so you can see at a glance which round an issue came from. Changing the version affects **new** issues only. Existing issues and their pins are never moved or closed - moving them silently would misstate where a problem actually was. *** ## Using Weave Open the **Weave** tab in the dashboard header. Each card is a **Coordination Item** (`CI-NNN`) holding one or more issues. **Filters** (top of the page): | Control | What it does | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------- | | **All / Open / Closed** | Filter items by state | | **Discipline: All** | Filter by discipline. A clash spanning two disciplines matches both. | | **Plane: All** | Filter by what the item is made of: **All planes**, **Review Markup only**, **Model Check only**, or **Spans both planes** | | **Search** | Free text across comments, markup types, disciplines and ACC issue numbers | | **Clear filters** | Appears only while a filter is active | A **Showing N of M items** readout sits beside the filters. When a filter matches everything it says so explicitly - on a real project most items share a discipline, so "all of them" is a normal and correct answer, not a broken filter. **Linking issues.** Click **Link** on any issue card to connect it to any other issue in the project, including across planes - a review markup to the model clash it caused. Issues already linked to that one are hidden from the list so you cannot link the same pair twice. If two candidates would otherwise look identical, TRACE adds their discipline and a short id to tell them apart. * The default link is **relates-to**, which is symmetric and claims nothing about cause. * **Causes** is directional and opt-in. TRACE never asserts a cause for you. * Two people may record conflicting views of the same pair. Both are kept, and the link shows as **contested** - a record that cannot hold a disagreement is not evidence. * **Unlink** retracts a link. It is marked as retracted and stays on the record; nothing is deleted. *** ## Capture fix (which element was fixed) On any issue card in Weave, **Capture fix (Revit selection)** records **which model element** the modeler actually changed to resolve that issue. Select the element in Revit, click the button, and TRACE stores that element's permanent Revit identifier as evidence of the fix. This is what lets TRACE notice that two issues were resolved on the **same** element and suggest they are related. TRACE can only ever *suggest*; a person confirms every link. **What it needs:** Revit open with the model loaded, an element selected, and the **Nonica AI Connector for Revit** installed and enabled (open the NonicaTab in Revit and switch on the AI connection). **The free NonicaTab tier is sufficient** - TRACE only reads your current selection. **If the connector is not installed,** the button appears disabled and reads **Capture fix - needs Revit connector**, with instructions in its tooltip. Nothing else in TRACE is affected. **Notes** * TRACE only ever **reads** your Revit selection. It never modifies your model. * Select the element in **its own model**. If you select an element inside a linked model, TRACE says so rather than recording an identifier it cannot match later. * A capture can be retracted. It stays on the record marked as retracted, and stops counting as evidence. *** ## The Status Tray TRACE places a **system tray icon** (bottom-right of the Windows taskbar) showing status at a glance: * **Green dot** - engine connected and healthy; shows the last sync time * **Yellow dot** - attention needed (errors, or license expiring soon) * **Red dot** - engine not running Right-click the tray icon to **Open Dashboard**, open **Setup / Add Sheets**, **Restart Engine**, or exit. A navy-cube **"TRACE Tray"** shortcut is also placed in your Start menu and on your Desktop so you can reopen the tray if you ever close it. The engine starts automatically on Windows login and runs hidden - you normally never need to touch it. > Keep Bluebeam Revu open with your Studio Session (and MCP enabled) so TRACE can render thumbnails. The sync itself (issues, pins, status) does not require Revu to be open - only the thumbnail render and status writeback do. *** ## Supported Markup Types Only four markup types generate ACC Issues. All other types are silently ignored. | Markup Type | Bluebeam Type | Pin Location | | ----------- | --------------- | ------------------------------- | | Cloud+ | PolygonCloud | Centroid of cloud body | | Cloud | CloudAnnotation | Centroid of annotation rect | | Callout | FreeTextCallout | Callout tip coordinates | | Pen | Ink | Centroid of ink annotation rect | **Silently skipped:** FreeText, Arrow, Line, Rectangle, Arc, Ellipse, Polygon, Length Measurement, Stamp, and all other types. *** ## Status Mapping **ACC -> Bluebeam (reverse sync):** | ACC Issue Status | Bluebeam Markup Status | | ---------------- | ---------------------- | | in\_progress | None | | not\_approved | None | | in\_dispute | None | | draft | None | | pending | Accepted | | in\_review | Accepted | | closed | Completed | **Bluebeam -> ACC (forward sync):** TRACE syncs the markup's current Bluebeam status and comments to the ACC Issue on every update. Reverse sync is suppressed right after a forward write to prevent echo loops. In the activity feed, each event shows the status from the platform the change came from - the Bluebeam status for BB -> ACC events, the ACC status for ACC -> BB events. > **Your manual Bluebeam statuses are preserved.** A status you set by hand in Bluebeam - including **Rejected** and **Cancelled** - is never silently rewritten. TRACE writes back only when the two sides genuinely disagree, so a reviewer's deliberate Rejected or Cancelled stays put. *** ## Bluebeam Studio Setup TRACE works with **Bluebeam Studio Sessions** (not Studio Projects). * Markups must be created inside an active Studio Session * The session is polled every 15 seconds by the engine * Multiple PDF sheets per session are supported - map each sheet in the setup wizard * Enable the **MCP integration** in Revu so TRACE can render thumbnails locally *** ## Autodesk Construction Cloud Setup * ACC project must have the **Docs** and **Issues** modules active * Issue types must be configured in the project settings * PDF sheets must be published to ACC Docs before mapping in the wizard * The PDF sheets in ACC must match the Bluebeam files (same version, same geometry) *** ## Revit Setup * Install the **Autodesk Issues Add-in v5.2+** * Open the Revit model from **ACC Docs** (not a local copy) * Issues created by TRACE appear in the Issues panel automatically * Modeler resolves the issue in the model and closes the ACC Issue - TRACE handles the rest *** ## Cloud Mode (Platform AEC Hosts the Engine) Prefer not to run the engine yourself? In cloud mode the TRACE sync engine runs on a Platform AEC cloud server 24/7, and you install only a lightweight **Agent** on the machine running Revu. * **The cloud engine** does all of the Bluebeam <-> ACC synchronization - reading markups, creating and updating ACC Issues, and writing status back. You do not install or manage it. * **The Agent** is a small background app that renders the sheet thumbnail for each ACC Issue using your local Revu and sends only that rendered image to the cloud. It is required for thumbnails. **Install (same installer):** 1. Extract `TRACE-installer.zip` and run `install.bat` 2. Choose **`1` - Cloud** 3. The Agent installs, starts immediately, and auto-starts at every Windows login 4. Your browser opens to the hosted setup wizard at `https://cloud.platform-aec.com/setup` to connect your project **Dashboard:** your hosted dashboard is at `https://cloud.platform-aec.com` - sign in from any browser, on any device, to check sync status from anywhere, not just the machine running Revu. The setup steps (Bluebeam + Autodesk sign-in, session, project, sheet mapping), supported markup types, and status mapping are identical to self-hosted. *** ## Troubleshooting **Markups not appearing in ACC:** * Confirm the markup type is Cloud+, Cloud, Callout, or Pen (other types are skipped) * Confirm the markup's sheet (PDF page) is mapped in the wizard - markups on an unmapped page are skipped until you map that page * Check the dashboard at `http://localhost:3000` for sync health and error messages **ACC Issue created but no thumbnail:** * Make sure Bluebeam Revu is open, joined to the Studio Session, and has **MCP enabled** * If the dashboard shows a "Revu MCP not reachable" banner, thumbnails are paused; enable MCP / reopen Revu and they resume automatically * Thumbnails are rendered a moment after the Issue is created - give it a tick or two **Issue on the wrong sheet:** * This is a sheet-mapping mismatch - reopen the wizard and confirm each Bluebeam page maps to the correct ACC sheet * Ensure the PDF sheet version in ACC matches the Bluebeam file exactly (coordinate mapping requires identical geometry) **Status not writing back to Bluebeam:** * Bluebeam Revu must be open and connected to the Studio Session **Sign-in expired / authentication errors:** * If the dashboard shows an authentication alert banner, click **Reconnect Bluebeam** (or **Reconnect Autodesk** in cloud mode) in the dashboard header to re-authorize - no terminal or reinstall needed * The engine resumes on its next cycle once the new sign-in completes **Dashboard not loading:** * Open a browser to `http://localhost:3000` on the machine running the engine * If it is blank, reopen the engine from the status tray (Restart Engine), or contact Platform AEC support *** ## FAQ **Does TRACE change how reviewers work in Bluebeam?** No. Reviewers mark up PDFs in Bluebeam Studio Sessions exactly as they always have. **Does TRACE change how modelers work in Revit?** No. Modelers use the standard Autodesk Issues Add-in inside Revit. TRACE creates the issues; the Add-in surfaces them. **What exactly runs on my machine in self-hosted mode?** The full TRACE engine plus a small status tray. The engine talks only to your Bluebeam and Autodesk accounts - your data never leaves your network. **Do I need a server?** No. The engine runs on the same Windows machine as Revu. For continuous sync, leave that machine on and signed in. **Which Bluebeam tier is required?** Any Bluebeam Revu license that supports Studio Sessions, with the MCP integration enabled. **Which ACC tier is required?** Build Essentials or higher (Docs + Issues modules must be active). **Can TRACE sync multiple sheets?** Yes. Map as many sheets as needed in the setup wizard. (Multiple *sessions* at once are on the roadmap.) **Does TRACE work if Bluebeam Revu is closed?** Forward sync (issues, pins, status) continues - the engine reads markups via the Bluebeam API and does not need Revu open. Only the thumbnail render and status writeback need Revu open and joined to the session. **What happens if my machine or the engine restarts?** The engine auto-starts at login and resumes from its saved sync state - nothing is duplicated or lost. *** ## Security & Data Handling **Self-hosted (recommended):** * **The engine runs on your machine.** It talks directly to your Bluebeam Studio Session and your ACC project - nothing is sent to Platform AEC. * **Your data stays on your network:** markups, geometry, files, and OAuth tokens never leave the machine. * **Authentication:** OAuth 2.0 for both Bluebeam and Autodesk; tokens are stored locally on your machine and refreshed automatically. * **Transport:** all traffic is directly between your machine and Bluebeam/Autodesk over HTTPS. **Cloud mode (managed, early access):** * The sync engine runs on a secure Platform AEC server; your markup and issue data is processed there to keep Bluebeam and ACC in sync. The Agent on your machine sends only the rendered thumbnail image - not your files. *** ## Contact & Support **Amro Sallam - Platform AEC Inc.** Email: For Early Access customers: response within 24 hours. Include a screenshot of your dashboard and a description of the issue. Website: [platform-aec.com](https://platform-aec.com) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://platform-aec.gitbook.io/platform-aec-docs/readme.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.