LWC Reference

Complete reference for every event, message, and Apex action available to an LWC running inside a Keelstone Screen Flow.

---

How LWC ↔ Keelstone communication works

LWC components run in Salesforce's domain and cannot call Office APIs directly. Keelstone bridges them through two channels:

postMessage — For real-time, synchronous document operations (read range, write data, insert file). Your LWC calls window.parent.postMessage(payload, '*') and the Keelstone taskpane executes the Office API call.

Apex Invocable Actions — For all other operations (document generation, SOQL queries, server-side PDF/chart/presentation creation). These are added to your Screen Flow as action elements. The flow passes them KeelstoneSessionId from the conversation variable.

LWC in Screen Flow
    │
    ├─ window.parent.postMessage({type:'KEELSTONE_WRITE', ...})
    │          ↓
    │   Keelstone taskpane → Excel.run() / Word API
    │          ↓
    │   window.postMessage({type:'KEELSTONE_WRITE_RESULT', ...})   ← LWC receives
    │
    └─ Flow Action: KS_WriteData (keelstoneSessionId, dataJson, target)
               ↓
       Apex → POST app.keelstone.dev/api/excel/write
               ↓
       Server → socket.io → taskpane → Excel.run()

---

1 — Events your LWC can send to Keelstone

Send via window.parent.postMessage(payload, '*') from your LWC. The taskpane processes these synchronously. Listen for the response with window.addEventListener('message', handler).

---

KEELSTONE_INSERT

Inserts a base64-encoded .xlsx file as a new sheet in the workbook.

Send:

window.parent.postMessage({
    type:     'KEELSTONE_INSERT',
    base64:   '<base64-encoded xlsx>',  // required
    filename: 'Report.xlsx'             // optional, used as sheet name hint
}, '*');

No response event — fire and forget.

---

KEELSTONE_WRITE

Writes a 2D array to a range. Optionally creates an Excel Table and named range.

Send:

window.parent.postMessage({
    type:       'KEELSTONE_WRITE',
    data:       [['Name', 'Amount'], ['Acme', 50000]],  // required — 2D array, row 0 = headers
    target:     'A1',                                    // optional — cell address or named range
    namedRange: true                                     // optional — create named range (default true)
}, '*');

Response: KEELSTONE_WRITE_RESULT

{
    type:      'KEELSTONE_WRITE_RESULT',
    tableName: 'KS_Opportunities',  // null if namedRange was false
    address:   'A1:B3',
    rowCount:  2                    // excludes header row
}

---

KEELSTONE_QUERY

Runs a SOQL query server-side and writes results to a range. Relationship fields (Account.Name) are automatically flattened to dot-notation column headers.

Send:

window.parent.postMessage({
    type:           'KEELSTONE_QUERY',
    soql:           'SELECT Name, Account.Name, Amount FROM Opportunity WHERE StageName = \'Closed Won\'',  // required
    target:         'A1',    // optional
    includeHeaders: true     // optional, default true
}, '*');

Response: KEELSTONE_QUERY_RESULT

{
    type:     'KEELSTONE_QUERY_RESULT',
    address:  'A1:C10',
    rowCount: 9
}

---

KEELSTONE_GET_RANGE

Requests the current selection address and values.

Send:

window.parent.postMessage({ type: 'KEELSTONE_GET_RANGE' }, '*');

Response: KEELSTONE_RANGE_RESPONSE

{
    type:    'KEELSTONE_RANGE_RESPONSE',
    address: 'Sheet1!B2:D5',
    values:  [['Q1', 100], ['Q2', 200]]  // 2D array of cell values
}

---

KEELSTONE_SAVE_TABLES

Reads all Excel Tables on the active sheet and POSTs their data to /api/data/save.

Send:

window.parent.postMessage({ type: 'KEELSTONE_SAVE_TABLES' }, '*');

Response: KEELSTONE_SAVE_RESULT

{
    type:   'KEELSTONE_SAVE_RESULT',
    saved:  42,
    errors: []
}

---

2 — Events your LWC receives from Keelstone

These arrive automatically — no configuration required. Listen with window.addEventListener('message', handler).

---

KS_OFFICE_EVENT

Real-time document events forwarded by the Keelstone taskpane. Debounced at 250 ms.

{
    type:      'KS_OFFICE_EVENT',
    eventType: '<see table below>',
    data:      { /* event-specific payload */ }
}

