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 extending KSExcel)

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

KeelstoneSessionId (required)

Every flow that includes a Keelstone LWC component must declare KeelstoneSessionId as a String input variable. Keelstone passes this automatically when launching the flow — you do not need to set it.

<variables>
    <name>KeelstoneSessionId</name>
    <dataType>String</dataType>
    <isCollection>false</isCollection>
    <isInput>true</isInput>
    <isOutput>false</isOutput>
</variables>

Wire it to each LWC component on a screen:

<inputParameters>
    <name>keelstoneSessionId</name>
    <value><elementReference>KeelstoneSessionId</elementReference></value>
</inputParameters>

See Flow Wiring for a complete example.

Other input variables

Beyond KeelstoneSessionId, you can declare any additional input variables your flow needs. Flows launched from a Quick Action on a record page also receive recordId as a standard Salesforce input.

Output variables

Flow output variables are not returned to the taskpane. LWC components push data to Excel directly using kstone/api methods — see Building Custom LWCs.

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, extend KSExcel from kstone/api and call its methods directly — no postMessage or event wiring required.

// myFlowComponent.js
import { KSExcel } from 'kstone/api';
import { api } from 'lwc';

export default class MyFlowComponent extends KSExcel {
    @api keelstoneSessionId;  // required — wired from KeelstoneSessionId flow variable
    @api someInputFromFlow;

    async connectedCallback() {
        await this.ksWrite(
            [['Name', 'Value'], ['Example', this.someInputFromFlow]],
            'A1'
        );
    }
}

<!-- myFlowComponent.js-meta.xml -->
<targets>
  <target>lightning__FlowScreen</target>
</targets>
<targetConfigs>
  <targetConfig targets="lightning__FlowScreen">
    <property name="keelstoneSessionId" type="String" label="Keelstone Session ID" />
    <property name="someInputFromFlow"  type="String" label="Input Value" />
  </targetConfig>
</targetConfigs>

See Building Custom LWCs for the full API reference.

Listening to document events

LWC components inside flows can react to real-time document changes — cell selections, text selection in Word, and slide changes in PowerPoint. These events arrive as window.postMessage with type = 'KS_OFFICE_EVENT':

connectedCallback() {
    this._handler = this._onOfficeEvent.bind(this);
    window.addEventListener('message', this._handler);
}

disconnectedCallback() {
    window.removeEventListener('message', this._handler);
}

_onOfficeEvent(event) {
    if (event.data?.type !== 'KS_OFFICE_EVENT') return;
    const { eventType, data } = event.data;

    if (eventType === 'excel:selectionChanged') {
        this.selectedAddress = data.address;
        this.selectedValues  = data.values;
    }
}

No additional configuration is needed — the taskpane forwards events automatically. See the Events Overview for the full list of event types.

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.

Template-scoped actions

By default, actions appear on all open documents. If you want an action to only appear when a specific template was used to generate the document, link it to a Keelstone_Template__c record via Keelstone_Template_Action__c:

1. Create a Keelstone_Template__c record with the appropriate Template_Key__c
2. On the action record, create a Keelstone_Template_Action__c junction record linking the action to the template

Once any junction record exists on an action, it becomes template-scoped. It only appears in the taskpane when the open document has a matching _ks_template_key custom property (written automatically when KS: Insert Document is used).

Actions with no junction records remain global and always appear.

Controlling access with Custom Permissions

By default, every active Keelstone Action is visible to all users who have the Keelstone_User permission set. Custom Permissions let you restrict individual actions (or entire groups) to specific users — for example, showing a contract approval action only to Legal, or a commission tool only to Finance managers.

How it works

When the taskpane loads, Keelstone checks each action's Required Permission field against the permissions the logged-in Salesforce user actually holds. If the field is blank, the action is visible to everyone. If it contains a Custom Permission API name, the action is hidden from any user who does not have that permission granted via a Permission Set.

The same gate applies to Keelstone Group records — if a group has a Required Permission set, the entire group (and all its actions) is hidden from users who don't have it.

Step 1 — Create a Custom Permission

1. In Salesforce Setup, search for Custom Permissions and open it
2. Click New
3. Fill in:
   • Label — e.g. Keelstone Legal
   • Name — the API name Keelstone will check, e.g. Keelstone_Legal (no spaces, no namespace prefix needed)
   • Description — optional, for your own reference
4. Click Save

Step 2 — Add the permission to a Permission Set

1. Go to Setup → Permission Sets
2. Open the Permission Set you want to grant the permission to (e.g. your Legal_Team permission set, or create a new one)
3. Click Custom Permissions in the left nav
4. Click Edit, find your new permission in the Available list, and move it to the Enabled list
5. Click Save
6. Assign the Permission Set to the appropriate users via Manage Assignments

Step 3 — Set the Required Permission on the Action record

1. Open the Keelstone Action record you want to restrict
2. In the Required Permission field, enter the API name of the Custom Permission exactly as you defined it — e.g. Keelstone_Legal
3. Save the record

The action will now be hidden from any user who does not have Keelstone_Legal granted through one of their Permission Sets. No taskpane restart is needed — the filter runs on every config load.

Gating an entire group

To hide a whole group of actions at once, set the Required Permission field on the Keelstone Group record instead of (or in addition to) individual action records. If the user lacks the group permission, none of the group's actions are shown regardless of individual action permissions.

Example: role-based action menus

Team	Custom Permission	Permission Set	Actions gated
Sales	Keelstone_Sales	Sales Rep	Generate Proposal, Log Call
Legal	Keelstone_Legal	Legal Team	Insert Clause, Approve Contract
Finance	Keelstone_Finance	Finance Manager	Commission Calc, Export Revenue

Each user sees only the tiles relevant to their role. A Sales rep who is also a Finance Manager would see both Sales and Finance tiles.

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) shows the relay log — use it to verify API calls are reaching the taskpane.