Administrator guide

This guide follows Katarzyna Zielińska, the Platform Admin persona, through the journeys that keep DataFlow AI running — from a cold three-day infrastructure build, through daily operations and user onboarding, into incident response. It closes with the Migration Specialist's four-phase legacy migration journey, performed by an engineer in the Migration Center. Every step is mapped to a concrete screen, tool, or route.

Before you start

The Platform Admin is the control-plane operator. Katarzyna's backend role is ADMIN (level 100 — the top of the hierarchy); her Keycloak realm role is the composite org_admin; her UX persona is admin. She has all 28 front-end permissions and full access to the Administration Console.

Her allowed route prefixes include /, /admin, /monitor, /migration, /design-studio, /governance, /connections, /pipelines, /data-browser, and /templates. Notably the Administration Console (/admin) is visible to the admin persona only.

Journey 1 — Initial platform setup

Standing up the platform takes three focused days.

Day 1 — Infrastructure

1. Katarzyna runs terraform apply against the IaC templates.
2. Terraform provisions a GKE Autopilot cluster in europe-central2.
3. It provisions a Cloud SQL PostgreSQL instance for the platform's metadata.

Tooling: Terraform, GKE, Cloud SQL.

Day 2 — Security

1. She configures Keycloak with Active Directory federation over LDAPS.
2. She sets up Vault for credential management.
3. She defines the RBAC roles and maps AD groups to them with Keycloak role mappers.

Tooling: Keycloak admin console, Vault, role mappers.

Day 3 — Connectivity

1. She registers the connectors Polkomtel needs: Teradata, Snowflake, Databricks, SAP HANA, and MSSQL.
2. She tests every connection.
3. She sets up monitoring and alerting with Grafana and PagerDuty.

Tooling: connection registration API, Grafana, PagerDuty.

Journey 2 — Daily operations

Katarzyna's day centers on the Administration Console and the admin variant of the Home Dashboard.

08:00 — Morning health check

1. She opens the Admin Dashboard (/dashboard, admin variant).
2. The SystemHealthCard confirms all services are UP, with CPU at 34% and memory at 52%.
3. The CostTrackerCard shows spend — today $142, month-to-date $3,847 against a $5,000 budget.

Mid-morning — User management

1. A new-user request arrives from the DBI team.
2. Katarzyna assigns the user to a workspace and an environment.
3. Their AD-group membership auto-provisions the correct permissions.

Scaling

1. A high-CPU alert fires during the month-end peak.
2. She reviews the usage patterns on the dashboard.
3. GKE Autopilot auto-scales the cluster; she can apply a manual override if needed.

Screens: HomeDashboard (admin), SystemHealthCard, CostTrackerCard, ActiveUsersCard, InfrastructureAlertsCard, ScalingEventsCard, ServiceStatusTable, Administration Console.

Journey 3 — User and team onboarding

Adding a new user or team is a routine but multi-step journey.

1. Provision the user. The user is synced from Active Directory via Keycloak federation, or created manually in Keycloak with a username, email, name, temporary password, and realm roles. In the Admin Console she uses Users tab → + Create User and fills the dialog (name, email *@plk.pl, role, workspace, AD groups, status, notification toggles).
2. Assign workspace membership. She assigns the user to a workspace via the metadata-service API — POST /workspaces/{id}/members with a role.
3. Create a workspace (if needed). POST /workspaces with a name, slug, and environment, plus resource quotas — concurrent runs, max pipelines, GCS storage, and Spark executors.
4. Register connections. She registers the workspace's data connections and tests connectivity with POST /connections/{id}/test.

The Admin Console's AD Group Mapping table makes the link explicit: each row shows an AD group, the platform role it grants, the workspace scope, and the member count.

Screens: /admin/users (Users and Workspaces tabs), Keycloak admin console, workspace API.

Journey 4 — Incident response

Walkthrough of a real incident: pipeline failures spike at 02:00.

Step 1 — Detect and diagnose

1. A PagerDuty P1 alert fires — 50+ pipeline failures.
2. Katarzyna checks Grafana, which shows a Teradata latency spike at 01:55.
3. Root cause: a conflict with a Teradata DWH maintenance window.

