Add HCL generation advice header

docs/exporting-configuration/README.md

@@ -0,0 +1,9 @@
+# Ping CLI - Exporting Platform Configuration
+
+## Resolving Terraform Plan Errors
+
+The following documents describe the actions that must be taken, per provider, to resolve `terraform plan` errors following configuration generation.
+
+- [PingOne Terraform Provider](./pingone-plan-errors.md)
+
+If you encounter an error that is not documented, please [raise a new issue](https://github.com/pingidentity/pingcli/issues/new?title=Undocumented%20Config%20Generation%20Error).

docs/exporting-configuration/pingone-plan-errors.md

@@ -0,0 +1,83 @@
+# Ping CLI - Exporting Platform Configuration - PingOne Plan Errors
+
+The following sections describe the actions that must be taken, per resource, to resolve `terraform plan` errors following configuration generation.
+
+If you encounter an error that is not documented, please [raise a new issue](https://github.com/pingidentity/pingcli/issues/new?title=Undocumented%20PingOne%20Config%20Generation%20Error).
+
+## Resource: pingone_application
+
+### Attribute saml_options.type value must be one of: ["WEB_APP" "CUSTOM_APP"], got: "TEMPLATE_APP"
+
+**Cause**: Template applications are not supported in the PingOne provider version used to run `terraform plan`.
+
+**Resolution**: Upgrade the PingOne Terraform provider version.  Further details can be found at https://github.com/pingidentity/terraform-provider-pingone/issues/841
+
+**Documentation**:
+- [Terraform Registry](https://registry.terraform.io/providers/pingidentity/pingone/latest/docs/resources/application#nestedatt--saml_options)
+
+## Resource: pingone_branding_theme
+
+### 2 attributes specified when one (and only one) of [background_color.<.background_color,background_color.<.use_default_background,background_color.<.background_image] is required
+
+**Cause**: Due to a [Terraform configuration generation limitation](https://developer.hashicorp.com/terraform/language/import/generating-configuration#conflicting-resource-arguments), conflicting parameters are included in the generated HCL.
+
+**Resolution**: Manual modification is required to ensure only one of `background_color`, `use_default_background` or `background_image` is defined.
+
+**Documentation**:
+- [Terraform Registry](https://registry.terraform.io/providers/pingidentity/pingone/latest/docs/resources/branding_theme#schema)
+
+## Resource: pingone_certificate
+
+### one of `pem_file,pkcs7_file_base64` must be specified
+
+**Cause**: Certificates are not exported from PingOne to maintain tenant security.
+
+**Resolution**: Manual modification is required to set either `pem_file` or `pkcs7_file_base64` in the generated HCL.
+
+**Documentation**:
+- [Terraform Registry](https://registry.terraform.io/providers/pingidentity/pingone/latest/docs/resources/certificate#schema)
+
+## Resource: pingone_forms_recaptcha_v2
+
+### Must set a configuration value for the secret_key attribute as the provider has marked it as required
+
+**Cause**: The reCaptcha v2 secret key is not exported from PingOne to maintain tenant security.
+
+**Resolution**: Manual modification is required to set `secret_key` in the generated HCL.
+
+**Documentation**:
+- [Terraform Registry](https://registry.terraform.io/providers/pingidentity/pingone/latest/docs/resources/forms_recaptcha_v2#schema)
+
+## Resource: pingone_mfa_application_push_credential
+
+### No attribute specified when one (and only one) of [apns.<.fcm,apns.<.apns,apns.<.hms] is required
+
+**Cause**: Push credential values are not exported from PingOne to maintain tenant security.
+
+**Resolution**: Manual modification is required to set one of `apns`, `fcm`, or `hms` in the generated HCL.
+
+**Documentation**:
+- [Terraform Registry](https://registry.terraform.io/providers/pingidentity/pingone/latest/docs/resources/mfa_application_push_credential#schema)
+
+## Resource: pingone_notification_settings_email
+
+### Must set a configuration value for the password attribute as the provider has marked it as required.
+
+**Cause**: Passwords for email servers are not exported from PingOne to maintain tenant security.
+
+**Resolution**: Manual modification is required to set the `password` field in the generated HCL.
+
+**Documentation**:
+- [Terraform Registry](https://registry.terraform.io/providers/pingidentity/pingone/latest/docs/resources/notification_settings_email#schema)
+
+## Resource: pingone_phone_delivery_settings
+
+### The argument provider_custom.authentication.password is required because provider_custom.authentication.method is configured as: "BASIC"
+
+**Cause**: Password fields are not exported from PingOne to maintain tenant security.
+
+**Resolution**: Manual modification is required to set the `provider_custom.authentication.password` value in the generated HCL.
+
+**Documentation**:
+- [Terraform Registry](https://registry.terraform.io/providers/pingidentity/pingone/latest/docs/resources/phone_delivery_settings#password)
+

internal/connector/common/common_utils.go

@@ -5,6 +5,7 @@ import (
 	"os"
 	"path/filepath"
 	"text/template"
+	"time"
 
 	"github.com/pingidentity/pingcli/internal/connector"
 	"github.com/pingidentity/pingcli/internal/customtypes"
@@ -51,6 +52,11 @@ func WriteFiles(exportableResources []connector.ExportableResource, format, outp
 		}
 		defer outputFile.Close()
 
+		err = writeHeader(format, outputFilePath, outputFile)
+		if err != nil {
+			return err
+		}
+
 		for _, importBlock := range *importBlocks {
 			// Sanitize import block "to". Make lowercase, remove special chars, convert space to underscore
 			importBlock.Sanitize()
@@ -59,7 +65,7 @@ func WriteFiles(exportableResources []connector.ExportableResource, format, outp
 			case customtypes.ENUM_EXPORT_FORMAT_HCL:
 				err := hclImportBlockTemplate.Execute(outputFile, importBlock)
 				if err != nil {
-					return fmt.Errorf("failed to write import block template to file %q. err: %s", outputFilePath, err.Error())
+					return fmt.Errorf("failed to write import template to file %q. err: %s", outputFilePath, err.Error())
 				}
 			default:
 				return fmt.Errorf("unrecognized export format %q. Must be one of: %s", format, customtypes.ExportFormatValidValues())
@@ -68,3 +74,29 @@ func WriteFiles(exportableResources []connector.ExportableResource, format, outp
 	}
 	return nil
 }
+
+func writeHeader(format, outputFilePath string, outputFile *os.File) error {
+	// Parse the HCL header
+	hclImportHeaderTemplate, err := template.New("HCLImportHeader").Parse(connector.HCLImportHeaderTemplate)
+	if err != nil {
+		return fmt.Errorf("failed to parse HCL import header template. err: %s", err.Error())
+	}
+
+	header := struct {
+		DateTime string
+	}{
+		DateTime: time.Now().Format(time.RFC1123),
+	}
+
+	switch format {
+	case customtypes.ENUM_EXPORT_FORMAT_HCL:
+		err := hclImportHeaderTemplate.Execute(outputFile, header)
+		if err != nil {
+			return fmt.Errorf("failed to write import template to file %q. err: %s", outputFilePath, err.Error())
+		}
+	default:
+		return fmt.Errorf("unrecognized export format %q. Must be one of: %s", format, customtypes.ExportFormatValidValues())
+	}
+
+	return nil
+}

internal/connector/exportable.go

@@ -9,6 +9,9 @@ import (
 //go:embed templates/hcl_import_block.template
 var HCLImportBlockTemplate string
 
+//go:embed templates/hcl_import_header.template
+var HCLImportHeaderTemplate string
+
 // A connector that allows exporting configuration
 type Exportable interface {
 	Export(format, outputDir string, overwriteExport bool) error

internal/connector/templates/hcl_import_header.template

@@ -0,0 +1,23 @@
+#######################################################################################################################
+#
+# Generated by Ping CLI: {{.DateTime}}
+# https://github.com/pingidentity/pingcli
+#
+# Using the Terraform import blocks generated in this file, Terraform HCL can be generated and resource
+#  configuration can be imported to Terraform state using Terraform's out-of-the-box import features.
+#
+# Use of the Terraform import blocks requires Terraform `v1.5.0` and later.
+#
+# For more information on the Terraform import block feature, visit
+#  https://developer.hashicorp.com/terraform/language/import
+#
+# To generate Terraform configuration, run `terraform plan` with the `-generate-config-out` flag.  For example:
+#  terraform plan -generate-config-out=generated_resources.tf
+#
+# There are limitations in the generation process that may result in errors being shown on `terraform plan`.
+#
+# For more information on the manual steps required to resolve the errors, visit
+#  https://github.com/pingidentity/pingcli/blob/main/docs/exporting-configuration/README.md
+# 
+#######################################################################################################################
+