Import archived session history

​

Migrating from embedded OpenGeni

1. Preserve your existing external tenant and user mappings: use the same stable source / tenant externalId with ensureWorkspace, and explicitly onboard each admitted user with addExternalWorkspaceMember. Import routes do not provision workspaces or grant membership.
2. Retain the original title, session creation time, event timestamps, creator, and visibility. Source ISO timestamps support at most millisecond precision; normalize higher-precision dates explicitly and retain originals in your ledger. Import through og.asUser(originalUserId, { source }) to derive the verified external creator/owner. An organization key without asUser creates a workspace-shared, ownerless archive; it cannot create a private archive. visibility: "user_private" requires the verified owning user and the existing organization private-session enablement. Never widen visibility merely to make an import succeed.
3. Re-upload retained files to the destination workspace through uploadFile (or the existing begin/upload/complete APIs). Build a stable old-to-new file ID/reference map and replace file references in event payloads before freezing import requests. Old file IDs, signed URLs, storage paths, and sandbox paths do not become valid in the new deployment.
4. Store a migration ledger mapping source session IDs to returned session IDs, stable importIds, file mappings, exact requests, and acknowledged offsets. The v1 request carries title and creation time, not arbitrary source metadata; keep additional metadata in that host-owned ledger.

// Server only; og and source come from your backend setup.
import {
  importArchivedSession,
  appendArchivedSessionEvents,
  type ImportArchivedSessionRequest,
  type AppendArchivedSessionEventsRequest,
} from "@opengeni/sdk/session-history-import";

const actor = og.asUser(legacy.creatorExternalId, { source });
const importRequest = {
  importId: `embedded:${legacy.id}`, // Stable, at most 200 characters.
  title: legacy.title,
  createdAt: legacy.createdAt, // Original ISO timestamp, not migration time.
  visibility: legacy.visibility, // "workspace_shared" or "user_private".
  events: [],
} satisfies ImportArchivedSessionRequest;

await migrationLedger.saveImportRequest(importRequest); // Persist before sending.
const imported = await importArchivedSession(actor, workspaceId, importRequest);
await migrationLedger.saveImportReceipt(imported);

const batchRequest = {
  batchId: nextBatch.id, // Stable, at most 200 characters; persist the exact body.
  offset: imported.nextOffset, // Zero-based event count, not an event sequence.
  events: nextBatch.events, // Non-empty, prepared with destination file references.
} satisfies AppendArchivedSessionEventsRequest;
await migrationLedger.saveBatchRequest(batchRequest);
const appended = await appendArchivedSessionEvents(
  actor,
  workspaceId,
  importRequest.importId,
  batchRequest,
);
await migrationLedger.saveBatchReceipt(appended); // Next new batch uses nextOffset.