Článek je technický, pro lidi, kteří hledají „Trimble BCF import problems“, ne obecné BIM novinky. Prostě se může stát, že vám práce s BCF v Trimble connect smaže vazby na prvky, náhledový obrázek a další informace!!

English summary

Trimble Connect BCF file import is not a reliable way to push status or comment updates back from an external BIM app. On a real project (71 topics, full 47 MB export vs. ~55 KB metadata delta), we found that metadata-only .bcf re-import often removes 3D viewpoints and IFC links on existing topics, while including the same viewpoint or comment GUIDs triggers already exists errors. BCF export also requires project administrator rights—regular users may see TOPIC_EXPORT_ERROR / Access denied and get a 2 KB file with one topic instead of the full set. Official docs lag behind practice (e.g. BCF 3.0 exports while help still emphasizes 2.1). The buildingSMART-correct path is BCF-API (PUT topic, POST comment), not BCF-XML zip exchange; BIMcollab-style update files behave the same as a minimal delta export. What works today: full BCF down into your tool, local archive as source of truth, status changes in Trimble UI, or delete topic + full re-import with new GUIDs as a heavy fallback; a Trimble Connect project extension calling Topics API is the most practical next step without full OAuth developer registration.

1. Od čeho jsme začínali (a proč to vůbec řešit)

Myšlenka je na papíře jednoduchá: úkoly (BCF Topics) vedeme v Trimble Connect — kvůli 3D kontextu, týmu, assignee, stavům. Práci s rozpočtem děláme ve Forgee Takeoff — rozkliknu prvek, vidím pravidla, pozici v rozpočtovém XML, odchylky, kde je položka v souboru. Chyběl jen most zpět: když v Takeoffu odbavím tiket (stav, komentář, štítek), Trimble to musí vědět.

BCF jako standard na to vypadá ideálně: Trimble exportuje .bcf, my importujeme, pracujeme, exportujeme delta, Trimble importuje. Realita je složitější — hlavně směr nahoru (aplikace → Trimble).

2. První náraz: export/import není pro každého uživatele

Než jsme řešili obsah souborů, narazili jsme na oprávnění.

Při exportu BCF z Trimble Connect (filtry „Assigned to me“, desítky topiců v UI) vypadl soubor ~2 kB, uvnitř 1–2 topic(y). V exportním protokolu u každého ostatního:

{
„code“:“TOPIC_EXPORT_ERROR“,
„message“:“Access denied: You do not have permission for this operation“
}

Lesson: BCF export/import v TC není jen „vidím seznam úkolů“. Potřebuješ projektového administrátora nebo explicitně nastavená práva. Trimble nemá jemný RBAC typu „může měnit stav, ale neexportovat BCF“ — prakticky User vs. Admin + práva ke složkám (read/write). Pro integraci to znamená: účet, kterým sync děláš, musí být admin projektu (nebo export dělá admin a soubor předává).

Po nastavení admin práv stejný export vyšel ~47 MB, 71 topiců, 76 viewpointů, 44 komentářů — celý projekt (5lzZy3B5a5Q).

3. Dva světy: BCF-API vs. BCF soubor (a dokumentace lže)

Trimble oficiálně propaguje BCF Topics API — BCF server podle buildingSMART (2.1 i 3.0). Správný update = PUT topic, POST comment. Ne přepis celého ZIPu.

Registrace OAuth app na developer.trimble.com je ale pro malý tým těžká (musíte koupit licenci, nebo být parner, nebo použít licenci zákazníka – nemyslitelné) — proto jsme šli cestou souborů.

BCF 2.1 vs. 3.0 — realita ≠ help

Help dlouho tvrdil: import/export souborů jen 2.1. Export z TC v červnu 2026 ale klidně dá 3.0:

<!– bcf.version –>
<Version VersionId=“3.0″/>
BCF 3.0 export BCF 2.1 export
ServerAssignedId (BCF-63)
ano
ne
project.bcfp / ProjectId
ano
ano
Viewpointy v malém exportu
ne
ne

Lesson: Pro import do vlastní appky ber 3.0 (máš lidské ID ticketu). Pro re-import do Trimble jsme konzervativně testovali 2.1 (oficiálně podporovaný).

Dva typy BCF souborů (kritické!)

Typ Velikost Obsah K čemu
Plný archiv
desítky MB
.bcfv, .png, Header/Files, GUID prvků
První import, obnova pohledů
Metadata export
desítky kB
jen markup.bcf, stavy, komentáře
Sync stavů dolů do Forgee

Metadata export nesmí jít uploadem nahoru do TC u existujících topiců — viz další sekce.

4. Co funguje spolehlivě (směr dolů)

Trimble → export BCF → import do Forgee — tohle jsme dotáhli:

  • Parsování BCF 3.0 (bcf-client / vlastní parser)
  • Mapování na issue v Mongo: topicGuid, ServerAssignedId, stav, assignee, komentáře
  • Viewpointy + IFC GUID z plného archivu → navigace v 3D Takeoffu
  • bcfSync baseline po importu — snapshot stavu/komentářů z posledního BCF z Trimble; UI ukazuje Trimble / Lokálně
  • Forgee umí odbavit tiket i když Trimble u topicu už nemá 3D (práce z lokálního archivu)

Lesson: Lokální plný BCF archiv na disku = pojistka. Cesta v metadata.json → bcf_import.lastSourcePath.

5. Co nefunguje: file import jako „update kanál“ (směr nahoru)

