Add documentation examples for templated steps

Author: denys-octopus

docs/resources/process_templated_child_step.md

@@ -46,28 +46,28 @@ resource "octopusdeploy_step_template" "my_script" {
 
   parameters = [
     {
-      name      = "Parameter.One"
+      name = "Parameter.One"
       id = "10001000-0000-0000-0000-100010001001"
-      label     = "First Parameter"
+      label = "First Parameter"
       default_value = "default-value-one"
       display_settings = {
         "Octopus.ControlType" : "SingleLineText"
       }
     },
     {
-      name      = "Parameter.Two"
+      name = "Parameter.Two"
       id = "10001000-0000-0000-0000-100010001002"
-      label     = "Second Parameter"
+      label = "Second Parameter"
       display_settings = {
-        "Octopus.ControlType" : "SingleLineText"
+        "Octopus.ControlType": "SingleLineText"
       }
     },
   ]
     
   properties = {
-    "Octopus.Action.Script.ScriptBody" : "echo '1.#{Parameter.One} ... 2.#{Parameter.Two} ...'"
-    "Octopus.Action.Script.ScriptSource" : "Inline"
-    "Octopus.Action.Script.Syntax" : "Bash"
+    "Octopus.Action.Script.ScriptBody": "echo '1.#{Parameter.One} ... 2.#{Parameter.Two} ...'"
+    "Octopus.Action.Script.ScriptSource": "Inline"
+    "Octopus.Action.Script.Syntax": "Bash"
   }
 }
 
@@ -86,11 +86,29 @@ resource "octopusdeploy_process" "example" {
   project_id  = octopusdeploy_project.example.id
 }
 
+resource "octopusdeploy_process_step" "parent" {
+  process_id  = octopusdeploy_process.app.id
+  name = "Parent Step"
+  properties = {
+    "Octopus.Action.MaxParallelism" = "2"
+    "Octopus.Action.TargetRoles" = "azure-one"
+  }
+  type = "Octopus.Script"
+  execution_properties = {
+    "Octopus.Action.RunOnServer" = "True"
+    "Octopus.Action.Script.ScriptSource" = "Inline"
+    "Octopus.Action.Script.Syntax"       = "PowerShell"
+    "Octopus.Action.Script.ScriptBody" = <<-EOT
+      Write-Host "Parent Step:  #{My.Variable}"
+    EOT
+  }
+}
 
