TeamcenterKnowledge

Skills

Cameo Connector Config

Skill cameo-connector-config. Configure and switch the HCL Cameo Connector for Teamcenter between environments and releases. Covers the fact that an "environment" is 14 (file, key) writes over 11 key names across TWO files that nothing keeps in step (a half-switch logs in fine and sends files to the wrong tier), the Java .properties escaping bug that presents as a missing folder, replace-never-overlay when swapping connector releases, the Cameo profile that must move with it, and the catalogue of errors on this stack that name the wrong cause. Use for any Cameo/Teamcenter connector setup, environment switch, release upgrade, or "it logged in but something is wrong" investigation.

Verified live on Cameo 2024x Refresh3 with connector releases 2506 and 2606, against Teamcenter 2506 (cloud, 25060.0004.0000.2025100200) and Teamcenter 2606 (local VM, 26060.0000.0000.2026052800). Vendor source: the HCLTech Cameo Connector for Teamcenter Installation Guide shipped inside each kit.

The tooling built from this knowledge is CameoTcConfig; its BUILDING.md covers how to rebuild that. This skill is the domain knowledge underneath.

The one thing to know

An environment is not a setting. It is 14 (file, key) writes over 11 key names spread over two files that no installer keeps in step: the authority is Environment.plan() in CameoTcConfig/cameocfg/model.py, which enumerates every write explicitly rather than leaving them implicit.

<cameo>\plugins\CameoTCIntPlugin\conf\cameotcIntegration.properties
%ProgramData%\Siemens\MBSE\bhm\CommonClient.properties
Key File What it decides
TC_SERVER_URL connector where Cameo signs in
AWC_WEBLOGIC_HOST_URL connector the embedded Active Workspace panel
URL client the client library's own copy of the sign-in address
AWC_WEBLOGIC_HOST_**URI** client URI, not URL. Easy to get wrong
BOOTSTRAP_URLS client where model FILES actually go
Transport / TRANSPORT / IS_TCCS both must agree across the two

★★★ The failure this causes does not announce itself. With TC_SERVER_URL pointed at one tier and BOOTSTRAP_URLS at another, login succeeds and file transfer goes somewhere else. Observed live: TC_SERVER_URL on a demo VM while BOOTSTRAP_URLS still read http://saber2:4544, and saber2 was a hosts-file alias for the cloud tier.

CommonClient.properties is the file nobody edits: it is rewritten by the connector at launch, lives outside the Cameo installation, and holds the one setting that decides where files land. Always resolve BOOTSTRAP_URLS to an address and compare it against the sign-in host. An alias reads like a name, and names look interchangeable.

The /tc rule, proven not assumed

TC_SERVER_URL must be the web-tier context root ending at /tc, nothing further. Captured by pointing it at a local listener: the connector sends exactly one request, no prior handshake.

POST /tc/RestServices/Core-2008-06-Session/login   Content-Type: application/xml
<LoginInput group="" locale="en" password="..." role=""
            sessionDiscriminator="TCMEClient" username="..."
            xmlns="http://teamcenter.com/Schemas/Core/2008-06/Session"/>

It appends RestServices/<Service>/<operation> itself, and uses RestServices (XML), not JsonRestServices. A path-less URL makes com.teamcenter.soa.client.Connection return null on every operation. A doubled /tc/tc fails with a message about the server.

★ The guide's examples use port 7001. That is HCL's own example, not a default. Get the port from the tier you are actually pointed at.

Java .properties traps

The connector file is a Java properties file. Three things follow, all seen live.

★★ Directory values MUST be double-backslashed. D:\CameoStagingTemp is read as D:CameoStagingTemp, a drive-relative path that resolves under Cameo's own folder, and export then fails with "system cannot find the path" naming a folder nobody configured.

Detect it by encode(decode(raw)) != raw. Do not look for a backslash in the decoded value: in the broken case the backslash is exactly what went missing, so that check passes on the file it exists to reject.

★ logger.properties is the exception and uses forward slashes.

★ Neither file has a BOM. Writing one makes the first key unreadable, and the connector reports that as a missing setting rather than a broken file. Use [IO.File]::WriteAllText($p,$t,(New-Object System.Text.UTF8Encoding($false))).

★ CREATE_VALUE_PROPERTY_CONFIG is one value spanning ~54 physical lines joined by trailing backslashes. A line-at-a-time editor corrupts it.

★ The shipped key SteretypeNameTrucationLimit is misspelled twice. Correct the spelling and the connector stops reading it.

