Guided client onboarding

View full size

Use the guided setup flow for a new Azure Synapse-to-Databricks or SQL Server-to-Lakebase engagement. It turns seven governed requirements into one ordered journey:

1. create the migration workspace;
2. register the source estate;
3. bind a secret-safe connection reference;
4. verify source access with retained evidence;
5. activate the engagement;
6. request an assessment; and
7. review and accept the discovered scope.

The Databricks App and fa call the same Fabric Platform actions. The App does not keep a second checklist: a step becomes complete only when its domain event is present in the organization-scoped projection.

Use the guided Databricks App flow

Open Engagements → New engagement. Enter a program name, accountable owner, and the delivery services being requested. Create draft creates only the governed container; it does not connect to a source, run code, or claim readiness.

After creation, Airlift opens Guided setup at:

/<organization>/engagements/<engagement-id>/setup

The page shows all seven requirements but enables only the first unmet action. Each action panel explains what to provide, why it is required, what evidence it creates, and where to read the source-specific guide. Completed steps have a green check. Later steps remain locked so operators cannot accidentally perform onboarding out of order.

Register the source estate

Choose one of the currently supported Azure onboarding routes:

Name the actual client environment, identify its owner, and select development, staging, or production. Only estates attached to this engagement appear in its sidebar and source workspaces.

Register a secret-safe connection reference

Create the credential in the client-approved secret system first. Then enter only an opaque reference such as:

databricks-connection://migration/client-synapse-metadata
databricks-secret://migration/sql-server-reader
secret://client-vault/source-metadata

A connection reference is never a password. Airlift rejects passwords, tokens, JDBC URLs containing credentials, query strings, and fragments. The binding declares the source estate and allowed capabilities such as inventory_read and metadata_read; the secret value never enters the Airlift ledger.

Verify source access

Run the admitted source preflight with the same credential reference. The probe records a connectivity diagnostic covering every declared capability and proves, at minimum:

• authentication using the referenced credential;
• source identity and version;
• metadata visibility for the intended schemas/databases;
• denied access outside the admitted boundary; and
• the adapter/tool generation that produced the result.

The probe is recorded through airlift.connection_diagnostic_record by an admitted system principal; the handler derives the diagnostic digest — a caller can never supply it. Then choose Verify binding in the guided setup panel. The App attaches the recorded diagnostic automatically; it never asks an operator to paste a digest.

Verification evidence digest is the 64-character SHA-256 digest of the recorded connectivity diagnostic. Airlift records the digest and authenticated verifier; it does not copy the source credentials or report body. Unattended jobs perform the same step with fa connection verify; its digest recipe lives in Authenticated automation.

The binding changes from pending to verified only when the named diagnostic is fresh, matches the current binding revision, and every required probe passed. A login screenshot, a caller-authored “passed” flag, or a caller-chosen digest is not verification evidence.

Activate the engagement

Review the source estate and verified connection, then choose Activate engagement. Activation accepts the starting configuration and allows governed discovery work. It does not freeze final scope, deploy artifacts, certify parity, or authorize cutover.

Run the first assessment

Choose the estate, retain the pinned adapter generation, and supply a unique request reference. Start assessment records an idempotent request for the Airlift worker. The worker uses the configured source adapter and later records the immutable report, normalized inventory, dependency data, source version, and exact tool generation.

{
  "estateId": "est_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "toolVersion": "lakebridge@<deployed-generation>",
  "requestRef": "client-discovery-001"
}

fa assessment start \
  --file assessment-start.json \
  --idempotency-key client-discovery-001

fa assessment status <assessment-id> --json

The setup flow displays Assessment is running until a configured worker records the result. It never invents inventory to make the step green.

Accept the discovered scope

When assessment recording finishes, choose Open assessment review. Review:

• normalized source objects and object types;
• source paths, complexity, and exclusions;
• dependency edges and critical paths;
• tool and report references;
• the expected object and edge counts; and
• assumptions that must remain true for planning.

Accept the dependency graph first, then accept the assessment scope. Airlift computes the inventory, dependency, and scope digests. Planning consumes these accepted digests rather than a live source query or mutable spreadsheet.

fa inventory list --estate-id <estate-id> --assessment-id <assessment-id> --json
fa inventory graph show <dependency-graph-id> --json
fa assessment accept \
  --file assessment-accept.json \
  --idempotency-key client-scope-accept-v1

After acceptance, Guided setup is complete and its primary action changes to Build migration plan.

Perform the same setup with fa

Install the private CLI package from the registry configured by your organization:

npm install --global @fabricorg/airlift-cli
fa --version
fa doctor --profile production

The CLI derives organization and actor identity from the authenticated Databricks context. Do not place an organization ID or user identity in action payloads.

Create the estate, engagement, binding, and assessment with stable idempotency keys. Verification sits between diagnosis and activation: interactive operators choose Verify binding in the App, while unattended jobs use fa connection verify with the recorded diagnostic digest recipe in Authenticated automation — a caller-chosen digest is rejected either way.

fa estate register --file estate.json --idempotency-key client-estate-v1
fa engagement create --file engagement.json --idempotency-key client-engagement-v1
fa connection register --file source-binding.json --idempotency-key client-binding-v1
fa connection diagnose <binding-id> --file probes.json --idempotency-key client-diagnose-v1
# Verify the binding in the App, or with the digest recipe in Authenticated automation.
fa engagement activate <engagement-id> --idempotency-key client-activate-v1
fa assessment start --file assessment-start.json --idempotency-key client-assessment-v1
fa engagement status <engagement-id> --json

Example estate payloads differ only where the source contract differs:

{
  "name": "Client production Synapse",
  "sourceSystem": "synapse",
  "sourceVariant": "synapse_dedicated_sql",
  "owner": "client-data-platform",
  "environment": "prod",
  "priority": "priority"
}

{
  "name": "Client operational SQL Server",
  "sourceSystem": "sql_server",
  "sourceVariant": "sql_server",
  "owner": "client-application-team",
  "environment": "prod",
  "priority": "priority"
}

The App immediately renders CLI-created records because both surfaces read the same governed projections.

What the client can inspect

After onboarding, each engagement exposes five shareable views:

Production onboarding boundary

Before connecting production data, confirm the Databricks App uses workspace identity, the organization registry admits the client and operators, the durable store and artifact store are configured, and the source connection follows the client's least-privilege policy. Automated cutover remains disabled until a source-and-target-specific effector has passed the production cutover and rollback capability suite.

Do not represent local fixtures or a successful setup walkthrough as client migration proof. Workspace and client claims require immutable provider run references for the same source, target, artifact digest, and validation profile.