-# Run templated script step
-resource "octopusdeploy_templated_process_step" "script" {
+# Templated script child step
+resource "octopusdeploy_process_templated_child_step" "script" {
   process_id  = octopusdeploy_process.example.id
-  name = "Step 3"
+  parent_id = octopusdeploy_process_step.parent.id
+  name = "Templated Child Step"
   template_id = octopusdeploy_step_template.my_script.id
   template_version = octopusdeploy_step_template.my_script.version
 
@@ -190,5 +208,5 @@ Read-Only:
 Import is supported using the following syntax:
 
 ```shell
-terraform import [options] octopusdeploy_process_templated_step.<name> "<process-id>:<step-id>"
+terraform import [options] octopusdeploy_process_templated_child_step.<name> "<process-id>:<parent-step-id>:<child-step-id>"
 ```

docs/resources/process_templated_step.md

@@ -10,14 +10,11 @@ description: |-
 This resource manages a single step of a Runbook or Deployment Process which based on existing custom step template
 
 ### Remarks
-A Step is the building block of a Deployment or Runbook Process. 
+A Templated Step is the step of a Deployment or Runbook Process which based on existing custom step template
 
-When there are multiple Steps in a Process, we strongly recommend adding a `octopusdeploy_process_step_order` resource to pin the step order. If you later need to change the order of steps in your process, or insert a new step within an existing process, you'll need the Step Order defined first. Without an explicit Step Order, Steps will be added to the process in the order they're applied by Terraform - this is usually the order they appear in your HCL, but is not guaranteed to be deterministic. 
-
-This resource also contains a concept that doesn't exist in the Octopus Deploy domain model: `properties` vs `execution_properties`:
-
-* `properties` are the inputs to control behaviour of the step within the process as whole
-* `execution_properties` are the controls for how and what will be executed when step runs
+This resource expose only attributes which can be controlled by the consumer of a template. To avoid 'state drift' templated step divide template parameters into two attributes 'parameters' and 'unmanaged_parameters':
+* `parameters` are template parameters configured by the practitioner
+* `unmanaged_parameters` is readonly collection of template parameters not configured by the practitioner (usually parameters with default value)
 
 ## Example Usage
 
@@ -82,26 +79,20 @@ resource "octopusdeploy_project" "example" {
   name = "Example"
 }
 
-resource "octopusdeploy_channel" "example" {
-  name       = "Example Channel (OK to Delete)"
-  project_id = octopusdeploy_project.example.id
-}
-
 resource "octopusdeploy_process" "example" {
   project_id  = octopusdeploy_project.example.id
 }
 
-
-# Run templated script step
+# Templated script step
 resource "octopusdeploy_templated_process_step" "script" {
   process_id  = octopusdeploy_process.example.id
-  name = "Step 3"
+  name = "Templated Step"
   template_id = octopusdeploy_step_template.my_script.id
   template_version = octopusdeploy_step_template.my_script.version
 
   # Parameter's default value is used when not provided in configuration
   parameters = {
-    "Parameter.Two" = "my-second-value"
+    "Parameter.Two" = "my-example-value"
   }
 
   execution_properties = {
@@ -197,5 +188,5 @@ Read-Only:
 Import is supported using the following syntax:
 
 ```shell
-terraform import [options] octopusdeploy_process_templated_child_step.<name> "<process-id>:<parent-step-id>:<child-step-id>"
+terraform import [options] octopusdeploy_process_templated_step.<name> "<process-id>:<step-id>"
 ```

examples/resources/octopusdeploy_process_templated_child_step/import.sh

@@ -1 +1 @@
-terraform import [options] octopusdeploy_process_templated_step.<name> "<process-id>:<step-id>"
+terraform import [options] octopusdeploy_process_templated_child_step.<name> "<process-id>:<parent-step-id>:<child-step-id>"

examples/resources/octopusdeploy_process_templated_child_step/resource.tf

@@ -27,28 +27,28 @@ resource "octopusdeploy_step_template" "my_script" {
 
   parameters = [
     {
-      name      = "Parameter.One"
+      name = "Parameter.One"
       id = "10001000-0000-0000-0000-100010001001"
-      label     = "First Parameter"
+      label = "First Parameter"
       default_value = "default-value-one"
       display_settings = {
         "Octopus.ControlType" : "SingleLineText"
       }
     },
     {
-      name      = "Parameter.Two"
+      name = "Parameter.Two"
       id = "10001000-0000-0000-0000-100010001002"
-      label     = "Second Parameter"
+      label = "Second Parameter"
       display_settings = {
-        "Octopus.ControlType" : "SingleLineText"
+        "Octopus.ControlType": "SingleLineText"
       }
     },
   ]
 
   properties = {
-    "Octopus.Action.Script.ScriptBody" : "echo '1.#{Parameter.One} ... 2.#{Parameter.Two} ...'"
-    "Octopus.Action.Script.ScriptSource" : "Inline"
-    "Octopus.Action.Script.Syntax" : "Bash"
+    "Octopus.Action.Script.ScriptBody": "echo '1.#{Parameter.One} ... 2.#{Parameter.Two} ...'"
+    "Octopus.Action.Script.ScriptSource": "Inline"
+    "Octopus.Action.Script.Syntax": "Bash"
   }
 }
 
@@ -67,11 +67,29 @@ resource "octopusdeploy_process" "example" {
   project_id  = octopusdeploy_project.example.id
 }
 
+resource "octopusdeploy_process_step" "parent" {
+  process_id  = octopusdeploy_process.app.id
+  name = "Parent Step"
+  properties = {
+    "Octopus.Action.MaxParallelism" = "2"
+    "Octopus.Action.TargetRoles" = "azure-one"
+  }
+  type = "Octopus.Script"
+  execution_properties = {
+    "Octopus.Action.RunOnServer" = "True"
+    "Octopus.Action.Script.ScriptSource" = "Inline"
+    "Octopus.Action.Script.Syntax"       = "PowerShell"
+    "Octopus.Action.Script.ScriptBody" = <<-EOT
+      Write-Host "Parent Step:  #{My.Variable}"
+    EOT
+  }
+}
 
-# Run templated script step
-resource "octopusdeploy_templated_process_step" "script" {
+# Templated script child step
+resource "octopusdeploy_process_templated_child_step" "script" {
   process_id  = octopusdeploy_process.example.id
-  name = "Step 3"
+  parent_id = octopusdeploy_process_step.parent.id
+  name = "Templated Child Step"
   template_id = octopusdeploy_step_template.my_script.id
   template_version = octopusdeploy_step_template.my_script.version
 

examples/resources/octopusdeploy_process_templated_step/import.sh

@@ -1 +1 @@
-terraform import [options] octopusdeploy_process_templated_child_step.<name> "<process-id>:<parent-step-id>:<child-step-id>"
+terraform import [options] octopusdeploy_process_templated_step.<name> "<process-id>:<step-id>"

examples/resources/octopusdeploy_process_templated_step/resource.tf

@@ -58,26 +58,20 @@ resource "octopusdeploy_project" "example" {
   name = "Example"
 }
 
-resource "octopusdeploy_channel" "example" {
-  name       = "Example Channel (OK to Delete)"
-  project_id = octopusdeploy_project.example.id
-}
-
 resource "octopusdeploy_process" "example" {
   project_id  = octopusdeploy_project.example.id
 }
 
-
-# Run templated script step
+# Templated script step
 resource "octopusdeploy_templated_process_step" "script" {
   process_id  = octopusdeploy_process.example.id
-  name = "Step 3"
+  name = "Templated Step"
   template_id = octopusdeploy_step_template.my_script.id
   template_version = octopusdeploy_step_template.my_script.version
 
   # Parameter's default value is used when not provided in configuration
   parameters = {
-    "Parameter.Two" = "my-second-value"
+    "Parameter.Two" = "my-example-value"
   }
 
   execution_properties = {

octopusdeploy_framework/schemas/process_templated_child_step.go

@@ -136,7 +136,7 @@ func (p ProcessTemplatedChildStepSchema) GetResourceSchema() resourceSchema.Sche
 				DefaultEmpty().
 				Build(),
 			"unmanaged_parameters": util.ResourceMap(types.StringType).
-				Description("Template parameters not configured by the practitioner.").
+				Description("Template parameters not configured by the practitioner (usually parameters with default value).").
 				Computed().
 				Build(),
 			"template_properties": util.ResourceMap(types.StringType).

octopusdeploy_framework/schemas/process_templated_step.go

@@ -154,7 +154,7 @@ func (p ProcessTemplatedStepSchema) GetResourceSchema() resourceSchema.Schema {
 				DefaultEmpty().
 				Build(),
 			"unmanaged_parameters": util.ResourceMap(types.StringType).
-				Description("Template parameters not configured by the practitioner.").
+				Description("Template parameters not configured by the practitioner (usually parameters with default value).").
 				Computed().
 				Build(),
 			"template_properties": util.ResourceMap(types.StringType).

templates/resources/process_templated_step.md.tmpl

@@ -10,14 +10,11 @@ description: |-
 {{ .Description | trimspace }}
 
 ### Remarks
-A Step is the building block of a Deployment or Runbook Process. 
+A Templated Step is the step of a Deployment or Runbook Process which based on existing custom step template
 
-When there are multiple Steps in a Process, we strongly recommend adding a `octopusdeploy_process_step_order` resource to pin the step order. If you later need to change the order of steps in your process, or insert a new step within an existing process, you'll need the Step Order defined first. Without an explicit Step Order, Steps will be added to the process in the order they're applied by Terraform - this is usually the order they appear in your HCL, but is not guaranteed to be deterministic. 
-
-This resource also contains a concept that doesn't exist in the Octopus Deploy domain model: `properties` vs `execution_properties`:
-
-* `properties` are the inputs to control behaviour of the step within the process as whole
-* `execution_properties` are the controls for how and what will be executed when step runs
+This resource expose only attributes which can be controlled by the consumer of a template. To avoid 'state drift' templated step divide template parameters into two attributes 'parameters' and 'unmanaged_parameters':
+* `parameters` are template parameters configured by the practitioner
+* `unmanaged_parameters` is readonly collection of template parameters not configured by the practitioner (usually parameters with default value)
 
 ## Example Usage