Tady je jádro článku. Trimble file import u existujícího topicu (stejné Topic GUID) není delta patch — chová se spíš jako „toto je nový stav topicu z souboru“.

Matice pokusů (konkrétní projekt , reálné soubory)

Varianta exportu Výsledek v Trimble
Metadata only — stav + nové komentáře, bez ViewPoints, bez .bcfv
Import projde, ale často smaže pohledy a vazbu na IFC u topiců
ViewPoints v markup, bez .bcfv souborů
VIEWPOINT_IMPORT_ERROR — chybí soubor
ViewPoints + .bcfv se stejnými GUID
Viewpoint with this GUID already exists…
Header/Files (ReferencedFiles) se stejnými GUID
REFERENCED_FILES_IMPORT_ERROR — already exists
BIM Collab update export (Nové tickety_*_update.bcf, BCF 2.1)
Stejné chování jako náš Forgee delta — Collab to neřeší lépe
Plný archiv + nové topic/viewpoint GUID (režim obnovy)
Teoreticky create po smazání topicu v TC — neotestováno naživo

Typické chyby z importního protokolu:

Comment with GUID ‚xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx‘ already exists for this issue
Viewpoint with this GUID already exists in the specified project and issue

Proč metadata-only export „smaže“ 3D

Náš první „minimální delta“ export (~55 KiB, 8 stavů, 10 komentářů, 0 pohledů) Trimble interpretoval tak, že topic už nemá viewpointy ani selection. U všech dotčených úkolů zmizely obrázky a vazba na model.

To není bug Trimble v klasickém smyslu — špatný mental model na naší straně: BCF ZIP u file importu = deklarace celého stavu, ne JSON patch.

buildingSMART vs. Trimble file import

Specifikace BCF-API: viewpointy jsou immutable (append-only). Update = nové komentáře, změna metadat topicu. File import to nedodržuje — nemůžeš bezpečně poslat „jen stav“ bez pohledů.

Lesson: Checkbox „Aktualizujte nastavení projektu tématu…“ při importu neresí pohledy — jen rozšíří povolené Type/Status/Priority/Tag v nastavení projektu (kvůli cizím hodnotám z Collabu). Trimble Help — Import BCF

6. Co jsme nakonec implementovali (pragmatický kompromis)

V Forgee dva režimy exportu:

1. Update (stav + komentář) — z metadata BCF z Trimble

  • Nové komentáře dostanou nové GUID
  • Existující komentáře z baseline se neopakují (fix „already exists“)
  • Riziko: upload může smazat pohledy → používat vědomě, nebo měnit stav v TC UI

2. Obnova Trimble (plný + nové GUID) — z plného archivu

  • Nové topic GUID, nové viewpoint GUID, přejmenované .bcfv/.png
  • Historie jen v textu komentářů z activity
  • Postup: smazat topic v TC → import → fresh BCF zpět do Forgee

Sync baseline bcfSync — po importu z Trimble víme, co je „jako v cloudu“ vs. lokální změna. Re-import po uploadu narovná Mongo bez slepého tlačítka „upload OK“.

7. Co jsme se naučili o integraci obecně

  1. Neplést kanály: BCF-XML = výměna / create; BCF-API = sync. Trimble file import ≠ API patch.
  2. Dva soubory, dvě role: metadata BCF pro diff dolů; plný archiv pro 3D a obnovu.
  3. GUID disciplína: Topic GUID = identita. Komentáře a viewpointy mají vlastní GUID — re-import stejných = chyba.
  4. Práva first: bez admin exportu nemáš data — integrace začíná u TC projektových rolí.
  5. Dokumentace zaostává: TC exportuje 3.0, help mluví o 2.1; ověřuj bcf.version v ZIPu.
  6. BIM Collab není záchrana: jejich update BCF se chová jako náš delta — stejné limity file importu.
  7. Relink model: Trimble má ruční relink — signál, že vazba IFC je křehká (nicméně v Trimblu jsem tu volbu nikde nenašel).

8. Kam dál (zatím jen dokumentace, ne kód)

TC project extension + BCF Topics API — extension v TC Web dostane token přihlášeného admina, volá REST (PUT/POST), posílá data na vlastní bridge → Mongo Atlas. Obchází registraci OAuth app; sync spouštíš tlačítkem v TC místo export/import souboru. Viz docs/development/bcf_trimble_workflow.md.

Pro solo admina (já = uživatel = admin) je to nejlogičtější náhrada file kolotoče — až bude čas otestovat na živém projektu.

9. Co jsme nezjistili / otevřené

  • Re-import Obnova Trimble (nové GUID) na produkční zakázce s klientem v loopu
  • Import BCF 3.0 zpět do TC (exportují 3.0, import help stále zdůrazňuje 2.1)
  • Trimble odpověď na FORBIDDEN export — jestli jde práva nastavit jemněji ve větších účtech (US enterprise)
  • Extension MVP: token → GET/PUT topics na jednom ticketu

10. TL;DR pro Googlera

Chci z vlastní aplikace posílat změny stavů BCF topiců do Trimble Connect.
File import .bcf u existujících topiců není spolehlivý update kanál — metadata-only import může smazat pohledy; plný re-import se stejnými GUID padá na already exists.
Funguje: plný export z TC → vaše appka; změny stavu v TC UI; nebo BCF-API / budoucí TC extension.
Nejdřív zkontrolujte: jste projektový admin? Máte plný BCF archiv? Nerozlišujete metadata vs. plný export?