From 93a3d95e79f06f951cbc2d6734c1d28426f37ea7 Mon Sep 17 00:00:00 2001 From: Roland Krummenacher Date: Wed, 29 Apr 2026 20:08:53 +0200 Subject: [PATCH 1/2] Fix stale and incorrect entries in data dictionary Several entries in the FinOps toolkit data dictionary were inaccurate or referred to deprecated columns. Corrections in this commit: - BilledCost / EffectiveCost: align descriptions with the FOCUS 1.2 spec; remove ActualCost/AmortizedCost dataset references and the stale "include the Cost Management connector" guidance - BillingCurrency: clarify it applies to billing-amount columns only (pricing-amount columns use PricingCurrency) - BillingProfileId / BillingProfileName: correct as MCA-only (previously described as covering EA or MCA); fix "invoices invoices" typo - CommitmentDiscountQuantity: replace incorrect description (was describing CommitmentDiscountType) with FOCUS 1.2 wording - ListUnitPrice: replace stale OnDemandUnitPrice reference with ContractedUnitPrice (renamed in v0.4) - PricingQuantity: replace stale UsageQuantity reference with ConsumedQuantity (renamed in v0.4) - PricingUnitDescription: fix grammar typo and add FOCUS 1.2 wording - TotalSavingsRunningTotal: was describing DiscountCostSavings; now correctly references TotalSavings Co-Authored-By: Claude Opus 4.7 (1M context) --- docs-mslearn/toolkit/help/data-dictionary.md | 22 ++++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs-mslearn/toolkit/help/data-dictionary.md b/docs-mslearn/toolkit/help/data-dictionary.md index 58a8f31c3..5c0fe49b5 100644 --- a/docs-mslearn/toolkit/help/data-dictionary.md +++ b/docs-mslearn/toolkit/help/data-dictionary.md @@ -3,7 +3,7 @@ title: FinOps toolkit data dictionary description: This article describes the column names found in FinOps toolkit solutions, including columns from Cost Management and FOCUS. author: flanakin ms.author: micflan -ms.date: 04/01/2026 +ms.date: 04/29/2026 ms.topic: concept-article ms.service: finops ms.subservice: finops-toolkit @@ -44,20 +44,20 @@ Quick links: | AccountOwnerId | Email address of the identity responsible for billing for this subscription. It's your EA enrollment account owner or MOSA account admin. Not applicable to MCA. | | AmortizationClass | Indicates how a row relates to amortization to identify and distinguish between the charges before and after amortization is applied. Derived from `ChargeCategory` and `CommitmentDiscountStatus` when not provided by Cost Management. | | AvailabilityZone | Area within a resource location used for high availability. Not available for all services. Not included in Microsoft Cloud cost data. | -| BilledCost | Amount owed for the charge after any applied discounts. If using FinOps hubs, you need to include the Cost Management connector to see all billed costs. Maps to CostInBillingCurrency for actual cost in Cost Management. | +| BilledCost | A charge serving as the basis for invoicing, inclusive of all reduced rates and discounts while excluding the amortization of upfront charges (one-time or recurring). See [`EffectiveCost`](#e) for the amortized equivalent. | | BilledCostInUsd | `BilledCost` in USD. | | BilledPricingCost | `BilledCost` in the pricing currency. | | BillingAccountAgreement | Derived. Indicates the type of account. Allowed values: EA, MCA, MG, MOSA, MPA. | | BillingAccountId | Unique identifier for the billing account. "BillingAccount" columns map to the EA billing account and MCA billing profile. `x_BillingAccount` is the same as Cost Management. | | BillingAccountName | Name of the billing account. "BillingAccount" columns map to the EA billing account and MCA billing profile. `x_BillingAccount` is the same as Cost Management. | | BillingAccountType | Indicates whether the `BillingAccountId` represents an EA billing account or MCA billing profile. | -| BillingCurrency | Currency code for all price and cost columns. | +| BillingCurrency | Currency that a charge was billed in. Applies to billing-amount columns like `BilledCost`, `EffectiveCost`, and `ListCost`. Pricing-amount columns (for example, `ContractedUnitPrice`, `ListUnitPrice`) use [`PricingCurrency`](#p). | | BillingExchangeRate | Exchange rate to multiply by when converting from the pricing currency to the billing currency. | | BillingExchangeRateDate | Date the exchange rate was determined. | | BillingPeriodEnd | Exclusive end date of the invoice period. Usually the first of the next month at midnight. | | BillingPeriodStart | First day of the invoice period. Usually the first of the month. | -| BillingProfileId | Unique identifier of the scope that invoices are generated for. EA billing account or MCA billing profile. | -| BillingProfileName | Name of the scope that invoices invoices are generated for. EA billing account or MCA billing profile. | +| BillingProfileId | Unique identifier for the Microsoft billing profile. Same as `BillingAccountId` for MCA. Not applicable for EA. | +| BillingProfileName | Name of the Microsoft billing profile. Same as `BillingAccountName` for MCA. Not applicable for EA. | | ~CapacityCommitmentId~ (removed) | See `CapacityReservationId`. | | CapacityReservationId | Unique identifier of the on-demand capacity reservation, if applicable. Not related to commitment discounts. Only available for virtual machines. Extracted from `x_SkuDetails` or `SkuPriceDetails` when not provided by Cost Management. | | CapacityReservationStatus | Indicates whether the `CapacityReservationId` was used or not for this charge, if applicable. Allowed values: `Used`, `Unused`. Extracted from `x_SkuDetails` or `SkuPriceDetails` when not provided by Cost Management. | @@ -78,7 +78,7 @@ Quick links: | CommitmentDiscountName | Name of the commitment discount (for example, reservation, savings plan) this resource utilized. Maps to **BenefitName** in Cost Management. | | CommitmentDiscountNameUnique | Derived. Unique name of the commitment (for example, reservation, savings plan), including the ID for uniqueness. | | CommitmentDiscountNormalizedRatio | Derived. Instance size flexibility (ISF) normalized ratio for commitment discounts, if applicable. | -| CommitmentDiscountQuantity | Label assigned by the provider to describe the type of commitment-based discount applied to the row. Derived when not provided by Cost Management. | +| CommitmentDiscountQuantity | Amount of a commitment discount purchased or accounted for in commitment-discount-related rows, denominated in `CommitmentDiscountUnit`. Derived when not provided by Cost Management. | | CommitmentDiscountSavings | Derived. Used in Power BI to sum the amount saved from commitment discounts only. Does not include savings from negotiated discounts. Formula: `ContractedCost - EffectiveCost`. | | CommitmentDiscountSavingsRunningTotal | Derived. Calculates the accumulated or running total of `CommitmentDiscountSavings` for the day, including all previous day's values. | | CommitmentDiscountSpendEligibility | Indicates whether spend commitment discounts (like savings plans) are eligible for this charge. Derived from the **Prices** dataset. | @@ -107,7 +107,7 @@ Quick links: | CustomerName | Cloud Solution Provider (CSP) customer tenant name. | | DiscountCostSavings | See [`TotalSavings`](#t). | | DiscountCostSavingsRunningTotal | See [`TotalSavingsRunningTotal`](#t). | -| EffectiveCost | BilledCost with commitment purchases spread across the commitment term. See [Amortization](terms.md#amortization). Maps to CostInBillingCurrency for amortized cost in Cost Management. | +| EffectiveCost | The amortized cost of the charge after applying all reduced rates, discounts, and the applicable portion of relevant prepaid purchases (one-time or recurring) that covered this charge. See [Amortization](terms.md#amortization). | | EffectiveCostInUsd | `EffectiveCost` in USD. | | EffectiveCostPerResource | Derived. Used in Power BI to calculate the average `EffectiveCost` for each unique resource ID. This is a simple average. Formula = `SUM(EffectiveCost) / DCOUNT(ResourceId)`. This does not account for all free resources and may include nested, child resources or deleted resources. | | EffectiveCostRunningTotal | Derived. Used in Power BI to calculate the total `EffectiveCost` for the reporting period up to and including the specified day. For instance, the cost for the 15th will include the cost from the 1st through the 15th. | @@ -123,7 +123,7 @@ Quick links: | IsFree | Derived. Indicates if this charge is free and has 0 `BilledCost` and 0 `EffectiveCost`. If the charge shouldn't be free, contact support because it's likely an inaccurate or incomplete data in Cost Management. | | ListCost | Derived if not available. List (or retail) cost without any discounts applied. | | ListCostInUsd | ListCost in USD. | -| ListUnitPrice | List (or retail) price per unit. If the same as OnDemandUnitPrice when there are discounts, this means list price and cost weren't provided by Cost Management. | +| ListUnitPrice | Suggested provider-published unit price for a single Pricing Unit of the associated SKU, exclusive of any discounts. If the same as `ContractedUnitPrice` when there are discounts, this means list price and cost weren't provided by Cost Management. | | Month | Derived. Month of the charge. | | NegotiatedCostSavings | See [`NegotiatedDiscountSavings`](#n). | | NegotiatedCostSavingsRunningTotal | Derived. Calculates the accumulated or running total of NegotiatedCostSavings for the day, including all previous day's values. | @@ -138,10 +138,10 @@ Quick links: | PricingBlockSize | Derived. Indicates what measurement type is used by the `PricingQuantity`. Extracted from **UnitOfMeasure** in Cost Management. | | PricingCategory | Describes the pricing model used for a charge at the time of use or purchase. Allowed values: `Standard`, `Dynamic`, or `Committed`. | | PricingCurrency | Currency code used for internal pricing. Renamed from **x_PricingCurrency** in FOCUS 1.2. | -| PricingQuantity | Derived. Amount of a particular service that got used or purchased based on the PricingUnit. `PricingQuantity` is the same as `UsageQuantity` divided by `x_PricingBlockSize`. | +| PricingQuantity | Derived. Amount of a particular service that got used or purchased based on the PricingUnit. `PricingQuantity` is the same as `ConsumedQuantity` divided by `x_PricingBlockSize`. | | PricingSubcategory | Describes the kind of pricing model used for a charge within a specific `PricingCategory`. | | PricingUnit | Derived. Indicates what measurement type is used by the `PricingQuantity`. Extracted from **UnitOfMeasure** in Cost Management. | -| PricingUnitDescription | Describes the measurement type is used by the `PricingQuantity`. Maps to **UnitOfMeasure** in Cost Management. | +| PricingUnitDescription | Describes the measurement type used by the `PricingQuantity`, including pricing block size. This is what is used in the price list and on the invoice. Maps to **UnitOfMeasure** in Cost Management. | | PublisherCategory | Indicates whether a charge is from a cloud provider or third-party Marketplace vendor. Allowed values: `Cloud Provider` and `Vendor`. Maps to PublisherType in Cost Management. | | PublisherId | Unique identifier for the organization that created the product that got used or purchased. | | PublisherName | Name of the organization that created the product that got used or purchased. | @@ -209,7 +209,7 @@ Quick links: | ToolkitTool | Derived. Name of the tool in the FinOps toolkit the resource supports. | | ToolkitVersion | Derived. Version of the tool in the FinOps toolkit the resource supports. | | TotalSavings | Derived. Used in Power BI to sum the total amount saved after negotiated and commitment discounts are applied. Will be negative for unused commitments. Formula: `ListCost - EffectiveCost`. | -| TotalSavingsRunningTotal | Derived. Calculates the accumulated or running total of DiscountCostSavings for the day, including all previous day's values. | +| TotalSavingsRunningTotal | Derived. Calculates the accumulated or running total of `TotalSavings` for the day, including all previous day's values. | | UsageCPUHours | See [`ConsumedCoreHours`](#c). | | UsageQuantity | Number of units of a resource or service that got used or purchased based on the `UsageUnit`. Replaced by `ConsumedQuantity` in v0.4 to align with FOCUS 1.0. | | UsageUnit | Indicates what measurement type is used by the `UsageQuantity`. Replaced by `ConsumedUnit` in v0.4 to align with FOCUS 1.0. | From bb946dd0f399c6f8a57698e16279f13a63a82258 Mon Sep 17 00:00:00 2001 From: Roland Krummenacher Date: Wed, 29 Apr 2026 20:18:52 +0200 Subject: [PATCH 2/2] Add changelog entry for data dictionary corrections Co-Authored-By: Claude Opus 4.7 (1M context) --- docs-mslearn/toolkit/changelog.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs-mslearn/toolkit/changelog.md b/docs-mslearn/toolkit/changelog.md index dc22e673f..61c9e6f6a 100644 --- a/docs-mslearn/toolkit/changelog.md +++ b/docs-mslearn/toolkit/changelog.md @@ -35,6 +35,11 @@ The following section lists features and enhancements that are currently in deve ### Bicep Registry module pending updates - Cost Management export modules for subscriptions and resource groups. + +### [Data dictionary](help/data-dictionary.md) updates + +- **Fixed** + - Corrected stale and incorrect descriptions for `BilledCost`, `EffectiveCost`, `BillingCurrency`, `BillingProfileId`, `BillingProfileName`, `CommitmentDiscountQuantity`, `ListUnitPrice`, `PricingQuantity`, `PricingUnitDescription`, and `TotalSavingsRunningTotal` to align with FOCUS 1.2 ([#2112](https://github.com/microsoft/finops-toolkit/pull/2112)). -->