Migrating an existing app from UI-Kit to Cosmos UI Introduction Introduced in Pega 8.3, Cosmos is an opinionated design system that offers end users a new, optimized experience for working with cases. It also offers significant developer productivity gains: in addition to built-in styling, most functionality is provided inside different design templates and, using the model, developers simply map data into template regions, toggle on/off various features, and brand the application with App Studio.

Figure 1 The view of a case in Cosmos and editing the view of the case in App Studio

This article provides guidance for migrating your existing Pega application built on UI-Kit to Cosmos UI using the Pega Platform 8.3. To get started, let’s first talk about the level of effort. Understanding Level of Effort The level of effort to migrate to Cosmos depends on several factors:

• Number of case types. The amount of work to adopt Cosmos is related to the number of case types since each case type has a certain number of flow actions and other screens that needs to be migrated to use design templates.

• Number of overridden rules from UI Kit in ruleset. Cosmos uses some of the same section rules, so you must un-override these sections and the main case type harnesses (Review/Confirm/Perform/New). Later in this article, we’ll show how to use a tool to help identify overridden sections and harnesses.

• Skin overrides and custom Skin formats. Cosmos is an opinionated design system. As such, your application skin should inherit from CosmosSkin and you should re-theme the different components to match your organization’s design system by overriding the Mixins. You should also use App Studio to brand your application, including setting the logo and colors.

• Use of skin formats that were in UI Kit that do not exist in Cosmos skin. Compared to UI-Kit, there are fewer skin formats in Cosmos, which reduces the size of generated CSS and improves performance.

• Sections not based on design templates. This is likely where developers will spend the most time during migration. For high consistency and optimization, the Pega platform offers many section and page level design templates which are already styled for Cosmos. For your app to look its best and to adhere to Cosmos, sections should be refactored to use design templates.

• Custom helper classes for styling. For the same reason as previous point, and to reduce your app’s custom code and complexity, you should also remove custom CSS helper classes used for styling. Instead, you should use the right format from the Cosmos skin, tweak item spacing in a Dynamic Layout’s property panel, or use OOTB common helper classes.

These are things to take into consideration when scoping the level of effort. Keep in mind that the investment in migrating to Cosmos significantly pays off later in that much of the layout and configuration is provided by Cosmos templates and developers override very few rules, which, unlike UI-Kit upgrades, significantly simplifies upgrades to future versions of Cosmos. Now let’s turn to understanding how we’ll configure our development environment. Overview of configuring a development environment for migration Migration is easier if you have the new app and old app running simultaneously with the same underlying data. Meaning, in both apps, we want to show the same existing case data and same existing data for built-in platform features such as Pulse and Spaces. This aides in migration, as you can easily compare the design time and runtime aspects of the old app and new app as you migrate. It also allows better flexibility in deployment; you can have some users adopt the app based on the new Cosmos UI (adopters) while keeping some of the your users on the old UI.

Figure 2 The same case in the old app and the new app, allowing you to easily compare both apps

Here’s an overview of the setup of this approach.

Create duplicate Application, Access Group, and Operator records We’ll configure two Application rules, one for the current application and one for the application based on Cosmos UI. We’ll configure both application rules to have the same name, but different versions. It is important to use the same name in both Application records. If you do not use the same name, you’ll still have the same case data between apps, but the existing data for built-in features like Pulse and Spaces will not surface in the new app because data for those features is keyed off the application name. We’ll also configure two Access Group records, one pointing to the current app and one pointing to the app based on Cosmos UI. Finally, we’ll configure two admin operator records, one pointing to each access group. This allows us to easily work with both applications simultaneously instead of having to constantly switch applications. Using rulesets to manage changes, not branches We’ll change rules in the new app during migration, and we’ll manage these changes with ruleset versions, not branches. Why wouldn’t we use branches? Since branches (or “branch rulesets”) are actually rulesets, they cause undesired behavior during migration. One such issue is marking rules as Withdrawn, which you’ll likely need to do. If you mark a rule as Withdrawn in a branch, the rule resolver will correctly ignore the rule in the branch, but it will then choose the rule in the original ruleset down the stack, which still contains the overridden rule. For example, in UI-Kit apps, developers often overrode rules such as the Perform harness into an app ruleset. As you’ll see later, Perform and other rules should not be overridden in Cosmos apps, so we need to un-override Perform so that our application uses the one from Work- in the Theme-Cosmos Ruleset. If we withdraw it in a branch, then here’s the ruleset stack with undesired behavior:

