PULSE per Forma® | Documentazione beta

1. REQUISITI

Prima di installare.

PULSE per Forma gira in locale sul computer della persona che lo usa e comunica con Autodesk attraverso le API ufficiali. L'installazione è per utente e non richiede scrittura in Program Files.

Windows 10 o Windows 11.
Un client AI desktop compatibile installato sul PC.
Node.js 20 o successivo. Se manca, l'installer lo scarica e lo configura.
Connessione verso developer.api.autodesk.com.
Porta locale 3978 libera per il login Autodesk.
Porta locale 3977 libera per il viewer 3D locale.

Le porte sono usate solo su 127.0.0.1. Non serve aprire regole firewall in ingresso: se proxy o firewall aziendali filtrano le chiamate Autodesk, deve essere consentito il traffico verso gli endpoint APS.

2. APS E HUB

Preparare Autodesk Platform Services.

La configurazione APS va preparata una volta da un amministratore con ruolo Account Admin sul hub Autodesk. Il ruolo Project Admin non è sufficiente per autorizzare l'app sul tenant.

Crea una app APS di tipo Desktop, Mobile, Single-Page App.
Lascia l'app pubblica: per questo flusso non serve un Client Secret.
Abilita Data Management API, Forma API e AEC Data Model API.
Imposta il callback esatto http://localhost:3978/callback.
Autorizza il Client ID nel hub Forma da Settings / Custom Integrations.
Ripeti l'autorizzazione per ogni hub su cui PULSE deve lavorare.

Se il login riesce ma i progetti non compaiono, nella maggior parte dei casi l'app è stata autorizzata sul hub sbagliato o non è stata autorizzata su tutti i hub necessari.

La regione deve corrispondere all'ambiente Autodesk: US per acc.autodesk.com, EMEA per acc.autodesk.eu. Una regione errata produce risposte vuote o errori 404.

3. INSTALLAZIONE

Installare la beta sul PC.

La pagina beta di PULSE per Forma invia il pacchetto personale con installer, documentazione e seriale Trial Premium di 14 giorni. Prima di avviare l'installazione chiudi i client AI desktop aperti.

Scarica lo ZIP ricevuto dalla pagina PULSE per Forma®.
Estrai completamente lo ZIP prima di avviare l'installer.
Esegui l'installer ufficiale incluso nel pacchetto beta.
Inserisci il Client ID APS preparato dall'amministratore.
Seleziona la regione US, EMEA o APAC.

Durante l'installazione PULSE verifica i prerequisiti, controlla Node.js, installa le dipendenze, copia il server in %APPDATA%\.pulse\forma, scrive il file .env, avvia un controllo reale del server MCP e aggiorna le configurazioni dei client rilevati.

Nei pacchetti tecnici la stessa procedura può essere eseguita anche da distribution\install.bat. Per installazioni silenziose usare distribution\install.ps1 -Silent -ApsClientId CLIENT_ID -Region US. Il log è in %TEMP%\pulse-forma-install.log.

4. CLIENT AI

Collegare l'assistente.

L'installer registra il server MCP locale nei client AI desktop presenti sul computer. Quando li trova, aggiorna le configurazioni di Claude Desktop, Claude Code, Codex/ChatGPT desktop, OpenCode, Cursor, Windsurf, Visual Studio Code, Cline, LM Studio, Gemini CLI e altri client compatibili con file JSON o TOML.

"pulse-forma": {
  "command": "node",
  "args": [
    "C:\\Users\\TUO_UTENTE\\AppData\\Roaming\\.pulse\\forma\\dist\\server.js"
  ]
}

Dopo l'installazione riapri il client AI desktop. Le app web nel browser non possono collegarsi direttamente a un server MCP locale.

5. LOGIN E VERIFICA

Primo avvio.

Al primo uso chiedi al client AI di collegarsi ad Autodesk. PULSE apre il browser sul login, completa il flusso PKCE e salva il token locale nel profilo utente.

Accedi ad Autodesk con PULSE per Forma. Controlla lo stato di PULSE per Forma. Elencami gli account e i progetti disponibili.

Il controllo di stato deve restituire versione, modalità di autenticazione, regione configurata e strumenti attivi. Se l'elenco progetti è vuoto, verifica hub, autorizzazione app, regione e permessi dell'utente sul progetto.

