Improving documentation of importing resources (#403)

.gitignore

@@ -82,3 +82,5 @@ makefile
 
 # MSI files
 *.msi
+
+examples/temp

docs/guides/importing.md

@@ -0,0 +1,53 @@
+---
+page_title: "Importing existing Power Platform resources"
+subcategory: "Guides"
+description: |-
+  <no value>
+---
+
+# Importing existing Power Platform resources
+
+Many of the resources in the Power Platform provider can be imported into your Terraform configuration.  This guide will show you how to import existing resources into your configuration.  Resources that can be imported have an `import` section in their documentation.
+
+## Using `terraform import`
+
+Using `terraform import` will only import resources into the state.  It does not generate configuration and requires that you write the configuration yourself and ensure that it is correct.
+
+```bash
+terraform import powerplatform_environment.example_env 00000000-0000-0000-0000-000000000001
+```
+
+## Using import blocks
+
+Terraform allows the use of import blocks to import existing resources into your configuration.  This can be useful if you have pre-existing resources that you want to manage with Terraform.  The following is an example of an import block used to import the default Power Platform environment:
+
+```terraform
+import {
+  to = powerplatform_environment.example_env
+  id = "00000000-0000-0000-0000-000000000001"
+}
+
+resource "powerplatform_environment" "default" {
+  display_name     = "Contoso (default)"
+  location         = "unitedstates"
+  environment_type = "Default"
+  dataverse = {
+    currency_code     = "USD"
+    language_code     = 1033
+    security_group_id = "00000000-0000-0000-0000-000000000000"
+  }
+
+  lifecycle {
+    prevent_destroy = true
+  }
+}
+```
+Terraform processes the import block during the plan stage. Once a plan is approved, Terraform imports the resource into its state during the subsequent apply stage.
+
+```bash
+terraform apply
+```
+
+## Generating configuration
+
+Terraform has [experimental support for generating configuration from import blocks](https://developer.hashicorp.com/terraform/language/import/generating-configuration).  This feature is not perfect, but it can help you get started with your configuration if you have some pre-existing resources.

docs/resources/billing_policy.md

@@ -116,3 +116,12 @@ Optional:
 - `delete` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours). Setting a timeout for a Delete operation is only applicable if changes are saved into state before the destroy operation occurs.
 - `read` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours). Read operations occur during any refresh or planning operation when refresh is enabled.
 - `update` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours).
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# Billing policies can be imported using the billing policy id (replace with a real billing policy guid)
+terraform import powerplatform_billing_policy.example 00000000-0000-0000-0000-000000000000
+```

docs/resources/data_loss_prevention_policy.md

@@ -251,3 +251,12 @@ Optional:
 - `delete` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours). Setting a timeout for a Delete operation is only applicable if changes are saved into state before the destroy operation occurs.
 - `read` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours). Read operations occur during any refresh or planning operation when refresh is enabled.
 - `update` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours).
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# DLP Policies can be imported using the DLP policy id (replace with a real DLP Policy guid)
+terraform import powerplatform_data_loss_prevention_policy.example_dlp 00000000-0000-0000-0000-000000000000
+```

docs/resources/environment.md

@@ -20,8 +20,6 @@ A Power Platform environment is a space in which you can store, manage, and shar
 
 ## Example Usage
 
-
-
 ```terraform
 terraform {
   required_providers {
@@ -104,5 +102,11 @@ Optional:
 - `read` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours). Read operations occur during any refresh or planning operation when refresh is enabled.
 - `update` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours).
 
+## Import
 
+Import is supported using the following syntax:
 
+```shell
+# Environment resource can be imported using the environment id (replace with a real environment guid)
+terraform import powerplatform_environment.example 00000000-0000-0000-0000-000000000000
+```

docs/resources/environment_group.md

@@ -70,3 +70,12 @@ resource "powerplatform_tenant_settings" "environment_routing" {
 ### Read-Only
 
 - `id` (String) Unique id of the environment group
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# Environment Groups can be imported using the environment group id (replace with a real environment group guid)
+terraform import powerplatform_environment_group.example 00000000-0000-0000-0000-000000000000
+```

examples/resources/powerplatform_billing_policy/import.sh

@@ -0,0 +1,2 @@
+# Billing policies can be imported using the billing policy id (replace with a real billing policy guid)
+terraform import powerplatform_billing_policy.example 00000000-0000-0000-0000-000000000000

examples/resources/powerplatform_data_loss_prevention_policy/import.sh

