Ask & analyse

Show dashboards inside Salesforce

Put an Insights dashboard on a Lightning record, app, or home page — filtered to the record being viewed.

7 min read

A dashboard earns its keep where the work happens. Any Insights chart or dashboard can be rendered inside Salesforce — on a record page, an app page, or a home page — using the OrgAdmin Insight Lightning component. On a record page it filters itself to the record being viewed, so one dashboard serves every account, every opportunity, every case.

It travels between orgs, too. Switch embedding on once and the dashboard becomes a template: place it in a sandbox and it shows sandbox numbers, place the same one in production and it shows production numbers. The dashboard supplies the questions; each org answers them with its own data.

Set an org up once

Five steps, in this order. You only do them once per connected org — after that, embedding any further dashboard is a single switch.

  1. 1

    Turn embedding on for the dashboard

    Open the dashboard, click Embed, and switch on Allow embedding. Nothing is shared until you do this, and it is deliberately a person's decision — the AI that builds dashboards has no way to flip it.
  2. 2

    Deploy the component to your org

    In the same panel, choose Add package to Development Studio. That creates a project holding the Apex controller and its test class, a sandbox post-copy class, the Lightning component, a custom setting, a Trusted URL and a permission set. Review it, then deploy it the usual way — see Development Studio. Deploying to a production org must run the test class OrgAdminEmbedControllerTest, so pick Run specified tests and name it.
  3. 3

    Give viewers the permission set

    In Setup, assign the OrgAdmin Insight Viewer permission set (OrgAdmin_Insight_Viewer) to everyone who should see embedded dashboards. Without it Salesforce shows them “You do not have access to the Apex class”. Administrators can call every class, so test with a normal user before rolling out.
  4. 4

    Create an embed key

    On the org's settings page, under Salesforce embedding, create a key. The secret is shown once and never again — copy it before you close the page.
  5. 5

    Tell Salesforce where to look

    In Salesforce Setup, go to Custom Settings → OrgAdmin Embed Settings → Manage → New and paste three values: the URL https://orgadmin.ai, the Key ID, and the secret. Custom setting values are data rather than metadata, which is why the deploy cannot fill them in for you.

Place it on a page

In the Lightning App Builder, drag OrgAdmin Insight onto a page and set its properties:

  • Dashboard or chart ID — copy it from the Embed panel. This is the only required property.
  • Record filter ID — record pages only; see below.
  • Extra filters (JSON) — optional fixed values, for example {"stage":["Closed Won"]}, when one placement should always show a particular slice. Build it in the Embed panel and copy it across: each filter type takes a different shape (a stage picker wants an array, a date wants an object), and a value in the wrong shape is quietly ignored rather than reported.
  • Card title, Initial height, Theme — presentation only. The dashboard measures itself and corrects the height once it renders, so the initial value just avoids a jump on first paint.

Filters you do not fix stay live inside the page: a viewer can still change the date range without leaving Salesforce.

Filtering by the record

A dashboard does not automatically know what an Account page is about — it has to declare a filter for the record, and you point the component at it. The simplest way to get one is to ask the builder for it: “this will go on the Account record page, filter it by the record it's embedded on.” The AI then adds a filter bound to the right lookup field and gives it a working sample record so the dashboard still previews properly inside Insights.

The Embed panel shows that filter's id — put it in Record filter ID and the page's record is substituted every time the component loads. Before it is, Salesforce checks that the person viewing the page can read that record; if they can't, they see a message instead of the dashboard.

A dashboard with a record filter needs one. If Record filter ID is blank, or the dashboard is placed on an app or home page, it shows “This dashboard is built for a record page” rather than quietly showing the sample record it was built with. If the panel says no record filter exists, the dashboard shows org-wide numbers on every record, which is occasionally what you want (a company-wide average to compare against) but usually is not.

One dashboard, every record

Build and check it once against a single account. The same asset then works on every Account page in the org — there is nothing to duplicate per record, and no report folder to maintain.

Freshness and API use

An embedded dashboard follows the dashboard's Data refresh setting, like it does in the app (see Insights). Everyone viewing it in one org reads through the same connection, so they share one encrypted cached run: a dashboard on an Account page that two hundred people open in an afternoon costs one set of queries per refresh window, not two hundred. The line above the tiles shows when the numbers are from, and Refresh runs them live (at most once a minute).

Choose Always live on the dashboard if it lists personal details and you would rather results were never stored, even briefly. Each view then queries Salesforce, so keep an eye on the org's daily API allowance for busy pages.

Keys and rotation

The key is a shared secret: your org's Apex signs each request with it, and this app checks the signature. Two keys can be active at once, which is the whole rotation story — create the new one, paste it into the custom setting, then revoke the old one.

Revoking takes effect on open pages at their next refresh rather than whenever a session happens to lapse, so it is a real off switch. Revoke a key if you suspect it has been copied out of the org, or when someone who could read the custom setting leaves.