Step 2 — Coordinate

1. She coordinates with the Teradata DBA team.
2. Teradata is back online at 03:30.

Step 3 — Recover and learn

1. She runs a bulk retry of all failed pipelines from their checkpoints.
2. She updates the runbook — adding a Teradata maintenance-window blackout so the conflict cannot recur.

Screens: notification / alert panel, IncidentPanel, Monitor Center (admin-scoped), Grafana, PagerDuty.

Journey 5 — Legacy migration (Migration Specialist, four phases)

Legacy migration has no dedicated persona — it is performed by a Data Engineer working in the Migration Center, often in coordination with the Platform Admin. The RFI scope is 500+ PowerCenter workflows and 50–100 Alteryx workflows (roughly 550–600 assets). Targets: >85% auto-conversion for PowerCenter and >75% for Alteryx. A typical batch takes about six weeks.

Phase 1 — Assessment (Week 1)

1. Upload the PowerCenter XML export — for example, 150 objects — into the Import Wizard (/migration/import).
2. The wizard auto-detects the file type (PowerCenter XML / Alteryx YXMD / Unknown) and shows per-file cards with object counts.
3. Click Analyze with AI. A 4-stage checklist runs — Parsing → Analyzing → Compatibility → Report — with a live scrolling analysis feed.
4. Review the Compatibility Report: four summary cards (Total Objects, Auto-Convertible %, Manual Required %, Estimated Effort hrs), a Workflow Assessment table with complexity badges, an Object-Type breakdown chart, and a Risk Items panel. A typical result: 85% auto-convertible, 15% manual.

Screens: Import Wizard — FileUploadStep, AnalysisProgressStep, AnalysisFeed, CompatibilityReportStep, WorkflowAssessmentTable.

Phase 2 — Batch conversion (Weeks 2–3)

1. Auto-convert the pipelines using AI plus rules — click Start Conversion to move to /migration/conversion.
2. The Conversion Dashboard shows summary cards (Total, Auto-Converted donut, Manual donut, average confidence) and a Conversion Status by Object Type table — Source Qualifier, Expression, Lookup, Filter, Joiner, Custom Java, Router, Other.
3. Review each converted YAML pipeline in the Design Studio via the card's Open in Design Studio action.
4. Fix flagged items — for example, 23 complex Java transforms that need manual attention.

Screens: Conversion Dashboard — ConversionSummaryCards, ObjectTypeConversionTable, ConvertedPipelineList, ConfidenceDistributionChart, RiskItemsPanel.

Phase 3 — Validation (Weeks 4–5)

1. Open the Validation Suite (/migration/validation) and click Run All Tests.
2. The suite runs data-parity tests comparing source against target — row counts, checksums, and column values.
3. The Pipeline Comparison Table shows the results; failed rows expand to per-column FailureDetail (expected vs. actual, diff type).
4. Fix discrepancies — for example, 3 edge-case pipelines.

Screens: Validation Suite — ValidationTestRunner, ValidationResultsTable, DataComparisonView.

Phase 4 — Cutover (Week 6)

1. Run a parallel run — both the legacy system and DataFlow AI for one week.
2. Validate that both produce identical results.
3. Decommission the PowerCenter workflows.
4. Track overall progress in the Migration Progress Tracker (/migration/progress) — a phase timeline, a Gantt chart, a batch-progress view, an ETA card, a velocity metric, and risk items.

Screens: Migration Progress Tracker — PhaseTimeline, BatchProgress, MigrationEtaCard.

Journey → screen cross-reference

Administration Console reference

The Admin Console (/admin) has five sections plus a Quick Stats footer.

Common quick actions: create a user (/admin/users → + Create User), revoke a session (Security → Active Sessions → Revoke), and rotate an API key (Security → API Keys → rotate icon).

Where to go next

• User journeys — the full journey index with ASCII maps.
• Data Engineer guide — including the engineer's side of legacy migration.
• Analyst & Steward guide — the journeys for the data-producing and governing personas.
• Personas & roles — how the Admin persona maps to backend and Keycloak roles.