When you're designing an application, one of the most quietly powerful decisions you'll make is how to handle your data: should it be embedded directly into your case, or should it be referenced from a central source?
It might sound like a backend detail, but this choice can ripple through your entire application; it affects performance, auditability, historical accuracy, and even how confidently your business can respond to change. And here's the kicker: it's not always obvious which way to go.
Let me walk you through two real-world scenarios where this decision plays out in very different but equally impactful ways.
Same data object, different strategy. That's the beauty of thoughtful design in Pega.
The Product Order dilemma
You're designing a product ordering system. Users browse a catalog, pick a product, and place an order. The catalog is dynamic; product names, descriptions, and prices can change over time. But after an order is placed, you want that order to reflect exactly what the customer saw at that moment. If the product name changes next week, the invoice from last week shouldn't magically update.
So, what do you do?
You reference the Product data during selection by pulling it in real-time from a Data Page. But when the order is placed, you snapshot the Product details into the Case. That's Embedded Data. Now, even if the catalog changes, your order stays true to its original state: clean, consistent, and audit-proof.
A product field from Purchase Order with the reference data is copied to the case checkbox.
The Supplier Onboarding journey
Now let's switch gears. You're working on an onboarding process for a supplier. The data is still in flux during onboarding; it's being reviewed, updated, and validated. It's not ready to be part of your official system of record yet. So, referencing it doesn't make sense. Instead, you embed the data directly into the onboarding Case.
The Data Model for Supplier Management Case Type, which shows that Data Reference field, Approved Supplier, and embedded field, Supplier Details, are both referring to Supplier.
After the onboarding is approved, that Embedded Data becomes the source of truth. You then promote it—saving it to a shared Supplier Data Type and reference it from that point forward. But here's the twist: you still want to preserve the original onboarding details. Maybe for audit, maybe for comparison. So, you keep the embedded version in the Case and use a Data Page to fetch the current version. Now you can compare the two and see how things have evolved.
The Data Model of the Supplier Management Case Type; Approved Supplier and Supplier Details field definitions are shown as Data Reference and Embedded respectively.
The beauty of it all
Here's the part that makes this design approach truly elegant: in both use cases, the core data object and its model are exactly the same. Whether it's a product or a supplier, the structure doesn't change. What changes is how you use it—how you store it, source it, and refer to it—based on the lifecycle Stage and business need.
And that decision is made entirely at design time. It's up to the application designer or architect to determine whether a data object should be embedded, referenced, or both, based on how the data behaves across the case lifecycle. The user benefits from the clarity and consistency this brings, without needing to know the technical specifics behind it.
This separation of data structure from data usage strategy gives your application both flexibility and clarity. You define your data type once and then design how it's used across different contexts. It's clean, scalable, and future proof.
Final Thought
So, the next time you're designing a Pega application, don't just ask "what data do I need?" Ask "how will this data live and evolve through the case?" That one question can lead you to smarter, cleaner, and more future-proof designs.
Because in the end, good design isn't just about what you build; it's about how well it holds up when things change.
Related Resources
Don't Forget
- JOIN THE CONVERSATION on Support Center
- FOLLOW @PegaDeveloper on X