Swapping a connector release

There is no installer. Per Installation Guide 4.2, installing is a folder copy: drop CameoTCIntPlugin into <cameo>\plugins, then copy lib\Teamcenter_Profile.mdzip to <cameo>\profiles and C:\Users\Public (that path, not Public\Documents).

★★ Replace, never overlay. plugin.xml declares ownClassloader="true" with class-lookup="LocalFirst", so the plugin's own jars win over Cameo's. A jar left behind by an overlay copy is preferred, giving a mixed build that reports the new version number.

★★★ A kit's conf is HCL's own working file, not neutral defaults. The 2606 kit arrived with:

TC_SERVER_URL              https://10.118.58.91:7001/tc     (an HCL address)
LicenseDir                 27057@10.118.58.116              (an HCL server)
STAGING_DIR                C:\apps\bhm\staging              (does not exist)
CameoTCIntImportWorkingDir (blank)
USE_JCEF_BROWSER           true

Launching Cameo on that gives an unreachable licence server, no working directory, and a blank Active Workspace panel. And the licence symptom sends people to the WinNAT fix, which would be the wrong one. Carry every key present in both the old and new conf across; keys only in the new one keep the kit default, which is how a release's genuinely new settings arrive.

★ The Cameo profile must move too, and the releases ship different ones (168,719 bytes for 2506 against 160,328 for 2606). A stale profile shows up as red borders around synced elements, which reads as a problem with the model. Watch for extra copies: one machine had a third, loose in <cameo>\plugins, stale by a whole release.

★ Cameo must be closed. The plugin jars are locked by the running JVM (verified by handle probe). conf\*.properties is NOT locked, which is why an environment switch works with Cameo open and still needs a restart to take effect.

★ Cameo's window belongs to <cameo>\jre\bin\javaw.exe, not cameoea.exe. Detect it by install directory, not process name.

Version compatibility

Two axes, both must hold:

Cameo release      x  connector release   ->  A / P / X from the matrix
connector release  x  Teamcenter release  ->  the connector's certified range

★★ A Cameo family's base row and refresh row carry DIFFERENT support. Cameo 2024x base is certified against connector 2406; the 2024x refreshes are not. Matching on the family alone flips the answer.

★★ The compatibility matrix is the authority; a kit's Installation Guide is not. The 2606 kit's guide claims Teamcenter 2606 / 2512.2604 / 2506.004 / 2412 and Cameo 2024x Golden through Refresh3, all wider than the matrix. Connector 2606 did log in cleanly against Teamcenter 2506 and read that site's customized mapping without complaint, and a full check-out/check-in on Teamcenter 2606 succeeded. None of that makes any of it certified. Record a kit's claim, display it, never let it upgrade a verdict: "certified" is what buys Siemens support when something stops working.

★ Teamcenter's release cannot be read without authenticating. /, /version.json, /tc/version, /manifest.json and the Active Workspace paths all return 404, 403, or a page with no version in it. With a sign-in, the version is in the login response at serverInfo.Version / DisplayVersion; no second call is needed.

★ A version mismatch does not announce itself as a version error. Connector 2506 against a 2606 tier failed with HTTP 405 and a marshalling error, which reads as a wrong address.

The mapping file: not the client's business

A kit ships MAGICDRAW_BHMIntegrationDefinition.xml and the guide (section 7) describes importing it server-side. Do not reason about it from a client, and do not run that import blind.

Measured on one machine: the cloud tier's mapping was site-customized, 1,475,150 bytes with 1,157 references to custom XVE5* types across 57 element mappings and 28 object mappings (a whole L0/L1/L2/L3 Requirement + Paragraph + ReqSpec hierarchy). The kit's file maps those same names to the stock Requirement type. import_file replaces the dataset wholesale, so the documented import would have destroyed the customization and broken requirements integration for everyone on that tier.

Meanwhile the demo VM ran the stock mapping, and Teamcenter 2606 ships its own copy at tc_root\install\mdw0magicdraw\ that is structurally identical to the kit's. Both machines were correct for their site. Whether a given mapping is right cannot be predicted from a client, so a client-side tool should say nothing about it.

Errors that name the wrong cause

On this stack, an error that names its own cause is a hypothesis, not a finding.

