KEELSTONE_SAVE_TABLES

Reads all Excel Tables on the active worksheet and sends their data to the Keelstone server at /api/data/save. The taskpane responds with KEELSTONE_SAVE_RESULT containing the number of records saved and any errors.

This event is the write half of the query builder round-trip: KEELSTONE_WRITE pushes data into Excel as a named Table, and KEELSTONE_SAVE_TABLES pulls it back out and saves it to Salesforce.

note

/api/data/save is currently a stub that echoes the row count. Salesforce upsert is not yet implemented. This documents the intended pattern for when the endpoint is fully built out.

Payload

{
  type: 'KEELSTONE_SAVE_TABLES';
}

No additional fields. The taskpane reads all tables on the active sheet automatically.

What the taskpane does

1. Calls sheet.tables.load('items/name') to enumerate all tables on the active worksheet.
2. For each table, loads the header row values and data body values.
3. POSTs to /api/data/save:

{
  "tables": [
    {
      "tableName": "KS_1714000000",
      "headers": ["Id", "Name", "Phone"],
      "rows": [
        ["001...", "Acme Corp", "555-0101"],
        ["001...", "Globex", "555-0102"]
      ]
    }
  ]
}

4. Posts KEELSTONE_SAVE_RESULT back to the LWC with the server's response.

Response: KEELSTONE_SAVE_RESULT

{
  type: 'KEELSTONE_SAVE_RESULT';
  saved: number;   // number of records successfully saved
  errors: number;  // number of records that failed
}

Example

// LWC: trigger save
handleSaveClick() {
    this.isSaving = true;
    window.parent.postMessage({ type: 'KEELSTONE_SAVE_TABLES' }, '*');
}

// LWC: handle result
_onMessage(event) {
    if (event.data?.type !== 'KEELSTONE_SAVE_RESULT') return;
    const { saved, errors } = event.data;
    this.isSaving = false;

    const message = errors > 0
        ? `${saved} record(s) saved with ${errors} error(s).`
        : `${saved} record(s) saved.`;

    this.dispatchEvent(new ShowToastEvent({
        title:   'Save Complete',
        message,
        variant: errors > 0 ? 'warning' : 'success',
    }));
}

Full round-trip

User runs SOQL query
        ↓
LWC → KEELSTONE_WRITE (namedRange: true)
        ↓
Taskpane writes data → creates Excel Table "KS_1714000000"
        ↓
Taskpane → KEELSTONE_WRITE_RESULT { tableName, rowCount }
        ↓
LWC shows "Save to Salesforce" button
        ↓
User clicks Save
        ↓
LWC → KEELSTONE_SAVE_TABLES
        ↓
Taskpane reads all tables → POST /api/data/save
        ↓
Taskpane → KEELSTONE_SAVE_RESULT { saved: 3, errors: 0 }
        ↓
LWC fires toast: "3 records saved."

Notes

• All tables on the active worksheet are included, not just the most recently written one. If the user has written multiple queries to different ranges on the same sheet, all will be sent.
• Tables created outside of KEELSTONE_WRITE (e.g., manually by the user) are also included if they exist on the active sheet.
• To save only a specific table, a tableName filter field may be added to the payload in a future version.