# Istari Digital — User Guide --- --- sidebar_label: Account --- # Account Management Create your Istari Digital Platform account, sign in, and recover access. - [Sign up](./sign-up.md) — Register with SSO or email and set up two-factor authentication. - [Sign in](./sign-in.md) — Log in from a new or existing device. - [Reset password](./reset-password.md) — Recover access if you forget your password. :::tip Already signed in and want to change your name or password? See [Settings](../user-guide/settings.md). ::: --- --- sidebar_position: 3 sidebar_label: Reset password --- # Reset Password Recover access to your account when you have forgotten your password. You reset it from the sign-in screens. 1. Open your company's Istari Digital URL in your browser. 2. Enter your email address and click **Next**. 3. On the password screen, click **Reset Password**. 4. Check your inbox for a password-reset email from Istari Digital (check spam/junk if you don't see it). Click **Reset Password** in the email. 5. Enter and confirm your new password. It must include: - At least 15 characters - Uppercase and lowercase letters - At least one number - At least one special character 6. Click **Next**. A confirmation screen confirms your password has been reset. 7. You will be redirected to the sign-in screen. ## Change your password while signed in On some installations, Settings has a **Password** entry. There, if you are signed in and know your current password, you can change it from **Password** instead. See [Change your password](../user-guide/settings.md#change-your-password). --- --- sidebar_position: 2 sidebar_label: Sign in --- # Sign-in Guide Follow this guide to sign in to the Istari Digital Platform. ## Sign in with email — new device or browser 1. Open your company's Istari Digital URL in Google Chrome. Contact your IT administrator if you don't know the URL. 2. Enter the email address you used to sign up. 3. Click **Next** and enter your password. 4. Enter the 2FA code from your authenticator app before it expires. 5. You are now signed in. ## Sign in with email — existing device 1. Open your company's Istari Digital URL in Google Chrome. 2. Select your existing account from the home screen. 3. Enter the 2FA code from your authenticator app. 4. You are now signed in. ## Sign in with Google SSO 1. Open your company's Istari Digital URL in Google Chrome. 2. Click the **Google** button. 3. Enter your Google email and password, then confirm Google 2-Step Verification. 4. Enter the 2FA code from your authenticator app. 5. You are now signed in. ## You don't have access to Istari yet This page appears when your sign-in worked but you cannot use Istari yet. One sentence below the heading gives the reason: | Message | What it means | | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | "Your sign-in worked, but no account is registered for you here." | Istari has no account for the address you signed in with. See the causes below the table. | | "Your account has been suspended." | An administrator suspended your account. | | "Your tenant has been suspended." | An administrator suspended the [tenant](../../intro/terminology.md#tenant) you belong to. | | "Your account could not be matched to a registered user." | Istari could not match your sign-in to a registered person. | | "Your account is registered but belongs to no tenant yet." | You have an account, but nobody has added you to a tenant. | "No account is registered for you here" has these causes: - You signed in with a different address from the one your administrator added. Sign in again with exactly that address. - Your [sign-in provider](../../intro/terminology.md#sign-in-provider) has not verified the address. Verify it there, then sign in again. - Nobody has added you yet. Ask your administrator. - Your account is not in the group of accounts linked to your tenant at your sign-in provider. Ask your administrator. Below the reason, the page says **Contact your administrator** and shows a contact when your installation names one. The page offers only **Sign out**. 1. Tell your administrator which message you see. Each message has a different fix. 2. Once your administrator has fixed the cause, sign out and sign in again. ## FAQ - **I forgot my password.** Use the [Reset password](./reset-password.md) guide to recover access. - **What is an authentication code?** A time-sensitive code from your authenticator app that verifies your identity. It refreshes every 30 seconds. - **What devices support the authenticator app?** iOS and Android phones, and compatible desktop platforms. --- --- sidebar_position: 1 sidebar_label: Sign up --- # Sign-up Guide Follow this guide to create your Istari Digital Platform account. ## Before you begin 1. **Install Google Chrome** — download and install the latest version. 2. **Install an authenticator app** — on your mobile device, install [Google Authenticator](https://support.google.com/accounts/answer/1066447) or a compatible TOTP app. If you already have one, go to step 3. 3. **Ask your administrator how to get an account** — on some installations, an administrator must add you before you can use Istari. Ask whether to sign up yourself or to have your IT administrator create your account. - If you sign up, use exactly the email address your administrator added, and verify it when asked. - Sign-up can succeed even when something does not match, such as a different or unverified address. Istari then shows [You don't have access to Istari yet](./sign-in.md#you-dont-have-access-to-istari-yet) when you sign in. ## Sign up with SSO 1. Open your company's Istari Digital URL (e.g. `istari.companyname.com`) in Google Chrome. Contact your IT administrator if you don't know the URL. 2. Click the **Google** sign-in button. 3. Enter your Google account email and password, then complete Google 2-Step Verification. 4. Fill in any required registration fields and click **Register**. 5. Accept the **Privacy Policy** and **Terms of Service**. 6. Set up two-factor authentication — choose the **Authenticator App** option and scan the QR code with your app. 7. Enter the generated code before it expires (codes rotate every 30 seconds). 8. A success message confirms your account is ready. ## Sign up with email 1. Open your company's Istari Digital URL in Google Chrome. 2. Enter your email address and click **Next**. 3. Click **Register** and fill out the form. Your password must include: - At least 15 characters - Uppercase and lowercase letters - At least one number - At least one special character 4. Accept the **Terms of Service** and **Privacy Policy**. 5. Enter the verification code sent to your email. Check your spam folder if you don't see it. 6. Enter your password to log in. 7. Set up two-factor authentication — choose the **Authenticator App** option and scan the QR code. 8. Enter the generated code to complete sign-up. ## FAQ - **What is my username?** Your work email address. - **What is an authentication code?** A time-sensitive code generated by your authenticator app. It refreshes every 30 seconds and verifies your identity. - **Can I skip the authenticator app?** No — an authenticator app is required. Contact your IT administrator if you cannot install one. - **What devices support the authenticator app?** iOS and Android phones, and compatible desktop platforms. --- --- title: Administrators --- # Administrators An installation with [tenant management](../../intro/terminology.md#tenant-management) has two administrator roles: | Role | Administers | Who may grant or revoke it | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | **Tenant Administrator** | One tenant: its people, agents and settings | A Platform Administrator, for any tenant; a Tenant Administrator, for their own tenant | | **Platform Administrator** | The whole installation: every tenant, every tenant's people, and who holds the Platform Administrator role, from the [Platform Admin Console](./console.md) | A Platform Administrator | A Platform Administrator can manage any tenant without holding the Tenant Administrator role there. A person can also hold both roles. The Tenant Administrator role applies to the tenant the person belongs to. Your IT administrator [creates the first Platform Administrator](../../icbs-install/03-control-plane/10-identity-service/05-Create-the-First-Platform-Administrator.md) when the platform is installed. ## Grant an administrator role You can make someone a Tenant Administrator only if they belong to a tenant. 1. Find the person: - To grant **Tenant Administrator**: **Users** in the Admin Panel, **Users** in the Platform Admin Console, or the **Members** section of a tenant's page in the Platform Admin Console. - To grant **Platform Administrator**: **Users** in the Platform Admin Console, or the **Members** section of a tenant's page there. 2. Open the row's **⋮** menu and choose **Make tenant admin** or **Make platform admin**. On the person's details page, check the role's box in the **Roles** section instead. 3. The confirmation says what the person will administer. Click **Grant**. If you grant a role to yourself, your access usually updates at once. Otherwise a notification says "Your own roles update on your next sign-in." The row menu items are always named **Make tenant admin**, **Remove tenant admin**, **Make platform admin** and **Remove platform admin**. Confirmations, the **Admin** column and the **Roles** section may show your installation's own names for the roles. ## Revoke an administrator role You cannot revoke your own administrator role. Your own row's menu offers no **Remove tenant admin** or **Remove platform admin**, and your own boxes in **Roles** are disabled. 1. Find the person, as for granting. 2. Open the row's **⋮** menu and choose **Remove tenant admin** or **Remove platform admin**. On the details page, clear the role's box instead. 3. The confirmation says what the person will no longer administer. Click **Revoke**. A Platform Administrator may revoke any other Tenant Administrator, including a tenant's only one. A role can come from your sign-in provider rather than from Istari. The confirmation then says: "This role was imported from the sign-in provider. Removing it here takes effect now, and it stays removed even if the provider still grants it." ## Refusals Where the page can tell in advance that an action would be refused, the action is disabled: - In a row's **⋮** menu, the reason appears under the action's name. - In the **Roles** section, hover over the box to read the reason. Otherwise the refusal appears in the dialog or as a notification. | Situation | Message | What to do | | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------- | | Removing the last active Platform Administrator: revoking their role or their membership, suspending them, or suspending their tenant | "The installation keeps at least one active platform administrator." | Grant the role to someone else first | | Granting a role to a suspended person | "This user is suspended." | Reactivate the person first | | Granting Tenant Administrator in a suspended tenant, from the Platform Admin Console | "This tenant is suspended." | A Platform Administrator reactivates the tenant first | | A Tenant Administrator removing Tenant Administrator from a Platform Administrator | "Only a platform administrator can change a platform administrator." | Ask a Platform Administrator | ## On installations without tenant management If **Settings** > **Admin** > **Users** has an **Invited** tab, your installation does not use [tenant management](../../intro/terminology.md#tenant-management). There, your IT administrator grants administrator access in your sign-in provider, not in Istari. The **Admin** column of the **Users** page only shows who holds it. --- --- title: Agents sidebar_position: 5 --- # Agents Agents are external processes that execute jobs (functions) on behalf of users. This page covers **Agent Management** (agents, agent pools, and pool details) and **personal access tokens** for agent authentication. ## Prerequisites - You need the **Tenant Administrator** or **Platform Administrator** role (on installations without tenant management, organization administrator access from your sign-in provider). The **Agents** entry in the main sidebar appears only for administrators; visiting `/agents` without the role redirects to the home page. - If you do not see **Agents** in the sidebar, ask an administrator; see the [Administrator Guide overview](./index.md#prerequisites). **Navigation:** Click **Agents** in the sidebar (or go to `/agents`) ## Page layout At the top of the Agents page: - **Tabs:** **All Agents** and **Agent Pools** switch the main view. - **Generate Key** or **Generate Token:** one button in the top-right that creates agent credentials. Follow [Generate an agent key](#generate-an-agent-key) when the button is **Generate Key**, and [Generate an agent token](#generate-an-agent-token) when it is **Generate Token**. ## Generate an agent key :::note Availability Follow this section when the top-right button is **Generate Key**. When the button is **Generate Token**, follow [Generate an agent token](#generate-an-agent-token). ::: 1. Click **Generate Key** (key icon) in the top-right. 2. In the **New Agent Access Key** dialog, optionally enter a name in **Agent name (optional)**. Leave it blank and Istari Digital assigns one automatically. Despite its label, the box names the key, not the agent shown under **All Agents**. The platform names the agent unless the agent's configuration sets a name; see [Agent Keys](../../icbs-install/04-Agents/06-Agent-Keys.md). If what you type matches the name of an active agent in your tenant, the dialog warns you but still lets you generate the key. 3. Set **Expiration**. The presets are **30 days**, **90 days**, **180 days**, and **1 year (maximum)** (the default). **Custom date…** requires a date; **Generate** stays disabled until you pick one. 4. Click **Generate**. 5. On the **Agent Access Key Generated** screen, **copy or download the key immediately** — it will only be shown once. The screen also shows **User UUID**, **Tenant ID**, and **Expires**. Click **Copy** to copy. Click **Download credentials** to download it. > **Important:** The key is shown only once. If you lose it, generate a new one. Generating a key here also creates the agent it belongs to. The agent is created in your tenant — see [Agent Multi-Tenancy](../../icbs-install/04-Agents/07-Agent-Multi-Tenancy.md). It appears under **All Agents** once the host it is configured on starts up. If you have CLI access to the agent host, you can do the same thing there with [`stari key create-agent --configure`](../../icbs-install/05-CLI/05-creating-a-new-agent-with-a-key.md), which generates the keypair on the host, creates the agent, and writes the agent's configuration — so the private key is never downloaded or handed off. ## Generate an agent token :::warning Deprecated Tokens are deprecated as of the July 2026 release and have been superseded by Keys. Support for Tokens will be removed from the platform in a future release. See the [PAT → Key Exchange](../../icbs-install/05-CLI/04-exchanging-pat-for-key.md) guide to migrate to keys. ::: 1. Click **Generate Token** (key icon) in the top-right. 2. Enter a **Token name** and click **Generate**. 3. **Copy token** stores the value to the clipboard and closes the dialog. > **Important:** The token is shown only once. If you lose it, generate a new one. ## All Agents tab ### Filters and search | Control | Purpose | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Search by** | **Module** — filter agents by installed module name or version. **Name** — filter by agent display name. | | **Search** | Text field; placeholder depends on **Search by**. | | **Archive status** | **Active**, **Archived**, or **All**. Changing this clears row selection. | | **Pool membership** | **Any**, **In a pool**, or **Not in a pool**. | | **Organization** | Shown only when more than one tenant is visible to you, as it is to a Platform Administrator. On installations without tenant management it is shown when you belong to several organizations. Pick one, or **All organizations**. | When a search is active, the table loads additional pages automatically so results are not limited to the first page only. ### List refresh When data is loaded, a line shows **Updated** with the last refresh time. ### Status badges Each agent displays a color-coded status badge: | Color | Meaning | Examples | | ----------- | ----------------- | ---------------------------------------------- | | **Green** | Healthy / idle | Idle, Completed, ExecutionSuccess | | **Yellow** | In progress | Running, ExecutingJob, UpdatingModule, Claimed | | **Red** | Error or canceled | Any "Failed" status, Unknown, Canceled | | **Neutral** | Other | Any status not in the above groups | The **Last updated** column shows the timestamp for the current status. ### Column sorting Sortable columns (click header): **Agent Name**, **Status**, **Last updated**, **Version**, **Host OS**, **Last Restarted**. Checkbox, **Installed Modules**, **Pools**, and actions are not sortable. ### Agents table columns | Column | Description | | --------------------- | -------------------------------------------------------------------------- | | _(checkbox)_ | Select rows for bulk actions. | | **Agent Name** | Display name; agent ID below with copy control. | | **Status** | Colored badge (see above). | | **Last updated** | Time for current status. | | **Version** | Agent software version. | | **Host OS** | Operating system. | | **Last Restarted** | Last restart time, or **Unknown**. | | **Installed Modules** | Module chips; popover for name/version; overflow as **+N more**. | | **Pools** | Pool name badges for pools this agent belongs to; overflow as **+N more**. | | **⋯** | Row actions. | If more agents exist, use **Load more** at the bottom of the table. ### Agent detail panel 1. Click a row (not on links, checkboxes, or menus) to open an **agent detail** area. 2. The detail UI opens in a **resizable panel at the bottom** of the page (you can drag the splitter or collapse it). The panel header shows name, status badge, OS, and version, and a close control. | Tab | Contents | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Modules & Functions** | For each installed module: name, version, install time when known, and a list of **catalog functions** (display names) supported for that module version. | | **Modules History** | Timeline of module install/update/remove events. | | **Status History** | Timeline of status changes. | | **Access keys** | List of keys registered for the agent. Click **Revoke key** next to a key to disable it immediately. | :::note Availability The **Access keys** tab appears on the agent detail when the Identity Service is [enabled](../../icbs-install/03-control-plane/10-identity-service/01-Install-and-Configure.md) for your deployment and the agent records who created it. If it is missing, ask your IT administrator. ::: ### Bulk actions (selected agents) When at least one row is selected: - **Create New Pool** — Opens **Create Agent Pool**; after the pool is created, selected agents are added to it (with progress and toasts). - **Add to Pool…** — Adds all selected agents to an existing pool. - **Clear selection** — Clears checkboxes. ### Archive or restore an agent 1. Open the **⋯** menu on the row. 2. Choose **Archive Agent** or **Restore Agent** (restore appears when the agent is archived). 3. Confirm if prompted. Archived agents no longer receive job assignments. ## Agent Pools tab Layout: **pools list** on the left, **pool detail** on the right. Click a pool row to select it and load the detail pane. ### Pools list controls - **Search pools...** — Filters pools by name. - **Status filter:** **Active**, **Archived**, or **All**. - **New Pool** — Opens **Create Agent Pool** (name and description). Sortable columns include **Pool Name** and **Created**; **Agents** and **Users** counts are not sortable. Use **Load more** when the list is paginated. ### Pool table columns | Column | Description | | ------------- | ---------------------------------------------------------- | | **Pool Name** | Click name to select pool without toggling row focus. | | **Agents** | Count of agent memberships. | | **Users** | Count of user memberships. | | **Created** | Creation time. | | **⋯** | **Edit**, **Archive** or **Restore** (for archived pools). | ### Pool detail pane When a pool is selected, the right side shows the pool name and description and four tabs: | Tab | Purpose | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Overview** | Summary counts (agents, users, unfinished jobs) and **module coverage** across agents in the pool (module/version, how many agents provide it, function counts from the catalog). | | **Agents** | Agents in the pool; clicking an agent can open the same bottom **agent detail** panel as on **All Agents**. | | **Users** | Users assigned to the pool. | | **Jobs** | Jobs associated with the pool. | ### Create or edit a pool - **Create:** **New Pool** (pools view) or **Create New Pool** (bulk selection on **All Agents**). Dialog title **Create Agent Pool**; fields **Name** (required) and **Description**; submit creates the pool. - **Edit:** **⋯** → **Edit** on a pool row. Dialog title **Edit Agent Pool**; update name/description. ### Archive or restore a pool From the pool row **⋯** menu: **Archive** or **Restore** for archived pools. Confirm if the app asks for confirmation. --- --- title: AI Models sidebar_position: 13 --- # AI Models AI Models registers the LLM endpoints the organization can use and the model configurations approved on each one. **Navigation:** avatar > **Settings** > **Admin** > **LLMs and AI Instructions**, **LLMs** tab (or go to `/admin/ai`) The page heading is **Endpoints and Models**. ## Identical tool-call loop guard **Identical tool-call loop guard** is a cluster-wide limit: how many identical tool calls (the same tool and the same arguments) an agent may make before its loop is stopped. It applies to every model. Change the number and click **Save**. A toast confirms **Loop guard saved.** ## Add an endpoint 1. Click **Add endpoint**. 2. In the **Add endpoint** dialog: - **Host** — pick a host already provisioned for this deployment. You do not type the URL or a credential. The list is empty until a host has been provisioned. - **Name** — a label for this endpoint (for example, `GenAI.mil gateway`). - **Enabled** — turn the endpoint off to keep it registered without using it. 3. Click **Add endpoint**. A toast confirms **Endpoint added.** Editing an existing endpoint confirms **Endpoint saved.** The same host can back more than one endpoint. When it does, the host label is disambiguated. An endpoint card shows the name, the host, and a **Disabled** badge when the endpoint is off. Use the pencil to open **Edit endpoint**, or the trash icon to delete it. Deleting asks **Delete {name}?** and, after you confirm, toasts **Deleted {name}.** Deleting an endpoint also removes every model configured on it. ## Add a model On an endpoint card, click **Add model**. In the **Add model** dialog: - **Configuration name** — the label people see (for example, `Gemini 3.6 Flash (Path B)`). The same model can be added more than once with different delivery settings. - **Model ID** — the identifier passed to the LLM client (for example, `gemini/gemini-3.6-flash`). The provider is inferred from this identifier. - **Path** — URL path appended to the endpoint's host (for example, `/v1`). The dialog shows the effective URL. - **Disable system prompt** — fold the grounding into the first user message instead of a system role. - **Disable native tool-calling interface** — drive tools with a prompt-based loop instead of the provider's native tool calls. - **Show in the user model picker** — let people choose this model in chat. If no models are selectable, the picker stays hidden. - **Max iterations** — the tool-loop cap for this model. Leave it blank to use the cluster default. - **Extended thinking** — turn on thinking for this model, then set **Thinking budget (tokens)**. - **Reasoning effort** — the default effort sent for this model. **No override** leaves it unset. The choices are **minimal**, **low**, **medium**, and **high**. - **Reasoning effort choices offered to users** — which of those efforts people can pick. Leave them all unchecked to hide the effort picker for this model. - **Enabled** — turn the model off to keep the configuration without offering it. Click **Add model**. A toast confirms **Model added.** Editing an existing model confirms **Model saved.** **Cancel** closes the dialog without saving. A model row shows the configuration name, the model ID, and badges for the settings that are on (**No system prompt**, **No native tools**, **User-selectable**, **Max iterations**). Use the pencil to open **Edit model**, or the trash icon to delete that configuration only. Delete uses the same **Delete {name}?** confirmation and **Deleted {name}.** toast. ## Choose the default model The default model is the one each new chat starts on. It shows a **Default** badge. On any other enabled model, click **Set as default**. A toast confirms **Default model updated.** A disabled model cannot be the default. --- --- title: AI Steering sidebar_position: 12 --- # AI Steering AI Steering sets the prompt text applied to every AI chat turn in the organization. Changes take effect on the next message. **Navigation:** avatar > **Settings** > **Admin** > **LLMs and AI Instructions**, **AI Instructions** tab (or go to `/admin/ai`) The page heading is **AI configuration**. ## Edit a prompt Each prompt is its own card. The cards are: | Prompt | What it does | | --------------------- | ------------------------------------------------------------------------------------------------------------------------- | | **Base grounding** | Foundational instructions and the concept glossary sent at the start of every turn. The other prompts are appended to it. | | **Steering prompt** | Extra guidance such as tone and policy. Applied after the base grounding and before the tool-use guidance. | | **Tool-use guidance** | When to use tools versus answer directly. Applied last. | A card shows **Using default** until you save a change, then **Customized**. 1. Edit the text. A counter shows how many characters you have used, up to 32,000. **Save** stays disabled while the text is unchanged, too long, or a save is in progress. 2. Click **Save**. A toast confirms **AI configuration saved.** 3. Click **Discard changes** to drop edits you have not saved. ## Reset or restore - **Reset to default** is available on a **Customized** prompt. It clears your text and restores the built-in prompt. A toast confirms **Reverted to the default.** - **History** lists earlier versions of that prompt. Restoring a version copies it into the editor; you still click **Save** to keep it. Restoring the default uses **Reset to default**. ## Preview the assembled message Click **Preview assembled message** to read the full prompt the chat will send: base grounding, then the steering prompt, then the tool-use guidance. ## Leave with unsaved edits If you navigate away with unsaved prompt text, a dialog asks **Discard unsaved AI configuration?** - **Keep editing** stays on the page. - **Discard and leave** drops the unsaved text and continues. --- --- title: App Integrations sidebar_position: 6 --- # App Integrations Connect external applications so your users can link files from those applications into the platform **and** run **authenticated jobs** against them — for example opening a Teamwork Cloud project, reading a Google Drive file, or querying a Windchill server. **Navigation:** avatar > **Settings** > **Admin** > **App Integrations** (or go to `/admin/integrations`) The page heading is **Integrations**. ## How integrations work - An **integration** is a connection to one external application (Dassault Systèmes Teamwork Cloud, Google Drive, PTC Windchill, and others). You configure each integration once for your tenant. A Platform Administrator also sees and manages only their own tenant's integrations. - Each integration has an **auth standard** that sets how people sign in to the application: - **OAuth2 / OIDC — browser sign-in** for applications that use single sign-on. - **Basic — username & password** for applications that authenticate with a stored username and password. - Jobs sign in using a **credential**, which is one of two kinds: - A **service account** — a single sign-in **shared** across your tenant and managed by administrators. Users can select it but cannot change it. - A **linked account** — a user's **own** connection to the application, which each user creates for themselves. - When a function needs to sign in, the person launching the job selects which credential to use. Shared service accounts are labeled in the picker so users can tell them apart from their own linked accounts. For the underlying concepts, see [Integrations, jobs, and agents](../../intro/key-concepts/integrations#authenticated-jobs). > **Note:** Credentials are never attached to a queued job. When an agent claims an authenticated job, the platform issues a short-lived, single-use sign-in encrypted so that only that one agent can read it. The agent keeps it in a private file for the duration of the job and removes it when the job finishes — even if the job fails. No per-agent key setup is required. ## Applications you can connect | Application | Auth standard | How users authenticate | | ------------------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------- | | **Dassault Systèmes Teamwork Cloud** | Basic, or OAuth2 / OIDC | Each user links their own account (browser sign-in), or you provide a shared service account | | **Google Drive** | OAuth2 / OIDC | Each user links their own Google account (browser sign-in) | | **PTC Windchill** | Basic | A shared service account you create, or a personal linked account | | **Dassault Systèmes 3DEXPERIENCE** | Basic | A shared service account, or a personal linked account | | **Microsoft 365** | OAuth2 / OIDC | Each user links their own account (browser sign-in) | | **IBM Rational DOORS Next** | Basic or OAuth1 | Each user links their own Jazz account (browser sign-in), or a shared service account (service connection) | The platform's provider catalog is larger than the table above, which covers the most commonly configured applications. It also includes **Siemens Teamcenter**, **IBM Rational DOORS** (classic), **IBM Engineering Workflow Management**, **IBM Engineering Test Management**, **IBM Rhapsody Model Manager**, **IBM Engineering Lifecycle Management**, **3DEXPERIENCE CATIA**, **3DEXPERIENCE Enovia**, **Atlassian Jira**, **Atlassian Confluence**, and **Ping Identity**. The **Application** dropdown is populated from the catalog your deployment reports, so the choices you see may be narrower. The exact list of applications and the fields each one requires are presented in the **Add integration** dialog. ## View integrations Integrations are listed **grouped by application**. Each group shows the application name and how many integrations it has. Within a group, each integration row shows: - **Name**, with any assigned **control tags** as chips - Auth standard, created date, and created-by summary - Inline action icons: - **Test connection** (browser sign-in integrations) - **Edit integration** (pencil) - **Delete integration** (trash) - An expandable **service accounts** section under the row (for example, `1 service account` / `N service accounts`) Below the application groups, an **API tokens** section holds shared keys that are not tied to a provider. Use **Add service account** there; the dialog title is **Add service account (API token)**. ## Add an integration 1. Click **Add integration** in the top-right. 2. In the **Add integration** dialog: - Enter a **Name** that identifies this integration (for example, `Teamwork Cloud — Engineering`). You can add more than one integration for the same application. - Optionally assign **Control tags** — only users who hold every selected tag can see the integration or use accounts linked under it. Leave empty to keep it open to everyone in your tenant. - Select the **Application**. - Select the **Auth standard** offered by that application (**OAuth2 / OIDC — browser sign-in** or **Basic — username & password**). - Fill in the application-specific and sign-in fields that appear (see the walkthroughs below). - For OAuth standards, optionally set **Server CA certificate (PEM)** and **Verify server TLS certificate** when your identity provider uses a private CA. 3. For browser sign-in integrations, click **Test connection** to validate the configuration before saving. If the test fails (or cannot run), the primary button becomes **Add anyway** so you can still save. 4. Click **Add** (or **Add anyway**). The integration appears in its application group. ## Edit an integration 1. Click the **Edit integration** (pencil) icon on the integration row. 2. In the **Edit integration** dialog, update name, control tags, auth fields, or TLS trust settings as needed. 3. For browser sign-in integrations, click **Test connection** to re-validate. If the test fails, the primary button becomes **Save anyway**. 4. Click **Save** (or **Save anyway**). The sections below walk through the most common setups end to end. ## Connect Dassault Systèmes Teamwork Cloud with OIDC Use this when your Teamwork Cloud (TWC) is single-sign-on only, so users authenticate through your identity provider rather than a TWC username and password. This lets users run authenticated Cameo and Teamwork Cloud jobs with their own identity. Setup has two halves, in order: a **Teamwork Cloud administrator** registers Istari Digital as an OpenID Connect client on the TWC Authentication Server, then an **Istari Digital administrator** creates the integration using the values from that registration. ### Register Istari Digital on the Teamwork Cloud Authentication Server A Teamwork Cloud administrator performs this once, on the TWC side. The only value needed from Istari Digital is the **redirect (callback) URL**: your Istari Digital web application's address followed by `/connection-callback.html` (for example, `https://app.example.com/connection-callback.html`). **TWC 2024x and later** — in the TWC **Settings** application, go to **OAuth clients > OpenID Connect > Create client** and enter: | Setting | Value | | --------------- | ----------------------------------------------------------------------------- | | Client name | `IstariDigital` (or similar) | | Client secret | Generate a strong secret and record it — you enter it in Istari Digital below | | Redirect URI(s) | The Istari Digital callback URL above | | Grant types | **Authorization Code** and **Refresh Token** | | Response type | `code` | The generated **client key** is the client ID you give to the Istari Digital administrator. **TWC 2022x and earlier** (no OIDC client UI) — edit the Authentication Server configuration on the server host, then **restart the Authentication Server**: In `/AuthServer/config/authserver.properties`: | Property | Change | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `authentication.client.ids` | Append your chosen client ID for Istari Digital (comma-separated list). The authorization endpoint rejects any client ID not in this list. | | `authentication.redirect.uri.whitelist` | Append the Istari Digital callback URL above (comma-separated; full URL or prefix). Redirect URIs that are not whitelisted are rejected. | | `authentication.token.expirity` | Access/id-token lifetime. A short lifetime is fine — Istari Digital renews tokens per job via the refresh token. ("Expirity" is the vendor's spelling — copy the property name exactly as shown.) | In `webappplatform.properties`: | Property | Change | | ------------------------------ | -------------------------------------------------------------------------------- | | `authentication.client.secret` | Set a strong client secret and record it — you enter it in Istari Digital below. | > **Note:** Property names may vary slightly between TWC releases — verify against the Dassault Systèmes / No Magic documentation for your version. Istari Digital identifies the TWC user from the token claims `preferred_username`, `email`, or `sub` (in that order). TWC populates these by default, so no change is normally needed — just confirm your Authentication Server has not been customized to strip them. ### Create the integration in Istari Digital **Before you begin**, gather from the registration above (or from your identity provider, if users sign in to TWC through a separate one): - The **issuer URL** — the Authentication Server base URL (for example, `https://twc.example.com:8443/authentication`). - The **client ID** registered for Istari Digital (on TWC 2024x, the generated **client key**). - The matching **client secret**. The OIDC field values differ by TWC version. TWC 2024x's Authentication Server runs **two** OIDC services side by side: clients registered in the **OAuth clients** UI are served by a newer service with its own endpoints, while the older 2022x-style service still answers standard automatic discovery. Because of that, automatic discovery finds the **wrong** endpoints for a 2024x-registered client — enter them explicitly as described below. **Steps:** 1. Go to **Settings** > **Admin** > **App Integrations** and click **Add integration**. 2. Enter a **Name**, set **Application** to **Dassault Systèmes Teamwork Cloud**, and set **Auth standard** to **OAuth2 / OIDC — browser sign-in**. 3. Enter the **Teamwork Cloud server** address that your users' projects live on (for example, `twc.example.com`). 4. Fill in the OIDC fields for your TWC version (see the two versions below). 5. Click **Test connection**, then **Add** (or **Add anyway** if you choose to save without a passing test). **TWC 2024x and later** (client registered in the **OAuth clients** UI) — first, in a browser, open `https://:8443/authentication/.well-known/oidc-configuration`. This page lists your server's exact endpoint URLs; copy them into the fields below. Note that two of the pre-filled Teamwork Cloud defaults must also be changed: | Field | Value | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Issuer** | The Authentication Server base URL (for example, `https://twc.example.com:8443/authentication`) | | **Authorization endpoint** | The `authorization_endpoint` value from the configuration page (normally optional — required here). It looks like `https://twc.example.com:8443/authentication/oidc/authorize`. | | **Token endpoint** | The `token_endpoint` value from the configuration page (normally optional — required here). It looks like `https://twc.example.com:8443/authentication/api/oidc/token`. | | **Client ID** / **Client secret** | Exactly the client key and secret from the TWC **OAuth clients** registration. | | **Client secret header** | **Clear this field so it is blank.** The pre-filled value (`X-Auth-Secret`) is how TWC 2022x accepts the secret; the 2024x service rejects it. | | **Scopes** | Edit to exactly `openid` — **remove `offline_access`**. The 2024x service rejects unknown scopes with an `invalid_scope` error when a user signs in. Durable connections still work: refresh tokens come from the **Refresh Token** grant type in the client registration. | **TWC 2022x and earlier** (client registered in `authserver.properties`) — automatic discovery works, and the pre-filled Teamwork Cloud defaults are correct: - **Issuer** — the Authentication Server base URL. - **Client ID** and **Client secret** — the values you registered for Istari Digital. - Leave **Authorization endpoint** and **Token endpoint** blank to discover them automatically from the issuer. - Leave **Scopes**, **Use PKCE**, **Client secret header**, and the other pre-filled defaults unchanged. > **Note:** If your Authentication Server presents a certificate the platform does not trust (for example, self-signed), paste the signing CA certificate into **Server CA certificate (PEM)**. As a last resort you can turn off **Verify server TLS certificate**, but an unverified connection can be intercepted — prefer the CA field. **Next:** users connect their own Teamwork Cloud identity once under **Linked Accounts > Link account**, which opens a browser sign-in. After that, the linked account is available in the credential picker when they launch a job. ### Network requirements | From | To | When / why | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Users' browsers | The Istari Digital web application **and** the TWC Authentication Server (for example, `https://twc.example.com:8443/authentication`) | During account linking — the browser is redirected to the Authentication Server sign-in page and returns to Istari Digital's callback. If TWC delegates sign-in to a corporate identity provider, the browser must reach that too. | | Istari Digital agents | The Istari Digital API **and** the TWC data server (the server address your users' projects live on) | While running Cameo / TWC jobs — the agent receives the encrypted sign-in from Istari Digital and connects to the TWC server. | | Istari Digital platform | The TWC Authentication Server (outbound HTTPS) | OIDC discovery, the one-time sign-in exchange when a user links their account, and a token renewal each time a job runs. | Teamwork Cloud never initiates connections to Istari Digital — no inbound access to Istari Digital is required from the TWC side. ## Connect Google Drive Use this so users can reference Google Drive files in jobs (for example with the Google Workspace module). Each user links their own Google account, and jobs act with that user's Google access. ### Register Istari Digital in the Google Cloud Console A Google Cloud / Workspace administrator performs this once, in the [Google Cloud Console](https://console.cloud.google.com/). The only value needed from Istari Digital is the **redirect (callback) URL**: your Istari Digital web application's address followed by `/connection-callback.html` (for example, `https://app.example.com/connection-callback.html`). 1. Create (or select) a Google Cloud **project** to hold the client. 2. Configure the **OAuth consent screen** if the project does not have one yet. For a Google Workspace organization, choose user type **Internal** so only your organization's accounts can sign in (**External** works too, but Google may require app verification depending on scopes). 3. Under **APIs & Services > Library**, enable the **Google Drive API** — modules access Drive files through it. 4. Under **APIs & Services > Credentials**, click **Create credentials > OAuth client ID**, choose application type **Web application**, and add the Istari Digital callback URL to **Authorized redirect URIs** (no JavaScript origins are needed). 5. Record the generated **client ID** and **client secret** — you enter them in Istari Digital below. You do not need to configure offline/refresh access — Istari Digital requests it automatically during the browser sign-in, so each linked account stays durable. The default Drive scope grants access only to files the user creates with or opens through Istari Digital, not their whole Drive. ### Create the integration in Istari Digital **Before you begin**, have the **client ID** and **client secret** from the registration above. The issuer is `https://accounts.google.com`. **Steps:** 1. Go to **Settings** > **Admin** > **App Integrations** and click **Add integration**. 2. Enter a **Name**, set **Application** to **Google Drive**, and set **Auth standard** to **OAuth2 / OIDC — browser sign-in**. 3. Fill in the OIDC fields: - **Issuer** — `https://accounts.google.com`. - **Client ID** and **Client secret** — from your Google Cloud OAuth client. - The Google Drive **scope** and offline-access settings are pre-filled, so Google returns a durable connection. Add scopes only if your module needs broader access. 4. Click **Test connection**, then **Add** (or **Add anyway** if you choose to save without a passing test). **Next:** users connect their Google account once under **Linked Accounts > Link account**, then select it when launching a job. ### Network requirements | From | To | When / why | | ----------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Users' browsers | The Istari Digital web application **and** `accounts.google.com` | During account linking — the browser signs in to Google and returns to Istari Digital's callback. | | Istari Digital agents | The Istari Digital API **and** Google APIs (`www.googleapis.com`) | While running jobs — the agent receives the encrypted sign-in from Istari Digital and calls the Google Drive API. | | Istari Digital platform | Google's sign-in endpoints (`accounts.google.com`, `oauth2.googleapis.com`), outbound HTTPS | OIDC discovery, the one-time sign-in exchange when a user links their account, and a token renewal each time a job runs. | Google never initiates connections to Istari Digital — no inbound access to Istari Digital is required. ## Connect Microsoft 365 Use this so users can run authenticated jobs against Microsoft 365 with their own identity. Each user links their own Microsoft account through a browser sign-in. ### Register Istari Digital in Microsoft Entra A Microsoft Entra (Azure AD) administrator performs this once, in the [Microsoft Entra admin center](https://entra.microsoft.com/). The only value needed from Istari Digital is the **redirect (callback) URL**: your Istari Digital web application's address followed by `/connection-callback.html` (for example, `https://app.example.com/connection-callback.html`). 1. Go to **Identity > Applications > App registrations** and click **New registration**. 2. Enter a **Name** (for example, `Istari Digital`), and under **Supported account types** choose **Accounts in this organizational directory only** (single tenant). 3. Under **Redirect URI**, select platform **Web** and enter the Istari Digital callback URL. 4. Click **Register**, then from the app's **Overview** page record the **Application (client) ID** and the **Directory (tenant) ID**. 5. Go to **Certificates & secrets > New client secret**, and record the secret **value** immediately (it is shown only once). Note its expiry date — you will need to create a new secret and update the integration in Istari Digital before it expires. Istari Digital requests only the standard sign-in permissions (`openid`, `email`, `profile`, `offline_access`), which most tenants allow without admin consent. If your modules need Microsoft Graph data (for example, files or mail), add the corresponding **delegated** permissions under **API permissions** and grant admin consent if your tenant requires it. ### Create the integration in Istari Digital **Before you begin**, gather from the registration above: - The **issuer URL** — `https://login.microsoftonline.com//v2.0`, using the **Directory (tenant) ID** from the app's Overview page. - The **Application (client) ID**. - The **client secret** value. **Steps:** 1. Go to **Settings** > **Admin** > **App Integrations** and click **Add integration**. 2. Enter a **Name**, set **Application** to **Microsoft 365**, and set **Auth standard** to **OAuth2 / OIDC — browser sign-in**. 3. Fill in the OIDC fields: - **Issuer** — the tenant issuer URL above. - **Client ID** and **Client secret** — from your Entra app registration. - **Scopes** and **Use PKCE** are pre-filled with working defaults — add scopes only if your module needs Microsoft Graph access. 4. Click **Test connection**, then **Add** (or **Add anyway** if you choose to save without a passing test). **Next:** users connect their Microsoft account once under **Linked Accounts > Link account**, then select it when launching a job. ### Network requirements | From | To | When / why | | ----------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Users' browsers | The Istari Digital web application **and** `login.microsoftonline.com` | During account linking — the browser signs in to Microsoft and returns to Istari Digital's callback. | | Istari Digital agents | The Istari Digital API **and** Microsoft 365 endpoints (for example, `graph.microsoft.com`) | While running jobs — the agent receives the encrypted sign-in from Istari Digital and calls Microsoft services. | | Istari Digital platform | Microsoft's sign-in endpoints (`login.microsoftonline.com`), outbound HTTPS | OIDC discovery, the one-time sign-in exchange when a user links their account, and a token renewal each time a job runs. | Microsoft never initiates connections to Istari Digital — no inbound access to Istari Digital is required. ## Connect IBM DOORS Next with OAuth 1.0a (OAuth1) Use this so users can run authenticated DOORS Next jobs with their own Jazz identity. Setup has two halves, in order: a **Jazz administrator** registers Istari Digital as an OAuth consumer on the server, then an **Istari Digital administrator** creates the integration with the values from that registration. :::note Running a DOORS Next job with an OAuth1 linked credential or service connection requires **IBM DOORS module v1.3.2 or later** — earlier module versions accept only Basic credentials for DOORS Next jobs. ::: ### Register an OAuth consumer on the Jazz Team Server A Jazz administrator performs this once. In the Jazz Team Server admin console (`https:///jts/admin`), open the **Consumers (Inbound)** page and register a consumer named `IstariDigital` (or similar) with a strong, recorded **consumer secret**. Record the generated **consumer key** as well — both go into Istari Digital below. To also offer a **shared service connection** (jobs sign as one organizational identity, with no per-user sign-in), assign a **functional user** to the consumer during registration. ### Create the integration in Istari Digital 1. Go to **Settings** > **Admin** > **App Integrations** and click **Add integration**. 2. Enter a **Name**, set **Application** to **IBM Rational DOORS Next**, and set **Auth standard** to **OAuth1 — browser sign-in**. 3. Enter the **Server base URL** (for example, `https://elm.example.com`), plus the **Consumer key** and **Consumer secret** from the registration. 4. The **Discovery document path** is pre-filled with `/rm/rootservices` and the **Identity path** with `/jts/whoami`. While a discovery document is set, the three OAuth endpoint fields can stay blank — they are read from it. 5. For an on-premises server signed by a private CA, paste the certificate under **Server CA certificate (PEM)**. 6. Click **Test connection**, then **Add**. **Next:** users link their own DOORS Next account under **Linked Accounts > Link account** — a browser sign-in to Jazz plus a one-time authorization. If the consumer has a functional user, you can instead expand the integration's service accounts and click **Add service connection** to create the shared connection. ### Network requirements | From | To | When / why | | ----------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | Users' browsers | The Istari Digital web application **and** the Jazz server | During account linking — the browser signs in to Jazz and returns to Istari Digital's callback. | | Istari Digital platform | The Jazz server | During discovery, **Test connection**, and the OAuth request/access-token exchanges for account linking and service connections. | | Istari Digital agents | The Istari Digital API **and** the Jazz server | While running jobs — the agent receives the encrypted sign-in from Istari Digital and calls DOORS Next. | DOORS Next never initiates connections to Istari Digital — no inbound access to Istari Digital is required. ## Create a Windchill service account Use this to set up a single **shared** Windchill service user that everyone in your tenant runs jobs through, rather than each user linking a personal account. **Before you begin**, gather the **username** and **password** of the Windchill service account you want jobs to use, and decide on a display **name** for it (users see this name in the credential picker). **Steps:** 1. Make sure a **PTC Windchill** integration exists. If not, click **Add integration**, enter a **Name**, set **Application** to **PTC Windchill** (auth standard **Basic — username & password**), and click **Add**. 2. In the PTC Windchill group, expand the integration's **service accounts** section. 3. Click **Add service account**. 4. In the **Add service account — {name}** dialog, enter the **Name**, **Username**, and **Password** of the service user. 5. Click **Add**. The service account is shared across your tenant. When users launch a Windchill job they can select it from the credential picker, where it is marked as a service account. Users cannot view or change its password. > **Note:** If you want each user to authenticate as themselves instead of through a shared account, skip the service account and have users add a personal linked account under **Linked Accounts > Link account** for the Windchill integration. ## How users select a credential when running a job When a function requires a sign-in, the job launcher shows a **credential picker**: - Users see their own **linked accounts** plus any **service accounts** shared across your tenant for that application. Service accounts are labeled so they are easy to distinguish. - For functions that can optionally use a sign-in, users can attach a credential under the launcher's **Advanced options**. Users manage their own linked accounts under **Linked Accounts**; service accounts are managed by administrators on this page and appear as read-only options in the picker. Users submitting jobs through the Python client select a credential the same way, by passing `auth_bindings` to `add_job` — see [Run jobs on a third-party Resource](../../icbs-build-python/05-connected-resources.md#run-jobs-on-a-third-party-resource). ## Manage service accounts 1. In an integration's row, click the expandable **service accounts** control. 2. Click **Add service account** to create a shared credential for that integration. 3. Use the trash icon on a service account row to remove it. For provider-less shared keys, use the **API tokens** group at the bottom of the page and **Add service account** — the dialog title is **Add service account (API token)**. ## Delete an integration 1. Click the **Delete integration** (trash) icon on the integration row. 2. Confirm in the **Delete integration** dialog. > **Warning:** Deleting an integration also removes the service accounts and linked accounts under it, and may break existing file connections and authenticated jobs that depend on it. ## Restrict an integration with control tags Control tags limit who can see and use an integration. Assign them in the **Control tags** field when adding or editing an integration: a user must hold **every** tag on the integration to see it, link an account to it, or use its accounts in a job. An integration with no tags is unrestricted. Enforcement is server-side, so the same rule applies to API and SDK access. Service accounts under a tagged integration inherit its tags — shown as dashed chips — and can carry additional directly-assigned tags that restrict that one account further. Tags synced from an external system can only be inherited, never assigned directly. Manage the tags themselves, and users' tag assignments, under [Control Tags](./control-tags.md). --- --- title: Platform Compatibility sidebar_position: 11 --- # Platform Compatibility Monitor API compatibility between the Istari Digital Platform server and the agents connected to it. **Navigation:** avatar > **Settings** > **Admin** > **Compatibility** (or go to `/admin/compatibility`) :::note Availability **Compatibility** appears in the **Admin** group in Settings only for administrators. ::: ## Server versions At the top of the page, the platform shows: - **Registry Service version** — the backend API version for your deployment - **Frontend version** — the web UI release version ## Agent Compatibility table The **Agent Compatibility** section lists connected agents with: | Column | Description | | ----------- | -------------------------------- | | **Agent** | Agent display name | | **Version** | Agent software version | | **Status** | Compatibility result (see below) | ### Status values | Status | Meaning | | --------------------- | ------------------------------------------- | | **Compatible** | Agent version matches server expectations | | **Incompatible** | Agent cannot work with this server version | | **Revision Mismatch** | Agent and server API revisions do not align | | **Deprecated** | Agent version is deprecated for this server | | **Unreachable** | Agent could not be reached for the check | | **Unknown** | Status could not be determined | A summary line above the table reports the overall state of the agents rather than a count. It reads **No agents**, **Incompatible agents detected**, **Revision mismatches detected**, **Deprecation warnings present**, **Some agents have unknown compatibility**, or **All agents compatible**, whichever applies first. ### Filters and actions - **Organization** — shown only when more than one tenant is visible to you, as it is to a Platform Administrator. On installations without tenant management it is shown when you belong to several organizations. Filter the table by one, or **All organizations**. - **Refresh** — reload compatibility data for the current filter. - **Pagination** — page through results; choose page size **10**, **20**, or **50**. - **Export JSON** — download a JSON report with server versions and the full agent compatibility list. ## Related - [Agents](./agents.md) — manage agents and agent pools - [Administrator Guide overview](./index.md) --- --- title: Platform Admin Console --- # Platform Admin Console The Platform Admin Console is where Platform Administrators manage every tenant and every person on the installation. The [Admin Panel](../../intro/terminology.md#admin-panel), by contrast, manages your own tenant. The Platform Admin Console exists only on installations with [tenant management](../../intro/terminology.md#tenant-management), and only Platform Administrators can open it. See [Administrators](./administrators.md) for the roles. ## Open the Platform Admin Console 1. Click your avatar at the bottom of the sidebar. 2. Click **Platform Admin Console**. You can also go to `/console`, which opens **Tenants**. A Tenant Administrator who opens a console address is taken to the Admin Panel instead. ## Sections The Platform Admin Console replaces the main sidebar with its own: | Section | Shows | Route | | ----------- | --------------------------------------------------------------------------------- | ------------------ | | **Tenants** | Every tenant, with each tenant's details and members; see [Tenants](./tenants.md) | `/console/tenants` | | **Users** | Every tenant's people; see [User Management](./user-management.md) | `/console/users` | **Back to Istari**, at the bottom of the sidebar, returns you to the main app. ## The Users page The Platform Admin Console's **Users** page works like the Admin Panel's, across every tenant. [User Management](./user-management.md) notes each difference, such as the **Tenant** dropdown and the **Make platform admin** action. --- --- title: Control Tags sidebar_position: 4 --- # Control Tags A **control tag** is a need-to-know control an administrator defines, then assigns in two places: to **users** and to **Resources**. A user can open a tagged Resource when they have a role on it and hold every tag the Resource carries. Create the tag on this page, assign it to users from [Users](./user-management.md#assign-control-tags-to-a-user), and assign it to a Resource from that Resource (Administrator or Owner). Control tags apply to the whole installation, not to one tenant. Administrators in every tenant see the same tags, and any of them can rename or archive a tag, including one created in another tenant. Secure Connections use the same tags as a transfer control: - On a **sending** connection, [tag rules](./secure-connections.md#tag-rules-sending-connections) allow or block each Resource based on the tags it carries. - On a **receiving** connection, [transformation rules](./secure-connections.md#transformations-receiving-connections) add, remove, or replace tags on what arrives. A rule that puts a local tag on a received Resource changes who can see it. Assign that tag to the users who should see the Resource, including permitted recipients of the connection. **Navigation:** avatar > **Settings** > **Admin** > **Control Tags** (or go to `/admin/control-tags`) ## View Control Tags The page has **Active** and **Archived** tabs only. 1. The default view shows the **Active** tab. 2. The table lists each tag with: - **Name** (with colored dot) - **Description** - **Created** date - **Created By** user - **⋯** actions menu 3. Switch to the **Archived** tab to see archived tags. The table is paginated, 10 rows per page by default. The footer shows **Showing N tags** when everything fits on one page, or **Showing X-Y of N** when it does not, plus **Items per page:** (**10**, **20**, **30**, or **50**). ## Create a Control Tag 1. Click **New Control Tag** in the top-right. 2. In the dialog: - **Name** — enter the tag display name (required). - **Description** — optional description text. - **Display Color (#hex)** — enter a hex color value, or click **Pick a color** to use the color picker. A preview of the tag with the chosen color is shown. 3. Click **Create**. ## Edit a Control Tag 1. Click the **⋯** menu on a tag row. 2. Select **Edit**. 3. Update the **Name**, **Description**, or **Display Color (#hex)**. 4. Click **Update**. ## Archive a Control Tag 1. On the **Active** tab, click the **⋯** menu on a tag row. 2. Select **Archive**. 3. Confirm the action. Archived tags are no longer available for new assignments. ## Restore an Archived Control Tag 1. Switch to the **Archived** tab. 2. Click the **⋯** menu on the archived tag row. 3. Select **Restore**. 4. Confirm the action. The tag returns to the **Active** list and becomes available for assignment again. ## Assign Control Tags to Users Assign tags from [Users](./user-management.md): 1. Open **Settings** > **Admin** > **Users**. 2. In the **Control Tags** column (or in **User Details**), click the tags area for the user. 3. In the **Edit Control Tags** dialog, select or deselect tags and optionally provide a **reason**. 4. Click **Save**. --- --- title: Admin Panel Overview sidebar_position: 1 --- # Administrator Guide Use the **Admin Panel**, the administrator pages listed under **Admin** in Settings, to manage your tenant across the Istari Digital web app: people and access policy, agents and external applications, partner connections, compatibility, and usage reporting. Platform Administrators also manage every tenant from the [Platform Admin Console](./console.md). These tasks support every stage of adoption. Install, Connect, Build, and Share link here when a procedure requires administrator access, while this guide keeps all administrator tasks in one place. For everyday work with Systems, Resources, and jobs, see [Build with no code](../../build/02-no-code.md). For infrastructure and control-plane administration, see [Install](../../icbs-install/01-Introduction.md). ## What you will find here - **Platform Admin Console** — Manage every tenant and every tenant's people (Platform Administrators). - **People & access policy** — Add and manage people, manage tenants, grant administrator roles, assign tool access and classification levels, and configure control tags and infosec levels. - **Agents & integrations** — Create agent keys or tokens, manage agents, register external applications and credentials, and check compatibility. - **Secure Connections** — Configure governed data exchange with partner organizations and diagnose synchronization failures. - **AI** — Set the prompts applied to every AI chat turn, and register the endpoints and models those chats can use. - **Usage Metrics** — Download usage data for reporting and analysis. ## Prerequisites These prerequisites apply to installations with [tenant management](../../intro/terminology.md#tenant-management). For installations without it, see [On installations without tenant management](#on-installations-without-tenant-management). - You need an administrator role: **Tenant Administrator** in your tenant, or **Platform Administrator**. See [Administrators](./administrators.md) for what each role covers and who can grant it. - Only a Platform Administrator can enable and configure infosec levels; see [Infosec Levels](./infosec-levels.md). - If **Admin** does not appear in Settings, ask an administrator of your tenant to grant you a role. - If nobody holds an administrator role yet, your IT administrator [creates the first Platform Administrator](../../icbs-install/03-control-plane/10-identity-service/05-Create-the-First-Platform-Administrator.md). ### On installations without tenant management If **Settings** > **Admin** > **Users** has an **Invited** tab, your installation does not use [tenant management](../../intro/terminology.md#tenant-management). There, your IT administrator grants administrator access in your sign-in provider, and the Platform Admin Console, Tenants and Administrators pages do not apply. ## Admin Panel Overview 1. Click your avatar at the bottom of the sidebar, then **Settings**. 2. In the Settings navigation, the **Admin** group sits below your personal settings. Click a section there. The **Admin** group appears only for administrators. You can also go to `/admin`, which opens the first section you can use, usually **Users**. Breadcrumbs on admin pages start at **Settings**. A section marked in the **Also requires** column appears only when that feature is enabled for your deployment. | Section | Description | Route | Also requires | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------- | ----------------------------------- | | **Users** | Add, suspend and reactivate your tenant's people; manage their administrator roles, tool access and control tags | `/admin/users` | — | | **Control Tags** | Create, edit, and archive control tags | `/admin/control-tags` | — | | **Infosec Levels** | Enable and configure information security classification | `/admin/infosec` | Infosec enabled for your deployment | | **App Integrations** | Configure third-party app connections (Google Drive, Windchill, etc.) | `/admin/integrations` | — | | **Encryption Keys** | Placeholder for managing the keys that protect your tenant's data. Not yet configurable | `/admin/encryption-keys` | — | | **Secure Connections** | Configure inbound and outbound data channels with partner registries | `/admin/secure-connections` | — | | **Usage Metrics** | Download usage data as CSV for a chosen date range | `/admin/usage` | — | | **Compatibility** | Monitor server and agent API compatibility | `/admin/compatibility` | — | | **LLMs and AI Instructions** | Register LLM endpoints and the models approved on each (**LLMs** tab), and edit the prompts applied to every AI chat turn (**AI Instructions** tab); see [AI Models](./ai-models.md) and [AI Steering](./ai-steering.md) | `/admin/ai` | — | **Agents** (create agent credentials and manage agents) live under **Agents** in the main app sidebar at `/agents`, not in the **Admin** group in Settings. That entry is also visible to administrators only. Legacy URLs `/admin/agent`, `/admin/agents`, `/admin/agent-management`, and `/agent-management` redirect there. See [Agents](./agents.md). ## Guide Sections ### Platform Admin Console - [Platform Admin Console](./console.md) — manage every tenant and every tenant's people (Platform Administrators) ### People & access policy - [User Management](./user-management.md) — add people one at a time or from a CSV file, suspend and reactivate them, and manage their tool access, keys and classification levels - [Tenants](./tenants.md) — create, edit, suspend and reactivate tenants, and manage their members - [Administrators](./administrators.md) — grant and revoke the Tenant Administrator and Platform Administrator roles - [Control Tags](./control-tags.md) — create and manage control tags (assign tags to users in [User Management](./user-management.md)) - [Infosec Levels](./infosec-levels.md) — enable and configure security classification levels ### Agents & integrations - [Agents](./agents.md) — generate keys or tokens, view and manage agents - [App Integrations](./app-integrations.md) — configure third-party connections - [Platform Compatibility](./compatibility.md) — server and agent version compatibility ### Secure Connections - [Secure Connections](./secure-connections.md) — configure sending and receiving connections with partner registries - [Debugging Secure Connections](./secure-connections-debugging.md) — diagnose sync failures and authentication issues ### AI - [AI Steering](./ai-steering.md) — edit the prompts applied to every AI chat turn - [AI Models](./ai-models.md) — register endpoints and the models approved on each ### Reporting - [Usage Metrics](./usage-metrics.md) — download usage reports ## Quick Reference: Admin Routes | Route | Page | | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | `/admin` | Admin entry (opens the first section you can use, usually `/admin/users`) | | `/admin/users` | User management | | `/admin/users/` | A person's details (tenant management only) | | `/admin/control-tags` | Control tag management | | `/admin/infosec` | Infosec level configuration | | `/admin/integrations` | Third-party app integrations | | `/admin/encryption-keys` | Encryption keys (placeholder; not yet configurable) | | `/admin/usage` | Usage metrics | | `/admin/compatibility` | Platform compatibility | | `/admin/ai` | LLMs and AI Instructions; the older `/admin/ai-models` and `/admin/ai-settings` redirect here | | `/admin/secure-connections` | Secure connection management | | `/admin/secure-connections/:kind/:connectionId` | Connection settings (`?tab=details`, `rules`, `users`, or `owners`) | | `/admin/secure-connections/:kind/:connectionId/sync-status` | Connection sync status detail | | `/agents` | Agent credentials and agent management (main sidebar) | | `/console` | Platform Admin Console entry (redirects to `/console/tenants`); tenant management only | | `/console/tenants` | Tenants | | `/console/tenants/` | A tenant's details and members | | `/console/users` | Every tenant's people | | `/console/users/` | A person's details | --- --- title: Infosec Levels sidebar_position: 3 --- # Information Security (Infosec) Levels :::note Availability Infosec levels appear in the admin pages only when information security classification is **enabled for your deployment**. If **Infosec Levels** is missing from the **Admin** group in Settings, contact your IT administrator. This capability is **experimental** and may change. ::: Infosec levels provide security classification for resources across the platform. Once enabled, this feature **cannot be disabled**. **Navigation:** avatar > **Settings** > **Admin** > **Infosec Levels** (or go to `/admin/infosec`) Infosec settings apply to the whole installation. Only a Platform Administrator (on installations without tenant management, an organization administrator) can enable infosec levels or change the maximum and default levels. Tenant Administrators can open the page but cannot save changes. ## Enable Infosec Levels 1. Locate the **Enable Infosec Levels** toggle. Helper text beneath it reminds you: "Once enabled, this setting cannot be disabled." 2. Switch the toggle to **ON**. 3. Select an **Infosec Schema** (required). The schema determines the available classification levels and **cannot be changed after enabling**. 4. Configure the maximum and default levels (see next section). 5. Click **Save Changes**. **Save Changes** stays disabled until something on the card has changed. **Cancel** leaves the page and returns to `/admin`. Once infosec is enabled, an alert at the top of the card confirms it: "Infosec levels are enabled. This setting is permanent and cannot be disabled." > **Warning:** Enabling infosec levels is a permanent, irreversible action for the installation. Once enabled, the toggle is disabled and cannot be turned off. The **Infosec Schema** selector is locked after enable. ## Configure Maximum and Default Levels After enabling infosec: 1. **Maximum Infosec Level Allowed** — Select the highest level that can be assigned to any resource in the installation. This acts as a ceiling. 2. **Default Infosec Level for All Resources** — Select the level automatically assigned to new resources. This must be at or below the maximum level. Both dropdowns show all available levels with their color indicators, sorted by order. The levels come from the selected **Infosec Schema**. **Validation rules:** - The default level cannot be higher than the maximum level (checked in the web app before save). - Both fields must be selected before saving. - Maximum and default can be changed after infosec is enabled; the schema and enabled state cannot. - Lowering the maximum below the highest level already assigned to any resource, system, or sending connection is rejected by the **Istari Registry Service** API. The admin UI does not block that selection in advance — save fails with an API error if any object would exceed the new ceiling. 3. Click **Save Changes**, or **Cancel** to return to `/admin` without saving. **Save Changes** stays disabled until a value on the card has changed. ## View Available Infosec Levels When infosec is enabled, a **"Available Infosec Levels"** card appears below the configuration card. This shows all levels defined in the infosec schema (e.g., US DoD classification levels) with: - A numbered, colored badge for each level - The level name This list is read-only and determined by the infosec schema. ## Assign Infosec Levels to Users Assign clearance from [Users](./user-management.md): 1. Open **Settings** > **Admin** > **Users**. 2. In the **Classification** column (or in **User Details**), click the user's current level or **"Set level..."**. 3. Select the desired level from the dropdown. > Only defined levels are listed; you cannot remove an assignment from that column. ## How Infosec Levels Appear Across the Platform Once enabled, infosec levels are visible throughout the application in several places: | Location | What is Shown | Who Can Edit | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | **Top banner** (global) | A colored banner displaying the installation's maximum infosec level name | Not editable (display only) | | **Avatar menu** and **Settings** | The current user's personal classification level badge, below their name and tenant in the avatar menu and at the top of Settings | Not editable (set by admin) | | **Profile** page | A read-only **Classification Level** field showing the user's assigned level with shield icon and color | Not editable (set by admin) | | **System** home page header | Shield icon with the system's infosec level. Change it with **Edit System Details** > **Classifications** | Administrator or Owner on the system | | **Resources** page header | Shield icon with the Resource's infosec level | Administrator or Owner on the Resource | | **File details pane** (side panel) | A **"Classification"** property row with inline dropdown to change the level | Administrator or Owner on the file | | **File/artifact content viewer** | A colored **classification banner** below the header bar showing "Resource Classification Level" | Not editable (reflects current level) | | **Upload dialog** | Per-file **infosec level selector** when uploading new files; defaults to the installation's default level, highlighted in red if not set | Any user uploading (restricted to their allowed levels) | | **Admin > Users** table | **Classification** column with inline level selector per user (also in **User Details**) | Tenant Administrator or Platform Administrator (on installations without tenant management, an organization administrator) | | **Admin > Infosec Levels** | Schema selection, enable toggle, and maximum/default configuration | Platform Administrator (on installations without tenant management, an organization administrator) | **Level restriction rules:** - Users can only assign levels up to the **lower of**: the platform maximum, the system maximum (if within a system), and their personal infosec clearance. - Resources without an explicit assignment inherit the installation's **default level**. --- --- title: Debugging Secure Connections sidebar_position: 10 --- # Debugging Secure Connections :::note Availability The Secure Connection Service (SCS) must be installed and configured at the infrastructure level before the connections described here exist. If you are an administrator but **Secure Connections** is missing from the **Admin** group in Settings, ask your IT administrator to complete [Secure Connection Service Setup](../../icbs-install/09-secure-connection-service.md). If you are not an administrator, ask an administrator of your tenant, or of your organization on installations without tenant management. ::: This guide covers diagnosing and resolving common issues with [Secure Connections](./secure-connections.md), including configuration problems and sync failures. Administrators with access to the Secure Connections admin panel use this page. End users should start with [Secure Connections (User Guide)](../user-guide/secure-connections.md) and contact their administrator if a problem persists. --- ## Prerequisites Before troubleshooting an issue at the connection-configuration level, confirm that the underlying infrastructure is in place and healthy. Most "the connection won't work at all" symptoms trace back to deployment-level misconfiguration rather than anything done in the admin UI. - The Secure Connection Service (SCS) is deployed and reachable by the rest of the cluster. See [Secure Connection Service Setup](../../icbs-install/09-secure-connection-service.md) for the full deployment walkthrough, including the Helm chart, identity-provider role and machine user, S3 Inbox / Outbox buckets, Master Key, and required environment variables. - The SCS Master Key matches between SCS and the Registry Service (`ISTARI_DIGITAL_SECURE_CONNECTION_SERVICE_MASTER_SECRET` and `FILE_SERVICE_REMOTE_MASTER_SECRET`). See [Master Key](../../icbs-install/09-secure-connection-service.md#master-key). - The Inbox / Outbox object stores referenced by the connection exist, are reachable, and the SCS and Registry Service have access (either via static keys or Pod Identities). See [S3 Bucket Management](../../icbs-install/09-secure-connection-service.md#s3-bucket-management). - The SCS machine user has been granted its Registry Service role on the Istari Digital project. See [Prerequisites](../../icbs-install/09-secure-connection-service.md#prerequisites) in Secure Connection Service Setup. --- ## Debugging Secure Connection Sync To view the most recent sync attempts, click the colored (red/yellow/green) sync status icon on the far left of the row in the **Sending Connections** or **Receiving Connections** table. ### Sending Side Checks #### Sync Failures | Error message | Resolution | | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `shared secret unavailable: InvalidToken` | The Master Secret has rotated. Reset the shared secret on the connection, and if its value changed, re-share it with the receiving Istari Digital instance. | | `connection failed (no manifest produced): bucket not configured: No RSS object-store configuration for label` | The S3 bucket configuration is not duplicated correctly between the Registry Service and SCS. See [S3 Bucket Management](../../icbs-install/09-secure-connection-service.md#s3-bucket-management). | | `outbox write failed: Revision size= exceeds single-op copy_object ceiling` | The file is larger than the ~2 GB per-file cap and cannot be transferred through a Secure Connection. The file is excluded from sync; other shared files on the connection continue to flow. Support for files larger than 2 GB is planned for a future version. | #### Sync Succeeds, File Not Received 1. On the **Sync status** page, use the **With updates** filter (default) to show sync events that contain newly pushed files. Confirm the resource ID of the affected file appears in a successful sync. If it does, the file has left the sending side cleanly — skip to [Receiving Side Checks](#receiving-side-checks). Switch to **All** if you need every sync event, including those with no resource changes. 2. If the Outbox was changed after the Sending Connection was created, the file may need to be re-published. Unshare the file, wait for the next sync, and re-share it. 3. Confirm the Outbox is configured to the correct S3 bucket. See [S3 Bucket Management](../../icbs-install/09-secure-connection-service.md#s3-bucket-management). ### Receiving Side Checks #### Sync Failures | Error message | Resolution | | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `properties read failed: An error occurred (NoSuchKey) when calling the GetObject operation: The specified key does not exist.` | This can appear if bucket configuration was changed after files were pushed. Ask the sending side to create a new connection to resolve. | | `connection failed (no manifest received)` | Confirm the Shared ID matches the Shared ID on the sending side exactly. Confirm the Inbox is receiving files as expected (i.e. manifest files located in `/shard0/manifest`). See [S3 Bucket Management](../../icbs-install/09-secure-connection-service.md#s3-bucket-management). | | `connection failed (no manifest produced): bucket not configured: No RSS object-store configuration for label` | The S3 bucket configuration is not duplicated correctly between the Registry Service and SCS. See [S3 Bucket Management](../../icbs-install/09-secure-connection-service.md#s3-bucket-management). | | `signature verification failed: HMAC mismatch` | The shared secret on the receiving connection does not match the shared secret on the sending side. Have the sending side re-share the shared secret, then reset it on the receiving connection to the new value. | | `resource skipped: control tag(s) uncovered by any transformation predicate ...` | Files carrying the uncovered tags are skipped (the sync completes as degraded) while other files continue to sync. Set up a transformation covering the incoming control tags on the receiving connection. See [Transformations (Receiving Connections)](./secure-connections.md#transformations-receiving-connections). | | `sync blocked receiver side: sending connection clearance exceeds the local platform max` | The sending connection's Permitted Infosec Level is higher than this platform's maximum level. Ask the sending side to lower it, or raise your maximum. See [Infosec Compatibility Between Platforms](./secure-connections.md#infosec-compatibility-between-platforms). | | `sync blocked receiver side: sending connection clearance is restricted but local platform infosec is disabled` | Infosec is disabled here, so only a connection permitted at US DoD `UNCLASSIFIED` can deliver. See [Infosec Compatibility Between Platforms](./secure-connections.md#infosec-compatibility-between-platforms). | | `sync paused: ... unmapped by the connection's infosec level mapping` | The sender uses a different infosec schema and at least one incoming level has no local mapping yet. Complete the mapping on the receiving connection; the sync resumes on the next cycle. See [Infosec Schema Mapping](./secure-connections.md#infosec-schema-mapping-receiving-connections). | #### Sync Succeeds, File Not Received 1. Confirm the user trying to view the file is a permitted recipient of the receiving connection. See [Permitted Recipients (Receiving Connections)](./secure-connections.md#permitted-recipients-receiving-connections). 2. Confirm the user holds the infosec level and control tags required for the file. 3. If the file is an unparented artifact, follow the steps in [Finding Artifacts Shared to You Individually](../user-guide/secure-connections.md#finding-artifacts-shared-to-you-individually). --- ## Other Issues ### Sync Has Not Run Recently If a connection has not produced a sync event in some time and no error appears in the table above, ask your IT administrator to verify the [Secure Connection Service deployment](../../icbs-install/09-secure-connection-service.md) and review the SCS container logs for signs of misconfiguration. --- ## Receiving Connection Issues ### Incoming Artifacts Are Not Visible If an artifact arrived through a receiving connection but a user cannot find it, see [Finding Artifacts Shared to You Individually](../user-guide/secure-connections.md#finding-artifacts-shared-to-you-individually) in the user guide. --- ## Related Documentation - [Secure Connection Service Setup (IT Admin)](../../icbs-install/09-secure-connection-service.md) — Helm chart, identity provider, S3, and Master Key prerequisites - [Secure Connections (Admin Guide)](./secure-connections.md) - [Secure Connections (User Guide)](../user-guide/secure-connections.md) - [Sharing and Access Control](../user-guide/sharing-and-access.md) --- --- title: Secure Connections sidebar_position: 9 --- # Secure Connections :::note Availability The Secure Connection Service (SCS) must be installed and configured at the infrastructure level before any of the in-product features described here are available. IT administrators should complete the steps in [Secure Connection Service Setup](../../icbs-install/09-secure-connection-service.md) (Helm chart, S3 buckets, Master Key) first. ::: Secure Connections lets your organization exchange resources with partner registries over authenticated, encrypted channels. An outbound **Sending Connection** pushes data you own to a partner; an inbound **Receiving Connection** pulls data a partner pushes to you. **Navigation:** avatar > **Settings** > **Admin** > **Secure Connections** (or go to `/admin/secure-connections`) > **Visibility:** The **Secure Connections** admin section is visible to administrators only. > **For end users:** Once a Sending Connection is configured here, users with Editor access on a file can share it with the partner organization through the file's **Share** dialog. The end-user-facing flow, including all certification prompts and the rules under which files are automatically removed from a connection, is documented in [Secure Connections (User Guide)](../user-guide/secure-connections.md). > **Troubleshooting:** For sync failures, authentication errors, and other operational issues, see [Debugging Secure Connections](./secure-connections-debugging.md). > **Setting up your first connection?** [Configure partner sharing (Secure Connections)](../../tutorials/administer/configure-partner-sharing.md) walks through both sides in order — creating the connection, handing the credentials to the partner administrator, and verifying that a shared model syncs. --- ## Sharing Across Security Boundaries Secure Connections support sharing between Istari instances operating at different **platform maximum infosec levels**, in **either direction** — from a higher environment to a lower one (high to low) or from a lower environment to a higher one (low to high). A common example is a high-side environment releasing unclassified information to a low-side environment: 1. Set up a Sending Connection from the high system to the lower system. 2. Tag the resources to be shared at the appropriate infosec level (e.g. `UNCLASSIFIED`). 3. Share the resources through the connection. > **Your organization owns the process.** Istari facilitates cross-boundary sharing but does not define or replace your organization's release process. > > Customers sharing across security boundaries must define their own process and data security controls governing what data may cross, and are responsible for enforcing them. > > Use the connection's: > > - **Permitted Infosec Level** > - **Tag Rules** > > as guardrails that back your process — for example, cap a high-to-low connection's **Permitted Infosec Level** so only resources tagged at or below that level can sync. ### Infosec Compatibility Between Platforms The two platforms on a connection do not need matching infosec configurations: the receiving platform judges only the sending connection's **Permitted Infosec Level** against the rules below. | Sending side | Receiving platform: infosec disabled | Receiving platform: same schema | Receiving platform: different schema | | ----------------------------------------------------------------------------- | ------------------------------------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------- | | Infosec disabled | Allowed | Allowed; resources arrive at your default level | Allowed; resources arrive at your default level | | Permitted level is US DoD `UNCLASSIFIED` | Allowed | Allowed | Allowed once the incoming level is [mapped](#infosec-schema-mapping-receiving-connections) | | Permitted level is the lowest level of any other schema (e.g. AUS `OFFICIAL`) | Blocked | Allowed | Allowed once the incoming level is [mapped](#infosec-schema-mapping-receiving-connections) | | Permitted level is above the lowest level, at or below your max | Blocked | Allowed | Allowed once every incoming level at or below the permitted level is mapped | | Permitted level is above your maximum level | Blocked | Blocked | Allowed once mapped; each incoming level must map onto a local level at or below your maximum | A blocked same-schema sync fails on the receiving side with a message naming the cause and nothing is received; the fix is to lower the sending connection's permitted level or raise the receiving platform's maximum. A cross-schema sync that needs mapping pauses until the mapping is complete, then delivers on the next cycle. Within the same schema, a resource's level is preserved on arrival; across schemas it becomes whatever local level the mapping assigns. --- ## Page Layout The page is split into two tabs: **Sending Connections** and **Receiving Connections**. Each tab shows a sortable table of configured connections. Use the **Active / All** toggle (top-right of the tab bar) to include archived connections in the list. Administrators can **star** connections they work with often and filter either list to their own starred connections; stars are personal to each administrator. The sync status shown for each connection refreshes about every 60 seconds. Columns common to both tabs: | Column | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | _(status icon)_ | Live sync health. Click to open the [Sync status](#sync-status) detail page. | | **About** | Display name and description of the connection. Archived connections are visually dimmed. | | **Permitted Access** | Whether the connection permits **Edit** or **View** access for shared resources. See [Allow Edit Access](#allow-edit-access). | | **Onward Sharing** | Whether the receiving organization may share received files onward. See [Onward Sharing](#onward-sharing-sending-connections). | | **Shared ID** | Opaque identifier exchanged with the partner platform. | | **Inbox / Outbox** | The object store this connection reads from or writes to. | | _(actions)_ | **Edit connection** (opens the [connection settings page](#connection-settings-page)) and **Archive**. | Sending-only columns: | Column | Description | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Permitted Senders** | Who may share over the connection. Click to [edit](#permitted-senders-sending-connections). | | **Permitted Infosec Level** | Highest infosec level a resource may carry to be shared over the connection (only visible when infosec is enabled). Click to change it inline; see [Permitted Infosec Level](#permitted-infosec-level-sending-connections). | Receiving-only columns: | Column | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | **Permitted Recipients** | Users granted access to files received through the connection. Click to [edit](#permitted-recipients-receiving-connections). | ### Connection Settings Page Clicking **Edit connection** on a row (or a Permitted Senders / Permitted Recipients cell) opens the connection's settings page, which is split into three tabs: - **Details**: **Shared ID**, the object store, **Access Type**, **Onward Sharing**, and the shared secret controls. When infosec is enabled, a sending connection also shows **Permitted Infosec Level** here, and a receiving connection shows [Infosec Schema Mapping](#infosec-schema-mapping-receiving-connections). - **Rules**: [Tag Rules](#tag-rules-sending-connections) on a sending connection, [Transformations](#transformations-receiving-connections) on a receiving connection. - **Permitted Senders** (sending) or **Permitted Recipients** (receiving): who may share over, or access files received through, the connection. Each tab saves independently — there is no single save for the whole page: - **Details** and **Rules** stage your edits locally and contribute their own **Save changes** and **Discard** buttons to the page header. Whichever of the two you are on is the tab those header buttons act upon; **Discard** drops that tab's staged edits. - **Permitted Senders** and **Permitted Recipients** have their own **Save** button within the tab itself, not in the page header. This is also what saves the **Allow all users to share with this sending connection** toggle. - **Name** and **Description** are not on any tab. Edit them inline from the page title using the pencil beside the connection name; they save on their own as soon as you confirm, independently of either mechanism above. --- ## Add a Connection Click **Add Secure Connection** (top-right), then choose **Add Sending Connection** or **Add Receiving Connection**. ### Add a Sending Connection A sending connection pushes resources from this platform to a partner. 1. Fill in **Name** and optionally **Description**. 2. Select an **Outbox** — the object store whose contents are sent to the partner. A warning appears if the chosen outbox is already used by another sending connection. 3. Enter a **Shared ID** — a short identifier for the channel (letters, digits, `.`, `-`, `_` and `/` only; no spaces). **Append unique suffix to Shared ID** is checked by default and appends a random suffix on submit to guarantee uniqueness; clear it to use the identifier exactly as you typed it. See [Nested Shared IDs](#nested-shared-ids) for how `/` is used. 4. Enter and confirm a **Shared Secret** — treat this like a password. It is never retrievable after this dialog closes. 5. Assign **Permitted Infosec Level** (visible and required when infosec is enabled) — the highest infosec level a resource may carry to be shared over this connection. **Create** stays disabled until a level is chosen. See [Permitted Infosec Level](#permitted-infosec-level-sending-connections). 6. Optionally turn on **Allow all users to share with this sending connection**. Off by default: only [Permitted Senders](#permitted-senders-sending-connections) may share files over the connection, and you are added automatically as an edit-level permitted sender. 7. Optionally turn on **Allow Edit Access** — see [Allow Edit Access](#allow-edit-access). When on, users at the receiving organization can run jobs and edit their copy of resources specifically granted "Edit Access" through this connection. 8. Optionally turn on **Allow Onward Sharing** — see [Onward Sharing](#onward-sharing-sending-connections). Off by default; when on, the receiving organization may share files it receives over this connection onward over its own sending connections. 9. Check the certification box confirming this connection will share data with an external organization. 10. Click **Create**. After creation, a credentials screen shows the final **Shared ID** (with its appended suffix) and a masked **Shared Secret** — both copyable. Share these with the partner so they can configure the matching receiving connection. **The secret cannot be retrieved again once you close this screen.** Which resources may flow through the connection is governed by [Tag Rules](#tag-rules-sending-connections), configured from the connection's **Rules** tab after creation. #### Nested Shared IDs A Shared ID may contain `/` to place the share under a subfolder of the outbox bucket — for example `partner-a/models` and `partner-a/artifacts` are two connections that share one bucket while keeping their manifests and content apart. Each segment between slashes must be a real name (`.` and `..` segments are rejected). Give the partner the full slash-separated value; their receiving connection uses it exactly as typed. ### Add a Receiving Connection A receiving connection accepts resources pushed to this platform by a partner. 1. Fill in **Name** and optionally **Description**. 2. Select an **Inbox** — the object store where incoming data lands. A warning appears if the chosen inbox is already used by another receiving connection. 3. Enter the **Shared ID** provided by the sending-side partner. 4. Enter the **Shared Secret** provided by the sending-side partner. 5. Click **Create**. The creating user is automatically set as the initial permitted recipient of the new receiving connection. --- ## Edit a Connection Click **Edit connection** (pencil icon) on a connection row to open the connection's [settings page](#connection-settings-page) on its **Details** tab (`?tab=details`). A link to the settings page with no `?tab=` opens the **Rules** tab instead. Changes are staged as you edit and applied with **Save changes** in the page header; **Discard** drops them. **Name** and **Description** are edited inline from the page title: click the pencil beside the connection name, edit the fields, and save with the check button or Enter. These save immediately rather than being staged behind **Save changes**. Fields on the **Details** tab, staged until you save: - **Inbox / Outbox** — changing the store takes effect going forward; previously synced data stays in place. A sending connection's outbox **cannot be changed while the connection has active shares**; the change is refused until those resources are unshared. Create a second connection on the new object store instead. A connection with no active shares can be re-pointed freely and publishes a fresh manifest into the new outbox on its next cycle. - **Shared Secret** — click **Reset Secret** (sending) or **Update Secret** (receiving) to stage a new value. The new secret is only applied when you click **Save changes**. For sending connections, confirm by entering it twice; for receiving connections, enter the new value provided by the sending side. Sending-only editable fields: - **Permitted Infosec Level** (when infosec is enabled) — see [Permitted Infosec Level](#permitted-infosec-level-sending-connections) below. Lowering it unshares resources already shared above the new level. - **Access Type** — see [Allow Edit Access](#allow-edit-access) below. Changing it from **Edit** to **View** downgrades active Editor shares. - **Onward Sharing** — see [Onward Sharing](#onward-sharing-sending-connections) below. Turning it off revokes every onward share the receiving organization has made from this connection. **Allow all users to share with this sending connection** lives on the connection's **Permitted Senders** tab and saves with that tab's own **Save** button; see [Permitted Senders](#permitted-senders-sending-connections). Tag rules are edited separately on the connection's **Rules** tab; see [Tag Rules](#tag-rules-sending-connections). The **Shared ID** is read-only after creation but can be copied from the Details tab. --- ## Changes That Affect Shared Resources Some edits cascade to resources already flowing through a connection: disabling [Allow Edit Access](#allow-edit-access), lowering the [Permitted Infosec Level](#permitted-infosec-level-sending-connections), saving [Tag Rules](#tag-rules-sending-connections) that block an active share, turning off [Onward Sharing](#onward-sharing-sending-connections), and [archiving](#archive-a-connection) a receiving connection. The platform previews the impact and asks you to confirm it before anything is written: - The confirmation dialog states what the change does, **how many resources it affects** (for example, _3 active shares are blocked by the new rules and will be unshared_), and what the receiving organization loses. - When the preview reports **no affected resources**, an access, infosec-level, or tag-rule change saves immediately with no dialog. Archiving and turning off onward sharing always ask for confirmation. - **Cancel** closes the dialog and leaves your staged edits in place, unsaved. Unshares are delivered to the receiving instance as a revocation request; see [Revocation and Tombstoning](#revocation-and-tombstoning). --- ## Allow Edit Access Every connection carries a ceiling for the **maximum** access the receiving organization may be granted over resources shared through it. Set it with the **Allow Edit Access** switch when you add a sending connection, and change it afterwards with the **Access Type** control on the connection's **Details** tab: - **View**: every resource shared through the connection is view-only. Updates to resources are still shared, but receivers cannot run jobs on or edit them. - **Edit**: Owners and Editors of resources on the sending Istari Digital instance may share a resource at either view or edit. Resources shared at edit can be run as jobs and revised on the receiving copy; those edits stay on the partner's copy and are not sent back. ### Sending Side Open the connection's **Details** tab, set **Access Type** to **Edit** or **View**, then **Save changes**. The connection's **Permitted Access** updates accordingly. The change syncs to the paired receiving connection on the next sync cycle (typically 1–2 minutes). > **Lowering Access Type to View downgrades active Editor shares.** Changing the ceiling from Edit to View downgrades every resource currently shared through the connection at Edit access to View access. See [Changes That Affect Shared Resources](#changes-that-affect-shared-resources). ### Receiving Side On a Receiving Connection, the **Access Type** section is **read-only**. It reflects what the sending organization granted and cannot be changed locally: - **Edit** (granted): _"The sending organization has granted edit access. You can run jobs on resources synced through this connection."_ - **View** (not granted): _"The sending organization has not granted edit access. Resources synced through this connection are view-only."_ --- ## Onward Sharing (Sending Connections) By default a file that arrived over a receiving connection stays inside the receiving organization: its users may share it with each other, but not over their own sending connections. **Allow Onward Sharing** on a sending connection lifts that restriction for the files it sends. It is off by default; set it when you add the connection or change it later on the connection's **Details** tab. When onward sharing is permitted: - The receiving organization may share a received file over any of its own sending connections, subject to that connection's own guardrails (permitted senders, permitted infosec level, tag rules). - An onward share is **capped at the access level the file was received at** — a file received at View can only be shared onward at View. - Onward shares are **revoked automatically** when the original file is revoked, when the receiving connection is archived, or when you turn onward sharing off. Lowering a file's received access from Edit to View revokes its Edit-level onward shares; View-level onward shares stay in place. Each revocation reaches the next organization the same way any other revocation does; see [Revocation and Tombstoning](#revocation-and-tombstoning). The receiving connection shows the sender's decision read-only; it is learned on the first sync after the connection is created or the setting changes. --- ## Permitted Infosec Level (Sending Connections) When infosec is enabled, a sending connection carries a **Permitted Infosec Level**: the highest infosec level a resource may carry to be shared over the connection. It cannot exceed the organization's platform maximum (see [Infosec Levels](./infosec-levels.md)). Set it in the add dialog, on the connection's **Details** tab, or inline from the **Permitted Infosec Level** column of the Sending Connections table. **Lowering** the level unshares every resource currently shared above the new level. Before the change is saved, the platform reports how many shared resources will be unshared and asks you to confirm (see [Changes That Affect Shared Resources](#changes-that-affect-shared-resources)). Each unshared resource is delivered to the receiving instance as a revocation request; see [Revocation and Tombstoning](#revocation-and-tombstoning). --- ## Tag Rules (Sending Connections) Tag rules decide, resource by resource, what may flow through a sending connection based on the control tags the resource carries. Those tags are the need-to-know controls assigned to the Resource and to users; here they also decide whether the Resource may pass. See [Control Tag](../../intro/key-concepts/sharing-security-access-control.md#control-tag). They replace the permitted control tag list and fixed transformation rules that sending connections used in earlier releases. A ruleset is a list of **checks** plus a mandatory **ELSE** rule: - Each check has an **If a resource has** condition over the resource's control tags (no tags, any of a set, all of a set, or any tag not in a set), an optional **Then require** clause, and a verdict of **Allow** or **Block**. - An **Allow** check may also apply tag transformations (add, remove, or map control tags) to the copy that is sent. A **Block** check cannot apply transformations. - **Every check that matches a resource applies to it.** A resource is allowed only when all of its matching checks allow; one matching **Block** check blocks the resource no matter what the other matches say. The order in which checks are listed does not affect the outcome. - The transformations from all matching **Allow** checks are combined and applied together in a single pass (removes, then maps, then adds), so transformations from different checks interact: a map of tag X to tag Y from one check and a remove of tag X from another yield neither tag. - The **ELSE** rule decides every resource that no check matched, so nothing passes through undecided. ### Edit the Ruleset 1. Open a sending connection and go to its **Rules** tab. 2. Add a check with **Add a Check**, or open an existing row to edit it. Multiple rows can be open at once. 3. **Stage changes** commits a row into your local draft. Deleting a row is also local until save. 4. **Save changes** persists the whole ruleset. **Discard** drops every local edit. > **Saving unshares blocked shares.** Saving a ruleset that blocks a resource currently shared through the connection unshares that resource automatically. Before the ruleset is saved, the platform reports how many active shares the new rules block and asks you to confirm; each unshared resource is then delivered to the receiving instance as a revocation request. A ruleset that blocks nothing currently shared saves without a prompt. See [Changes That Affect Shared Resources](#changes-that-affect-shared-resources). ### Test the Ruleset Use **Test ruleset** on the Rules tab to evaluate a hypothetical set of control tags against the ruleset exactly as it appears on screen, including staged edits and edits still open in an editor. Nothing is persisted by a test. The result shows the verdict, the transformations that would apply, and every rule that matched. While an open edit is incomplete, **Run test** is disabled until the edit is finished or cancelled. --- ## Transformations (Receiving Connections) Transformation rules rewrite control tags on resources as they arrive through a receiving connection. The tags left on the received Resource are the same need-to-know controls used inside your organization: a user sees that Resource when they have a role on it and hold every tag it carries. A rule that adds or replaces a tag therefore changes who can see the Resource, so assign the resulting local tags to those users, including permitted recipients. See [Control Tag](../../intro/key-concepts/sharing-security-access-control.md#control-tag). All transformations matching a file are grouped and applied together in a single pass, in this fixed order regardless of the order they are listed: **removes**, then **maps**, then **adds**. Open a receiving connection's settings page and go to its **Rules** tab. Transformations are presented in the same check-table layout as sending-side tag rules, under the column headers **If a resource has** and **Apply transformations**. (The sending-side table uses **If a resource has**, **Then require**, and **With transformations**.) Edits are staged locally until you click **Save changes** in the page header; **Discard** drops them. ### Rule Types | Rule | What it does | | ----------- | ----------------------------------------------------------------------- | | **Add** | Always adds the selected control tag to synced resources. | | **Remove** | Always removes the incoming tag from synced resources. | | **Replace** | Replaces the incoming tag with a local control tag on synced resources. | Each rule requires a **Description** explaining why it exists. - **Predicate** (Replace, Remove): choose from the **incoming tags** sent by the partner platform. - **Value** (Add, Replace): choose from your organization's active local control tags. - A warning is shown if any incoming tags are not covered by a **Remove** or **Replace** rule: _"N incoming control tags need a check"_ and _"The following incoming tags are not removed or replaced. Provide a mapping or syncing will fail."_ Files carrying an uncovered tag are skipped and recorded as per-resource failures (the sync completes as degraded) until a covering rule is added; other files continue to sync. > As part of the Shared Cybersecurity Responsibility Model, administrators are expected to make good-faith mappings from the sending platform's control tags to valid equivalent local tags. --- ## Infosec Schema Mapping (Receiving Connections) When the sending platform uses a different infosec schema than yours, incoming resources carry classification levels your platform does not know. A receiving connection learns the sending platform's level catalog during sync, and administrators translate it from the **Infosec Schema Mapping** section on the **Details** tab of the connection's settings page (shown when infosec is enabled). - Map each **incoming level** onto a **local level** of your own schema. Every incoming level at or below the sending connection's [Permitted Infosec Level](#permitted-infosec-level-sending-connections) must be mapped before resources are imported; the sync pauses until the mapping is complete. - A mapping must target an active local level at or below your platform's maximum level. If a mapping later becomes illegal (for example the local maximum is lowered), the sync pauses until it is corrected. - Incoming levels that disappear from the sender's catalog are pruned from the mapping automatically. - Mapping is unavailable when both platforms use the same infosec schema, since no translation is needed. --- ## Permitted Senders (Sending Connections) A sending connection can restrict who may share files through it. Each sending connection has an **Allow all users to share with this sending connection** toggle: - **On**: any user with Editor access on a file may share it over the connection. - **Off**: only listed permitted senders may share. Everyone else is denied, with no administrator bypass. Permitted senders are assigned one of two levels: - **Edit**: may share files at either View or Edit access. - **View**: may share files at View access only. To manage the list, open the sending connection's settings page and go to its **Permitted Senders** tab (or click the **Permitted Senders** cell in the connections table). Search for users to add them, set each user's level with the View / Edit selector, and click **Save**. When you create a connection with allow-all turned off, you are added automatically as an edit-level permitted sender so the connection is usable immediately. Connections created before this feature existed keep allow-all on, so pre-existing sharing is unaffected until an administrator turns it off. --- ## Permitted Recipients (Receiving Connections) Permitted recipients of a receiving connection (called owners in earlier releases) are granted access to every file that arrives through it, and may reshare those files with other users. Sharing a received file onward over one of your own sending connections is permitted only when the sending organization enabled [Onward Sharing](#onward-sharing-sending-connections) on their side. When a file has been shared with [Edit Access](#allow-edit-access), edit-level permitted recipients will be able to edit the file and grant edit access to other users. > **Classification gating:** Permitted recipients are not automatically assigned the infosec level or control tags carried by an incoming file. A permitted recipient whose own classification does not satisfy the file's infosec level, or who does not hold every control tag the file carries, will not see the file even though the connection grants the underlying view role. To make a file visible to a permitted recipient, an administrator must assign that user the matching infosec level and control tags through the [Administrator Guide](./user-management.md). 1. Open the receiving connection's settings page and go to its **Permitted Recipients** tab (or click the **Permitted Recipients** cell in the connections table). 2. Search for users by name and click to add them. 3. Set each recipient's permission with the **View / Edit** selector; edit-level recipients can edit received files when the connection grants [Edit Access](#allow-edit-access). 4. Remove a permitted recipient by clicking the remove button next to their name. 5. Click **Save**. --- ## Sync status Each active connection displays a sync status icon indicating the health of its most recent synchronization: | Icon | Meaning | | -------- | ----------------------------------- | | Success | Last sync completed without errors. | | Degraded | Sync completed with partial errors. | | Failure | Sync failed. | Click the icon to open the **Sync status** detail page (`/admin/secure-connections/:kind/:connectionId/sync-status`). For help interpreting sync events and resolving failures, see [Debugging Secure Connections](./secure-connections-debugging.md). ### Sync status detail page The page shows a paginated list of sync events for the connection, newest first. - Each row shows how many resources were updated, a preview of the sync message, the timestamp, and the overall status badge. - Click a row (or the chevron) to expand it and see per-resource status, resource IDs, and individual messages. Click any resource ID to copy it. - Click a truncated message to open it in full in a dialog. Use the **With updates / All** toggle to filter sync events. **With updates** (the default) shows only events where at least one resource was modified; **All** includes every sync event. --- ## Revocation and Tombstoning When a user unshares a resource from a **Sending Connection**, the connection: - Stops sending updates for that resource. - Emits a **revocation** signal to the partner. On the paired **Receiving Connection**, the receiving platform honors that signal by **tombstoning** its downstream copy — deleting the copy's content and clearing its metadata, leaving an inert placeholder. The end-user-facing behavior is documented in [Secure Connections (User Guide)](../user-guide/secure-connections.md#revocation-and-tombstoned-files). Feature timeline: - **Sending-side revocation** — supported since the Secure Connection Service shipped in the [2026.05.01 release](/releases/2026-05-01-Release). - **Receiving-side tombstoning** — the platform acting on that revocation, added in the [2026.07.01 release](/releases/2026-07-01-Release). ### What Revocation Does and Does Not Do Revocation tombstones the **registered resource** on the receiving platform, per revision. Every revision — including any the receiver added locally — is emptied of content, and the file's metadata is cleared. Content-bearing operations against a tombstoned resource or revision are refused with **410 Gone**. > **Revocation cannot remove data from the storage inbox.** A Receiving Connection only parses data that has already been placed in an object-store **Inbox**. > > - It does **not** reach back into the Inbox bucket the connection delivered through. > - It cannot delete data the partner exported, downloaded, or forwarded outside the platform. > - Propagating deletion into the Inbox bucket and outside of the platform is the responsibility of the **transfer mechanism** and the partner's own data-handling processes, respectively, not of the revocation signal. ### Audit Logs Revocation is auditable and observable through the same surfaces as every other sync activity: - **Audit logs** — Each revocation the receiving side processes is written to the Secure Connection audit log: - An informational entry when a downstream resource is successfully tombstoned, naming the upstream and downstream resource IDs. - An error entry when a tombstone attempt fails. - A no-op entry for a revocation of a resource that was never received. - **Sync status** — Because revocation is re-emitted each sync cycle and retried idempotently until the tombstone succeeds, a pending or failed tombstone can surface across several consecutive sync events on the [Sync status detail page](#sync-status-detail-page). Expand a row to see the per-resource status and message; once the tombstone lands, subsequent syncs stop retrying it. --- ## Archive a Connection Archiving stops synchronization and hides the connection from the default (**Active**) view. It cannot be undone. - **Sending connection**: files already shared over it are not revoked. The partner keeps its copies, and they no longer receive updates. Unshare any files you want revoked before you archive, because files cannot be unshared from an archived connection. Revocation reaches the partner only through synchronization, which archiving stops permanently: wait until the [Sync status detail page](#sync-status-detail-page) shows each revocation delivered, or the partner confirms the files are tombstoned, before you archive. - **Receiving connection**: every file received over it is archived, and any onward shares made from those files are revoked; see [Onward Sharing](#onward-sharing-sending-connections). 1. Click **Archive** (trash icon) on the connection row. 2. Confirm in the dialog. To view archived connections, switch the **Active / All** toggle to **All**. Archived rows are dimmed and their row actions are disabled. --- --- title: Tenants --- # Tenants A tenant is your company or customer entity on the installation: a group of people and agents that work in Istari together, managed by its own Tenant Administrators. Each person and agent belongs to at most one tenant; see [Membership](../../intro/terminology.md#membership). Platform Administrators manage tenants from the **Tenants** page of the [Platform Admin Console](./console.md), at `/console/tenants`. Tenant Administrators manage their own tenant's people from the Admin Panel's **Users** page instead; see [User Management](./user-management.md). Each tenant has: - a **display name**, which you can change; - a **slug**, a short identifier chosen when the tenant is created, which cannot change afterwards. IT uses it to add people to the tenant; - an optional **description**, which you can change. ## The tenants list The tabs above the table filter by status: **All**, **Active** (the default) and **Suspended**, each with a count. - A grey **Default** chip marks the [default tenant](#make-a-tenant-the-default). - The **Members** count is the number of people in the tenant; agents are not counted. Clicking the count opens the tenant's page, whose **Members** section lists those people. Each row ends with an **Edit** pencil, which opens the tenant's page, and a **⋮** menu: - **Set as default**, disabled on the default tenant's own row with "This is the default tenant." - **Suspend**, or **Reactivate** for a suspended tenant. ## Create a tenant Check the tenants list first, because the tenant may already exist. When the platform is installed or upgraded, it can create a tenant for each organization in your [sign-in provider](../../intro/terminology.md#sign-in-provider) that it was set up to read. Those tenants are ready for sign-in. 1. Click **New tenant**. 2. Enter a **Display name**. 3. Enter a **Slug**: lowercase letters and numbers, with single hyphens between them, up to 63 characters. It cannot change later. 4. Optionally enter a **Description**. 5. Click **Create tenant**. If the slug is taken, the dialog stays open with "A tenant with that slug already exists." under the slug. 6. Ask your IT administrator to add the tenant's people, and give them the slug (**Copy slug** on the tenant's page). IT follows [Adding people to a tenant](../../icbs-install/03-control-plane/10-identity-service/02-Register-Clients-and-Tenants.md#creating-a-tenant-by-hand). For now, adding a person to a new tenant in the web app is refused with a message that the tenant maps to no organization; IT adds them instead. ## Edit a tenant 1. Open the tenant's page from its name or its **Edit** pencil. 2. To rename it, click the pencil beside the name, type the new name, and press Enter. Escape cancels. 3. To change the description, edit the **Description** field and click **Save**. **Discard** drops your changes. The slug shows below the description as a read-only field with a **Copy slug** button. ## Make a tenant the default The default tenant is the one a person joins when no other tenant is named for them. For example, the **Add user** dialog in the Platform Admin Console starts on it. At most one tenant is the default, and it must be active. Choose **Set as default** in the tenant's row menu. The **Default** chip moves at once. A suspended tenant cannot be the default; its **Set as default** is disabled with "Reactivate this tenant before making it the default." :::note Hiding the default-tenant controls If **Set as default** and the **Default** chip are missing, your installation has hidden them. Your IT administrator controls this with the web app setting `VITE_DEFAULT_TENANT_CONTROLS_ENABLED`; `false` hides them. ::: ## Suspend a tenant Suspending a tenant stops its people and agents from signing in. Only a Platform Administrator can suspend a tenant. If the tenant is your own, suspending it suspends you too, and you lose access to the platform. 1. Choose **Suspend** in the tenant's row menu, or click the **Suspend tenant** icon button beside the status in the header of its page. 2. Read the consequences the dialog lists: - Everyone in the tenant, people and agents, is suspended and loses access to the platform. - By default, every membership and role grant in the tenant is revoked. So is every other role those people and agents hold, including the Platform Administrator role. - Reactivating the tenant restores the tenant only; see [Reactivate a tenant](#reactivate-a-tenant). 3. Type the tenant's name, exactly as shown, to enable **Suspend**. 4. Click **Suspend**. Your installation may instead be set to keep memberships and roles when a tenant is suspended. Ask your IT administrator which your installation does. If the default tenant is suspended, the oldest other active tenant becomes the default. Reactivating the suspended tenant does not make it the default again. The dialog stays open with the reason when the suspension is refused: | Situation | Message | | --------------------------------------------------------------------- | ----------------------------------------------------------------------- | | It is the only active tenant | "Cannot suspend the only active tenant. Activate another tenant first." | | It would leave the installation with no active Platform Administrator | "The installation keeps at least one active platform administrator." | ## Reactivate a tenant Choose **Reactivate** in the tenant's row menu, or click the **Reactivate tenant** icon button in the header of its page. There is no confirmation. Reactivating restores the tenant only. Its people and agents stay suspended until an administrator reactivates them. To bring each person back: 1. If they hold no membership (**Reactivate** is disabled for them), grant one: add them with **Add user** in the tenant's **Members** section, or use **Grant membership** on their details page. 2. Reactivate the person from **Users**; see [Reactivate a person](./user-management.md#reactivate-a-person). 3. If their administrator roles were revoked, grant them again; see [Grant an administrator role](./administrators.md#grant-an-administrator-role). ## Manage a tenant's members A tenant's page has a **Members** section below its details, headed **Members (N)**. It is the Platform Admin Console's users list fixed to this tenant: the same search, status tabs, **Add user**, **Add from CSV** and row actions, with no **Tenant** dropdown or column. See [User Management](./user-management.md). --- --- title: Usage Metrics sidebar_position: 8 --- # Usage Metrics Download a CSV report of your tenant's platform usage for a specified date range. Every administrator, Platform Administrators included, gets only their own tenant's report. A Platform Administrator who belongs to no tenant cannot download a report. **Navigation:** avatar > **Settings** > **Admin** > **Usage Metrics** (or go to `/admin/usage`) ## Download Usage Data 1. On the **Usage Metrics** page: - Select a **Start date** using the date picker. - Select an **End date** using the date picker. 2. Click **Download CSV**. 3. A CSV file with usage data for the selected period downloads to your computer. --- --- title: User Management sidebar_position: 2 --- # User Management The **Users** page lists a tenant's people. From it you add people one at a time or from a CSV file, suspend and reactivate them, grant administrator roles, and manage their control tags, classification levels, tool access and keys. Agents are managed on the [Agents](./agents.md) page. **Navigation:** - In the [Admin Panel](../../intro/terminology.md#admin-panel), **Settings** > **Admin** > **Users** (`/admin/users`) shows the people in your tenant. The tenant's name sits under the heading. - Platform Admin Console > **Users** (`/console/users`) shows every tenant's people, for Platform Administrators. See [Platform Admin Console](./console.md). A Tenant Administrator manages the people in their tenant. A Platform Administrator manages everyone. A Platform Administrator who belongs to no tenant sees "Your account belongs to no tenant. Manage users from the Platform Admin Console." in the Admin Panel. This page describes installations with [tenant management](../../intro/terminology.md#tenant-management). If **Settings** > **Admin** > **Users** has an **Invited** tab instead of **Pre-registered**, see [On installations without tenant management](#on-installations-without-tenant-management). ## The list - In the Platform Admin Console, pick a tenant from the **Tenant** dropdown, or leave it on **All tenants**. The dropdown lists active tenants only. - Pick a status tab: - **All** (the default) - **Active**: people who can sign in and have done so - **Pre-registered**: people added who have not signed in yet and are not suspended - **Suspended**: people who cannot sign in until reactivated - Type in the search field to filter the loaded rows by name or email. The heading shows **Users (N)**, or **Users (N+)** when more rows remain; click **Load more** to fetch the next 100. | Column | Shows | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Full Name** | The display name | | **Email** | The email address | | **Tenant** | Platform Admin Console only: the tenant's name, or **No tenant** | | **Status** | **Active**, **Pre-registered** or **Suspended** | | **Admin** | A pill for each administrator role the person holds, such as **Platform Administrator** or **Tenant Administrator**. A Tenant Administrator pill refers to the person's own tenant | | **Control Tags** | Assigned control tags | | **Classification** | Infosec level; shown only when infosec is enabled | | **Last Sign In** | When the person last signed in, or **Never** | **Control Tags** and **Classification** show a dash until the person first signs in. ### Row actions Each row ends with an **Edit user** pencil, which opens the person's details, and a **⋮** menu: - **Make tenant admin** or **Remove tenant admin**; see [Administrators](./administrators.md). - In the Platform Admin Console, **Make platform admin** or **Remove platform admin**. - Below a separator, **Suspend**, or **Reactivate** for a suspended person. Some actions are missing or disabled: - Your own row never offers **Suspend**, **Remove tenant admin** or **Remove platform admin**. When nothing else applies, its menu is disabled. - Any other row with no action for you has no menu. - An action that is blocked for now is disabled, with the reason under its name. ## Add a person A person can hold one membership at a time, so you cannot add someone who belongs to another tenant. 1. Click **Add user** in the top-right. 2. Choose the tenant: - In the Platform Admin Console's **Users** list, pick it in the dialog's **Tenant** dropdown, which starts on the default tenant. - In the Admin Panel, the person joins your tenant. - In a tenant's [**Members** section](./tenants.md#manage-a-tenants-members), they join that tenant. 3. Enter the person's **Email**, **First Name** and **Last Name**. All three are required. 4. Click **Add user**. What happens next depends on whether Istari already knows the person: - If nobody holds that email address yet, the person is created and listed under **Pre-registered** until they first sign in. - If the person already exists and holds no membership, they are granted a membership in the tenant. Until a person first signs in, you cannot assign their control tags, classification, tool access or keys. Istari sends no invitation. Tell the person to sign in; [When someone cannot sign in](#when-someone-cannot-sign-in) describes the account they need. If the person cannot be added, the dialog says why: | Situation | Message | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | A Platform Administrator adds someone who belongs to another tenant | "This person already holds a membership in another tenant." | | A Tenant Administrator adds someone they cannot see, such as someone in another tenant | "This email belongs to someone outside this tenant. Ask a platform administrator for help." | | The person was created, but granting the membership failed | The dialog says so and offers **Retry the grant** | ## Pre-register people from a CSV file 1. In the Platform Admin Console, pick a tenant in the **Tenant** dropdown first. In the Admin Panel, people join your tenant. 2. Click **Add from CSV**, next to **Add user**. 3. Click **Choose CSV file** and pick a file. 4. Check the preview, then click **Pre-register N people**. 5. Wait for the run to finish, review the results, and click **Close**. ### File format The first non-blank row is the header. Header names ignore case, and spaces, hyphens and underscores count as the same character, so `First Name` matches `first_name`. | Column | Header | Notes | | ------------ | -------------------------- | ----------------------------------------------------- | | Email | `email` or `email_address` | Required | | Display name | `display_name` | Optional | | First name | `first_name` | Joined with the last name when display name is blank | | Last name | `last_name` | Joined with the first name when display name is blank | Other columns are ignored and listed in the preview. Example file: ```csv email,first_name,last_name ada@example.com,Ada,Lovelace ``` A file is refused before anything is sent when it: - is larger than 1 MB; - cannot be read as CSV, for example because of an unclosed quote; - is empty, or has no rows below the header; - has no email column; - names the same column twice, for example both `email` and `email_address`; - has more than 1,000 rows. Split it and import each part. ### Preview and results The preview says how many rows were read, how many will be pre-registered and how many will be skipped. A row with an invalid email address, or one that repeats an earlier row's address, is skipped and listed with its reason. Row numbers count every row in the file, blank ones included. While the run continues, the dialog shows "Processed X of N" and stays open. When it finishes, each row has one outcome: | Outcome | Meaning | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Pre-registered** | Nobody held the address; the person was created in the tenant | | **Added** | The person already existed and was granted a membership. For a suspended person the detail reads "This person is suspended; activate them from Users." | | **Already a member** | The person already held a membership in this tenant | | **Refused** | The row was not completed; the detail gives the reason, such as a person who belongs to another tenant, with the same message as in [Add a person](#add-a-person) | Rows skipped in the preview are listed as **Refused** too. Importing the same file again is safe: rows already done come back as **Already a member**. If a person was created but not added to the tenant, the detail ends with "The person was created but not added; import the file again to finish." ## User details The **Edit user** pencil opens the person's details page. **Back to Users** returns to the list. If you cannot see the person, the page reads "This user is not available to you." The page has up to three tabs: **Details**, **Tool access** (for people you administer) and **Access keys**. ### Details tab | Row | Shows | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Status** | **Active**, **Pre-registered** or **Suspended** | | **Display name** | The name given when the person was added, or their email address if none was given. After the person's first sign-in, the name from your sign-in provider. You cannot change it here. | | **Email** | Editable until the person first signs in; see below | | **Tenant** | The person's tenant, or **No tenant** | | **Created** | When the person was added | | **Updated on** | When the person's record last changed | | **Last signed in** | When the person last signed in, or **Never** | Below the rows, a **Roles** section lists roles as checkboxes. A checked box means the person holds the role; clicking a box opens the same confirmation as the row menu, and a box you cannot use shows the reason. See [Administrators](./administrators.md). The **Control Tags** section holds the person's control tags and, when infosec is enabled, their classification. Before the person first signs in, it reads "Available after first signs in." For people you administer, other than yourself, the bottom of the tab shows a **Suspend User** card, or a **Reactivate user** card for a suspended person. ## Suspend a person Suspending stops a person from signing in. Who can suspend whom: - A Platform Administrator can suspend anyone but themselves. - A Tenant Administrator can suspend people in their tenant, except themselves and Platform Administrators. For a Platform Administrator, **Suspend** is disabled with "Only a platform administrator can suspend a platform administrator." 1. Click **Suspend** on the person's row, or on the **Suspend User** card of their **Details** tab. 2. Read the consequences: - The person cannot sign in until reactivated. - Their credentials stop working within thirty seconds. - Memberships and role grants are kept and return when they are reactivated. 3. Click the button labelled **Suspend **. You cannot suspend the last active Platform Administrator; see [Refusals](./administrators.md#refusals). ## Reactivate a person The administrators who can suspend a person can also reactivate them. Reactivating needs the person to hold a membership in an active tenant. If the person holds no membership, **Reactivate** is disabled with "Grant a membership before activating." Grant one first: - **Platform Administrator:** 1. On the person's **Details** tab, click **Grant membership** under the card. 2. Pick an active tenant. If the tenant of their most recently revoked membership is active, it is selected to start with. 3. Click **Grant membership**. **Reactivate** then becomes available. - **Tenant Administrator:** you can grant the membership again only if the person's revoked membership was in your own tenant. Add the person with **Add user**. Otherwise, ask a Platform Administrator. If the person's membership is in a suspended tenant, **Reactivate** is refused with the same message, "Grant a membership before activating." [Reactivate the tenant](./tenants.md#reactivate-a-tenant) first. To reactivate the person, click **Reactivate** on their row, or on the **Reactivate user** card of their **Details** tab. There is no confirmation. Suspending a tenant revokes its memberships by default; see [Suspend a tenant](./tenants.md#suspend-a-tenant). ## Edit an email before first sign-in A Platform Administrator, or a Tenant Administrator of the person's tenant, can correct a pre-registered person's email address: 1. On the **Details** tab, click **Edit email**. 2. Enter the address and click **Save**, or click **Cancel**. An invalid address, or one someone else holds, is refused under the field. Once the person signs in, the address comes from your sign-in provider and can no longer be edited here. If they sign in while you edit, **Save** reports "This person has signed in, so their email can no longer be changed here." ## Manage tool access for a user The **Tool access** tab controls which tools and functions a person can run. It appears for a Platform Administrator, and for a Tenant Administrator of the person's tenant. - **Granted tools** lists each tool the person holds. Expand a tool to see its functions. - To add a tool, search for it with **Add tool** and pick it. A new tool starts with every function selected. - A tool's checkbox selects or clears all its functions. It is checked only when every function is selected. - A tool saved with every function selected also covers functions added to it later. A tool saved with some functions selected covers only those. - To remove a tool, click the **X** beside it. - **Save** replaces the person's tool access with the list as shown. **Discard** drops your changes. If only part of a save succeeds, a message says so and the list reloads to show what the person holds now; review it and save again. Before the person first signs in, the tab reads "Available after first signs in." ## Manage keys for a user The **Access keys** tab lists a person's access keys for programmatic access to the Istari Digital Platform API. A key cannot be generated until the person has signed in; before then, **Generate** fails with "An error occurred while generating the key." To revoke a key, click **Revoke key** on its row and confirm with **Revoke**. To generate a key: 1. Click **Generate Key**. 2. In the **New Access Key** dialog, optionally fill in **Name (optional)**, and set **Expiration**: **30 days**, **90 days**, **180 days**, **1 year (maximum)** (the default), or **Custom date…**. 3. Click **Generate**. The keypair is generated in your browser. 4. Click **Download credentials** and share the file with the person securely. The private key is not shown again. ## Assign Classification Level to a User :::note Availability The **Classification** column and row appear only when Infosec Levels are enabled for your deployment (see [Infosec Levels](./infosec-levels.md)). ::: You can assign a level from the users table **Classification** column or from the person's details: 1. In the users table, find the **Classification** column (or open the person's details). 2. Click the user's current classification level (or **"Set level..."** if none is assigned). 3. A dropdown appears listing all available infosec levels with their color indicators. 4. Select the desired level. 5. The assignment is saved immediately with a confirmation toast. This determines the maximum infosec level the user can view and assign to resources. ## Assign Control Tags to a User Assigning a tag to a user is what lets that user satisfy the need-to-know check on any Resource that carries the same tag. That includes Resources already on the platform and Resources that arrive through a receiving connection after a transformation rule writes a local tag onto them. See [Control Tags](./control-tags.md). 1. In the users table, find the **Control Tags** column (or open the person's details). 2. Click the tags area for the user (shows existing tags as chips, or a small "add" indicator). 3. In the **Edit Control Tags** dialog: - Select or deselect tags using the multi-select list. - Optionally provide a **reason** for the change in the text area. 4. Click **Save**. ## When someone cannot sign in A person who signs in to your sign-in provider but cannot use Istari sees **You don't have access to Istari yet**, with one of these reasons: | Message | What to do | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | "Your sign-in worked, but no account is registered for you here." | [Add the person](#add-a-person) to their tenant. If you added them under a different address, [correct it](#edit-an-email-before-first-sign-in). | | "Your account is registered but belongs to no tenant yet." | A Platform Administrator grants the person a membership; see [Reactivate a person](#reactivate-a-person). | | "Your account has been suspended." | [Reactivate the person](#reactivate-a-person). | | "Your tenant has been suspended." | A Platform Administrator [reactivates the tenant and then each person](./tenants.md#reactivate-a-tenant). | | "Your account could not be matched to a registered user." | Nothing in the Admin Panel resolves this; refer it to your IT administrator. | Adding a person sends no invitation and creates no account in your [sign-in provider](../../intro/terminology.md#sign-in-provider). The person signs in with an account there that meets both conditions: - It is in the organization linked to their tenant. - Its verified email address matches the one you entered. Otherwise Istari does not match their sign-in to the person you added. If they have no such account, ask your IT administrator to [create one](../../icbs-install/10-Zitadel-User-Management/02-creating-new-users.md). ## On installations without tenant management If the **Users** page has an **Invited** tab, your installation does not use tenant management, and the page works as described in this section. ### View users 1. Pick an organization from the dropdown at the top of the page (**Select organization...**). 2. Use the **tabs** to filter the user list: - **All** — every user - **Active** — users who have signed in and are active - **Invited** — users who have been added but have not yet signed in - **Suspended** — deactivated users 3. Each tab shows a **count** of users in that state. 4. Use the **Search** field (placeholder **Search by user name...**) to filter by name or email. The page heading is **Users (N)**. The table is paginated, 10 rows per page by default. The footer shows **Showing N users** when everything fits on one page, or **Showing X-Y of N** when it does not, plus **Items per page:** (**10**, **20**, **30**, or **50**) and **Page X of Y**. The users table displays the following columns: | Column | Description | | ------------------ | ----------------------------------------------------------------------------- | | **Full Name** | The user's display name | | **Email** | The user's email address | | **Updated on** | Date the user was last updated | | **Status** | Active (green check), Invited (yellow clock), or Suspended (red X) | | **Admin** | Green check if the user has admin privileges | | **Control Tags** | Assigned control tags (colored chips) — click to edit | | **Classification** | Infosec level assignment (only shown when infosec is enabled) — click to edit | | **⋯** | Opens **User Details** (**View user details**) | ### Add a new user 1. Pick your own organization in the dropdown; the **Add user** button appears only there. 2. Click **Add user** (+ icon) in the top-right. 3. In the dialog, enter: - **Email** (required) - **First Name** (required) - **Last Name** (required) 4. Click **Invite**. 5. The user will appear in the **Invited** tab until they accept and sign in. ### User Details dialog 1. Find the user in the table. 2. Click the **⋯** button on their row (**View user details**). 3. The **User Details** dialog shows the user's name, email, status, admin flag, control tags, and classification (when infosec is enabled). To edit a user's name, click the pencil icon next to **Name**, update **First name** and/or **Last name**, and click the check icon to save, or the X icon to cancel. The dialog footer provides: - **Deactivate** — deactivate the user (confirm in the **Deactivate User** dialog). The user's status changes to **Suspended** and they can no longer sign in. The button is hidden on your own account and on users who are already **Suspended**. - **Manage Tool Access** — open the tool access controls (the button is hidden unless you are an administrator). - **Manage Keys** — open access key management. - **Close** — close the dialog. :::note Availability **Manage Keys** appears only when the Identity Service is [enabled](../../icbs-install/03-control-plane/10-identity-service/01-Install-and-Configure.md) for your deployment. ::: ### Manage Tool Access 1. Open **User Details** for the user. 2. Click **Manage Tool Access**. 3. In the **Manage Tool Access for {name}** dialog: - Filter the list with **Search tools...**. - Each **tool** is shown as an expandable accordion section with a checkbox that grants the whole tool. The checkbox is indeterminate when only some of that tool's functions are granted. - Within each tool, individual **functions** are listed as checkboxes. - Check or uncheck functions to grant or revoke access. 4. Click **Save**. ### Manage Keys 1. Open **User Details** for the user. 2. Click **Manage Keys**. 3. In the **Access Keys — {name}** dialog: - Each **key** is shown as a row in the table. - Click **Revoke key** on the row and confirm to revoke the key. - Click **Generate Key** to register a new key for the user. - In the **New Access Key** dialog, optionally fill in **Name (optional)** — leave it blank and Istari Digital assigns a name automatically. - Set **Expiration**. The presets are **30 days**, **90 days**, **180 days**, and **1 year (maximum)** (the default). **Custom date…** requires a date; **Generate** stays disabled until you pick one. - Click **Generate**. - On the **Access Key Generated** screen, **copy or download the key immediately** — it will only be shown once. The screen shows **Expires**. Click **Copy** to copy. Click **Download credentials** to download it. ### Assign classification levels and control tags Click a user's **Classification** or **Control Tags** cell in the table, or use **User Details**, and follow [Assign Classification Level to a User](#assign-classification-level-to-a-user) and [Assign Control Tags to a User](#assign-control-tags-to-a-user). Where those steps open the person's details, use the **User Details** dialog. --- --- sidebar_position: 0 title: Web app Guide --- # Web app Guide These guides cover everyday use of the Istari Digital Platform in the **Istari Digital web app**. You can also interact with the platform programmatically using the [Python Client](../icbs-build-python/index.md). The top-level navigation groups browser-based guidance by goal: | Guide | Navigation | Audience | What is covered | | -------------------------------------------- | ---------- | -------------- | ------------------------------------------------------------------ | | [Account](./account/index.md) | Install | All users | Sign up, sign in, reset password | | [Build with no code](../build/02-no-code.md) | Build | All users | Systems, Resources, jobs, versioning, and results in the web app | | [Admin Guide](./admin-guide/index.md) | Admin | Administrators | Users, access policy, agents, integrations, sharing, and reporting | --- --- title: 3D Visual Diff sidebar_position: 13 --- # 3D Visual Diff 3D Visual Diff lets you compare two versions of a 3D model and see what geometry was added, removed, or displaced, without opening the files in external CAD software. ## Starting a comparison 1. Open a 3D model file that has **two or more versions**. 2. In the center panel header, open the **Compare** tab. 3. In the version sidebar, choose the version to use on the **left** and the version to use on the **right**. Versions are listed by revision date. 4. Use **Switch** to swap the left and right selections. The comparison renders in the main viewport. You can orbit and pan to inspect changes from any angle. Zoom is **⌘ + scroll** on macOS and **Ctrl + scroll** on Windows and Linux. ## Supported formats 3D Visual Diff works with mesh-based model files in these formats: - OBJ - STL - GLB - glTF - 3MF - MSH Both versions must be the **same format**. For example, you cannot compare an OBJ file against a GLB file. ## View modes - **Split view** shows the two versions side by side. - **Unified view** combines the versions into a single overlaid model. ## Comparison modes In split view, you can switch how changes are colorized: - **Structural** highlights how the geometry differs between versions: - **Green** is geometry added in the right version. - **Red** is geometry removed from the left version. - **Grey** is geometry that is unchanged. - **Displacement** shows a heat map of how far surfaces moved between versions. Unchanged areas stay neutral. The legend labels the two directions **Recessed** and **Protruding**. A legend in the corner of the viewport reflects the active mode's color scheme. ## Ghost overlay Enable **Ghost overlay** to show one version translucently over the other. When the overlay is on, two opacity sliders control visibility: - **Primary** sets the opacity of the main model. - **Ghost** sets the opacity of the overlaid reference model. ## Slicing Enable **Slice** to cut a cross-section through both models and inspect internal or nested geometry: - Choose the slice axis: **X**, **Y**, or **Z**. - Drag the depth slider to move the slice plane through the model. A picture-in-picture indicator shows the position of the slice plane. ## Saving a snapshot Use **Download comparison image** to capture the current view as a PNG. ## Limits and requirements - Each file must be under **50 MB**. - Both versions must be the **same format**. - If the files cannot be compared, the viewport explains why — for example when the formats differ, a file is too large, or a model contains no geometry to compare. ## Related - [Update a Resource](./update-a-resource.md#compare-versions) — text and image diffs on the **Compare** tab - [View a Resource](./view-a-resource.md) — open a Resource and its **Compare** tab --- --- title: Accept changes sidebar_position: 28 --- # Accept changes A branch can follow the latest version of a Resource, or a Subsystem's baseline or tag. When those move forward, the branch doesn't update by itself. The new versions wait on the **Changes Available** page until an Editor reviews them and commits them to the branch. Resources pinned to a specific version never show up here. See [Directory](./system-tree.md#pin-a-version). ## Open Changes Available When updates are waiting, any of these opens the **Changes Available** page for the selected branch: - **Page header:** click the **Updates available (N)** button (refresh icon) next to **Home | \**. - **Overview** tab: in the **Version control** card, click **View** next to **Review updates available**. - **Commits** page: click **View Changes Available (N)** on the **New changes available** card. See [Commits](./commits.md). - **Latest commit:** open the branch's **Latest** commit and click **View Changes Available (N)** in the **Version Control** card. These entry points only appear for Editors and above, and only on a branch that isn't archived. ## Review and commit the changes 1. On **Changes Available (N)**, review the incoming changes: - The **Version Control** card counts **Changed**, **Added**, and **Removed** items against the branch's latest commit. - The tree marks each changed item. Select a Resource to compare its current version with the incoming one side by side. - Select a Subsystem to see whether it was **Added**, **Changed**, or **Removed**. 2. Click **Commit All** to accept every change, or **Cancel** to go back to **Commits** without changing anything. **Commit All** accepts all the changes together. You can't pick individual items. It creates a commit named **Accept available updates**, which becomes the branch's **Latest** commit, and then opens the **Commits** page. > **Required role:** Editor or above. ## Related - [Commits](./commits.md) - [Directory](./system-tree.md) - [Subsystems](./subsystems.md) --- --- title: Add Resources sidebar_position: 18 --- # Add Resources You add a Resource in two ways. **Upload** stores the file on the Istari Digital Platform. **Connect** registers a Resource whose bytes stay in an external app, such as Google Drive or Windchill. Both start from the **Resources** page. An administrator configures app integrations before **Connect** lists them. See [App integrations](../admin-guide/app-integrations.md). ## Upload files ### Drag and drop 1. Go to the **Resources** page. 2. Drag one or more files from your computer onto the page. A drop zone indicator appears. 3. The **Upload Resources** modal opens. For each entry, fill in: - **Resource name** (required). - **External Identifier** (optional). - **Tags** (optional). - **Infosec Level** (required when infosec is enabled — defaults to the installation's default level; the field is highlighted in red if empty). 4. Click **Upload**. Use **Add more files** to extend the batch before uploading. ### Add resources 1. On the **Resources** page, click **Add resources** in the top-right action bar (or the **+** icon in the left panel header). 2. In the **Add Resources** modal, select the **Upload** tab. 3. Click **Choose Files** and select files from your computer. 4. Complete the upload metadata and confirm. ## Connect an external Resource 1. On the **Resources** page, click **Add resources**. 2. In the **Add Resources** modal, select the **Connect** tab. 3. Choose an **app integration** (for example Google Drive, Teamwork Cloud, PTC Windchill, Dassault Systèmes 3DEXPERIENCE, or Microsoft 365). 4. Fill in the connection form with the required details for that integration. 5. Click **Connect**. The platform creates a metadata Resource that references the external source. To add a new revision of a Resource that is already registered, see [Update a Resource](./update-a-resource.md). ## Related - [Resources](./resources.md) - [Find Resources](./find-resources.md) - [View a Resource](./view-a-resource.md) --- --- title: Branches sidebar_position: 3 --- # Branches Create and switch **branches**, save **commits**, and open **change requests** in the Istari Digital web app. Branches let you change a System's composition while keeping the work isolated and reviewable. For how Resource versions and System branches fit together, see [Version control](../../intro/key-concepts/version-control.md). For a branch's history, see [Commits](./commits.md). :::note Required role Creating branches, committing changes, and merging change requests all require the **Editor** role or above on the System. Viewers can browse branches, commits, and change requests but cannot change them. ::: ## Switch branches 1. In the System's page header, click the chevron next to **Branch | \** to open **Go to Branch**. 2. Search for or select a branch. The System reloads on that branch's latest commit. Click **Branch | \** itself, or **Go to Branches** in the dropdown, to open the **Branches** tab. ## Create a branch _Requires **Editor** or above._ 1. Click **New Branch** in the **Go to Branch** dropdown, or **+ Branch** on the **Branches** tab. 2. In **Create a new branch**, choose the **Source branch** and enter a name for the new branch. 3. Click **Create branch**. Commit work on the new branch, then merge it into another branch with a [change request](#change-requests) when the work is ready. To change what a branch tracks, see [Edit what the branch tracks](./system-tree.md#edit-what-the-branch-tracks). ## Branch options The **Branches** tab lists the System's branches. Its tabs are **Overview**, **Active**, **Archived**, and **All**. Use **Search branches** to find one. Each row shows when the branch was updated and any open change request. Open a branch's options menu (**Branch Options**) for these actions: - **Rename Branch**: opens **Rename branch**. Enter a **New name** and click **Rename branch**. - **View Commits**: opens the branch's [Commits](./commits.md) page. - **Copy Hash to Clipboard**: copies the branch's latest commit ID. - **Archive Branch** or **Restore Branch**: archiving keeps the branch's commits. Restore an archived branch to keep working on it. The default **baseline** branch can't be archived, and you can't change which branch is the default. ## Promote a branch Promoting points a target branch at the same commit as a source branch, for example to move reviewed work into **baseline**. Promote is only available on the [legacy Systems page](./systems.md#legacy-systems-page). In the redesign, merge with a [change request](#change-requests) instead. On the legacy page: 1. Open the branch switcher and select **Go to Branches**. 2. On the source branch's row, click **Promote**. 3. In **Promote branch**, confirm the **Source branch** and choose the **Target branch**. 4. Click **Promote**. ## Commits Each commit records one saved change to a branch: who made it, when, and a commit message. To see a branch's history, open its options menu on the **Branches** tab and select **View Commits**. From there you can open a commit to compare it with the one before it, or **Restore** it (called **Rollback to this commit** on the legacy Systems page). See [Commits](./commits.md). When tracked Resources or Subsystems have newer versions, Editors and above can accept them onto a branch that isn't archived from **Changes Available**. See [Accept changes](./accept-changes.md). ## Change requests ### Create a change request 1. Click **Change Request** in the System's page header. 2. Click **Compare and Create Change Request**. 3. On **Comparing Branches**, choose the **From branch:** (your working branch) and the **Merge to:** branch (the branch you want to update). 4. Enter a **Change Request Title** and an optional **Description**. 5. Review the **System Delta**, which lists the Resources and Systems that were **added**, **removed**, or **changed**. 6. Click **Create Change Request**. You can also start a change request with **Create change request** on any row of the [Commits](./commits.md) page. ### Review and merge _Merging requires **Editor** or above._ The **Change Requests** list has **Open**, **Merged**, and **Closed** tabs and a search box. Each request shows its title, status, and source and target branches. Open a request to see its **Conversation**, **Resources Changed**, and **Commits** tabs. On **Resources Changed**, each entry shows a folder breadcrumb for where the Resource lives in the System. Files that were relocated are labeled **moved**. - To merge, click **Merge Change Request**, add an optional comment, then click **Confirm Merge and Close Change Request**. - To reject the changes, click **Close**, add an optional comment, then click **Confirm Close**. If either branch has moved since the request was opened, merging is blocked until you refresh. This avoids merging a stale comparison. Change requests have no separate approval step: anyone with edit permission can merge or close them. ### What a merge changes After a merge, opening the **Merge to:** branch shows the same Resources as the **From branch:**. You see the same versions, in the same folders, with the same Subsystems. Read the **System Delta** before you merge. Each row is one change the merge makes on the **Merge to:** branch: - **Added.** This Resource or Subsystem is on the working branch. After the merge, it is on the target branch too. - **Removed.** This Resource or Subsystem is on the target branch and not on the working branch. After the merge, it is no longer on the target branch. It stays in an earlier commit on the target branch's [Commits](./commits.md) page. - **Changed.** Both branches include this Resource or Subsystem, at different versions. After the merge, the target branch shows the version from the working branch. The whole file is that version. Two edits of the same text file stay two separate versions. Someone may commit new work on the target branch after you create the working branch. That work stays on the target branch's **Commits** page, but opening the target branch after the merge does not show it. Open that earlier commit to view the work, or **Restore** it if you want the target branch to show it again. To keep both sets of work, add the newer target-branch updates to the working branch before you merge. **Example.** Baseline starts with `requirements.txt` at version 1. You create a branch named `feature` from that baseline. - On `feature`, you commit `requirements.txt` at version 2 and add `bracket.stl`. - A teammate then updates baseline: `requirements.txt` at version 3, and a new file, `notes.txt`. You create a change request from `feature` (**From branch:**) to baseline (**Merge to:**), then merge it. | Resource | Baseline just before the merge | `feature` | Baseline just after the merge | | ------------------ | ------------------------------ | ---------------- | ----------------------------------------------------------------------- | | `requirements.txt` | version 3 | version 2 | version 2, from `feature` | | `bracket.stl` | not on baseline | on `feature` | on baseline | | `notes.txt` | on baseline | not on `feature` | not on baseline; still in the teammate's commit on the **Commits** page | Version 2 and version 3 of `requirements.txt` are not combined into one file. To have version 3, `notes.txt`, and `bracket.stl` together on baseline, add the teammate's updates to `feature` before you merge. ## Programmatic branching To create branches, commit Resources, and open or merge change requests from Python, see [Branching and change requests](../../icbs-build-python/04-branching.md) (`istari-digital-client` 10.14.0 or later). ## Transitioning from configurations and snapshots Branches replace **configurations**, which previous versions of the platform used to manage the set of Resources and Subsystems inside a System. Your existing configurations were not deleted. They were moved to **branches** with the same names the configurations had before. In previous versions, every update to a configuration captured a **snapshot**: a complete picture of the Resources and Subsystems at that moment. Those snapshots now appear as **commits** on the [Commits](./commits.md) page of the branch that replaced your configuration, in the same order they were created. Opening any commit shows the System exactly as it was at that point. Anywhere you previously used a snapshot of a configuration, use a commit on a branch. --- --- title: Commits sidebar_position: 27 --- # Commits Each **commit** records one saved change to a branch: who made it, when, and a commit message. The **Commits** page lists a branch's commits and lets you open, compare, and restore them. ## Open the Commits page The Commits page always shows one branch: the branch you have selected. Open it from any of these places: - **Overview** tab of the System: in the **Version control** card, click **Total commits in \**. - **Activity** tab of the System: select the **Commits** filter, then click **Branch Commits (N)**. - **Branches** tab: open a branch's options menu and select **View Commits**. See [Branches](./branches.md#branch-options). To jump straight to the latest commit instead, click the **Commit** hash in the **Version control** card on **Overview**. To see another branch's commits, use the branch picker under the **Commits** title. The back arrow returns to the System's home page. ## Read the commit list Commits are grouped by day under **Commits on \**, newest first. Each row shows: - The first line of the commit message (click it to open the commit) - The author and how long ago the commit was made - **Latest** on the branch's current commit - The short commit hash Row buttons: - **Restore**: add a new commit with this commit's contents. Not shown on the **Latest** commit. See [Restore a commit](#restore-a-commit). - **Copy ID**: copy the full commit ID. - **Create change request**: open a new change request. See [Change requests](./branches.md#change-requests). When newer Resource or Subsystem versions are waiting to be accepted, a **New changes available** card appears above the list. See [Accept changes](./accept-changes.md). ## Open a commit Click a commit's message to open **Commit #\**. The page shows: - **Authored by**: the author and the commit date - **Commit Message**: the full message - **Version Control**: counts of **Changed**, **Added**, and **Removed** items compared with the previous commit on the branch - The directory as it was at that commit, with changed items marked Select a changed Resource to compare it side by side with its version in the previous commit. Use **Split view** or **Unified view** to change the layout. Use **Show directory** or **Hide directory** to toggle the tree. Click the back arrow to return to the commit list. The first commit on a branch has no previous commit, so it has nothing to compare against. ## Restore a commit **Restore** adds a new commit with the contents of an earlier commit. Nothing in the branch's history is lost. :::note The legacy Systems page calls this action **Rollback to this commit**. ::: 1. On the **Commits** page, click **Restore** on a commit row, or open the commit and click **Restore** in the **Version Control** card. 2. In **Are you sure you want to Restore?**, click **Yes, I am**. After the restore: - A new commit appears at the top of the list as **Latest**, with the restored contents. - The commit you restored stays where it was in the list. - Every commit in between stays listed. The previous **Latest** commit can now be restored too. If someone else changed the branch after you opened the page, the restore is canceled. Review the latest commits and try again. > **Required role:** Editor or above. Archived branches must be restored first. ## Still in the legacy Systems page These commit actions aren't in the redesigned Systems experience yet. Use the legacy Systems page (`/systems`) for them. See [Systems](./systems.md#legacy-systems-page). - **Compare any two commits.** In the legacy page, use **Compare versions** in **Commit history**. The redesign only compares each commit with the one before it. - **Create a branch from an earlier commit.** In the legacy page, use **Create branch from this commit** in **Commit history**. ## Related - [Accept changes](./accept-changes.md) - [Branches](./branches.md) - [Version control](../../intro/key-concepts/version-control.md) --- --- title: Connected Sources sidebar_position: 26 --- # Connected Sources :::note Experimental feature **Connected Sources** is off by default. Enable it under **Application Settings** → **Experimental Features** → **Connected Sources**. The toggle is per browser and is remembered there. See [Settings](./settings.md#application-settings). ::: Connected Sources lets you browse an app integration and connect its items to Istari as resources. Select a folder or a hierarchical model to connect everything under it at once. Only **Teamwork Cloud** app integrations are supported. --- ## Enable Connected Sources 1. Click your **avatar** at the bottom of the sidebar. 2. Select **Application**. 3. Under **Experimental Features**, turn **Connected Sources** on. A **connect** icon appears in the **Resources** panel header. Turn the toggle off the same way to hide it. --- ## Before You Start 1. Ask your administrator to add a Teamwork Cloud app integration. Administrators, see [App Integrations](../admin-guide/app-integrations.md). 2. Add your credentials for that integration in [Linked Accounts](./settings.md#linked-accounts). --- ## Connect Resources 1. Click the **connect** icon in the **Resources** panel header. 2. Select an app integration. 3. Select the items to connect. 4. Click **Connect**. Istari syncs the selected items from the source. Folders and large models can take a while. To check progress, select the resource in the **Resources** panel. Connected resources appear in the **Resources** panel under a sub-header for their integration, such as **Teamwork Cloud**. --- ## Sync a Resource Pull the latest changes from the source into Istari. 1. Open the resource. 2. Click **Sync** in the page header. The **Sync** button shows when the sync is complete. --- ## Edit the Sync Selection Choose which child items are included when a connected resource syncs. 1. In the **Resources** panel, click the **⋯** (more actions) icon on the integration sub-header. 2. Select **Edit Selection**. 3. Check or uncheck items. Unchecked items stop syncing but remain as resources in Istari. 4. Click **Save**. --- ## Disconnect a Source 1. In the **Resources** panel, click the **⋯** (more actions) icon on the integration sub-header. 2. Select **Disconnect**. --- ## Related - [Application Settings](./settings.md#application-settings) — Turn Connected Sources on or off. - [Linked Accounts](./settings.md#linked-accounts) — Add credentials for app integrations. - [App Integrations](../admin-guide/app-integrations.md) — How administrators set up app integrations. --- --- title: Find Resources sidebar_position: 17 --- # Find Resources The **Resources** page lists every Resource you can open. Use the tree to browse, or filter it when the list is long. Header search covers Systems, Jobs, and other types as well — see [Search](./search.md). ## Browse the tree 1. Click **Resources** in the sidebar (or go to `/resources`). 2. The left panel is a tree of your Resources. Scroll to load more. 3. Resources are tree nodes. Only a ZIP archive shows a chevron. Open other artifacts from the **Activity** tab — see [View a Resource](./view-a-resource.md). 4. Click a Resource to open it in the center and right panels. ## Filter the tree 1. On the **Resources** page, click the **Filter resources** icon in the left panel header. 2. The filter dialog opens. Set any combination of: - **Resource Name** - **Description** - **External Identifier** - **Uploaded by** (one or more users) - **Source** — **All Sources** or **Secure Connections** - **Status** — **All**, **Active**, or **Archived** 3. Click **Search** to apply filters to the tree. 4. Active filters appear as removable chips above the tree. Remove individual filters with **×**, or use **Clear All**. ## Search the platform The tree filter only narrows the **Resources** page. To search Systems, Jobs, and modules as well, use the header search bar (or press **⌘ K** / **Ctrl K**) and press **Enter**. Results open at `/search`. See [Search](./search.md). ## Related - [Resources](./resources.md) - [Add Resources](./add-resources.md) - [View a Resource](./view-a-resource.md) --- --- title: Find Systems sidebar_position: 21 --- # Find Systems The **System Dashboard** lists the Systems you can open. To find a System by name or creator, use header search. See [Search](./search.md). ## Browse the System Dashboard 1. Click **Systems** in the sidebar (or go to `/systems-dashboard`). 2. Use the toolbar to change what you see: - **Card** or **List** view - **Sort by:** **Newest first**, **Oldest first**, or **Recently viewed** - **Show favorites only** (star): only the Systems you have starred - **Show archived systems**: switch to archived Systems, then **Show active systems** to switch back 3. Systems load in pages. If more are available, **Load more** appears at the bottom. Each System shows its name, description, creator, creation date, and an **infosec badge** when information security levels are enabled. Click the star to add a System to your favorites. Use **Open this branch:** to open the System on a specific branch. ## Open a System Click a System's card or name. The System's home page opens on **Overview**, on the default branch unless you picked another with **Open this branch:**. To reopen a System you used recently, click the chevron next to **Home | \** in the page header. **Last opened** lists your last five Systems. ## Find your way around a System The page header holds the System's main controls: | Control | What it does | | --------------------------- | ------------------------------------------------------------------------------------------------------ | | **Home \| \** | Return to the System's home page | | **Updates available (N)** | Review newer Resource and Subsystem versions. Editors only. See [Accept changes](./accept-changes.md). | | **Directory** | Browse and edit the branch's Resources, folders, and Subsystems. See [Directory](./system-tree.md). | | **Workflows** | The System's workflow log. See [Workflow log](./workflow-log.md). | | **Change Request** | List, create, and merge change requests. See [Change requests](./branches.md#change-requests). | | **Branch \| \** | Open the **Branches** tab. The chevron next to it switches branches. See [Branches](./branches.md). | The home page has two tabs: - **Overview**: - A live **Directory** card with Resource and Subsystem counts - A **Workflows logs** card - **Details** (classification) - **Version control**: branch, latest commit and author, commit and branch counts, pending change requests, and updates available - **Members**: who has access - **Activity**: a feed of commits, change requests, and System events. Filter by **All activities**, **Commits**, or **Change requests**, or use **Search any activity**. From the **Version control** card, open the [Commits](./commits.md) page or the [Changes Available](./accept-changes.md) page. ## Related - [Systems](./systems.md) - [Manage a System](./manage-a-system.md) - [Directory](./system-tree.md) --- --- title: Folders sidebar_position: 25 --- # Folders **Folders** arrange the Resources in a System's directory. Examples are `engineering/aero/` and `scratch/`. A folder is layout on a branch. You create, move, and rename folders in edit mode, and **Commit Changes** saves them as a commit. See [Directory](./system-tree.md) for adding and removing what the branch tracks. - **Path-based.** A folder is the path of the Resources inside it. An empty folder stays in the tree after you commit. - **Per branch.** The layout belongs to the branch you are editing. Earlier commits keep the layout they were saved with. ## Browse folders 1. Open a System and click **Directory**. 2. Click a **folder** to expand or collapse it. **Expand All Folders** and **Collapse All Folders** are in the tree header's **⋯** menu. 3. Click a Resource to view it. ## Create, move, and rename Folder changes are staged in edit mode until you commit them. **Create a folder** 1. Click **Add new** (**+**) > **Folder**. This opens edit mode if it isn't open already. 2. In **New folder**, enter a **Folder name** and click **Create**. 3. Drag Resources into the folder. An empty folder can be committed. To create a folder inside another, open the folder's row menu and choose **Add New** > **Folder**. Folder names can contain spaces and other characters. The platform stores them and shows the name you entered. The Python client uses an encoded path for the same names. See [Folders in a System](../../icbs-build-python/06-folders.md). **Move Resources** - **Drag** a Resource onto a folder. - Select several Resources and drag them together. - Drag a folder into another folder to nest it. If the target already has a folder with the same name, confirm **Merge folders** to combine them. **Rename a folder** Open the folder's row menu and choose **Edit Name**. In **Rename folder**, enter the new name and click **Rename**. Everything in the folder, including nested folders, moves with the new name. **Remove a folder** Open the folder's row menu and choose **Remove**. If the folder holds files, choose one: - **Move contents up** to keep the files in the parent folder - **Remove files** to remove them along with the folder ## Save folder changes 1. Make your folder and Resource changes in edit mode. 2. Click **Commit Changes**, enter a **Commit Message**, and click **Commit Changes**. This creates a new commit on the branch. 3. To drop your changes instead, click **Cancel**, then **Discard changes**. The System returns to its last commit. > **Required role:** Editor or above on the System. ## What stays the same - **Resource names.** Moving a Resource leaves its name as it is. See [Update a Resource](./update-a-resource.md). - **Access.** A folder does not grant or restrict access. See [Sharing and Access Control](./sharing-and-access.md). - **History.** Earlier commits keep the folder layout they were saved with. ## Related - [Systems](./systems.md) - [Directory](./system-tree.md) - [Branches](./branches.md) --- --- title: Find your way around sidebar_position: 1 --- # Find your way around the web app This page maps the Istari Digital web app itself — what each part of the screen does and where the controls live. For what you can accomplish in the browser and which page covers each task, see [Build with no code](../../build/02-no-code.md). ## Navigation Overview After signing in, the **header** search ( **⌘ K** / **Ctrl K** ) and the **sidebar** on the left provide primary navigation. | Item | Where | Visibility | | ------------------ | ----------------------------------------------------------- | ----------------------------------------------------- | | **Search** | Header — search ( **⌘ K** / **Ctrl K** ) | All users | | **Istari AI Chat** | Left sidebar — full-page chat at `/ai-chat` | When **Istari AI Chat** is on in Application settings | | **Notifications** | Left sidebar — inbox and archive for platform notifications | All users | | **Systems** | Left sidebar — the System Dashboard, branches, and commits | All users | | **Resources** | Left sidebar — individual Resources and artifacts | All users | | **Jobs** | Left sidebar — function executions and tools | All users | | **Agents** | Left sidebar — agents and agent pools | Administrators only | Below the main icons, the sidebar footer holds your **avatar**, which opens the user menu. ## User Menu Click your **avatar** at the bottom of the sidebar. The menu shows your name, email, tenant, and classification level (when infosec levels are enabled), then: - **Settings** — your profile, notifications, application preferences, developer keys and tokens, and linked accounts; see [Settings](./settings.md). - Administrators also find the [Admin Panel](../../intro/terminology.md#admin-panel) there, as an **Admin** group in the Settings navigation. - **Learn more** — opens this documentation in a new tab - **Platform Admin Console** — manage every tenant and user of the installation (Platform Administrators only; see [Platform Admin Console](../admin-guide/console.md)) - **Log out** — sign out of the platform For admin-specific features, see the [Administrator Guide](../admin-guide/index.md). ### On installations without tenant management If Settings lists a **Password** entry, your installation does not use [tenant management](../../intro/terminology.md#tenant-management). There, the avatar menu has no **Platform Admin Console**, and you edit your name and password in Settings; see [Settings](./settings.md#on-installations-without-tenant-management). ## Tips - **Copy a link or ID:** On a System's home page, click the **⋯** menu and choose **Copy System Link**, or click the ID next to the System name. In the **Directory**, a row's **Copy** menu copies its URL, name, link, or ID. - **Navigate with breadcrumbs:** Breadcrumbs at the top of detail pages let you jump back to parent pages. - **Resizable panels:** On the system and files detail pages, drag the divider between panels to resize them. Click the **panel collapse** icon (or press **Cmd+[**) to collapse or expand the left panel. - **Pagination:** The Resources tree loads more as you scroll. Job tables use the controls at the bottom to move between pages and change page size. --- --- title: Jobs and Automation sidebar_position: 8 --- # Jobs and Automation A **Job** represents the execution of a function (tool) on a file. Jobs are used for operations like extracting artifacts, running transformations, and processing data. ## View Your Jobs 1. Click **Jobs** in the sidebar (or navigate to `/jobs`). 2. By default, you see **Jobs** — a table of jobs you have created. 3. The jobs table shows: - **Tool / Function** — the tool and function that was executed - **Job ID** — first 6 characters of the UUID with ellipsis (click to copy the full ID) - **Started On** — the date and time the job was started - **Status** — current job status badge - **Actions** — cancel button for jobs that have not yet reached a terminal state ## View All Jobs (Administrators) 1. Navigate to the **Jobs** page. 2. The page header has **Jobs** and **Tools** for every user. 3. Administrators also see **All Jobs**, which lists the jobs of every user in every tenant. Only a Platform Administrator (on installations without tenant management, an organization administrator) can load the list; for a Tenant Administrator it does not load. ## Create a Job (Run a Function) Users with the **Executor** role (or Editor and above) can create and run jobs on a file when they also have permission for the tool/function. ### From the Resources Page 1. Navigate to **Resources** and select a Resource. 2. In the tab header, click **Create Job** (next to **Download**, **Archive**, and **Share**). 3. In the **Create Job** dialog: - **Tool/Function Combination** — the tool and function to run. - **Select a Tool Version** (if multiple versions are available). - **Configure Parameters** (if the selected function requires input parameters). - **Advanced options** — choose an **Agent** or **Agent Pool** (Automatic by default, or select a specific agent/pool). 4. Click **Execute Function** to start the job. ### From a System Page 1. Open a system, click **Directory**, and select a file. 2. Click **Create a job** to open the **Create Job** dialog. 3. Follow the same steps as above to configure and execute the function. ## Extract Artifacts from a File "Extract" is a specific job type that processes a file to produce viewable artifacts. ### From the Resources Page 1. Select a file that has no preview (you will see a **"No Preview Available"** message). 2. Click the **Extract** button in the empty state. 3. The **Create Job** dialog opens pre-configured for extraction — configure and execute. ### From a System Page 1. Open a system, click **Directory**, and select a model. 2. If the **Preview** tab shows **No Preview Available**, click **Extract**. Otherwise, click **Create a job**. 3. The **Create Job** dialog opens. Configure and execute. > **Required role:** Permission to run jobs on the Resource (Executor, Editor, or above). ## View Job Details 1. From the **Jobs** page: Click the **Tool / Function** link on any job row. 2. From the **Resources** page: open the **Activity** tab and click a job group name in the artifacts browser. 3. The **Job Details** dialog shows: - **Status** with icon - **Job ID** - **Tool Name** and **Function Name** - **Agent Name**, **Agent Assignment**, **Agent ID**, and **Pool Assignment** (when assigned to a pool) - **Started On** date and **Started By** user - **Inputs** section (only visible to the job creator): Lists the input files with name, type, and size. - **Status History**: A collapsible table of all status transitions with timestamps. You can also view job details by navigating directly to `/jobs/:jobId`. ## Cancel a Job You can cancel any job that has not yet finished — that is, any job that has not reached a terminal state (**Completed**, **Failed**, or **Canceled**). 1. Navigate to the **Jobs** page. 2. Find the job you want to cancel. If it has not finished, an **X** (cancel) button is shown in the **Actions** column. 3. Click the **X** to cancel the job. 4. The job status will change to **Canceled**. > **What happens when you cancel a job** > > Canceling sets the job's status to **Canceled** and tells the platform to stop > accepting further status updates and file uploads from that job. However, any > operation already in progress on the agent is allowed to finish. This means: > > - The job may continue running on the agent, but once it is canceled the > platform no longer accepts output from it. Any results or logs the job > produces after cancellation are **not recorded** in the Istari Digital Platform. > - If an in-progress operation modifies an external system (for example, an > `update_tags` operation that updates a model in a connected third-party > application), that change may still complete even though the job is canceled > in the Istari Digital Platform. > > This is the current behavior. We are considering additional capabilities in the > [Integrations SDK](../../connect/04-custom-modules/01-integrations-sdk-intro.md) > that would let modules provide tool-specific handling when a job is canceled — > for example, cleanly stopping or rolling back in-progress work in the underlying tool. > We welcome feedback from customers interested in these additional capabilities. ## Job Statuses | Status | Description | | -------------- | ------------------------------------------------- | | **Created** | Job has been created | | **Pending** | Job is queued, waiting for an agent to pick it up | | **Claimed** | An agent has claimed the job | | **Running** | The job is actively executing | | **Validating** | Output is being validated | | **Uploading** | Results are being uploaded | | **Completed** | Job finished successfully | | **Failed** | Job encountered an error | | **Canceled** | Job was cancelled by a user | | **Unknown** | Status could not be determined | Active jobs (Pending, Claimed, Running, Validating, Uploading) show a **spinner** indicator. When a job **completes successfully**, you will receive a **browser notification** and an **audio cue**. Failed and canceled jobs show a **toast notification** only. ## Tools The **Tools** tab on the **Jobs** page lists the tools and functions available to you based on your access. 1. Navigate to **Jobs** in the sidebar. 2. Click the **Tools** tab in the page header. 3. Browse or search for a tool by name. 4. Click a tool to see its available functions, version, and description. --- --- title: Lineage sidebar_position: 5 --- # Lineage **Lineage** shows how a model or artifact was produced and what it was used to produce. Parent/child relationships are recorded automatically when jobs run: outputs are linked to the input files they consumed. Use lineage to answer questions like: - Which design files and simulation results led to this part? - For a multi-step workflow, what did each step produce and which downstream steps consumed it? ## Concepts - **Parent** — a resource that was used to generate another resource. - **Child** — a resource that was generated from another resource. - **Lineage graph** — the parent/child relationships from the selected resource, in both directions. ## View lineage for a resource 1. Open any model or artifact on the **Resources** page (or from a System Resource tree). 2. In the center panel header, open the **Lineage** tab. 3. The graph reads left to right and is scoped to the revision you have open: - **Parents** are on the left. - The selected revision is in the center. - **Children** are on the right. 4. Click any node to navigate to that resource. From there you can open its **Lineage** tab to continue exploring. Anyone who can open the Resource can open **Lineage**. There is no separate role for the tab. ## Lineage and jobs When a job completes, its output resources are automatically related to the job's input files. Workflows build lineage without extra steps: - Run a job — outputs are linked to inputs. - Chain jobs together — each step's outputs become parents of the next step's outputs. - Open any resource's **Lineage** tab to see the execution graph that produced it. See [Jobs and Automation](./jobs.md) for running and reviewing jobs. ## Sharing and lineage Collaborators with access to the underlying resources see the same lineage you do. File-level permissions still apply — users without access to a particular resource see it in the graph with limited information. See [Sharing and Access Control](./sharing-and-access.md) for sharing details. ## Related - [View a Resource](./view-a-resource.md) — open the **Lineage** tab from the center panel - [Jobs and Automation](./jobs.md) — how jobs create lineage links --- --- title: Manage a System sidebar_position: 22 --- # Manage a System Create a System, edit its details, share it, download it, archive it, or change its settings. What the System contains (Resources, [folders](./folders.md), and Subsystems) is edited in the [Directory](./system-tree.md). System actions are in the **More options** (**⋯**) menu, labeled **System Options**. You can open it from three places: - A System on the **System Dashboard** - The header of the System's home page - The **Directory** tree header ## Create a System 1. On the **System Dashboard**, click **New System**. 2. In the **Create system** dialog: - Enter a **Name** (defaults to "Untitled system"). - Enter a **Description** (required). - Choose **Classifications** when information security levels are enabled. 3. Click **Create**. The new System's home page opens. ## Edit the name, description, or classification 1. Open the **⋯** menu and select **Edit System Details**. 2. Update the **Name**, **Description**, or **Classifications**. 3. Click **Update**. > **Required role:** Editor or above. Changing classification requires Administrator or Owner. ## Copy a link or ID - **⋯** menu > **Copy System Link** copies a link to the System. - On the System's home page, click the **ID** next to the System name to copy the System ID. ## Share a System Select **Share System** from the **⋯** menu, or manage members in **Settings** > **Members**. See [Share a System](./sharing-and-access.md#share-a-system). ## Download a System 1. Open the **⋯** menu and select **Download System**. 2. In **Download system**, optionally check **Include subsystems** to add each tracked Subsystem under its own folder. 3. Click **Download**. A ZIP that keeps the folder structure downloads in the background. The download contains the branch's committed state. It is unavailable while you are editing. To download only some files, see [Directory](./system-tree.md#download-files). :::note Downloads of large files or archives may be blocked by your deployment's download limits. Contact your IT administrator if you have questions about these limits. ::: ## Archive or unarchive a System **Archive** 1. Open the **⋯** menu and select **Archive System**. 2. Click **Archive** to confirm. **Unarchive** 1. On the **System Dashboard**, click **Show archived systems**. 2. Open the System's **⋯** menu and select **Unarchive System**. 3. Click **Unarchive**. > **Required role:** Owner only. ## System settings Click **Settings** in the header of the System's home page. - **Members**: - Add users with **Add users**. - Set each user's role, or remove them. - Click **Save**. - Owners can't be changed. Managing members requires Editor or above. Editors can assign **Viewer** or **Editor**. Assigning **Administrator** requires Administrator or Owner. - **Webhooks**: notify an external service when the System changes. 1. Click **+ Webhook**. 2. Enter a **Title** and choose a **Target** (**HTTP** or **GitLab Pipeline**). 3. Select the **System Events** to send: **New Commit** or **Create New Change Request (Open)**. 4. When you create the webhook, copy its secret. It is shown only once. 5. **Recent Deliveries** lists each delivery and its status. Managing webhooks requires Editor or above. ## Related - [Systems](./systems.md) - [Find Systems](./find-systems.md) - [Directory](./system-tree.md) --- --- title: Notebooks sidebar_position: 6 --- # Notebooks :::note Experimental feature Notebooks is available behind an opt-in toggle. Turn it on under **Application Settings → Experimental Features → Notebooks**. Behavior and labels may change before general availability. ::: A **notebook** is an interactive Python document that lives inside a system. Notebooks use the standard Jupyter `.ipynb` format and run in your browser, so you can write and execute code against the resources in a system without setting up a local environment. A notebook is made up of **code cells** (Python) and **markdown cells** (formatted text), and can reference other files in the same system through `@`-links. Notebooks are files like any other resource in a system: they appear in the system's file tree, are versioned, and follow the same access control as the rest of the system's content. --- ## Create a notebook 1. Open the system you want to add the notebook to and click **Directory**. 2. Click **Add new** (**+**) > **Notebook**. To put it in a folder, use the folder's row menu: **Add New** > **Notebook**. 3. In **Notebook Name**, enter a name and click **Done**. 4. Click **Commit Changes**, enter a message, and click **Commit Changes**. The notebook is added to your staged changes and saved to the branch when you commit. > **Required access:** Write access to the system. A new notebook starts with a single markdown cell so you can describe what it does. --- ## Open a notebook In the system's **Directory**, click any `.ipynb` file. The notebook opens in the main content area as an editor, showing its cells in order with a toolbar across the top. The header shows a **kernel status** indicator that reflects whether the in-browser Python environment is ready, running, or in an error state. --- ## Work with cells A notebook is an ordered list of cells. Each cell is one of two types: - **Code cells** contain Python. They run in the notebook's in-browser kernel and display their output — text, tables, and images — directly beneath the cell. A run counter (for example, `[1]`) shows the order in which cells were executed. - **Markdown cells** contain formatted text. They render as headings, lists, links, tables, and math (LaTeX is supported), giving you a place to document your work. ### Edit a cell Click inside a cell to edit it. Code cells provide Python syntax highlighting and autocompletion; markdown cells show a live preview of the rendered text. ### Add a cell - Click the **+** on the toolbar to add a cell, or - Click a **divider between two cells** to insert a new cell at that position and choose whether it is a code or markdown cell. ### Move or delete a cell Hover over (or focus) a cell to reveal its toolbar, then: - Use the **up / down arrows** to move the cell within the notebook. - Click the **trash** icon to delete the cell. --- ## Run code - **Run one cell:** focus a code cell and click **Run cell**. - **Run the whole notebook:** click **Run all cells** (the play icon) in the header to execute every code cell from top to bottom. While a cell runs, its run indicator shows `[*]`; when it finishes it shows its execution number. Output — including standard output, errors, and rendered results such as HTML or images — appears below the cell. --- ## Reference other resources with `@`-links Notebooks can work directly with the other files in the same system. Inside a code or markdown cell, click **Add link** to open the resource picker and choose a file. This inserts an `@`-reference (for example, `@my_model`). When the notebook runs, each `@`-link resolves to a live Python object for that resource, so you can load and operate on the system's models and artifacts in your code. --- ## Generate, save a cell, and the kernel - On a code cell, **Generate code (⌘G)** asks the assistant to draft Python. On a markdown cell, the same control is **Generate text**. - **Save as resource** on a cell stores that cell's output as a Resource. While it runs, the control reads **Saving…**. - **Restart kernel** is on the kernel status indicator. It is disabled with the tooltip **Kernel busy** while the kernel is working. - **Add files to the kernel** uploads files the notebook can read in the current kernel session. ## Save, discard, and download - **Save** with **Cmd + S** / **Ctrl + S**, or click the **Save** button (it appears once you have unsaved changes). Saving stores a new version of the notebook. - **Discard** reverts the notebook to its last saved version. - **Download** the notebook as a standard `.ipynb` file using the download icon in the header — useful for running it in another Jupyter environment or sharing it outside the platform. > **Required access:** Write access to the system is needed to save changes. Read access is enough to open and view a notebook. --- ## Related - [Systems](./systems.md) — notebooks are files within a system. - [View a Resource](./view-a-resource.md) — details, preview, and versions, including notebooks. --- --- title: Notifications sidebar_position: 14 --- # Notifications The Istari Digital Platform notifies you about jobs and sharing through **toasts** (brief on-screen alerts) and a **Notifications** inbox in the sidebar. :::note Availability **Notifications** is in the sidebar for every signed-in user. Contact your IT administrator if the inbox or toasts are missing. ::: ## Notification inbox **Notifications** appears in the primary sidebar with an unread badge (1–9, or **9+** when there are ten or more unread items). ### Open the inbox Click **Notifications** in the sidebar, or follow **View inbox** from a summary toast. The page has two tabs: - **Inbox** — active notifications (read and unread) - **Archive** — notifications you have archived ### Read a notification Click a notification row to open the detail pane on the right. - Clicking an **unread** notification marks it as read and opens the detail pane. - Clicking a **read** notification opens the detail pane without changing its read state. Unread items show a blue dot beside the row. The page header shows how many notifications are unread. The detail pane shows a summary of the event and an **Open Job**, **Open System**, or **Open Resource** link that navigates directly to the related resource. ### Select and bulk actions Use the checkboxes beside each notification (or **Select all** at the top of the list) to select one or more items. The header shows how many are selected and offers: - **Mark as read** — marks all selected unread items as read - **Archive** (Inbox tab) — moves selected items to the Archive tab - **Restore** (Archive tab) — returns selected items to the Inbox tab - **Clear selection** — deselects all items ### Load more The inbox loads notifications in pages. Click **Load more** at the bottom of the list to fetch older items. ### What appears in the inbox | Event | Description | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Resource access granted | Someone shared a system, file, model, or artifact with you | | Job completed | A job you started finished successfully | | Job failed | A job you started failed | | Secure Connection activity | A partner organization shared a resource with you over a Secure Connection, sent a new revision of one, or revoked one. Sent to the connection's [permitted recipients](../admin-guide/secure-connections.md#permitted-recipients-receiving-connections). | Canceled jobs do not appear in the inbox. ## Notification toasts Notification toasts appear in the bottom-right corner of the Istari Digital web app while you work on other pages. Contact your IT administrator if toasts never appear. ### What triggers a toast | Event | Toast title | | -------------------------------------------------- | ---------------------------- | | A job you triggered completes successfully | **Job completed** | | A job you triggered fails | **Job failed** | | Someone shares a System with you | **System shared with you** | | Someone shares a file, model, or artifact with you | **Resource shared with you** | Toasts include events from the last 30 seconds, so a share that arrives just before you reload can still appear. ### Individual toasts When three or fewer notifications arrive at once, each one appears as its own toast with: - A title describing the event - A description — the job's function name, or the name of the person who shared and the resource name - A **View** button that navigates directly to the job or resource Individual toasts dismiss automatically after ten seconds. ### Summary toast When four or more notifications arrive at the same time, a single summary toast appears instead: - Title: **X new notifications** - **View inbox** — navigates to the notifications inbox (requires the inbox to be enabled by your administrator) - **Expand** — shows the first three as individual toasts; if more remain above the threshold, a new summary appears for those Summary toasts dismiss automatically after fifteen seconds. --- --- title: Resources sidebar_position: 4 --- # Resources A **Resource** is a model, artifact, or other file registered on the Istari Digital Platform. The **Resources** page (`/resources`) is where you work with one Resource at a time: a tree on the left, a viewer in the center, and details on the right. Resources that belong together live in a [System](./systems.md). ## What's in this section | Page | What you do | | ------------------------------------------- | ----------------------------------------------------------------- | | [Find Resources](./find-resources.md) | Browse the tree and narrow it with filters | | [Add Resources](./add-resources.md) | Upload files, or connect a Resource that stays in an external app | | [View a Resource](./view-a-resource.md) | Read details, preview, artifacts, and comments | | [Update a Resource](./update-a-resource.md) | Rename, add a version, compare, download, or archive | | [Lineage](./lineage.md) | See what produced a Resource and what was produced from it | | [3D Visual Diff](./3d-visual-diff.md) | Compare the geometry of two versions of a 3D model | --- --- title: Search sidebar_position: 7 --- # Search The **search bar** sits in the center of the top header on every page. Use it to find systems, resources (models and artifacts), and agents from anywhere in the platform — by name, description, ID, or a set of structured filters. --- ## Open the search bar - **Click** the search bar in the header and start typing, or - Press **Cmd + K** (macOS) or **Ctrl + K** (Windows/Linux) from any page to focus it instantly. The search bar is available everywhere except the Admin area. When the bar is focused, a dropdown opens beneath it showing the filters available for the current scope. --- ## Choose a scope On the left of the search bar is a **scope selector**. It limits what you are searching across: | Scope | Searches | | ----------------- | --------------------------------------- | | **Any** (default) | Systems, resources, and agents together | | **Resources** | Models and artifacts only | | **Systems** | Systems only | | **Agents** | Agents only | Your selected scope is remembered as you navigate between pages, so a search you start on one page carries its scope to the next. --- ## Run a search 1. (Optional) Pick a **scope**. 2. Type a search term. The placeholder — _"Search by UUID, name and description…"_ — hints at what plain text matches: a resource or system **UUID**, a **name**, or a **description**. 3. Submit your search by pressing **Enter** or clicking the **magnifying glass** icon on the right of the bar. ### Filter your search You can narrow results with structured **filter tokens** typed directly into the bar, in the form `token:value` (for example, `owner:alice status:active`). As you type a token, the dropdown suggests values where it can (such as user names for `owner:`). Structured filter tokens are available under the **Resources**, **Systems**, and **Agents** scopes — not under **Any**. The available tokens depend on the scope: | Token | Meaning | Available in | | ---------------------- | -------------------------------------- | -------------------------- | | `owner:` | Who created it | Resources, Systems | | `status:` | `active` or `archived` | Resources, Systems, Agents | | `type:` | `model` or `artifact` | Resources | | `mime:` | MIME type (e.g. `model/stl`) | Resources | | `version:` | Version label (e.g. `v1.0.0`) | Resources | | `display:` | Display name | Resources | | `external_identifier:` | External identifier | Resources | | `children:` | Has child artifacts (`true` / `false`) | Resources | | `parent:` | Has a parent (`true` / `false`) | Resources | | `module:` | Installed module | Agents | | `os:` | Operating system | Agents | | `version:` | Agent version | Agents | | `pool:` | In a pool (`true` / `false`) | Agents | --- ## View results Press **Enter** to open `/search`. The page has one **Search Results** list. The count next to the heading is the number loaded, with a **+** when more matches exist on the server. ### What each result shows Each row shows the matching name, with highlighted text, and enough context to tell systems, resources, jobs, and modules apart. Click a result to open it. ### Paging **Previous**, **Page X of Y**, and **Next** move through the results already loaded. **Load more results** fetches the next set from the server. While that request runs, the button reads **Loading...**. ### Empty and loading states - Before you enter a term, the page reads **Enter a search term to find systems, resources, jobs, and modules.** - Filters without a search term, outside the Resources scope, read **Enter a search term to search all types, or switch to Resources to use these filters.** - While results load, a spinner is shown. - When nothing matches, the list reads **No matching results found.** - If the search fails, the page shows **Failed to search.** and **Retry**. --- ## Clear or close the search - Click the **X** in the search bar to clear your query and filters. Your selected **scope is kept**, so you can immediately start a new search in the same scope. - Press **Escape**, or click anywhere outside the bar, to **close** the dropdown without losing what you typed. --- ## Related - [Systems](./systems.md) — open and manage the systems you find. - [Find Resources](./find-resources.md) — browse and filter the Resources tree. - [View a Resource](./view-a-resource.md) — open a model or artifact from a result. --- --- title: Secure Connections sidebar_position: 10 --- # Secure Connections :::note Availability Secure Connections require a **Sending Connection** configured by an administrator for your deployment. Contact your admin if you do not see the controls described below. ::: Secure Connections let you share an individual resource (a model or an artifact) with a partner organization through a **Sending Connection** that an administrator has already configured. Once a resource is shared through a connection, the Istari Digital Platform keeps the partner's copy in sync as you upload new revisions and produce new artifacts from it. Each share carries an **access level** (either **View access** or **Edit access**) that controls what the partner can do with their copy. View access is read-only; Edit access lets the receiving organization run jobs on the resource and add their own revisions to their copy. The access levels you can pick are bounded by the connection's ceiling, which the sending administrator sets (see [Per-File Access Level](#per-file-access-level-view-vs-edit)). > Secure Connections apply to **models and artifacts** only. Systems cannot be shared through a Secure Connection as a whole. > **File size limit:** Secure Connections cannot transfer individual files larger than ~2 GB. Files above this cap are rejected on the sending side and never reach the partner organization. Support for larger files is planned for a future version. > **Unsharing signals revocation.** The receiving platform attempts to honor revocation by _tombstoning_ its copy of the resource. See [Revocation and Tombstoned Files](#revocation-and-tombstoned-files) below for what this does and what it cannot do. > **Something not working?** If a file is not appearing on the partner side or has stopped syncing, ask your administrator to consult [Debugging Secure Connections](../admin-guide/secure-connections-debugging.md). --- ## See Which Partners a Resource Is Shared With Open the Resource's details pane on the **Resources** page (or from a system branch or commit). The **Connections** row lists the partner organizations currently receiving this resource. If the resource is not shared with any partner, the row shows **None**. --- ## Share a Resource with a Partner Organization 1. Open the resource and click the **Share** button (share icon) in the resource's action bar. 2. The **Share \** dialog opens in user-sharing mode by default. Click **Share with external connection** (globe icon, top-right of the dialog) to switch to Secure Connections sharing. 3. In the **Add organization** field, search for and click the partner organization you want to add. Only sending connections that you have not already added are shown. 4. The selected connections appear under **Connections with access (N)**. To remove one, click the remove button next to its name. 5. For each connection that permits editing, set the **access level** (View or Edit) — see [Per-File Access Level](#per-file-access-level-view-vs-edit) below. 6. Review the certification box and check the required boxes (see [Confirmation Prompts](#confirmation-prompts) below). 7. Click **Share** to save. A toast confirms **External connection sharing updated.** The dialog states: **Sharing with Secure Connections does not cascade; child resources must be manually shared.** To switch back to sharing with internal users, click **Share with users** (people icon, bottom-left). > **Required role:** Editor or above on the resource. --- ## Share from Python Everything the **Share** dialog does is also available in the Python SDK, so sharing can be part of an automated pipeline. `V3Client` in `istari-digital-client` provides: - `list_shareable_sending_connections()` — the connections you may share to, with each connection's access ceiling - `share_file_to_sending_remote()` — share a resource at View or Edit access - `list_sending_remote_shares_for_resource()` — the partners a resource is currently shared to - `revoke_file_from_sending_remote()` — stop sharing The same rules apply as in the web app: models and artifacts only, Editor access on the resource, and the connection's limits are enforced. Sync is asynchronous, so the partner receives the file on the next sync cycle rather than when the call returns. See [Python Client 203 — Share with a partner](../../tutorials/automate/203-share-with-partner.md) for a worked example and the [V3Client reference](../../icbs-build-python/v3/v3-client.mdx#secure-connection-sharing) for signatures. --- ## Confirmation Prompts Because Secure Connections send data to an external organization, every change that adds or removes a partner — or that pushes new content to one — must be explicitly confirmed before it can be saved. The confirmation always appears as an **amber-bordered certification box** inside the dialog, with a checkbox you must tick before the action button enables. ### When Adding a Partner The box lists each partner that will gain access: > This resource will be shared with: > > - _Partner Org A_ > - _Partner Org B_ > > **Confirm External Organization(s) will gain access to this model.** The subject ("this model", "this artifact", "this revision", or "any artifacts produced by this tool run") changes depending on the action. ### When Removing a Partner The box presents a checkbox describing what the partner retains: > **Confirm External Organization(s) will retain their copy of this model and will stop receiving new updates.** Removing a partner from a resource's access list stops future synchronization **and sends a revocation signal** across the connection. On the next sync cycle, the partner's receiving platform attempts to honor it by **tombstoning** its copy — best-effort and eventually consistent, so it is not instantaneous. Revocation **cannot** purge data the partner has already exported, downloaded, or forwarded outside the platform. See [Revocation and Tombstoned Files](#revocation-and-tombstoned-files) below. If your change adds **and** removes partners in a single save, both checkboxes are shown and both must be checked. --- ## Per-File Access Level (View vs. Edit) When you add a connection in the share dialog, that share gets an **access level** that determines what the partner can do with their copy: - **View access** (eye icon) — the partner's copy is read-only. They can view it but cannot run jobs against it or add revisions. - **Edit access** (pencil icon) — the partner can run jobs on their copy and add their own revisions to it. Their edits stay on their copy; they are not sent back to you. The selector that appears for each connection depends on the connection's **Permitted Access**, which your administrator sets on the connection: - If the connection permits editing, a **View access / Edit access** dropdown appears for that row, defaulting to **View access**. - If the connection only permits viewing, the row shows a locked **View access** badge (with the tooltip _"This connection only permits view access."_) and no selector. When you grant **Edit access**, the certification box heading reads **"These External Organization(s) will gain edit access:"** and you must confirm that those organizations will be able to run jobs and edit their copy of this resource. Changing a share's level re-requires confirmation. Re-opening the share dialog shows each connection under **Connections with access** at its saved access level. If an administrator later turns the connection's **Allow Edit Access** off, every share on that connection at Edit access is downgraded to View access automatically; the administrator confirms how many shares are affected before the change is saved. The partner keeps its copy but can no longer run jobs on it or add revisions. --- ## Actions That Automatically Push Data to Partners Once a resource is shared through a Sending Connection, these actions automatically propagate the result to every partner the resource is shared with. Each one shows the same certification box before it can complete: | Action | Certification subject | Where it appears | | ------------------------------------------------ | ----------------------------------------- | ------------------------------------------------------------ | | Upload a new revision of the resource | _this revision_ | **Upload Version** dialog | | Run a function that produces artifacts | _any artifacts produced by this tool run_ | **Function** panel on the resource page | | Extract artifacts from a system branch or commit | _any artifacts produced by this tool run_ | **Extract \?** dialog from a system Resource tree | In every case, the action button (**Upload**, **Execute Function**, **Extract**) stays disabled until the certification checkbox is ticked. If the resource is not shared with any partner, the certification box is not shown and the action proceeds normally. --- ## Finding Artifacts Shared to You Individually On the receiving end, an artifact that is shared on its own — without its parent model — does not appear in the default **Resources** view, which lists models grouped with their child artifacts. You can still find them via the global **Search** by file name. --- ## Working with Resources Received from a Partner When a partner shares a resource with you, what you can do with your copy depends on the access level they granted: - **View access** — the resource is read-only. **Create Job**, **Extract**, and **Add Version** are disabled, with a tooltip explaining the resource is view-only. - **Edit access** — you can run jobs on your copy and add your own revisions. The revision list shows a plus (**+**) button to add a revision, and any artifacts or jobs you create stay local to your instance. ### Local vs. Remote Revisions On an editable received resource, each revision in the versions list carries a **source icon** so you can tell where it came from: - A **router icon** marks a **remote revision** synced from the partner (tooltip _"Source: \"_). - A **home icon** marks a **local revision** you added on your own instance (tooltip _"Revision local to this Istari Digital instance"_). As the partner uploads new revisions on their side, they continue to sync in and appear with the router icon alongside your local revisions. ### Sharing a Received Resource Onward A resource you received from a partner can be shared over one of your own organization's Sending Connections only if the partner enabled **onward sharing** on the connection it arrived through. When they did, the Share dialog lists your sending connections as usual; when they did not, the resource cannot be added to any connection and the dialog says so. An onward share is capped at the access level you received the resource at: a resource received at View can only be shared onward at View. It also depends on the original share staying in place — see [case 3](#3-the-original-share-is-withdrawn) below. ### Lineage Open the **Lineage** tab in the resource details panel to see provenance. A remote-sourced revision connects to a synthetic **Receiving Remote** source node (dashed border, router icon) through an edge labeled **"synced from"**, and the revision you are viewing is marked as the **anchor**. Jobs you run on your copy and the artifacts they produce appear in the same graph as the usual resource → job → artifact chain. --- ## Cases Where a Resource Is Automatically Unshared Sending Connections can enforce up to two limits, both optional, that an administrator sets when configuring the connection (a third case, specific to resources you received from a partner, is covered [below](#3-the-original-share-is-withdrawn)): - A **Permitted Infosec Level**, the maximum classification the connection allows. - A set of **Tag Rules**, checks over the Resource's control tags that yield an **Allow** or **Block** verdict for each Resource. Every check that matches a Resource applies, and one matching Block check blocks the Resource regardless of the other matches. Those tags are the same need-to-know controls assigned to the Resource and to users. See [Control Tag](../../intro/key-concepts/sharing-security-access-control.md#control-tag). Whenever the platform detects that a resource no longer fits within these limits, the resource is removed from that connection automatically. This can happen either by changing the resource or by changing the connection. ### 1. The Resource Outgrows the Connection A resource is **removed from a connection** when one of these changes makes the resource ineligible: - The resource's **infosec level is raised** above the connection's Permitted Infosec Level. - A **control tag change** causes the connection's tag rules to reach a **Block** verdict for the resource. When this happens: - The partner organization **keeps the copy of the resource (and any earlier revisions) it has already received**, but stops receiving any further updates from this connection. - Other Sending Connections whose limits still cover the resource's new classification continue to sync as normal. - The **Connections** row on the resource's details pane updates to reflect the new set of partners. ### 2. The Connection Is Tightened Past Its Shared Resources An administrator can also tighten a Sending Connection so that a resource already shared through it no longer qualifies: - **Lowering the Permitted Infosec Level** below the level of a currently shared resource. - **Saving a tag ruleset** that reaches a **Block** verdict for a currently shared resource. Before the change is saved, the administrator sees how many shared resources it affects and must acknowledge that the partner organization will lose access to them. Once confirmed, every affected resource is **unshared from the connection automatically** — you are not asked to unshare it first. When this happens: - The resource stops receiving any further updates from this connection. - A **revocation request** is sent to the receiving instance so it can lock the transferred files. The partner's copy (and any earlier revisions) may remain readable until the receiving platform honors the revocation by **tombstoning** it — after which each revision's content is deleted and its metadata cleared. See [Revocation and Tombstoned Files](#revocation-and-tombstoned-files) for what this does and what it cannot do. - Other Sending Connections whose limits still cover the resource continue to sync as normal. - The **Connections** row on the resource's details pane updates to reflect the new set of partners. If a resource you own disappears from a connection, check with your administrator whether the connection's limits changed. ### 3. The Original Share Is Withdrawn If you shared a **received** resource onward (see [Sharing a Received Resource Onward](#sharing-a-received-resource-onward)), that onward share is revoked automatically when the partner revokes the original resource, archives the connection it came through, or turns onward sharing off on that connection. If the partner lowers your access to View, an onward share made at Edit is revoked as well; onward shares made at View stay in place. The organization you shared onward with receives a revocation request exactly as if you had unshared the resource yourself. --- ## Revocation and Tombstoned Files When you **unshare** a resource from a Sending Connection, the platform: - Stops sending further updates for that resource - Sends a **revocation** signal across the connection. On the next sync cycle, the partner's receiving platform attempts to honor it by **tombstoning** its copy. ### What a Tombstoned File Is A **tombstoned** file is a received resource whose content has been **revoked**. When the receiving platform processes a revocation, it: - **Deletes each revision's content**, so the bytes can no longer be downloaded. - **Clears the file's metadata**, leaving an empty placeholder. Revocation is applied **per revision**, so every revision of the file is zeroed, including any revision added locally on the receiving side. > **Tombstoning is best-effort and eventually consistent.** Revocation crosses an organizational boundary through the transfer mechanism, so it is not instantaneous: > > - The sending side re-emits the revocation each sync cycle, and the receiving side retries until the tombstone succeeds. > - Until then, the receiving copy may still be readable. > - Revocation of a resource the partner never received is a no-op. ### See Also - [Secure Connections (Admin Guide)](../admin-guide/secure-connections.md#revocation-and-tombstoning) for administrator-facing detail. --- --- title: Settings sidebar_position: 11 --- # Settings Open Settings by clicking your **avatar** at the bottom of the sidebar, then **Settings** (`/settings`). Settings is one page with its own navigation on the left: - **Your account** at the top: your name, email, [tenant](../../intro/terminology.md#tenant), and classification level (when infosec levels are enabled). - **Your settings**: - **Profile** - **Password** (only on installations without tenant management) - **Notifications** - **Application** - **Developer** - **AI Instructions** (when **Istari AI Chat** is on) - **Linked Accounts** Each page has its own address, such as `/settings/developer`. - **Admin**, below your settings: the [Admin Panel](../../intro/terminology.md#admin-panel) pages. This group appears only for administrators. See the [Administrator Guide](../admin-guide/index.md). The profile and password sections below describe installations with [tenant management](../../intro/terminology.md#tenant-management). If Settings lists a **Password** entry, your installation does not use tenant management, and you edit your name and password in Istari; see [On installations without tenant management](#on-installations-without-tenant-management). ## Your Profile Click your avatar > **Settings** > **Profile**. The page shows your **Email**, **Name**, and [**Tenant**](../../intro/terminology.md#tenant), read-only. If infosec levels are enabled, it also shows your **Classification Level** as a read-only badge with your assigned level name and color (set by your admin). Your [sign-in provider](../../intro/terminology.md#sign-in-provider) manages your email and name. To change them, use your account page at your sign-in provider if your installation offers one, or ask your IT administrator. ## Your password Your sign-in provider holds your password. To change or recover it, follow [Reset password](../account/reset-password.md), which starts from the sign-in screen. ## Application Settings 1. Click your avatar > **Settings** > **Application**. 2. In the main preferences card, configure: - **Font size** — select from **Smaller**, **Small**, **Default**, **Large**, or **Larger**. - **Theme Preference** — **System**, **Light**, or **Dark** (toggle group with sun/moon icons). 3. Under **Experimental Features**, toggle optional capabilities (each persists per browser): | Toggle | What it enables | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | **System redesign** | Open the redesigned System Dashboard from the sidebar instead of the legacy Systems page. On by default; see [Systems](./systems.md) | | **Resource redesign** | Open the redesigned resource library overview from the sidebar instead of the legacy resources page (when enabled for the deployment) | | **Notebooks** | Interactive Python (Jupyter) notebooks inside a system — see [Notebooks](./notebooks.md) | | **Istari AI Chat** | An AI assistant you open from the page header — see [Istari AI Chat](../../icbs-build-ai/ai-chat.md) | | **Connected sources** | Lets you browse an app integration and connect its items. Select a folder to connect everything under it at once. | A toggle appears only when the capability is available for your deployment. When your deployment pins a setting, the row shows a **Managed by your deployment** badge and the switch is disabled. When **Istari AI Chat** is on, Application settings also shows **Popped-out window style** under Experimental Features, only in Chromium. **Floating (stays on top)** keeps the popped-out chat above other windows. **Standard window** behaves like any other window. ## AI Instructions When **Istari AI Chat** is on, Settings lists **AI Instructions**, your personal instructions for Istari AI. Its **AI custom instructions** card holds tone, focus, and format guidance added to every chat, up to 2,000 characters. The guidance does not override the assistant's safety rules. An administrator can turn the feature off. - **Save** stores the text. - **Discard changes** drops unsaved edits. - **Clear** removes saved instructions. ## Linked Accounts Click your avatar > **Settings** > **Linked Accounts** (or go to `/settings/linked-accounts`). Two cards: - **Linked accounts** — link an external account so jobs can run authenticated to it on your behalf. You can link more than one account per provider. **Link account** opens a picker grouped under **Sign in with a browser** and **Enter a username and password**. Each linked account has **Reconnect** and **Disconnect**. - **Personal third party API tokens** — store a third-party API token so a job can send it as auth. These tokens are not tied to a provider. **Add API token** creates one. **Delete** removes it. This is separate from the [personal access tokens](#developer-settings--personal-access-tokens) under **Developer**, which authenticate to the Istari Digital Platform itself. ## Developer Settings — Keys :::note Availability **Generate Key** appears under **Developer** when access keys are available for your organization. In that case **Generate New Token** is not shown. Contact your administrator if you expected one of these controls and do not see it. ::: Keys allow programmatic access to the Istari API. ### Generate a Key 1. Click your avatar > **Settings** > **Developer**. 2. Click **Generate Key**. 3. In the **New Access Key** dialog, enter a **Name (optional)**. The helper text reads: "A name helps you recognize this key later. If you leave it blank, Istari assigns one automatically." 4. Choose an **Expiration** — 30, 90, or 180 days, **1 year (maximum)** (selected by default), or a custom date. 5. Click **Generate**. 6. **Copy or download the key immediately** — it will only be shown once. Click **Copy** to copy. Click **Download credentials** to download it. The dialog also shows the key's expiration date. ### View Existing Keys - The **Access Keys** card shows a **Client ID** row. Click it to copy the ID. - The table columns are **Name**, **Key ID**, **Algorithm**, and **Created**. ### Revoke Keys On the key row, click the icon whose tooltip is **Revoke key**. The confirmation title is **Revoke key**. Click **Revoke**. ## Developer Settings — Personal Access Tokens Personal Access Tokens (PATs) allow programmatic access to the Istari API. :::warning Deprecated PATs are deprecated as of the July 2026 release and have been superseded by Keys. As of the August 2026 release, when **Generate Key** is available, no new PATs can be created — existing PATs are unaffected and continue to work until revoked. Support for PATs will be removed from the platform in a future release. Python scripts: [Move a Python script from a PAT to a key](../../icbs-build-python/move-from-pat-to-key.md). The CLI and agents: [PAT → Key Exchange](../../icbs-install/05-CLI/04-exchanging-pat-for-key.md). ::: ### Generate a Token When **Generate Key** is shown, **Generate New Token** is not. Create a Key instead. 1. Click your avatar > **Settings** > **Developer**. 2. Click **Generate New Token**. 3. In the **New Personal Access Token** dialog, enter a **Token Name**. 4. Click **Generate**. 5. **Copy the token immediately** — it will only be shown once. Click **Copy Token** to copy. ### View Existing Tokens - The **Personal Access Tokens** table shows all your tokens with their **name** and **creation date**. - A token created for an agent shows an **Agent** badge next to its name. ### Revoke Tokens - **Remove one token:** Click the icon whose tooltip is **Remove token**. The confirmation title is **Remove Personal Access Token**. Click **Remove**. - **Revoke every token:** When the table has at least one token, **Revoke All Tokens** appears above it. The confirmation title is **Revoke All API Keys**. Click **Revoke All**. ## Developer Settings — Endpoints The **Endpoints** card lists the service addresses used to configure an Istari client. - **API URL** - **Registry URL**, shown only when no API URL is set, or when the registry host differs from the API URL. The row says it is optional, and required only by Istari Digital Python SDK, Agent, and CLI versions released before July 2026 (Python SDK v10 and lower). ## Developer Settings — Version Information The **Version Information** card lists **Registry Service version** and **Frontend version**. **Copy all** copies both lines. The button stays unavailable until both versions are known. ## On installations without tenant management If the Settings page lists a **Password** entry, your installation does not use [tenant management](../../intro/terminology.md#tenant-management). There, you edit your name and change your password in Istari. ### Edit Your Profile 1. Click your avatar > **Settings** > **Profile**. 2. Your **email** is shown as read-only (managed by your sign-in provider). 3. If infosec levels are enabled, your **Classification Level** is shown as a read-only badge with your assigned level name and color (set by your admin). 4. Edit your **First name** and **Last name**. 5. Click **Save Changes**. 6. A confirmation banner appears: "Your new name is saved." ### Change Your Password 1. Click your avatar > **Settings** > **Password**. 2. Enter your **Current Password**. 3. Enter your **New Password** and **Confirm Password**. 4. The form shows **live validation** for password requirements: - At least 15 characters - Uppercase letter - Lowercase letter - And other policy-defined rules 5. Click **Save Password** when all requirements are met. --- --- title: Sharing and Access Control sidebar_position: 9 --- # Sharing and Access Control ## Share a Resource 1. Navigate to **Resources** and select the Resource you want to share. 2. Click the **Share** button (share icon) in the file details action bar. 3. In the **Share \** dialog: - **Search for users** by name using the search field at the top. - You can share with someone outside your company only if they are already registered on this installation and not suspended. Type their full **email address**, then choose the **Invite email user** option below the field. Despite the label, no invitation is sent and no account is created. - For each user, select a **role** from the dropdown: - **Can view** — read-only access - **Can edit** — view and modify access - **Admin** — full access including managing other users' permissions - View the **Shared with** list below. (If the list is empty the header will be **Not shared with anyone**.) 4. Click **Share** to save changes. > The roles you can assign depend on your own role (see [Understanding Roles](#understanding-roles)). ## Share a System ### From the System Options Menu 1. Open the **⋯** menu on a System in the **System Dashboard**, or on the System's home page. 2. Select **Share System**. 3. The **Edit \ Roles** dialog opens. Use the same flow as sharing a file. ### From System Settings 1. Open the System and click **Settings** in the header. 2. On **Members**, click **Add users** to add people, set each member's role, or remove members. 3. Click **Save**. The **Members** card on the System's **Overview** also lists who has access. Its **Share** link opens **Settings**. > **Required role:** Editor or above on the system. Editors can assign **Viewer** or **Editor**. Assigning **Administrator** requires Administrator or Owner. See [Understanding Roles](#understanding-roles). ## Bulk Share Resources on a Branch This feature lets you grant access to **the Resources you select on a branch** in one step, rather than sharing them one at a time. 1. Open a system, select a branch, and click **Directory**. 2. Select the Resources you want to share. Hold **⌘** or **Ctrl** and click to select several, or hold **Shift** to select a range. 3. Click **Share** in the main area. 4. In the **Share selected resources** panel at the bottom: - **Access level to grant** — **View** or **Edit**. - **Users to grant access to** — only users who already have access to the system are available. 5. Click **Grant view access to N users** or **Grant edit access to N users**. With one user selected, the label says **user**. > **Required role:** Editor or above on the system. Users must already have system access to be selected for bulk sharing. ## System Permission Inheritance When you share a system, the role you assign **automatically applies to all models and artifacts** tracked by the system's branches and commits: - A **Viewer** on the system can **view** all tracked models and artifacts. - An **Editor** on the system can **view and edit** all tracked models and artifacts. - **Archive** permissions do **not** cascade from systems — only direct Owners or Administrators on a resource can archive it. This means you can grant a user access to an entire set of tracked files by sharing the system once, rather than sharing each file individually. **Key points:** - If you **remove** a user's system role, their cascaded access to tracked resources is also removed. Any direct access they have on individual files is preserved. - If a file is tracked by **multiple systems**, the user retains access as long as they have a role on at least one of those systems. - Subsystem contents are **not** included — permissions on a parent system do not cascade into subsystem resources. ## Understanding Roles | Role | Can View | Can Edit | Can Share | Can Manage Roles | Can Archive | | ----------------- | -------- | -------- | ------------------- | ---------------- | ----------- | | **Viewer** | Yes | No | No | No | No | | **Editor** | Yes | Yes | Yes (viewer/editor) | No | No | | **Administrator** | Yes | Yes | Yes (all roles) | Yes | No | | **Owner** | Yes | Yes | Yes (all roles) | Yes | Yes | **Role assignment restrictions:** - **Editors** can assign **Viewer** or **Editor** roles (cannot assign Administrator). - **Administrators** and **Owners** can assign any role (Viewer, Editor, Administrator). - **Receiving Connection Owner (view access)** can only assign **Viewer** roles. - **Receiving Connection Owner (edit access)** can assign **Viewer** or **Editor** roles. - **Owners**, **Receiving Connection Owner (view access)**, and **Receiving Connection Owner (edit access)** appear as badges in the access list. None of these can be removed or reassigned — they are controlled by the upstream sharing connection. ## Remove Access 1. Open the sharing dialog for the relevant file or system. 2. Find the user in the **Shared with** list. 3. Click the **Remove** button next to their name. 4. Click **Share** to apply the change. > **Note:** Owners, Receiving Connection Owner (view access), and Receiving Connection Owner (edit access) cannot be removed from the access list — they are controlled by the upstream sharing connection. ## Information Security (Infosec) Levels Infosec levels classify resources by their security sensitivity. This feature must be enabled by an admin (see the [Administrator Guide](../admin-guide/infosec-levels.md)). ### Where Infosec Levels Are Displayed Once enabled by your admin, classification levels appear throughout the platform: - **Global banner** — A colored banner at the top of every page shows the installation's maximum infosec level. - **Avatar menu** and **Settings** — Your personal classification level appears as a colored badge below your name. - **Profile** — A read-only **Classification Level** field shows your assigned level with a shield icon. - **Systems and Resources page headers** — A shield icon displays the resource's current infosec level. - **File details pane** (side panel) — A **"Classification"** property row shows the level inline, with a dropdown to change it if you have permission. - **File and artifact content viewer** — A colored **classification banner** appears below the header bar, labeled "Resource Classification Level." - **Upload dialog** — When uploading new files, each file has an **infosec level selector** that defaults to the installation's default level. Files cannot be uploaded without a level when infosec is enabled (the field is highlighted in red if empty). ### Set Infosec Level on a Resource #### From the Page Header 1. Open a file. 2. Click the **infosec level badge** (shield icon with chevron) in the page header. 3. A dropdown appears listing all levels available to you, each with a colored indicator. 4. Select the desired level. The change is saved immediately. To change a System's level, use **Edit System Details** > **Classifications**. See [Manage a System](./manage-a-system.md#edit-the-name-description-or-classification). #### From the File Details Pane 1. Select a Resource on the **Resources** page or in a System's **Directory**. 2. In the details pane on the right, find the **"Classification"** property. 3. Click the current level to open the dropdown. 4. Select the desired level. A confirmation toast appears. ### Level Restrictions The levels you can assign are restricted by the **lowest of**: - The **platform maximum** level configured by your admin. - The **system maximum** (when setting a level on a file within a system). - Your **personal infosec clearance** (assigned by an admin). If no level has been explicitly assigned, resources inherit the installation's **default infosec level**. > **Required role:** Administrator or Owner on the resource. ## Sharing with Partner Organizations (Secure Connections) Files (models and artifacts) can also be shared with external partner organizations through **Sending Connections** configured by an administrator. Adding a partner, removing a partner, uploading a new revision, and producing new artifacts from a shared file all surface a confirmation prompt before the change is saved. See [Secure Connections](./secure-connections.md) for the full flow, the confirmation prompts, and the cases where files are automatically removed from a connection. > Contact your administrator if Secure Connection controls are missing — the feature requires infrastructure setup and a configured Sending Connection. ## Control Tags A **control tag** is a need-to-know control assigned to a Resource and to users together. When you add a tag to a Resource, only users who hold that tag can open it, in addition to their role. An administrator assigns the tag to those users. The same tags are what a Secure Connection checks. A sending connection's tag rules allow or block the Resource based on the tags it carries. A receiving connection's rules can write local tags onto the copy that arrives, and those tags then decide who can see the received Resource. See [Control Tag](../../intro/key-concepts/sharing-security-access-control.md#control-tag). ### View Control Tags - Tags appear as colored chips on models and artifacts, including when those Resources are listed in a System. - On the **Resources** page, tags are visible in the page header next to the infosec badge. ### Edit Control Tags on a Resource There are two editing flows depending on the context: **From the resource header** (files, artifacts): 1. Click the **tags area** in the resource's header (or the **"add"** button if no tags exist). 2. In the **Edit Control Tags** dialog: - Select or deselect tags using the multi-select list. - Optionally provide a **reason** for the change in the textarea. 3. Click **Save**. **From the file details pane:** 1. In the right panel, find the **Control Tags** property. 2. Click the tags area to open a searchable popover. 3. Toggle tags on or off — changes are saved immediately per toggle. > **Required role:** Administrator or Owner on the resource. --- --- title: Subsystems sidebar_position: 24 --- # Subsystems A System can track other Systems. Those linked Systems appear as **Subsystems** in the directory. Subsystems can nest when a Subsystem tracks Systems of its own. ## View Subsystems 1. Open a System and click **Directory**. 2. **Subsystem** rows appear in the tree with the System's name. 3. Expand a Subsystem to browse its tracked Resources and any nested Subsystems. 4. Click a Subsystem to see its summary: System ID, classification, link details, and which version is tracked. 5. Click a Resource under a Subsystem to preview it. The Subsystem row menu (right-click) has these items: - **View Subsystem** - **Open System** - **Open in New Tab** - **Copy** (URL, name, link, or ID) - **Edit System Details** - **Share** - **Remove** (in edit mode) ## Add or change tracked Systems 1. Open the **Directory** and click the pencil (**Edit system**). 2. In the **Library** pane, open the **Systems** tab. Search for a System, then click **Add** or drag it into the tree. - To create a System and add it in one step, click **Create System**, or choose **Add new** (**+**) > **Subsystem**. 3. For each tracked System, choose a **System version**: **baseline** or a specific **tag**. 4. To stop tracking a System, open its row menu and select **Remove**. 5. Click **Commit Changes**, enter a message, and click **Commit Changes** to save a commit on the branch. You can't add the current System, or a System the branch already tracks. > **Required role:** Editor or above to add, change, or remove tracked Systems. When a tracked Subsystem moves to a newer version, the change appears on the [Accept changes](./accept-changes.md) page. ## Related - [Systems](./systems.md) - [Directory](./system-tree.md) - [Branches](./branches.md) --- --- title: Directory sidebar_position: 23 --- # Directory The **Directory** tab shows what the selected branch tracks: Resources, [folders](./folders.md), and [Subsystems](./subsystems.md). Editing that set and clicking **Commit Changes** saves a new **commit** on the branch. For creating branches and merging them, see [Branches](./branches.md). ## Browse the directory 1. Open a System and click **Directory** in the header. To view a different branch, switch branches first. See [Branches](./branches.md#switch-branches). 2. The tree on the left lists: - **Subsystems**, when the branch tracks other Systems - Tracked Resources, in folders when the branch uses them - Artifacts under the files they were produced from 3. Click a Resource to open it in the main area. The tabs are **Activity**, **Preview**, **Lineage**, and **Compare**. See [View a Resource](./view-a-resource.md). 4. The details panel on the right shows the Resource's metadata and versions. Use **Show details** or **Hide details** to toggle it, and **Expand preview** to give the main area more room. With nothing selected, the details panel summarizes the System and lists its branches under **Branch/Commit History**. Click a branch to switch to it. Tree header controls: - **Search**: filter the tree by name. - **Sort**: **A to Z**, **Z to A**, **Type** (default), **Updated**, or **Change**. - **⋯** menu: **Expand All Folders**, **Collapse All Folders**, and the System actions in [Manage a System](./manage-a-system.md). Right-click a Resource, or use its row menu, for these actions: - **View Resource** - **Open in New Tab** - **Copy** (URL, name, link, or ID) - **Download** - **Share** - **Rename** - **Archive** - **Remove** (in edit mode) To run a job on the selected Resource, click **Create a job**. See [Jobs](./jobs.md). ### Select several items - Hold **⌘** (Mac) or **Ctrl** and click to select several items. - Hold **Shift** and click to select a range. The main area then lists the selected folders, Resources, and Subsystems, with **Download**, **Share**, and **Remove**. ## Edit what the branch tracks 1. Open the **Directory** on the branch you want to change. 2. Click the pencil (**Edit system**) in the tree header, or choose an item from the **Add new** (**+**) menu. Either one opens edit mode, and the pencil reads **Editing system**. 3. Make your changes: - **Add from the library.** The **Library** pane opens next to the tree. On **Resource Library** or **Systems**, search and click **Add**, or drag an item into the tree. - **Add new** (**+**) menu: **Resource**, **Subsystem**, **Folder**, **Upload File**, or **Connect Resources**. **Notebook** appears when [Notebooks](./notebooks.md) are on. - **Remove** an item from its row menu. **Undo remove** brings it back. - **Arrange** Resources into [folders](./folders.md). The **Adds go to \** strip shows where new items will land. Click **Clear add target** to add at the top level instead. 4. Click **Review changes** to see everything you staged under **Added**, **Removed**, and **Changed**. Undo single items, or use **Undo all** for a group. 5. Click **Commit Changes** at the top of the **Library** pane. 6. In **Commit Changes**, enter a **Commit Message** and click **Commit Changes**. To leave without saving, click **Cancel**, then **Discard changes**. **Commit Changes** is disabled when nothing is staged or when the commit would leave the System empty. > **Required role:** Editor or above. ### Pin a version In edit mode, each top-level Resource has a **File version** selector: - **Latest** follows new versions of the Resource. Each new version shows up on the [Accept changes](./accept-changes.md) page. - A specific version keeps the branch on that version. Subsystems have a **System version** selector instead, with **baseline** or a tag. See [Subsystems](./subsystems.md). ## Upload files into a System - **Drag and drop:** drag files from your computer onto the **Directory**. Edit mode opens. - **From the menu:** click **Add new** (**+**) > **Upload File**. In **Add New Resources**, click **Choose Files**. In the **Upload Resources** dialog, fill in metadata such as tags and classification, then click **Upload**. The uploaded files are added to your changes. Click **Commit Changes** to save them to the branch. To link files from an app integration instead, choose **Connect Resources**. See [Connected sources](./connected-sources.md). > **Required role:** Editor or above. ## Accept newer versions When tracked Resources or Subsystems have newer versions, an **Updates available (N)** button appears in the page header. Click it to review the changes and **Commit All**. See [Accept changes](./accept-changes.md). ## Download files - **One file:** open its row menu and select **Download**. - **Several files:** select them, then click **Download** in the main area. - **The whole System:** use **Download System** in the **⋯** menu. See [Download a System](./manage-a-system.md#download-a-system). ## Share Resources on a branch Select Resources in the tree, then click **Share** in the main area. That opens **Share selected resources**. See [Bulk Share Resources on a Branch](./sharing-and-access.md#bulk-share-resources-on-a-branch). ## Related - [Systems](./systems.md) - [Folders](./folders.md) - [Subsystems](./subsystems.md) - [Commits](./commits.md) --- --- title: Systems sidebar_position: 2 --- # Systems A **System** groups related Resources, and optional Subsystems, so you can share, browse, and version them together. **Folders** arrange those Resources in the System's directory. Every System starts with a **baseline** branch. Each saved change to a branch is a **commit**. Click **Systems** in the sidebar to open the **System Dashboard** (`/systems-dashboard`). Open a System to see its home page, with **Overview**, **Directory**, **Workflows**, **Change Request**, and **Branch** in the header. For how Systems relate to Resources, see [Systems and Subsystems](../../intro/key-concepts/systems.md). :::info Redesigned Systems experience The redesigned Systems experience is the default and will become the permanent design. The legacy Systems page is still available for now but will be deprecated soon. See [Legacy Systems page](#legacy-systems-page). ::: ## What's in this section | Page | What you do | | --------------------------------------- | -------------------------------------------------------------------------------- | | [Find Systems](./find-systems.md) | Browse the System Dashboard, open a System, and find your way around its pages | | [Manage a System](./manage-a-system.md) | Create, edit, share, download, archive, or unarchive a System, and its settings | | [Directory](./system-tree.md) | Browse what a branch tracks, edit it, and commit the changes | | [Folders](./folders.md) | Arrange the Resources on a branch into folders | | [Subsystems](./subsystems.md) | Track another System inside this one | | [Branches](./branches.md) | Create and manage branches, and merge them with change requests | | [Commits](./commits.md) | Read a branch's history, compare a commit with the one before it, and restore it | | [Accept changes](./accept-changes.md) | Review newer Resource and Subsystem versions and commit them to a branch | | [Notebooks](./notebooks.md) | Run Python notebooks inside a System | | [Workflow log](./workflow-log.md) | Record a run that happened outside the platform and attach its outputs | ## Legacy Systems page The legacy Systems page is at `/systems`. To make the sidebar open it instead of the System Dashboard, turn off **System redesign** under **Settings** > **Application** > **Experimental Features**. See [Settings](./settings.md#application-settings). A few tasks are still only available on the legacy page: | Task | On the legacy page | | --------------------------------------- | ------------------------------------------------------------------------------------- | | Promote one branch onto another | **Go to Branches** > **Promote**. See [Branches](./branches.md#promote-a-branch). | | Compare any two commits | **Commit history** > **Compare versions**. See [Commits](./commits.md). | | Create a branch from an earlier commit | **Commit history** > **Create branch from this commit**. See [Commits](./commits.md). | | Open job details from a job in the tree | Click the job name. In the redesign, use the [Jobs](./jobs.md#view-job-details) page. | --- --- title: Update a Resource sidebar_position: 20 --- # Update a Resource These actions are on the Resource you have open: rename it, add a version, compare versions, download it, or archive it. Open the Resource from the tree first — see [View a Resource](./view-a-resource.md). ## Rename 1. In the details pane, hover **Resource Name** and click the pencil icon. 2. Type the new name in the inline text field. 3. Press **Enter** or click the checkmark to save. Click **X** to cancel. > **Required role:** Editor, Administrator, Owner, or the original creator. Artifacts cannot be renamed. ## Add a version 1. In **Resource Versions** on the right, click **+** (Add version). You can also drag a file onto the section — it shows **Drop to add version**. 2. In the version modal: - **Upload** tab: drag a file onto the modal, or click **Choose file**. - **Connect** tab: link to an updated external source. 3. Confirm the upload. > **Required role:** Editor, Administrator, Owner, or a Receiving Connection Owner with edit access. View-only remote access cannot add a version. ## Compare versions 1. Select a Resource that has two or more versions and is a previewable type. 2. In the center panel header, open the **Compare** tab. 3. For text, image, and other non-3D types: - Use the left and right version selectors to pick which versions to compare. - Toggle between **Split** and **Unified**. - The diff highlights additions, deletions, and changes. 4. For supported 3D formats, the **Compare** tab shows a colorized visual diff. See [3D Visual Diff](./3d-visual-diff.md). ## Download 1. Click the **Download** icon in the tab header, next to **Share** and **Create Job**. 2. The file downloads to your computer. ## Archive 1. Click the **Archive** icon in the tab header, next to **Share** and **Create Job**. 2. Confirm the archive action in the dialog. > **Required role:** Owner. Archive is not available for artifacts. ## Related - [Resources](./resources.md) - [View a Resource](./view-a-resource.md) - [Add Resources](./add-resources.md) - [3D Visual Diff](./3d-visual-diff.md) --- --- title: Version Control sidebar_position: 16 --- # Version Control Branches, commits, and change requests in the Istari Digital web app are documented on [Branches](./branches.md). For how Resource versions and System branches fit together, see [Version control](../../intro/key-concepts/version-control.md). To do the same work from Python, see [Branching and change requests](../../icbs-build-python/04-branching.md). --- --- title: View a Resource sidebar_position: 19 --- # View a Resource Open a Resource from the tree on the **Resources** page. The center panel shows the Resource, and the right panel shows its details. ## Center panel The center panel header has these tabs: - **Activity** — the artifacts browser (the default tab). Jobs that produced artifacts are listed here. - **Preview** — the file viewer for this Resource. When infosec is enabled, a **classification banner** at the top of the preview shows the Resource's classification level. - **Lineage** — the lineage graph for the selected revision. See [Lineage](./lineage.md). - **Compare** — a diff when the Resource has two or more versions and supports comparison. See [Update a Resource](./update-a-resource.md#compare-versions). For 3D models, see [3D Visual Diff](./3d-visual-diff.md). ## Details The right panel shows: - **Resource Versions** — revisions, with **+** (Add version) to upload a new one. See [Update a Resource](./update-a-resource.md). - **Resource Name** (pencil icon to rename), **Resource ID**, **Revision ID** (copyable). - **Created** date and **Created by**. - **Size**. - **Classification** (editable dropdown when infosec is enabled and you are permitted to change it). - **Control Tags** (editable if permitted). - **Shared with**. - **Connections** — partner organizations receiving the Resource through secure connections, or **None**. Shown when secure connections are configured for your deployment. - **Sync Status** — shown when secure connection partners have access. - **External Version**, **External Identifier**, **Description** — shown only if set. - **Receiving Source** — shown for Resources that arrived over a receiving connection. - **Comments** — a collapsible section with threaded comments. ## Preview The **Preview** tab renders supported file types: | File type | Viewer | | ---------------------------- | -------------------------------------------------------- | | Images (PNG, JPG, GIF, etc.) | Image viewer with pan/zoom | | PDF | PDF viewer | | 3D models | Interactive 3D viewer | | HTML | Rendered HTML | | Markdown | Rendered Markdown | | Text / code files | Text viewer with syntax highlighting and **Copy** button | | JSON | JSON viewer with **Copy** button | | XML | XML viewer | If no preview is available, you see **No Preview Available** with **Extract** (run a function to produce viewable artifacts). See [Jobs and Automation](./jobs.md). ## Artifacts Artifacts are Resources derived from a parent Resource through a job (for example, elements extracted from a ZIP or a model). 1. Select a parent Resource. 2. Open the **Activity** tab. The artifacts browser shows a searchable table. 3. Artifacts are grouped by the job that produced them: - The **tool/function** name that ran (click to view job details). - Each artifact as a row with name, type, and size. 4. Click an artifact to view its details, preview, and metadata. ZIP archives are the tree nodes that expand. Other artifacts open from the **Activity** tab. ## Comments 1. Select a Resource. 2. In the right panel, expand **Comments**. 3. Read existing comments and add new ones. 4. A single comment opens at `/comment/:commentId`. ## Related - [Resources](./resources.md) - [Find Resources](./find-resources.md) - [Update a Resource](./update-a-resource.md) - [Lineage](./lineage.md) --- --- title: Workflow log sidebar_position: 15 --- # Workflow log The **Workflows** tab on a System records runs of work performed _outside_ the Istari Digital Platform — scripts, CI jobs, batch runs — whose outputs are uploaded back to the System. An entry tied to a branch links its output files to the **branch** and **commit** that were active when the run took place. A branchless entry records neither. Outputs stay on the workflow entry until you convert one into a tracked Resource. ## Browse and view entries 1. Open a System and click **Workflows** in the header. The **Workflows logs** card on the System's **Overview** also links here. 2. Entries are listed with title, status, branch, and file count, most recent first. Filter by title, branch (**All branches** or a specific branch), and archive state (**Active** / **Archived** / **All**). 3. Click an entry to view its detail — including **Branch** and **Commit** — and preview or download the output files. ## Create an entry Workflow log entries are created from your external workflow via the SDK. See [External workflow logs](../../icbs-build-python/v3/03-workflow-logs.md). ## Convert an output to a Resource Each output row has **Convert**, which opens **Convert to Resource**. 1. Open the workflow entry and click **Convert** on an output. 2. Set **Display name** and **Resource type** (**Model** or **Artifact**). 3. Choose a **Branch**, or **No branch** to add the Resource to the catalog without tracking it on this System. 4. Click **Convert**. The Resource is then available like any other Resource you uploaded. ## Archive / Restore an entry 1. In the **Workflows** tab, hover over an entry and click the **⋯** menu (or the archive control). 2. Select **Archive entry** (or **Restore entry** if it is already archived). > **Required role:** Editor or above. ## Related - [Directory](./system-tree.md) — the Resources a branch tracks - [Branches](./branches.md) — branches and commits linked from workflow entries - [External workflow logs](../../icbs-build-python/v3/03-workflow-logs.md) — create entries from the SDK