StartWorkflow system task documentation

Netflix · Mar 24, 2022 · 0844b86 · 0844b86
1 parent 7098e95
commit 0844b86
Show file tree

Hide file tree

Showing 6 changed files with 65 additions and 36 deletions.
diff --git a/docs/docs/configuration/workflowdef.md b/docs/docs/configuration/workflowdef.md
@@ -5,7 +5,7 @@
 At a high level, a workflow is the Conductor primitive that encompasses the definition and flow of your business logic.
 A workflow is a collection (graph) of tasks and sub-workflows. A workflow definition specifies the order of execution of
 these [Tasks](taskdef.md). It also specifies how data/state is passed from one task to the other (using the
-input/output parameters). These are then combined together to give you the final result. This orchestration of Tasks can
+input/output parameters). These are then combined to give you the final result. This orchestration of Tasks can
 happen in a hybrid ecosystem that includes microservices, serverless functions, and monolithic applications. They can
 also span across any public cloud and on-premise data center footprints. In addition, the orchestration of tasks can be
 across any programming language since Conductor is also language agnostic.

diff --git a/docs/docs/gettingstarted/startworkflow.md b/docs/docs/gettingstarted/startworkflow.md
@@ -2,16 +2,16 @@
 
 When starting a Workflow execution with a registered definition, Workflow accepts following parameters:
 
