Decision Branching (#486)

Author: danielgerlag

ReleaseNotes/3.1.0.md

@@ -0,0 +1,84 @@
+# Workflow Core 3.1.0
+
+## Decision Branching
+
+You can define multiple independent branches within your workflow and select one based on an expression value.
+
+For the fluent API, we define our branches with the `CreateBranch()` method on the workflow builder.  We can then select a branch using the `Decision` step.
+
+This workflow will select `branch1` if the value of `data.Value1` is `one`, and `branch2` if it is `two`.
+```c#
+var branch1 = builder.CreateBranch()
+    .StartWith<PrintMessage>()
+        .Input(step => step.Message, data => "hi from 1")
+    .Then<PrintMessage>()
+        .Input(step => step.Message, data => "bye from 1");
+
+var branch2 = builder.CreateBranch()
+    .StartWith<PrintMessage>()
+        .Input(step => step.Message, data => "hi from 2")
+    .Then<PrintMessage>()
+        .Input(step => step.Message, data => "bye from 2");
+
+
+builder
+    .StartWith<HelloWorld>()
+    .Decide(data => data.Value1)
+        .Branch("one", branch1)
+        .Branch("two", branch2);
+```
+
+The JSON representation would look somthing like this.
+
+```json
+{
+  "Id": "DecisionWorkflow",
+  "Version": 1,
+  "DataType": "MyApp.MyData, MyApp",
+  "Steps": [
+    {
+      "Id": "decide",
+      "StepType": "WorkflowCore.Primitives.Decide, WorkflowCore",
+      "Inputs": 
+      {
+        "Expression": "data.Value1" 
+      },
+      "OutcomeSteps":
+      {
+        "Print1": "\"one\"",
+        "Print2": "\"two\""
+      }
+    },
+    {
+      "Id": "Print1",
+      "StepType": "MyApp.PrintMessage, MyApp",
+      "Inputs": 
+	  { 
+		"Message": "\"Hello from 1\"" 
+	  }
+    },
+    {
+      "Id": "Print2",
+      "StepType": "MyApp.PrintMessage, MyApp",
+      "Inputs": 
+	  { 
+	    "Message": "\"Hello from 2\"" 
+	  }
+    }
+  ]
+}
+```
+
+
+## Outcomes for JSON workflows
+
+You can now specify `OutcomeSteps` for a step in JSON and YAML workflow definitions.
+
+```
+"OutcomeSteps":
+{
+	"<<Step1 Id>>": "<<expression>>",
+	"<<Step2 Id>>": "<<expression>>"
+}
+```
+If the outcome of a step matches a particular expression, that step would be scheduled as the next step to execute.

WorkflowCore.sln

@@ -101,6 +101,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "ReleaseNotes", "ReleaseNote
 		ReleaseNotes\2.0.0.md = ReleaseNotes\2.0.0.md
 		ReleaseNotes\2.1.0.md = ReleaseNotes\2.1.0.md
 		ReleaseNotes\2.1.2.md = ReleaseNotes\2.1.2.md
+		ReleaseNotes\3.0.0.md = ReleaseNotes\3.0.0.md
+		ReleaseNotes\3.1.0.md = ReleaseNotes\3.1.0.md
 	EndProjectSection
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "WorkflowCore.Sample14", "src\samples\WorkflowCore.Sample14\WorkflowCore.Sample14.csproj", "{6BC66637-B42A-4334-ADFB-DBEC9F29D293}"
@@ -135,9 +137,11 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "WorkflowCore.Tests.Elastics
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "WorkflowCore.Tests.Redis", "test\WorkflowCore.Tests.Redis\WorkflowCore.Tests.Redis.csproj", "{78217204-B873-40B9-8875-E3925B2FBCEC}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "WorkflowCore.DSL", "src\WorkflowCore.DSL\WorkflowCore.DSL.csproj", "{20B98905-08CB-4854-8E2C-A31A078383E9}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "WorkflowCore.DSL", "src\WorkflowCore.DSL\WorkflowCore.DSL.csproj", "{20B98905-08CB-4854-8E2C-A31A078383E9}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "WorkflowCore.Sample18", "src\samples\WorkflowCore.Sample18\WorkflowCore.Sample18.csproj", "{5BE6D628-B9DB-4C76-AAEB-8F3800509A84}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "WorkflowCore.Sample18", "src\samples\WorkflowCore.Sample18\WorkflowCore.Sample18.csproj", "{5BE6D628-B9DB-4C76-AAEB-8F3800509A84}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ScratchPad", "test\ScratchPad\ScratchPad.csproj", "{FD7B9F06-9970-4C30-A2C0-FD7412FF620B}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -341,6 +345,10 @@ Global
 		{5BE6D628-B9DB-4C76-AAEB-8F3800509A84}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{5BE6D628-B9DB-4C76-AAEB-8F3800509A84}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{5BE6D628-B9DB-4C76-AAEB-8F3800509A84}.Release|Any CPU.Build.0 = Release|Any CPU
+		{FD7B9F06-9970-4C30-A2C0-FD7412FF620B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{FD7B9F06-9970-4C30-A2C0-FD7412FF620B}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{FD7B9F06-9970-4C30-A2C0-FD7412FF620B}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{FD7B9F06-9970-4C30-A2C0-FD7412FF620B}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -398,6 +406,7 @@ Global
 		{78217204-B873-40B9-8875-E3925B2FBCEC} = {E6CEAD8D-F565-471E-A0DC-676F54EAEDEB}
 		{20B98905-08CB-4854-8E2C-A31A078383E9} = {EF47161E-E399-451C-BDE8-E92AAD3BD761}
 		{5BE6D628-B9DB-4C76-AAEB-8F3800509A84} = {5080DB09-CBE8-4C45-9957-C3BB7651755E}
+		{FD7B9F06-9970-4C30-A2C0-FD7412FF620B} = {E6CEAD8D-F565-471E-A0DC-676F54EAEDEB}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {DC0FA8D3-6449-4FDA-BB46-ECF58FAD23B4}

docs/control-structures.md

@@ -131,3 +131,34 @@ builder
     )
     .Then(context => Console.WriteLine("Carry on"));
 ```
+
+### Decision Branches
+
+You can define multiple independent branches within your workflow and select one based on an expression value.
+
+For the fluent API, we define our branches with the `CreateBranch()` method on the workflow builder.  We can then select a branch using the `Decide` step.
+
+Use the `Decide` primitive step and hook up your branches via the `Branch` method.  The result of the input expression will be matched to the expressions listed via the `Branch` method, and the matching next step(s) will be scheduled to execute next.
+
+
+This workflow will select `branch1` if the value of `data.Value1` is `one`, and `branch2` if it is `two`.
+```c#
+var branch1 = builder.CreateBranch()
+    .StartWith<PrintMessage>()
+        .Input(step => step.Message, data => "hi from 1")
+    .Then<PrintMessage>()
+        .Input(step => step.Message, data => "bye from 1");
+
+var branch2 = builder.CreateBranch()
+    .StartWith<PrintMessage>()
+        .Input(step => step.Message, data => "hi from 2")
+    .Then<PrintMessage>()
+        .Input(step => step.Message, data => "bye from 2");
+
+
+builder
+    .StartWith<HelloWorld>()
+    .Decide(data => data.Value1)
+        .Branch("one", branch1)
+        .Branch("two", branch2);
+```

docs/json-yaml.md

@@ -480,3 +480,69 @@ Do:
   - Id: do2
     StepType: MyApp.DoSomething2, MyApp
 ```
+
+### Decision Branches
+
+You can define multiple independent branches within your workflow and select one based on an expression value.
+Use the `Decide` primitive step and hook up your branches via the `OutcomeSteps` property.  The result of the input expression will be matched to the expressions listed in `OutcomeSteps`, and the matching next step(s) will be scheduled to execute next.
+
+```json
+{
+  "Id": "DecisionWorkflow",
+  "Version": 1,
+  "DataType": "MyApp.MyData, MyApp",
+  "Steps": [
+    {
+      "Id": "decide",
+      "StepType": "WorkflowCore.Primitives.Decide, WorkflowCore",
+      "Inputs": 
+      {
+        "Expression": "<<input expression to evaluate>>" 
+      },
+      "OutcomeSteps":
+      {
+        "Branch1": "<<result expression to match for branch 1>>",
+        "Branch2": "<<result expression to match for branch 2>>"
+      }
+    },
+    {
+      "Id": "Branch1",
+      "StepType": "MyApp.PrintMessage, MyApp",
+      "Inputs": 
+	  { 
+		  "Message": "\"Hello from 1\"" 
+	  }
+    },
+    {
+      "Id": "Branch2",
+      "StepType": "MyApp.PrintMessage, MyApp",
+      "Inputs": 
+	  { 
+	    "Message": "\"Hello from 2\"" 
+	  }
+    }
+  ]
+}
+```
+
+```yaml
+Id: DecisionWorkflow
+Version: 1
+DataType: MyApp.MyData, MyApp
+Steps:
+- Id: decide
+  StepType: WorkflowCore.Primitives.Decide, WorkflowCore
+  Inputs:
+    Expression: <<input expression to evaluate>>
+  OutcomeSteps:
+    Branch1: '<<result expression to match for branch 1>>'
+    Branch2: '<<result expression to match for branch 2>>'
+- Id: Branch1
+  StepType: MyApp.PrintMessage, MyApp
+  Inputs:
+    Message: '"Hello from 1"'
+- Id: Branch2
+  StepType: MyApp.PrintMessage, MyApp
+  Inputs:
+    Message: '"Hello from 2"'
+```

src/WorkflowCore.DSL/Models/v1/StepSourceV1.cs

@@ -30,7 +30,8 @@ public class StepSourceV1
         public ExpandoObject Inputs { get; set; } = new ExpandoObject();
 
         public Dictionary<string, string> Outputs { get; set; } = new Dictionary<string, string>();
-
 
+        public Dictionary<string, string> OutcomeSteps { get; set; } = new Dictionary<string, string>();
+
     }
 }

