Facade clients (beta)

Beta Preview

The facade clients Istari, IstariIntegrations and IstariAdmin are in beta in istari-digital-client 14.0.0. Their API may change between releases without a deprecation cycle. For production code that cannot absorb a breaking change, use Client and V3Client.

The facade clients are a simpler way to call the Istari Digital Platform from Python. They ship in the same istari-digital-client package as Client and V3Client.

Each facade client groups its methods by the kind of object they act on. istari.resources holds the Resource methods, istari.systems the System methods, and istari.jobs the job methods. Each of these attributes is a manager: an object that holds the methods for one kind of platform object. You call a method on the manager, for example istari.resources.create() or istari.systems.get().

A manager picks which platform API to call for you. You never choose between Client and V3Client methods, and your code stays the same when the platform moves a feature to a newer API.

The facade clients take the same Configuration as Client and V3Client, so one script can use both.

Three facade clients

The facade has three clients, one for each kind of work. They are separate from the stable Client and V3Client; Which client to use compares all five.

Client	Who it is for	Managers
Istari	Application code and everyday work on Resources, Systems and jobs	resources, systems, jobs, credentials, libraries
IstariIntegrations	Module authors, agent operators, the Integrations SDK and the stari CLI	agents, agent_pools, modules, tools, functions, function_auth_secrets, operating_systems
IstariAdmin	Tenant and platform administration	users, tokens, keys, identity, infosec, tenants, scs, usage

Import all three from istari_digital_client. On this page, istari, integrations and admin are instances of Istari, IstariIntegrations and IstariAdmin.

What's in this section

Each page lists one domain's managers and methods. Signatures and parameters are in each method's docstring, for example help(istari.resources.create).

Page	Managers
Resources	istari.resources
Systems	istari.systems
Jobs and credentials	istari.credentials, istari.jobs
Packages and libraries	istari.libraries
Agents, modules and tools	integrations.agent_pools, integrations.agents, integrations.function_auth_secrets, integrations.functions, integrations.modules, integrations.operating_systems, integrations.tools
Administration	admin.identity, admin.infosec, admin.keys, admin.tenants, admin.tokens, admin.usage, admin.users
Identity administration	admin.identity, in full detail
Secure Connections	admin.scs

Construct and close a client

Configuration() reads the key from the environment, the same way as SDK setup. Build it once, then open the client in a with block:

from dotenv import load_dotenv
from istari_digital_client import Configuration, Istari

load_dotenv()  # copies .env into the environment

config = Configuration()

with Istari(config) as istari:
    resource = istari.resources.create("wing.stl", "model", description="FEA model")
    print(resource.resource_id)

The .env names for the key are on Credentials. Each client owns an HTTP connection pool. The with block releases it on exit; outside a with block, call istari.close() when you are done. IstariIntegrations and IstariAdmin work the same way.

Methods on every facade client

Each facade client also has these methods. The examples use istari; integrations and admin have the same ones.

Method	What it does
istari.close	Release the HTTP connection pool
istari.liveness	Check that the platform API is up
istari.readiness	Check that the platform is ready to serve requests

Working with facade clients

These conventions apply to all three facade clients.

Method names

Most managers use the same method names: list, get, create, update (on objects you can change), and archive / restore. Archiving hides an object without deleting it, and restore brings it back. A few methods use the platform's own verb instead, such as integrations.agents.register().

Methods on returned objects

create and get return objects such as Resource, System, Branch, Job and ChangeRequest. Each object keeps a link to the client that returned it, so the next step is a method on the object rather than another manager call:

with Istari(config) as istari:
    # resource_type is "model", "artifact" or "file"
    resource = istari.resources.create("wing.stl", "model", description="FEA model")

    job = istari.jobs.create(
        resource_id=resource.resource_id,
        function="@istari:extract",
        tool_name="siemens_nx",
        tool_version="2506",
    )
    status = job.poll(timeout=600)  # "Completed", "Failed" or "Canceled"

    system = istari.systems.create(name="Aircraft", description="Top-level system")
    baseline = system.baseline_branch()
    feature = system.create_branch("feature-x", from_branch=baseline)
    feature = feature.commit(add=[resource], folders={resource.file_revision_id: "10-Model"})
    feature.create_change_request(baseline, title="Add wing model").merge()

• job.poll() checks the job every 5 seconds until it finishes, and returns the final status. It raises TimeoutError if timeout seconds pass first; with no timeout, it waits indefinitely.
• branch.commit() returns a new Branch that points at the commit, so assign the result before you use the branch again. add takes Resources or revisions. folders maps each added revision id to a folder name. Branching and change requests and Folders in a System cover both.
• merge() raises ConflictError when either branch changed after the change request was opened. Pass check_only=True to test a merge without running it.
• Objects also carry methods for sharing, tagging and reading content, such as resource.create_access(subject_id=..., relation="editor"), resource.add_control_tags([...]), resource.assign_infosec_level(...) and resource.read_text().

