Field techniques and common challenges
The following insights come from Blueprint Delivered™ engagements and partner enablement sessions. They capture practical techniques, common pitfalls, and lessons learned by experienced practitioners that are not always obvious from product documentation. Use them to accelerate discovery, improve collaboration with stakeholders, and create Blueprints that are easier to validate, estimate, and build.
Start the conversation
Experienced practitioners do not wait for perfect requirements. They use Blueprint to create momentum, establish a shared understanding, and improve discovery discussions from the very first session.
|
Start before you have everything |
Run a warm-up with clients new to Blueprint |
|---|---|
| You don’t need a complete Business Requirements Document (BRD) before starting with Pega Blueprint™. Even a quick phone call or brief conversation can provide enough information to create an initial Blueprint, which can serve as the agenda for your next meeting. Presenting a low-fidelity Blueprint to a client is far more valuable than showing them a blank page. Begin iterating from the first session rather than waiting until the last. | If a client is unfamiliar with Blueprint or Pega terminology—such as stages, steps, decisions, and automations—don't begin by addressing their actual problem. Instead, have everyone work on a familiar scenario, like a pet store, a birthday party booking, or a library. Once they are comfortable with the tool and its vocabulary, you can shift the focus to their real project. This approach will significantly enhance the design conversation. |
Use AI Deliberately
The AI Assistant can significantly accelerate design work, but the best results come when practitioners actively guide, review, and validate its output.
| You remain in control of every AI change | Version before using the AI Assistant | Use the AI Assistant from the relevant screen |
|---|---|---|
|
The AI Assistant provides a summary of proposed changes for your review before applying them. Always take the time to assess it. Blueprint acts as a co-pilot, not an autonomous system. Its value lies in AI speed combined with your design expertise. |
Before running any AI Assistant prompt that modifies the Blueprint, make a snapshot. This is important not just before importing. Changes made by AI can sometimes influence areas beyond the specific section you've indicated (for example, a prompt related to Data & Integrations might impact the Case Lifecycle). Creating a version serves as your safe rollback point. | It is important to consider your current screen context (Data & Integrations vs. Case Lifecycle). Working within the appropriate context reduces unintended changes and enhances accuracy in output. |
Make the Blueprint understandable
Blueprint is a communication tool as much as a design tool. These practices help stakeholders understand the solution being proposed and avoid common misconceptions during reviews.
| Rename imported API fields for business clarity | Business rules and decisions do not execute in Preview |
|---|---|
| Technical names from API specifications (such as cust_ref_id, txn_dt_utc, and pmt_amt_gross) are not suitable for stakeholder reviews or previews. After importing a specification, request the AI Assistant to rename the fields to more business-friendly names. Provide context regarding who will use the data and the purpose of the application, and then review the suggested names. | The preview displays every step in the process, regardless of the specific conditions that would affect the path in the actual application. A decision point is used for routing. It's important to inform stakeholders clearly: "In the real application, you would only see this screen if condition X is true." Remember, the preview is a UI prototype, not a functioning simulation. |
Prepare for the build
The most valuable Blueprints not only capture requirements, but also provide enough context and direction for builders to implement the solution with confidence.
| Blueprint captures intent, not final architecture | Notes tell the builder which embedded fields to surface | If integrations are missing, everything is assumed local |
|---|---|---|
|
A blueprint outlines the necessary data and behaviors required for a project, rather than defining the final structure. Its Data Model focuses on answering the question, “What information needs to exist for this case?” instead of “What is the cleanest and most normalized structure?” To ensure clarity, fields that represent real-world entities—such as a customer, a credit report, or an address—should be organized into their own Data Objects before finalizing the blueprint, rather than being left as flat fields. The Blueprint serves as the starting point for shared understanding, not as the concluding step in structural design. |
When you add an Embedded field to a step, Blueprint displays all the fields within that embedded object in the Preview. However, in Pega Infinity™, the Solution Builder can show only specific fields. Use the step's Note to specify which fields should be displayed. For example: "Only show Employer Name, Job Title, and Annual Income; do not include Employment Start Date on this screen." The notes will be included when you export the project. | The estimator and the Solution Builder both default to assuming any Data Object without a System of Record is stored locally in Pega. If an external integration flagged, the build estimate is understated, sometimes significantly. Identify and flag external sources during Blueprinting, not mid-build. Even without full details, mark the object External and add a Note naming the likely source system. |
Reframe fidelity as discovery
As a Blueprint evolves, additional detail often emerges. Experienced teams treat this growing fidelity as a sign of improved understanding rather than uncontrolled scope growth.
| More steps at high fidelity are expected, not scope creep |
|---|
| A blueprint that expands from 30 steps to 45 as you transition from low to high fidelity is beneficial because it reveals previously hidden requirements, such as risk-review automations, document-verification steps, and exception paths. Identifying these requirements early is crucial; discovering them during the build phase can be much more costly. A more comprehensive blueprint leads to more confident estimates, rather than creating larger issues. |
Keep Learning from the Field
Some of the most valuable Blueprint practices come from the experiences of architects, consultants, and delivery teams. Stay connected to the community to continue learning and refining your approach.
Join the Blueprint and App Design Expert Circle to connect with practitioners, architects, and consultants. These circles foster collaborative knowledge sharing and thought leadership in technical design, aiming to elevate application excellence and Pega Blueprint expertise through exchanging best practices, innovative methods, and insights across various business scenarios.
This Topic is available in the following Module:
Want to help us improve this content?