Skip to main content

Blueprint practices and guardrails

You have worked through the Blueprint Delivered™ approach as a Solution Designer, from generating an initial Blueprint to validating the design with stakeholders. The guidance below summarizes the most important practices to carry into your own engagements.

Blueprint design

Practice Why it matters
Provide relevant, structured context What Pega Blueprint™ generates depends on the relevance and structure of your input. Use available artifacts, including business requirements documents (BRDs), standard operating procedures (SOPs), and application context, to guide generation. Well-defined inputs produce more useful designs. Vague or unrelated inputs produce generic results.
Design one journey at a time Generate each Case Type in a focused pass. Trying to design everything at once can produce shallow results. Complete the primary Workflow before moving to other Case Types. Finishing one Workflow end to end improves clarity, fidelity, and stakeholder validation.
Choose Smart Shapes deliberately Generate each Case Type in a focused pass. Trying to design everything at once can produce shallow results. Complete the primary Workflow before moving to other Case Types. Finishing one Workflow end to end improves clarity, fidelity, and stakeholder validation.
Choose between the Case Data Model and Data Objects Use a Data Object for a reusable business entity or concept, such as a customer or Credit Report. Use the Case Data Model for information specific to the Case workflow. When in doubt, ask: Would this information still have meaning outside this Case?
Write meaningful field descriptions Field descriptions help Blueprint generate realistic sample data in Preview and preserve design intent for Authoring. Empty descriptions can produce generic results. A useful description explains the field’s purpose, expected values, and relationship to other fields.
Validate early and often in Preview Use Preview throughout the design process to validate workflows, data, and user interactions with stakeholders. Early validation surfaces gaps and reduces rework during Authoring.
Design for intent, not implementation Blueprint defines what the application should do, not every Rule used to build it. Focus on business intent and meaning. Implementation decisions are made during import and Authoring.
Use Notes to guide the Solution Builder When Blueprint cannot represent a requirement directly, add a Note to the relevant Workflow Step or Data Object. Use Notes for essential guidance, such as specific UI controls, complex routing logic or field conditions, declarative rules, Data Page strategy, Adaptive and Predictive Models, or integration runtime rules. Notes travel with the Blueprint export and appear to the Solution Builder throughout Authoring.

Blueprint Recommendations

When you download a Blueprint file, Blueprint analyzes the design and presents recommendations for gaps that might affect fidelity, consistency, or completeness during Authoring.  These recommendations may highlight missing Persona access settings, unreferenced Data Objects, or unused fields.

How to access Recommendations

  1. On the Summary step, click Download Blueprint.
    Pega Blueprint Summary screen with options to download, share, and view history.
  2. If the Blueprint recommendations dialog opens, review each recommendation and select its link to open the relevant section.
  3. Make the necessary changes, then return to Summary and select Download Blueprint again.
  4. Repeat as needed until you have addressed each recommendation.
  5. If a recommendation does not apply or will be addressed during Authoring, select Download anyway.

When is Download anyway acceptable?

Select Download anyway when:

  1. You understand the recommendation and have a clear plan to address it during Authoring.
  2. You have determined that the recommendation does not apply. For example, a Data Object used only as a reference might not need to appear in a Workflow.
Caution: Do not ignore recommendations by default. Consciously decide whether to address each recommendation now or later.

Versioning

Blueprint versions are read-only, point-in-time snapshots of the design. Use them as checkpoints before significant changes, reviews, or handoffs. Versions also provide a baseline that the team can view or restore if the design changes unexpectedly.

When to create a version Why
Before importing into Pega Infinity™ Capture the approved pre-import design so the team can trace the Blueprint used to create the application foundation.
Before a significant structural change Adding a Stage, removing a Case Type, or restructuring the Data Model can be difficult to reverse. Create a version first so you can compare or restore the earlier design.
After each workshop or design sprint Capture the agreed state at the end of each session and preserve a record of the decisions made.
After stakeholder approval in Preview Preserve the validated design as a baseline for import or further refinement.
Before extending an exported Blueprint Preserve the starting state before changing the design of an existing application.

Collaboration

Blueprinting is a collaborative activity. A designated Solution Designer remains accountable for the Blueprint, but the decisions it captures require input from business stakeholders, subject matter experts, and the Solution Builder. Working in one shared Blueprint keeps the design aligned and avoids competing copies.

How to share a Blueprint

  1. On the Summary step, click Share.
    Pega Blueprint Summary screen with the Share option selected.
  2.  The owner can invite collaborators by email and assign one of the following access levels:
    1. Co-owner: Has the same permissions as the primary owner, including the ability to share and delete the Blueprint.
    2. Editor: Can view and change the Blueprint.
    3. Viewer: Can view the Blueprint and use Preview but cannot make changes.
Tip: Before inviting Editors, create a version to preserve the review baseline. Blueprint records collaborator changes in its history, and you can restore an earlier version if necessary.

Below is a guide outlining the principles for sharing a Blueprint to ensure effective collaboration.

Principle Guidance
Share early, not only at sign-off Invite the Solution Builder and key contributors early to surface implementation concerns and align on intent before finalizing the Blueprint.
Validate in Blueprint, not in documents A shared Blueprint lets stakeholders explore the live Preview. This produces more useful feedback than a static screenshot or PDF.
Create a version before review Preserve a clean baseline of what stakeholders reviewed and approved before inviting Editors to make changes.
Use Viewer access for business stakeholders Most business stakeholders do not need Edit access. Viewer access lets them review the Blueprint and explore Preview without changing the design.
Agree on accountability and access Designate a team member to remain accountable for the Blueprint. Assign Co-owner access only when another person needs sharing or administrative permissions.

Check your knowledge with the following interaction:

This Topic is available in the following Module:
If you are having problems with your training, please review the Pega Academy Support FAQs.

Did you find this content helpful?

Yes
No

Want to help us improve this content?
Suggest an edit

We'd prefer it if you saw us at our best.

Pega Academy has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

Close Deprecation Notice