Create a migration engagement

View full size

An Airlift engagement is the top-level delivery record for one migration or modernization program. It connects source estates, services, immutable external references, connection bindings, waves, artifacts, evidence, and operator decisions under one organization.

Use an engagement when your application needs to answer:

• which estates and services are in scope;
• who owns the migration;
• which source, target, and service connections have been verified;
• which exact scope was frozen for delivery or cutover; and
• which governed actions changed that scope.

Use the Databricks App

Start in Migration inbox. It ranks active engagements by blockers and failed evidence, then gives each row one primary action: resolve the next blocker or continue the earliest incomplete gate. Use Status when you need the complete governed projection rather than the operating queue.

Open Engagements to search or filter the portfolio and see one card per migration workspace. Each card shows the source-to-target route, owner, current phase, completed gates, active blockers, capability preflight, and gate-completion percentage.

• Select the card title or non-action area to open the engagement overview.
• Choose Continue migration to bypass the overview and open the current actionable workspace. When conversion residue blocks the engagement, this opens the matching remediation case rather than another status screen.
• Choose View migration status to inspect all eight delivery phases and their evidence.
• Choose New engagement to open /engagements/new. After draft creation, Airlift opens /engagements/<id>/setup and guides source registration, a secret-safe connection reference, verification evidence, activation, assessment, and scope acceptance in order. It never redirects to an unrelated existing engagement.

The sidebar starts in Portfolio view and deliberately hides source-specific and journey links until you choose a current engagement. Open Current engagement, then select a migration workspace. Airlift keeps that engagement visible in the desktop context bar and adds only its attached sources and phase workspaces to navigation. Returning to Portfolio view removes that source-specific navigation without changing migration state.

Choose Search migrations or press ⌘K/Ctrl K to jump directly to an engagement overview, migration status, artifact explorer, run ledger, or source workspace. Search is navigation only; it never changes scope or runs a governed action.

The sidebar presents the eight evidence gates in delivery order: discover, plan, convert, move data, prepare the release, validate, certify, and cut over. Resolve conversion issues is a contextual workbench used when the Convert gate produces residue; it is not a ninth evidence gate. Hover or focus a navigation item to see what that workspace owns. Compiler, modernization, portfolio, and administration workbenches remain available under Advanced tools; most migration operators do not need them for the everyday guided journey.

The engagement workspace places Your next step before the journey and metrics. Its primary button opens the first incomplete gate or exact blocker, and the current phase card repeats that action for discoverability. Source-specific entry points, artifact and validation counts, and Manage engagement follow. Management opens automatically when a draft needs activation or when no source is configured; otherwise it remains collapsed.

Every engagement has five stable, shareable views:

The lifecycle controls mean:

Inline help buttons expose these definitions with mouse, keyboard, or touch. Consequential prerequisites and blocked reasons remain visible without requiring a tooltip.

Check the capability boundary before execution

An engagement preflight translates the selected services into an evidence requirement, then checks every scoped estate and source variant against the tenant capability registry. Run it before activating a factory pilot, promising a client outcome, or scheduling a cutover:

fa engagement preflight eng_<id>
fa engagement preflight eng_<id> --json

Discovery requires hermetic assessment and dependency proof. A factory pilot requires workspace-proven execution, movement, validation, and target generation. A migration factory requires representative client proof. Cutover assurance additionally requires a production-certified cutover and rollback path. Modernization adds its own separately evidenced requirement.

The command exits with status 1 when blocked and explains the next action for each missing, proposed, stale, unavailable, or under-proved capability. Human and mixed lanes are valid delivery paths when proven, but remain visible with their required skills so the engagement can staff and estimate them explicitly.

Create and activate the engagement

Applications invoke the same Platform actions used by the Airlift workbench. Derive the organization and actor from your authenticated server context; never accept them as authoritative request-body fields.

import { AIRLIFT_ACTION_IDS, contentDigest } from "@fabricorg/airlift";

const created = await runtime.invokeAction(AIRLIFT_ACTION_IDS.engagementCreate, {
  tenantId: session.organizationId,
  actorId: session.userId,
  actorType: "natural_person",
  idempotencyKey: commandId,
  params: {
    name: "Enterprise warehouse migration",
    owner: "data-platform",
    services: ["discovery", "migration_factory", "modernization"],
    estateIds: [estateId],
    externalRefs: [
      { system: "crm", type: "opportunity", id: "OPP-1042" },
    ],
  },
});