Class Ruleset Rule availability

Notes

MyApp-Work- MyRuleset_Branch_Perform

Withdrawn In a branch ruleset, we mark rule as withdrawn

MyApp-Work- MyRuleset:01-01-01 Available rRule resolver picks this one instead, which is still overridden

Work- Theme-Cosmos Available This is the one we want the rule resolver to pick.

This problem is avoided by using an incremented ruleset version where we mark the rule as Withdrawn in the incremented ruleset. The ruleset stack instead looks like this, and the rule resolver will pick the rule we want from Theme-Cosmos.

Class Ruleset version Rule availability

Notes

MyApp-Work- MyRuleset:01-01-02 Withdrawn We mark rule as withdrawn in incremented ruleset

MyApp-Work- MyRuleset:01-01-01 Available This is the bad one, and rule resolver will skip it

Work- Theme-Cosmos Available aThe rule resolver will pick up this one, which is what we want

So, we’ll use incremented ruleset versions in the new app when a ruleset has rules that need to be migrated or un-overridden. Importantly, in the old app, we’ll cap those same rulesets to a specific version to prevent the old app from breaking. Here’s a diagram summarizing this approach and what we’ll configure in this article. On the right, we have two applications running side by side, both using the same core business logic but built on different themes. The UI for Cosmos application has the incremented ruleset and the old application’s ruleset is capped at 01-01-01.

Got it? OK, using a sample application, let’s actually do the steps to configure both apps in our environment. Steps to configuring our development environment Our existing Application definition specifies UI-Kit as the built-on, contains an application skin that inherits from UI-Kit’s pyEndUser skin, and specifies app-specific rulesets.

1. Save-As your existing operator id. Since this will be the id we used to explore the old app built with UI-Kit, give it an appropriate name. Don’t log in with it. Remain logged in with your existing developer ID, which we’ll soon update to point to the new app.

2. Save-As CarWash:01.01.01 Application rule and set version to Carwash:01.01.02

Now we have the same application record for our new Cosmos app, but a different version.

3. In the new CarWash:01.01.02 app def, remove UIKit built-on and add Theme-

Cosmos:01.01. Leave the skin name for now; we’ll change that shortly.

4. In CarWash:01.01.01 app definition, (old app), cap the CarWash:01-01 ruleset to the

latest version, 01-01-01. This will keep our old app from breaking when we make changes.

5. Open CarWash1 ruleset. Lock the 01-01-01 version to prevent accidental changes, and create a new ruleset version, CarWash:01-01-02.

6. Verify your ruleset now looks like this.

7. Save-As your existing Access Group. Name it the same but with “Cosmos” appended. Set the version to 01.01.02. Leave the portals alone for now; we’ll change them shortly.

8. Open your operator record. Add your new Access Group and set it as default. Don’t forget to save the record!

9. Change over to the new application by selecting “Switch Application” and selecting the other version of your app that is based on Cosmos.

10. Return to your new access group. Remove pyCaseManager7 and pyCaseWorker portals (these are from UI Kit and do not exist in Cosmos). Add “UserPortal”, the single end user Portal from Theme-Cosmos. Since this is the AG for your administrator, Leave the default portal as “Developer”.

11. Create a new Skin by selecting Create > User Interface > Skin. Set a name for your new skin, enable “Inherit component formats and mixins from an existing skin”, and enter CosmosSkin as the skin to inherit from.

12. Return to your new application record for Cosmos app. Change the Skin to your newly

created skin

At this point, you can actually launch UserPortal from Designer studio, and you’ll see the Cosmos Home page of your app. Remember, both apps use the same data: If you happen to have any open assignments from the old app, they’ll show up in the To do widget. Application level Pulse posts created in the old app will render in the Pulse section of the new app. Don’t open one of your existing cases yet. If you do, you’ll get an error with a bad UI. In the next section, we’ll migrate the view of a case to Cosmos.

Migrating the view of a case Migrating a case to Cosmos requires un-overriding a few rules you should no longer override, then creating a copy of a section rule from Theme-Cosmos ruleset. Un-overriding rules you should no longer override In applications built on UI-Kit, developers often override the following rules to customize. In Cosmos, they should not be overridden. Shortly, we’ll cover steps to un-override these rules, so refer back to this list. • Harnesses

