# TRACE Docs ## Trace Documentation #### by PLATFORM AEC ## 1. What is Trace Trace is a bidirectional sync engine built by PLATFORM AEC that connects **Bluebeam Studio Sessions** to **Autodesk Construction Cloud (ACC) Issues** — automatically. When a reviewer marks up a PDF in a Bluebeam Studio Session, Trace reads that markup via API and creates a native ACC Issue with a 2D sheet pin placed at the exact location of the markup on the drawing sheet. When the issue is resolved and closed in ACC — whether by a project manager or a Revit modeler using the native Autodesk Issues Add-in — Trace writes the completed status back to the original Bluebeam markup, closing the loop automatically. **No manual data entry. No copy-paste between platforms. No markups left open after issues are resolved.** ### Who is Trace for? Trace is designed for **General Contractors and Construction Management firms** who use both Bluebeam Studio for design review and Autodesk Construction Cloud for project management and issue tracking. It is specifically built around the coordination gap that exists between these two platforms — a gap that currently costs teams significant time and introduces errors on every project. ### What Trace is not Trace does not replace Bluebeam, ACC, or Revit. It is not a markup creation tool. It does not modify drawings. It does not create Bluebeam markups — it reads them. Trace runs silently in the background, connecting tools your team already uses without changing how they use them. ## 2. How Trace Works Trace implements a full bidirectional loop across three platforms: ### The Forward Path: Bluebeam → ACC {% stepper %} {% step %} ### A reviewer opens a PDF inside a **Bluebeam Studio Session** and adds markups Clouds, callouts, and annotations are added as part of a standard design review. {% endstep %} {% step %} ### Trace monitors the session via the Bluebeam Studio API and detects new or updated markups {% endstep %} {% step %} ### Trace creates a native **ACC Issue** via the Autodesk Construction Cloud Issues API This includes a **2D sheet pin** placed at the exact X/Y coordinates of the markup on the drawing sheet. {% endstep %} {% step %} ### The ACC Issue appears in Autodesk Forma and is visible to the entire project team {% endstep %} {% endstepper %} ### The Autodesk Native Leg: ACC → Revit This leg is handled natively by Autodesk — no custom code required from Trace. {% stepper %} {% step %} ### The Revit modeler opens the model from ACC Docs in Revit 2022 or later {% endstep %} {% step %} ### The **Autodesk Issues Add-in** (v5.2+) displays the ACC Issue as a pushpin directly on the corresponding sheet in Revit {% endstep %} {% step %} ### The modeler makes the required change and marks the issue as resolved in ACC {% endstep %} {% endstepper %} ### The Return Path: ACC → Bluebeam {% stepper %} {% step %} ### Trace detects the issue closure in ACC {% endstep %} {% step %} ### Trace writes the **Review/Completed** status back to the original Bluebeam markup via the Bluebeam Studio API {% endstep %} {% step %} ### The markup now appears as "Completed set by Platform AEC" in Bluebeam's Markups List — visible to all session attendees {% endstep %} {% endstepper %} **The entire loop is automatic. No human intervention required between steps 2 and 10.** ## 3. System Requirements ### Bluebeam Requirements | Requirement | Minimum | | ---------------- | -------------------------------------------------------------------------------------------------- | | Bluebeam product | Revu with Studio or Bluebeam Max | | Studio Sessions | Active Studio subscription required | | API access | Bluebeam v2 SessionMarkups API (beta access required — arranged by PLATFORM AEC during onboarding) | | Session type | Studio Session (not Studio Project) | ### Autodesk Construction Cloud Requirements | Requirement | Minimum | | ---------------- | ------------------------------------------- | | ACC subscription | Build Essentials or higher | | ACC Issues | Issues module must be active on the project | | Project type | ACC project with Docs enabled | | Sheets | PDF sheets published to ACC Docs | ### Revit Requirements (for ACC → Revit leg) | Requirement | Minimum | | ---------------------- | ------------------------------------------------------------------------ | | Revit version | Revit 2022 or later | | Autodesk Issues Add-in | Version 5.2 or later | | Model location | RVT model must be published to ACC Docs and opened from ACC within Revit | ### Machine Requirements (Beta V1) During Beta V1, Trace is installed and configured by the PLATFORM AEC team on a designated machine at your organization. | Requirement | Minimum | | ---------------- | --------------------------------------------------------------------------- | | Operating system | Windows 10 or Windows 11 | | Runtime | Node.js 18 or later (installed by PLATFORM AEC) | | Network | Outbound internet access to api.bluebeam.com and developer.api.autodesk.com | | Availability | Machine must be running during active review sessions for sync to operate | ## 4. The Beta Program ### What Beta V1 Means Trace Beta V1 is a private, managed beta. Access is by invitation only. PLATFORM AEC works directly with each beta customer to configure, deploy, and support Trace on their projects. Beta V1 is **not self-serve**. There is no installer to download. Onboarding requires a direct engagement with the PLATFORM AEC team. ### What Beta Customers Get * Direct access to Amro Sallam (Founder, PLATFORM AEC) for onboarding and support * Trace configured and installed on your designated sync machine * Full end-to-end sync between Bluebeam Studio Sessions and ACC Issues * Participation in shaping the product roadmap before public launch * Preferred pricing when Trace moves to general availability ### What We Ask of Beta Customers * A real project to test on — live Bluebeam Studio Sessions and an active ACC project * Feedback on the workflow, edge cases, and anything unexpected * A designated point of contact at your organization for onboarding coordination ### How to Apply Email **** with: * Your company name and role * Which tools you currently use (Bluebeam version, ACC subscription tier) * A brief description of the project coordination challenge you're trying to solve ## 5. Bluebeam Studio Setup ### Session vs. Project Trace works with **Bluebeam Studio Sessions**, not Studio Projects. * **Studio Session**: A time-boxed collaborative review event where attendees mark up PDFs together in real time. Sessions are the correct primitive for design review workflows. Trace is built around Sessions. * **Studio Project**: A persistent file storage location. Trace does not currently sync from Studio Projects. If your team uses Studio Projects as storage between reviews, the correct workflow is: store files in the Project, pull them into a Session for each review round, and let Trace handle the sync during the Session. ### Setting Up a Session for Trace 1. Open Bluebeam Revu on your machine. 2. Navigate to **Bluebeam Studio → Sessions → Start Session**. 3. Add the PDF drawing sheets you want reviewed. 4. Invite reviewers as session attendees. 5. Provide the **Session ID** (format: `XXX-XXX-XXX`, visible in the session header) to your PLATFORM AEC onboarding contact so Trace can be pointed at the correct session. ### Session Lifecycle | Stage | Duration | Notes | | ------------- | -------------------------- | ------------------------------------------------------ | | Active review | 1–2 weeks typical | Trace syncs markups during this window | | Archive | 90 days after session end | Session data accessible but not actively synced | | Deletion | 180 days after session end | Session data permanently removed from Bluebeam servers | ### Important: Session Start = Fresh Canvas When a Studio Session starts, it opens with a fresh canvas. Markups that exist on your local PDF are **not automatically imported** into the session. Reviewers must add markups directly within the session. This is standard Bluebeam behavior, not a Trace limitation. ### Markup Author Display When Trace writes a status back to Bluebeam, it will appear in the Markups List as: > "Completed set by Platform AEC on \[date] at \[time]" This is the display name associated with the Trace application credentials. It is not configurable in Beta V1. ## 6. Autodesk Construction Cloud Setup ### Project Requirements Your ACC project must have the following configured before Trace can create issues: 1. **Docs module active** — drawing sheets must be published to ACC Docs 2. **Issues module active** — the Issues tool must be enabled for the project 3. **Issue types configured** — at least one issue type must exist in the project settings 4. **Sheets published** — the PDF sheets being reviewed in Bluebeam must also exist as published sheets in ACC Docs ### Sheet Alignment Trace places ACC Issue sheet pins using the exact X/Y coordinates from the Bluebeam markup. This works because when Revit publishes a sheet to PDF and that PDF is used in both Bluebeam and ACC, both platforms share identical 2D geometry at identical scale. **For pins to land correctly, the PDF in Bluebeam and the sheet in ACC Docs must be the same file at the same version.** If different PDF exports are used, pin placement may be offset. ### ACC Permissions The account used to authorize Trace against ACC must have: * **Project Admin** or **Project Member** role on the target project * **Issues: Create and Edit** permissions * **Docs: View** permissions for the relevant sheet set Your PLATFORM AEC onboarding contact will walk through the authorization step during setup. You will authenticate Trace against your ACC account via a standard Autodesk OAuth flow — no credentials are stored by PLATFORM AEC. ### Issue Naming Convention In Beta V1, ACC Issues created by Trace are named using the following convention: > `[Markup Subject] — [Markup Comment]` For example, a Bluebeam callout with subject "Callout" and comment "CHECK WALL TYPE HERE" creates an ACC Issue titled: > `Callout — CHECK WALL TYPE HERE` Issue naming conventions will be configurable in future releases. ## 7. Revit Setup ### The Autodesk Issues Add-in The ACC-to-Revit leg of the Trace workflow is handled entirely by the **Autodesk Issues Add-in**, a native Autodesk tool. Trace does not write anything to Revit directly. **Requirements:** * Revit 2022 or later * Autodesk Issues Add-in version 5.2 or later (download from the Autodesk App Store) * The RVT model must be published to ACC Docs * Revit must be opened with the model loaded **from ACC** (not from a local file path) ### How the Revit Leg Works 1. The modeler opens Revit and loads the model from ACC Docs via the **Open from Autodesk Docs** option. 2. The Issues Add-in panel shows all open ACC Issues assigned to this project. 3. Issues created by Trace appear as 2D pushpins on the corresponding sheet within Revit. 4. The modeler navigates to the issue location, makes the required change, and marks the issue as **Resolved** or **Closed** in the Issues Add-in panel. 5. ACC updates the issue status. 6. Trace detects the status change and writes **Review/Completed** back to the Bluebeam markup. ### Troubleshooting Revit Issues **Issue pins not appearing in Revit:** * Confirm the model is opened from ACC Docs, not a local file * Confirm the Issues Add-in is version 5.2 or later * Check that the sheet view in Revit corresponds to the sheet the pin was placed on **Issue Add-in not showing issues:** * Ensure you are signed into the correct Autodesk account in Revit * Verify the project in Revit matches the ACC project Trace is connected to ## 8. Understanding the Sync Engine ### How the Sync Engine Runs In Beta V1, the Trace sync engine runs as a **Windows Service** on a designated machine. The service name is: > `Trace - Platform AEC Sync` The engine polls Bluebeam and ACC on a regular interval. It does not require a browser to be open or any manual action to trigger a sync. ### The Dashboard When the Trace engine is running, a local dashboard is accessible at: > `http://localhost:3000` The dashboard displays: * **Engine status** — whether the sync engine is running (LIVE or MOCK mode) * **Last sync time** — when the engine last successfully polled Bluebeam and ACC * **Markup state table** — all markups being tracked, their current BB status, linked ACC issue, and ACC status * **Recent activity feed** — a log of recent sync events, auto-refreshing every 5 seconds ### Sync Triggers | Event | Trace Action | | --------------------------------------- | ------------------------------------------------- | | New markup detected in Bluebeam Session | Creates ACC Issue with 2D sheet pin | | Existing markup status updated in BB | Updates linked ACC Issue status | | ACC Issue closed/resolved | Writes Review/Completed status to Bluebeam markup | ### Duplicate Detection Trace tracks all markups it has synced. If the engine restarts or a markup is encountered again, Trace will not create a duplicate ACC Issue. Each markup is synced once and tracked by its unique markup ID. ### Token Management Trace manages authentication tokens for both Bluebeam and ACC automatically. OAuth tokens are refreshed in the background. You will not be prompted to re-authenticate during normal operation. ## 9. Markup Types & Status Mapping ### Supported Markup Types In Beta V1, Trace reads all markup types from Bluebeam Studio Sessions. Common types include: | Bluebeam Type | Description | | -------------- | ------------------------------------ | | Cloud / Cloud+ | Area markup indicating a review zone | | Callout | Text annotation with leader line | | FreeText | Free-floating text annotation | | Polygon | Area markup (custom shape) | | Ellipse | Circular/oval markup | | Rectangle | Rectangular area markup | | Stamp | Pre-defined review stamp | All markup types with a subject and/or comment are eligible for ACC Issue creation. ### Markup Data Captured For each markup, Trace reads and maps the following: | Bluebeam Field | ACC Issue Field | | --------------------- | ----------------------------- | | Subject + Comment | Issue title | | X coordinate | Sheet pin X position | | Y coordinate | Sheet pin Y position | | Page number | Sheet reference | | Author (display name) | Issue description attribution | | Created timestamp | Issue creation reference | ### Status Values Bluebeam markup statuses available via the API: | Model | State | Meaning | | ------ | --------- | ------------------------------------------------ | | Review | None | No status set (default) | | Review | Accepted | Markup accepted as-is | | Review | Rejected | Change required | | Review | Cancelled | Markup voided | | Review | Completed | Issue resolved — written by Trace on ACC closure | Trace writes **Review / Completed** to a Bluebeam markup when the corresponding ACC Issue is closed. This is the status that appears in Revu as: > "Completed set by Platform AEC on \[date] at \[time]" ## 10. ACC Issues & Sheet Pins ### How Issues Are Created When Trace creates an ACC Issue, it uses the following structure: * **Type**: Native ACC Issue (type: "file") * **Sheet pin**: 2D placement on the corresponding sheet * **Pin position**: Normalized X/Y coordinates derived from the Bluebeam markup position * **Published**: True (immediately visible in Forma and the Revit Issues Add-in) * **Origin**: Tagged as created via Autodesk Docs API integration ### Viewing Issues in Forma ACC Issues created by Trace are visible in **Autodesk Forma** (formerly BIM 360) in the Issues module. Each issue displays: * The issue title (from markup subject/comment) * The 2D sheet pin on the drawing * Issue status (Open → Closed) * Creation timestamp and attribution ### Viewing Issues in Revit Issues appear as pushpins on the relevant sheet inside Revit when opened via the Autodesk Issues Add-in. The pin location corresponds directly to the markup location in Bluebeam. ### Issue Lifecycle | Stage | Trigger | ACC Status | BB Status | | ----------- | ------------------------------- | ---------- | ---------------- | | Created | New BB markup detected | Open | None | | In Progress | Assigned/acknowledged in ACC | In Review | None | | Resolved | Modeler marks resolved in Revit | Resolved | None | | Closed | PM closes in ACC | Closed | Review/Completed | Trace writes back to Bluebeam on **Closed** status. Resolved-only does not trigger writeback in Beta V1. ## 11. Status Writeback ### How Writeback Works When Trace detects that an ACC Issue has been closed, it calls the Bluebeam Studio API to update the corresponding markup status: ```http PUT /publicapi/v2/sessions/{sessionId}/files/{fileId}/markups/{markupId}/status Body: { "Model": "Review", "State": "Completed" } ``` This is the only write operation Trace performs on Bluebeam. Trace never creates, deletes, or modifies markup geometry — only markup status. ### Writeback Confirmation After writing the status, Trace performs a verification GET to confirm the status was applied. The dashboard activity feed logs this event. In Bluebeam Revu, the Markups List will display: > Completed set by Platform AEC on \[date] at \[time] This is visible to all session attendees in real time. ### Writeback Timing Writeback occurs on the next sync cycle after an ACC Issue is detected as closed. In Beta V1, the sync interval is configured during onboarding based on your workflow needs. Typical writeback latency is under 5 minutes. ## 12. Troubleshooting ### Markups Not Appearing in ACC **Check:** Is the Bluebeam Studio Session ID configured correctly in Trace?\ Confirm the Session ID (format `XXX-XXX-XXX`) with your PLATFORM AEC contact. **Check:** Is the sync engine running?\ Navigate to `http://localhost:3000` and verify the engine shows LIVE status. **Check:** Was the markup created after Trace was started?\ Trace only reads markups from the current session state forward. Markups that existed before Trace was configured may need to be re-created or manually synced. **Check:** Does the markup have a subject and/or comment?\ Trace uses subject and comment to construct the ACC Issue title. Markups with neither may be skipped in Beta V1. ### ACC Issue Pin in Wrong Location **Check:** Are the same PDF files used in both Bluebeam and ACC Docs?\ Pin placement relies on coordinate alignment between Bluebeam and ACC. If different PDF exports or versions are used in each platform, coordinates will not align. **Check:** Is the sheet published to ACC Docs at the same scale as the Bluebeam PDF?\ Scale differences between the Bluebeam PDF and the ACC sheet will offset pin placement. ### Status Not Writing Back to Bluebeam **Check:** Has the ACC Issue been fully **Closed** (not just Resolved)?\ In Beta V1, Trace triggers writeback on Closed status only. **Check:** Is the sync machine running and connected to the internet?\ The Windows Service must be active and have outbound internet access to api.bluebeam.com. **Check:** Is the Bluebeam authentication token valid?\ Token refresh is automatic, but if the machine has been offline for an extended period, re-authentication may be required. Contact your PLATFORM AEC onboarding contact. ### Dashboard Not Loading **Check:** Is the Trace Windows Service running?\ Open Windows Services (`services.msc`) and verify "Trace - Platform AEC Sync" is in a Running state. If stopped, right-click → Start. **Check:** Is another application using port 3000?\ The dashboard runs on `localhost:3000`. If another application is using that port, contact your PLATFORM AEC contact to reconfigure. ### Duplicate ACC Issues Trace includes duplicate detection and will not create a second issue for a markup it has already synced. If you are seeing duplicates, contact your PLATFORM AEC onboarding contact — this indicates a state file may have been cleared or the engine was re-initialized. ## 13. FAQ
Do reviewers need to change how they use Bluebeam? No. Reviewers use Bluebeam Studio Sessions exactly as they always have. Trace reads from the session in the background. There is nothing to install or configure on reviewer machines.
Do project managers need to change how they use ACC? No. ACC Issues created by Trace appear as native issues in the ACC Issues module. PMs manage them exactly like any other issue.
Does Trace work with all Bluebeam products? Trace requires a Bluebeam subscription that includes Studio Sessions. This includes Bluebeam Revu with Studio and Bluebeam Max. Bluebeam Revu Standard without a Studio subscription is not supported.
Does Trace work with all ACC subscription tiers? Trace has been tested and confirmed working on ACC Build Essentials tier and above. The v1 Issues API, which Trace uses, is available on Build Essentials.
Can Trace sync to multiple sessions at once? In Beta V1, Trace is configured for one session at a time per installation. Multi-session support is on the roadmap.
Can multiple projects be synced? In Beta V1, Trace is configured for one ACC project per installation. Multi-project support is on the roadmap.
What happens to markups that were in the session before Trace was configured? Trace will attempt to read all markups currently in the session on startup. Markups created before Trace was configured may or may not be synced depending on their state. Your PLATFORM AEC contact will advise on this during onboarding.
Does Trace store our drawing data? No. Trace reads markup metadata (position, subject, comment, status) but does not store, cache, or transmit drawing files or PDF content. See Section 14 for full data handling details.
What happens when the Bluebeam Session ends? When a Studio Session ends, Trace stops syncing for that session. Any markups not yet synced will be processed in the final sync cycle before the session closes. Future session rounds should be configured as new sessions.
Can we use Trace without Revit? Yes. The Revit leg of the loop is handled natively by Autodesk. Trace only manages the Bluebeam ↔ ACC connection. If your team resolves ACC Issues directly in the ACC Issues module (without Revit), the writeback to Bluebeam still occurs.
What is the pricing model? Trace is free during the Beta V1 program. Pricing for general availability has not been finalized. Beta participants will receive preferred pricing. Contact for details.
## 14. Security & Data Handling ### Authentication Trace uses **OAuth 2.0** (3-legged authorization code flow) to authenticate with both Bluebeam and Autodesk Construction Cloud. This means: * You authenticate using your own Bluebeam and Autodesk credentials * Trace never receives or stores your username or password * Access tokens are issued by Bluebeam and Autodesk directly and stored locally on the sync machine * Tokens are refreshed automatically and expire according to each platform's standard token lifecycle ### Data Accessed Trace accesses the following data from each platform: **From Bluebeam:** * Studio Session file list (to identify which PDFs are in the session) * Markup list per file (markup ID, type, position, subject, comment, status, author display name) * Markup status (read and write) **From Autodesk Construction Cloud:** * Project issue list (to detect status changes) * Issue creation (write only — creates new issues) * Sheet/viewable metadata (to place pins on the correct sheet) ### Data NOT Accessed Trace does not access: * Drawing files or PDF content * Personal account information beyond display names * Financial or billing data * Any data outside the configured session and project ### Data Storage Trace stores the following locally on the sync machine: * **State file** (`state.json`): Tracks which markups have been synced and their current sync state. Contains markup IDs, ACC issue IDs, and status values. No drawing content. * **Token file** (`.bb-tokens.json`, `.tokens.json`): OAuth access and refresh tokens for Bluebeam and ACC. Stored locally on the sync machine only. * **Environment file** (`.env`): Configuration including client IDs and session/project identifiers. No user credentials. None of these files are transmitted to PLATFORM AEC servers. ### Network Communication Trace communicates with the following endpoints: | Endpoint | Purpose | | ------------------------------------------- | ----------------------------------------------- | | `api.bluebeam.com` | Bluebeam Studio API (markup read, status write) | | `developer.api.autodesk.com` | Autodesk APS (ACC Issues API) | | `auth.bluebeam.com` | Bluebeam OAuth token exchange | | `developer.api.autodesk.com/authentication` | Autodesk OAuth token exchange | No data is sent to PLATFORM AEC servers during normal operation. ### Beta V1 Security Posture Beta V1 is a managed installation. PLATFORM AEC will not remotely access your sync machine without your explicit invitation. All configuration is done in person or via a documented setup call. ## 15. Contact & Support ### Beta Support During Beta V1, all support goes directly to the PLATFORM AEC founding team. **Primary contact:** Amro Sallam, AIA, NCARB Founder, PLATFORM AEC **Response time:** Within 24 hours on business days. For critical sync failures during an active review session, same-day response is our commitment. ### Reporting Issues When reporting an issue, please include: * The Bluebeam Session ID (format: `XXX-XXX-XXX`) * The ACC project name * A description of what you expected to happen and what happened instead * If available: a screenshot of the Trace dashboard at `http://localhost:3000` * The approximate time the issue occurred (for log correlation) ### Feature Requests Trace is actively being developed. Beta participant feedback directly shapes the roadmap. To submit a feature request or workflow suggestion, email with the subject line "Trace Feature Request." ### About PLATFORM AEC PLATFORM AEC is a construction technology company building intelligent integrations for the AEC and construction industries. **Design · Data · Intelligence** platform-aec.com --- # Agent Instructions: 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: ``` GET https://platform-aec.gitbook.io/platform-aec-docs/trace-docs.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.