if (!created.ok) throw new Error(`${created.stage}: ${created.error}`);
const engagementId = created.data.engagementId as string;

await runtime.invokeAction(AIRLIFT_ACTION_IDS.engagementActivate, {
  tenantId: session.organizationId,
  actorId: session.userId,
  actorType: "natural_person",
  idempotencyKey: `${commandId}:activate`,
  params: { engagementId },
});

Creation produces a draft. Activation marks the record ready for execution. Updates are accepted only while the engagement is draft or active.

Register connection bindings

A connection binding describes what Airlift may ask an external connection to do. It stores an opaque credential reference and declared capabilities; it does not store a password, token, connection string, or secret value.

const binding = await runtime.invokeAction(
  AIRLIFT_ACTION_IDS.connectionBindingRegister,
  {
    tenantId: session.organizationId,
    actorId: session.userId,
    actorType: "natural_person",
    idempotencyKey: `${commandId}:source-binding`,
    params: {
      engagementId,
      estateId,
      name: "Source metadata access",
      sourceSystem: "synapse",
      direction: "source",
      credentialRef: "databricks-connection://synapse-metadata",
      capabilities: ["inventory_read", "metadata_read"],
    },
  },
);

Accepted reference schemes are connection://, databricks-connection://, databricks-secret://, and secret://. User information, query strings, fragments, and unrecognized schemes are rejected by the action schema.

After your connection verifier completes its source-specific checks, record the connectivity diagnostic as an admitted system principal, then verify the binding with the recorded diagnostic's derived digest:

const diagnostic = await runtime.invokeAction(
  AIRLIFT_ACTION_IDS.connectionDiagnosticRecord,
  {
    tenantId: session.organizationId,
    actorId: session.servicePrincipalId,
    actorType: "system",
    idempotencyKey: `${commandId}:diagnose-source-binding`,
    params: {
      connectionBindingId: binding.data.connectionBindingId,
      bindingRevisionDigest: connectionBindingRevisionDigest(bindingRow),
      providerId: "acme-source-probe",
      providerVersion: "probe@1.0.0",
      evidenceRef: "volumes/evidence/diagnostics/binding.json",
      evidenceDigest: contentDigest(probeReport),
      runRef: "runs/diagnostic/binding",
      startedAt,
      completedAt,
      probes, // every probe required by the declared capabilities, all passing
    },
  },
);

await runtime.invokeAction(AIRLIFT_ACTION_IDS.connectionBindingVerify, {
  tenantId: session.organizationId,
  actorId: session.userId,
  actorType: "natural_person",
  idempotencyKey: `${commandId}:verify-source-binding`,
  params: {
    connectionBindingId: binding.data.connectionBindingId,
    // verificationDigest must be the recorded diagnostic digest; a caller-chosen
    // digest is not evidence.
    verificationDigest: diagnostic.data.diagnosticDigest,
  },
});

Registration does not imply connectivity. The binding remains pending until admitted verification evidence is recorded. A retired binding remains visible in the audit and projection history but cannot return to verified.

Freeze the delivery scope

Freezing is a governed action, not a client-authored flag. Airlift computes the SHA-256 scope digest from the recorded engagement ID, services, estates, and external references.

const frozen = await runtime.invokeAction(AIRLIFT_ACTION_IDS.engagementFreeze, {
  tenantId: session.organizationId,
  actorId: session.userId,
  actorType: "natural_person",
  idempotencyKey: `${commandId}:freeze`,
  params: { engagementId },
});

A frozen engagement rejects later edits. Use the resulting scopeDigest as the stable input reference for delivery plans, evidence exports, deployment releases, and cutover prechecks.

Read the projections

Queries use organization-scoped projections. They do not mutate state.

const engagement = runtime.db.engagements.get(session.organizationId, engagementId);
const bindings = runtime.db.connectionBindings.listByEngagement(
  session.organizationId,
  engagementId,
);

The Databricks App exposes the same records under Engagements. Workbench forms are thin authenticated transports over these actions; policy or schema denials are shown to the operator and remain in the governed invocation ledger.

Action summary

Agent principals cannot invoke these actions. A separately admitted service principal may use the narrow automation role through the authenticated remote API. Migration agents may assess and convert within their admitted bounds; they cannot govern engagement scope or connection admission.