o Review o Confirm o Perform o New

• Section rules o pyCaseMain o pyCaseMainAddInfo

Designer Studio contains a handy tool you can use to help you find the above UI-Kit rules you have overridden in your application’s rulesets.

1. Select Configure > Application > Development > RuleOverrides

2. From the “Base” column, select UI-Kit-7.

3. From the “Masked by” column, select your application rulesets for may contain overridden rules from UI-Kit.

4. Enable “Group by rule type” 5. Scroll down and click submit.

6. You’ll get a report categorized by rule type with all rules in your selected rulesets that

override a UI-Kit rule. Expand a category such as Harness

In the below example, the Review harness is being overridden in both of the app-specific rulesets we selected above.

7. For both of these overrides, use the Open button to open the rule. 8. Save-As them into the incremented ruleset version and mark them as Withdrawn. 9. Refer back to the list of UI-Kit rules that should not be overriden at the beginning of this

article and repeat these steps for each rule that needs to be un-overriden Create a pyCaseMainInner from Theme-Cosmos ruleset It’s expected that developers have previously overridden the section rule pyCaseMainInner (which was based on a UI-Kit design template) to customize the view of a case. If so, it won’t yet render correctly in your new app, because Cosmos uses a new design template for pyCaseMainInner and the existing one points to a UI-Kit template. Don’t try to just fix up your existing pyCaseMainInner. It’s much easier to start with fresh copy of pyCaseMainInner (Work-) from Cosmos, then iteratively customize. Start with one of your case types and do the following:

1. Use search in Designer Studio to locate and open pyCaseMainInner from class “Work-“ in the Theme-Cosmos ruleset. (If search index is not enabled on your system, you can also find it in the records explorer)

2. Double check that you opened the one from CL: Work- and RS: Theme-Cosmos:01-01-01

3. Save-As it into your own ruleset and specific a case-specific class

a. Important: Don’t specify “Work-” as the class when saving into your ruleset, as it will apply to all cases. Instead, specify a case-specific class.

4. Now that you have a default, case specific version of pyCaseMainInner, re-run your Portal and open one of your existing cases. We’re now viewing our existing case with the default view of a case offered by Cosmos. We see a summary panel on the left with a case header; default edit and more menu buttons; the case status, priority, created, and updated fields; and default tabs, one that shows you all the fields in your case and the other the pulse feed of the case. In the main work area, your flows are the same and you can run them. To the right is a collapsible Utility panel with utilities including Followers and Files & Documents.

This is a good stopping point. Now let’s turn to are other customizations you can do mostly using App Studio. What’s next? Now that you can view your cases with the default configuration, you can continue rapidly customizing your application mostly using only App Studio.

Refactor sections to use design templates You should edit sections used in your CarWash:01-01-02 ruleset to use the design templates available in Cosmos UI. Your legacy sections will continue to be used in your UI-Kit based application, while the Cosmos based application will use sections that leverage design template and that are editable in App Studio. Customize the Summary Panel You can also customize the summary panel by following the steps detailed in this article:

Customizing the Case Summary panel in Cosmos https://community1.pega.com/community/pega-support/question/customizing-case-summary-panel-cosmos

Customize the vertical tabs on a case Built as Single Page Application where only certain parts of the screen change, the vertical tabs on a case, located under the summary panel, allow you to switch views within your case. By default, you currently have two vertical tabs on your case, Details and Pulse. Using App Studio, you can add additional tabs by dropping sections into the main work area region in the pyCaseMainInner section rule.

Brand your application You can also brand your application with App Studio. In App Studio, select the Settings button. Then, select Theme from the settings menu.

You can change the application icon and application anem that renders in at the top of the left navigation ribbon. You can also change color mixins the font styling.

For a demo of some of these customizations and to learn more about Cosmos in 8.3, check out the following ten minute Tech Talk from the Pega Community.

Tech talk: Accelerate your workflow with Cosmos UI https://community.pega.com/video-library/accelerate-your-workflow-cosmos-ui

Watch the Pega Community for additional upcoming articles about Cosmos. If you have questions about Cosmos, be sure to post to the Pega Community.