Building a Channel Node

What You Are Building

A HIL channel node is a node executor that:

1. Reads the field manifest to know what to present to the human.
2. Formats those fields for the target channel.
3. Sends the message via the channel's API.
4. Returns "waiting" to suspend the workflow.
5. Has a corresponding webhook controller that resumes the workflow when the human responds.

The node executor and the webhook controller are two separate entry points but share the same ExecutionResId as the correlation key between them.

Step 1 — Resolve the HIL Fields

In OnProcess, resolve the HIL payload using IHilLabelResolver:

// Inject IHilLabelResolver into your executor constructor
var hilFields = await _hilLabelResolver.ResolveAllAsync(
    nodeExecutionContext,
    cancellationToken);

// hilFields is IReadOnlyList<ResolvedHilField>
// Each entry has:
//   .FieldKey        — the config field name
//   .Label           — human-readable label (may be runtime-resolved)
//   .Description     — additional context
//   .CurrentValue    — the field's current value (object)
//   .DisplayMode     — ReadableContext | ReadableMasked | Concealed
//   .InputMode       — Locked | EditableOptional | RequiredFromHuman | PrefilledEditable
//   .WasEvaluated    — true if label was a dynamic expression

Step 2 — Apply Display and Input Rules

Before formatting for the channel, apply the policy rules to each field:

foreach (var field in hilFields)
{
    switch (field.DisplayMode)
    {
        case HilDisplayMode.ReadableContext:
            // Show the value as-is
            break;
        case HilDisplayMode.ReadableMasked:
            // Render value as "••••••••" — never expose the actual value
            break;
        case HilDisplayMode.Concealed:
            // Skip this field entirely — do not render it
            continue;
    }

    bool isEditable = field.InputMode is
        HilInputMode.EditableOptional or
        HilInputMode.RequiredFromHuman or
        HilInputMode.PrefilledEditable;

    bool isRequired = field.InputMode == HilInputMode.RequiredFromHuman;

    // Format accordingly for your channel
}

Step 3 — Embed the ExecutionResId

Get the ExecutionResId from the execution context and embed it in the outgoing message payload. The exact mechanism depends on the channel.

string resId = nodeExecutionContext
    .ElementExecutionContext
    .ExecutionContext
    .ExecutionResId;

Step 4 — Send and Suspend

Send the formatted message via the channel's API, then return the "waiting" port key. Do this in your OnProcess implementation:

protected override async Task<NodeExecutionResult> OnProcess(
    NodeExecutionContext context,
    CancellationToken cancellationToken)
{
    var hilFields = await _hilLabelResolver.ResolveAllAsync(context, cancellationToken);
    var message   = BuildChannelMessage(hilFields, resId);  // your formatter

    await _channelClient.SendMessageAsync(recipientId, message, cancellationToken);

    // Return "waiting" — engine serializes memory and suspends
    return NodeExecutionResult.Suspend("waiting");
}

Step 5 — The Webhook Handler

This is a separate controller endpoint that the channel calls when the human responds. The handler must:

// Example: verify HMAC signature from channel header
if (!_signatureValidator.Validate(request))
    return Unauthorized();

string resId = ExtractResId(payload); // your strategy

var responseData = new Dictionary<string, object>
{
    ["approved"]       = payload.Action == "approve",
    ["reviewerNotes"]  = payload.InputValues["notes"] ?? ""
};

await _continuationOrchestrator.ContinueAsync(
    executionResId:    resId,
    responseData:      responseData,
    cancellationToken: ct);

return Ok(); // acknowledge to the channel — important!

// Fast-ack pattern for channels with 3-second timeout
_ = Task.Run(() => _continuationOrchestrator.ContinueAsync(resId, data, CancellationToken.None));
return Ok();

Channel Node Checklist