This document covers what are the dos and don’ts about how to customize a Cosmos rules application

1/ Stay in App Studio for UI editing

While the App studio editing environment is not as feature rich as Dev Studio, it is actually the best approach to create a guardrail compliant application and ensuring that the customization will be able to work when switching to Project fnx and the new UI rendering architecture https://community.pega.com/knowledgebase/products/platform/project-fnx

Sections in Cosmos Rules that are expected to be customized and edited have been marked as 'editable' in App Studio and should be the starting point for all your customization - this include

• Case Summary panel - https://community1.pega.com/community/pega-support/question/customizing-case-summary-panel-cosmos
• Main Case page with the vertical tabs and utilities
• Case flow actions

Going into dev studio and overriding any section from the Theme-Cosmos ruleset into your application is going to lead to upgrade issues and issues to adopt the new UI rendering architecture

You should also use App Studio for creating and editing case types and data types

2/ SPA only - Must use a single page Dynamic Container

Cosmos Rules is based on a single page application (SPA) design and as such only the single page dynamic container is supported and must be used. This is similar to the Case Worker portal in UI-Kit

While you can go in dev studio and override the UserPortal section that contains the Dynamic container to a multi-doc DC, this will not work for several reasons:

• multi-doc DC is opening every case inside an iframe and will cause performance issues since the browser needs to parse all the JS and CSS when opening a case - SPA allows to load the JS and CSS once and use it for ALL pages
• multi-doc is a deprecated configuration and will generate a guardrail warning - While you can use it for your UI-kit based app, it should not be used with Cosmos and will not be supported in the new rendering architecture based on React (fnx project)
• it will cause conflict with the Ajax containers that are used for creating new cases or performing assignments.

3/ Do not customize the OTB UserPortal

Cosmos Rules provides an OTB portal called 'UserPortal'. This User portal follows our best practices and is an auto-generated portal that must be edited through the 'Channel and interfaces' landing page.

You should not resave the UserPortal into a new portal - To change the name of the portal visible in the browser tab and the name of the application, go to App Studio and use the 'Theme' landing page under the Settings page.

Also you should not need to create multiple portals for each type of user - in Pega 8.3, you can use the role based management from App studio using the 'Access' page under the Users category

Keep the main portal as a collapsible ribbon on the left and the main content. Any customization of the OTB portal will lead to some upgrade issues and a lot of override CSS

4/ Use the Case Main UI template

The case main template in Cosmos Rules is used to provide a 3 columns region with the summary panel, the main content and the utilities.

While it is possible to change the design template that is used by the pyCaseMainInner section, you should not change the template but rather add section and properties for the different regions that are exposed

5/ Use the CosmosSkin

Cosmos is an opinionated design system and using the new Cosmos-Theme will require your application to adopt the Cosmos Design system and user experience that comes with it

You can re-theme the OTB Cosmos Rules UI by creating a skin in your application that inherits from the CosmosSkin but you should not create a new skin or use your old application skin used with UI-Kit with the new Cosmos-Theme. We recommend to override the different mixins available in the CosmosSkin into your application skin