Merge pull request #39 from Azure/feature/heinrich

- Implemented import of PolicyDefinitionGroups from built-in Initiatives to custom Initiatives
- Updated scripts (cleanup)
- Documented approach for getting updates from this repo to your working copy repo without overwriting you changes
- Documented approach to contributing to the project without sharing your information, such as your tenant id, management groups, and subscription
- Created a script Sync-Repo.ps1 to facilitate the above synchronization tasks
- Improved structure to facilitate synchronization

Definitions/Assignments/README.md

@@ -1,14 +1,28 @@
 
 # Policy Assignments
 
+## Table of Contents
+
+- [Components](#components)
+- [Assignment File Overview Diagram](#assignment-file-overview-diagram)
+- [Assignment JSON file structure](#assignment-json-file-structure)
+- [Assignment Node Components](#assignment-node-components)
+- [Details for `scope` and `notScope` Values](#details-for--scope--and--notscope--values)
+- [Using the `PacAssignmentSelector`](#using-the--pacassignmentselector-)
+- [Resource Group patterns in `notScope`](#resource-group-patterns-in--notscope-)
+- [Example Scope Definition](#example-scope-definition)
+- [Reading List](#reading-list)
+
+## Components
+
 This chapter describes how **Policy Assignments** are handled by PaC. To learn about how custom Policy and Initiative definitions are managed, see the [Policy Definitions](../Policies/README.md) and [Initiative Definitions](../Initiatives/README.md).
 
 The components required for **creating / updating / deleting Policy assignments and Policy set (initiative) assignments** are the following:
 
 | Component | What is it used for? | Where can it be found? |
 |--|--|--|
 | **Assignment JSON files** | The assignments JSON file follows the management group hierarchy (optionally including subscriptions and resource groups) and defines all policy and initiative assignments on these scopes. | `Definitions/Assignments` folder |
-| **Global Settings File** | The `global-settings.jsonc` file specifies common values for Policy Assignments  |`Definitions` folder |
+| **Global Settings File** | The `global-settings.jsonc` file specifies common values for Policy Assignments  | `Definitions` folder |
 
 <br/>[Back to top](#policy-assignments)<br/>
 
@@ -197,7 +211,7 @@ The assignment selector determines the array being selected for this run of the
 
 1. **[Define Policy Assignments](../../Definitions/Assignments/README.md)**
 
-1. **[Scripts](../../Scripts/README.md)**
+1. **[Operational Scripts](../../Scripts/Operations/README.md)**
 
 **[Return to the main page](../../README.md)**
 <br/>[Back to top](#policy-assignments)<br/>

Definitions/Initiatives/README.md

@@ -1,13 +1,18 @@
 # Initiative Definitions
 
-This chapter describes how Initiative (Policy Set) definitions are handled by the Policy-as-Code framework.
+## Table of Contents
 
-> **NOTE**:
-> When authoring policy/initiative definitions, check out the [Maximum count of Azure Policy objects](https://docs.microsoft.com/en-us/azure/governance/policy/overview#maximum-count-of-azure-policy-objects)
+- [Initiative (Policy Set) Definition Files](#initiative--policy-set--definition-files)
+- [Recommendations](#recommendations)
+- [Example](#example)
+- [Reading List](#reading-list)
+
+## Initiative (Policy Set) Definition Files
 
 The names of the definition JSON files don't matter, the Initiative definitions are registered based on the `name` attribute. It is recommended that you use a `GUID` as the `name`. The solution also allows the use of JSON with comments by using `.jsonc` instead of `.json` for the file extension.
 
-## Initiative (Policy Set) Definition Files
+> **NOTE**:
+> When authoring policy/initiative definitions, check out the [Maximum count of Azure Policy objects](https://docs.microsoft.com/en-us/azure/governance/policy/overview#maximum-count-of-azure-policy-objects)
 
 The Initiative definition files are structured based on the official [Azure Initiative definition structure](https://docs.microsoft.com/en-us/azure/governance/policy/concepts/initiative-definition-structure) published by Microsoft. There are numerous definition samples available on Microsoft's [GitHub repository for azure-policy](https://github.com/Azure/azure-policy/tree/master/built-in-policies/policySetDefinitions).
 
@@ -96,7 +101,7 @@ The Initiative definition files are structured based on the official [Azure Init
 
 1. **[Define Policy Assignments](../../Definitions/Assignments/README.md)**
 
-1. **[Scripts](../../Scripts/README.md)**
+1. **[Operational Scripts](../../Scripts/Operations/README.md)**
 
 **[Return to the main page](../../README.md)**
 <br/>[Back to top](#initiative-definitions)<br/>

Definitions/Policies/README.md

@@ -1,27 +1,31 @@
 # Policy Definitions
 
-This chapter describes how Policy definitions are handled by the Policy-as-Code framework.
-Policy definitions do not evaluate resources until they are assigned to a specific scope with an Assignment.
+## Table of Contents
 
-> **NOTE**:
-> When authoring policy/initiative definitions, check out the [Maximum count of Azure Policy objects](https://docs.microsoft.com/en-us/azure/governance/policy/overview#maximum-count-of-azure-policy-objects)
+- [Policy Definition Files](#policy-definition-files)
+- [Recommendations](#recommendations)
+- [Example](#example)
+- [Reading List](#reading-list)
+
+## Policy Definition Files
 
 The names of the definition JSON files don't matter, the Policy and Initiative definitions are registered based on the `name` attribute. It is recommended that you use a `GUID` as the `name`. The solution also allows the use of JSON with comments by using `.jsonc` instead of `.json` for the file extension.
 
-## Policy Definition Files
+> **NOTE**:
+> When authoring policy/initiative definitions, check out the [Maximum count of Azure Policy objects](https://docs.microsoft.com/en-us/azure/governance/policy/overview#maximum-count-of-azure-policy-objects)
 
 The Policy definition files are structured based on the official [Azure Policy definition structure](https://docs.microsoft.com/en-us/azure/governance/policy/concepts/definition-structure) published by Microsoft. There are numerous definition samples available on Microsoft's [GitHub repository for azure-policy](https://github.com/Azure/azure-policy).
 
 <br/>[Back to top](#policy-definitions)<br/>
 
 ## Recommendations
 
-* `"name"` should be a GUID - see <https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-guid?view=powershell-7.2>.
-* `"category"` should be one of the standard ones defined in built-in Policy definitions.
-* Do not specify an `id`.
-* Make the `effect` parameterized.
-* Whenever feasible, provide a `defaultValue` for parameters, especially for an `effect` parameter.
-* Policy aliases are used by Azure Policy to refer to resource type properties in the `if` condition and in `existenceCondition`: <https://docs.microsoft.com/en-us/azure/governance/policy/concepts/definition-structure#aliases>.
+- `"name"` should be a GUID - see <https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-guid?view=powershell-7.2>.
+- `"category"` should be one of the standard ones defined in built-in Policy definitions.
+- Do not specify an `id`.
+- Make the `effect` parameterized.
+- Whenever feasible, provide a `defaultValue` for parameters, especially for an `effect` parameter.
+- Policy aliases are used by Azure Policy to refer to resource type properties in the `if` condition and in `existenceCondition`: <https://docs.microsoft.com/en-us/azure/governance/policy/concepts/definition-structure#aliases>.
 
 <br/>[Back to top](#policy-definitions)<br/>
 
@@ -78,7 +82,7 @@ The Policy definition files are structured based on the official [Azure Policy d
 
 1. **[Define Policy Assignments](../../Definitions/Assignments/README.md)**
 
-1. **[Scripts](../../Scripts/README.md)**
+1. **[Operational Scripts](../../Scripts/Operations/README.md)**
 
 **[Return to the main page](../../README.md)**
 <br/>[Back to top](#policy-definitions)<br/>

Definitions/README.md

@@ -7,12 +7,25 @@
 - Policy Assignments must be at this scope or below.
 - Operational tasks, such as `Create-AzRemediationTasks.ps1`, must use the same rootScope or they will fail.
 
+## Table of Content
+
+- [Folders](#folders)
+- [Global Settings](#global-settings)
+  - [managedIdentityLocation](#managedidentitylocation)
+  - [globalNotScopes](#globalnotscopes)
+  - [pacEnvironments](#pacenvironments)
+  - [representativeAssignments](#representativeassignments)
+  - [initiativeSetsToCompare](#initiativesetstocompare)
+- [Reading List](#reading-list)
+
+## Folders
+
 This folder and subfolders contain the definitions to deploy. Tasks:
 
 1. Define the Azure environment in **[global-settings.jsonc](#global-settings)**
 1. Create custom Policy definitions (optional) in folder **[Policies](Policies/README.md)**
 1. Create custom Initiative definitions (optional) in folder **[Initiatives](Initiatives/README.md)**
-1. Define the Policy Assignments in folder **[Policy Assignments](Assignments/README.md)**
+1. Define the Policy Assignments in folder **[Assignments](Assignments/README.md)**
 
 ## Global Settings
 
@@ -195,7 +208,7 @@ Each entry in the array defines one of the environmnent types:
 
 1. **[Define Policy Assignments](../Definitions/Assignments/README.md)**
 
-1. **[Scripts](../Scripts/README.md)**
+1. **[Operational Scripts](../Scripts/Operations/README.md)**
 
 **[Return to the main page](../README.md)**
 <br/>[Back to top](#pipeline)<br/>

Pipeline/README.md

@@ -1,10 +1,22 @@
 # Pipeline
 
-This article of the Policy as Code documentation contains all of the necessary information to configure, run and operate the deployment pipeline properly.
-
 This repository contains starter pipeline definitions for Azure DevOps. **The authors are interested in supporting other deployment pipelines. If you have developed pipelines for other technologies, such as GitHub, Jenkins, ...**
 
-<br/>[Back to top](#pipeline)<br/>
+## Table of Contents
+
+- [Components](#components)
+- [GitHub Flow for Policy as Code Flows](#github-flow-for-policy-as-code-flows)
+- [Single Tenant Pipeline Stages with Role Separation](#single-tenant-pipeline-stages-with-role-separation)
+- [Service Connections and Roles](#service-connections-and-roles)
+- [Deployment Scripts for Pipeline](#deployment-scripts-for-pipeline)
+- [Scripts per Stage](#scripts-per-stage)
+  - [Script Flow](#script-flow)
+  - [Common Script Parameters](#common-script-parameters)
+  - [Build-AzPoliciesInitiativesAssignmentsPlan.ps1](#build-azpoliciesinitiativesassignmentsplanps1)
+  - [Deploy-AzPoliciesInitiativesAssignmentsFromPlan.ps1](#deploy-azpoliciesinitiativesassignmentsfromplanps1)
+  - [Set-AzPolicyRolesFromPlan.ps1](#set-azpolicyrolesfromplanps1)
+- [Pipeline Execution](#pipeline-execution)
+- [Reading List](#reading-list)
 
 ## Components
 
@@ -19,7 +31,7 @@ The components required for **configuring the pipeline and deploying policies, i
 
 <br/>[Back to top](#pipeline)<br/>
 
-## GitHub Flow for Policy as Code Flows
+## GitHub Flow for Policy as Code
 
 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.
 
@@ -83,20 +95,27 @@ Create service connections for each of your environments and require minimum rol
 
 <br/>[Back to top](#pipeline)<br/>
 
-### **Script:** Build-AzPoliciesInitiativesAssignmentsPlan.ps1
+### Common Script Parameters
+
+|Parameter | Required | Explanation |
+|----------|----------|-------------|
+| `PacEnvironmentSelector` | Optional | Selects the tenant, rootScope, defaultSubscription, assignment scopes/notScope and file names. If omitted, interactively prompts for the value. |
+| `DefinitionsRootFolder` | Optional | Definitions folder path. Defaults to environment variable `$env:PAC_DEFINITIONS_ROOT_FOLDER` or `./Definitions`. It contains `global-settings.jsonc`.
+
+<br/>[Back to top](#pipeline)<br/>
+
+### Build-AzPoliciesInitiativesAssignmentsPlan.ps1
 
 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-parmeters-for-flexible-and-unified-definitions), these parameters are defined:
 
 |Parameter | Required | Explanation |
 |----------|----------|-------------|
-| `PacEnvironmentSelector` | Required | Selects the tenant, rootScope, defaultsubscription, assignment scopes and file names. If omitted, interactively prompts for the value. |
 | `IncludeResource GroupsForAssignments` | Optional | Resource Group level assignments are not recommended; therefore, the script excludes Resource Groups from processing to save substantial execution time (tens of minutes to hours). This switch parameter overrides that default behavior. |
 | `SuppressDeletes` | Optional | When using this switch, the script will NOT delete extraneous Policy definitions, Initiative definitions and Assignments. This can be useful for brown field deployments. |
-| `DefinitionsRootFolder` | Optional | Definitions folder path. Defaults to environment variable PacDefinitionsRootFolder or './Definitions'. It contains `global-settings.jsonc` and folders `Policies`, `Initiatives` and `Assignments`. |
-| `PlanFile` | Optional | Plan output file (Json). Plan output filename. If empty it is read from `GlobalSettingsFile`. |
-
+| `PlanFile` | Optional | Plan filename. Defaults to environment variable `$env:PAC_OUTPUT_FOLDER/Plans/$PacEnvironmentSelector-plan.json` or `./Outputs/Plans/$PacEnvironmentSelector-plan.json`. |
+| `RolesPlanFile` | Optional | Role Assignment plan output filename. Defaults to environment
 <br/>[Back to top](#pipeline)<br/>
 
 ### Deploy-AzPoliciesInitiativesAssignmentsFromPlan.ps1
@@ -105,8 +124,8 @@ Deploys Policies, Initiatives, and Policy Assignments at their desired scope bas
 
 |Parameter | Required | Explanation |
 |----------|----------|-------------|
-| `PlanFile` | Required | Plan input file (Json). |
-| `RolesPlanFile` | Required | Role Assignment plan output file. |
+| `PlanFile` | Optional | Plan filename. Defaults to environment variable `$env:PAC_OUTPUT_FOLDER/Plans/$PacEnvironmentSelector-plan.json` or `./Outputs/Plans/$PacEnvironmentSelector-plan.json`. |
+| `RolesPlanFile` | Optional | Role Assignment plan filename. Defaults to environment variable `$env:PAC_OUTPUT_FOLDER/Plans/$PacEnvironmentSelector-roles.json` or `./Outputs/Plans/$PacEnvironmentSelector-roles.json`. |
 
 <br/>[Back to top](#pipeline)<br/>
 
@@ -116,7 +135,7 @@ Creates the role assignments for the Managed Identities required for `DeployIfNo
 
 |Parameter | Required | Explanation |
 |----------|----------|-------------|
-| `RolesPlanFile` | Required | Role Assignments plan input file. |
+| `RolesPlanFile` | Optional | Role Assignment plan filename. Defaults to environment variable `$env:PAC_OUTPUT_FOLDER/Plans/$PacEnvironmentSelector-roles.json` or `./Outputs/Plans/$PacEnvironmentSelector-roles.json`. |
 
 <br/>[Back to top](#pipeline)<br/>
 
@@ -158,7 +177,7 @@ If there are no changes, empty stage(s) are executed to explicitly show that no
 
 1. **[Define Policy Assignments](../Definitions/Assignments/README.md)**
 
-1. **[Scripts](../Scripts/README.md)**
+1. **[Operational Scripts](../Scripts/Operations/README.md)**
 
 **[Return to the main page](../README.md)**
 <br/>[Back to top](#pipeline)<br/>