App Studio Integration

Integration Direction

WorkDesk hosts App Studio apps — the integration is one-directional. WorkDesk is the container; App Studio provides the applications. App Studio apps appear as additional navigation items in the WorkDesk sidebar, making WorkDesk the single entry point for the employee experience.

WorkDesk as a Shell

WorkDesk's navigation sidebar has two sections: core WorkDesk pages (Tasks, History, Notifications, Dashboard) and app-configured pages from App Studio. Administrators assign which App Studio apps appear in a user's WorkDesk navigation, based on the user's role.

Hosting Mechanism

WorkDesk supports two hosting mechanisms for App Studio apps, depending on the app's deployment configuration:

AppShellHost Component

AppShellHost.tsx is the WorkDesk component responsible for rendering a hosted App Studio app. It detects the app's integration type and delegates to the appropriate renderer:

// AppShellHost.tsx — renders App Studio apps in WorkDesk content area
import { MicrofrontendHost } from './MicrofrontendHost';
import { IframeHost }        from './IframeHost';

interface AppConfig {
  appId:         string;
  displayName:   string;
  icon:          string;
  integrationType: 'microfrontend' | 'iframe';
  remoteUrl:     string;        // Module Federation remote entry URL (microfrontend)
  iframeUrl:     string;        // App URL (iframe)
  scope:         string;        // Module Federation scope name
  module:        string;        // Module Federation module name
}

export function AppShellHost({ app }: { app: AppConfig }) {
  if (app.integrationType === 'microfrontend') {
    return (
      <MicrofrontendHost
        remoteUrl={app.remoteUrl}
        scope={app.scope}
        module={app.module}
        authToken={useAuthStore(s => s.token)}
        tenantId={useAuthStore(s => s.tenantId)}
      />
    );
  }

  return (
    <IframeHost
      src={app.iframeUrl}
      appId={app.appId}
      // Passes auth token via postMessage after iframe loads
    />
  );
}

Authentication Passthrough

App Studio apps hosted in WorkDesk receive the user's Passport JWT so they can make authenticated API calls without requiring a separate login:

// IframeHost.tsx — passes auth token to iframe app via postMessage
export function IframeHost({ src, appId }: IframeHostProps) {
  const token = useAuthStore(s => s.token);
  const iframeRef = useRef<HTMLIFrameElement>(null);

  const handleIframeLoad = () => {
    iframeRef.current?.contentWindow?.postMessage(
      {
        type:    'WORKDESK_AUTH',
        token:   token,
        appId:   appId,
        origin:  window.location.origin,
      },
      new URL(src).origin  // only post to the expected app origin
    );
  };

  return (
    <iframe
      ref={iframeRef}
      src={src}
      onLoad={handleIframeLoad}
      sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
      style={{ width: '100%', height: '100%', border: 'none' }}
    />
  );
}

// In the App Studio app — receive the token
window.addEventListener('message', (event) => {
  if (event.data.type === 'WORKDESK_AUTH') {
    authStore.setToken(event.data.token);
  }
});

App Navigation Configuration

Administrators configure which App Studio apps appear in a user's WorkDesk navigation through the WorkDesk admin API. Apps are assigned per-role:

// Admin API — assign App Studio apps to a role's WorkDesk navigation
PUT /api/workdesk/admin/navigation-config
Authorization: Bearer {adminToken}

{
  "roleId": "role-manager-guid",
  "navItems": [
    {
      "appId":       "app-expense-manager",
      "displayName": "Expense Manager",
      "icon":        "fa-receipt",
      "order":       1,
      "integrationType": "microfrontend",
      "remoteUrl":   "https://apps.bizfirstai.com/expense-manager/remoteEntry.js",
      "scope":       "expenseManager",
      "module":      "./App"
    },
    {
      "appId":       "app-hr-portal",
      "displayName": "HR Portal",
      "icon":        "fa-user-tie",
      "order":       2,
      "integrationType": "iframe",
      "iframeUrl":   "https://apps.bizfirstai.com/hr-portal/"
    }
  ]
}

Shared Context Between WorkDesk and Hosted Apps

Micro-frontend apps (Module Federation) share the following context with WorkDesk automatically:

App Loading States