Message Actually
HTTP 405, Content is not allowed in prolog connector/Teamcenter release mismatch, or a page where data was expected
"licence problem" at login WinNAT reserving the licence port. net stop winnat && net start winnat as admin. Check netsh int ipv4 show excludedportrange protocol=tcp
"system cannot find the path" at export a single backslash in the properties file
red borders around synced elements a stale Teamcenter_Profile.mdzip
blank Active Workspace panel USE_JCEF_BROWSER=true where the bundled Chromium cannot load (UnsatisfiedLinkError: no chrome_elf). Set it false for WebView2
"Cameo will not license on relaunch" the three ordinary startup modals (License Server localhost:1101, Select Edition, Merge Plugin missing). Not a licence fault
"Communication with Teamcenter server was lost while an operation was in progress. The server has probably terminated abnormally." Teamcenter's OWN fault body, not a broken socket. See below

★★★ That last one is the sharpest example on this stack, and it was settled by capture rather than by reasoning. EXERCISED 2026-08-11, connector 2606 against Teamcenter 2606, every byte relayed and recorded:

POST /tc/RestServices/Core-2008-06-Session/login          -> 200, 1474 ms
     <ns1:LoginResponse> real user, real GroupMember, real UserSession
POST /tc/RestServices/Core-2011-06-Session/getTypeDescriptions -> 500, 347 ms
     <InternalServerException> code 1003
     "Communication with Teamcenter server was lost while an operation was
      in progress.  The server has probably terminated abnormally."

The sign-in SUCCEEDED. The dialog comes from the call after it, and the text is Teamcenter's own message, serialized as well-formed XML and delivered over a perfectly healthy HTTP conversation in 347 ms. Both exchanges recorded complete: nothing reset, nothing truncated, nothing timed out between Cameo and the web tier. The "communication" that was lost is the web tier's connection to its backend tcserver, which is not the connection the client owns.

⇒ Read it as a server-side fault relayed verbatim, and go to the tier's own logs. Do NOT go looking at the network, the address, the transport or the connector configuration, all of which this message invites. The root cause on the run above was a null pointer in an attribute setting deployed by a custom BMIDE template. Nothing client-side could have found that, and every client-side hypothesis it suggested was wrong.

★★ Note the shape, because it generalises: an HTTP 500 carrying a fault body is a successful conversation. A client that renders the fault's message as its own error tells you what the server said, never where it happened.

Capturing the conversation

When the connector's story and the tier's story disagree, stop reasoning and put something on the wire. CameoTcConfig ships this: cameocfg/sniffer.py is a byte-faithful recording relay, driven by five MCP tools (cameo_record_start, cameo_record_status, cameo_record_stop, cameo_captures, cameo_capture_read) or by sniff.py from a terminal.

cameo_record_start "Demo VM"     derives + saves a "(recording)" profile, starts relays
cameo_switch      to that profile          <- both files, all fourteen keys
start Cameo, reproduce the failure         <- settings are read at STARTUP only
cameo_record_stop                          then switch back

★ Why not the connector's own payload dump. CT_REQ_RESP_JSON_DIR and isPayloadRequired record what the connector believed it exchanged, after its own parsing. They cannot separate "the request never left" from "the server reset" from "the server answered HTML", and all three produce the same dialog.

★★ Both addresses must move. A recording profile that relays sign-in while file transfer still goes straight to the tier is the half-switch in another costume, and it also makes the capture silently partial.

★★ An empty capture is not evidence of anything. It means Cameo was not switched, or was not restarted. broken: 0 is equally true of a clean session and of a session that never happened, so read exchanges alongside it.

★ Filter the noise by User-Agent. The Switcher's own health checks poll the same addresses (Python-urllib/…, Core-2011-06-Session/login in JSON). The connector is Apache-HttpClient/4.5.13 (Java/17.x) calling Core-2008-06-Session/login in XML. In one 77-exchange capture, exactly two exchanges were Cameo. Close the Switcher during a capture.

★ Responses are gzipped. Decompress before reading a body, or the XML looks like binary and the first character reads as a decode error.

★ The capture folder holds the sign-in password in clear, because replay needs the exact bytes. It is a credential. Redaction applies to every display path, but never to what is on disk.

★★ Is user logged in: true appears after FAILED and cancelled logins. Never read it as a health signal. The real markers are Login Successfull (sic, two Ls) with a clean loginToTeamcenter(): Finished, versus Login Unsuccessfull.

★★ In C:\Temp\CameoTCIntLogs.log the useful message is on the line AFTER the one tagged ERROR. Content is not allowed in prolog carries no ERROR tag, so matching only error-tagged lines drops it and every diagnosis collapses to a generic failure.

