Studio · Yemaya · External Tool Integrations

Purpose#

Admin lane console wired to the @yemaya/orchestration DccRoutingTable: define DCC routes (which external tool handles which production step type, with priority and fallback), validate them, and view the priority-ordered routing table.

Entry points#

• Studio index quick-actions.
• No breadcrumb panel on this page.
• This page links out to /studio/yemaya/pipeline-step-types.
• Embedded as a lane inside /studio/yemaya/api.
• Direct URL / bookmark (signed-in + studio entitlement).

Layout regions#

page.tsx renders ShellLayout active="studio" and:

• Workspace panel (StudioYemayaExternalToolIntegrationsWorkspace, data-yemaya-external-tool-integrations-workspace):
  • <h1> "Yemaya External Tool Integrations Workspace".
  • Summary <p data-yemaya-external-tool-integrations-summary> (DCC routes with priority + fallback).
  • Routes lane — loading / unauthorized / error / ready-form / result.
• Route Map panel (data-yemaya-external-tool-integrations-route-map): <h2> "Route Map" with five entries.
• Quick-action panel: two quickAction links.

States#

• Loading — data-yemaya-eti-loading ("Loading routing table…").
• Unauthorized — 401/403 → data-yemaya-eti-unauthorized with reason "Yemaya workspace scope required to view external tool integrations.".
• Error — non-OK / malformed catalog → data-yemaya-eti-error.
• Ready-form — catalog (dccKinds, stepTypes) loaded; data-yemaya-eti-dccs lists the DCC tools.
• Result — 200 → data-yemaya-eti-result with data-yemaya-eti-count and data-yemaya-eti-routes (each data-yemaya-eti-route).
• Validation error — invalid JSON, empty/non-array routes, or a non-200 POST → data-yemaya-eti-routes-error.

Interactions#

Routes lane#

<form data-yemaya-eti-routes-form>:

• DCC routes (JSON) — <textarea data-yemaya-eti-field-routes> (aria-label "dcc routes json"), seeded with two mesh_generation routes at different priorities.
• Filter by step type (optional) — <input data-yemaya-eti-field-step> (aria-label "step type filter").
• "Validate & resolve routes" submit (data-yemaya-eti-routes-submit) — POSTs { routes, stepType? }.

Route map#

data-yemaya-external-tool-integrations-route-map — five entries:

• /studio/yemaya/external-tool-integrations
• /studio/yemaya/external-tool-integrations/scenes/[sceneId]
• /studio/yemaya/external-tool-integrations/exports/[exportId]
• /studio/yemaya/external-tool-integrations/revisions/[revisionId]
• /studio/yemaya/external-tool-integrations/governance/[policyId]

Quick actions#

• "Open Yemaya Pipeline Step Types workspace" → /studio/yemaya/pipeline-step-types.
• "Back to Studio workspace index" → /studio.

Data & contracts#

• Reads: GET /v1/admin/yemaya/external-tool-integrations (catalog; dccKinds, stepTypes) on mount with buildBffAuthHeaders(), cache: 'no-store'.
• Writes: POST /v1/admin/yemaya/external-tool-integrations/routes → { routes: [{ routeId, stepType, dcc, serverId, toolName, priority, fallbackRouteIds? }] } (priority-ordered).
• Realtime: None.
• Caching: client fetch on mount, no-store; aborted on unmount.
• Auth/role check: admin-scoped, fail-closed; route additionally signed-in + studio via the proxy gate.

Cross-references#

• Workspace source: apps/oshun/web/src/components/studio/StudioYemayaExternalToolIntegrationsWorkspace.tsx
• Route map source: apps/oshun/web/src/components/studio/StudioYemayaExternalToolIntegrationsRouteMap.ts
• Page source: apps/oshun/web/src/app/studio/yemaya/external-tool-integrations/page.tsx
• Embedded in: studio-yemaya-api.md
• Sibling: studio-yemaya-pipeline-step-types.md
• Studio overview: studio-overview.md
• Feature spec: V1/features.md

Open questions / known gaps#

• Routes are entered as raw JSON; verify whether a structured route builder is planned.
• Route-map children (scenes/exports/revisions/governance) are a sitemap contract; confirm which dynamic pages exist.