0.4 doc updates and fixes (#816)

docs/_docs/framework/capabilities/manage/assessment.md

@@ -4,7 +4,7 @@ grand_parent: FinOps Framework
 parent: Manage
 title: Assessment
 permalink: /framework/capabilities/manage/assessment
-nav_order: 1
+nav_order: 6
 description: This article helps you understand the FinOps assessment capability within the FinOps Framework and how to implement that in the Microsoft Cloud.
 author: bandersmsft
 ms.author: banders

docs/_docs/framework/capabilities/manage/invoicing-chargeback.md

@@ -4,7 +4,7 @@ grand_parent: FinOps Framework
 parent: Manage
 title: Chargeback
 permalink: /framework/capabilities/manage/invoicing-chargeback
-nav_order: 6
+nav_order: 5
 description: This article helps you understand the invoicing and chargeback capability within the FinOps Framework and how to implement that in the Microsoft Cloud.
 author: bandersmsft
 ms.author: banders

docs/_docs/framework/capabilities/manage/onboarding.md

@@ -4,7 +4,7 @@ grand_parent: FinOps Framework
 parent: Manage
 title: Onboarding
 permalink: /framework/capabilities/manage/onboarding
-nav_order: 4
+nav_order: 3
 description: This article helps you understand the onboarding workloads capability within the FinOps Framework and how to implement that in the Microsoft Cloud.
 author: bandersmsft
 ms.author: banders

docs/_docs/framework/capabilities/manage/operations.md

@@ -4,7 +4,7 @@ grand_parent: FinOps Framework
 parent: Manage
 title: FinOps practice operations
 permalink: /framework/capabilities/manage/operations
-nav_order: 1
+nav_order: 2
 description: This article helps you understand the FinOps practice operations capability within the FinOps Framework and how to implement that in the Microsoft Cloud.
 ---
 

docs/_docs/framework/capabilities/manage/policy.md

@@ -4,7 +4,7 @@ grand_parent: FinOps Framework
 parent: Manage
 title: Policy + governance
 permalink: /framework/capabilities/manage/policy
-nav_order: 5
+nav_order: 4
 description: This article helps you understand the cloud policy and governance capability within the FinOps Framework and how to implement that in the Microsoft Cloud.
 author: bandersmsft
 ms.author: banders

docs/_docs/framework/capabilities/manage/tools-and-services.md

@@ -4,7 +4,7 @@ grand_parent: FinOps Framework
 parent: Manage
 title: FinOps tools and services
 permalink: /framework/capabilities/manage/tools
-nav_order: 6
+nav_order: 7
 description: This article helps you understand the FinOps tools and services capability within the FinOps Framework and how to implement that in the Microsoft Cloud.
 ---
 

docs/_docs/framework/capabilities/optimize/architecting.md

@@ -4,7 +4,7 @@ grand_parent: FinOps Framework
 parent: Optimize
 title: Architecting for cloud
 permalink: /framework/capabilities/optimize/architecting
-nav_order: 3
+nav_order: 1
 description: This article helps you understand the architecting for cloud capability within the FinOps Framework and how to implement that in the Microsoft Cloud.
 author: bandersmsft
 ms.author: banders

docs/_docs/framework/capabilities/optimize/licensing.md

@@ -4,8 +4,7 @@ grand_parent: FinOps Framework
 parent: Optimize
 title: Licensing and SaaS
 permalink: /framework/capabilities/optimize/licensing
-
-nav_order: 3
+nav_order: 4
 description: This article helps you understand the licensing and SaaS capability within the FinOps Framework and how to implement that in the Microsoft Cloud.
 author: bandersmsft
 ms.author: banders

docs/_docs/framework/capabilities/optimize/workloads.md

@@ -4,7 +4,7 @@ grand_parent: FinOps Framework
 parent: Optimize
 title: Workloads
 permalink: /framework/capabilities/optimize/workloads
-nav_order: 1
+nav_order: 2
 description: This article helps you understand the Workload optimization capability within the FinOps Framework and how to implement that in the Microsoft Cloud.
 author: bandersmsft
 ms.author: banders

docs/_docs/framework/capabilities/quantify/README.md

@@ -15,7 +15,7 @@ Measure product and cloud performance and map to organizational KPIs to facilita
 <details open markdown="1">
    <summary class="fs-2 text-uppercase">On this page</summary>
 
-- [� Capabilities](#-capabilities)
+- [📝 Capabilities](#-capabilities)
 - [⏩ Next steps](#-next-steps)
 - [🧰 Related tools](#-related-tools)
 

docs/_docs/framework/capabilities/quantify/benchmarking.md

@@ -4,7 +4,7 @@ grand_parent: FinOps Framework
 parent: Quantify
 title: Benchmarking
 permalink: /framework/capabilities/quantify/benchmarking
-nav_order: 3
+nav_order: 4
 description: This article helps you understand the benchmarking capability within the FinOps Framework and how to implement that in the Microsoft Cloud.
 author: ripadrao
 ms.author: banders

docs/_docs/framework/capabilities/quantify/planning.md

@@ -4,7 +4,7 @@ grand_parent: FinOps Framework
 parent: Quantify
 title: Planning and estimating
 permalink: /framework/capabilities/quantify/planning
-nav_order: 3
+nav_order: 1
 description: This article helps you understand the planning and estimating capability within the FinOps Framework and how to implement that in the Microsoft Cloud.
 author: bandersmsft
 ms.author: banders
@@ -22,6 +22,7 @@ This article helps you understand the planning and estimating capability within
 <details open markdown="1">
   <summary class="fs-2 text-uppercase">On this page</summary>
 
+- [✋ Before you begin](#-before-you-begin)
 - [▶️ Getting started](#️-getting-started)
 - [🏗️ Building on the basics](#️-building-on-the-basics)
 - [🍎 Learn more at the FinOps Foundation](#-learn-more-at-the-finops-foundation)

docs/_reporting/hubs/README.md

@@ -101,28 +101,22 @@ Once deployed, you can report on the data in Power BI or by connecting to the st
 ## ➕ Create a new hub
 
 <blockquote class="note" markdown="1">
-  _FinOps hubs 0.2 is a breaking change. To upgrade an existing hub instance, please refer to the [Upgrade guide](./upgrade.md)._
+  _FinOps hubs 0.4 introduces support for FOCUS 1.0. This is **not** a breaking change and is completely backwards compatible with v0.3. To learn more, please refer to the [Upgrade guide](./upgrade.md)._
 </blockquote>
 
-1. **Register resource providers.**
-
-   FinOps hubs use Event Grid and Cost Management behind the scenes. Before you deploy your template, register the `Microsoft.EventGrid` and `Microsoft.CostManagementExports` resource providers.
-
-   [Learn more](https://docs.microsoft.com/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider)
-
-2. **Deploy your FinOps hub.**
+1. **Deploy your FinOps hub.**
 
    {% include deploy.html template="finops-hub" public="1" gov="0" china="0" %}
 
    [Learn more](../../_resources/deploy.md)
 
-3. **Configure scopes to monitor.**
+2. **Configure scopes to monitor.**
 
    FinOps hubs use Cost Management exports to load the data you want to monitor. You can configure exports manually or grant access to your hub to manage exports for you.
 
    [Learn more](./configure-scopes.md)
 
-4. **Connect to your data.**
+3. **Connect to your data.**
 
    You can connect to your data from any system that supports Azure storage. For ideas, see [get started with hubs](#-get-started-with-hubs) below. We recommend using pre-built Power BI starter templates to get started quickly.
 
@@ -188,7 +182,7 @@ Required permissions for deploying or updating hub instances are covered in the
 
 You will need one or more of the following to export your cost data:
 
-| Scope                             | Permission                                                                                                                            |
+| Scope                                                 | Permission                                                                                                                             |
 | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
 | Subscriptions and resource groups (all account types) | [Cost Management Contributor](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#cost-management-contributor). |
 | EA billing scopes                                     | Enterprise Reader, Department Reader, or Account Owner (aka enrollment account).                                                       |

docs/_reporting/hubs/upgrade.md

@@ -20,6 +20,8 @@ Upgrade an existing FinOps hub instance to the latest version to leverage new ca
 - [Before you begin](#before-you-begin)
 - [Upgrading 0.0.1](#upgrading-001)
 - [Upgrading 0.1.x](#upgrading-01x)
+- [Upgrading 0.2](#upgrading-02)
+- [Upgrading 0.3](#upgrading-03)
 - [⏭️ Next steps](#️-next-steps)
 
 </details>
@@ -28,10 +30,6 @@ Upgrade an existing FinOps hub instance to the latest version to leverage new ca
 
 Upgrading a FinOps hub instance is usually the same as the initial setup but depending on what version you're moving from or to, you may have specific steps that are needed. Use the following sections to move from one version to another. If you have any questions, please [start a discussion](https://github.com/microsoft/finops-toolkit/discussions).
 
-<blockquote class="warning" markdown="1">
-  _The most common issue people face when upgrading to `0.2` is trying to use **new** Power BI reports with an **old** hub or using **old** Power BI reports with an **upgraded** hub. FinOps hubs and reports from the `0.0.1` and `0.1.x` releases are compatible, but they are not compatible with `0.2`._
-</blockquote>
-
 <br>
 
 ## Before you begin
@@ -65,6 +63,7 @@ Microsoft Online Services Agreement (MOSA, aka PAYG) and Microsoft internal subs
 If you have an EA or MCA account, please upgrade to `0.2` which uses the new [FOCUS](../../_docs/focus/README.md) cost data format and covers both billed (actual) and amortized costs with 30% less data size (and storage costs). This will be the baseline for all future updates.
 
 [See 0.2 upgrade instructions](#ea-and-mca-accounts-for-01x){: .btn .mb-4 .mb-md-0 .mr-4 }
+[View changes](../../_resources/changelog.md#-v01){: .btn .mb-4 .mb-md-0 .mr-4 }
 
 <br>
 
@@ -98,17 +97,45 @@ Before you upgrade, consider the following:
    - If you modified the reports, you will need to re-apply your changes to the new reports. Refer to [How to update existing reports to FOCUS](../../_docs/focus/README.md#how-to-update-existing-reports-to-focus) for details.
    - If you need your customized reports to continue to run while you upgrade, deploy a second instance of FinOps hubs using a different storage account to avoid data processing errors.
 
-Based on the above, use the following steps to upgrade your hub instance from `0.1.x` to `0.2.x`:
+Based on the above, use the following steps to upgrade your hub instance from `0.1.x` to `0.3`:
 
 1. Delete any amortized cost exports pointing to your hub instance.
 2. If desired, delete the historical amortized cost data to keep storage costs down.
-3. Deploy FinOps hubs `0.2.1` and create new FOCUS exports using the [Create a new hub](./README.md#-create-a-new-hub) instructions.
+3. Deploy FinOps hubs `0.3` and create new FOCUS exports using the [Create a new hub](./README.md#-create-a-new-hub) instructions.
    <blockquote class="note" markdown="1">
      _You can skip step 1 since resource providers have already been registered._
    </blockquote>
 4. Backfill historical data using the FOCUS export.
 
-[Download](https://github.com/microsoft/finops-toolkit/releases/tag/v0.2.1){: .btn .mb-4 .mb-md-0 .mr-4 }
+[Download 0.3](https://github.com/microsoft/finops-toolkit/releases/tag/v0.3){: .btn .mb-4 .mb-md-0 .mr-4 }
+[View changes](../../_resources/changelog.md#-v02){: .btn .mb-4 .mb-md-0 .mr-4 }
+
+<br>
+
+## Upgrading 0.2
+
+Upgrading FinOps hubs 0.2 to 0.4 is as simple as re-deploying the template and optionally update to the v0.3 Power BI reports. There are no breaking changes, so Power BI reports from v0.2 should work with v0.3 and vice-versa.
+
+[Download 0.3](https://github.com/microsoft/finops-toolkit/releases/tag/v0.3){: .btn .mb-4 .mb-md-0 .mr-4 }
+[View changes](../../_resources/changelog.md#-v03){: .btn .mb-4 .mb-md-0 .mr-4 }
+
+<br>
+
+## Upgrading 0.3
+
+Upgrading FinOps hubs 0.3 to 0.4 is as simple as re-deploying the template and optionally update to the v0.4 Power BI reports. There are no breaking changes, so Power BI reports from v0.3 should work with v0.4 and vice-versa.
+
+FinOps hubs 0.4 aligns with FOCUS 1.0, so you will notice changes to the following columns:
+
+- ChargeCategory is "Purchase" for refunds instead of "Adjustment".
+- ChargeClass (new) is "Correction" for refunds.
+- CommitmentDiscountStatus (new) replaces ChargeSubcategory for commitment discount usage.
+- Region is replaced by RegionId and RegionName.
+
+Reports work with both FOCUS 1.0 and FOCUS 1.0 preview exports, so there's no need to change exports in order to use the new reports. The reports themselves update the schema to meet FOCUS 1.0 requirements.
+
+[Download 0.4](https://github.com/microsoft/finops-toolkit/releases/tag/v0.4){: .btn .mb-4 .mb-md-0 .mr-4 }
+[View changes](../../_resources/changelog.md#-v04){: .btn .mb-4 .mb-md-0 .mr-4 }
 
 <br>
 

docs/_reporting/power-bi/README.md

@@ -30,7 +30,7 @@ Accelerate your analytics efforts with simple, targeted reports. Summarize and b
 <!-- markdownlint-disable-line --> {% include_relative _intro.md %}
 
 <blockquote class="note" markdown="1">
-   _As of FinOps toolkit 0.2, all reports have been updated to use the FinOps Open Cost and Usage Specification (FOCUS). To learn more, see [About FOCUS](../../_docs/focus/README.md)._
+   _As of FinOps toolkit 0.4, all reports have been updated to use the FinOps Open Cost and Usage Specification (FOCUS) 1.0. To use FOCUS 1.0 preview, please leverage the 0.3 toolkit release. To learn more, see [About FOCUS](../../_docs/focus/README.md)._
 </blockquote>
 
 <br>

src/optimization-engine/ftkver.txt

@@ -1 +1 @@
-0.2.1-rc.2
+0.4

src/powershell/Private/Save-FinOpsHubTemplate.ps1

@@ -66,11 +66,11 @@ function Save-FinOpsHubTemplate
         $releases = Get-FinOpsToolkitVersion -Latest:$($Version -eq 'Latest') -Preview:$Preview `
         | Where-Object { $_.Version -ne '0.2' -and ($azEnv -eq 'AzureCloud' -or $_.Version.StartsWith('0.0') -or $_.Version.StartsWith('0.1')) }  # 0.2 not supported in Azure Gov/China (as of Feb 2024)
 
-        # Redirect 0.2 to 0.2.1 due to bug
+        # Redirect 0.2 to 0.3 due to bug
         if ($Version -eq '0.2')
         {
             Write-Information $LocalizedData.Hub_Deploy_02to021
-            $Version = '0.2.1'
+            $Version = '0.3'
         }
 
         # TODO: Remove 0.2+ redirect for Azure Gov/China when FOCUS exports are supported

src/powershell/Tests/Unit/Save-FinOpsHubTemplate.Tests.ps1

@@ -93,25 +93,25 @@ InModuleScope FinOpsToolkit {
         }
 
         Context 'Version redirection' {
-            It 'Should redirect 0.2 to 0.2.1' {
+            It 'Should redirect 0.2 to 0.3' {
                 # Arrange
                 Mock -CommandName 'Get-AzContext' { @{ Environment = @{ Name = 'AzureCloud' } } }
-                Mock -CommandName 'Get-FinOpsToolkitVersion' { mockVersionList '0.2.1', '0.2', '0.1.1' }
+                Mock -CommandName 'Get-FinOpsToolkitVersion' { mockVersionList '0.3', '0.2', '0.1.1' }
 
                 # Act
                 Save-FinOpsHubTemplate -Version '0.2'
 
                 # Assert
-                Assert-MockCalled -CommandName 'Test-Path' -Times 1 -ParameterFilter { $Path.EndsWith('0.2.1.zip') }
+                Assert-MockCalled -CommandName 'Test-Path' -Times 1 -ParameterFilter { $Path.EndsWith('0.3.zip') }
             }
 
             It 'Should redirect 0.2 to 0.1.1 for Azure Gov' {
                 # Arrange
                 Mock -CommandName 'Get-AzContext' { @{ Environment = @{ Name = 'AzureGov' } } }
-                Mock -CommandName 'Get-FinOpsToolkitVersion' { mockVersionList '0.2.1', '0.2', '0.1.1' }
+                Mock -CommandName 'Get-FinOpsToolkitVersion' { mockVersionList '0.3', '0.2', '0.1.1' }
 
                 # Act
-                Save-FinOpsHubTemplate -Version '0.2.1'
+                Save-FinOpsHubTemplate -Version '0.3'
 
                 # Assert
                 Assert-MockCalled -CommandName 'Test-Path' -Times 1 -ParameterFilter { $Path.EndsWith('0.1.1.zip') }
@@ -120,10 +120,10 @@ InModuleScope FinOpsToolkit {
             It 'Should redirect 0.2 to 0.1.1 for Azure China' {
                 # Arrange
                 Mock -CommandName 'Get-AzContext' { @{ Environment = @{ Name = 'AzureChina' } } }
-                Mock -CommandName 'Get-FinOpsToolkitVersion' { mockVersionList '0.2.1', '0.2', '0.1.1' }
+                Mock -CommandName 'Get-FinOpsToolkitVersion' { mockVersionList '0.3', '0.2', '0.1.1' }
 
                 # Act
-                Save-FinOpsHubTemplate -Version '0.2.1'
+                Save-FinOpsHubTemplate -Version '0.3'
 
                 # Assert
                 Assert-MockCalled -CommandName 'Test-Path' -Times 1 -ParameterFilter { $Path.EndsWith('0.1.1.zip') }
@@ -132,7 +132,7 @@ InModuleScope FinOpsToolkit {
             It 'Should support 0.1.1 for Azure Gov' {
                 # Arrange
                 Mock -CommandName 'Get-AzContext' { @{ Environment = @{ Name = 'AzureGov' } } }
-                Mock -CommandName 'Get-FinOpsToolkitVersion' { mockVersionList '0.2.1', '0.2', '0.1.1' }
+                Mock -CommandName 'Get-FinOpsToolkitVersion' { mockVersionList '0.3', '0.2', '0.1.1' }
 
                 # Act
                 Save-FinOpsHubTemplate -Version '0.1.1'
@@ -144,7 +144,7 @@ InModuleScope FinOpsToolkit {
             It 'Should support 0.1.1 for Azure China' {
                 # Arrange
                 Mock -CommandName 'Get-AzContext' { @{ Environment = @{ Name = 'AzureChina' } } }
-                Mock -CommandName 'Get-FinOpsToolkitVersion' { mockVersionList '0.2.1', '0.2', '0.1.1' }
+                Mock -CommandName 'Get-FinOpsToolkitVersion' { mockVersionList '0.3', '0.2', '0.1.1' }
 
                 # Act
                 Save-FinOpsHubTemplate -Version '0.1.1'

src/powershell/en-US/FinOpsToolkit.strings.psd1

@@ -12,7 +12,7 @@ ConvertFrom-StringData -StringData @'
     Hub_Deploy_Deploy = Deploying FinOps hub '{0}' to resource group '{1}'.
     Hub_Deploy_TemplateNotFound = Could not find template 'main.bicep' at path '{0}'.
     Hub_Deploy_02to011 = Version 0.2 is not supported for Azure Gov and Azure China due to FOCUS exports not being available in Cost Management yet. Using version 0.1.1 instead.
-    Hub_Deploy_02to021 = Version 0.2 is not supported due to a bug in the deployment template. Using version 0.2.1 instead.
+    Hub_Deploy_02to021 = Version 0.2 is not supported due to a bug in the deployment template. Using version 0.3 instead.
     Hub_Remove_Failed = FinOps hub could not be deleted. {0}.
     Hub_Remove_NotFound = FinOps hub '{0}' not found.