Overview

When a user interacts with a widget, the widget fires an event through FormHostProvider. Each event type calls a specific endpoint and sends a JSON payload to your backend.

How It Works

Each section executes a single API endpoint:

Endpoint action	Used by
runFormEvent	Field changes, button clicks, table events, autocomplete
runFormUploadFiles	File upload widget
runFormDeleteFileEvent	File deletion
runFormDownloadFileEvent	File download
runFormGetLinkedFileEvent	File preview
runFormGetLinkedFileMetaEvent	File metadata
runFormGetLinkedFileByChunks	Chunked (large file) download
runFormGetPresignedUrl	Presigned URL for large file preview
runLoadFormEvent	Form definition load

Common Fields

All runFormEvent requests share this base structure. Event-specific fields are noted in each section.

{
  "pluginCode":   "construct",
  "formCode":     "documents",
  "guid":         "550e8400-e29b-41d4-a716-446655440000",
  "projectGuid":  "38I9rEPw1BmxP75XcxgzD5WGOk1",
  "pGuid":        "38I9rEPw1BmxP75XcxgzD5WGOk1",
  "formData":     { "field1": "value1" },
  "widgetsState": null,
  "widgetName":   "WIDGETNAME",
  "widgetValue":  null,
  "widgetEvent":  "eventName",
  "widgetContext": {
    "referer":        "/forms/documents/550e8400",
    "parentWidgetId": null,
    "hasParentForm":  false,
    "originator":     null,
    "parent":         null
  }
}

note

widgetContext is transmitted as a JSON-encoded string on the wire. The values shown above are the deserialized structure.

Your backend identifies the event using widgetName and widgetEvent from the request body.