Skip to main content

Implementation Approach

The WhatIF platform is built on a configuration-driven philosophy. Rather than encoding business mapping rules, product structures, or environment-specific values directly in notebook code, the platform externalizes all of this into YAML configuration files and SQL Server metadata. This means that when mapping rules change, new products are added, or the platform is deployed to a new environment, the response is a configuration update, not a code change. The Configuration Reference describes each YAML file in detail. The Deployment Guide describes the sequence in which these configurations are deployed and validated.

The platform's core behavior is driven by four inputs: YAML configuration for XML build and parse flows, SQL Server metadata for scenarios and report configurations, runtime notebook parameters passed through the Fabric orchestration pipeline, and the Lakehouse source and target tables that hold the data at each stage.

XML Build​

The XML Build flow is responsible for constructing the Rating Engine request payloads from source data. It reads its mapping rules from a runtime YAML configuration path, identifies the source mode, either database records or source XML files, and builds one XML payload per configured business key. Each built payload is persisted to a Delta target table and merged using the configured identity column, making the process idempotent across multiple runs.

The source mode selection is a deployment-time decision driven by the data contract. DB mode is used when source data is relational and available through SQL Server. XML mode is used when source files must be read from a Lakehouse shortcut or file path. This decision must be agreed upon during the discovery phase, as it determines which YAML configuration file and notebook parameters are required. See Onboarding and Setup for the full discovery sequence.

Generic XML Parse​

The Generic XML Parse flow is the primary reusable parser pattern in the platform. It reads its parse rules from a runtime YAML configuration at execution time, which means the same notebook can handle different product structures, mapping rules, and output schemas simply by pointing it at a different configuration file. This is the default implementation approach for any project where parsing rules are expected to evolve, multiple products or lines of business exist, or runtime configuration changes are anticipated.

The parser supports both filter-stage and process-stage parsing, scalar mappings and repeated-node mappings, XML-derived values and static values, and automatic table creation and evolution. Rows are merged into target tables using the configured incremental key. The critical implementation rule for repeated XML structures is that RowIdentity must define row creation — repeated rows must be expanded using row-scope logic, not extracted as scalars. This distinction is one of the most common sources of implementation errors and is covered in detail in Known Limitations.

Scenario API Processing​

The Scenario API flow brings together the XML build output and the scenario metadata to invoke the Rating Engine at scale. It reads scenario metadata from SQL Server, reads throughput and context YAML configurations, builds the request payloads, and submits them to the Rating Engine using distributed Spark execution. One result row is stored per policy, and the response XML is parsed into normalized output tables.

The flow supports two execution branches, the current-premium branch and the proposed-premium branch, controlled by the CurrentPremiumCheck parameter. Both branches must be validated independently during testing. The notebook runtime parameters that govern this flow are documented in Notebook Runtime Parameters. The architectural context for how the Rating Engine is invoked and how responses are captured is described in the Architecture Walkthrough.

Analytical Reporting Views​

The reporting data mart is implemented as a set of SQL views exposed from the Lakehouse SQL Analytics Endpoint. This approach centralizes all transformation logic in SQL rather than in the semantic model, which keeps the semantic model focused on business measures, display behavior, and report navigation rather than data shaping.

The mart follows a Kimball-style pattern with dimension views, a fact view, and helper views for dynamic reporting. Unknown-member handling is applied to all dimension joins so that unresolved foreign keys do not break the fact table. Coverage and rate-component reporting use configuration-driven logic driven by ScenarioDB.ReportConfigurations.

The current source systems feeding the reporting mart are ScenarioDB (scenarios, books of business, users, and report configurations), dataload (policy, risk, risk extension, and coverage), and RatingOutput (rating response tables at the policy, risk, and coverage grain).

The current view inventory published from views_config.yml includes the following:

  • Dimensions: dbo.Dim_Scenario, dbo.Dim_Book, dbo.Dim_User, dbo.Dim_Risk, dbo.Dim_Coverage, dbo.Dim_Policy, dbo.Dim_LineOfBusiness, dbo.Dim_Customer, dbo.Dim_Agent, dbo.Dim_Agency, dbo.Dim_Geography, dbo.Dim_PremiumChangeBand
  • Fact: dbo.Fact_PolicyPremium
  • Reporting helper and dynamic views: dbo.Rate_Report, dbo.vw_filters

Fact_PolicyPremium is currently at the grain of Policy - Risk - Coverage - Scenario. Dim_Coverage is filtered using ScenarioDB.ReportConfigurations. Rate_Report is generated using configuration-driven rate attributes and dynamic case expressions.

Semantic Model and Report Layer​

The reporting views do not feed end-user reports directly. They feed a shared semantic model, import_sm_whatif, which is stored in Import mode and sourced from the Lakehouse SQL Analytics Endpoint views rather than from base Lakehouse tables. Two live-connected report artifacts are built on top of this shared model: What-If Actuarial Reports and WhatIf Scenario Compare.

The semantic model supports charged, current, and proposed premium comparisons; winner and loser segmentation using dim_premiumchangeband; profile-driven analysis for risk, coverage, and policy views; and multi-currency and display-format helper tables. The implementation rule is to keep complex shaping logic in SQL views, keep business measures and display behavior in the semantic model, and organize reusable measures in a dedicated measure table such as KeyMeasures.

Embedded Reporting and Schema Drift Handling​

The reporting solution is embedded within the WhatIF application using the User Owns Data model. Report context is controlled through URL filter parameters passed from the application, and workspace permissions and row-level security continue to apply through the signed-in user's identity.

Because the semantic model uses Import mode, it must be refreshed after each scenario run and after any change to the underlying SQL views. The platform handles schema drift — where source SQL views gain or lose columns over time — through the Semanticmodel_autoupdate notebook. This notebook compares Lakehouse SQL view columns against semantic model columns, uses XMLA and TOM to add or remove columns as needed, triggers a model refresh through Fabric REST, and polls for refresh completion before the model is used again. This automation must be operationally reliable before go-live, as described in the Production Readiness Checklist.