6. WORKFLOW INIZIALI

Cosa puoi chiedere a PULSE.

La guida utente copre i 162 comandi disponibili nella beta: navigazione di account, progetti e cartelle; issue; upload e gestione documenti; query del modello tramite AEC Data Model; Model Query Gateway; viewer 3D; Field Ops; Custom Attributes; Data Connector e funzioni admin.

Elencami gli account e i progetti disponibili. Dammi un inventario dei modelli del progetto selezionato. Mostrami i principali dati disponibili per questo modello. Elenca gli elementi con il parametro da verificare vuoto. Confronta due versioni del modello e prepara un riepilogo.

Le operazioni che modificano dati cloud restano protette da impostazioni locali, modalità anteprima e conferme esplicite dove previste.

7. VIEWER 3D

Viewer federato e prerequisiti.

Il viewer locale permette di aprire modelli, isolare elementi, colorarli per categoria, parametro o stato, leggere proprietà e catturare schermate. La sessione gira in locale sulla porta 3977 e viene aperta nel browser con un URL del tipo http://127.0.0.1:3977/session/....

Chiedi a PULSE di avviare il viewer.
Apri il link di sessione restituito dal client AI in Chrome o Edge.
Chiedi a PULSE di aprire il modello o di mostrare il risultato di una query.
Usa prompt come isola tutti i muri, colora gli elementi con WBS vuoto o inquadrali.

Per i modelli Revit cloud, le query principali usano AEC Data Model. Per il viewer 3D, le preview e l'analisi di file non Revit come IFC, DWG, NWC o PDF serve anche l'accesso Model Derivative API.

Model Derivative è una API Premium e non è disponibile sulle app APS Desktop pubbliche. Per abilitarla serve una seconda app APS di tipo Web App, con Client Secret custodito dall'azienda, autorizzata nel hub Forma tramite Custom Integrations.

APS_CLIENT_ID=client_id_della_web_app
APS_CLIENT_SECRET=client_secret_della_web_app

Queste variabili vanno aggiunte in %APPDATA%\.pulse\forma\.env sui computer dove il viewer avanzato è necessario, poi va riavviato il client AI. Se mancano o sono errate, i comandi viewer, preview o analisi non Revit possono fallire, mentre i workflow Forma e AEC Data Model continuano a funzionare.

Quando lavori su elementi del modello, preferisci gli externalElementId restituiti dalle query AEC. La traduzione da revitElementId a dbId può non essere disponibile su alcuni modelli; in quel caso ripeti l'operazione usando gli ID esterni della query.

8. SICUREZZA

Controlli locali.

Token, Client ID, regione e segreti restano nel profilo Windows dell'utente.
Audit e log locali non devono contenere token, URL firmati o dati sensibili nei log operativi.
Le letture restano separate dalle operazioni che modificano documenti, issue o dati admin.
Upload, delete, restore e funzioni admin richiedono autorizzazioni e conferme coerenti con il workflow.
La beta attiva un Trial Premium personale di 14 giorni tramite il seriale ricevuto dal form.

In questa fase non sono coperti tutti i moduli ACC/Forma: Cost Management, Takeoff, Forms, Photos e Model Coordination vanno considerati fuori dal perimetro operativo della beta.

9. PROBLEMI COMUNI

Diagnosi rapida.

Il login restituisce `invalid_client`.

Controlla che il Client ID APS sia corretto e non contenga spazi o ritorni a capo.

Il login funziona ma non vedo i progetti.

Autorizza l'app nel hub corretto e verifica che l'utente sia membro dei progetti con file visibili.

Vedo alcuni hub ma non tutti.

Ripeti la Custom Integration per ogni hub Autodesk necessario.

Ricevo errori 404 su progetti, file o modelli.

Controlla la regione configurata: US, EMEA o APAC.

PULSE non compare tra gli strumenti del client AI.

Chiudi e riapri completamente il client, poi controlla il log installer.

I comandi viewer o preview falliscono.

Verifica la Web App APS con Model Derivative, il Client Secret e l'autorizzazione nel hub.

10. GUIDE PDF

Guide complete.

I PDF inclusi nel pacchetto beta restano il riferimento operativo completo per setup, login, troubleshooting e uso dei 162 comandi.