Skip to main content

Building Screen Flows

Any Salesforce Screen Flow can be a Keelstone action. This page covers the patterns and requirements for flows that work well in the Keelstone dialog context.

Anatomy of a Keelstone flow​

Screen 1: Data collection
  → accountSearch (or your own components)

Assignment: Prepare merge data

Screen 2: Document generation
  → excelTemplate (or your own LWC that fires KEELSTONE_INSERT)

End

The flow finishes normally. Keelstone's onstatuschange handler detects FINISHED or FINISHED_SCREEN and closes the dialog.

Creating a Keelstone Action record​

Once your flow is deployed:

  1. In your org, go to Keelstone Actions (custom object)
  2. Create a new record with:
    • Label — what the user sees on the tile
    • Action Type — Flow
    • Action Target — the Flow API name
    • Active — checked

Optional settings:

  • Icon — emoji or Unicode character displayed on the tile
  • Order — controls tile sort order within a group
  • Dialog Height / Width — percentage of screen (defaults: 80% × 60%)
  • Launch Target — Dialog (default) or Taskpane

Flow variables​

Input variables (from Keelstone Action record)​

Keelstone launches flows with an empty input list — cmp.startFlow(flowApiName, []). If your flow requires input variables, they must come from within the flow itself (e.g., queried from Salesforce records) or be configured via the action record using custom fields.

Output variables​

Flow output variables are not returned to the taskpane. Use LWC events (KEELSTONE_INSERT, KEELSTONE_WRITE, KEELSTONE_QUERY) to push data to Excel instead.

Screen navigation​

Keelstone dialogs support standard flow navigation — Next, Back, and Finish buttons all work. The dialog closes when the flow finishes, regardless of which screen the user ends on.

Recommended screen settings for document generation screens:

<allowBack>false</allowBack>
<allowFinish>true</allowFinish>
<allowPause>false</allowPause>

Disabling Back prevents users from re-running the generation accidentally. Disabling Pause avoids incomplete flow interviews accumulating in the org.

Using custom LWC components​

Any LWC exposed as lightning__FlowScreen can be used in a Keelstone flow. To communicate with Excel, fire the appropriate KEELSTONE_* event:

// myFlowComponent.js
import { LightningElement, api } from 'lwc';

export default class MyFlowComponent extends LightningElement {
  @api someInputFromFlow;

  connectedCallback() {
    // Example: push data to Excel when the screen loads
    this.pushData();
  }

  pushData() {
    const payload = {
      type: 'KEELSTONE_WRITE',
      data: [['Name', 'Value'], ['Example', this.someInputFromFlow]],
      target: 'A1'
    };
    try { window.parent.postMessage(payload, '*'); } catch (e) {}
    document.dispatchEvent(new CustomEvent('keelstoneinsert', { detail: payload, bubbles: true }));
  }
}
// myFlowComponent.js-meta.xml target
<targets>
  <target>lightning__FlowScreen</target>
</targets>
<targetConfigs>
  <targetConfig targets="lightning__FlowScreen">
    <property name="someInputFromFlow" type="String" label="Input Value" />
  </targetConfig>
</targetConfigs>

Grouping actions​

Actions can be organized into groups using the Keelstone Group object. Groups appear as collapsible sections in the taskpane tile grid. To create a group:

  1. Create a Keelstone Group record (Label, Icon, Order, Description, Active)
  2. On each Keelstone Action record, set the Group lookup

Actions without a group appear ungrouped at the bottom of the tile grid.

Controlling access with Custom Permissions​

To restrict which users see an action, create a Custom Permission and assign it to the Action record's Required Permission field. Users who don't have that permission (via a Permission Set) won't see the tile.

This is the recommended way to build role-based action menus — e.g., show an "Approve Contract" action only to users in the Legal permission set.

Testing your flow​

Before connecting to a Keelstone Action, test your flow in the standard Flow debug interface in Salesforce. Confirm:

  • All screens render correctly
  • Output variables are populated after selection
  • The flow finishes without errors

Then test end-to-end in the Excel taskpane. The system check panel (gear icon in the taskpane footer) logs all events — use it to verify KEELSTONE_INSERT is received.