Widget Data Binding

widgetProps Evaluation

Each key in widgetProps can be a static value or an expression. The executor evaluates all expressions before creating the HIL task, so the widget always receives resolved data:

{
  "widgetProps": {
    "items": "$output.fetchInvoice.lineItems",
    "totalAmount": "$output.fetchInvoice.total",
    "currency": "$output.fetchInvoice.currency ?? 'USD'",
    "budgetLimit": "$output.fetchBudget.remainingBudget",
    "showHistory": "$context.actorId === $output.fetchEmployee.managerId",
    "readOnly": false,
    "theme": "compact"
  }
}

Complex Props

Widget props can include transformed arrays, merged objects, or computed values:

// Transformed array
"items": "$output.fetchInvoice.lineItems.map(item => ({ ...item, budgetCategory: item.category, overBudget: item.amount > 500 }))"

// Merged objects
"config": "{ ...($output.fetchSettings.widgetConfig), readOnly: $json.viewOnly }"

// Computed threshold
"flagThreshold": "$output.fetchPolicy.maxApprovalAmount * 0.8"

Props Schema Validation

Before creating the HIL task, the engine validates the evaluated props against the widget's declared PropsSchema:

// WidgetExecutor validation
var def = _registry.GetWidget(config.WidgetId);
var validationResult = _schemaValidator.Validate(props, def.PropsSchema);
if (!validationResult.IsValid)
{
    return NodeExecutionResult.Fail(new WidgetPropsValidationException(
        $"Widget props invalid: {string.Join(", ", validationResult.Errors)}"));
}