Operator runbook — Plan 119 connection method picker rollout¶

Superseded by Plan 128 (docs/operations/connections-ux.md). The 3-step picker (/connections/new) and the connection_method_picker tenant flag both shipped under Plan 119 and were retired in Plan 128 in favour of inline vendor tiles on /connections. This doc is kept for archive context; do not follow it for new rollouts.

The 3-step connection-method picker (/connections/new) replaces the legacy vendor grid for adding a new connection. Per Plan 119 the picker is off by default for every tenant in v1; the operator flips the flag per-tenant once they have reviewed the new flow.

Rollout decision tree¶

Is the tenant a friendly early-adopter / pilot? -> enable now.
Has the customer asked for clearer trust-model surfacing? -> enable now.
Is the customer mid-onboarding with a runbook that screenshots the
  legacy grid?                                       -> wait for refresh.
Otherwise                                            -> leave off; revisit after 2-week soak.

After ~2 weeks of soak with at least 2 enabled tenants the picker flips default-on for new tenants — the legacy grid stays available under /connections/new-legacy for one more release cycle so any ops runbook screenshots stay valid until they're refreshed.

Enabling the flag (per tenant)¶

The flag lives in tenants.settings.flags.connection_method_picker, exposed via the standard Plan 82 tenant-flag PATCH endpoint and the /admin/tenants/{id} flags-form UI.

Option A — UI (preferred)¶

https://app.secruna.com/admin/tenants/{tenant_id}
Scroll to Feature flags.
Toggle Connection method picker to On.
Click Save. The form emits a tenant.flags.updated audit row with the before/after override block.

Option B — API (scripted)¶

curl -X PATCH "https://api.secruna.com/admin/tenants/{tenant_id}/flags" \
  -H "Content-Type: application/json" \
  --cookie "session=<your-platform-admin-session>" \
  -d '{"connection_method_picker": true}'

The response echoes the resolved flag block. To revert, PATCH with null so the override clears and the tenant inherits the global default again:

curl -X PATCH "https://api.secruna.com/admin/tenants/{tenant_id}/flags" \
  -H "Content-Type: application/json" \
  --cookie "session=<your-platform-admin-session>" \
  -d '{"connection_method_picker": null}'

What the customer sees¶

Before the flip — the Add new connection button on /connections points to /connections/new-legacy (the vendor-grid the customer is used to).
After the flip — the same button points to /connections/new (Step 1 of the picker). The legacy grid stays accessible at /connections/new-legacy so a customer who deep-linked or bookmarked the legacy URL keeps working.

Roll-back¶

The flag flip is instant — set it back to false (or PATCH with null to inherit the default-off) and the customer's next page load on /connections routes back to the legacy grid. No data migration is involved; the picker shell is a pure UX layer over the same vendor dialogs the legacy grid uses.

Observability¶

Each flag flip emits a tenant.flags.updated audit log row with changed_keys=["connection_method_picker"] and the before/after override values.
The connect-method-picker.* frontend events (if added later) flow to the standard analytics pipeline; today there's no in-app funnel telemetry — operators rely on the customer feedback channel
the connection success rate per vendor.

FAQ¶

Q: Does flipping the flag break in-flight OAuth callbacks? No. The picker reuses the same /connections/{provider}/start and /connections/{provider}/connect endpoints as the legacy grid; the flag only swaps the UX layer in front of them.

Q: Will existing connections keep working? Yes. The connection detail page now surfaces a "Connected via …" trust-posture badge derived from connection.subtype. Existing rows without a subtype fall back to the provider-default posture.

Q: When does the legacy grid get removed? After the default flips on for new tenants and the soak period passes. Expect a follow-up changelog entry naming the version.