Automation Builder

The automation builder provides methods for quickly writing automations. To use the automation builder, inject an IAutomationBuilder or IStartupHelpers (which has a Builder property) into any IAutomationRegistry. Here is a brief example.

    public void Register(IRegistrar reg)
    {
        var simpleAutomation = _builder.CreateSimple()
            .WithTriggers("switch.my_switch")
            .WithName("This is my simple automation")
            .WithExecution(async (stateChange, cancellationToken) => {
                // do work
                return;
            })
            .Build();

        reg.Register(simpleAutomation);
    }

The builder has several methods and overloads for creating Simple, Conditional, Schedulable, and Sun automations.

When using a generic method, the state change passed to your WithExecution method will match appropriately. Each of these methods will return some version of the abstract AutomationBuildingInfo object, which in turn has extension methods for setting up the automation. Depending on the method you call, you will have different options for setting up the automation.

public interface IAutomationBuilder
{
    SimpleAutomationBuildingInfo CreateSimple(bool enabledAtStartup = true);
    TypedAutomationBuildingInfo<Tstate, Tatt> CreateSimple<Tstate, Tatt>(bool enabledAtStartup = true);
    TypedAutomationBuildingInfo<Tstate, JsonElement> CreateSimple<Tstate>(bool enabledAtStartup = true) 
        => CreateSimple<Tstate, JsonElement>(enabledAtStartup);

    ConditionalAutomationBuildingInfo CreateConditional(bool enabledAtStartup = true);
    TypedConditionalBuildingInfo<Tstate, Tatt> CreateConditional<Tstate, Tatt>(bool enabledAtStartup = true);
    TypedConditionalBuildingInfo<Tstate, JsonElement> CreateConditional<Tstate>(bool enabledAtStartup = true) 
        => CreateConditional<Tstate, JsonElement>(enabledAtStartup);

    SchedulableAutomationBuildingInfo CreateSchedulable(bool reschdulable = false, bool enabledAtStartup = true);
    TypedSchedulableAutomationBuildingInfo<Tstate, Tatt> CreateSchedulable<Tstate, Tatt>(bool reschdulable = false, bool enabledAtStartup = true);
    TypedSchedulableAutomationBuildingInfo<Tstate, JsonElement> CreateSchedulable<Tstate>(bool reschdulable = false, bool enabledAtStartup = true) 
        => CreateSchedulable<Tstate, JsonElement>(reschdulable, enabledAtStartup);

    SunAutommationBuildingInfo CreateSunAutomation(SunEventType sunEvent, bool enabledAtStartup = true);
}

At a minimum, to create an automation with the builder,

• Call one of the Create methods
• Specify one or more triggers
• Specify the execution
• Call Build()

Note: depending on the Create method called, there may be other requirements. For example, any conditional automation requires you call the When method and one of the For methods to specify the duration.

Here is an example of creating a strongly-typed and durable automation.

        var typedDurable = _builder.CreateSchedulable<OnOff>()
            .WithTriggers("input_boolean.my_motion_sensor")
            .WithName("Turn off the lights when no one is around")
            .WithDescription("an optional description")
            .While(sc => sc.IsOff())
            .ForMinutes(30)            
            .WithExecution(ct => _services.Api.TurnOffByLabel("my_label", ct))
            .MakeDurable()
            .Build();

Notice that ToOnOff() did not need to be called because the state change is already typed appropriately.

Below is a list of methods that extend various automation info objects returned by the builder. See Automation Types for details of each type.

• WithName - sets the name of the automation. If you do not specify a name, one will be created for you.
• WithDescription - sets the optional description
• WithMode - sets the mode of the automation
• WithAdditionalEntitiesToTrack - Sets additional entities to track. See System Monitor for more details.
• When - for use with Conditional automations
• While - for use with Schedulable automations
• For, ForMinutes, ForHours - specifies when a delayable automation should run after the When/While returns true
• GetNextScheduled - For use with Schedulable automations. You should only use this method if not using the While and For methods. This method takes a lambda that takes the state change like the while method and should return a DateTime to specify when the automation should be scheduled
• SetReschedulable - For use with schedulable automations
• ShouldExecutePastEvents - For use with schedulable automations
• ShouldContinueOnError - For use with delayable automations
• MakeDurable - makes a schedulable automation use Durable timings
• WithTimings - Sets the timings of an automation. Note this will override MakeDurable and vice versa
• TriggerOnBadState - allows your automation to trigger if the state is "unknown" or "unavailable"