SalesLeads Demo Handler

What Makes This a "Demo" Handler

The built-in handler writes to a generic log table (Process_StateLogs) that works for any use case. The SalesLeads handler writes directly to CRMSimple_SalesLeads — a real CRM domain table. The node that uses this handler doesn't just track state; it owns and manages the lead record.

This is the template to study before building your own handler. Every key decision is made here: key mapping, update strategy, plugin registration, 3-project layout.

CRMSimple_SalesLeads Table Schema

Key Mapping Strategy

The SalesLeads handler maps business keys to StateHandlerContext fields differently from the built-in handler:

// SalesLeadRepository — key mapping in queries
public async Task<IdempotencyStatus?> GetCurrentStatusAsync(
    StateHandlerContext ctx, CancellationToken ct)
{
    var lead = await _ctx.SalesLeads
        .Where(l => l.Email    == ctx.ItemEntityKey   // Email ← ItemEntityKey
                 && l.LeadType == ctx.ItemKey          // LeadType ← ItemKey
                 && l.TenantID == ctx.TenantID
                 && !l.Deleted)
        .OrderByDescending(l => l.Created)
        .FirstOrDefaultAsync(ct);

    return lead is null
        ? null
        : (IdempotencyStatus)lead.Status;
}

In-Place Update vs Append-Only

The built-in handler uses an append-only strategy — it inserts a new row and marks old rows Superseded using SupersededByID. This gives complete history but uses more storage.

The SalesLeads handler uses in-place update — it updates the existing lead row's Status, data fields, and Modified timestamp. This is appropriate when the entity IS the record (a CRM lead record should be one row, not dozens of history rows).

public async Task SetAsync(
    StateHandlerContext ctx, IdempotencyStatus status, string? data, CancellationToken ct)
{
    var lead = await _repo.GetByKeyAsync(
        email: ctx.ItemEntityKey, leadType: ctx.ItemKey, ctx.TenantID, ct);

    if (lead is null)
    {
        // First time we see this lead — insert
        await _repo.InsertAsync(BuildLead(ctx, status, data), ct);
    }
    else
    {
        // Lead exists — update in place
        lead.Status   = (int)status;
        lead.Modified = DateTime.UtcNow;
        // Optionally update enrichment fields from data JSON
        await _repo.UpdateAsync(lead, ct);
    }
}

Plugin Registration

public class SalesLeadsDataStateMachinePlugin : IDataStateMachinePlugin
{
    public void Register(IServiceCollection services, IConfiguration config)
    {
        // Handler is Singleton — shared across all requests
        services.AddSingleton<IDataStateMachineHandler, SalesLeadsDataStateMachineHandler>();

        // Repository is Scoped — one per request (holds DbContext)
        services.AddScoped<ISalesLeadRepository, SalesLeadRepository>();

        // Register the DbContext for this handler
        services.AddDbContext<SalesLeadsDbContext>(opts =>
            opts.UseSqlServer(config.GetConnectionString("BizFirstFiV3")));
    }
}

Node Config to Activate This Handler

{
  "dataStateMachine": {
    "handler": "sales-leads",
    "scope":   "Element",
    "options": {}
  }
}

Using as a Template for Your Custom Handler

Replace CRMSimple_SalesLeads with your own domain table. Replace Email and LeadType with your own business keys. Decide on in-place update vs append-only. Implement IDataStateMachinePlugin. Add your DLL to the output folder. Done.