★ Six NullPointerException stack traces appear in a successful checkout. The connector dumps each request/response to the folder named by CT_REQ_RESP_JSON_DIR; unset, it builds a FileOutputStream(null), throws, logs and carries on. Setting that variable is a genuinely useful payload capture, independent of isPayloadRequired/jsonPayloaddir in logger.properties, and only the latter is documented.

Logging: nothing tidies itself

Rotation Deletion
connector logger.properties none at all never
client log4j2.xml by time and size no delete policy

Measured: a 38 MB connector log, and 58 client files totalling 362 MB of which 264 MB came from one logger, com.teamcenter.soa.client.Connection, left at DEBUG. Adding a log4j DefaultRolloverStrategy does not fix accumulation: with a time-based filePattern its maximum applies per rollover period. Sweep by age from outside.

★ Edit log4j2.xml as scoped text, never through an XML parser: a parser round trip reformats the document and drops the Siemens header and the comment block documenting the level names. Scope the SizeBasedTriggeringPolicy substitution to its enclosing <RollingFile>, or you also shrink the traffic appender's deliberately larger limit.

Environment variables (Installation Guide 4.1)

MAGICDRAW_HOME and JRE_HOME are required; three PATH entries are asked for (%JRE_HOME%, ...\CameoTCIntPlugin\lib for FlexLM, ...\sdk\org.jcef\libs for the embedded panel). JAVA_HOME is not in the guide.

★ On a working machine all three PATH entries were absent and the connector ran fine. Treat them as advisory. On a managed corporate machine these are IT's to set, so report and suggest; do not write them.

★ Cameo always runs its own bundled JRE whatever JRE_HOME says. A machine with JRE_HOME on Java 21 while Cameo runs 17 is not broken, but note that the matrix puts connector 2606 on Java 21 while Cameo 2024x ships 17: that is precisely why the matrix marks the pairing Planned.

Order of operations

  • Configuration changes need a full Cameo restart. The connector reads them at startup only, so a change made while Cameo is open shows in the file and not in the product.
  • Put Model greys out after the first push. Synchronize is a PULL that discards local edits. The real push path is Check-Out, edit, Check-In.
  • Without the Merge Plugin loaded, Check-Out offers only "Replace the Project with the Server Version and discard all Local modification". Back up the local .mdzip first; the dialog does not warn in terms anyone recognises as destructive.
  • %TEMP%\MAGICDRAW_BHMIntegrationDefinition.xml is re-read on each Put Model, so a mapping change does not need a re-login even though a properties change needs a restart.

Browsing Teamcenter WITHOUT leaving Cameo - the "parameter palette"

EXERCISED 2026-08-14, Cameo 2024x + connector against vm2606, screenshots taken.

Toolbar button Open Active Workspace in Hosted Window. It docks the real Active Workspace UI as a panel inside the Cameo window - search, Tasks, Recent, the lot. This is the answer to "the parameters live in Teamcenter but I want to see them without leaving Cameo": TC stays the source of truth, AW is embedded. The button sits just right of the Teamcenter toolbar group; hover it and the STATUS BAR shows the tooltip (the tooltip itself does not survive a screenshot). Verified: searching Set Mass returned 985 results, top hit Set Mass Revision: A, a parameter definition authored over SOA minutes earlier.

⚠ Where it is NOT. Four wrong places, all checked:

  • the Teamcenter menu carries only User Profile + Revision Rule, logged in or not. Nothing browsable.
  • the Window menu lists no Teamcenter panel at all.
  • the diagram palette (Selection/Tools/Common -> Package, Block, ...) is SysML element types. Unrelated, and the obvious thing to mistake it for.
  • it is inert until a project is open AND you are logged in to TC. With no project open, the login action is not even offered.

Two traps that make Cameo look broken while you do this

⚠⚠ A queued modal Merge Plugin warning BLOCKS THE EVENT THREAD. The connector raises "the Project Merge plugin is not available or loaded" (disabling Compare with -> PLM Revision, and compare/merge during Check Out and Update). It can sit queued and invisible behind other windows. While it is up, Cameo answers nothing: the Open API bridge times out (measured: a 180 s timeout on the EDT), and any script dispatched meanwhile runs NESTED INSIDE the dialog's event pump. A stack trace showing your script under com.hcl.cameotc.integration.ui2.ImportDialog.onOkClick is that. ⇒ Before concluding the bridge is broken, look for a modal dialog. Dismiss, then retry.

