Implementation notes using Esla 2.0

[dodyg]

I need a simple workflow for our internal recruitment system to handle customizable email notifications when certain events happen (new submission, new file submission) and also to configure automatic tagging.

This thread will just contain things that I found while learning and integrating Esla to this small application.

[dodyg]

OK so it seems to me that the most prudent way is to use the latest build of Esla 2.0 #347 (reply in thread)

[dodyg]

Hello world with Esla 2

using System;
using Elsa.Activities.Console;
using Elsa.Builders;
using Elsa.Services;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection()
    .AddElsaCore(options => options.
        AddConsoleActivities()
        .AddWorkflow<HelloWorld>())
    .BuildServiceProvider();

var workflowRunner = services.GetRequiredService<IBuildsAndStartsWorkflow>();
await workflowRunner.BuildAndStartWorkflowAsync<HelloWorld>();

public class HelloWorld : IWorkflow
{
    public void Build(IWorkflowBuilder builder)
    {
        builder.WriteLine("Hello world 2");
    }
}

[dodyg]

This doesn't work - it just prints Hello World 0. I will have to return to this later on. My expectation is that this workflow will run ever 5 seconds but this is probably just a wrong API to use.

using System;
using Elsa.Activities.Console;
using Elsa.Builders;
using Elsa.Services;
using Elsa.Activities.Temporal;
using Microsoft.Extensions.DependencyInjection;
using NodaTime;
using Elsa;

var services = new ServiceCollection()
    .AddElsaCore(options => options.
        AddConsoleActivities()
        .AddWorkflow<HelloWorld>()
        .AddQuartzTemporalActivities()
        )
    .BuildServiceProvider();

var workflowRunner = services.GetRequiredService<IBuildsAndStartsWorkflow>();
await workflowRunner.BuildAndStartWorkflowAsync<HelloWorld>();
Console.ReadLine();

public class HelloWorld : IWorkflow
{
    public void Build(IWorkflowBuilder builder)
    {
        int count = 0;
        builder.Timer(Duration.FromSeconds(5))
            .WriteLine($"Hello world {count++}");
    }
}

[dodyg]

The funny thing is that above code won't print anything I remove the .Timer(Duration.FromSeconds(2)).

[dodyg]

OK this works. The lesson here if you use Timer() you don't need to explicitly start the activity. If you don't, you gotta start the workflow manually.

using Elsa;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Elsa.Activities.Console;
using Elsa.Builders;
using Elsa.Services;

using var host = new HostBuilder()
    .ConfigureServices(services =>
    {
        services.AddElsa(elsa =>
        {
            elsa
                .AddConsoleActivities()
                .AddQuartzTemporalActivities()
                .AddWorkflow<HelloWorld>();
        });
    })
    .UseConsoleLifetime()
    .Build();

await host.Services.GetService<IBuildsAndStartsWorkflow>().BuildAndStartWorkflowAsync<HelloWorld>();
await host.WaitForShutdownAsync();

public class HelloWorld : IWorkflow
{
    public void Build(IWorkflowBuilder builder) =>
        builder
            .WriteLine(() => $"Let's do this thing!");
}

[dodyg]

Now lets figure out how to add an activity to a workflow

[dodyg]

Ok that was easy

using Elsa;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Elsa.Builders;
using Elsa.Services;
using Elsa.ActivityResults;

using var host = new HostBuilder()
    .ConfigureServices(services =>
    {
        services.AddElsa(elsa =>
        {
            elsa
                .AddConsoleActivities()
                .AddQuartzTemporalActivities()
                .AddWorkflow<HelloWorld>()
                .AddActivity<SayHello>();
        });
    })
    .UseConsoleLifetime()
    .Build();

await host.Services.GetService<IBuildsAndStartsWorkflow>().BuildAndStartWorkflowAsync<HelloWorld>();
await host.WaitForShutdownAsync();

public class HelloWorld : IWorkflow
{
    public void Build(IWorkflowBuilder builder) =>
        builder
            .Add<SayHello>();
}

public class SayHello : Activity
{
    protected override IActivityExecutionResult OnExecute()
    {
        System.Console.WriteLine("Hello world");
        return Done();
    }
}

[sfmskywalker]

@dodyg

Regarding the Timer activity, the reason such workflows won't work in regular console apps is because they rely on additional background services to run (such as Quartz.NET). Therefore, these activities only work correctly when the .NET application is created using a (web) host as you've seen when using the HostBuilder API.

Of course, even when using HostBuilder to setup the application, merely registering a workflow that does not have any "trigger" activities such as Timer won't automatically execute either; those you would have to run manually. Or, add a trigger such as Timer or HTTP Endpoint (which itself requires additional middleware to be installed with the ASP.NET Core pipeline).

