UI Integration

Workflows connect Brezel layouts to backend behavior. A UI-triggered workflow should make the user action obvious, keep feedback immediate, and return only data the client needs.

Resource table buttons

Resource tables can trigger workflow events from row actions or toolbar actions.

{
    "identifier": "markTaskDone",
    "icon": "mdi:check",
    "type": "primary",
    "event": {
        "action": "workflow",
        "module": "tasks",
        "event": "markTaskDone",
        "data": {
            "status": "done"
        }
    }
}

The workflow should register a matching webhook event and decide whether to refresh the current prototype or return a response.

Standalone buttons

Use the buttons layout component for commands that belong in a detail view or custom panel.

{
    "type": "buttons",
    "options": {
        "buttons": [
            {
                "identifier": "previewReport",
                "icon": "mdi:file-eye-outline",
                "label": "Preview report",
                "events": {
                    "on_click": ["previewReport"]
                }
            }
        ]
    }
}

Use on_click for UI-local events. Use a workflow action event when the button should call a module-level command.

Field events

Field events are best for quick feedback: setting dependent fields, filtering options, or validating a small section of the form.

{
    "identifier": "customer",
    "type": "select",
    "options": {
        "references": "customers",
        "events": {
            "on_change": ["setProjectCustomerDefaults"]
        }
    }
}

Keep field-event workflows synchronous and fast. They often run while users are typing or editing a form.

Modals

Use action/modal when a command needs confirmation or additional input.

{
    "name": "confirmArchive",
    "type": "action/modal",
    "options": {
        "type": "confirm",
        "layout": "tasks.archive_modal",
        "checkpoint": true
    },
    "set": {
        "archiveData": "confirm:"
    },
    "to": {
        "confirm": {
            "archiveTask": ["default"]
        }
    }
}

The modal is part of the active UI request, so modal workflows must stay synchronous until the modal interaction is complete.

Client responses

Use the response action that matches the UI need.

Element	Use for
action/response	Return JSON or raw data to the caller.
action/set	Set values, visibility, or options in the active client form.
action/redirect	Move the user to another module or resource view.
action/refresh	Refresh the current page after a server-side change.
action/viewFile	Show a generated file in the browser.
action/downloadFile	Send a generated file as a download.
action/notify	Show toast, mail, or SMS-style notifications.

Avoid mixing too many client responses in one path. A workflow branch should have one clear UI result.

UI integration checklist

• The button label and workflow identifier describe the same command.
• The workflow receives only the row, resource, or input data it needs.
• Field events are synchronous and lightweight.
• Long work starts an async job and gives immediate feedback.
• Notifications describe the outcome without exposing internal service details.