From acfdfb5db2093c8ade872d87469839888fd129f9 Mon Sep 17 00:00:00 2001 From: mawasile <50197777+mawasile@users.noreply.github.com> Date: Thu, 10 Oct 2024 21:46:14 +0200 Subject: [PATCH] Refactor output.tf and variables.tf for powerplatform_data_record (#492) Co-authored-by: github-actions[bot] --- .../documentation-20241010-194509.yaml | 5 + .changie.yaml | 3 + docs/resources/data_record.md | 305 ++++++++++++++++-- .../powerplatform_data_record/output.tf | 9 - .../res_application_user/main.tf | 59 ++++ .../res_role/main.tf | 52 +++ .../res_team/main.tf | 52 +++ .../powerplatform_data_record/resource.tf | 59 ++-- templates/resources/data_record.md.tmpl | 55 ++++ 9 files changed, 540 insertions(+), 59 deletions(-) create mode 100644 .changes/unreleased/documentation-20241010-194509.yaml create mode 100644 examples/resources/powerplatform_data_record/res_application_user/main.tf create mode 100644 examples/resources/powerplatform_data_record/res_role/main.tf create mode 100644 examples/resources/powerplatform_data_record/res_team/main.tf create mode 100644 templates/resources/data_record.md.tmpl diff --git a/.changes/unreleased/documentation-20241010-194509.yaml b/.changes/unreleased/documentation-20241010-194509.yaml new file mode 100644 index 000000000..1acf7c744 --- /dev/null +++ b/.changes/unreleased/documentation-20241010-194509.yaml @@ -0,0 +1,5 @@ +kind: documentation +body: Improved documentation of `data_record` with examples for app users, business units, teams, and roles +time: 2024-10-10T19:45:09.853535143Z +custom: + Issue: "414" diff --git a/.changie.yaml b/.changie.yaml index b2341d1ec..8b0e57bb6 100644 --- a/.changie.yaml +++ b/.changie.yaml @@ -28,6 +28,9 @@ kinds: - label: 🚨 Security key: security auto: patch + - label: 📚 Documentation + key: documentation + auto: patch newlines: afterChangelogHeader: 1 beforeChangelogVersion: 1 diff --git a/docs/resources/data_record.md b/docs/resources/data_record.md index 1739973f0..ba692b430 100644 --- a/docs/resources/data_record.md +++ b/docs/resources/data_record.md @@ -1,7 +1,5 @@ --- -# generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "powerplatform_data_record Resource - powerplatform" -subcategory: "" description: |- The Power Platform Data Record Resource allows the management of configuration records that are stored in Dataverse as records. This resource is not recommended for managing business data or other data that may be changed by Dataverse users in the context of normal business activities. --- @@ -10,14 +8,261 @@ description: |- The Power Platform Data Record Resource allows the management of configuration records that are stored in Dataverse as records. This resource is not recommended for managing business data or other data that may be changed by Dataverse users in the context of normal business activities. +Data Record is a special type of a resources, that allows creation of any type Dataverese table record. The syntax for working with `data_record` resource is simmilar to raw WebAPI HTTP requests that this record uses: + +- [WebAPI overview - Power Platform | Microsoft Learn](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/overview) + ## Example Usage +The following examples show how to use the `data_record` resource to configure some of the most common Dataverse settings. These are minimal examples just to show the syntax, and do not include all possible configuration options. Use these as a starting point if you need to set additional fields. + +### Business Units + +Example of how to create a [Business Unit](https://learn.microsoft.com/power-platform/admin/create-edit-business-units) + +```terraform +terraform { + required_providers { + powerplatform = { + source = "microsoft/power-platform" + } + } +} + +variable "environment_id" { + type = string +} + +variable "name" { + type = string +} + +variable "costcenter" { + type = string +} + +variable "parent_business_unit_id" { + type = string +} + +resource "powerplatform_data_record" "business_unit" { + environment_id = var.environment_id + table_logical_name = "businessunit" + disable_on_destroy = true + columns = { + name = var.name + costcenter = var.costcenter + parentbusinessunitid = { + table_logical_name = "businessunit" + data_record_id = var.parent_business_unit_id + } + } +} + +output "resource_id" { + value = powerplatform_data_record.business_unit.id +} + +output "resource" { + value = powerplatform_data_record.business_unit +} +``` + +### Application User + +Example of how to create an [Application User](https://learn.microsoft.com/power-platform/admin/manage-application-users) + +```terraform +terraform { + required_providers { + powerplatform = { + source = "microsoft/power-platform" + } + } +} + +variable "environment_id" { + description = "The unique identifier of the environment" + type = string + validation { + condition = length(var.environment_id) > 0 + error_message = "The environment id must not be empty" + } + +} + +variable "application_id" { + description = "EntraId clientid of the application" + type = string + validation { + condition = length(var.application_id) > 0 + error_message = "The application id must not be empty" + } +} + +variable "business_unit_id" { + description = "Unique identifier of the business unit" + type = string + validation { + condition = length(var.business_unit_id) > 0 + error_message = "The business unit id must not be empty" + } +} + +variable "role_ids" { + type = set(string) + description = "The role ids that are granted to this application user" +} + + +resource "powerplatform_data_record" "app_user" { + table_logical_name = "systemuser" + environment_id = var.environment_id + disable_on_destroy = true # Application Users cannot be deleted without being disabled first + columns = { + applicationid = var.application_id + businessunitid = { + table_logical_name = "businessunit" + data_record_id = var.business_unit_id + } + systemuserroles_association = tolist([for rid in var.role_ids : { table_logical_name = "role", data_record_id = tostring(rid) }]) + } +} + +output "application_user_id" { + value = powerplatform_data_record.app_user.id +} +``` + +### Role + +Example of how to create a [Role](https://learn.microsoft.com/power-platform/admin/create-edit-security-role#create-a-security-role) + +```terraform +terraform { + required_providers { + powerplatform = { + source = "microsoft/power-platform" + } + } +} + +variable "environment_id" { + description = "The unique identifier of the environment" + type = string + validation { + condition = length(var.environment_id) > 0 + error_message = "The environment id must not be empty" + } +} + +variable "role_name" { + description = "The name of the role" + type = string + validation { + condition = length(var.role_name) > 0 + error_message = "The role name must not be empty" + } +} + +variable "business_unit_id" { + description = "The unique identifier of the business unit" + type = string + validation { + condition = length(var.business_unit_id) > 0 + error_message = "The business unit id must not be empty" + } +} + +resource "powerplatform_data_record" "role" { + environment_id = var.environment_id + table_logical_name = "role" + + columns = { + name = var.role_name + + businessunitid = { + table_logical_name = "businessunit" + data_record_id = var.business_unit_id + } + } +} + +output "role_id" { + value = powerplatform_data_record.role.id +} +``` + +### Team + +Example of how to create a [Team](https://learn.microsoft.com/power-platform/admin/manage-teams) + +```terraform +terraform { + required_providers { + powerplatform = { + source = "microsoft/power-platform" + } + } +} + +variable "environment_id" { + description = "The unique identifier of the environment" + type = string + validation { + condition = length(var.environment_id) > 0 + error_message = "The environment id must not be empty" + } + +} + +variable "team_name" { + description = "The name of the team" + type = string + validation { + condition = length(var.team_name) > 0 + error_message = "The team name must not be empty" + } +} + +variable "team_description" { + description = "The description of the team" + type = string +} + +variable "role_ids" { + type = set(string) + description = "The role ids that are granted to this team" + +} + +resource "powerplatform_data_record" "team" { + environment_id = var.environment_id + table_logical_name = "team" + columns = { + name = var.team_name + description = var.team_description + + teamroles_association = tolist([for rid in var.role_ids : { table_logical_name = "role", data_record_id = tostring(rid) }]) + } +} + +output "team_id" { + value = powerplatform_data_record.team.id +} +``` + +## End to End Example + ```terraform terraform { required_providers { powerplatform = { source = "microsoft/power-platform" } + azuread = { + source = "hashicorp/azuread" + } } } @@ -25,6 +270,9 @@ provider "powerplatform" { use_cli = true } +provider "azuread" { + use_cli = true +} resource "powerplatform_environment" "data_record_example_env" { display_name = "powerplatform_data_record_example" @@ -37,6 +285,7 @@ resource "powerplatform_environment" "data_record_example_env" { } } +# get the root business unit by querying for the business unit without a parent data "powerplatform_data_records" "root_business_unit" { environment_id = powerplatform_environment.data_record_example_env.id entity_collection = "businessunits" @@ -44,42 +293,46 @@ data "powerplatform_data_records" "root_business_unit" { select = ["name"] } +# Create a new business unit with the root business unit as parent module "business_unit" { source = "./res_business_unit" environment_id = powerplatform_environment.data_record_example_env.id - name = "my business unit" + name = "Sales" costcenter = "123" parent_business_unit_id = one(data.powerplatform_data_records.root_business_unit.rows).businessunitid } -resource "powerplatform_data_record" "role" { - environment_id = powerplatform_environment.data_record_example_env.id - table_logical_name = "role" +# Create a new role +module "custom_role" { + source = "./res_role" + environment_id = powerplatform_environment.data_record_example_env.id + role_name = "my custom role" + business_unit_id = one(data.powerplatform_data_records.root_business_unit.rows).businessunitid +} - columns = { - name = "my custom role" +module "team" { + source = "./res_team" + environment_id = powerplatform_environment.data_record_example_env.id + team_name = "main team" + team_description = "main team description" + role_ids = [module.custom_role.role_id] - businessunitid = { - table_logical_name = "businessunit" - data_record_id = data.powerplatform_data_records.root_business_unit.rows[0].businessunitid - } - } } -resource "powerplatform_data_record" "team" { - environment_id = powerplatform_environment.data_record_example_env.id - table_logical_name = "team" - columns = { - name = "main team" - description = "main team description" +resource "azuread_application_registration" "data_record_app_user" { + display_name = "powerplatform_data_record_example" +} - teamroles_association = [ - { - table_logical_name = "role" - data_record_id = powerplatform_data_record.role.id - } - ] - } +resource "azuread_service_principal" "data_record_app_user" { + client_id = azuread_application_registration.data_record_app_user.client_id +} + +module "application_user" { + source = "./res_application_user" + environment_id = powerplatform_environment.data_record_example_env.id + application_id = azuread_application_registration.data_record_app_user.client_id + business_unit_id = one(data.powerplatform_data_records.root_business_unit.rows).businessunitid + role_ids = [module.custom_role.role_id] } ``` diff --git a/examples/resources/powerplatform_data_record/output.tf b/examples/resources/powerplatform_data_record/output.tf index a146b332f..e69de29bb 100644 --- a/examples/resources/powerplatform_data_record/output.tf +++ b/examples/resources/powerplatform_data_record/output.tf @@ -1,9 +0,0 @@ -output "data_record_role" { - description = "Role Data Record" - value = resource.powerplatform_data_record.role -} - -output "data_record_team" { - description = "Team Data Record" - value = resource.powerplatform_data_record.team -} diff --git a/examples/resources/powerplatform_data_record/res_application_user/main.tf b/examples/resources/powerplatform_data_record/res_application_user/main.tf new file mode 100644 index 000000000..fbbe384cd --- /dev/null +++ b/examples/resources/powerplatform_data_record/res_application_user/main.tf @@ -0,0 +1,59 @@ +terraform { + required_providers { + powerplatform = { + source = "microsoft/power-platform" + } + } +} + +variable "environment_id" { + description = "The unique identifier of the environment" + type = string + validation { + condition = length(var.environment_id) > 0 + error_message = "The environment id must not be empty" + } + +} + +variable "application_id" { + description = "EntraId clientid of the application" + type = string + validation { + condition = length(var.application_id) > 0 + error_message = "The application id must not be empty" + } +} + +variable "business_unit_id" { + description = "Unique identifier of the business unit" + type = string + validation { + condition = length(var.business_unit_id) > 0 + error_message = "The business unit id must not be empty" + } +} + +variable "role_ids" { + type = set(string) + description = "The role ids that are granted to this application user" +} + + +resource "powerplatform_data_record" "app_user" { + table_logical_name = "systemuser" + environment_id = var.environment_id + disable_on_destroy = true # Application Users cannot be deleted without being disabled first + columns = { + applicationid = var.application_id + businessunitid = { + table_logical_name = "businessunit" + data_record_id = var.business_unit_id + } + systemuserroles_association = tolist([for rid in var.role_ids : { table_logical_name = "role", data_record_id = tostring(rid) }]) + } +} + +output "application_user_id" { + value = powerplatform_data_record.app_user.id +} diff --git a/examples/resources/powerplatform_data_record/res_role/main.tf b/examples/resources/powerplatform_data_record/res_role/main.tf new file mode 100644 index 000000000..ea3a961b6 --- /dev/null +++ b/examples/resources/powerplatform_data_record/res_role/main.tf @@ -0,0 +1,52 @@ +terraform { + required_providers { + powerplatform = { + source = "microsoft/power-platform" + } + } +} + +variable "environment_id" { + description = "The unique identifier of the environment" + type = string + validation { + condition = length(var.environment_id) > 0 + error_message = "The environment id must not be empty" + } +} + +variable "role_name" { + description = "The name of the role" + type = string + validation { + condition = length(var.role_name) > 0 + error_message = "The role name must not be empty" + } +} + +variable "business_unit_id" { + description = "The unique identifier of the business unit" + type = string + validation { + condition = length(var.business_unit_id) > 0 + error_message = "The business unit id must not be empty" + } +} + +resource "powerplatform_data_record" "role" { + environment_id = var.environment_id + table_logical_name = "role" + + columns = { + name = var.role_name + + businessunitid = { + table_logical_name = "businessunit" + data_record_id = var.business_unit_id + } + } +} + +output "role_id" { + value = powerplatform_data_record.role.id +} diff --git a/examples/resources/powerplatform_data_record/res_team/main.tf b/examples/resources/powerplatform_data_record/res_team/main.tf new file mode 100644 index 000000000..5f0dcb434 --- /dev/null +++ b/examples/resources/powerplatform_data_record/res_team/main.tf @@ -0,0 +1,52 @@ +terraform { + required_providers { + powerplatform = { + source = "microsoft/power-platform" + } + } +} + +variable "environment_id" { + description = "The unique identifier of the environment" + type = string + validation { + condition = length(var.environment_id) > 0 + error_message = "The environment id must not be empty" + } + +} + +variable "team_name" { + description = "The name of the team" + type = string + validation { + condition = length(var.team_name) > 0 + error_message = "The team name must not be empty" + } +} + +variable "team_description" { + description = "The description of the team" + type = string +} + +variable "role_ids" { + type = set(string) + description = "The role ids that are granted to this team" + +} + +resource "powerplatform_data_record" "team" { + environment_id = var.environment_id + table_logical_name = "team" + columns = { + name = var.team_name + description = var.team_description + + teamroles_association = tolist([for rid in var.role_ids : { table_logical_name = "role", data_record_id = tostring(rid) }]) + } +} + +output "team_id" { + value = powerplatform_data_record.team.id +} diff --git a/examples/resources/powerplatform_data_record/resource.tf b/examples/resources/powerplatform_data_record/resource.tf index 501dd6004..e1a672fbe 100644 --- a/examples/resources/powerplatform_data_record/resource.tf +++ b/examples/resources/powerplatform_data_record/resource.tf @@ -3,6 +3,9 @@ terraform { powerplatform = { source = "microsoft/power-platform" } + azuread = { + source = "hashicorp/azuread" + } } } @@ -10,6 +13,9 @@ provider "powerplatform" { use_cli = true } +provider "azuread" { + use_cli = true +} resource "powerplatform_environment" "data_record_example_env" { display_name = "powerplatform_data_record_example" @@ -22,6 +28,7 @@ resource "powerplatform_environment" "data_record_example_env" { } } +# get the root business unit by querying for the business unit without a parent data "powerplatform_data_records" "root_business_unit" { environment_id = powerplatform_environment.data_record_example_env.id entity_collection = "businessunits" @@ -29,40 +36,44 @@ data "powerplatform_data_records" "root_business_unit" { select = ["name"] } +# Create a new business unit with the root business unit as parent module "business_unit" { source = "./res_business_unit" environment_id = powerplatform_environment.data_record_example_env.id - name = "my business unit" + name = "Sales" costcenter = "123" parent_business_unit_id = one(data.powerplatform_data_records.root_business_unit.rows).businessunitid } -resource "powerplatform_data_record" "role" { - environment_id = powerplatform_environment.data_record_example_env.id - table_logical_name = "role" +# Create a new role +module "custom_role" { + source = "./res_role" + environment_id = powerplatform_environment.data_record_example_env.id + role_name = "my custom role" + business_unit_id = one(data.powerplatform_data_records.root_business_unit.rows).businessunitid +} - columns = { - name = "my custom role" +module "team" { + source = "./res_team" + environment_id = powerplatform_environment.data_record_example_env.id + team_name = "main team" + team_description = "main team description" + role_ids = [module.custom_role.role_id] - businessunitid = { - table_logical_name = "businessunit" - data_record_id = data.powerplatform_data_records.root_business_unit.rows[0].businessunitid - } - } } -resource "powerplatform_data_record" "team" { - environment_id = powerplatform_environment.data_record_example_env.id - table_logical_name = "team" - columns = { - name = "main team" - description = "main team description" +resource "azuread_application_registration" "data_record_app_user" { + display_name = "powerplatform_data_record_example" +} - teamroles_association = [ - { - table_logical_name = "role" - data_record_id = powerplatform_data_record.role.id - } - ] - } +resource "azuread_service_principal" "data_record_app_user" { + client_id = azuread_application_registration.data_record_app_user.client_id +} + +module "application_user" { + source = "./res_application_user" + environment_id = powerplatform_environment.data_record_example_env.id + application_id = azuread_application_registration.data_record_app_user.client_id + business_unit_id = one(data.powerplatform_data_records.root_business_unit.rows).businessunitid + role_ids = [module.custom_role.role_id] } diff --git a/templates/resources/data_record.md.tmpl b/templates/resources/data_record.md.tmpl new file mode 100644 index 000000000..299fb5ffd --- /dev/null +++ b/templates/resources/data_record.md.tmpl @@ -0,0 +1,55 @@ +--- +page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}" +description: |- + {{ .Description }} +--- + +# {{.Name}} ({{.Type}}) + +{{ .Description | trimspace }} + +Data Record is a special type of a resources, that allows creation of any type Dataverese table record. The syntax for working with `data_record` resource is simmilar to raw WebAPI HTTP requests that this record uses: + +- [WebAPI overview - Power Platform | Microsoft Learn](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/overview) + +## Example Usage + +The following examples show how to use the `data_record` resource to configure some of the most common Dataverse settings. These are minimal examples just to show the syntax, and do not include all possible configuration options. Use these as a starting point if you need to set additional fields. + +### Business Units + +Example of how to create a [Business Unit](https://learn.microsoft.com/power-platform/admin/create-edit-business-units) + +{{tffile "examples/resources/powerplatform_data_record/res_business_unit/main.tf" }} + +### Application User + +Example of how to create an [Application User](https://learn.microsoft.com/power-platform/admin/manage-application-users) + +{{tffile "examples/resources/powerplatform_data_record/res_application_user/main.tf" }} + +### Role + +Example of how to create a [Role](https://learn.microsoft.com/power-platform/admin/create-edit-security-role#create-a-security-role) + +{{tffile "examples/resources/powerplatform_data_record/res_role/main.tf" }} + +### Team + +Example of how to create a [Team](https://learn.microsoft.com/power-platform/admin/manage-teams) + +{{tffile "examples/resources/powerplatform_data_record/res_team/main.tf" }} + +## End to End Example + +{{tffile "examples/resources/powerplatform_data_record/resource.tf" }} + +{{ .SchemaMarkdown | trimspace }} +{{- if .HasImport }} + +## Import + +Import is supported using the following syntax: + +{{codefile "shell" .ImportFile }} +{{- end }}