I figured it might be helpful to clear this up a little.

I'm loving the learning points you're sharing here, thanks for doing that!

[dodyg]

We can set a variable from the workflow and use it within activity.

using Elsa;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Elsa.Builders;
using Elsa.Services;
using Elsa.ActivityResults;
using Elsa.Services.Models;

using var host = new HostBuilder()
    .ConfigureServices(services =>
    {
        services.AddElsa(elsa =>
        {
            elsa
                .AddConsoleActivities()
                .AddQuartzTemporalActivities()
                .AddWorkflow<HelloWorld>()
                .AddActivity<SayHello>();
        });
    })
    .UseConsoleLifetime()
    .Build();

await host.Services.GetService<IBuildsAndStartsWorkflow>().BuildAndStartWorkflowAsync<HelloWorld>();
await host.WaitForShutdownAsync();

public class HelloWorld : IWorkflow
{
    public void Build(IWorkflowBuilder builder) =>
        builder
            .SetVariable("message", "hello")
            .Then<SayHello>();
}

public class SayHello : Activity
{
    protected override IActivityExecutionResult OnExecute(ActivityExecutionContext context)
    {
        var message = context.GetVariable<string>("message");
        System.Console.WriteLine(message);
        return Done();
    }
}

[dodyg]

OutcomeNames is really useful

[dodyg]

So Outcome(OutcomeNames.Done) is the same as Done()

public class HelloWorld : IWorkflow
{
    public void Build(IWorkflowBuilder builder) =>
        builder
            .SetVariable("message1", "hello")
            .Then<SayHello>()
            .When(OutcomeNames.Done).WriteLine("Display is successful");
}

So "Display is successful" will be displayed when SayHello returns Done(). What will happen if it returns Fault() though.

[dodyg]

Maybe this is the answer #594 (comment)

[sfmskywalker]

What will happen if it returns Fault() though.

When returning a FaultResult, it will put the workflow instance into the Faulted state, which means it will simply stop any further execution.

[sfmskywalker]

There's probably a way to do it but I don't know it yet.

Elsa catches all exceptions that happen when a given activity executes and puts the workflow instance into the Faulted state. It also writes a log entry at the Error log level. This will show up in the console if logging is configured to display errors.

[dodyg]

Call one activity then another

using Elsa;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Elsa.Builders;
using Elsa.Services;
using Elsa.ActivityResults;
using Elsa.Services.Models;
using System;

using var host = new HostBuilder()
    .ConfigureServices(services =>
    {
        services.AddElsa(elsa =>
        {
            elsa
                .AddConsoleActivities()
                .AddQuartzTemporalActivities()
                .AddWorkflow<HelloWorld>()
                .AddActivity<SayHello>()
                .AddActivity<SayGoodbye>();
        });
    })
    .UseConsoleLifetime()
    .Build();

await host.Services.GetService<IBuildsAndStartsWorkflow>().BuildAndStartWorkflowAsync<HelloWorld>();
await host.WaitForShutdownAsync();

public class HelloWorld : IWorkflow
{
    public void Build(IWorkflowBuilder builder) =>
        builder
            .SetVariable("message", "hello")
            .Then<SayHello>()
            .Then<SayGoodbye>();
}

public class SayHello : Activity
{
    protected override IActivityExecutionResult OnExecute(ActivityExecutionContext context)
    {
        try
        {
            var message = context.GetVariable<string>("message");
            System.Console.WriteLine(message);
            context.SetVariable("message", "goodbye");
            return Outcome(OutcomeNames.Done);
        }
        catch(Exception ex)
        {
            return Fault(ex.Message);
        }
    }
}

public class SayGoodbye : Activity
{
    protected override IActivityExecutionResult OnExecute(ActivityExecutionContext context)
    {
        try
        {
            var message = context.GetVariable<string>("message");
            System.Console.WriteLine(message);
            return Outcome(OutcomeNames.Done);
        }
        catch (Exception ex)
        {
            return Fault(ex.Message);
        }
    }
}

Pay attention SayHello activity set the message variable.

[dodyg]

You can return output object when you return Done() from one Activity and it can be an input to another Activity

using Elsa;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Elsa.Builders;
using Elsa.Services;
using Elsa.ActivityResults;
using Elsa.Services.Models;
using System;

using var host = new HostBuilder()
    .ConfigureServices(services =>
    {
        services.AddElsa(elsa =>
        {
            elsa
                .AddConsoleActivities()
                .AddQuartzTemporalActivities()
                .AddWorkflow<HelloWorld>()
                .AddActivity<SayHello>()
                .AddActivity<SayGoodbye>();
        });
    })
    .UseConsoleLifetime()
    .Build();

