Some time ago, in my Industries CPQ work, I built a quote-summary FlexCard. Its job was modest: sit on a quote record and show the totals at a glance — the kind of card a sales rep reads for a few seconds before deciding what to do next. I opened the preview, and the card showed nothing. Not an error message. Not a broken layout. Just a quiet, empty rectangle.
I spent twenty years in education before Salesforce, and that work teaches you one thing above all: silence is rarely empty. When a student goes quiet, something specific is happening — you just have to ask the right questions in the right order. A blank FlexCard is the same. In my experience, it is nearly always one of four causes, and there is a calm, ordered way to find out which one you have.
First, the vocabulary, because I promised to explain every term. OmniStudio is Salesforce’s toolkit for building guided, data-driven screens with little or no code. A FlexCard is one of its components: a small card that displays data — fields, totals, buttons — usually on a record page. The card does not fetch data on its own; it asks a data source for JSON (the plain-text, nested format data travels in between systems) and displays whatever it finds at the paths it was told to look at. That sentence is really the whole article. Everything below is just a method for checking it.
The four causes of a blank card
When a FlexCard renders empty, it comes down to one of these almost every time:
- The data source returned nothing. The query behind the card ran, but came back empty — wrong record Id, a filter that matched no rows, an input that never arrived.
- The data came back under different names. The source returned real data, but under JSON node names the card does not expect. And JSON paths are case-sensitive:
quoteTotalandQuoteTotalare two different worlds. - The running user cannot see the data. Object and field-level access apply to OmniStudio like everywhere else. If the user’s profile cannot read a field, its value is silently absent — the card does not error, it just shows a gap.
- You are looking at a stale version. OmniStudio components are versioned. Your edit exists, but the version being served is yesterday’s, because changes only reach users when a new version is activated and published.
Notice something about all four: not one of them produces an error message. That is the trap.
A blank FlexCard is not an error. It is a silence — and every silence on this list has a specific, findable cause.
Debug from the data inward
The instinct, when a card is blank, is to stare at the card. Resist it. The card is the last link in a chain, and the fault is usually upstream. So we work from the data inward, one hop at a time.
Step one: preview the DataRaptor alone. A DataRaptor is OmniStudio’s declarative data tool — the piece that extracts records from Salesforce (or writes them back) and shapes them into JSON. Open it by itself, give it a known record Id — a quote you can see with your own eyes in the org — and run its preview. Then read the raw JSON it returns, slowly. Is there data at all? What are the node names, exactly, letter by letter?
One practical note: the exact labels and tab names in the OmniStudio designers shift between releases, so I describe locations loosely — “the preview tab of the DataRaptor” — rather than quoting button text that may have been renamed by the time you read this. Trust the structure of the method, not the exact label, and verify in your org.
Step two: preview the Integration Procedure with the same input. An Integration Procedure is a server-side orchestration — a sequence of steps that can call DataRaptors, transform data, and hand a combined result to the UI. Give it the same record Id and watch what each step passes on to the next. Data can enter a procedure healthy and leave it renamed, wrapped in an extra node, or dropped by a conditional step.
Step three: only now, preview the FlexCard with test parameters. If the first two hops were clean and the card is still blank, the problem lives in the card’s own configuration — usually in its merge fields, which brings us to the quietest failure of all.
At every hop, the question is the same, and it never changes:
Does the JSON node the next layer expects actually exist — with exactly that spelling?
The failure that makes no sound
A merge field is a placeholder in the card — something like {QuoteTotal} — that pulls a value out of the JSON at that path. Here is the part nobody warns beginners about: a merge-field typo does not fail. It does not throw an error, does not turn red, does not log a complaint. A wrong path simply renders as empty.
Write {quoteTotal} when the JSON says QuoteTotal, and the card will show you nothing, forever, without telling you why. That silence is exactly why beginners lose hours here. This is also why the raw JSON from step one matters so much: once the real node names are in front of you, checking merge fields becomes a spelling exercise instead of a guessing game.
Test as the real user, not as yourself
Picture a scene, because it happens constantly. You build the card as an admin. You preview it as an admin. It works beautifully. You ship it — and the sales team tells you it is blank.
Field-level security (Salesforce’s control over which fields a given profile or permission set can read) and sharing rules apply to OmniStudio just as they do everywhere else on the platform. If the running user cannot read a field, the value is simply not there — silently, again. An admin preview that works proves nothing about a standard user’s experience.
So test with the real profile or permission set of the affected user — log in as them where your org’s policy allows it, or reproduce their permissions in a sandbox. It feels like extra ceremony. It is the step that finds cause number three.
Yesterday’s version can outlive your edit
The fourth cause is the one that makes you doubt your own eyes: you fixed the card, and it is still blank. OmniStudio components are versioned, and your changes only reach users when a new version is activated and published. Editing is not shipping.
Caching adds a layer on top: even after you publish, yesterday’s version can outlive your edit for a while. So make version discipline part of the loop, not an afterthought — deactivate, reactivate, publish a new version, and confirm which version is actually active before concluding your fix “did not work.” How aggressively things are cached can vary between orgs and releases, so once more: verify in your org.
Your next step
This checklist is not theoretical for me — it is what I run in my own Industries CPQ and OmniStudio work (I hold both OmniStudio certifications), and the order matters more than any single trick in it: data source alone, then the procedure, then the card; then permissions with a real user; then the active version.
Here is your homework, in the spirit of the teacher I used to be. Pick one FlexCard in your org — a working one is fine — and run the checklist on it top to bottom. Preview its DataRaptor with a real record Id and read the JSON. Trace the Integration Procedure hop by hop. Check one merge field against the raw node names, letter by letter. The point is to practice the loop while nothing is broken, so that on the day a card shows you nothing, you are not staring at an empty rectangle wondering where to begin. You will already know: start at the data, and walk inward.