feat: Add importProperties parameter for selective property import and improve state tracking

[RudyBricks]

Overview

This PR enhances the import functionality for msgraph_resource to support importing existing Microsoft Graph resources without triggering unintended modifications. It introduces the importProperties query parameter and improves state management for more accurate drift detection.

Changes

1. Import with Selective Properties (importProperties)

• Feature: Added support for importProperties query parameter in import operations
• Purpose: Allows users to specify which properties to track when importing existing resources
• Syntax: /groups/{id}?importProperties=displayName,mailEnabled,mailNickname,securityEnabled
• Behavior:
  • Seeds specified properties as null in Terraform state during import
  • Subsequent Read operation populates them with actual values from Microsoft Graph
  • Enables managing only selected properties while ignoring others
  • Supports nested properties using dot notation (e.g., web.redirectUris)

2. Enhanced State Management

• Remote State Tracking: Always save the remote resource state into private state during Read operations
• Improved PATCH Calculation: Calculate PATCH body by comparing against the remote state stored in private state instead of the Terraform state
• Benefits:
  • More accurate drift detection
  • Prevents unnecessary updates when properties haven't actually changed
  • Better handling of properties that may be modified outside Terraform

3. Comprehensive Documentation

• Updated docs/resources/resource.md with detailed import examples
• Updated docs/resources/groups.md with group-specific import patterns
• Created new comprehensive guide: docs/guides/importing_resources.md
• Added example workflow in examples/imports/groups/
• Documented best practices, common patterns, and troubleshooting

Use Case

This is particularly valuable when importing existing Microsoft Graph resources into Terraform management:

Before: Importing a resource would result in an empty body, causing Terraform to want to remove all properties on the next plan.

After: Users can selectively import properties they want to manage:

terraform import msgraph_resource.group "/groups/{id}?importProperties=displayName,mailEnabled,mailNickname,securityEnabled"

[RudyBricks]

@microsoft-github-policy-service agree