await host.Services.GetService<IBuildsAndStartsWorkflow>().BuildAndStartWorkflowAsync<HelloWorld>();
await host.WaitForShutdownAsync();

public class HelloWorld : IWorkflow
{
    public void Build(IWorkflowBuilder builder) =>
        builder
            .SetVariable("message", "hello")
            .Then<SayHello>()
            .Then<SayGoodbye>();
}

public class SayHello : Activity
{
    protected override IActivityExecutionResult OnExecute(ActivityExecutionContext context)
    {
        try
        {
            var message = context.GetVariable<string>("message");
            System.Console.WriteLine(message);
            return Done("goodbye");
        }
        catch(Exception ex)
        {
            return Fault(ex.Message);
        }
    }
}

public class SayGoodbye : Activity
{
    protected override IActivityExecutionResult OnExecute(ActivityExecutionContext context)
    {
        try
        {
            var message = context.GetInput<string>();
            System.Console.WriteLine("What is the message? " + message);
            return Outcome(OutcomeNames.Done);
        }
        catch (Exception ex)
        {
            return Fault(ex.Message);
        }
    }
}

[dodyg]

The problem is this: in SayHello if you return Output("goodbye"), it won't work. It's not clear what's the purpose of Output function. This is confusing.

e.g. below's code won't work. It will compile fine but the workflow would stop working and never reach SayGoodbye.

public class SayHello : Activity
{
    protected override IActivityExecutionResult OnExecute(ActivityExecutionContext context)
    {
        try
        {
            var message = context.GetVariable<string>("message");
            System.Console.WriteLine(message);
            return Output("goodbye");
        }
        catch(Exception ex)
        {
            return Fault(ex.Message);
        }
    }
}

[sfmskywalker]

It's not clear what's the purpose of Output function. This is confusing.

