Discussion
Customizing a Cosmos Rules application
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
1) For new application which are starting on 8.4 and want to leverage the cosmos design system , what are the options available to use this enterprise skin and what is the best practice .
Use a skin that inherits from CosmosSkin - do not add more formats - use the mixin override to change the default theme and branding. Use helper classes as much as possible
2)For existing applications which are on upgrade to 8.4 we have added our enterprise skin to the inheritance of the application skin and reverted the mixins of the application skin to the inherited enterprise skin and we did face any issues .
Some of the mixins are similar between the pyEndUSer skin in ui-kit and CosmosSkin. You might be able to reuse the changes. In general migrating the entreprise skin will depend on how many new formats were added and how many mixin override were used. In general, I would recommend to restart from a new skin that overrides from CosmosSkin and reapply the mixin override changes.
You should not override the CosmosSkin - this makes it difficult to use a new version of Cosmos - this best practice was also applicable to ui-kit - We have enforced this best practice by making CosmosSkin final
@Richard Marsot -
We are planning to upgrade call center application from 7.3.1 to 8.4.1. We are trying to explore cosmos design system this application. Shipped sample HC-CRM application doesn't include Cosmos application; still referring to UI-Kit. Does cosmos design supports HC-CRM based application?
@Richard Marsot - Hi Richard , We have an firm wide UI Kit in terms of styling/ fonts / colors / background which all applications have to adhere to . We are starting some new application on 8.4 and upgrading existing applications to 8. 4 because of which i cannot create a new skin rule inheriting from Cosmos Skin
We have build an enterprise wide skin rule mostly mixins like styling/ fonts / colors / background and some helper classes and base styles . For example the checkbox and radio buttons look different in our skin than the cosmos theme .
Questions:-
1) For new application which are starting on 8.4 and want to leverage the cosmos design system , what are the options available to use this enterprise skin and what is the best practice .
2)For existing applications which are on upgrade to 8.4 we have added our enterprise skin to the inheritance of the application skin and reverted the mixins of the application skin to the inherited enterprise skin and we did face any issues .
I noticed that the Cosmos skin is a final rule and since we want to have our enterprise skin being used in new applications as well existing applications what is Pega recommendation here .
Appreciate your thoughts .
Thanks
Dinesh