eventType	App	Fires when	data shape
excel:selectionChanged	Excel	User selects a range	{ address: "Sheet1!A1:B3", values: [[...]] }
excel:changed	Excel	A cell value changes	{ address: "A1", worksheetId: "Sheet1" }
excel:sheetActivated	Excel	User switches sheets	{ worksheetId: "Sheet1" }
word:selectionChanged	Word	Cursor moves or selection changes	{ selectedText: "..." }
ppt:selectionChanged	PowerPoint	User selects a slide	{ slides: [{ id, index, title }] }

How events reach a dialog-launched flow:

Taskpane emits ks:office-event on socket
        ↓
Relay server forwards to the dialog socket for the same session
        ↓
flow-host.html converts to window.postMessage({ type: 'KS_OFFICE_EVENT', ... })
        ↓
Your LWC receives it via window.addEventListener('message')

For flows launched in the taskpane itself (Launch Target = Taskpane), events arrive directly without the relay.

---

Response events

Responses to messages you sent (section 1 above). Arrive on the same message listener.

type	Triggered by	Payload
KEELSTONE_WRITE_RESULT	KEELSTONE_WRITE	{ tableName, address, rowCount }
KEELSTONE_RANGE_RESPONSE	KEELSTONE_GET_RANGE	{ address, values }
KEELSTONE_QUERY_RESULT	KEELSTONE_QUERY	{ address, rowCount }
KEELSTONE_SAVE_RESULT	KEELSTONE_SAVE_TABLES	{ saved, errors }

---

Listening — complete LWC pattern

// myComponent.js
connectedCallback() {
    this._handler = this._onMessage.bind(this);
    window.addEventListener('message', this._handler);
}

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

_onMessage(event) {
    const msg = event.data;
    if (!msg?.type) return;

    // Office events (arrive automatically)
    if (msg.type === 'KS_OFFICE_EVENT') {
        const { eventType, data } = msg;
        if (eventType === 'excel:selectionChanged') {
            this.selectedRange  = data.address;
            this.selectedValues = data.values;
        }
        if (eventType === 'word:selectionChanged') {
            this.selectedText = data.selectedText;
        }
        if (eventType === 'excel:sheetActivated') {
            this.activeSheet = data.worksheetId;
        }
        return;
    }

    // Responses to messages you sent
    switch (msg.type) {
        case 'KEELSTONE_RANGE_RESPONSE':
            this.activeRange = msg.address;
            break;
        case 'KEELSTONE_WRITE_RESULT':
            this.tableName   = msg.tableName;
            this.recordCount = msg.rowCount;
            break;
        case 'KEELSTONE_QUERY_RESULT':
            this.queryAddress = msg.address;
            break;
        case 'KEELSTONE_SAVE_RESULT':
            this.savedCount = msg.saved;
            break;
    }
}

---

3 — Keelstone Apex Actions

All Keelstone actions are @InvocableMethod classes. Add them to your Screen Flow as Action elements. Each action needs a KeelstoneSessionId input (wired to the {!KeelstoneSessionId} conversation variable) unless marked otherwise.

All results include success (Boolean) and either resultJson (String) or dedicated output variables. When success is false, check errorMessage.

---

Excel — Reading

KS: Get Range

Returns the current selection address and values.

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓	Active session ID
resultJson	Output	String	—	{ address, values }
success	Output	Boolean	—

---

Excel — Writing

KS: Write Data to Excel

Writes a 2D JSON array to a range.

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
dataJson	Input	String	✓	2D array as JSON, e.g. [["Name","Amount"],["Acme",50000]]
target	Input	String		Target cell or named range, e.g. "A1"
namedRange	Input	Boolean		Create a named range for the written data (default true)
resultJson	Output	String	—	{ address, tableName, rowCount }
success	Output	Boolean	—

KS: Query Salesforce and Write to Excel

Runs SOQL server-side and writes results to a range. Relationship fields are flattened to Account.Name column headers automatically.

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
soql	Input	String	✓	SOQL query
target	Input	String		Target cell or named range
includeHeaders	Input	Boolean		Write column headers as first row (default true)
resultJson	Output	String	—	{ address, rowCount }
success	Output	Boolean	—

---

Excel — Charts

KS: Add Excel Chart from Range

Creates a chart from an existing data range in the workbook.

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
dataRange	Input	String	✓	A1 notation, e.g. "A1:C5"
sheetName	Input	String		Sheet containing the range (default: active sheet)
chartType	Input	String		ColumnClustered, Line, Pie, BarClustered, Area, Scatter (default ColumnClustered)
title	Input	String		Chart title
position	Input	String		Top-left cell for chart placement, e.g. "E2"
xAxisTitle	Input	String
yAxisTitle	Input	String
chartName	Input	String		Name for the chart object
showLegend	Input	Boolean		Default true
showDataLabels	Input	Boolean		Default false
resultJson	Output	String	—	{ chartName }
success	Output	Boolean	—

