TC SOA Session

Skill tc-soa-session. Connect to any Teamcenter web tier over the JSON REST SOA surface (the same one Active Workspace uses). Covers the XSRF bootstrap handshake, the login envelope, the fact that TC returns HTTP 200 on faults, and how to tell a bad credential from a down server-manager pool. Use this before any other Teamcenter automation skill.

One protocol works against every Teamcenter web tier from TC 11 through 2506/2606, with no Siemens client libraries: the JSON REST binding at /tc/JsonRestServices/. A Teamcenter "instance" is nothing but a host plus credentials. Everything that varies per deployment (BMIDE data model, saved queries, release, FMS, auth) is discovered at runtime, not compiled in.

Prefer the existing tooling

Do not hand-roll a login. Two proven clients already exist:

• tc MCP server (tc-mcp/mcp_server.py, registered in .mcp.json as tc; instance-agnostic, one server for any number of tiers via profiles.json). Tools: tc_connect, tc_status, tc_session_info, tc_disconnect, tc_call (run ANY operation), tc_find_items, tc_query_by_type, tc_get_properties, tc_discover_types, tc_search_operations, tc_list_services, tc_service_operations, tc_profiles. This is the default path.
• tc-mcp/tc_client.py as a plain Python module when you need a standalone script (pure stdlib, no requests). from tc_client import connect, call_operation.

Reach for the raw protocol below only when writing a new client or debugging one.

The protocol, exactly

1. GET  <host>/                          -> sets _csrf and XSRF-TOKEN cookies
2. POST <host>/tc/JsonRestServices/Core-2011-06-Session/login
3. POST <host>/tc/JsonRestServices/<Package>-<YYYY-MM>-<Service>/<operation>

Every POST must carry the whole cookie jar and echo the current XSRF token in an X-XSRF-TOKEN header. The token rotates: re-read the XSRF-TOKEN cookie after every call and use the new value on the next one.

Login body (note descrimator, which really is misspelled in the wire contract):

{"header":{"state":{},"policy":{}},
 "body":{"credentials":{"user":"<user>","password":"<pw>",
                        "role":"","group":"",
                        "descrimator":"my-client","locale":""}}}

Every operation body is a {header, body} envelope. Callers usually pass just the operation arguments; wrap them as {"header":{"state":{},"policy":{}},"body":<args>}.

Host string

host is the origin only, e.g. http://tc-web.example.com:8080. Never include /tc; the client appends /tc/JsonRestServices/.... Putting /tc in the host produces a 404 that reads like an unreachable server.

TC returns HTTP 200 on faults. Always.

A failed call is a 200 with a fault body. Detect it by .QName matching /Exception/:

q = data.get(".QName")
if isinstance(q, str) and "Exception" in q:
    msg = data.get("message") or data["partialErrors"][0]["errorValues"][0]["message"]

Also check ServiceData.partialErrors on responses that otherwise look fine: a batch operation happily reports partial success.

A wrapper's envelope is not the payload. tc_client.call_operation returns {ok, status, error, data}. Reading output or queries straight off that envelope yields silent empty results. Always unwrap data, and raise when ok is false.

Cold-start timing

A Teamcenter pool can take 15 to 25 seconds to assign a tcserver on the first login of a session. Later calls are fast. Use a generous timeout (45s) and do not read the first-call latency as a hang.

★★★ Never sweep candidate service paths. A wrong version segment HANGS.

The single most damaging mistake available on this surface, and two sessions have now made it independently.

Guessing an operation by trying Svc-2019-06-X/op, Svc-2020-12-X/op, Svc-2021-06-X/op and so on does not 404 on the misses. A non-existent version segment makes the request hang, and each hung request holds a tcserver slot until it times out. A pool is typically 8 slots. Two such probes saturated a pool and took a tier down for hours; a 24-candidate sweep is the same shape at three times the dose.

The tell: an identical InternalServerException returned by every candidate in a sweep. That is not "none of these exist." That is the pool dying underneath you, and the later candidates never reached a server at all.

Recovery is a service restart on the TC host (tc-vm-operations owns it):

Restart-Service "Teamcenter Server Manager TCDB_PoolA" -Force

⚠ This also poisons your diagnosis afterwards. Once the pool is starved, light reads can still succeed while anything heavy fails, so a passing SOA read looks like proof the tier is healthy when it is not. Both sessions who did this went on to blame a harness or a client defect. A successful SOA read does not clear the tier. It is not a control.

Do this instead: resolve the operation from the catalogue before calling it, never by probing. tc_search_operations and tc_list_services read the local 1,592-operation index, and tc-soa-docs-navigation covers the WSDL route. If the catalogue does not have it, the operation may be template-only and absent from the public SOA kit (AttrTargetMgmtAW-* is the known example). Ask a session that owns that template. One question is cheaper than a tier.

Reading a login failure correctly

Symptom	Meaning	Action
No XSRF-TOKEN cookie from the bootstrap GET	Wrong host/port, or not the web tier	Fix the URL
InternalServerException code 1003 "Failed to get a server assignment" or 1001 "None of the Server Managers are on-line", while the bootstrap GET issued cookies normally	The instance's server-manager pool is down. NOT a bad credential and NOT a struct error	Retry a few times with backoff to rule out a blip, then report it as an instance-side infrastructure gap and stop
A credential fault	Bad user/password/group/role	Fix the credential

Do not keep retrying indefinitely, and do not read a pool failure as "my login struct must be wrong."

Credentials

Passed once at connect and never stored. The MCP reads them from per-profile env vars (TC_<PROFILE>_USER / TC_<PROFILE>_PASSWORD). Never pass a password as an explicit tool argument: it lands in the transcript. The env-var mechanism exists to keep it out.

The setx trap. setx writes the registry, but already-running processes (and every child they spawn, including a "fresh" shell) keep their inherited environment block. After setx, the MCP will still say "missing credentials" until the whole client restarts. To test without restarting, read the registry directly and pass the value in a throwaway process:

[Environment]::GetEnvironmentVariable('TC_SABER2506_PASSWORD','User')

Introspect which Teamcenter you are actually on

Core-2011-06-Session/getTCSessionInfo returns the release, host name, user, group, role, and project list. Run it right after connecting. It is how you learn, for example, that a public gateway and an internal RDP tier are the same site, or that project and workContext are null for a service account (which blocks object creation on sites with use_program_security).

Related skills

tc-soa-payload-shapes (why a well-formed-looking call faults), tc-soa-docs-navigation (finding the real operation), tc-query-discovery (first reads).

---

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