Skip to main content

Installation Guide

This guide walks a Salesforce administrator through installing Keelstone Actions, connecting the Office or Google Workspace add-in, and verifying the setup end-to-end.

Prerequisites​

RequirementDetails
Salesforce editionEnterprise, Unlimited, Developer, or Professional
API version66.0 or later
Microsoft Office (optional)Excel, Word, or PowerPoint (Microsoft 365, desktop or browser)
Google Workspace (optional)Google Sheets, Docs, or Slides
BrowserChrome, Edge, or Firefox (for the Keelstone taskpane)
System Administrator profileRequired for package install and ECA verification

Step 1 — Install the Package​

Install Keelstone Actions from the AppExchange listing, or run the following command with Salesforce CLI:

sf package install \
  --package 04ta500000DGSNRAA5 \
  --target-org <your-org-alias> \
  --wait 10

The installer will prompt you to grant access to third-party websites (app.keelstone.dev). Approve this when prompted — it is required for Keelstone to communicate with the document.

Installation time

Package installation typically takes 2–4 minutes. A post-install job runs automatically in the background after install completes.

Step 2 — Verify the Post-Install Job​

The package runs a post-install job (KeelstonePostInstallHandler) that:

  1. Creates an External Client App (ECA) named Keelstone in your org with OAuth 2.0 PKCE credentials
  2. Registers your org with app.keelstone.dev

To verify this completed successfully:

  1. Go to Setup → External Client Apps
  2. Confirm an app named Keelstone exists with OAuth enabled

If the ECA is missing, the job may have failed. You can re-run it from the Keelstone Setup tab, or run it manually:

// Execute in Developer Console → Execute Anonymous
new KeelstonePostInstallHandler().onInstall(null);

Step 3 — Assign the Permission Set​

The Keelstone_User permission set grants read access to the Keelstone_Action__c and Keelstone_Group__c objects that the taskpane queries on login.

Assign it to every user who will use the add-in:

  1. Go to Setup → Permission Sets → Keelstone_User
  2. Click Manage Assignments → Add Assignments
  3. Select the users and click Assign
tip

You can also assign via the user record: User Detail → Permission Set Assignments → Edit Assignments.

Step 4 — Install the Office Add-in​

Keelstone is available as a Microsoft Office add-in for Excel, Word, and PowerPoint.

Option A — Microsoft AppSource (recommended)​

  1. Open Excel, Word, or PowerPoint
  2. Go to Insert → Get Add-ins
  3. Search for Keelstone
  4. Click Add

The add-in will appear in the Home ribbon as Keelstone.

Option B — Admin deployment via Microsoft 365 Admin Center​

For IT-managed deployments, upload the manifest files from your Microsoft 365 admin portal to deploy to all users automatically. Contact support@keelstone.dev for manifest files.

Option C — Sideload via Shared Folder (Windows or Mac desktop, testing or personal use)​

  1. Create a folder on your computer or a local network share. Right-click the folder, go to Properties, and ensure it is shared with yourself or your team.
  2. Place the downloaded manifest .xml file inside that folder.
  3. Open Excel (or Word/PowerPoint) and go to File → Options.
  4. Click Trust Center, then select Trust Center Settings.
  5. Select Trusted Add-in Catalogs on the left.
  6. In the Catalog Url box, paste the path to the folder (UNC path, e.g. \\machinename\SharedFolder), click Add Catalog, and ensure Show in Menu is checked.
  7. Click OK and restart Excel.
  8. Go to Insert → Add-ins (or Home → Add-ins) and click Shared Folder — you should see Keelstone.
  9. Click Add.

Step 4b — Install the Google Workspace Add-on (optional)​