KS: Add Excel Chart from Data

Creates a chart from inline data arrays (no existing range needed).

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
labels	Input	String	✓	JSON array of category labels, e.g. '["Q1","Q2","Q3","Q4"]'
series	Input	String	✓	JSON array of series, e.g. '[{"name":"Revenue","values":[100,200,150,300]}]'
sheetName	Input	String	✓	Sheet to write data and chart to
chartType	Input	String		See above (default ColumnClustered)
title	Input	String
dataTarget	Input	String		Cell where data should be written, e.g. "A1"
chartPosition	Input	String		Cell for chart placement
xAxisTitle	Input	String
yAxisTitle	Input	String
showLegend	Input	Boolean		Default true
showDataLabels	Input	Boolean		Default false
chartName	Input	String
resultJson	Output	String	—	{ chartName, dataRange }
success	Output	Boolean	—

KS: List Excel Charts

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
resultJson	Output	String	—	{ charts: [{ name, sheetName }] }
success	Output	Boolean	—

KS: Delete Excel Chart

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
chartName	Input	String	✓	Name returned by Add Chart
sheetName	Input	String
resultJson	Output	String	—	{ ok: true }
success	Output	Boolean	—

---

Excel — Comments

KS: Get Excel Cell Comments

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
address	Input	String		Cell ("B3"), range ("A1:D10"), or omit for all workbook comments
resultJson	Output	String	—	{ comments: [{ id, author, authorEmail, text, created, resolved, replies: [] }] }
success	Output	Boolean	—

KS: Add Excel Cell Comment

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
address	Input	String	✓	Target cell, e.g. "B3"
text	Input	String	✓	Comment body
resultJson	Output	String	—	{ id, author, created }
success	Output	Boolean	—

KS: Reply to Excel Cell Comment

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
commentId	Input	String	✓	ID from Get Cell Comments
text	Input	String	✓
resultJson	Output	String	—	{ id, author, created }
success	Output	Boolean	—

KS: Resolve Excel Cell Comment

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
commentId	Input	String	✓
resolved	Input	Boolean	✓	true to resolve, false to reopen
resultJson	Output	String	—	{ ok, resolved }
success	Output	Boolean	—

KS: Delete Excel Cell Comment

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
commentId	Input	String	✓
resultJson	Output	String	—	{ ok: true }
success	Output	Boolean	—

---

Excel/Word — Document Properties

Document properties are key/value strings stored inside the file. Keelstone uses _ks_doc_id and _ks_template_key internally — those keys are reserved and cannot be read or written by these actions.

KS: Get Document Property

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
key	Input	String	✓	Property key
resultJson	Output	String	—	{ key, value }
success	Output	Boolean	—

KS: Set Document Property

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
key	Input	String	✓	Property key (reserved keys _ks_doc_id, _ks_template_key are blocked)
value	Input	String	✓	Property value
resultJson	Output	String	—	{ ok: true }
success	Output	Boolean	—

KS: Get Document Settings

Returns all non-reserved document properties as a JSON object. Use this to read any custom metadata stored in the document by previous flow runs.

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
documentType	Input	String		"Word" or "Excel" (default "Word")
settingsJson	Output	String	—	JSON object of all non-internal properties, e.g. { recordId: "001...", status: "draft" }
success	Output	Boolean	—

---

Word — Reading

KS: Get Word Document Text

Returns the full body text of the open Word document.

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
resultJson	Output	String	—	{ text: "Full document body..." }
success	Output	Boolean	—

KS: Get Word Selection Comments

Returns comments anchored to the current cursor selection.

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
resultJson	Output	String	—	{ comments: [{ id, author, text, created, resolved }] }
success	Output	Boolean	—

---

Word — Writing

KS: Insert at Cursor (Word)

Inserts content at the current cursor position.

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
content	Input	String	✓	Text, HTML, or OOXML to insert
contentType	Input	String		"text" (default), "html", or "ooxml"
resultJson	Output	String	—	{ ok: true }
success	Output	Boolean	—

KS: Update Word Content Control

Replaces the text inside a tagged Content Control.

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
tag	Input	String	✓	Content Control tag, e.g. "SF_Indemnification_Clause"
text	Input	String	✓	Replacement text
resultJson	Output	String	—	{ ok: true }
success	Output	Boolean	—

