Migrating from Client to V3Client

V3Client introduces a unified Resource abstraction that consolidates the separate model, artifact, file, and document types currently exposed by Client. Resources are differentiated by a resource_type field and share a common lifecycle: create, list, get, archive, restore.

Backwards compatibility

Client and V3Client coexist. Both can be used in the same script — you do not need to migrate everything at once.

Architecture comparison

Existing types via Client

Each type has its own dedicated methods on Client: add_model, list_models, get_model, update_model, archive_model, plus parallel sets for artifacts, files, documents, and comments.

Unified model via V3Client

V3Client exposes a single Resource abstraction with a resource_type discriminator:

Existing type	V3Client resource_type
Model	"model"
Artifact	"artifact"
File	"file"
Document	"document"

Comments are scoped to a resource and managed through create_comment / list_comments / archive_comment / restore_comment.

Every resource has a stable resource ID, an ordered list of revisions, and a content token on each revision.

SDK setup

from istari_digital_client import Configuration, Client, V3Client

config = Configuration(
    registry_url="https://your-instance.istari.digital",
    registry_auth_token="your-personal-access-token",
)

client = Client(config)    # Jobs, agents, systems, access control
v3 = V3Client(config)      # Resources, revisions, comments, relationships

Method mapping

Create a resource

Client

model = client.add_model(
    path="/path/to/wing-stress.stl",
    description="FEA model for wing stress testing",
    version_name="v1.0.0",
)

V3Client

resource = v3.create_resource(
    path="/path/to/wing-stress.stl",
    resource_type="model",
    description="FEA model for wing stress testing",
    version_name="v1.0.0",
)

List resources

Client

models    = client.list_models()
artifacts = client.list_artifacts()
files     = client.list_files()

V3Client

all_resources = v3.list_resources()
models        = v3.list_resources(resource_types=["model"])

Get a resource

Client

model    = client.get_model(model_id="<id>")
artifact = client.get_artifact(artifact_id="<id>")
file     = client.get_file(file_id="<id>")

V3Client

resource = v3.get_resource(resource_id="<id>")

tip

Resource IDs carry over — the same UUIDs used by Client are the resource_id in V3Client.

Upload a new revision

With Client, updating a resource creates a revision implicitly. With V3Client, revisions are created explicitly.

Client

model = client.update_model(
    model_id="<id>",
    path="/path/to/wing-stress-v2.stl",
    description="Finer mesh near leading edge",
    version_name="v2.0.0",
)

V3Client

revision = v3.create_resource_revision(
    resource_id="<id>",
    path="/path/to/wing-stress-v2.stl",
    description="Finer mesh near leading edge",
    version_name="v2.0.0",
)

List revisions

Client has no direct revision-list endpoint. V3Client exposes the full history:

page = v3.list_resource_revisions(resource_id="<id>", size=10)
for rev in page.items:
    print(rev.file_revision_id, rev.version_name, rev.created)

Archive and restore

Client

client.archive_model(model_id="<id>")
client.restore_model(model_id="<id>")

V3Client

v3.archive_resource(resource_id="<id>")
v3.restore_resource(resource_id="<id>")

Comments

Client — comments are a separate top-level resource:

comment  = client.add_comment(resource_id="<id>", path="/path/to/comment.json", description="Review notes")
comments = client.list_model_comments(model_id="<id>")

V3Client — comments are scoped to a resource:

comment = v3.create_comment(resource_id="<id>", path="/path/to/comment.json", description="Review notes")
page    = v3.list_comments(resource_id="<id>")

Relationships (V3Client only)

Relationships link revisions across resources. There is no Client equivalent.

types = v3.list_revision_relationship_types()

v3.create_revision_relationship(
    source_revision_id="<source_id>",
    target_revision_id="<target_id>",
    relationship_type_id="<type_id>",
)

page = v3.list_revision_relationships(
    resource_id="<resource_id>",
    revision_id="<revision_id>",
)

Download a file

Generate a short-lived download URL from the content token:

resource = v3.get_resource(resource_id="<id>")
url = v3._storage_api.generate_download_url(sha=resource.content_token.sha)
print(url.url)

Capabilities only available via Client

Use Client for these — they have no V3Client equivalent yet:

Capability	Client methods
Jobs	add_job, get_job, list_jobs
Agents and pools	register_agent, list_agents, create_agent_pool
Systems and snapshots	create_system, create_snapshot
Modules and functions	list_functions, list_modules
Access control	create_access, update_access
Personal access tokens	create_personal_access_token
Users	list_users, get_current_user
Control tags	create_control_tag
App / auth integrations	create_app_integration, create_auth_integration

Migration strategy

Use V3Client for resource operations (create, list, get, revisions, comments) and keep Client for everything else:

resource = v3.create_resource(
    path="/path/to/model.stl",
    resource_type="model",
    description="My model",
)

job = client.add_job(
    model_id=resource.resource_id,
    function="@istari:extract",
    tool_name="siemens_nx",
    tool_version="2506",
    operating_system="Windows 11",
)

Incremental path:

1. New scripts — use V3Client for resource CRUD; keep Client for jobs, agents, and access control.
2. Existing scripts — migrate resource creation, listing, and download calls to V3Client; leave job and agent logic on Client.
3. Capabilities only on Client — jobs, systems, agents, and access control remain on Client until V3Client coverage expands.

Full method map

Client method	V3Client equivalent
add_model(path=...)	create_resource(path=..., resource_type="model")
add_artifact(model_id=..., path=...)	create_resource(path=..., resource_type="artifact")
add_file(path=...)	create_resource(path=..., resource_type="file")
get_model(model_id=...)	get_resource(resource_id=...)
get_artifact(artifact_id=...)	get_resource(resource_id=...)
get_file(file_id=...)	get_resource(resource_id=...)
list_models()	list_resources(resource_types=["model"])
list_artifacts()	list_resources(resource_types=["artifact"])
list_files()	list_resources(resource_types=["file"])
update_model(model_id=..., path=...)	create_resource_revision(resource_id=..., path=...)
update_artifact(artifact_id=..., path=...)	create_resource_revision(resource_id=..., path=...)
update_file(file_id=..., path=...)	create_resource_revision(resource_id=..., path=...)
archive_model(model_id=...)	archive_resource(resource_id=...)
restore_model(model_id=...)	restore_resource(resource_id=...)
archive_artifact(artifact_id=...)	archive_resource(resource_id=...)
restore_artifact(artifact_id=...)	restore_resource(resource_id=...)
archive_file(file_id=...)	archive_resource(resource_id=...)
restore_file(file_id=...)	restore_resource(resource_id=...)
list_model_comments(model_id=...)	list_comments(resource_id=...)
list_artifact_comments(artifact_id=...)	list_comments(resource_id=...)
add_comment(resource_id=..., path=...)	create_comment(resource_id=..., path=...)
archive_comment(comment_id=...)	archive_comment(resource_id=..., comment_id=...)
restore_comment(comment_id=...)	restore_comment(resource_id=..., comment_id=...)
(no equivalent)	list_resource_revisions(resource_id=...)
(no equivalent)	get_resource_revision(resource_id=..., revision_id=...)
(no equivalent)	create_revision_relationship(...)
(no equivalent)	list_revision_relationships(...)