-|field|description|Notes|
-|:-----|:---|:---|
-| name | Name of the Workflow. MUST be registered with Conductor before starting workflow | |
-| version | Workflow version | defaults to latest available version |
-| input | JSON object with key value params, that can be used by downstream tasks | See [Wiring Inputs and Outputs](../../configuration/workflowdef/#wiring-inputs-and-outputs) for details |
-| correlationId | Unique Id that correlates multiple Workflow executions | optional |
-| taskToDomain | See [Task Domains](../../configuration/taskdomains/#task-domains) for more information. | optional |
-| workflowDef | Provide adhoc Workflow definition to run, without registering. See Dynamic Workflows below. | optional |
-| externalInputPayloadStoragePath | This is taken care of by Java client. See [External Payload Storage](../../externalpayloadstorage/) for more info. | optional |
-| priority | Priority level for the tasks within this workflow execution. Possible values are between 0 - 99. | optional |
+|field| description                                                                                                                                       |Notes|
+|:-----|:--------------------------------------------------------------------------------------------------------------------------------------------------|:---|
+| name | Name of the Workflow. MUST be registered with Conductor before starting workflow                                                                  | |
+| version | Workflow version                                                                                                                                  | defaults to latest available version |
+| input | JSON object with key value params, that can be used by downstream tasks                                                                           | See [Wiring Inputs and Outputs](../../configuration/workflowdef/#wiring-inputs-and-outputs) for details |
+| correlationId | Unique Id that correlates multiple Workflow executions                                                                                            | optional |
+| taskToDomain | See [Task Domains](../../configuration/taskdomains/#task-domains) for more information.                                                           | optional |
+| workflowDef | An adhoc [Workflow Definition](../../configuration/workflowdef.md) to run, without registering. See [Dynamic Workflows](#dynamic-workflows).      | optional |
+| externalInputPayloadStoragePath | This is taken care of by Java client. See [External Payload Storage](../../externalpayloadstorage/) for more info.                                | optional |
+| priority | Priority level for the tasks within this workflow execution. Possible values are between 0 - 99.                                                  | optional |
 
 **Example:**
 

diff --git a/docs/docs/reference-docs/start-workflow-task.md b/docs/docs/reference-docs/start-workflow-task.md
@@ -0,0 +1,32 @@
+---
+sidebar_position: 1
+---
+# Start Workflow
+```json
+"type" : "START_WORKFLOW"
+```
+### Introduction
+
+Start Workflow starts another workflow.
+
+### Use Cases
+
+When another workflow needs to be started from a workflow, `START_WORKFLOW` can be used.
+
+### Configuration
+
+Start Workflow task is defined directly inside the workflow with type `START_WORKFLOW`.
+
+#### Input
+
+**Parameters:**
+
+| name          |type| description                                                                                                            |
+|---------------|---|------------------------------------------------------------------------------------------------------------------------|
+| startWorkflow | Map[String, Any] | The value of this parameter is [Start Workflow Request](../../gettingstarted/startworkflow.md#start-workflow-request). |
+
+#### Output
+
+| name       |type| description                    |
+|------------|---|--------------------------------|
+| workflowId | String | The id of the started workflow |
diff --git a/docs/docs/reference-docs/sub-workflow-task.md b/docs/docs/reference-docs/sub-workflow-task.md
@@ -6,7 +6,7 @@ sidebar_position: 1
 "type" : "SUB_WORKFLOW"
 ```
 ### Introduction
-Sub Workflow task allows for nesting a workflow within another workflow.
+Sub Workflow task allows for nesting a workflow within another workflow. Nested workflows contain a reference to their parent.
 
 ### Use Cases
 
@@ -15,9 +15,9 @@ case, Sub Workflow Task would be used.
 
 ### Configuration
 
-Sub Workflow task is defined directly inside the workflow with `"SUB_WORKFLOW"`.
+Sub Workflow task is defined directly inside the workflow with type `SUB_WORKFLOW`.
 
-#### Inputs
+#### Input
 
 **Parameters:**
 
@@ -27,12 +27,12 @@ Sub Workflow task is defined directly inside the workflow with `"SUB_WORKFLOW"`.
 
 **subWorkflowParam**
 
-|name|type|description|
-|---|---|---|
-| name | String | Name of the workflow to execute |
-| version | Integer | Version of the workflow to execute |
-| taskToDomain | Map[String, String] | Allows scheduling the sub workflow's tasks per given mappings. See [Task Domains](conductor/configuration/taskdomains/) for instructions to configure taskDomains. |
-| workflowDefinition | [WorkflowDefinition](conductor/configuration/workflowdef/) | Allows starting a subworkflow with a dynamic workflow definition. |
+|name| type                                                     |description|
+|---|----------------------------------------------------------|---|
+| name | String                                                   | Name of the workflow to execute |
+| version | Integer                                                  | Version of the workflow to execute |
+| taskToDomain | Map[String, String]                                      | Allows scheduling the sub workflow's tasks per given mappings. See [Task Domains](conductor/configuration/taskdomains/) for instructions to configure taskDomains. |
+| workflowDefinition | [WorkflowDefinition](../../configuration/workflowdef.md) | Allows starting a subworkflow with a dynamic workflow definition. |
 
 #### Output
 
@@ -44,11 +44,11 @@ Sub Workflow task is defined directly inside the workflow with `"SUB_WORKFLOW"`.
 ### Examples
 
 
-Imagine we have a workflow that has a fork in it.. In the example below, we inputting one image, but using a fork to create 2 images simultaneously:
+Imagine we have a workflow that has a fork in it. In the example below, we input one image, but using a fork to create 2 images simultaneously:
 
 ![](/img/workflow_fork.png)
 
-The left fork will create a JPG, and the right fork a WEBP image. Maintaining this workflow might be difficult, as changes made to one side of the fork do not automatically propagate the otehr.  Rather than using 2 tasks, we can define a ```image_convert_resize``` workflow that we can call for both forks as a subworkflow:
+The left fork will create a JPG, and the right fork a WEBP image. Maintaining this workflow might be difficult, as changes made to one side of the fork do not automatically propagate the other.  Rather than using 2 tasks, we can define a ```image_convert_resize``` workflow that we can call for both forks as a sub-workflow:
 
 ```json
 
@@ -145,7 +145,7 @@ Now our diagram will appear as:
 ![workflow with 2 subworkflows](../img/subworkflow_diagram.png)
 
 
-The inputs to both sides of the workflow are identical before and after - but we've abstraced the tasks into the subworkflow.  nay change to the subworkflow will automatically occur in bth sides of the fork.
+The inputs to both sides of the workflow are identical before and after - but we've abstracted the tasks into the sub-workflow. Any change to the sub-workflow will automatically occur in bth sides of the fork.
 
 Looking at the subworkflow (the WEBP version):
 
@@ -172,4 +172,4 @@ Looking at the subworkflow (the WEBP version):
 ```
 
 The ```subWorkflowParam``` tells conductor which workflow to call. The task is marked as completed upon the completion of the spawned workflow. 
-If the sub-workflow is terminated or fails the task is marked as failure and retried if configured. 
+If the sub-workflow is terminated or fails the task is marked as failure and retried if configured. 
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -29,8 +29,9 @@ nav:
         -  Fork: reference-docs/fork-task.md
         -  Join:    reference-docs/join-task.md
         -  Set Variable:  reference-docs/set-variable-task.md
+        -  Start Workflow: reference-docs/start-workflow-task.md
         -  Sub Workflow: reference-docs/sub-workflow-task.md
-        -  Switch: reference-docs/switch-task.md 
+        -  Switch: reference-docs/switch-task.md
         -  Terminate: reference-docs/terminate-task.md
         -  Wait: reference-docs/wait-task.md
     - System Tasks:
@@ -62,7 +63,7 @@ nav:
             - Task Inputs: how-tos/Tasks/task-inputs.md
             - Task Timeouts: how-tos/Tasks/task-timeouts.md
             - Updating Task Definitions: how-tos/Tasks/updating-tasks.md
-        - Workers: 
+        - Workers:
             -Build a Go Task Worker: how-tos/Workers/build-a-golang-task-worker.md
             -Build a Java Task Worker: how-tos/Workers/build-a-java-task-worker.md
             -Build a Python Task Worker: how-tos/Workers/build-a-python-task-worker.md

diff --git a/test-harness/src/test/groovy/com/netflix/conductor/test/integration/StartWorkflowSpec.groovy b/test-harness/src/test/groovy/com/netflix/conductor/test/integration/StartWorkflowSpec.groovy
@@ -12,17 +12,17 @@
  */
 package com.netflix.conductor.test.integration
 
+import org.springframework.beans.factory.annotation.Autowired
+
 import com.netflix.conductor.common.metadata.tasks.Task
 import com.netflix.conductor.common.run.Workflow
 import com.netflix.conductor.core.execution.tasks.StartWorkflow
 import com.netflix.conductor.dao.QueueDAO
 import com.netflix.conductor.test.base.AbstractSpecification
-import org.springframework.beans.factory.annotation.Autowired
+
 import spock.lang.Shared
 import spock.lang.Unroll
 
-import static com.netflix.conductor.core.execution.tasks.StartWorkflow.START_WORKFLOW_PARAMETER
-
 class StartWorkflowSpec extends AbstractSpecification {
 
     @Autowired
@@ -135,20 +135,16 @@ class StartWorkflowSpec extends AbstractSpecification {
 
         def startWorkflow = ['name': 'dynamic_wf', 'workflowDef': workflowDef]
 
-        def input = [:]
-        input[START_WORKFLOW_PARAMETER] = startWorkflow
-
-        new TestCase(name: 'workflow definition', workflowInput: input)
+        new TestCase(name: 'workflow definition', workflowInput: ['startWorkflow': startWorkflow])
     }
 
     /**
      * Builds a TestCase for a StartWorkflowRequest with a workflow name.
      */
     static workflowName() {
         def startWorkflow = ['name': 'integration_test_wf', 'input': ['param1': 'value1', 'param2': 'value2']]
-        def input = [:]
-        input[START_WORKFLOW_PARAMETER] = startWorkflow
-        new TestCase(name: 'name and version', workflowInput: input)
+
+        new TestCase(name: 'name and version', workflowInput: ['startWorkflow': startWorkflow])
     }
 
     /**