methodology-case-data-modeling

name	methodology-case-data-modeling
description	Use this skill when the user asks to design or review a data model, choose between Case Type vs. Data Object, model a business process in App Studio or Dev Studio, add or change Case Types or Data Objects, or structure fields, relationships, primary fields, business keys, or attachments within a Pega application.

When to Use

• The request mentions "Case Type", "Data Object", "Data Model", "Fields".
• The user provides a business scenario and asks for modeling guidance.
• There is a need to change the data model to meet new or evolving requirements.
• The user asks how to decide between embedding data vs. referencing it.

---

Overview

Object Set

Concept	Purpose	Class Hierarchy
Case Type	Procedural workflows — has stages, steps, SLAs, assignments	<Org>-<App>-Work-<CaseName>
Data Object	Reusable, non-process entities — CRUD-driven	<Org>-<App>-Data-<Entity>

pxObjClass is stamped on every instance and drives rule resolution. It identifies which class an object belongs to — never omit or override it.

---

What Makes a Good Case Type

• Has a process lifecycle — stages, steps, and a resolution.
• Has a deadline or SLA — time-sensitivity is a strong signal.
• Involves multiple actors or systems — human tasks, integrations, or approvals.
• Examples: Loan Application, Service Request, Claim Processing.

---

What Makes a Good Data Object

• Information managed primarily via Create / Read / Update / Delete.
• Entities referenced by cases but not owned by a single process.
• Examples: Customer, Address, Product, Policy.
• When unsure whether something is a Case Type or Data Object — choose Case Type.

---

Relationships

Between Case Types — Parent / Child

Use when one case depends on or spawns another (e.g., a Service Request spawns a Field Visit). The child case inherits context from the parent and can run in parallel or sequentially.

Between Case and Data Object — Reference or Embedded

Pattern	When to Use
Reference (Page Property)	Data lives in a System of Record; the case only links to it. Changes in the SOR are reflected automatically.
Embedded (Embedded Page)	Data is unique to this case instance and stored inside the case BLOB (pzPVStream). Use for snapshots or derived data.

Between Data Objects — Peer

Use for lookup or join relationships (e.g., Order → Product). No lifecycle dependency.

---

Fields, Primary Fields & Key Parts

Primary Fields — Mark the most important properties of a Data Object (e.g., "Full Name", "Account Number"). These auto-populate Create/Edit/Summary forms in the visual designer. Reorder thoughtfully; removing a primary field impacts generated views.

Key Parts — Defined on the General tab of the Class rule. One or more properties are nominated as Key Parts; their concatenated values form the pzInsKey — the physical primary key for every record in the Pega database. In the low-code designer, this surfaces as the Identifier field (defaulting to pyGUID). Define Key Parts before go-live — changing them post-production alters pzInsKey structures and causes data integrity issues.

Automatically generate a unique ID (Identifier toggle)

• When enabled (the default), Pega assigns pyGUID as the record's Identifier. The platform generates the value at record creation; no user input is required. Every save produces a new, unique record — no deduplication occurs. Use for entities where business-meaningful identity is irrelevant (e.g., audit events, case-level snapshots).
• When disabled, the architect designates a meaningful property as the Identifier (e.g., CustomerNumber, PolicyID). Pega uses this value to construct pzInsKey. If a record with the same Identifier value already exists, the platform updates it rather than inserting a duplicate. Use when records must align with a System of Record or when deduplication by a real-world key is required. Define the Identifier before go-live — changing it post-production restructures pzInsKey for all existing records and causes data integrity issues.

Calculated Fields — Use when a value is always derived (e.g., Total = Quantity × Price). Backed by a Decision rule or expression; do not allow manual override.

Attachment Fields — Add when attachments must be addressable in forms or business logic (e.g., a signed contract linked to a specific case stage).

To make a field searchable or reportable, expose it as a database column — by default, Pega stores all properties in a compressed BLOB.

---

Creating Data Objects

Creating Data Objects is not supported through the agent. This operation must be performed directly in the Data Designer in App Studio.

---

Case Type Design

Name after real business processes

Case types should map to actual business processes, not technical operations:

• Good: ServiceRequest, InsuranceClaim, LoanApplication
• Bad: ProcessData, RunBatch, CallExternalSystem

Use stages to model lifecycle phases

Stages represent major phases of a business process:

Create → Review → Approve → Fulfill → Resolve

Each stage should have:

• A clear entry and exit criteria
• One or more steps (assignments or automations)
• A meaningful name from the business domain

Separate work classes from data classes

• Work classes (-Work-) are for case types — things that have a lifecycle
• Data classes (-Data-) are for reference data — things that are looked up or stored
• Don't put case logic in data classes or static data in work classes

---

Data Model Design

Use meaningful property names

Properties should describe what they hold, not how they're used:

• Good: CustomerEmailAddress, PolicyEffectiveDate, ClaimAmount
• Bad: Field1, TempValue, Data

Use appropriate property types

Use Case	Property Type	Notes
Single value	Single Value (Text, Integer, etc.)	Most properties
Related entity	Page	Embedded object — one related record
List of entities	Page List	Embedded list — multiple related records
Key/value pairs	Page Group	Keyed collection — lookup by key
Fixed choices	Single Value with local list	Constrained values
Cross-case reference	Page (with automatic retrieval)	Point to a data page that loads the referenced case by ID

Design for reuse with Data Types

If multiple case types need the same data structure (e.g., Address, ContactInfo), define it as a Data Type:

• Data Types get their own class, properties, views, and data source
• They can be embedded in any case type as a Page or Page List property
• Changes to the Data Type automatically apply everywhere it's used

---

Tips

• Access control: Any new Case Type or Data Object requires explicit RBAC permissions. Update the Access Role rule (AccessRole-) to grant the appropriate personas Create/Read/Update/Delete access — otherwise, users cannot interact with the new type.
• Case vs. Data — context is king: A vendor list in a Purchase Request app is a Data Object. The same vendor list in a Vendor Management app may be a Case Type (with onboarding workflows, SLA tracking, and approvals). When in doubt, choose Case Type.
• Embedded vs. Reference — choose intentionally: Embedded data is fast to access but creates data drift if the source changes. Reference data stays current but introduces a dependency on the SOR's availability.
• Visual Data Model: Use App Studio's visual data modeler to audit relationships across Case Types and Data Objects before delivery.
• Flat data model: Putting everything in one class makes rules unresolvable and breaks specialization — always separate work, data, and integration classes.
• Overloaded case type: One case type handling multiple unrelated processes creates unmaintainable flows — create separate case types and use child cases for dependencies.

---

References

Skill	When to load
rules-rule-obj-property	Creating or modifying properties on a Case Type or Data Object
rules-rule-declare-pages	Creating or configuring Data Pages for a Data Object