src/WorkflowCore.DSL/Services/DefinitionLoader.cs

@@ -93,7 +93,7 @@ private WorkflowStepCollection ConvertSteps(ICollection<StepSourceV1> source, Ty
 
                 AttachInputs(nextStep, dataType, stepType, targetStep);
                 AttachOutputs(nextStep, dataType, stepType, targetStep);
-
+                
                 if (nextStep.Do != null)
                 {
                     foreach (var branch in nextStep.Do)
@@ -115,8 +115,7 @@ private WorkflowStepCollection ConvertSteps(ICollection<StepSourceV1> source, Ty
                         compensatables.Add(nextStep);
                 }
 
-                if (!string.IsNullOrEmpty(nextStep.NextStepId))
-                    targetStep.Outcomes.Add(new StepOutcome() { ExternalNextStepId = $"{nextStep.NextStepId}" });
+                AttachOutcomes(nextStep, dataType, targetStep);
 
                 result.Add(targetStep);
 
@@ -234,6 +233,23 @@ private void AttachOutputs(StepSourceV1 source, Type dataType, Type stepType, Wo
             }
         }
 
+        private void AttachOutcomes(StepSourceV1 source, Type dataType, WorkflowStep step)
+        {
+            if (!string.IsNullOrEmpty(source.NextStepId))
+                step.Outcomes.Add(new StepOutcome() { ExternalNextStepId = $"{source.NextStepId}" });
+            
+            foreach (var nextStep in source.OutcomeSteps)
+            {
+                var dataParameter = Expression.Parameter(dataType, "data");
+                var sourceExpr = DynamicExpressionParser.ParseLambda(new[] { dataParameter }, typeof(object), nextStep.Value);
+                step.Outcomes.Add(new StepOutcome()
+                {
+                    Value = sourceExpr,
+                    ExternalNextStepId = $"{nextStep.Key}"
+                });
+            }
+        }
+
         private Type FindType(string name)
         {
             return Type.GetType(name, true, true);

src/WorkflowCore.DSL/WorkflowCore.DSL.csproj

@@ -1,8 +1,8 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <TargetFramework>netstandard2.0</TargetFramework>
-    <Version>3.0.0</Version>
+    <Version>3.1.0</Version>
     <Description>DSL extenstion for Workflow Core provding support for JSON and YAML workflow definitions.</Description>
     <Authors>Daniel Gerlag</Authors>
     <Company />

src/WorkflowCore/Interface/IStepBuilder.cs

@@ -73,6 +73,13 @@ public interface IStepBuilder<TData, TStepBody>
         [Obsolete]
         IStepOutcomeBuilder<TData> When(object outcomeValue, string label = null);
 
+        /// <summary>
+        /// Configure an outcome branch for this step, then wire it to another step
+        /// </summary>
+        /// <param name="outcomeValue"></param>
+        /// <returns></returns>
+        IStepBuilder<TData, TStepBody> Branch<TStep>(object outcomeValue, IStepBuilder<TData, TStep> branch) where TStep : IStepBody;
+
         /// <summary>
         /// Map properties on the step to properties on the workflow data object before the step executes
         /// </summary>
@@ -158,6 +165,13 @@ public interface IStepBuilder<TData, TStepBody>
         /// <returns></returns>
         IStepBuilder<TData, Delay> Delay(Expression<Func<TData, TimeSpan>> period);
 
+        /// <summary>
+        /// Evaluate an expression and take a different path depending on the value
+        /// </summary>
+        /// <param name="expression">Expression to evaluate for decision</param>
+        /// <returns></returns>
+        IStepBuilder<TData, Decide> Decide(Expression<Func<TData, object>> expression);
+        
         /// <summary>
         /// Execute a block of steps, once for each item in a collection in a parallel foreach
         /// </summary>

src/WorkflowCore/Interface/IWorkflowBuilder.cs

@@ -7,13 +7,17 @@ namespace WorkflowCore.Interface
 {
     public interface IWorkflowBuilder
     {
+        List<WorkflowStep> Steps { get; }
+
         int LastStep { get; }                
 
         IWorkflowBuilder<T> UseData<T>();
 
         WorkflowDefinition Build(string id, int version);
 
         void AddStep(WorkflowStep step);
+
+        void AttachBranch(IWorkflowBuilder branch);
     }
 
     public interface IWorkflowBuilder<TData> : IWorkflowBuilder
@@ -27,5 +31,8 @@ public interface IWorkflowBuilder<TData> : IWorkflowBuilder
         IEnumerable<WorkflowStep> GetUpstreamSteps(int id);
 
         IWorkflowBuilder<TData> UseDefaultErrorBehavior(WorkflowErrorHandling behavior, TimeSpan? retryInterval = null);
+
+        IWorkflowBuilder<TData> CreateBranch();
+                
     }
 }

src/WorkflowCore/Models/StepOutcome.cs

@@ -5,9 +5,9 @@ namespace WorkflowCore.Models
 {
     public class StepOutcome
     {
-        private Expression<Func<object, object>> _value;
+        private LambdaExpression _value;
 
-        public Expression<Func<object, object>> Value
+        public LambdaExpression Value
         {
             set { _value = value; }
         }
@@ -23,7 +23,7 @@ public object GetValue(object data)
             if (_value == null)
                 return null;
 
-            return _value.Compile().Invoke(data);
+            return _value.Compile().DynamicInvoke(data);
         }
     }
 }