KSWord Reference

KSWord is the class to extend when your LWC component needs to read or write content in Microsoft Word. All methods are async and return when the Word operation completes.

Requirements:

• Keelstone Pro plan
• Keelstone Word Add-in open and connected in Microsoft Word

Import

import { KSWord } from 'kstone/api';

---

ksGenerate(templateBase64, data, filename)

Merges data into a Word template and inserts the result into the open Word document.

async ksGenerate(templateBase64, data, filename) → Promise<string>

Parameters:

Param	Type	Description
templateBase64	string	Base64-encoded .docx template file
data	object	Merge data matching the template's placeholders
filename	string	Filename for the inserted document

Returns: Base64 string of the merged document.

Example:

import getTemplate from '@salesforce/apex/WordTemplateController.getTemplate';

const templateBase64 = await getTemplate({ contentDocumentId: this.templateId });
await this.ksGenerate(templateBase64, { account: { Name: 'Acme', Industry: 'Tech' } }, 'Contract.docx');

---

ksInsertContentControl(tag, text, title?)

Wraps the current Word selection in a Content Control with the specified tag.

async ksInsertContentControl(tag, text, title?) → Promise<{ ok: true }>

Content Controls are reusable named regions in a Word document. Use tags to identify and update them later.

---

ksGetContentControl(tag)

Reads the text of a Content Control by its tag.

async ksGetContentControl(tag) → Promise<string | null>

Returns null if no Content Control with that tag exists.

---

ksUpdateContentControl(tag, text)

Replaces the text inside a Content Control identified by tag.

async ksUpdateContentControl(tag, text) → Promise<{ ok: true }>

Example:

await this.ksUpdateContentControl('contract-status', 'Executed');

---

ksInsertParagraph(text, style?, insertLocation?)

Inserts a paragraph at the specified location in the document.

async ksInsertParagraph(text, style?, insertLocation = 'End') → Promise<{ ok: true }>

Parameters:

Param	Type	Default	Description
text	string	required	Paragraph text
style	string	'Normal'	Word paragraph style name
insertLocation	string	'End'	'Start' | 'End' | 'Before' | 'After'

---

ksInsertTable(headers, rows)

Inserts a table with a header row followed by data rows.

async ksInsertTable(headers, rows) → Promise<{ ok: true }>

Parameters:

Param	Type	Description
headers	string[]	Column header names
rows	string[][]	2D array of data rows

Example:

await this.ksInsertTable(
    ['Account', 'Amount', 'Stage'],
    [['Acme', '$50,000', 'Closed Won'], ['Globex', '$30,000', 'Proposal']]
);

---

ksGetText()

Returns the full plain text of the document body.

async ksGetText() → Promise<string>

---

ksGetComments()

Returns all document comments with their full reply thread.

async ksGetComments() → Promise<Comment[]>

Returns:

[{
  id: 'comment-id',
  text: 'Review this clause',
  authorName: 'Matthew',
  resolved: false,
  replies: [{ id, text, authorName }]
}]

---

ksGetSelectionComments()

Returns only comments anchored within the current selection.

async ksGetSelectionComments() → Promise<Comment[]>

Same shape as ksGetComments().

---

ksAddComment(text)

Inserts a comment anchored to the current selection.

async ksAddComment(text) → Promise<{ id: string, ok: true }>

---

ksReplyToComment(commentId, text)

Adds a reply to an existing comment.

async ksReplyToComment(commentId, text) → Promise<{ ok: true }>

---

ksResolveComment(commentId, resolved?)

Resolves or reopens a comment.

async ksResolveComment(commentId, resolved = true) → Promise<{ ok: true }>

---

ksDeleteComment(commentId)

Deletes a comment from the document.

async ksDeleteComment(commentId) → Promise<{ ok: true }>

---

ksScanForKeywords(keywords)

Searches the document for each keyword and returns match counts for keywords that appear at least once.

async ksScanForKeywords(keywords) → Promise<{ keyword: string, count: number }[]>

Example:

const matches = await this.ksScanForKeywords(['liability', 'indemnification', 'termination']);
// [{ keyword: 'liability', count: 3 }, { keyword: 'termination', count: 1 }]
// (keywords with count=0 are omitted)

---

Minimal example

import { KSWord } from 'kstone/api';
import { api, track } from 'lwc';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';
import getTemplate from '@salesforce/apex/WordTemplateController.getTemplate';

export default class MyContractBuilder extends KSWord {
    @api keelstoneSessionId;
    @api recordId;
    @track status = '';

    async handleGenerate() {
        try {
            const templateBase64 = await getTemplate({ contentDocumentId: this.templateId });
            await this.ksGenerate(templateBase64, { recordId: this.recordId }, 'Contract.docx');
            this.status = 'Document inserted into Word.';
        } catch (err) {
            this.dispatchEvent(new ShowToastEvent({ title: 'Error', message: err.message, variant: 'error' }));
        }
    }
}

---

Flow Wiring

Wire KeelstoneSessionId from the flow to your component's keelstoneSessionId property. See Flow Wiring.