Sandboxes

Creating or refreshing a sandbox copies custom setting values from production — including the embed secret, which would let anyone who can read the sandbox's settings sign production dashboard links. The package includes a class that blanks it:

  1. 1

    Name the post-copy class

    When you create or refresh a sandbox from production, enter OrgAdminEmbedSandboxReset in the Apex Class field. It clears the Key ID and secret as the sandbox is created.
  2. 2

    Give the sandbox its own key

    Connect the sandbox in orgadmin.ai, create a key on its settings page, and paste it into the sandbox's OrgAdmin Embed Settings.

If a sandbox was refreshed without the class, rotate production's key (create a new one, update production's setting, revoke the old one) and give the sandbox its own. Until then, embeds in that sandbox show “The link does not match this connected org”.

Keeping the package up to date

The package has a version. Each org reports the version it runs the first time someone opens an embedded dashboard there, and the Embed panel shows it next to the org: Package v1.1.0, or Update available when a newer one exists. Older versions keep working — updating picks up the fixes.

To update, choose Add package to Development Studio again and deploy the refreshed project. If you changed any of its files in the studio, those are kept and listed rather than overwritten; choose Overwrite anyway to take the new version instead.

Who sees what

Embedded data is read as the connected org user

Inside this app a dashboard runs with your own Salesforce permissions. An embedded one does not: it runs through the connection of the org it is placed in, so everyone who can see the Lightning page sees the data that connection can see — not what their own profile allows. The embed says so in its footer, and the switch warns you before you turn it on.

Because each org answers with its own data, nothing crosses between them — a dashboard in your sandbox cannot show production figures. What switching embedding on does decide is that any org connected to this workspace may render it. Which orgs those are is governed by embed keys: an org with no key shows nothing, and revoking a key cuts it off at the next refresh.

In practice that means you should choose the pages deliberately. A pipeline dashboard on an Account page that every sales user already has access to is fine. A dashboard covering the whole company, dropped on a home page everybody sees, is a decision worth making on purpose rather than by accident.

Every embedded load is written to the audit log with the dashboard, the key used, the Salesforce user who opened the page, the package version, whether it came from the cache, and which filters were applied — never the filter values themselves.

The dashboard only opens inside Salesforce. Copying its address into a new browser tab shows “Open this inside Salesforce”, and a framed session lasts an hour before the component quietly signs a new one through Salesforce (keeping any filters the viewer had set).

Limits

  • Not supported: Experience Cloud sites and guest users, Salesforce Classic and Visualforce, and the report asset type.
  • Data is read as the connected org user, not the viewer — per-viewer visibility is not available.
  • Nothing checks ahead of time that a dashboard's fields exist in the org you place it in; a missing field shows as an error on that tile.
  • Removing an org (not just disconnecting it) deletes the dashboards built against it — including ones placed in other orgs. The remove screen counts them; move a dashboard to an org you are keeping (the org switcher on the dashboard) first.

When something looks wrong

  • “OrgAdmin embedding is not configured” — the custom setting has no org default record yet, or one of its three fields is blank.
  • An empty box where the dashboard should be — the Trusted URL is missing, inactive, or does not match https://orgadmin.ai. Salesforce refuses to frame anything it has not been told to trust. Components from package 1.1 say so after 15 seconds.
  • “You do not have access to the Apex class” — the viewer needs the OrgAdmin_Insight_Viewer permission set.
  • “If this stays blank, check the Trusted URL” — the frame never loaded, almost always because the Trusted URL OrgAdmin_Embed is missing, inactive, or does not match https://orgadmin.ai.
  • “This embed is not available” — the key was revoked, or the Key ID and secret belong to a different org. After a sandbox refresh, give the sandbox its own key (see Sandboxes).
  • “This dashboard is built for a record page” — set Record filter ID to the id the Embed panel shows, on a record page.
  • “You do not have access to this record” — the viewer can't read the record the page is about, so its dashboard isn't shown.
  • “N component settings were ignored” — an Extra filters value names a filter the dashboard doesn't have, or is in the wrong shape. Rebuild it in the Embed panel.
  • “Open this inside Salesforce” — the dashboard's address was opened directly; it only works on the Salesforce page.
  • “This dashboard is not shared” — embedding was switched off for it. Turn it back on in the dashboard's Embed panel.
  • “This dashboard is not available here” — the Dashboard ID is wrong, or it belongs to a different workspace. Re-copy it from the Embed panel.
  • One tile shows an error, the rest are fine — that query references a field the org you placed it in does not have. Nothing checks this ahead of time, so it surfaces the first time you view it there.
  • “This link has expired” or “Session expired” — normal for a tab left open a while; the component signs a fresh link by itself and the message clears.

Related: Insights for building the dashboard in the first place, Development Studio for the deploy, and Connect your Salesforce orgs for org settings and roles.

Follow along in your own org

This guide sets up AI Insights. 14-day free trial, no credit card.

Start free trial