# Handlers ### Overview A **Handler** is a configuration that defines what happens when an event fires on a UI element or a global board or form event occurs. Handlers are how Flexi Kanban connects user interactions and system events to operations — navigation, automation, filter manipulation, form actions, and more. The system model is: ``` Event → Handler → Action(s) ``` When an event fires, the Handler executes its primary action. It can optionally chain additional actions that run on success or failure of that primary action. *** ### Where Handlers Are Configured Handlers are attached to six different surfaces across the Flexi Kanban app: | Surface | Where Configured | | ----------------------- | ----------------------------------------- | | Card Elements | Kanban Studio — Card configuration | | Custom Buttons | Kanban Studio — Board-level configuration | | Board global events | Kanban Studio — Board Events section | | Form elements / buttons | Form Studio | | Form global events | Form Studio — Form Events section | | Card movement rules | Kanban Studio — Automation section | Card movement rules use the same Handler type model but do **not** support `onSuccess` / `onFailure` chaining. All other surfaces support the full Handler model. *** ### Handler Model Every Handler — except on card movement rules — follows the same structure: json ```json { "type": "", "config": { }, "onSuccess": [ ], "onFailure": [ ] } ``` | Field | Required | Description | | ----------- | -------- | ----------------------------------------------------------------------------------------------- | | `type` | Yes | The handler type. Determines what operation executes. See Handler Types. | | `config` | Yes | Type-specific configuration. Parameters vary by type. | | `onSuccess` | No | Array of Actions or Action Groups that execute after the primary action completes successfully. | | `onFailure` | No | Array of Actions or Action Groups that execute if the primary action fails. | For card movement rules, only `type` and `config` apply. `onSuccess` and `onFailure` are not supported. *** ### Handler Types Handler types are organized into five groups: #### Navigation Open forms, pages, records, and external URLs. | Type | What It Does | | ----------------------- | -------------------------------------------------- | | **Form** | Opens a Flexi Kanban Form built in Form Studio | | **Visualforce Page** | Opens a Salesforce Visualforce page | | **URL** | Navigates to any URL | | **Lightning Component** | Opens a Salesforce Lightning Component | | **SObject** | Navigates to a Salesforce record page by record ID | See Navigation Handler Types. #### Automation Execute backend operations defined in Flexi Kanban. | Type | What It Does | | ---------------- | ------------------------------------------------------------------------------------ | | **Action** | Executes a single Flexi Kanban Action | | **Action Group** | Executes a Flexi Kanban Action Group — a sequence of Actions sharing runtime context | See Automation Handler Types. #### Kanban API Interact with the board's filter system, dialpad, email composer, and note composer. | Type | What It Does | | ------------------------------------- | -------------------------------------------------------------------------- | | **Open CTI – Dial** | Opens the Salesforce dialpad and initiates a call | | **Send Email** | Opens the Salesforce dockable email composer | | **Create Note** | Opens the Salesforce Content Note composer | | **Apply Filters Template** | Loads a Filter Template into the Filter Panel and applies it automatically | | **Apply Filters Template Conditions** | Loads a Filter Template and applies it as hidden conditions | | **Clear Hidden Conditions** | Removes all hidden conditions set by Kanban API handlers | | **Select Filters Template** | Loads a Filter Template into the Filter Panel without applying | | **Merge Filters Template** | Merges a Filter Template into the existing Filter Panel state | | **Add Filter Condition** | Appends a single filter condition to the Filter Panel | | **Add Labels Filter Condition** | Adds a label value to the labels filter in the Filter Panel | | **Apply Filter Conditions** | Programmatically triggers Apply on the Filter Panel | | **Clear Filter Conditions** | Clears all conditions from the Filter Panel | | **Reset Filter Conditions** | Restores Filter Panel values from the active View | See Kanban API Handler Types. #### Form API Interact with Form Studio operations. | Type | What It Does | | ----------------------- | ---------------------------------------------------- | | **Execute Form Action** | Executes a Flexi Kanban Action defined inside a Form | See Form API Handler Types. #### Other | Type | What It Does | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | **Fire Event** | Dispatches a named event — used for board-to-board communication in Composite Kanban and for form-to-board communication after form submission | See Other Handler Types. *** ### Board Global Events Handlers can be attached to Kanban Board global events in the **Board Events** section of Kanban Studio. All Handler types are available on all events. | Event | When It Fires | | ------------------- | -------------------------------------------------- | | **Before Load** | Before the board loads its data | | **After Load** | After the board has finished loading data | | **View Changed** | When the user switches to a different View | | **Data Changed** | When underlying record data on the board changes | | **Filters Applied** | When filter conditions are applied | | **Filters Cleared** | When filter conditions are cleared | | **Filters Reset** | When filters are reset to the active View defaults | *** ### Form Global Events Handlers can be attached to Form global events in the **Form Events** section of Form Studio. All Handler types are available on all events. | Event | When It Fires | | --------------- | ------------------------------------------ | | **Before Load** | Before the form loads | | **After Load** | After the form has finished loading | | **After Save** | After the form has been saved or submitted | | **Activate** | When the form becomes active | *** ### Execution Order When a Handler fires: 1. The primary action defined by `type` and `config` executes. 2. If it succeeds, any `onSuccess` actions execute in listed order. 3. If it fails, any `onFailure` actions execute instead. `onSuccess` and `onFailure` reference standard Flexi Kanban Actions or Action Groups. The same Action can be reused across multiple Handlers without duplicating configuration. See Actions and Action Groups. *** ### Runtime Context When a Handler fires from a **Card Element**, the runtime context includes the record represented by that card. Actions in the Handler chain can reference that record's fields using merge expressions such as `{Opportunity.StageName}`. When a Handler fires from a **Custom Button** in the Kanban Header, there is no implicit record context. Any record reference must be passed explicitly in the Handler configuration. When a Handler fires from a **Board global event**, the context depends on the event. For example, a View Changed event carries the new view state; a Filters Applied event carries the current filter state. When a Handler fires from a **Form element or Form global event**, the context includes the form's current field values and any Variables defined in the form. *** ### Related Articles * Navigation Handler Types * Automation Handler Types * Kanban API Handler Types * Form API Handler Types * Other Handler Types * Actions and Action Groups * Kanban Studio * Form Studio