Keelstone also works in Google Sheets, Docs, and Slides via a Google Workspace add-on.

  1. Open a Google Sheet
  2. Go to Extensions → Apps Script
  3. Paste the Keelstone Apps Script code (available at https://docs.keelstone.dev or by contacting support@keelstone.dev)
  4. Save and deploy as a Google Workspace add-on

The Google add-on uses the same Salesforce session and the same action records as the Office add-in. Actions with Document Type = Excel / Sheets appear in Google Sheets, Word / Docs in Google Docs, and PowerPoint / Slides in Google Slides.

Step 5 — Connect to Your Salesforce Org​

When you first open the Keelstone taskpane in any Office app or Google Workspace add-on:

  1. You will see a login screen asking for your Salesforce custom domain
  2. Enter your org's custom domain (e.g., mycompany for mycompany.my.salesforce.com)
  3. As you type, the full URL is shown below — confirm it matches your org
  4. Click Continue
  5. A Salesforce login window opens — sign in with your credentials
  6. After login, the taskpane loads your action tiles

The session persists across Excel, Word, PowerPoint, and Google Workspace apps (all Keelstone add-ins share the same login).

Step 6 — Create Your First Action​

After installing, verify the setup with the built-in Hello World flow:

  1. Go to Keelstone Actions in your Salesforce org (custom object tab or App Launcher)
  2. Create a new record:
    • Label: Hello World
    • Action Type: Flow
    • Action Target: kstone__Keelstone_Hello_World
    • Document Type: Excel / Sheets
    • Active: ✓
  3. Open the Excel taskpane (or Google Sheets add-on)
  4. Click the Hello World tile
  5. The flow launches in a dialog and displays a "Keelstone is connected" confirmation

Step 7 — Verify the Remote Site Setting​

Keelstone requires https://app.keelstone.dev to be an approved endpoint.

  1. Go to Setup → Remote Site Settings
  2. Confirm KeelstoneApp is listed and Active is checked
  3. If missing, create it:
    • Remote Site Name: KeelstoneApp
    • Remote Site URL: https://app.keelstone.dev
    • Active: ✓

Step 8 — Enable the Lightning Session Token Setting​

Keelstone's Screen Flows run inside an Office dialog or taskpane webview, which is a third-party context outside of Salesforce. By default, Salesforce uses session cookies to authenticate embedded Lightning applications — but cookies are blocked in these webviews on Mac (Safari ITP), in sandbox orgs, and in certain browser security configurations.

Enable the following setting so Salesforce uses a session token instead:

  1. Go to Setup → Session Settings
  2. Scroll to the Lightning Out section
  3. Check "When embedding a Lightning application in a third-party site, use a session token instead of a session cookie"
  4. Click Save
Required in all orgs

This setting is required in every org where Keelstone is installed — including production, sandboxes, and scratch orgs. Without it, clicking an action tile will open the flow view but nothing will load (the taskpane will appear to hang silently with no error message).

Step 9 — (Optional) Configure Branding​

Pro Plan Feature

Branding customisation requires a Keelstone Pro plan. The Manifest Generator is available on all plans.

Admins can customise the taskpane header and Office ribbon button from the Keelstone Setup tab.

  1. Go to the Keelstone Setup tab → Branding section
  2. Under Current Logo, click Upload new logo
    • Accepted formats: PNG, JPG, SVG
    • Maximum file size: 50 KB
    • Recommended height: 48 px (the taskpane header is fixed-height)
  3. Optionally enter Custom CSS targeting .ks-header and other taskpane classes
  4. Click Save Branding

Changes are stored on the Keelstone server and apply immediately on the next taskpane load.

Ribbon icon (Office manifests)​

The ribbon icon is the button image that appears in the Word, Excel, and PowerPoint ribbons. It is hosted at a stable public URL so it can be referenced directly in Office manifest files.

  1. Under Ribbon Icon, click Upload ribbon icon
    • Accepted formats: PNG, JPG (SVG not supported by Office ribbon)
    • Maximum file size: 20 KB
    • Recommended size: 80 × 80 px square
  2. Click Save Branding

After saving, the hosted icon URL is displayed below the preview and is automatically pre-populated in the Manifest Generator.

Manifest Generator​

The Manifest Generator produces a customised Office manifest (XML) or Google Workspace manifest (appsscript.json) for internal distribution. The app GUID is never changed — only the ribbon button label and icon are replaced.

  1. In the Manifest Generator section, select the Application (Word, Excel, PowerPoint, or Google Sheets)
  2. Enter a Button Label (the text that appears under the button in the ribbon)
  3. The Button Icon URL is pre-populated from your saved ribbon icon, or enter a custom URL
  4. Click Download Manifest

A .zip file is downloaded containing the manifest file. Distribute it to your users via:

  • Microsoft 365 Admin Center (Integrated Apps → Upload custom app)
  • SharePoint catalog for older deployments
  • Google Workspace Admin (Apps → Google Workspace Marketplace apps → Configure) for the Google add-on

Troubleshooting​

Taskpane shows "Session not found"​

The session token has expired. Click Disconnect and log in again.

Action tiles do not appear​

  • Confirm the Keelstone_User permission set is assigned to your user
  • Confirm kstone__Active__c is checked on the Action record
  • Confirm kstone__Document_Type__c matches the app you are using (e.g., Excel / Sheets actions appear in both Excel and Google Sheets)

Post-install job did not run​

Open the Keelstone Setup tab and click Complete Setup, or run the anonymous Apex shown in Step 2. If the ECA was not created, check debug logs for error output.

Flows open but nothing loads (blank flow view, no error)​

The Lightning session token setting is not enabled. Go to Setup → Session Settings → Lightning Out and check "use a session token instead of a session cookie" (see Step 8). This is required in all orgs — production, sandboxes, and scratch orgs. Without it, $Lightning.use() fails silently and the flow never renders.

OAuth error during login​

  • Confirm the Keelstone ECA exists in Setup → External Client Apps
  • Confirm the Remote Site Setting for https://app.keelstone.dev is active
  • Try logging in from an incognito/private browser window

"This feature requires the pro plan" message​

Your org is on the Free tier and has reached the action or user limit. Contact support@keelstone.dev to upgrade.

Sandbox refresh — action tiles missing or license errors​

After refreshing a developer or partial sandbox, license assignments and action records are not copied from production. See the Sandbox Refresh guide at https://docs.keelstone.dev/sandbox-refresh for step-by-step recovery instructions.

Plan Limits​

PlanUsersActionsDocument MergesDocument Types
FreeUnlimited1100 per user / monthWord & Google Docs
BasicUnlimitedTemplate Builder onlyUnlimitedWord & Google Docs
ProUnlimitedUnlimitedUnlimitedExcel, Word, PowerPoint, PDF, Google Workspace

Merge limits apply to document generation (template merge and merge-from-file). Inserting text, reading ranges, and writing data do not count against the merge limit.

Support​