The Output method (which doesn't exist anymore in the latest version in master) used to return an OutputResult object which stored the provided value into the workflow instance, which would then be automatically "fed" into the next activity to execute as input.

The reason the SayHello activity doesn't seem to do anything is because you didn't tell the workflow runner what to do next (other then storing "goodbye" as an output value).

To instruct the workflow runner to continue with the next activity, you also need to return an OutcomeResult. To return multiple activity execution results, you can use the Combine method and provide multiple values.

For example, the following should work:

return Combine(Output("goodbye"), Done()); 

As mentioned before, the Output method no longer exists. With the latest version, to provide output from an activity, you can do one of the following:

1. Expose a public property like [ActivityOutput] public string Output { get; set; }, or
2. Use the Outcome method to provide both the outcome name as well as an output value.

Regardless of which method you choose, the output will be provided as input to the next activity to execute.

[dodyg]

Esla Default Activities

SetVariable

SetVariable("name", val)

This activity assign variable with value in ActivityExecutionContext .SetVariable .

definition

Then

Then<Activity>().

Activtiy is only executed if the previous Outcome is OutcomeNames.Done.

[dodyg]

Loop

This executes SayHello activity 4 times.

using Elsa;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Elsa.Builders;
using Elsa.Services;
using Elsa.ActivityResults;
using Elsa.Services.Models;
using System;
using Elsa.Activities.ControlFlow;

using var host = new HostBuilder()
    .ConfigureServices(services =>
    {
        services.AddElsa(elsa =>
        {
            elsa
                .AddConsoleActivities()
                .AddQuartzTemporalActivities()
                .AddWorkflow<Loop>()
                .AddActivity<SayHello>();
        });
    })
    .UseConsoleLifetime()
    .Build();

await host.Services.GetService<IBuildsAndStartsWorkflow>().BuildAndStartWorkflowAsync<Loop>();
await host.WaitForShutdownAsync();

public class Loop : IWorkflow
{
    public void Build(IWorkflowBuilder builder) =>
        builder
        .For(start: 0, end: 4, x => x.Then<SayHello>());
}

public class SayHello : Activity
{
    protected override IActivityExecutionResult OnExecute(ActivityExecutionContext context)
    {
        try
        {
            System.Console.WriteLine("Say Hello");
            return Done();
        }
        catch(Exception ex)
        {
            return Fault(ex.Message);
        }
    }
}

[dodyg]

Loop with accessing the index value

using Elsa;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Elsa.Builders;
using Elsa.Services;
using Elsa.ActivityResults;
using Elsa.Services.Models;
using System;
using Elsa.Activities.ControlFlow;

using var host = new HostBuilder()
    .ConfigureServices(services =>
    {
        services.AddElsa(elsa =>
        {
            elsa
                .AddConsoleActivities()
                .AddQuartzTemporalActivities()
                .AddWorkflow<Loop>()
                .AddActivity<Print>();
        });
    })
    .UseConsoleLifetime()
    .Build();

await host.Services.GetService<IBuildsAndStartsWorkflow>().BuildAndStartWorkflowAsync<Loop>();
await host.WaitForShutdownAsync();

public class Loop : IWorkflow
{
    public void Build(IWorkflowBuilder builder) =>
        builder
        .For(start: 0, end: 4, x => x.Then<Print>());
}

public class Print : Activity
{
    protected override IActivityExecutionResult OnExecute(ActivityExecutionContext context)
    {
        try
        {
            var index = context.GetVariable("CurrentValue");
            System.Console.WriteLine($"Say Hello {index}");
            return Done();
        }
        catch (Exception ex)
        {
            return Fault(ex.Message);
        }
    }
}

[dodyg]

Foreach

This will print the index, the value and the type of the given collection.

using Elsa;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Elsa.Builders;
using Elsa.Services;
using Elsa.ActivityResults;
using Elsa.Services.Models;
using System;
using Elsa.Activities.ControlFlow;

using var host = new HostBuilder()
    .ConfigureServices(services =>
    {
        services.AddElsa(elsa =>
        {
            elsa
                .AddConsoleActivities()
                .AddQuartzTemporalActivities()
                .AddWorkflow<Loop>()
                .AddActivity<Print>();
        });
    })
    .UseConsoleLifetime()
    .Build();

await host.Services.GetService<IBuildsAndStartsWorkflow>().BuildAndStartWorkflowAsync<Loop>();
await host.WaitForShutdownAsync();

public class Loop : IWorkflow
{
    public void Build(IWorkflowBuilder builder) =>
        builder
        .ForEach(x => new int[] { 10, 20, 30, 40 }, x =>
        {
            x.Then<Print>();
        });
}

public class Print : Activity
{
    protected override IActivityExecutionResult OnExecute(ActivityExecutionContext context)
    {
        try
        {
            var index = context.GetVariable("CurrentIndex");
            var value = context.GetVariable("CurrentValue");
            System.Console.WriteLine($"Index {index} values {value} type {value.GetType()}");
            return Done("No");
        }
        catch(Exception ex)
        {
            return Fault(ex.Message);
        }
    }
}

[dodyg]

@sfmskywalker

Why does in this workflow "CurrentValue" variable is missing from IfTrue

public class Loop : IWorkflow
{
    public void Build(IWorkflowBuilder builder) =>
        builder
        .ForEach(x => new int[] { 10, 20, 30, 40 }, x =>
        {
            x.IfTrue(condition: (ActivityExecutionContext m) =>
            {
                var has = m.HasVariable("CurrentValue");
                Console.WriteLine("Has variable " + has);
                var value = m.GetVariable<int>("CurrentValue");
                Console.WriteLine("Debug Value " + value);
                return value == 40;
            }, whenTrue: (y) =>
            {
                y.WriteLine("The last value");
            });
        });
}

but if I implement a custom activity, the variable are accessible

using Elsa;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Elsa.Builders;
using Elsa.Services;
using Elsa.ActivityResults;
using Elsa.Services.Models;
using System;
using Elsa.Activities.ControlFlow;
using Elsa.Activities.Console;
using Elsa.Activities.Primitives;

using var host = new HostBuilder()
    .ConfigureServices(services =>
    {
        services.AddElsa(elsa =>
        {
            elsa
                .AddConsoleActivities()
                .AddQuartzTemporalActivities()
                .AddWorkflow<Loop>()
                .AddActivity<Print>();
        });
    })
    .UseConsoleLifetime()
    .Build();

await host.Services.GetService<IBuildsAndStartsWorkflow>().BuildAndStartWorkflowAsync<Loop>();
await host.WaitForShutdownAsync();

public class Loop : IWorkflow
{
    public void Build(IWorkflowBuilder builder) =>
        builder
        .ForEach(x => new int[] { 10, 20, 30, 40 }, x =>
        {
            x.Then<Print>();
        });
}

public class Print : Activity
{
    protected override IActivityExecutionResult OnExecute(ActivityExecutionContext context)
    {
        try
        {
            var index = context.GetVariable("CurrentIndex");
            var value = context.GetVariable("CurrentValue");
            System.Console.WriteLine($"Index {index} values {value} type {value.GetType()}");
            return Done("No");
        }
        catch(Exception ex)
        {
            return Fault(ex.Message);
        }
    }
}

[sfmskywalker]

You discovered a bug, great find!

I will fix.

[sfmskywalker]

Fixed in e427a27.