⚠ frame.setAlwaysOnTop(True) suppresses Cameo's own menus. Raising the window that way to screenshot it means the menu bar highlights but no dropdown ever renders, which reads exactly like the click missing. Raise with setExtendedState(MAXIMIZED_BOTH) + toFront() and leave alwaysOnTop FALSE.

⚠ open_application launches a SECOND Cameo rather than activating the running one, and the second instance stops on the FlexNet licence dialog. Raise the existing window through the bridge instead.

Credentials

Automation against Teamcenter authenticates from the DPAPI credential store, never from a pasted secret: a tc-mcp profile names a credFile, and mcp_server._resolve_credentials(pcfg, '', '') hands the value straight to tc_client.connect. The 1,615-definition bulk authoring run on 2026-08-14 ran this way and reported credentialSource: credFile. Verify by EFFECT (the login succeeded) and never print or inspect the resolved value - see [[never-view-decrypted-credentials]].

⚠ That covers the API path only. Cameo's own Welcome to Teamcenter GUI login (User ID / Password / Group / Role / URL) is a human step: it is a password field, and typing into one is out of scope for an agent here. Log in by hand, then drive the hosted AW panel. UNVERIFIED: whether the connector can be configured to take stored credentials and skip that dialog - nobody has tested it, so do not record it as possible or impossible.

Single sign-on: the URL picks the strategy, and one strategy is not installed

Run status: EXERCISED 2026-08-20, Cameo 2024x + connector 2606, tier vm2606 (siemensdc). Read out of the shipped jars with javap, and confirmed against a working-then-broken-then-working login.

Filling in TC_SSO_LOGIN_URL can turn a working sign-in into Error in TcSS. Session Agent could not be started. It did exactly that here, on a tier whose Security Services are genuinely deployed and whose login service genuinely answers. Both facts are true and neither makes SSO usable from Cameo.

SSOClient.getConfiguredSessionInitializer(loginUrl) chooses by the shape of the login URL:

Condition Initializer
config property com.teamcenter.ss.client.SSOSessionInitializer set that class
URL ends /tccs or /tccs/ TccsSessionInitializer
anything else SessionAgentSessionInitializer

Row three shells out to SessionAgentStart.bat, from a directory OsUtil.getSessionAgentPath() reads out of the environment variable TCSSO_SESSION_AGENT_PATH. Unset, or the path missing, and it throws FileNotFoundException("Teamcenter Security Service Session Agent is not installed"), which the connector reports as the dialog above. Neither the variable nor the .bat existed anywhere on the test machine, so this failed every time, deterministically.

Two traps in that one class.

  • DEFAULT_SESSION_INITIALIZER is declared as SimpleSesInitializer and reads like a safe fallback. The selection method never uses it, and that class is not in the jar, so setting the property to it fails with a configuration error rather than helping.
  • TC_SSO_SESSION_FLAG looks like the switch that governs all of this. It is not. The URL alone decides which initializer loads, so clearing the flag while leaving the URL set changes nothing.

Before configuring SSO here, check the two things that decide whether it can work at all, and say which you checked:

[Environment]::GetEnvironmentVariable("TCSSO_SESSION_AGENT_PATH","Machine")
Get-ChildItem "<cameo-root>" -Recurse -Filter "SessionAgentStart*"

Both empty means the only routes are TCCS (TRANSPORT=tccs, IS_TCCS=true, login URL ending /tccs) or installing the Session Agent from a Teamcenter client kit. Neither has been exercised. Until one is, leave TC_SSO_LOGIN_URL, TC_SSO_APP_ID and TC_SSO_SESSION_FLAG empty and sign in with a user name and password.

The diagnostic lesson, which cost more than the fix. The failure was investigated forwards, from the error message down into the bytecode, and that investigation was correct and useless: it explained the mechanism of a fault that should never have been introduced. The question that solved it was "what changed since it worked", answered in one call by comparing the connector properties file timestamp (13:46:10, the moment of the switch) against the first failure (13:47:57) and the last success (11:46:52). When something that worked stops working, read the timestamps before reading the stack.

The value that broke it was recorded as DERIVED, not exercised in two places and applied to live files anyway. Marking provenance is worthless if the marked value still ships: an unexercised value must not be written over a configuration that already works.

Related skills

tc-soa-session, tc-vm-operations, tc-verify-and-cleanup, tc-parameters-units, tc-sso-keycloak.

Generated from skills/cameo-connector-config/SKILL.md in the tc-automation-skills library, which is the canonical copy and also serves as the agent skill set for Teamcenter work.