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 Notes
availability

MyApp-Work- MyRuleset_Branch_ Withdrawn In a branch ruleset, we mark rule

Perform 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 Notes
availability

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.