FIELD GUIDE

New-Environment Setup Guide

Everything needed to stand up the Capital ⇄ Teamcenter integration on a fresh machine — hub, plugin, types, project bootstrap, and the verification pass that proves the loop is closed. Every step here is the procedure we actually ran, including the traps we hit so you don't have to.

1. Prerequisites

The bring-up is deliberately light: no JDK, no Maven, no pip installs, no application server. Four things need to exist before you start.

2. The hub: tc-service and config.json

The hub is one Python file tree: tc_service.py serves the REST contract, store.py keeps a merged head plus append-only revision history per project, and teamcenter_soa.py pushes to the real Teamcenter. It also watches Capital's publish outbox — any logical-bom-*.json dropped there is imported and moved to processed/, so the loop works even when a POST times out.

All behaviour lives in tc-service\config.json. A redacted working example:

{
  "port": 8080,
  "storeDir": "<repo>/tc-service/store-data",
  "defaultProject": "Demo Vehicle Program",
  "outboxDir": "<CapitalHome>/plugins/XceleratorTcImport/tc-outbox",
  "seedFile": "<repo>/tc-service/seed-demo-vehicle-program.json",
  "capitalDtdPath": "<CapitalHome>/dtd/project.dtd",
  "parentPatchDir": "<repo>/tc-service/patch-maps",
  "capitalBaseids": {
    "UAV Platform": { "project": "UID…", "design": "UID…", "platform": "UID…" }
  },
  "teamcenter": {
    "enabled": true,
    "baseUrl": "https://<teamcenter-gateway>",
    "user": "<tc-service-user>",
    "password": "<tc-service-password>",
    "componentType": "Fnd0LogicalBlock",
    "functionType": "Functionality",
    "allocationRelation": "Seg0Allocate",
    "portType": "Fnd0LogicIntrfce",
    "functionPortType": "Network_Port",
    "signalType": "Signal",
    "carrierType": "Fnd0LogicConn",
    "networkType": "Network",
    "interfaceType": "Seg0Interface",
    "intfSpecType": "Seg0IntfSpec",
    "requirementType": "Requirement",
    "requirementRelation": "IMAN_requirement",
    "runTag": "",
    "legacyRunTags": ["T7"]
  }
}

The fields that matter operationally: outboxDir must point at the deployed plugin's tc-outbox so the watcher sees publishes; capitalDtdPath is stamped into every generated project XML's DOCTYPE and must resolve on the machine that will import it; capitalBaseids holds the per-project Capital UIDs that turn a re-import into a merge (§5); parentPatchDir points at the patch maps (§6). Missing keys fall back to sane defaults — the config loader even tolerates a PowerShell-authored BOM.

Start it from the tc-service directory and probe it:

py tc_service.py            # seeds the demo project on first run; log: tc-service\service.log

curl http://localhost:8080/health
{"status": "ok", ...}

Key endpoints

3. Building and deploying the Capital plugin

One script, no JDK. build.ps1 compiles both source trees with Capital's own ecj.jar against capitalapi.jar, packages the jar with Python (PowerShell's Compress-Archive corrupts jars), and deploys:

.\build.ps1              # compile + package dist\capital-tc-import.jar
.\build.ps1 -Deploy      # ...and deploy to <CapitalHome>\plugins\XceleratorTcImport

The deployed folder holds the jar, tc-connection.properties, and extras\jackson-*.jar copied from Capital's own lib\ (never substitute a downloaded Jackson — Capital's copy avoids classloader conflicts). Deploy is copy-if-missing for the properties file, so your live settings survive every redeploy. The anatomy:

# Hub connection
tc.baseUrl=http://localhost:8080
tc.auth.mode=none
tc.source=rest             # live REST; falls back to tc.bundleFile if unreachable
tc.project=auto            # RECOMMENDED — the panel follows the open project:
                           # stamped TC_ID/"Element ID" on the design wins,
                           # then the Capital project name, then the design name
tc.timeoutMs=30000

# Publish (Capital -> hub)
publish.outboxDir=tc-outbox
publish.postEnabled=true
publish.postPath=/import/bundle

# Import behaviour
import.updateExisting=true
import.externalIdProperty=TC_ID

After relaunch, confirm the load in the Main log: Custom plugins loaded: N (92 with the full suite — three publish actions, the assign-parent action, and five browser panels). The line also appears in %TEMP%\capital\2512\CapitalSystemsArchitect_*.log.

4. Teamcenter types, runTag, and legacyRunTags

Every Teamcenter type the hub creates is config-overridable under teamcenter in config.json — swap them as your BMIDE model evolves, no code change:

The runTag pattern. On a shared instance, runTag prefixes every created item id and name — we burned through T1…T7 proving the pipeline, each round cleanly namespaced and disposable. For production, set it to "". This is not cosmetic: cross-publish nesting resolves parent ids byte-exactly, so a tagged push looks for T1LOG-STGINV and misses the untagged spine node an earlier publish created. legacyRunTags (e.g. ["T7"]) lets production mode adopt items minted under an older test tag instead of re-creating them — active only when runTag is empty.

5. Seeding and bootstrapping a Capital project

Capital seats are populated from generated project XML — either rendered from a live Teamcenter extraction or straight off a store head:

GET /export/capital-xml?project=UAV%20Platform          # from the running hub
py capital_project_xml.py <bundle.json> [<out.xml>] [--dtd <path>] [--include-logic]

The generator enforces the hard-won format rules automatically: UTF-8 without BOM (Capital rejects anything not starting literally with <?xml), a resolvable DOCTYPE from capitalDtdPath, flat folder names, and deterministic baseids derived from TC ids. Two import paths:

6. Patch maps — parentage for delivered files

Files delivered from outside the loop (a customer .prt, a vanilla Capital project) carry no TC_PARENT_ID. Rather than depend on native assignment APIs cooperating, the hub applies a per-domain name→parentId patch map at import time — tc-service\patch-maps\parentid-patch.<domain>.json:

{
  "_comment": "fuel domain — nests delivered equipment under the spine",
  "Fuel Pump":         "LOG-STGINV",
  "Reservoir":         "LOG-STGINV",
  "Capacitance Probe": "LOG-INDINV"
}

Semantics: applied after merge-preserve and auto-enrichment, fills only missing parentIds (an engineer's explicit choice always wins), matches by name then id case-insensitively, skips _-prefixed keys as comments, and is re-read on every import — extend a map with no service restart. parentPatchDir in config.json relocates the directory. If the native path works, the patch is a no-op; if it doesn't, everything still nests correctly.

7. Final verification pass

Run this top to bottom on any fresh environment. Each step reproduces a behaviour we have proven live on Capital 2512 + Teamcenter 2506.