Matrix Field Beta
Matrix fields are for operational review grids: access reviews, skill assignments, permissions, RACI tables, device approvals, and other row-by-column workflows.
Production Limits
The beta guardrails are 250 rows, 100 columns, and 25,000 rendered cells. FormNode warns before those limits and blocks matrices that exceed them so public forms fail clearly instead of becoming slow or unreliable.
Field Config
{
"id": "access_matrix",
"type": "matrix",
"name": "access_matrix",
"label": "Access decisions",
"required": true,
"initialValueWebhookUrl": "https://automation.example.com/current-access",
"matrixConfig": {
"rowAxis": {
"label": "Users",
"sourceType": "dynamic",
"dataSourceType": "custom",
"customWebhookUrl": "https://automation.example.com/users",
"valueKey": "value",
"labelKey": "label",
"groupKey": "department"
},
"columnAxis": {
"label": "Access groups",
"sourceType": "dynamic",
"dataSourceType": "custom",
"customWebhookUrl": "https://automation.example.com/groups",
"valueKey": "value",
"labelKey": "label"
},
"cellType": "singleSelect",
"cellOptions": [
{ "label": "Keep access", "value": "Keep" },
{ "label": "Remove access", "value": "Remove" },
{ "label": "Needs review", "value": "Review" }
],
"submissionMode": "full",
"layoutWidth": "full"
}
}Initial Values
Current values should come from initialValueWebhookUrl. FormNode accepts flat cell arrays, row maps, boolean row-array shorthand, column maps with initialValueKeyAxis="column", dense spreadsheet-style payloads, and common webhook wrappers under data, values,cells, or results.
[
{ "rowId": "user_avery", "columnId": "vpn_users", "value": "Keep" },
{ "rowId": "user_jordan", "columnId": "accounting_share", "value": "Review" }
]Submission Payload
Submit webhooks receive the canonical cell payload plus row-map and diff helpers. Use full mode for simple workflows and diff mode when your automation only wants changed cells.
{
"access_matrix": {
"fieldName": "access_matrix",
"cells": [
{ "rowId": "user_avery", "columnId": "vpn_users", "value": "Keep", "rowLabel": "Avery Patel", "columnLabel": "VPN Users" }
],
"diff": {
"added": [],
"removed": [],
"updated": []
}
},
"access_matrix_rowMap": {
"user_avery": { "vpn_users": "Keep" }
},
"access_matrix_diff": {
"added": [],
"removed": [],
"updated": []
}
}Agent Testing
Agents can call the read-only smoke test endpoint or MCP smoke_test_form tool before handoff. The response includes Matrix row/column counts, selected-cell counts, guardrail warnings, sanitized dynamic errors, and a dry-run payload preview. Smoke tests do not create submissions or dispatch webhooks.