Merge pull request #113 from Azure/feature/fixlink

Fixed broken links in markdown.

Docs/breaking-changes-v6.0.md

@@ -58,14 +58,14 @@ For details consult the above table and the newly updated samples in StarterKit.
 ```
 
 * If you're using Azure DevOps pipelines add parameter `-devOpsType "ado"` to `Build-DeploymentPlans.ps1`
-* Add required `MS Graph` [permissions](azure-devops-pipeline.md) for the pipeline service connections.
+* Add required `MS Graph` [permissions](ci-cd-pipeline.md#ms-graph-permissions) for the pipeline service connections.
 
 ## Reading List
 
 * [Setup DevOps Environment](operating-environment.md) .
 * [Create a source repository and import the source code](clone-github.md) from this repository.
 * [Select the desired state strategy](desired-state-strategy.md)
-* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md)
+* Copy starter kit pipeline definition and definition folder to your folders.
 * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`.
 * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit.
 * [Add custom Policy definitions](policy-definitions.md).

Docs/ci-cd-pipeline.md

@@ -27,7 +27,7 @@
 * [Azure DevOps Pipeline](#azure-devops-pipeline)
   * [Service Connections](#service-connections)
   * [Deployment Environments](#deployment-environments)
-* [Deployment Scripts for Pipeline](#deployment-scripts-for-pipeline)
+* [Deployment Scripts](#deployment-scripts)
   * [Common Script Parameters](#common-script-parameters)
   * [Build-DeploymentPlans.ps1](#build-deploymentplansps1)
   * [Deploy-PolicyPlan.ps1](#deploy-policyplanps1)
@@ -43,7 +43,7 @@
 
 The diagram below shows the use of GitHub Flow in Policy as Code. Builds are triggered for Commits, optionally for Pull Requests and for successful main branch merges.
 
-![image.png](Images/PaC-GitHub-Flow.png)
+![image.png](Images/epac-github-flow.png)
 
 ## Service connections for DevOps CI/CD
 
@@ -140,6 +140,7 @@ After you configure the Permissions (`Add a permission`), you must `Grant admin
 ![image,png](Images/ms-graph-permissions.png)
 
 Read the following Microsoft instructions to [learn more about MS Graph Application Permissions](https://learn.microsoft.com/en-us/graph/permissions-overview?tabs=http#application-permissions)
+
 1. [Register your app](https://learn.microsoft.com/en-us/graph/auth-v2-service#1-register-your-app)
 2. [Configure permissions for Microsoft Graph](<https://learn.microsoft.com/en-us/graph/auth-v2-service#2-configure-permissions-for-microsoft-graph>)
 3. [Get administrator consent](https://learn.microsoft.com/en-us/graph/auth-v2-service#3-get-administrator-consent)
@@ -189,7 +190,7 @@ Service connections give the pipeline the proper permissions to deploy at desire
 
 Create distinct ADO environment to configure approval gates. Refer to the following documentation:  <https://docs.microsoft.com/en-us/azure/devops/pipelines/process/environments?view=azure-devops>
 
-## Deployment Scripts for Pipeline
+## Deployment Scripts
 
 > ---
 > ---
@@ -203,6 +204,11 @@ Create distinct ADO environment to configure approval gates. Refer to the follow
 
 <br/>
 
+
+![image.pmg](Images/epac-deployment-scripts.png)
+
+<br/>
+
 ### Common Script Parameters
 
 |Parameter | Required | Explanation |
@@ -215,7 +221,7 @@ Create distinct ADO environment to configure approval gates. Refer to the follow
 
 Analyzes changes in policy, initiative, and assignment files. It calculates a plan to apply deltas. The deployment scripts are **declarative** and **idempotent**: this means, that regardless how many times they are run, they always push all changes that were implemented in the JSON files to the Azure environment, i.e. if a JSON file is newly created/updated/deleted, the pipeline will create/update/delete the Policy and/or Initiative definition in Azure. If there are no changes, the pipeline can be run any number of times, as it won't make any changes to Azure.
 
-In addition to the [common parameters](#common-parameters-for-flexible-and-unified-definitions), these parameters are defined:
+In addition to the [common parameters](#common-script-parameters), these parameters are defined:
 
 |Parameter | Required | Explanation |
 |----------|----------|-------------|
@@ -290,7 +296,7 @@ Detail view:
 * [Setup DevOps Environment](operating-environment.md) .
 * [Create a source repository and import the source code](clone-github.md) from this repository.
 * [Select the desired state strategy](desired-state-strategy.md)
-* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md)
+* Copy starter kit pipeline definition and definition folder to your folders.
 * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`.
 * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit.
 * [Add custom Policy definitions](policy-definitions.md).

Docs/clone-github.md

@@ -58,7 +58,7 @@ The repo contains a script to synchronize directories in both directions: `Sync-
 * [Setup DevOps Environment](operating-environment.md) .
 * [Create a source repository and import the source code](clone-github.md) from this repository.
 * [Select the desired state strategy](desired-state-strategy.md)
-* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md)
+* Copy starter kit pipeline definition and definition folder to your folders.
 * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`.
 * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit.
 * [Add custom Policy definitions](policy-definitions.md).

Docs/cloud-adoption-framework.md

@@ -79,7 +79,7 @@ Several of the assignment files also have parameters which need to be in place.
 * [Setup DevOps Environment](operating-environment.md) .
 * [Create a source repository and import the source code](clone-github.md) from this repository.
 * [Select the desired state strategy](desired-state-strategy.md)
-* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md)
+* Copy starter kit pipeline definition and definition folder to your folders.
 * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`.
 * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit.
 * [Add custom Policy definitions](policy-definitions.md).

Docs/definitions-and-global-settings.md

@@ -17,13 +17,13 @@
 
 **On this page**
 
-- [Folders](#folders)
-- [Global Settings](#global-settings)
-  - [Uniquely identify deployments `pacOwnerId`](#uniquely-identify-deployments-pacownerid)
-  - [Define EPAC Environments in `pacEnvironments`](#define-epac-environments-in-pacenvironments)
-  - [DeployIfNotExists and Modify Policy Assignments need `managedIdentityLocation`](#deployifnotexists-and-modify-policy-assignments-need-managedidentitylocation)
-  - [Excluding scopes for all Assignments with `globalNotScopes`](#excluding-scopes-for-all-assignments-with-globalnotscopes)
-- [Reading List](#reading-list)
+* [Folders](#folders)
+* [Global Settings](#global-settings)
+  * [Uniquely identify deployments `pacOwnerId`](#uniquely-identify-deployments-pacownerid)
+  * [Define EPAC Environments in `pacEnvironments`](#define-epac-environments-in-pacenvironments)
+  * [DeployIfNotExists and Modify Policy Assignments need `managedIdentityLocation`](#deployifnotexists-and-modify-policy-assignments-need-managedidentitylocation)
+  * [Excluding scopes for all Assignments with `globalNotScopes`](#excluding-scopes-for-all-assignments-with-globalnotscopes)
+* [Reading List](#reading-list)
 
 ## Folders
 
@@ -137,7 +137,7 @@ The arrays can have the following entries:
 - [Setup DevOps Environment](operating-environment.md) .
 - [Create a source repository and import the source code](clone-github.md) from this repository.
 - [Select the desired state strategy](desired-state-strategy.md)
-- [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md)
+- Copy starter kit pipeline definition and definition folder to your folders.
 - [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`.
 - [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit.
 - [Add custom Policy definitions](policy-definitions.md).

Docs/desired-state-strategy.md

@@ -109,7 +109,7 @@ By default, Policy Assignments at resource groups are not managed by EPAC. Prior
 * [Setup DevOps Environment](operating-environment.md) .
 * [Create a source repository and import the source code](clone-github.md) from this repository.
 * [Select the desired state strategy](desired-state-strategy.md)
-* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md)
+* Copy starter kit pipeline definition and definition folder to your folders.
 * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`.
 * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit.
 * [Add custom Policy definitions](policy-definitions.md).

Docs/documenting-assignments-and-policy-sets.md

@@ -17,7 +17,7 @@
 
 The Documentation feature provides reports on Initiatives and Assignments deployed within an environment, and comparisons of Initiatives (deployed or not) for considering differences in policies and effects.  Output is generated as Markdown (`.md`), and Excel (`.csv`) files.
 
-The script [`./Scripts/Operations/Build-PolicyAssignmentDocumentation.ps1`](../../Scripts/Operations/README.md#build-policyassignmentdocumentationps1) documents Initiatives and Assignments in your environment. It retrieves its instruction from the JSON files in this folder; the names of the definition JSON files don't matter as the script reads any file in the folder with a `.json` and `.jsonc` extension.
+The script [`./Scripts/Operations/Build-PolicyAssignmentDocumentation.ps1`](operational-scripts.md#build-policyassignmentdocumentationps1) documents Initiatives and Assignments in your environment. It retrieves its instruction from the JSON files in this folder; the names of the definition JSON files don't matter as the script reads any file in the folder with a `.json` and `.jsonc` extension.
 
 * Read and process Policy Assignments which are representative of an environment category, such as prod, test, dev, and sandbox. It generates Markdown (`.md`), and Excel (`.csv`) files.
 * Read and process Initiative definitions to compare them for Policy and effect overlap. It generates Markdown (`.md`), Excel (`.csv`) files, and JSON file (`.jsonc`).
@@ -26,8 +26,8 @@ The script [`./Scripts/Operations/Build-PolicyAssignmentDocumentation.ps1`](../.
 
 Each file must contain one or both documentation topics. This example file in the StarterKit has both topics. Element `pacEnvironment` references the Policy as Code environment in `global-settings.jsonc` defining the tenant and root scope where the custom Policy and Initiative definitions are deployed.
 
-* [`documentAssignments`](#specifying-assignment-documentation)
-* [`documentInitiatives`](#specifying-initiative-documentation)
+* [`documentAssignments`](#assignment-documentation)
+* [`documentInitiatives`](#initiative-documentation)
 
 ```jsonc
 {
@@ -146,10 +146,6 @@ Each `environmentCategories` entry specifies:
 
 ### Element `documentationSpecifications`
 
-> **Warning: Breaking change in release v5.3**
->
-> `type` is no longer needed and the field has been removed. The only previous `type` available is `effectsAcrossEnvironments`; the script will write a warning if it is specified. Specifying `"type": "effectsPerEnvironment",` will result in a script error.
-
 Each entry in the array defines a set of outputs:
 
 * `fileNameStem`: the file name stem used to construct the filenames.
@@ -226,7 +222,7 @@ Compares Policy and Initiative definitions to  Initiative definitions for Policy
 * [Setup DevOps Environment](operating-environment.md) .
 * [Create a source repository and import the source code](clone-github.md) from this repository.
 * [Select the desired state strategy](desired-state-strategy.md)
-* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md)
+* Copy starter kit pipeline definition and definition folder to your folders.
 * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`.
 * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit.
 * [Add custom Policy definitions](policy-definitions.md).

Docs/operating-environment.md

@@ -67,7 +67,7 @@ Agents (also called runners) are often hosted in VMs within Azure itself. It is
 * [Setup DevOps Environment](operating-environment.md) .
 * [Create a source repository and import the source code](clone-github.md) from this repository.
 * [Select the desired state strategy](desired-state-strategy.md)
-* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md)
+* Copy starter kit pipeline definition and definition folder to your folders.
 * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`.
 * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit.
 * [Add custom Policy definitions](policy-definitions.md).

Docs/operational-scripts.md

@@ -48,7 +48,7 @@ This script executes all remediation tasks in a Policy as Code environment speci
 
 ## Build-PolicyAssignmentDocumentation.ps1
 
-Generates documentation for assignments and initiatives based on JSON files in `$definitionsFolder/Documentation`. [See Define Documentation for details](../../Definitions/Documentation/README.md).
+Generates documentation for assignments and initiatives based on JSON files in `$definitionsFolder/Documentation`. [See Define Documentation for details](documenting-assignments-and-policy-sets.md).
 
 |Parameter | Required | Explanation |
 |----------|----------|-------------|
@@ -133,7 +133,7 @@ Exports a policy assignment from Azure to a local file in the EPAC format. Provi
 * [Setup DevOps Environment](operating-environment.md) .
 * [Create a source repository and import the source code](clone-github.md) from this repository.
 * [Select the desired state strategy](desired-state-strategy.md)
-* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md)
+* Copy starter kit pipeline definition and definition folder to your folders.
 * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`.
 * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit.
 * [Add custom Policy definitions](policy-definitions.md).

Docs/policy-assignments.md

@@ -19,7 +19,7 @@
 
 ## Components
 
-This chapter describes how **Policy Assignments** are handled by EPAC. To learn about how custom Policy and Initiative definitions are managed, see the [Policy Definitions](../Policies/README.md) and [Initiative Definitions](../Initiatives/README.md).
+This chapter describes how **Policy Assignments** are handled by EPAC. To learn about how custom Policy and Initiative definitions are managed, see the [Policy Definitions](policy-definitions.md) and [Policy Set (Initiative) Definitions](policy-set-definitions.md).
 
 The components required for **creating / updating / deleting Policy assignments and Policy set (initiative) assignments** are the following:
 
@@ -98,17 +98,17 @@ If you are using multiple Policy Sets, than EPAC will:
 
 ### Single node to assign allowed locations enforcement
 
-Assignment file [allowed-locations-assignments.jsonc](../../StarterKit/Definitions/policyAssignments/allowed-locations-assignments.jsonc) contains a single node to assign a single Initiative to one scope.
+Assignment file [allowed-locations-assignments.jsonc](../StarterKit/Definitions/policyAssignments/allowed-locations-assignments.jsonc) contains a single node to assign a single Initiative to one scope.
 
 ### Hierarchy to assign security and compliance initiatives
 
-Assignment file [security-baseline-assignments.jsonc](../../StarterKit/Definitions/policyAssignments/security-baseline-assignments.jsonc) contains 2 levels of hierarchy containing the root node and 2 child nodes. It uses a `definitionEntryList` instead of `definitionEntry`. Defining this with the `definitionEntry` approach would have increased the hierarchy from 2 levels (3 nodes) to 3 levels (7 nodes).
+Assignment file [security-baseline-assignments.jsonc](../StarterKit/Definitions/policyAssignments/security-baseline-assignments.jsonc) contains 2 levels of hierarchy containing the root node and 2 child nodes. It uses a `definitionEntryList` instead of `definitionEntry`. Defining this with the `definitionEntry` approach would have increased the hierarchy from 2 levels (3 nodes) to 3 levels (7 nodes).
 
 **Note**: With only two types of environments, 3 nodes versus 7 nodes is a small difference; however if you have a more complex environment differentiation with lots of environment types and parameters this becomes quickly untenable. As an extreme illustration with 8 environments (e.g., sandbox, dev, integration, testing, uat, perf, pre-prod and prod), you would need to specify 25 nodes. Such a file would likely be thousands of lines long and completely unreadable.
 
 ### Hierarchy to manage Azure resource tags
 
-Assignment file [tag-assignments.jsonc](../../StarterKit/Definitions/policyAssignments/tag-assignments.jsonc) defines:
+Assignment file [tag-assignments.jsonc](../StarterKit/Definitions/policyAssignments/tag-assignments.jsonc) defines:
 
 * Required tags and inherited tags with a `definitionEntryList` using 2 levels (plus the root node)
 * Environment tag values for resource groups with a `definitionEntry` using two levels (plus the shared root node)
@@ -118,7 +118,7 @@ Assignment file [tag-assignments.jsonc](../../StarterKit/Definitions/policyAssig
 * [Setup DevOps Environment](operating-environment.md) .
 * [Create a source repository and import the source code](clone-github.md) from this repository.
 * [Select the desired state strategy](desired-state-strategy.md)
-* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md)
+* Copy starter kit pipeline definition and definition folder to your folders.
 * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`.
 * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit.
 * [Add custom Policy definitions](policy-definitions.md).

Docs/policy-definitions.md

@@ -69,7 +69,7 @@ The names of the definition JSON files don't matter, the Policy and Initiative d
 * [Setup DevOps Environment](operating-environment.md) .
 * [Create a source repository and import the source code](clone-github.md) from this repository.
 * [Select the desired state strategy](desired-state-strategy.md)
-* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md)
+* Copy starter kit pipeline definition and definition folder to your folders.
 * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`.
 * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit.
 * [Add custom Policy definitions](policy-definitions.md).

Docs/policy-exemptions.md

@@ -43,6 +43,7 @@ The pacEnvironment (see global-settings.jsonc) is represented with a folder, suc
 ### CSV/XLSX Format
 
 If you use spreadsheets (.csv or .xlsx):
+
 * Column headers must be exactly as the JSON labels above.
 * `policyDefinitionReferenceIds` use comma separated list within each cell.
 * `metadata` cells must contain valid JSON.
@@ -52,7 +53,7 @@ If you use spreadsheets (.csv or .xlsx):
 * [Setup DevOps Environment](operating-environment.md) .
 * [Create a source repository and import the source code](clone-github.md) from this repository.
 * [Select the desired state strategy](desired-state-strategy.md)
-* [Copy starter kit pipeline definition and definition folder to your folders](starter-kits.md)
+* Copy starter kit pipeline definition and definition folder to your folders.
 * [Define your deployment environment](definitions-and-global-settings.md) in `global-settings.jsonc`.
 * [Build your CI/CD pipeline](ci-cd-pipeline.md) using a starter kit.
 * [Add custom Policy definitions](policy-definitions.md).