An object loses its link to the client when you copy it with copy.deepcopy() or pickle it. Calling one of its methods then raises DetachedInstanceError. Fetch it again from its manager, for example istari.jobs.get(job_id).

Paged results

Most list methods return a Page:

• A for loop or list(page) returns every item, fetching the next page as it goes. That is one request per page, which can be slow on a large collection.
• .items holds the current page only, and .total the full count when the platform reports one.
• page.take(n) returns up to n items and stops fetching once it has them. page.first() returns the first item, or None when the page is empty.
• You cannot index a page (page[0]); use first() or .items[0].

for resource in istari.resources.list(type_name=["model"]):
    print(resource.name)

latest_jobs = istari.jobs.list(size=10).take(10)  # one request

A few list methods return something other than a Page, so first(), take() and automatic paging do not apply:

• A plain list: admin.users.list(), admin.identity.tenants.list(), admin.infosec.list_levels() and istari.libraries.members.list().
• One page of tenants: admin.tenants.list(page=..., size=...) returns a single PageTenant. Read .items, and request the next page until it reaches .pages.
• A principal and its keys: admin.keys.list() and admin.identity.keys.list() return PrincipalKeys. Iterate over .keys.

Errors

Every facade method raises a subclass of IstariError when it fails, so one except clause covers them all. Client and V3Client raise ApiException instead.

• When the platform answers with an HTTP error, the exception is a subclass of APIStatusError with a status_code: BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, ValidationError, RateLimitError or InternalServerError.
• APIConnectionError means the request did not reach the platform, for example a network failure or a timeout.

from istari_digital_client import NotFoundError

try:
    resource = istari.resources.get(resource_id)
except NotFoundError as error:
    print(error.status_code, error)

When you pass a file id where a Resource id is expected, the manager looks up the Resource and retries for you. Other wrong ids, such as a revision id, come back as PermissionDeniedError rather than NotFoundError, so check which id you passed before you treat the error as missing access.

What still needs Client or V3Client

These areas have no facade manager, or only part of the workflow. Build a Client or V3Client from the same Configuration for them.

Area	On the facade in 14.0.0	Use instead	Reference
Inbox and notifications	—	V3Client: list_inbox_items, update_inbox_item, bulk_action_inbox_items, list_notifications	Notifications
AI chat and LLM configuration	—	V3Client: create_ai_conversation, append_ai_conversation_message, ai_config_*	AI chat
Search and favorites	branch.search() and the filters on resources.list	V3Client: search, list_suggested_items, favorite_resource, list_favorites	Search and favorites
Folder layout	branch.commit(folders=...) places the Resources a commit adds	Client: list_folders, and create_configuration with folder_path to rewrite the whole layout	Folders in a System, Systems API — Folders
Snapshots and configurations	Branches and commits	Client: list_snapshots, create_snapshot, compare_snapshots, list_system_configurations, update_tag	Systems API
Control tag catalog	Add, remove and list tags on a Resource	Client: create_control_tag, list_control_tags, update_control_tag, and tagging users	Access control — Control tags
Bulk and cross-tenant sharing	create_access, update_access, remove_access, list_access on Resource, System, Job	Client: bulk_create_access, create_access_by_email_for_other_tenants	Access control — Sharing
Infosec platform settings	Levels on a Resource or System; admin.infosec	Client: get_platform_infosec_settings, enable_platform_infosec_settings	Infosec levels
Job assignment and pool membership	agents.available_jobs, agent_pools create to restore	Client: remove_job_assigned_agent, update_agent_pool_agent, list_agent_pool_agents	Jobs API, Agent pools
Connected sources and connections	resources.get_connection; secure-connection remotes on admin.scs	V3Client: create_connected_source, list_connections, sync_connection	Connected sources
Auth integrations and credentials	istari.credentials.list; integrations.function_auth_secrets	Client: list_auth_integrations, create_credential, get_credential_authorize_url	Admin — Auth integrations, Credentials
System webhooks	—	Client: the *_webhooks_* methods	System webhooks
Authors	—	Client: create_author, list_authors, update_author	Agents, modules and tools

System Documents have no method on any client in 14.0.0.

Pages that use the facade

• Folders in a System — commit Resources into folders with branch.commit().
• Python Client 202 — First digital thread — registers a spreadsheet and runs extractions with Istari.
• Admin — users, tokens and auth integrations, with pointers to IstariAdmin.identity.
• Keys — which key methods IstariAdmin.identity.keys replaces.