@@ -0,0 +1,2 @@
+# DLP Policies can be imported using the DLP policy id (replace with a real DLP Policy guid)
+terraform import powerplatform_data_loss_prevention_policy.example_dlp 00000000-0000-0000-0000-000000000000

examples/resources/powerplatform_environment/import.sh

@@ -0,0 +1,2 @@
+# Environment resource can be imported using the environment id (replace with a real environment guid)
+terraform import powerplatform_environment.example 00000000-0000-0000-0000-000000000000

examples/resources/powerplatform_environment_group/import.sh

@@ -0,0 +1,2 @@
+# Environment Groups can be imported using the environment group id (replace with a real environment group guid)
+terraform import powerplatform_environment_group.example 00000000-0000-0000-0000-000000000000

internal/powerplatform/services/environment/models_environment.go

@@ -16,7 +16,7 @@ import (
 )
 
 var (
-	EnvironmentTypes = []string{"Sandbox", "Production", "Trial", "Developer"}
+	EnvironmentTypes = []string{"Sandbox", "Production", "Trial", "Developer", "Default"}
 )
 
 type EnvironmentDto struct {

templates/guides/importing.md.tmpl

@@ -0,0 +1,53 @@
+---
+page_title: "Importing existing Power Platform resources"
+subcategory: "Guides"
+description: |-
+  {{ .Description }}
+---
+
+# Importing existing Power Platform resources
+
+Many of the resources in the Power Platform provider can be imported into your Terraform configuration.  This guide will show you how to import existing resources into your configuration.  Resources that can be imported have an `import` section in their documentation.
+
+## Using `terraform import`
+
+Using `terraform import` will only import resources into the state.  It does not generate configuration and requires that you write the configuration yourself and ensure that it is correct.
+
+```bash
+terraform import powerplatform_environment.example_env 00000000-0000-0000-0000-000000000001
+```
+
+## Using import blocks
+
+Terraform allows the use of import blocks to import existing resources into your configuration.  This can be useful if you have pre-existing resources that you want to manage with Terraform.  The following is an example of an import block used to import the default Power Platform environment:
+
+```terraform
+import {
+  to = powerplatform_environment.example_env
+  id = "00000000-0000-0000-0000-000000000001"
+}
+
+resource "powerplatform_environment" "default" {
+  display_name     = "Contoso (default)"
+  location         = "unitedstates"
+  environment_type = "Default"
+  dataverse = {
+    currency_code     = "USD"
+    language_code     = 1033
+    security_group_id = "00000000-0000-0000-0000-000000000000"
+  }
+
+  lifecycle {
+    prevent_destroy = true
+  }
+}
+```
+Terraform processes the import block during the plan stage. Once a plan is approved, Terraform imports the resource into its state during the subsequent apply stage.
+
+```bash
+terraform apply
+```
+
+## Generating configuration
+
+Terraform has [experimental support for generating configuration from import blocks](https://developer.hashicorp.com/terraform/language/import/generating-configuration).  This feature is not perfect, but it can help you get started with your configuration if you have some pre-existing resources.

templates/resources/environment.md.tmpl

@@ -6,7 +6,7 @@ description: |-
 
 # {{.Name}} ({{.Type}})
 
-{{ .Description }}
+{{ .Description | trimspace }}
 
 A Power Platform environment is a space in which you can store, manage, and share your organization's business data, apps, chatbots, and flows. It also serves as a container to separate apps that may have different roles, security requirements, or target audiences. Each environment is created under an Azure Active Directory tenant and is bound to a geographic location. You can create different types of environments, such as production, sandbox, trial, or developer, depending on your license and permissions. You can also move resources between environments and set data loss prevention policies. A Power Platform environment can have zero or one Microsoft Dataverse database, which provides storage for your apps and chatbots. You can only connect to the data sources that are deployed in the same environment as your app or chatbot. For more information, you can check out the following links:
 
@@ -18,12 +18,18 @@ A Power Platform environment is a space in which you can store, manage, and shar
 
 - Service principals can't create development type environments
 
+{{ if .HasExample -}}
 ## Example Usage
 
-{{ if .HasImport }}
-{{ tffile .ImportFile }}
-{{ end }}
+{{tffile .ExampleFile }}
+{{- end }}
 
-{{ tffile .ExampleFile }}
+{{ .SchemaMarkdown | trimspace }}
+{{- if .HasImport }}
 
-{{ .SchemaMarkdown }}
+## Import
+
+Import is supported using the following syntax:
+
+{{codefile "shell" .ImportFile }}
+{{- end }}