Connected resources

A connected Resource is a link to data in a third-party app (Google Drive, Microsoft 365, Teamwork Cloud, 3DEXPERIENCE, or Windchill). You register it by uploading a small metadata pointer file with the Python Client. The platform stores the pointer; the engineering bytes stay in the external system until an agent fetches them for a job.

This page follows the order you work in: connect the Resource, run jobs on it, then revise it — using Client (add_model, add_job, update_model). For V3Client, see Connected resources (V3Client).

Connecting the app is an administrator task done once in the web app: they choose its sign-in method (OAuth2 / OIDC or Basic) and create any shared service accounts — see App Integrations in the Administrator Guide. Credentials are then encrypted at rest and delivered to the agent that runs a job automatically; there is no key setup. Connecting the Resources themselves, and running jobs on them, is what you do from Python.

Prerequisites

• Python Client — installed, and a configured client from Setup → Initialize the client. Every example below assumes it.
• App integration (admin) — an administrator connects the target app once in the web app and chooses how people sign in to it. See App Integrations.
• A stored credential — needed to run jobs on the Resource, not to connect it. See Run jobs on a third-party Resource.
• Host app access — the agent account must be able to open the external object. See Connecting files.

Uploaded or third-party: two kinds of Resource

Approach	What you pass to add_model	Where the bytes live
Upload	Path to the real file (.stl, .mdzip, .xlsx, …)	Your data plane
Connect (this page)	Path to a JSON metadata pointer file with a tool-specific extension	The third-party app

Both use the same SDK methods. The filename extension is what tells the platform the Resource is a link rather than an upload.

UI: Resources → Add resources → Connect writes the metadata Resource for you. See Connect an external Resource.

Connect a third-party Resource

1. Create a JSON file that describes the external reference (project id, Windchill OID, SharePoint path, and so on). Field names come from the integration module.
2. Save it with the correct extension (see Metadata extensions).
3. Call client.add_model(path=...). That call is deprecated in 13.1.9 and warns. create_resource with resource_type="model" takes the same pointer path.

The client uploads the pointer as the model revision content. No CAD, PLM, or Office bytes are sent to your data plane.

Metadata extensions

Integration	Base extension	Notes
Teamwork Cloud	.istari_teamwork_cloud_metadata	Often .istari_teamwork_cloud_metadata_mdzip. See Dassault Cameo.
Microsoft 365 / SharePoint	.istari_microsoft_365_metadata	Type suffixes _xlsx, _docx, _pptx, _csv.
Google Drive	.istari_google_drive_metadata_*	Always suffixed: _document, _spreadsheets, _presentation.
Windchill	.istari_windchill_metadata	See PTC Creo.
3DEXPERIENCE (Enovia)	.istari_dassault_3dexperience_enovia_metadata	See 3DEXPERIENCE Enovia.

Confirm the extension and JSON schema on the integration page or module manifest before production use.

Example: Teamwork Cloud (Cameo)

Save a metadata pointer file (for example my_project.istari_teamwork_cloud_metadata_mdzip). Either shape below works:

By project name, branch, and version:

{
  "project_name": "Istari_UAVOne(notional)",
  "branch_name": "trunk",
  "version": "11"
}

By identifier URI:

{
  "identifier": "mdel://ANY?projectID=twcloud:/cf16d07a-9a9f-43dd-8ad9-bee73d9e2581/9903a418-e792-4a69-9add-dc01fe2f57de&serverType=esiserver&serverName=10.30.102.103&projectName=Istari_UAVOne(notional)&elementName=ANY_NAME"
}

Register:

model = client.add_model(
    path="my_project.istari_teamwork_cloud_metadata_mdzip",
    display_name="TWC — Systems model",
)

Example: Windchill (via Creo module)

Save input.istari_windchill_metadata with the oid from the Windchill URL (URL-decode %3A → :, %2F → /):

{
  "oid": "VR:wt.epm.EPMDocument:132353"
}

model = client.add_model(
    path="input.istari_windchill_metadata",
    display_name="Windchill CAD",
)

Run jobs on a third-party Resource

Connecting the Resource needed no credential — the pointer file is only JSON. Running a job does, because this is the point where an agent signs in to the third-party app and fetches the real bytes.

Pick a stored credential, then bind it to the function's authentication input with auth_bindings:

from istari_digital_client import NewCredentialBinding

twc_credential = next(
    c for c in client.list_credentials() if c.name == "My Teamwork Cloud account"
)

job = client.add_job(
    model_id=model.id,
    function="@istari:twc_extract",
    tool_name="dassault_cameo",
    tool_version="2022x Refresh2",
    operating_system="Windows 11",
    auth_bindings=[
        NewCredentialBinding(
            input_name="twc_auth_login",
            credential_id=twc_credential.id,
        )
    ],
)

Set tool_name, tool_version, and operating_system to match the module, exactly as for an uploaded Resource. The two binding fields are:

• input_name — the function's auth_info input, as declared in the module's manifest: twc_auth_login for Teamwork Cloud, windchill_auth for Windchill. Check the function's documentation, or the manifest itself, for the name it expects. A function with more than one authentication input takes one binding per input.
• credential_id — a stored credential you can use. client.list_credentials() returns every credential available to you: your own linked accounts and any organization service accounts. Each has an id, a human-readable name (the name shown under Linked Accounts in the web app), and a status. Pass auth_integration_id to narrow the list to one application.

No secret travels with the submission — a queued job holds no live token. The platform mints a fresh sign-in from the referenced credential only when an agent claims the job, so credentials added or refreshed after submission are picked up automatically. The agent then reads the metadata pointer and fetches the model from the third-party app.

Model.add_job(...) accepts the same auth_bindings argument. This is the SDK counterpart of the web app's credential picker, described in App Integrations.

Use parameters= or parameters_file= as you would for an uploaded Resource, and poll outputs with get_job, get_model, and the artifact helpers — see Jobs and Python Client 202.

Revise a third-party Resource

Connected Resources are versioned like uploaded ones:

• update_model(model_id=..., path=...) — upload an updated metadata pointer.
• Mutating jobs — some functions write back to the external system; the platform records a new revision on the same model id.
• Re-run extract — run another function on the latest revision without creating a new model id.

The model id is stable across revisions. Use model.file.revisions or list_resource_revisions with V3Client.

Using a credential in your own module

If you are building a module that signs in to a third-party app, declare an authentication input and read the delivered sign-in at run time. See Authenticating to external systems from a module, and Module design patterns for how to validate and report on it.

Related documentation

• App Integrations — connecting an app, sign-in methods, and service accounts
• Resources (key concepts)
• Models and artifacts
• Connected resources (V3Client)