Skip to main content

After a Sandbox Refresh

When a Salesforce sandbox is refreshed from production, the Keelstone package remains installed but some configuration state is reset. The steps required depend on the sandbox type.

What carries over automatically​

ItemFull SandboxDeveloper / Partial Sandbox
Package installation✅✅
Keelstone_Action__c records✅❌ (no data copy)
Keelstone_Group__c records✅❌
Keelstone_Template__c records✅❌
Org API key (Keelstone_Org_Credential__c)✅❌
User package license assignments✅❌
External Client App (ECA)✅✅ (metadata)
Remote Site Setting✅✅ (metadata)
Session Settings (token mode)✅✅ (metadata)
Permission set assignments✅❌

Full Sandbox​

A full sandbox copies all production data, so action records, license assignments, and the org API key all carry over. Keelstone should work without any additional steps.

Verify by:

  1. Opening the Keelstone taskpane in Excel, Word, or PowerPoint
  2. Logging in with your sandbox credentials
  3. Confirming action tiles appear

If something looks wrong, re-run the setup job (see Re-run the post-install job below).

Developer or Partial Sandbox​

No data is copied. All of the following must be done after each refresh.

Step 1 — Re-run the post-install job​

The post-install job registers the sandbox with app.keelstone.dev and stores the org API key, which is required for license checks and document generation.

Run this in Developer Console → Execute Anonymous:

new KeelstonePostInstallHandler().onInstall(null);

Wait 10–15 seconds, then go to Setup → Apex Jobs and confirm the KeelstoneEcaSetupJob completed without errors.

This job also creates the default action groups (Word, Excel, PowerPoint) and the Template Builder action records.

Step 2 — Assign package licenses to users​

Package license assignments (UserPackageLicense records) are not copied in developer or partial sandboxes. Without them, the Keelstone license check will block all users.

  1. Go to Setup → Installed Packages
  2. Find Keelstone Actions and click Manage Licenses
  3. Click Add Users and assign licenses to the users who need access in this sandbox
tip

You only need to do this for users who will actively test in the sandbox. System Administrator users with the org API key in place will pass the license check via the fallback path even without a UserPackageLicense record.

Step 3 — Assign the permission set​

Permission set assignments are not copied. Assign Keelstone_User to any user who needs to see the action tiles:

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

Step 4 — Create test action records​

Action and group records are data and are not present after a developer sandbox refresh. The post-install job in Step 1 creates the default Template Builder actions automatically. For any additional custom actions, either:

  • Create them manually in the Keelstone Actions tab, or
  • Export from production using Data Export and import with Data Import Wizard or Salesforce CLI data commands

Step 5 — Verify the ECA and Remote Site Setting​

These are metadata and should carry over, but it is worth confirming:

  1. Setup → External Client Apps — confirm KS_OAuth_Client exists
  2. Setup → Remote Site Settings — confirm KeelstoneApp is active (https://app.keelstone.dev)
  3. Setup → Session Settings → Lightning Out — confirm "use a session token instead of a session cookie" is enabled (required for Mac users)

Re-run the post-install job​

At any time — after a refresh, after a failed install, or if the org API key is missing — you can re-run the full setup sequence:

new KeelstonePostInstallHandler().onInstall(null);

Or from the Keelstone Setup tab, click Complete Setup.

The job is idempotent: it upserts the ECA and CORS entry, refreshes the consumer key, registers or re-registers the org, and creates any missing default action groups and records.

How licenses work in sandboxes​

Keelstone's license check (KS_LicenseService.assertUserLicensed) runs two checks in order:

  1. UserPackageLicense — confirms the user has been assigned a Keelstone package license seat
  2. Org API key fallback — if no UserPackageLicense record exists, checks whether the org has a valid API key in Keelstone_Org_Credential__c

The org API key is written by the post-install job after registering with app.keelstone.dev. In a developer sandbox, this key is absent until the job runs, which is why Step 1 is required before any license-gated feature (Template Builder, document generation) will work.

LMA license records (managed in the Keelstone Hub org) are not affected by sandbox refreshes — they live in the packaging org and are independent of the subscriber sandbox.