OmniStudio Cache Strategies
Use this skill when deciding whether, where, and how to cache an OmniStudio
read path — and when diagnosing a cache that appears configured but is not
changing anything. It covers the three distinct caches that share the word
"cache" in OmniStudio, the Platform Cache limits every one of them inherits,
and the security consequences of serving a payload that was computed for
somebody else.
Before Starting
- Which runtime is this org on? Standard runtime and the Vlocity managed
package have separate documentation, separate settings, and in places
separate behaviour.
OmniStudioSettings.enableStandardOmniStudioRuntime
(API 65.0+) and enableOaForCore (64.0+) answer the question. Most
published OmniStudio writing describes the package; assume nothing until
you have checked.
- Is Platform Cache actually allocated? A partition with no capacity
produces no error and no speedup. Verify allocation in Setup before
scheduling any tuning work.
- What is the freshness contract in business terms? Not "as fresh as
possible" — a number, agreed with whoever owns the data. The platform's
5-minute TTL floor means some answers rule caching out entirely.
- Who can reach this component? Internal only, authenticated portal, or
guest. The answer changes the cache type and may forbid caching outright.
The Three Caches
Naming the layer is the whole diagnostic. These are independent:
| Layer |
Stores |
Configured by |
Symptom when misconfigured |
| Component metadata cache |
the compiled component definition |
isMetadataCacheDisabled (boolean, default false — so it is on by default) on OmniIntegrationProcedure and OmniScript |
slow cold start after deploy |
| Response cache |
the output payload |
Data Mapper Options tab (Platform Cache Type, Time to Live in Minutes); IP Cache Configuration section (whole response) or Cache Block element (enclosed steps); responseCacheType in metadata, plus responseCacheTtlMinutes on the Data Mapper type only |
warm reads no faster than cold |
| Platform Cache |
the underlying key/value substrate |
Setup → Platform Cache partition allocation |
nothing is cached at all, silently |
isMetadataCacheDisabled is a negative. Default false means metadata
caching is already enabled; setting it true turns caching off. It is a
debugging lever, not a performance lever, and flipping it will not change what
a warm read returns.
The Limits That Decide The Design
Every OmniStudio response cache sits on Platform Cache and inherits its
bounds. These are the numbers that most often invalidate a proposed design:
| Constraint |
Value |
| TTL minimum (org and session) |
300 s / 5 minutes |
| TTL maximum — org cache |
172,800 s / 48 hours (default 86,400 s / 24 h) |
| TTL maximum — session cache |
28,800 s / 8 hours |
| Maximum cache key size |
50 characters |
| Cache key characters |
alphanumeric only — put() throws Cache.InvalidParamException otherwise |
| Maximum size of a single cached item |
100 KB |
| Minimum partition size |
1 MB |
| Maximum local cache per partition, per request |
500 KB session / 1,000 KB org |
Three consequences worth internalising:
- A freshness requirement tighter than 5 minutes is a decision not to
cache, not a smaller number in the TTL field.
- The Redis-style key
catalog:v2:region=NA is illegal on this platform.
Use camelCase with no separators.
- Caching the whole aggregate response usually exceeds 100 KB. Cache the
resolved decision instead.
Security Consequences Of A Warm Read
A cache hit returns a payload computed during somebody else's request, under
that request's permission evaluation. Two documented facts and one reported
behaviour follow:
- Documented. "Data in the cache isn't encrypted." Shield Platform
Encryption does not follow a value into a cache entry.
- Documented. Org cache is addressed by a key. If the key is derived from
caller-supplied inputs rather than a server-resolved subject, the
caller chooses which entry to read. On a guest-reachable page this is a
cross-tenant read.
- Reported, not documented. Metadata caching is reported to let a component
execute for a user who would fail its Required Permission check on a cold
run, because that check sits on the path the cache skips. Treat this as a
reason not to lean on Required Permission as your only authorization
boundary — not as a Salesforce-documented behaviour you can cite. See
gotchas.md §4 for the provenance.
The defensive posture the third bullet implies is sound regardless of whether
the specific bypass reproduces in your org: an access check that runs only on a
cold path is not an authorization boundary. Gate on the object and field
permissions of the running user and on the sharing model, which are evaluated
per call.
Keep fieldLevelSecurityEnabled true on Data Mappers. It governs the cold
path, and the cold path decides what every subsequent warm read returns.
Recommended Workflow
- Establish the runtime (standard vs managed package) and confirm Platform
Cache partition allocation is non-zero. Stop here if it is zero — nothing
downstream is measurable until it is fixed.
- Measure the read path cold, as a user from the target audience. Record p50
and p95 and the serialized payload size in bytes.
- Classify the payload: identical for everyone, or scoped to a person. This
choice — not the desired hit ratio — sets
responseCacheType to org or
session. Anything guest-reachable or containing PII defaults to no cache.
- Set a TTL inside the platform range (5 min – 48 h org, 5 min – 8 h session)
that matches the agreed freshness contract. If the contract is tighter than
5 minutes, record the decision not to cache and stop.
- Design invalidation before shipping: a version discriminator inside the
cache key for routine releases, plus a documented purge path for incidents.
A TTL alone is a staleness bound, not an invalidation mechanism.
- Verify in the runtime context, as two different users, comparing payloads
and not only elapsed time. Designer preview timings do not demonstrate the
response cache.
- Instrument hit ratio and cold-start load. Plan capacity for the cold-start
spike that follows an eviction — cache "isn't persisted" and an Apex deploy
may clear it.
Review Checklist
Worked Examples (see references/examples.md)
- Naming the layer — the three caches, and which one your symptom belongs to
- Reference-data Data Mapper — the full Options-tab and metadata configuration
- The cache that silently did nothing — partition allocation
- Cache key characters — the
Cache.InvalidParamException reproduction
- Org vs session from the payload — deciding on audience, not latency
- Invalidation on deploy — the case nobody configures
Common Gotchas (see references/gotchas.md)
- TTLs below 5 minutes are below the platform floor and do not mean what they say
- Keys with
: or = throw Cache.InvalidParamException
- Cached data is unencrypted and warm reads do not re-check sharing
isMetadataCacheDisabled is a negative that defaults to false
- The IP metadata type documents a cache type but no TTL field — which means
the duration does not round-trip through metadata, not that the setting
is missing from the designer
- Standard runtime and managed package have parallel, differently-behaving docs
Top LLM Anti-Patterns (full list in references/llm-anti-patterns.md)
- Redis-style punctuated cache keys
- TTL values below the 5-minute floor
- Inventing property names (
cacheEnabled, isCacheable, cacheTTL)
- Answering with managed-package behaviour for a standard-runtime org
- Org cache for anything the caller can key
- Treating TTL as the invalidation design
Related
- omnistudio/integration-procedure-cacheable-patterns — owns cache-key
design, partition selection, the Cache Block element, and invalidation for
Integration Procedures specifically.
- omnistudio/omniscript-session-state — when the requirement is durability
across a logout rather than latency, session cache is the wrong store.
- omnistudio/omnistudio-security — Required Permission, guest exposure, and
the security settings referenced in
gotchas.md §4.
- standards/decision-trees/performance-tuning.md — read before concluding
that caching is the right lever. A cache layered over an unselective query
hides the defect rather than fixing it.
Official Sources Used
See references/well-architected.md for the full source list with the
specific claim each source grounds.
1---2name: omnistudio-cache-strategies3description: "Configure caching on DataRaptors and Integration Procedures for response-time gains. Triggers: OmniStudio cache, DataRaptor cache, IP cache TTL. NOT for IP-specific cacheable design — use omnistudio/integration-procedure-cacheable-patterns."4category: omnistudio5salesforce-version: "Spring '25+"6well-architected-pillars:7 - Performance8 - Reliability9triggers:10 - "dataraptor cache"11 - "integration procedure cache"12 - "omnistudio cache ttl"13 - "cache bust omniscript"14 - "why is my omnistudio cache not working"15tags:16 - omnistudio17 - cache18 - performance19inputs:20 - "current response times per IP/DR"21 - "data freshness requirements"22outputs:23 - "cache config + bust strategy + monitoring"24dependencies: []25runtime_orphan: true26version: 1.0.127author: Pranav Nagrecha28updated: 2026-08-1429metadata:30 source: https://skillmd.com/skills/pranavnagrecha/omnistudio-cache-strategies31---3233# OmniStudio Cache Strategies3435Use this skill when deciding whether, where, and how to cache an OmniStudio36read path — and when diagnosing a cache that appears configured but is not37changing anything. It covers the three distinct caches that share the word38"cache" in OmniStudio, the Platform Cache limits every one of them inherits,39and the security consequences of serving a payload that was computed for40somebody else.4142---4344## Before Starting4546- **Which runtime is this org on?** Standard runtime and the Vlocity managed47 package have separate documentation, separate settings, and in places48 separate behaviour. `OmniStudioSettings.enableStandardOmniStudioRuntime`49 (API 65.0+) and `enableOaForCore` (64.0+) answer the question. Most50 published OmniStudio writing describes the package; assume nothing until51 you have checked.52- **Is Platform Cache actually allocated?** A partition with no capacity53 produces no error and no speedup. Verify allocation in Setup before54 scheduling any tuning work.55- **What is the freshness contract in business terms?** Not "as fresh as56 possible" — a number, agreed with whoever owns the data. The platform's57 5-minute TTL floor means some answers rule caching out entirely.58- **Who can reach this component?** Internal only, authenticated portal, or59 guest. The answer changes the cache type and may forbid caching outright.6061---6263## The Three Caches6465Naming the layer is the whole diagnostic. These are independent:6667| Layer | Stores | Configured by | Symptom when misconfigured |68|---|---|---|---|69| **Component metadata cache** | the compiled component definition | `isMetadataCacheDisabled` (boolean, default `false` — so it is **on** by default) on `OmniIntegrationProcedure` and `OmniScript` | slow cold start after deploy |70| **Response cache** | the output payload | Data Mapper Options tab (**Platform Cache Type**, **Time to Live in Minutes**); IP **Cache Configuration** section (whole response) or **Cache Block** element (enclosed steps); `responseCacheType` in metadata, plus `responseCacheTtlMinutes` on the Data Mapper type only | warm reads no faster than cold |71| **Platform Cache** | the underlying key/value substrate | Setup → Platform Cache partition allocation | nothing is cached at all, silently |7273`isMetadataCacheDisabled` is a negative. Default `false` means metadata74caching is already enabled; setting it `true` turns caching **off**. It is a75debugging lever, not a performance lever, and flipping it will not change what76a warm read returns.7778---7980## The Limits That Decide The Design8182Every OmniStudio response cache sits on Platform Cache and inherits its83bounds. These are the numbers that most often invalidate a proposed design:8485| Constraint | Value |86|---|---|87| TTL minimum (org and session) | 300 s / 5 minutes |88| TTL maximum — org cache | 172,800 s / 48 hours (default 86,400 s / 24 h) |89| TTL maximum — session cache | 28,800 s / 8 hours |90| Maximum cache key size | 50 characters |91| Cache key characters | **alphanumeric only** — `put()` throws `Cache.InvalidParamException` otherwise |92| Maximum size of a single cached item | 100 KB |93| Minimum partition size | 1 MB |94| Maximum local cache per partition, per request | 500 KB session / 1,000 KB org |9596Three consequences worth internalising:97981. A freshness requirement tighter than 5 minutes is a decision **not to99 cache**, not a smaller number in the TTL field.1002. The Redis-style key `catalog:v2:region=NA` is illegal on this platform.101 Use camelCase with no separators.1023. Caching the whole aggregate response usually exceeds 100 KB. Cache the103 resolved decision instead.104105---106107## Security Consequences Of A Warm Read108109A cache hit returns a payload computed during somebody else's request, under110that request's permission evaluation. Two documented facts and one reported111behaviour follow:112113- **Documented.** **"Data in the cache isn't encrypted."** Shield Platform114 Encryption does not follow a value into a cache entry.115- **Documented.** Org cache is addressed by a key. If the key is derived from116 **caller-supplied** inputs rather than a **server-resolved** subject, the117 caller chooses which entry to read. On a guest-reachable page this is a118 cross-tenant read.119- **Reported, not documented.** Metadata caching is reported to let a component120 execute for a user who would fail its **Required Permission** check on a cold121 run, because that check sits on the path the cache skips. Treat this as a122 reason not to lean on Required Permission as your only authorization123 boundary — not as a Salesforce-documented behaviour you can cite. See124 `gotchas.md` §4 for the provenance.125126<!-- UNVERIFIED: the Required Permission bypass in the third bullet is not127stated in any Salesforce-published doc I could read. It traces to AppOmni's1282025 Salesforce Industry Cloud security research, reported via CSO Online and129Information Security Buzz. The behaviour itself, its scope (standard runtime vs130managed package), and the remediation settings are all unconfirmed against131Salesforce. Do not present it to a customer as documented platform behaviour;132reproduce it in a sandbox first. -->133134The defensive posture the third bullet implies is sound regardless of whether135the specific bypass reproduces in your org: an access check that runs only on a136cold path is not an authorization boundary. Gate on the object and field137permissions of the running user and on the sharing model, which are evaluated138per call.139140Keep `fieldLevelSecurityEnabled` true on Data Mappers. It governs the cold141path, and the cold path decides what every subsequent warm read returns.142143---144145## Recommended Workflow1461471. Establish the runtime (standard vs managed package) and confirm Platform148 Cache partition allocation is non-zero. Stop here if it is zero — nothing149 downstream is measurable until it is fixed.1502. Measure the read path cold, as a user from the target audience. Record p50151 and p95 and the serialized payload size in bytes.1523. Classify the payload: identical for everyone, or scoped to a person. This153 choice — not the desired hit ratio — sets `responseCacheType` to `org` or154 `session`. Anything guest-reachable or containing PII defaults to no cache.1554. Set a TTL inside the platform range (5 min – 48 h org, 5 min – 8 h session)156 that matches the agreed freshness contract. If the contract is tighter than157 5 minutes, record the decision not to cache and stop.1585. Design invalidation before shipping: a version discriminator inside the159 cache key for routine releases, plus a documented purge path for incidents.160 A TTL alone is a staleness bound, not an invalidation mechanism.1616. Verify in the runtime context, as two different users, comparing payloads162 and not only elapsed time. Designer preview timings do not demonstrate the163 response cache.1647. Instrument hit ratio and cold-start load. Plan capacity for the cold-start165 spike that follows an eviction — cache "isn't persisted" and an Apex deploy166 may clear it.167168---169170## Review Checklist171172- [ ] Runtime recorded (standard vs managed package) before any doc was cited173- [ ] Partition allocation verified non-zero in Setup174- [ ] TTL within 5 min – 48 h (org) or 5 min – 8 h (session)175- [ ] `responseCacheType` matches the payload's audience, not its latency176- [ ] No org cache on a guest-reachable, portal, or PII component177- [ ] Cache keys are alphanumeric only and ≤ 50 characters, enforced in one helper178- [ ] Serialized payload measured against the 100 KB per-item ceiling179- [ ] Version discriminator in the key, plus a documented purge path180- [ ] `fieldLevelSecurityEnabled` true on cached Data Mappers181- [ ] No cache on a Data Mapper whose `type` is `Load`182- [ ] Read path treats a miss as a latency event, never an error183184---185186## Worked Examples (see `references/examples.md`)187188- *Naming the layer* — the three caches, and which one your symptom belongs to189- *Reference-data Data Mapper* — the full Options-tab and metadata configuration190- *The cache that silently did nothing* — partition allocation191- *Cache key characters* — the `Cache.InvalidParamException` reproduction192- *Org vs session from the payload* — deciding on audience, not latency193- *Invalidation on deploy* — the case nobody configures194195## Common Gotchas (see `references/gotchas.md`)196197- TTLs below 5 minutes are below the platform floor and do not mean what they say198- Keys with `:` or `=` throw `Cache.InvalidParamException`199- Cached data is unencrypted and warm reads do not re-check sharing200- `isMetadataCacheDisabled` is a negative that defaults to `false`201- The IP metadata type documents a cache *type* but no TTL field — which means202 the duration does not round-trip through metadata, not that the setting203 is missing from the designer204- Standard runtime and managed package have parallel, differently-behaving docs205206## Top LLM Anti-Patterns (full list in `references/llm-anti-patterns.md`)207208- Redis-style punctuated cache keys209- TTL values below the 5-minute floor210- Inventing property names (`cacheEnabled`, `isCacheable`, `cacheTTL`)211- Answering with managed-package behaviour for a standard-runtime org212- Org cache for anything the caller can key213- Treating TTL as the invalidation design214215---216217## Related218219- **omnistudio/integration-procedure-cacheable-patterns** — owns cache-key220 design, partition selection, the Cache Block element, and invalidation for221 Integration Procedures specifically.222- **omnistudio/omniscript-session-state** — when the requirement is durability223 across a logout rather than latency, session cache is the wrong store.224- **omnistudio/omnistudio-security** — Required Permission, guest exposure, and225 the security settings referenced in `gotchas.md` §4.226- **standards/decision-trees/performance-tuning.md** — read before concluding227 that caching is the right lever. A cache layered over an unselective query228 hides the defect rather than fixing it.229230## Official Sources Used231232See `references/well-architected.md` for the full source list with the233specific claim each source grounds.