---

Word — Comments

KS: Add Word Comment

Adds a comment anchored to the current selection.

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
text	Input	String	✓	Comment body
resultJson	Output	String	—	{ id, author, created }
success	Output	Boolean	—

KS: Reply to Word Comment

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
commentId	Input	String	✓
text	Input	String	✓
resultJson	Output	String	—	{ id, author, created }
success	Output	Boolean	—

KS: Resolve Word Comment

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
commentId	Input	String	✓
resolved	Input	Boolean	✓	true to resolve, false to reopen
resultJson	Output	String	—
success	Output	Boolean	—

KS: Delete Word Comment

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
commentId	Input	String	✓
resultJson	Output	String	—	{ ok: true }
success	Output	Boolean	—

---

Word — Keywords

KS: Scan Keywords

Scans the open Word document for a list of keywords and returns their positions.

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
keywords	Input	List<String>	✓	Keywords to search for
resultJson	Output	String	—	{ matches: [{ keyword, count, paragraphIndexes }] }
success	Output	Boolean	—

---

PowerPoint

KS: Get PowerPoint Slide Count

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
resultJson	Output	String	—	{ count: 5 }
success	Output	Boolean	—

KS: Get PowerPoint Shapes

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
slideIndex	Input	Integer		0-based slide index (default 0)
resultJson	Output	String	—	{ shapes: [{ id, name, type, left, top, width, height }] }
success	Output	Boolean	—

KS: Add PowerPoint Slide

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
resultJson	Output	String	—	{ index }
success	Output	Boolean	—

KS: Delete PowerPoint Slide

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
slideIndex	Input	Integer	✓	0-based index
resultJson	Output	String	—	{ ok: true }
success	Output	Boolean	—

KS: Add PowerPoint Text Box

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
text	Input	String	✓	Text content
slideIndex	Input	Integer		Default 0
left	Input	Decimal		Left position in inches (default 1)
top	Input	Decimal		Top position in inches (default 1)
width	Input	Decimal		Width in inches (default 8)
height	Input	Decimal		Height in inches (default 2)
resultJson	Output	String	—	{ id, name }
success	Output	Boolean	—

KS: Add PowerPoint Image

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
base64	Input	String	✓	Base64-encoded image (PNG, JPG, GIF, BMP)
slideIndex	Input	Integer		Default 0
left	Input	Decimal		Default 1 inch
top	Input	Decimal		Default 1 inch
width	Input	Decimal		Default 3 inches
height	Input	Decimal		Default 3 inches
resultJson	Output	String	—	{ ok: true }
success	Output	Boolean	—

KS: Get PowerPoint Slide Text

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
slideIndex	Input	Integer		Default 0
resultJson	Output	String	—	{ shapes: [{ name, text }] }
success	Output	Boolean	—

KS: Set PowerPoint Shape Text

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
slideIndex	Input	Integer		Default 0
shapeName	Input	String	✓	Shape name from Get Shapes
text	Input	String	✓
resultJson	Output	String	—	{ ok: true }
success	Output	Boolean	—

KS: Delete PowerPoint Shape

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
slideIndex	Input	Integer		Default 0
shapeName	Input	String	✓
resultJson	Output	String	—	{ ok: true }
success	Output	Boolean	—

KS: Export PowerPoint Slide

Exports a single slide as a .pptx file. Requires PowerPoint API set 1.8 (Microsoft 365 desktop, June 2024+).

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
slideIndex	Input	Integer		0-based index
resultJson	Output	String	—	{ base64 } — base64 .pptx
success	Output	Boolean	—

KS: Get PowerPoint Slide Image

Renders a slide to a PNG image.

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
slideIndex	Input	Integer		Default 0
width	Input	Integer		Image width in pixels
height	Input	Integer		Image height in pixels
resultJson	Output	String	—	{ base64 } — base64 PNG
success	Output	Boolean	—

KS: Add PowerPoint Slide Tag

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
slideIndex	Input	Integer		Default 0
key	Input	String	✓	Tag key
value	Input	String	✓	Tag value
resultJson	Output	String	—	{ ok: true }
success	Output	Boolean	—

KS: Get PowerPoint Slide Tags

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
slideIndex	Input	Integer		Default 0
resultJson	Output	String	—	{ tags: { key: value, ... } }
success	Output	Boolean	—

KS: Insert PowerPoint Slides

Inserts slides from a base64 .pptx file into the current presentation.

