Umbraco.UIBuilder.Automate 18.0.1

<p align="center"> <img alt="Umbraco Automate" src="./assets/logo-128.png" width="128"> </p>

Umbraco.UIBuilder.Automate

Umbraco UI Builder triggers and actions for Umbraco Automate.

Overview

Umbraco.UIBuilder.Automate is a provider package that connects Umbraco UI Builder to Umbraco Automate, exposing UI Builder entity lifecycle events as first-class triggers and entity operations as actions in Automate flows — for example, notifying a channel when a new customer record is created, or cascading a delete to a related collection.

Key Features

• 3 triggers — react to entity created, saved, and deleted events across any registered UI Builder collection
• 2 actions — create and delete entities in a named UI Builder collection
• Rich trigger outputs — collection alias, entity ID, and the full entity serialized as JSON (encrypted properties omitted)
• Zero configuration — triggers and actions are automatically discovered by Umbraco Automate

Installation

dotnet add package Umbraco.UIBuilder.Automate

No further wiring is required — triggers and actions are auto-discovered by Umbraco Automate.

Requirements

• .NET 10.0
• Umbraco CMS 17.0.0+
• Umbraco UI Builder 17.0.0+
• Umbraco.Automate compatible version

Triggers

Fire an Automate flow when something happens in UI Builder.

All three triggers support an optional Collection Alias setting to filter to a specific collection (case-insensitive); leave it blank to fire for all collections. Entity Created is derived from the same notification as Entity Saved, filtered to the case where no prior version of the entity existed.

Entity Saved / Entity Created output

Entity Deleted output

Note: Properties configured as encrypted on the collection are omitted from EntityJson so that decrypted secrets are never persisted in the outbox or exposed to automations.

Actions

Run UI Builder operations from an Automate flow.

Create Entity

If the create is cancelled by an EntitySavingNotification handler or otherwise fails, the action fails with the underlying error rather than reporting a false success.

Delete Entity

Usage Examples

Notify on new entity creation

Trigger: Entity Saved (Collection Alias: customers)
  → Condition: IsNew == true
  → Action: Send Slack message
            "New customer created: {EntityJson}"

Cascade delete related data

Trigger: Entity Deleted (Collection Alias: orders)
  → Action: Delete Entity on the orderLines collection
            binding EntityId from the trigger output

Audit log all changes

Trigger: Entity Saved (no collection filter — fires for all collections)
  → Action: Write to an audit log system
            passing CollectionAlias, EntityId, IsNew, EntityJson

How It Works

Why triggers inject IUIBuilderAdapter

UI Builder's EntitySavedNotification and EntityDeletedNotification are intentionally generic — they fire for every registered entity type across all collections and carry no collection context. Unlike Commerce or Engage notifications (which wrap a specific domain object), UI Builder notifications do not identify which collection an entity belongs to.

IUIBuilderAdapter resolves this at runtime by:

1. Matching the entity's CLR type against registered collection configurations
2. Extracting the entity ID using the collection's configured ID property

This is an intentional deviation from the standard Automate trigger pattern where constructor injection is limited to TriggerInfrastructure. The deviation is documented on the trigger classes.

Entities registered in multiple collections

A single CLR type can be registered in more than one UI Builder collection. Because UI Builder's notifications carry no collection context, there is no way to know which collection a saved or deleted entity actually belonged to. When a type matches multiple collections the event is attributed to a single collection deterministically (lowest alias, ordinal) and a warning is logged. If you need per-collection behaviour for a shared type, filter downstream on CollectionAlias, or register distinct CLR types per collection.

Idempotency

The Entity Created and Entity Deleted triggers set an idempotency key of {triggerAlias}:{collectionAlias}:{entityId} so that a duplicate notification for the same event is de-duplicated by the outbox. This key contains no version component, so for collections with reused natural keys (as opposed to auto-increment/GUID keys) a create-delete-recreate of the same ID within the outbox retention window could be de-duplicated. This does not affect the common case of database-generated identity or GUID keys. The Entity Saved trigger sets no idempotency key, so every save reaches the outbox.

No RequiredSections

UI Builder sections are created by the developer with custom aliases (e.g. "myShop", "crm"). There is no fixed UI Builder backoffice section alias, so RequiredSections cannot be set on triggers and actions. All Automate users can see UI Builder step types regardless of section membership.

Development

dotnet restore
dotnet build
dotnet test

Project layout

src/
  Umbraco.UIBuilder.Automate/
    Actions/                # Automate actions that call UI Builder operations
    Internal/                # IUIBuilderAdapter and supporting collection/serialization helpers
    Triggers/                # Automate triggers backed by UI Builder notifications
    UIBuilderAutomateComposer.cs
tests/
  Umbraco.UIBuilder.Automate.Tests.Unit/

Future Work

These UI Builder notifications exist and could be exposed as triggers in a future version:

Cancelable notifications are observable-only in the current Automate trigger model — they cannot veto the operation. (Entity Created is already exposed, derived from EntitySavedNotification, so it is not listed here.)

These operations could be exposed as actions in a future release:

License

MIT — see LICENSE for details.