# Istari Digital — Python Client --- --- slug: /build/python/setup sidebar_label: Setup sidebar_position: 1 --- # Setup `istari-digital-client` is the Python interface to the Istari Digital Platform. This page installs the package and builds a configured `Client` — the entry point for every other example in this section. To create your first System end to end, work through [Python Client 201 — Your first System](../tutorials/automate/201-first-system.md) and come back here when you start writing your own code. ## Requirements - Python 3.10 or newer. Supported versions are listed on the [PyPI project description](https://pypi.org/project/istari-digital-client/#description). - `istari-digital-client` **13.2.1**, the Python client for Istari Digital Platform **2026.09**. The examples below install that version. Each release lists its client under **SDK Clients** in the [release notes](/releases/2026-09-01-Release). If you are not sure your instance is 2026.09, see [Match the client to the registry](#match-the-client-to-the-registry). - A **Key** from the web app — see [Credentials](#credentials) below. ## Installation Pick whichever fits how you already work. All three install the same package into an isolated environment. **pip, in a virtual environment:** ```bash python -m venv .venv && source .venv/bin/activate pip install "istari-digital-client==13.2.1" ``` **[uv](https://docs.astral.sh/uv/), in a virtual environment:** ```bash uv venv && source .venv/bin/activate uv pip install "istari-digital-client==13.2.1" ``` **uv, as a project** — when the code is a repository rather than a one-off script: ```bash uv init my-analysis && cd my-analysis uv add "istari-digital-client==13.2.1" uv run python analysis.py ``` `uv add` records the dependency in `pyproject.toml` and pins it in `uv.lock`, so a colleague reproduces your environment with `uv sync`. `uv run` executes in that environment without activating it. On Windows, activate with `.venv\Scripts\activate`. ## Credentials In the web app, open **avatar → Settings → Developer**. Click **Generate Key**, then **Download credentials** — the credentials file is shown once. It is JSON with `clientId`, `keyId`, and `key` (the private key). The dialog names it `istari-credentials.json`. Copy the **API URL** from the **Endpoints** section on the same page. Details: [Developer Settings — Keys](../users/user-guide/settings.md#developer-settings--keys). Put both in a `.env` file beside your script: ```text ISTARI_DIGITAL_API_URL= ISTARI_CLIENT_IDENTITY_SERVICE_SECRET_FILE=/absolute/path/to/istari-credentials.json ISTARI_DIGITAL_IDENTITY_SERVICE_ENABLED=true ``` Note the `ISTARI_CLIENT_` prefix on the file path — it is the only name the client reads for the credentials file. With that path and `ISTARI_DIGITAL_API_URL` set, Key authentication turns on even when `ISTARI_DIGITAL_IDENTITY_SERVICE_ENABLED` is absent. The sample sets it to `true` so the choice is explicit. Set it to `false` to keep a personal access token while a key file is also configured. Keep `.env` and the credentials file out of git, prompts, and chat logs. ## Initialize the client `Configuration()` reads those names from the environment, so the credential stays out of your code: ```python from dotenv import load_dotenv from istari_digital_client import Client, Configuration load_dotenv() # copies .env into the environment client = Client(Configuration()) ``` `python-dotenv` installs with the client, so there is nothing else to add. Point `load_dotenv("istari.env")` at another filename when you already keep credentials elsewhere — the tutorials use `istari.env`. ### Passing the values in code Constructor arguments override the environment. Use them when the values come from a secret manager, or when one process talks to more than one instance: ```python from istari_digital_client import Client, Configuration client = Client(Configuration( digital_api_url="https://api.your-instance.istari.app", identity_service_secret_file="/absolute/path/to/istari-credentials.json", identity_service_enabled=True, )) ``` > Identity Service secrets should only be used when the Identity Service is [enabled](../icbs-install/03-control-plane/10-identity-service/01-Install-and-Configure.md). ### Personal Access Tokens :::warning Deprecated PATs are deprecated as of the July 2026 release and have been superseded by Keys. Support for PATs will be removed from the platform in a future release. Which change matches your script is on [Move a Python script from a PAT to a key](./move-from-pat-to-key.md). The CLI exchange itself is [PAT → Key Exchange](../icbs-install/05-CLI/04-exchanging-pat-for-key.md). ::: A PAT uses two names instead of the three above — `ISTARI_REGISTRY_URL` and `ISTARI_REGISTRY_AUTH_TOKEN` in `.env`, or the matching arguments: ```python client = Client(Configuration( registry_url="https://your-instance.istari.digital", registry_auth_token="your-personal-access-token", )) ``` The **Registry URL** is in the **Endpoints** section of Developer Settings; see [Personal Access Tokens](../users/user-guide/settings.md#developer-settings--personal-access-tokens) for the token itself. ## Next steps - [Patterns](./02-patterns/index.md) — the calls behind common workflows. - [Keys](./api_reference/14-keys.md) — turn a personal access token into a key file, or list and revoke keys, with `client.keys`. - [Branching and change requests](./04-branching.md) — commit Resources to a branch and merge a change request. - [Folders in a System](./06-folders.md) — arrange a System's tree from Python. - [V3Client quick start](./v3/01-quick-start.md) — the unified resource API. ## Match the client to the registry This page installs `istari-digital-client` **13.2.1** for Istari Digital Platform **2026.09**. Use the commands in [Installation](#installation) when your instance is that release. If you are not sure, run [check-registry-readiness.py](pathname:///quickstart/check-registry-readiness.py). It reads the registry version from your instance and prints the `istari-digital-client` pin that matches it. Create the `.env` file in [Credentials](#credentials) first. The script reads that file. ```bash python -m pip install pyjwt python -c "import urllib.request; urllib.request.urlretrieve('https://docs.istaridigital.com/quickstart/check-registry-readiness.py', 'check-registry-readiness.py')" python check-registry-readiness.py ``` The first two lines of output are `registry_version=` and `sdk_version=`. Install the version printed after `sdk_version=`. A Key is the credential the script uses: `ISTARI_DIGITAL_API_URL` and `ISTARI_CLIENT_IDENTITY_SERVICE_SECRET_FILE` in `.env`. PyJWT is required for a Key. A personal access token also works when the Key file is unset: set `ISTARI_REGISTRY_URL` and `ISTARI_REGISTRY_AUTH_TOKEN` in the same `.env`. The script prints the versions only. The Key and the token stay in `.env`. --- --- slug: /build/python/patterns/workflows/sequential-pipeline sidebar_label: "Sequential pipeline" --- # Sequential Pipeline Chain multiple operations in order within a single engineering tool session so that each step sees the previous step's changes. ## When to use Use a sequential pipeline when you need to run several functions on the same model in a defined order — for example, update parameters and then extract geometry from the modified state. Because all steps execute inside a single tool session, changes are carried forward automatically and the model file is transferred and opened only once. ## How it works The sequential pipeline is implemented as a module function (`@istari:batch_execute`) built into supported integrations. The agent opens the model once, runs each step in order within that session, and aggregates all outputs into the job result. This avoids the overhead of uploading, downloading, and re-opening the model between steps. | Supported integration | | ----------------------- | | `dassault_3dexperience` | | `ptc_creo_parametric` | | `siemens_nx` | ### Input structure | Field | Type | Description | | ------------------- | ---------------- | ----------------------------------------------------------------------------- | | `func_list` | Array of objects | Ordered list of steps to execute | | `func_list[].name` | String | Canonical function name (e.g. `@istari:extract`) | | `func_list[].input` | Object | Step-specific parameters. Use `{}` when the step requires no extra parameters | ### Behaviour - Steps run in order. Model state carries forward — modifications from step N are visible to step N+1. - The model file is provided to the pipeline; individual steps do not need it in their `input`. - Step input values are bare (e.g. `"output_format": "step"`). No `{"type": "parameter", "value": ...}` wrapper is needed. - All step outputs are aggregated into a flat list returned by the job. ## Examples Update a wing length parameter and then extract from the modified 3DExperience model, all in one job: ```python job = client.add_job( model_id=model.id, function="@istari:batch_execute", tool_name="dassault_3dexperience", tool_version="2023x", operating_system="Windows 11", parameters={ "func_list": [ {"name": "@istari:update_parameters", "input": {"parameters": {"wing_length": "20m"}}}, {"name": "@istari:extract", "input": {}}, ] }, ) ``` Run all extraction functions on a Siemens NX model in a single session: ```python job = client.add_job( model_id=model.id, function="@istari:batch_execute", tool_name="siemens_nx", tool_version="2506", operating_system="Windows 11", parameters={ "func_list": [ {"name": "@istari:extract", "input": {}}, {"name": "@istari:extract_geometry", "input": {"output_format": "step"}}, {"name": "@istari:extract_parameters_full", "input": {}}, {"name": "@istari:update_parameters", "input": { "parameters": {"CogsCount": "15", "HoleDiam": "200"}, }}, ], }, ) ``` :::tip The `parameters` value can be stored in a separate JSON file for readability. Pass the file path via `parameters_file` instead of inline `parameters`. ::: ## Composing with other patterns A sequential pipeline can be used as the operation inside a [Parameter study](./02-parameter-study.mdx), letting you run a multi-step workflow for each set of variable values. See [Parameter study — Composing patterns](./02-parameter-study.mdx#composing-patterns) for an example. --- --- slug: /build/python/patterns/workflows/parameter-study sidebar_label: "Parameter study" --- # Parameter Study Run the same operation across a set of variable values to explore a design space automatically. ## When to use Use a parameter study when you need to repeat a function for multiple configurations — for example, sweeping a dimension across a range of values and collecting outputs for each. Because all iterations execute inside a single tool session, the model is transferred and opened only once, and the module handles substitution and iteration internally. ## How it works The parameter study is implemented as a module function (`@istari:variable_sweep`) built into supported integrations. You define one operation and a set of variables; the agent opens the model once and runs the operation for each combination, substituting `$varName` placeholders on every iteration. | Supported integration | | ----------------------- | | `dassault_3dexperience` | | `siemens_nx` | ### Input structure | Field | Type | Description | | ---------------- | ------ | ------------------------------------------------------------------- | | `function` | Object | The operation to repeat | | `function.name` | String | Canonical function name (e.g. `@istari:update_parameters`) | | `function.input` | Object | Operation parameters, optionally containing `$varName` placeholders | | `variables` | Object | Map of variable names to arrays of values | ### Behaviour - Use `$varName` placeholders anywhere in the operation input. On each iteration the placeholder is replaced with the corresponding value from the `variables` map. - Multiple variables can be swept simultaneously — all arrays must be the same length. Values are zipped by index (iteration 0 uses index 0 from every array, iteration 1 uses index 1, etc.). - Each iteration produces its own set of outputs, all aggregated into the job results. ## Examples Sweep a gear count parameter across four values on a Siemens NX model: ```python job = client.add_job( model_id=model.id, function="@istari:variable_sweep", tool_name="siemens_nx", tool_version="2506", operating_system="Windows 11", parameters={ "function": { "name": "@istari:update_parameters", "input": {"parameters": {"CogsCount": "$CogsCount"}}, }, "variables": {"CogsCount": ["8", "12", "16", "20"]}, }, ) ``` ## Composing patterns A parameter study's operation can itself be a [Sequential pipeline](./01-sequential-pipeline.mdx), letting you run a multi-step workflow for each set of variable values. Sweep a wing length variable across four values. On each iteration, update the parameter and then export geometry — both within the same tool session: ```python job = client.add_job( model_id=model.id, function="@istari:variable_sweep", tool_name="dassault_3dexperience", tool_version="2023x", operating_system="Windows 11", parameters={ "variables": {"wing_len": ["10m", "15m", "20m", "25m"]}, "function": { "name": "@istari:batch_execute", "input": { "func_list": [ {"name": "@istari:update_parameters", "input": {"parameters": {"wing_length": "$wing_len"}}}, {"name": "@istari:extract_geometry", "input": {"format": "stp"}}, ] } } }, ) ``` Variable values are referenced with a `$` prefix (e.g. `$wing_len`) and can appear anywhere within the nested function input. --- --- slug: /build/python/patterns/workflows sidebar_label: "Overview" --- # Workflow Patterns Workflow patterns coordinate multiple operations within a single engineering tool session. Because the model is transferred and opened only once, all steps share the same session state — changes from one step are immediately visible to the next, and no intermediate upload or download is needed. These patterns are implemented as module functions built into supported integrations. The agent handles session management, step sequencing, and output aggregation internally. | Pattern | Module function | Purpose | | --------------------------------------------------- | ------------------------ | --------------------------------------------------------------------- | | [Sequential pipeline](./01-sequential-pipeline.mdx) | `@istari:batch_execute` | Chain operations in order; each step sees the previous step's changes | | [Parameter study](./02-parameter-study.mdx) | `@istari:variable_sweep` | Run the same operation across a set of variable values | These patterns can be composed — for example, a parameter study where each iteration runs a sequential pipeline. --- --- slug: /build/python/patterns sidebar_label: "Patterns" --- # Patterns A pattern is a reusable solution to a recurring problem. In the context of the Istari Digital Platform, patterns capture proven approaches for connecting engineering data, automating workflows, and building reliable digital threads with the Python client. Each pattern describes **when** to use it, **how** it works, and provides ready-to-use SDK examples. ## Categories ### [Workflows](./01-workflows/index.md) Patterns for composing multiple operations into coordinated workflows — running steps in sequence, sweeping parameters across design variants, or combining both. --- --- slug: /build/python/branching sidebar_label: Branching sidebar_position: 4 title: Branching and change requests --- # Branching and change requests Create **branches**, commit Resource revisions, and open, merge, or close **change requests** with the Istari Digital Python client. Use this when branching and merging are part of an automated pipeline — for example, committing simulation output to a branch and opening a change request for review. For the conceptual model (Resource versions vs System branches), see [Version control](../intro/key-concepts/version-control.md). For the same flows in the web app, see [Branches](../users/user-guide/branches.md). ## Prerequisites - A configured `Client` — see [SDK setup](./01-setup.md). - **Editor** (or above) on the target System. ## Getting a System and its branches Branch operations live on the `System` object. Every System starts with a `baseline` branch: ```python system = client.get_system("26db98...") # your system ID baseline = system.get_branch("baseline") branches = system.list_branches() # all branches except baseline ``` ## Creating a branch Create a new branch off any existing branch to isolate the changes you're making: ```python v2 = system.create_branch("v2", from_branch=baseline) ``` :::note The `add_to_branch` helper commits to working branches; to update `baseline`, merge a change request into it as shown below. ::: ## Committing Resources to a branch Upload each file as a model, then commit its revision to the branch. You can commit several revisions (and Subsystems) in a single commit. `add_model` is deprecated in 13.1.9 and warns. It still returns the `Model` whose `.revision` `add_to_branch` takes. The same upload on `V3Client` is [`create_resource`](./v3/v3-client.mdx#create_resource). ```python render = client.add_model("renders/back.png") bom = client.add_model("bill_of_materials.json") v2 = system.add_to_branch(v2, revisions=[render.revision, bom.revision]) ``` To remove tracked files from a branch, use `system.remove_from_branch()` with the same arguments. Each call to `add_to_branch` / `remove_from_branch` creates one commit: ```python for commit in system.list_branch_history(v2): # newest first, like `git log` print(commit.snapshot_id, commit.created) ``` ## Creating a change request Merge by creating a change request from your working branch (the **source**) into the branch you want to update (the **target**): ```python from istari_digital_client import ChangeRequestCreateRequest response = client.create_change_request( system_id=system.id, change_request_create_request=ChangeRequestCreateRequest( source_tag_id=v2.id, target_tag_id=baseline.id, title="Move v2 to baseline", description="Added the renders and bill of materials", ), ) change_request = response.actual_instance # an OpenChangeRequestResponse print(change_request.change_request_id, change_request.status) # ... OPEN ``` ## Reviewing the changes Get high-level counts first: ```python summary = client.change_request_change_summary( system_id=system.id, change_request_id=change_request.change_request_id, ) print(f"{summary.added_count} added, {summary.removed_count} removed, " f"{summary.changed_count} changed") ``` Then page through the full delta: ```python diff_page = client.change_request_changes( system_id=system.id, change_request_id=change_request.change_request_id, ) for item in diff_page.items: diff = item.actual_instance # a resource diff or a subsystem diff print(diff.diff_type, diff.name) ``` You can filter the delta with `component_type=` (`RESOURCE`, `SUBSYSTEM`, or `ALL`) and `change_types=` (a list of `ADDED`, `REMOVED`, `CHANGED`), using the [`ChangeRequestComponentType`](./api_reference/08-enums.md#changerequestcomponenttype) and [`ChangeRequestDiffType`](./api_reference/08-enums.md#changerequestdifftype) enums. If `has_more` is true, pass `next_cursor` back as `cursor=` and the page's `head_pair_token` back as `x_head_pair_token=` so the next page stays on the same pair of branch heads. ## Merging the change request ```python from istari_digital_client import ChangeRequestMergeRequest merged = client.merge_change_request( system_id=system.id, change_request_id=change_request.change_request_id, change_request_merge_request=ChangeRequestMergeRequest( comment="Approved and merged", ), ).actual_instance print(merged.status) # MERGED ``` `merge_change_request` updates the target branch so that opening it shows the same Resources, versions, folders, and Subsystems as the source branch. When the same text file differs on the two branches, the target shows the source branch's version of that file, as a whole. Work saved only on the target stays in its commit history. The web app walkthrough, with an example, is [What a merge changes](../users/user-guide/branches.md#what-a-merge-changes). To close a change request without merging it, call `update_change_request` with `status="CLOSED"`. The body is a full replacement: omitting `title` or `description` clears that field, so send the current values back when you only want to change the status. `MERGED` is not a valid status here — merging stays on `merge_change_request`. `status="OPEN"` reopens a closed request, with the same replacement rule. ```python from istari_digital_client import ChangeRequestUpdateRequest closed = client.update_change_request( system_id=system.id, change_request_id=change_request.change_request_id, change_request_update_request=ChangeRequestUpdateRequest( status="CLOSED", title=change_request.title, description=change_request.description, comment="Rejected", ), ).actual_instance print(closed.status) # CLOSED ``` ## End-to-end example ```python from istari_digital_client import ( ChangeRequestCreateRequest, ChangeRequestMergeRequest, Client, Configuration, ) client = Client(Configuration( digital_api_url="https://api.your-instance.istari.app", identity_service_secret_file="/absolute/path/to/key.json", identity_service_enabled=True, )) system = client.get_system("26db98...") baseline = system.get_branch("baseline") v2 = system.create_branch("v2", from_branch=baseline) bom = client.add_model("bill_of_materials.json") v2 = system.add_to_branch(v2, revisions=[bom.revision]) change_request = client.create_change_request( system_id=system.id, change_request_create_request=ChangeRequestCreateRequest( source_tag_id=v2.id, target_tag_id=baseline.id, title="Move v2 to baseline", ), ).actual_instance summary = client.change_request_change_summary( system_id=system.id, change_request_id=change_request.change_request_id, ) print(f"{summary.added_count} added, {summary.removed_count} removed, " f"{summary.changed_count} changed") client.merge_change_request( system_id=system.id, change_request_id=change_request.change_request_id, change_request_merge_request=ChangeRequestMergeRequest(comment="LGTM"), ) ``` ## Related reference - [Change requests](./api_reference/12-change-requests.md) — parameter tables for create, list, diff, merge, and close. - [`System` branching methods](./api_reference/models/systems.md#system) — `create_branch`, `add_to_branch`, `list_branch_history`, and related helpers. - [Systems API](./api_reference/04-systems.md) — System, configuration, snapshot, and folder methods on `Client`. --- --- slug: /build/python/connected-resources sidebar_label: Connected resources sidebar_position: 5 --- # Connected resources A **connected Resource** is a link to data in a third-party app ([Google Drive, Microsoft 365, Teamwork Cloud, 3DEXPERIENCE, or Windchill](../integrations/07-Third%20Party%20App%20Integrations/01-app_integrations.mdx#supported-applications)). 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)](./v3/04-connected-resources.md). 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](../users/admin-guide/app-integrations.md) 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](./01-setup.md#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](../users/admin-guide/app-integrations.md). - **A stored credential** — needed to _run jobs_ on the Resource, not to connect it. See [Run jobs on a third-party Resource](#run-jobs-on-a-third-party-resource). - **Host app access** — the agent account must be able to open the external object. See [Connecting files](../integrations/07-Third%20Party%20App%20Integrations/02-connect_files.mdx). ## 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](../users/user-guide/add-resources.md#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](#metadata-extensions)). 3. Call `client.add_model(path=...)`. That call is deprecated in 13.1.9 and warns. [`create_resource`](./v3/v3-client.mdx#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](../integrations/03-Systems%20Engineering/03-dassault_cameo/index.mdx). | | 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](../integrations/02-CAD/03-ptc_creo/index.mdx). | | 3DEXPERIENCE (Enovia) | `.istari_dassault_3dexperience_enovia_metadata` | See [3DEXPERIENCE Enovia](../integrations/03-Systems%20Engineering/05-dassault_3dexperience_enovia/index.mdx). | 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:** ```json { "project_name": "Istari_UAVOne(notional)", "branch_name": "trunk", "version": "11" } ``` **By identifier URI:** ```json { "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: ```python 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` → `/`): ```json { "oid": "VR:wt.epm.EPMDocument:132353" } ``` ```python 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`**: ```python 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](../users/admin-guide/app-integrations.md#how-users-select-a-credential-when-running-a-job). 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](./api_reference/03-jobs.md) and [Python Client 202](../tutorials/automate/202-python-client.md). ## 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](../connect/04-custom-modules/03-authenticating-from-a-module.md), and [Module design patterns](../connect/04-custom-modules/04-design-patterns.md) for how to validate and report on it. ## Related documentation - [App Integrations](../users/admin-guide/app-integrations.md) — connecting an app, sign-in methods, and service accounts - [Resources (key concepts)](../intro/key-concepts/resources.md) - [Models and artifacts](./api_reference/02-files.md) - [Connected resources (V3Client)](./v3/04-connected-resources.md) --- --- slug: /build/python/folders sidebar_label: Folders sidebar_position: 6 title: Folders in a System --- # Folders in a System Arrange the Resources tracked by a System into a tree from Python (`istari-digital-client` 13.2.1). A folder is a path prefix on a **tracked Resource** in a commit, not an object you create: the web app shows the names you typed, and the API stores an encoded path. On 13.0.x, the branch method used below is named `branch.files()` rather than `branch.resources()`; everything else on this page is the same. For what folders are and when a Subsystem fits better, see [Systems and Subsystems](../intro/key-concepts/systems.md#folders-inside-a-system). For the same task in the browser, see [Folders](../users/user-guide/folders.md). ## Prerequisites - A configured `Client` — see [SDK setup](./01-setup.md). - **Editor** (or above) on the target System. ## Path encoding The write form is the System id without hyphens, then one dot-separated segment per folder level. Letters and digits stay literal; every other ASCII character becomes `_XX` — two uppercase hex digits of its code: | You mean | Stored as | | --------------- | ------------------- | | `10-Analysis` | `10_2DAnalysis` | | `tier 1 native` | `tier_201_20native` | | `v1_extracted` | `v1_5Fextracted` | Folder names must be ASCII. A bare `-`, space, or `_` in a segment is rejected. ```python import re def folder_path(system_id: str, *names: str) -> str: """The `<32-hex system id>.