Variable	Direction	Type	Required	Description
keelstoneSessionId	Input	String	✓
base64	Input	String	✓	Base64 .pptx file
sourceSlideIds	Input	List<String>		Specific slide IDs to insert; omit for all slides
resultJson	Output	String	—	{ ok: true }
success	Output	Boolean	—

---

Document Generation — No taskpane required

These actions call the Keelstone server directly from Apex. The Office add-in does not need to be open for them to run. Useful for automating document creation from record-triggered flows or scheduled flows.

KS: Generate Document from Template

Merges a Word or Excel template with Salesforce record data and saves the output to Salesforce Files.

Variable	Direction	Type	Required	Description
templateKey	Input	String	✓	Template_Key__c slug from a Keelstone_Template__c record — portable across orgs
contextJson	Input	String		Merge context as a JSON string. Build with KS: Build Merge Context + KS: Add Table, a custom Apex class, or an LWC.
mergeData	Input	String		Extra merge values as JSON — merged on top of contextJson at highest priority, e.g. '{"today":"April 14, 2026"}'
filename	Input	String		Output filename (extension determines format)
linkedEntityId	Input	String		Save the file linked to this record ID
externalLink	Input	Boolean		Generate a public download URL
contentDocumentId	Output	String	—	ContentDocumentId of the generated file
documentUrl	Output	String	—	Public URL (when externalLink is true)
templateKey	Output	String	—	Echo of input — useful for chaining or storing in the document
success	Output	Boolean	—
errorMessage	Output	String	—

Merge priority (lowest → highest): contextJson → mergeData JSON

KS: Build Merge Context

Serialises a primary SObject record to a context JSON string for passing to KS: Add Table and then KS: Generate Document.

Variable	Direction	Type	Required	Description
record	Input	SObject	✓
contextJson	Output	String	—	JSON representation of the record
success	Output	Boolean	—
errorMessage	Output	String	—

KS: Add Table to Context

Adds a related record collection to an existing context JSON string. Chain multiple calls to add multiple tables.

Variable	Direction	Type	Required	Description
contextJson	Input	String	✓	Context from KS: Build Merge Context or a prior KS: Add Table
records	Input	List<SObject>	✓	Related records to add
tableName	Input	String		Key name for this table in the context (default "items")
contextJson	Output	String	—	Updated context JSON
success	Output	Boolean	—
errorMessage	Output	String	—

KS: Fill PDF Form

Fills an AcroForm PDF template with Salesforce record field values and saves to Files.

Variable	Direction	Type	Required	Description
templateId	Input	String	✓	ContentDocumentId of the PDF template
record	Input	SObject	✓	Record whose API field names match the PDF form fields
filename	Input	String
linkedEntityId	Input	String
externalLink	Input	Boolean
flatten	Input	Boolean		Flatten form fields after filling (default false)
contentDocumentId	Output	String	—
documentUrl	Output	String	—
success	Output	Boolean	—
errorMessage	Output	String	—

KS: Generate PDF

Generates a PDF from a pdfmake document definition.

Variable	Direction	Type	Required	Description
docDefinitionJson	Input	String	✓	pdfmake docDefinition object as JSON
resultJson	Output	String	—	{ base64, mimeType: "application/pdf" }
success	Output	Boolean	—

KS: Generate PowerPoint Presentation

Generates a .pptx file from a JSON slide definition array. No PowerPoint add-in required.

Variable	Direction	Type	Required	Description
slidesJson	Input	String	✓	JSON array of slide objects — each can have title, body, bullets[], imageBase64, backgroundColor
title	Input	String		Presentation metadata title
layout	Input	String		pptxgenjs layout name, e.g. "LAYOUT_WIDE" (default) or "LAYOUT_16x9"
resultJson	Output	String	—	{ base64, mimeType: "application/vnd.openxmlformats-officedocument.presentationml.presentation" }
success	Output	Boolean	—

KS: Generate Chart Image

Generates a Chart.js chart as a PNG image. No Office add-in required.

Variable	Direction	Type	Required	Description
labelsJson	Input	String	✓	JSON array of category labels, e.g. '["Q1","Q2","Q3","Q4"]'
datasetsJson	Input	String	✓	JSON array of datasets, e.g. '[{"label":"Revenue","data":[100,200,150,300]}]'
chartType	Input	String		bar, line, pie, doughnut, radar, polarArea (default bar)
title	Input	String		Chart title
width	Input	Integer		Pixels (default 800)
height	Input	Integer		Pixels (default 500)
resultJson	Output	String	—	{ base64, mimeType: "image/png" }
success	Output	Boolean	—