Tech-Docs

Step-by-Step Guide: Migrating Pega Applications to Constellation UI Using Constellation Modernization Assistant

Prerequisites and Preparation

• Supported Platform: Your application must be running on Pega Infinity™ 23.1.x or later for migration. The tool requires Constellation Modernization Assistant, which you can download from the Pega Marketplace.
• Access/Privileges: You must have SysAdm4 (or higher) privileges.
• Application Readiness: All Ruleset versions in your app (and its built-on apps) should be locked. Your app must have at least one Case Type.
• Technical Know-How: Ensure you have at least one team member familiar with both your current app and the Pega Constellation design system.
• Backup and Clean-Up: Address technical debt, ensure data model readiness, and perform a skim of application rulesets if needed.

Phase 1: Discover

1. Application Walkthrough: Conduct a walkthrough (with business and technical stakeholders) to understand business-critical features and existing UI complexities.
2. Feature Identification: Use a top-down approach to map granular application features and reusable assets (using diagrams or feature maps).
3. Readiness Assessment: Understand components (data pages, integrations, background jobs) and identify objects reusable in Constellation.
4. Knowledge Building: Complete Pega Academy training on Constellation UI and its patterns if team members are new to this architecture.

Phase 2: Prepare and Analyze (Analysis Mode)

1. Install the Assistant:
   • Download the Constellation Modernization Assistant from the Pega Marketplace and install it in your Pega environment.
   • Add your application as a component in the system runtime context.
2. Run Analysis:
   • In Dev Studio, open the Constellation Modernization Assistant landing page and select your app for analysis.
   • Start analysis. The tool scans all sections, flow actions, case types, and properties.
   • The results are stored as Pega-Constellation-Migration class instances.
3. Review and Export Reports:
   • Once analysis completes, review the categorized summary—including number and type of problematic rules (minor/major/complex/critical).
   • Download the Excel file listing all identified issues by rule. Use this for collaboration and tracking progress.
4. Resolve Issues:
   • Fix issues as per documentation links provided—a number of common issues may be auto-fixed by the tool, but some require manual intervention (e.g., unsupported section components).
   • Typical issues: unsupported layouts, controls, or old patterns not compatible with the Constellation paradigm.
   • Test app after fixes to ensure it still works as intended.

Phase 3: Migrate (Migration Mode)

1. Lock Current App Rulesets: Lock all rulesets in the application and its built-ons, as migration creates new rulesets and ports rules.
2. Initiate Migration:
   • Open the Constellation Modernization Assistant landing page.
   • Confirm that the analysis summary is present and that all blockers are resolved.
   • Click the “Migrate my application” action.
   • Provide a name for the new (migrated) app (e.g., “Demo Account Management on Constellation”) and choose whether to use a new ruleset or branch (branch recommended for collaboration).
   • Start migration. The process will:
     • Convert section rules to views.
     • Update flow actions, set properties as relevant records.
     • Add Case Types, Data Types.
     • Retain existing portals and add a new Constellation Work Portal with App Studio access.
   • Keep the Assistant tab open—duration depends on app size.
3. Verify and Update Access Group:
   • Once migration is complete, a new access group will be created for the migrated app.
   • In Dev Studio, go to Author → Operator, and set the Application Access to the newly created access group (e.g., DemoAccoun:Authors). Save.

Phase 4: Adopt and Finalize

1. Test Thoroughly: Perform comprehensive UAT and regression testing. Address issues with data flows, integrations, and custom controls not fully covered in migration.
2. Review Limitations: The tool doesn’t migrate all components (e.g., tables, repeating dynamic layouts, DX components may need manual migration). Verify and manually redesign unconverted parts as needed.
3. Knowledge Transfer: Share experiences/learnings with your team. Refer to Pega Academy materials and Constellation Adoption Playbook for best practices.
4. Rollout: After successful user acceptance, plan the production migration rollout.

Key Tips & Best Practices

• Address technical debt and UI complexities before starting migration.
• Use Analysis mode early and often during major development phases—not just prior to migration.
• Keep detailed documentation of modifications and newly migrated elements.
• Consider a phased approach for very large apps: migrate and roll out business-critical features first, then incrementally modernize remaining modules.
• Take advantage of automated and downloadable Excel summaries for project tracking and reporting.

Reference Workflow Example (Table)

Phase	Key Actions
Discover	Walkthrough, map features, knowledge readiness
Prepare	Install Assistant, run Analysis, fix issues, export reports
Migrate	Lock rulesets, start migration in tool, create new app, update access group
Adopt	Deep testing, train team, address manual migration, roll out in production

For more detail on tool usage, refer to the Constellation Modernization Assistant component in Pega Academy and consult official documentation in your Pega environment. This procedure ensures a robust, manageable path from traditional UI architectures to modern, low-code, business-focused Pega applications.

• Constellation Modernization Assistant Overview (Pega Academy)
• Migrating an Application to Constellation (Pega Academy Challenge)
• Constellation Modernization Assistant Marketplace Component
• User Experience: Modernization Assistant Experience (Pega Support)
• Addressing Application Migration Issues (Pega Academy Challenge)
• Constellation Modernization Assistant Mission (Pega Academy)