Cosmos React PDF

Cosmos React
Pega Platform version 8.7 expands the scope of Cosmos React and its underlying view-based architecture to support the latest
open-source technologies and UI solutions. Cosmos React features a curated authoring experience that helps professional and
citizen developers build an application in the low-code App Studio environment, while also providing flexible orchestration.
Feature set
View-based applications combine the latest technology with Cosmos React, a dedicated version of the Cosmos design system.
Evaluate whether the Cosmos React setup supports your use case before building a new application, and continue using
section-based applications with Theme Cosmos where the classic architecture best serves your business needs.
For a list of supported and unsupported features in Cosmos React applications, see Choosing a UI version, UI version
comparison, and Feature limitations in Cosmos React.
For existing applications, the best practice is to keep your current front-end setup, whether it is Theme Cosmos or Theme UI-
Kit.
Theme Cosmos
Theme Cosmos is a section-based version of the Cosmos design system that helps you build powerful case management
applications in compliance with best practices and guidelines. By relying on a library of ready-to-use templates, patterns, and
themes, Theme Cosmos helps you reduce development effort and focus on your section-based application.
Both Theme Cosmos and Cosmos React offer efficient, user-friendly, and productive UI experiences for professional users.
Both application types are fully supported, with additional tooling in continued development.
For more information, see Feature limitations in Cosmos React and Theme Cosmos.
Cosmos design system

Pega Platform uses the Cosmos design system as its main product design resource. The system provides a consistent library of
components that form the entire user experience for both customer-facing applications and Pega Platform itself.
Cosmos relies fully on ready-to-use page structures, interaction pattens, and prefabricated UI components for more efficient
development and performance. In addition, a more modern design and increased focus on intuitiveness help save time on
application updates and user training.
Depending on the architecture that you use, the Cosmos design system has two versions: Cosmos React, which serves the
view-based architecture, and Theme Cosmos, which relies on sections.
When creating a new application, you can choose between a view-based Cosmos React UI, or a section-based Theme Cosmos
UI, which can be further expanded to include hybrid React components.
For more information on Cosmos, see the Pega Cosmos design system website.
Constellation UI Service
Cosmos React relies on the Constellation UI Service, a static content microservice that delivers front end components and
other static content to the browser. To obtain configuration, context, and data for Cosmos React applications, the
Constellation UI Service client interacts with the server exclusively through DX APIs. By keeping the container separate from
other services, you avoid dependencies, give developers tools to create new UI components without interfering with other
work, and improve overall application performance.
For more information, see Constellation UI service.
Cosmos taxonomy
The Cosmos design system maximizes productivity for the core guided workflow constructs of the Pega Platform. By
utilizing Cosmos' extensive library of ready-to-use page structures, interaction patterns and UI components, you can
deliver excellent interfaces while focusing on critical business logic and data, rather than building a UI from the ground
up.
Configuring Cosmos React
Cosmos React offers a new low-code paradigm for developing applications quickly by using out-of-the-box components
built around the concept of configuration. This still-expanding framework creates products that require less customization
and one-off development, but promote a slightly different approach compared to application creation.
Configuring portals
Portals represent the main interface of your application, and provide users, such as case workers, managers, and
customers, with the tools that they need to do their work. By configuring portals, you can set up an optimal environment
for each of these user groups with minimal effort.
Working with views
You use views to display and collect information in your applicaton, for example, to fulfill requests or process cases. By
setting up intuitive views and populating them with fields, you help users process their work with less effort.
Branding your application
Design systems help you introduce consistency to the applications that you build. By choosing to use a design system,
you can scale your designs to maintain a unified presence across a number of platforms with less effort.
Configuring an accessible UI
Reach the broadest audience for your application by building a user interface that addresses the needs of users with
disabilities. Designing a UI for assistive technologies, such as screen readers, is important for compliance and provides
essential access to users who have visual impairments.
Internationalization and localization
Internationalization and localization help you reach a wider audience by making your application available to users who
speak different languages. Localization is the process of translating application text and converting locale-specific
components, and internationalization is a general design principle that makes software more convenient to localize.
Embedding Pega Platform UI in web pages
You can choose parts of Pega Platform UI that suit your business needs and make them available to users of your
websites by creating a Web embed channel and inserting the auto-generated markup into any web page.
Integrating Cosmos React applications
Cosmos React is an opinionated design system that promotes out-of-the-box, low-maintenance solutions. However, its
architecture includes tools that allow experienced developers integrate Cosmos React applications with other design
systems or older applications that rely on sections.
Constellation UI service
Cosmos React applications rely on a static content microserivce that delivers front-end components and other static
content to the browser.
Configuring Docker authentication
Set up the first download of a Docker image from a Pega repository by configuring a Docker authentication config.json
file. This configuration is required when installing the Constellation UI Service with Docker for the first time.
Cosmos taxonomy
The Cosmos design system maximizes productivity for the core guided workflow constructs of the Pega Platform. By utilizing
Cosmos' extensive library of ready-to-use page structures, interaction patterns and UI components, you can deliver excellent
interfaces while focusing on critical business logic and data, rather than building a UI from the ground up.
The key components of a Cosmos UI include the home page, landing pages, and the full case page. You can configure each of
these components in the low-code authoring environment of App Studio.
Cosmos portal
Components of a Cosmos portal
Portal
Helps you to define how people interact with your application. Portals represent the main interface of your application,
and provide case workers, managers, and other users with the tools that they need to do their work.
The application displays landing pages and case pages in the main area of the portal. The left side of the portal features
an expandable menu that helps the users navigate the application and access notifications and recently viewed items.
Depending on your business needs, the portal can also include either a full application header, or a compact header in the
main menu consisting of an application name and logo. For more information, see Configuring portals.
Application header
If space is not a priority, you can add a header to the Cosmos portal. Although global search is available away from the
header in the main navigation, the application header can help your users identify the application at a glance, and
provides a central location for search. The header includes an application icon, a search bar, and an operator menu icon.
For more information, see Defining the application header.
Main navigation
Helps users navigate to landing pages, create new cases and – if the application has no header – access search features.
The menu also holds notifications and recent events, as well as user settings in portals in compact mode. If your
application does not use a header, the main menu also includes a global search box. For more information, see
Organizing the main navigation for a portal.
Preview panel
Provides users with tools to engage with a business object without context switching. The preview panel reuses the
structure and style of the summary panel of the full case page. For more information, see Configuring the preview panel.
Cosmos full case page

Regions in a full case page
Work area
Defines the space where users process their cases and access the bulk of case information. For more information, see
Configuring the full case view.
Summary panel
Displays the critical data of the case. The structure and style of the summary panel is the same as in the preview panel
and the mobile full case page. For more information, see Configuring the summary data view.
Utilities panel
Holds widgets and utilities that help users work a case, such as lists of attachments, case followers, or tags. For more
information, see Widgets in Cosmos React.
Summary panel
Summary panel details
Case header
Holds the case name, icon, and number, as well as the case edit menu and the case actions menu. For more information,
see Configuring general case type settings and Configuring and working with optional actions in case types.
Summary data
Displays highlighted primary and secondary fields for your case. For more information, see Configuring the summary data
view.
Tabs
Provide users with access to additional data. The application displays the content of the current tab in the bottom half of
the work area. For more information, see Configuring the full case view.
Cosmos work area

Case work area
Case life cycle
Displays the stages and steps of your case and indicates the current stage. The case life cycle chevron display is optional,
and you can remove it in the full view configuration. For more information, see Configuring the full case view.
Tasks
Enables users to navigate to and launch tasks in the case.
Displayed tab content
Shows the contents of the current tab selected in the summary panel.
Configuring Cosmos React

Applicable to Cosmos React applications
Cosmos React offers a new low-code paradigm for developing applications quickly by using out-of-the-box components built
around the concept of configuration. This still-expanding framework creates products that require less customization and one-
off development, but promote a slightly different approach compared to application creation.
Cosmos React is a prescribed design system that promotes out-of-the-box, low-maintenance solutions. Consequently, some
classic Pega Platform components work differently in Cosmos React. The following table lists some of the changes to the
design process:
Component Change in Cosmos React Best practice
Use fields in views. The

system pairs the field
Low-code configuration solutions are a core tenet of Cosmos React. automatically with an optimal
Controls Consequently, traditional controls, such as buttons or links, are replaced by out-of-the box control.
and JSP configurable components that include the automatic configuration of buttons
and associated actions. For custom solutions, use DX
components.
Editable The application removes editable data pages at the end of a requestor life
Use saveable data pages.
data pages cycle.
Live Cosmos React applications do not include the Design button and do not Use App Studio to build and
editing support live editing. edit views.
Mashups Cosmos React replaces iframe-based mashups with div-based web embeds. Use web embedding.
Reports
Cosmos React do not support complex reporting features with sub-reports and Use the Explore Data landing
and report
joins. page and Insights.
browser
Sections
Cosmos React supports template-based views that you design in App Studio. Use App Studio to build and
and
You cannot edit views in Dev Studio. edit views.
harnesses
Styles,
skins, and To maintain consistency, Cosmos React applications rely on the Cosmos
Use styling tools in App Studio.
custom design system for styling.
CSS
Temporary Cosmos React architecture is stateless, so it does not support temporary Use data pages for populating
pages pages. data.
For more information, see the Pega Academy article Cosmos React and Constellation.
UI version comparison
Pega Platform version 8.7 expands the scope of Cosmos React, a modernized UI.
Choosing a UI version
Cosmos React reduces time to value and offers a new paradigm for application authoring that eliminates the need for
deep Pega knowledge and front-end expertise. The goal of Cosmos React is to offer common patterns for case
management applications out-of-the-box.
Feature limitations in Cosmos React
By familiarizing yourself with the current capabilities and limitations of Cosmos React, you can choose the UI best suited
to your business needs. In cases where Cosmos React would limit the design of your application, the best practice is to
use Theme Cosmos.
Data visualization features in Cosmos React
You can use data visualization and reporting features to help you conveniently explore and analyze application data, such
as company sales, bugs, and team assignments. For example, in a sales application, you can visualize data about profits
that your company generates in specific regions. You can then analyze the distribution of earnings across various
categories of products.
Tools for debugging Cosmos React
Identify issues in the Cosmos React UI more conveniently by using recommended tools and techniques. Debugging helps
you adjust your application to make it issue-free and easier to maintain.
Application UI setup
When building a new application, you can choose the view-based Cosmos React UI or the section-based, server-rendered
Theme Cosmos UI that can also support view-based portal landing pages. You can check which UI your application is
using to better understand the tools at your disposal.

Configuring portals
Working with views
Explore Data
Visualizing data with insights
UI version comparison
Pega Platform version 8.7 expands the scope of Cosmos React, a modernized UI.
Cosmos React is the newest version of the Cosmos design system that, paired with a view-based architecture, offers superior
efficiency and responsiveness, but supports a different feature set than the classic Theme Cosmos. By learning about the
limitations of each framework, you can better choose the UI that fits the needs of your business.
The following table presents recommended uses for the two UI architectures.
User interface choice in Pega Platform version 8.7
Theme Cosmos Cosmos React
See Choosing a UI See Choosing a UI

New applications
version. version.

New applications based on a Theme Theme UI-Kit application
version. version.

Existing applications
version. version.
Application features
Mashup (web embed) ✓ ✓
Mobile ✓ ✓
Offline mode ✓
Accessibility ✓ ✓
Localization ✓ ✓
Reporting
Simple reporting and data exploration ✓ ✓
Complex reporting with sub-reports and joins ✓ ✓
Application UI that uses data from reports with complex joins ✓ ✓
Authentication
Attribute-based access controls (ABAC) ✓ ✓
OAuth 2.0 authentication ✓ ✓
Choosing a UI version
Cosmos React reduces time to value and offers a new paradigm for application authoring that eliminates the need for deep
Pega knowledge and front-end expertise. The goal of Cosmos React is to offer common patterns for case management
applications out-of-the-box.
You can extend Cosmos React for advanced use cases to build something new, but it is important to verify that Cosmos React
offers the business outcomes and capabilities that your application needs.
Best practices overview

Review the following table to select the right UI for your application.
Recommendation 8.5 8.6 8.7
New applications Use Theme Cosmos Use Theme Cosmos Evaluate Cosmos React
Existing applications No UI changes No UI changes No UI changes

Integrations with websites (no
Recommendation 8.5 8.6 Evaluate web
8.7 embeds in
professional front-end Use mashup Use mashup
Cosmos React
developer help)
Integrations with websites

Evaluate starter packs or DX Evaluate SDKs or DX API
(with professional front-end Evaluate SDKs
API directly directly
developer help)
Guidelines for new applications

For new applications that you build from scratch, review the feature limitations in Cosmos React. If your application
requires features that Cosmos React does not support, use Theme Cosmos.
For more information, see Feature limitations in Cosmos React.
For new applications that you build on top of existing applications that do not use Theme Cosmos, keep the original UI.
For example, Pega Customer Service uses Theme UI-Kit. If you build a new application that is based on the Pega
Customer Service application, it must also use Theme UI-Kit.
Guidelines for existing applications

Keep existing applications built with section rules and Theme UI-Kit on their current UI.
Keep existing Theme Cosmos applications that use a section-based UI on their current UI. Consider upgrading to the
latest version of the Cosmos theme ruleset ( Theme-Cosmos) in the application definition.
For more information, see Updating Theme Cosmos in your application.
To shorten future migrations, consider preparing for migration now by checking existing applications for compliance with
the App Studio delivery approach. Use the App Studio Compliance landing page to identify non-compliant UI elements in
your application, and then plan development time to address identified issues.
For more information, see App Studio development and Reviewing user interface components.
Feature limitations in Cosmos React

By familiarizing yourself with the current capabilities and limitations of Cosmos React, you can choose the UI best suited to
your business needs. In cases where Cosmos React would limit the design of your application, the best practice is to use
Theme Cosmos.
Important:
Evaluate whether Cosmos React supports your use case before building a new application, and continue using Theme Cosmos
for complex applications that require highly specialized features, such as offline mode.
For existing applications, the best practice is to keep your current front-end setup, whether it is Theme Cosmos or Theme UI-
Kit. Migration tooling and guidance is currently in development and planned to be released in the Pega Platform version 8.8.
For more information, see Choosing a UI version.
General limitations
Cosmos React does not support the following features in Pega Platform version 8.7:
Native preview and internal preview of media. Images can be uploaded, downloaded, or used as logo.
Offline mode.
Push and subscribe notification channels.
Multichannel features, including email and chat integration.
Rule delegation.
Paragraph rules.
Exporting tabular data to Excel.
Forms to edit or create data objects (data views are read-only).
Reports and the report browser. For more information, see Visualizing data with insights.
User-personalized dashboards.
Some localization features. For more information, see Localization limitations.
Complex mobile capabilities. For more information, see UI architecture recommendations for mobile apps.
Case management limitations

Cosmos React does not support the following case management features in Pega Platform version 8.7:
Automations for generating PDFs and documents.

Field-level auditing.
Geolocation tracking.
Get next work.
Team dashboard widget.
Documents and Spaces. You can only configure the application to launch Documents and Spaces in a section-based UI in
a new browser tab.
Questionnaire limitations
Cosmos React does not support the following questionnaire features in Pega Platform version 8.7:
The following question types:

Slider
Checklist
Multi textbox
Build a list
Radio button matrix
Question text with rich text options, such as feeding a response to the next question, or dynamic values in information
text
Scoring
Collaboration limitations
Cosmos React does not support the following collaboration features in Pega Platform version 8.7:
Adding tags from the tags overlay

Bookmarking Pulse comments
Private posts can be viewed, but not authored
Pulse feed does not support posting in multiple contexts and more than one feed on screen
Editing Pulse comments
Pinning posts to a space
Poster view for Pulse comments with a single attachment
Post types (Task and Private posts)
Referencing a case in Pulse
Searching Pulse comments
The Spaces, Tags, and Documents landing pages work only in hybrid mode (the pages open in an Infinity portal)
In addition, Pega maintains a list of known issues discovered in Cosmos React applications. For more information, see Existing
known issues.
Data visualization features in Cosmos React

You can use data visualization and reporting features to help you conveniently explore and analyze application data, such as
company sales, bugs, and team assignments. For example, in a sales application, you can visualize data about profits that
your company generates in specific regions. You can then analyze the distribution of earnings across various categories of
products.
Cosmos React and Theme Cosmos comparison

The following table provides a list of data visualization and reporting features in Pega Platform version 8.7. For more
information, see Reporting.
Theme Cosmos: Report Theme Cosmos: Theme Cosmos: Data Cosmos

Component name
Definition Chart Control Visualization Control React
Single Axis Combo Chart

(Cluster, Stack)
Dual Axis Combo Chart

(Cluster, Stack)
Area (Overlaid, Stack, 100%)
Funnel
Pyramid
Bubble
Pie (Normal, Exploded,

Donut)
Bar (3 types)
Column (3 types) Theme Cosmos: Report Theme Cosmos: Theme Cosmos: Data Cosmos
Component
Line name
Definition Chart Control Visualization Control React
Spark (Line, Column)
Gauge – 270 Arch
Gauge – Speedometer
Gauge – Half-Dial
Gauge – Half Arch
Gauge – Dial
Gauge – Linear
Gauge – Horizontal LED
Gauge – Vertical LED
Gauge – Cylinder
Gauge – Thermometer
Gauge – Progress
Map
Pareto Chart
Scatterplot
Double Donut
Radar Chart
Bullet Chart
Concentric Circles
Simple Value
Tools for debugging Cosmos React

Identify issues in the Cosmos React UI more conveniently by using recommended tools and techniques. Debugging helps you
adjust your application to make it issue-free and easier to maintain.
Cosmos React supports the following debugging methods.
Virtual DOM
Because Cosmos React uses ReactJS components, a virtual DOM is an important structure that stores metadata
information.
You can install the React Developer Tools plugin and use the Components tab in your browser's developer tools to check
UI elements and view related metadata. You can use the <virtual element>.props.getPConnect() command to get more
information about a selected component.
Redux DevTools
Cosmos React applications maintain data at the client server by using Redux.
Tracer
Tracer is the out-of-the-box tool for debugging Pega Platform applications.
For more information, see Application debugging by using the Tracer tool.
XRay
The XRay module provides an intuitive way to debug screen issues, such as metadata, fields metadata, and state
properties.
You can launch the XRay tool by entering PCore.getDebugger().toggleXRay(true) into the browser console. To disable XRay, enter
PCore.getDebugger().toggleXRay(false).
Application UI setup
Applicable to Cosmos React and Theme Cosmos applications
When building a new application, you can choose the view-based Cosmos React UI or the section-based, server-rendered
Theme Cosmos UI that can also support view-based portal landing pages. You can check which UI your application is using to
better understand the tools at your disposal.
You can check your UI setup by opening the Definition landing page in Dev Studio and looking at the Built on applications
and UI Runtime sections. Note: For more information on accessing and reviewing the application definition, see Exploring the
application definition.
Location of the Built on applications and UI Runtime sections on the Definition page
The following table presents how you can read the values of fields on the Definition page to determine your UI environment.
Field values on the Definition tab and the application UI setup
Use react-based landing

UI Runtime Built on applications UI setup
pages flag
View-based architecture with

Cosmos React.
React-based UI Any Not applicable
For configuration details, see
Cosmos React.
Section-based architecture
with Theme Cosmos but
without hybrid landing pages.
Server-rendered UI Theme-Cosmos For portal configuration, see

Building portals. For other
components, see Theme
Cosmos.
Hybrid Theme Cosmos UI.

Except for the landing pages,
your UI is section-based and
follows classic Pega
Server-rendered UI Theme-Cosmos ✔ configuration.

Theme Cosmos and Hybrid
mode.
Use react-based landing Section-based architecture
UI Runtime Built on applications UI setup
with a classic Theme UI-Kit
pages flag
Server-rendered UI UIKit Not applicable design system.

Theme UI Kit.
Configuring portals
Portals represent the main interface of your application, and provide users, such as case workers, managers, and customers,
with the tools that they need to do their work. By configuring portals, you can set up an optimal environment for each of these
user groups with minimal effort.
When you create a new application, Pega Platform automatically generates the first portal for you. Depending on your UI, the
default portal is called either User Portal (for Theme Cosmos in hybrid mode) or Web Portal (for Cosmos React). Note: For
interfaces that use section-based Theme Cosmos architecture without hybrid mode, see Building portals.
You can then configure the portal in App Studio by picking a template, populating it with pages and reusable widgets, and then
setting up the primary menu. In this way, you can control what users see when they interact with your application, and what
kind of navigation, forms, and work items they can create and use. To modify the interface even further, you can also set up
different content visibility settings for each persona to ensure that users who belong to a specific group see only the
information that is relevant to their responsibilities.
The App Studio environment offers an updated portal authoring experience that relies on intuitive actions such as drag and
drop operations, and provides a live preview of the menu.
Portal authoring in App Studio

Discover more about creating portals in the following articles:
Creating a portal
Deliver a user experience that matches the needs of each user group by setting up portals. Portals are highly
configurable interfaces that can help you to define how personas interact with your application.
Defining a portal header
Set a header to give your portals a distinct visual identity. By applying an application header (the top bar that spans the
entire width of a page), you ensure that users can quickly distinguish between different portals.
Organizing the contents of a portal
Help users increase productivity by populating your portal with tools that have the most relevance to user roles.
Portals for personas
You can use portals to design custom web interfaces for various personas in your application. Portals help you to control
the content with which each user interacts.
Previewing a portal
Preview a portal that you develop to verify that different types of devices, such as a desktop computer or a tablet,
correctly display the user interface.
Creating a portal
Deliver a user experience that matches the needs of each user group by setting up portals. Portals are highly configurable
interfaces that can help you to define how personas interact with your application.
As a best practice, you can set up a single portal for all your users, and control the visibility of specific UI elements through
personas and access privileges. Alternatively, you can create a dedicated portal for each persona, and populate each portal
with prefabricated components that help users complete their tasks.Note: When you create a new application, Pega Platform
automatically generates the first portal for you. Depending on your UI setup, the default portal is called either User Portal (for
Theme Cosmos in hybrid mode) or Standard Portal (for Cosmos React). For interfaces that use section-based architecture
without hybrid mode, see Building portals.
1. In the navigation pane of App Studio, click Channels, and then click Portal.
Creating a portal
2. On the New Portal window, provide a meaningful name and description for the portal, and then click Submit.
3. On the New portal interface page, click Save. Result: The portal is now active. You can configure it by modifying
components such as the navigation menu, access settings, and headers.
Defining a portal header

Set a header to give your portals a distinct visual identity. By applying an application header (the top bar that spans the entire
width of a page), you ensure that users can quickly distinguish between different portals.
Alternatively, you can add a combination of a logo and an icon to the main navigation menu. Each portal has a separate
header, and different portals in the same application can use different header styles. Important: For section-based Theme
Cosmos, using the application header requires you to update the theme ruleset to version 04. For more information, see
Updating Theme Cosmos in your application.
Header types
1. Open your portal:
a. In the navigation pane of App Studio, click Channels.
b. In the Current channel interfaces section, click the icon that represents the portal for which you want to edit the
header.
2. On the Configuration tab, in the Logo list, select the type of logo that you want to use:
Note: When you use Theme Cosmos, the default portal logo is the same as the application logo. If you use a separate
logo for your portal, the portal settings take precedence over the application settings. For more information on selecting a
logo for your application, see Defining a logo for an application.
To use the application logo, select Use default logo.
To use a separate logo for your portal, select Custom logo, and then upload the icon you want to use.
3. Select the header type:
To use the application header, select the Display application header checkbox.
To use the banner in the navigation menu, clear the Display application header checkbox.
Note: In Theme Cosmos, the search popover provides a consolidated list of search results in a table. The table supports
filtering and is customizable. You can also use a link to open the advanced search results page in a new browser tab.
4. In the Channel header list, select the name that is displayed in the portal header.
5. Click Save.
Organizing the contents of a portal

Help users increase productivity by populating your portal with tools that have the most relevance to user roles.
Note: For applications that do not use hybrid mode, see Creating and managing pages for applications.The portal in your
application can include a mix of ready-to-use and custom components. For example, a portal for an HR Manager persona can
include an out-of-the-box Dashboard page. You can then expand the portal further by adding a ready-made case status widget
that provides quick insight into the number of pending applications. At the same time, you can set up a custom landing page
that lists all the employees on the manager's team who are on leave in a given week, to help your other users plan their work
with the resources they have at hand.
Portal with an Explore Data landing page
Landing pages
Pages in portals can help you provide users with the tools that they need to efficiently plan work and complete common
management tasks. By using out-of-the box components, you can set up a functional work environment with minimal
effort.
Creating a landing page for an application
Build an application that matches the needs of your users by configuring landing pages. You can populate the pages with
fields, controls, and resources that improve user efficiency and workflows.
Removing a landing page from an application

Keep the content of your portal concise and relevant by removing obsolete pages. By disabling an existing landing page,
you ensure that users cannot add it to their menus.
Organizing the main navigation for a portal
Build a navigation menu that effectively organizes the content of your portal by adding pages to the menu and
determining the available case types.
Landing pages
Pages in portals can help you provide users with the tools that they need to efficiently plan work and complete common
management tasks. By using out-of-the box components, you can set up a functional work environment with minimal effort.
For example, you can set up a Teams page to help users quickly find all the teams with which they work.
Pega Platform provides a variety of ready-to-use custom pages that cover common work scenarios:
Home
Contains a brief overview of the application, including update information, message feed, and a worklist.
Explore Data
Features reporting tools for data and case types.
My Work
Provides quick access to cases and assignments of the user.
Search
Contains a search tool with a set of pre-defined filters.
Home
The Home landing page provides the user with a quick overview of your application. You can populate the home page
with out-of-the-box widgets, as well as fields and views that best meet the needs of your business.
Explore Data
Explore Data provides a convenient way to analyze and manage data in your application. For example, you can access
the list of all assignments of your team, and then analyze their status to verify the remaining workload for the current
release.
Search landing page overview
The search landing page helps you control what data is available for the Search and Reporting Service (SRS). You can
decide which classes of specific applications you want to index, to make them available for search. For example, you can
index a class that contains data about resolved bugs to make bug resolution data searchable.
Insights help you conveniently explore and analyze application data, such as company sales, bugs, and team
assignments. You can use insights to retrieve specific data, and present the data as a list or an interactive chart.
Home
The Home landing page provides the user with a quick overview of your application. You can populate the home page with out-
of-the-box widgets, as well as fields and views that best meet the needs of your business.
Unlike a traditional Pega Platform dashboard that the end user can customize, the Home page in a Cosmos React application
is a curated experience. Consequently, it is the application designers who specify what users see when they log in.
You can add the following widgets to the home page:
App announcements
Displays a welcome banner for the user. You can modify the text and the background of the announcement, as well as the
destination of the action button.
For more information, see Configuring the Home page welcome banner.
Pulse
Displays a message feed.
To do
Displays list of open cases assigned to the user.
Sample landing page

Configuring the Home page welcome banner
Send a customized message to your users by configuring the welcome banner on the Home page of your application with the
App announcement widget. For example, you can configure the banner to display a bulleted list of the latest changes to the
application.
1. Open the App announcement widget:

b. In the Current channel interfaces section, click the icon that represents the portal whose App announcement
widget you want to configure.
c. On the portal page, on the Content tab, click the Landing pages category.
d. In the Landing pages pane on the left side of the screen, click Home.
e. In the Edit page: Home pane, in the row that holds the App announcement widget, click Configure App
announcement.
2. In the Header text field, enter the title of your message.
3. In the Description field, enter the text of your message.
4. In the What's New link field, enter the address of the web page that you want to open when the user clicks the What's
New button on the banner.
5. In the Image URL field, enter the address of the image that you want to use as the banner's background.
The field accepts external links or images that are provided in the data:image format with base64 encoding.
6. Click Submit.
7. Provide text for the details bullet points:
a. In the header of your workspace, click the Switch Studio menu, and then click Dev Studio.
b. In the Dev Studio search field, search for and open the pyInitAnnouncements data transform.
The system sources the bullet points in your announcement from the D_pyAnnouncements data page. The
pyInitAnnouncements data transform populates D_pyAnnouncements with content.
c. On the Definition tab of the pyInitAnnouncements data transform, in the Source column, enter the text for the
bullets. For example: In this scenario, the pyInitAnnouncements data transform contains three actions, each
representing a bullet. You can remove the bullets or add new ones by copying the existing configuration.
Sample bullet configuration
d. On the ruleform, click Save.
For example: The following message banner represents a sample configuration:
Sample App anouncement widget

Configuring the Todo widget
Help your users quickly identify the highest priority tasks by setting up a Todo widget. The widget provides users with a list of
tasks from their worklist or the work queue to which they belong.
1. Open the Todo widget:

b. In the Current channel interfaces section, click the icon that represents the portal whose Todo widget you want
to configure.
d. In the Landing pages pane, click Home.
e. In the Edit landing page: Home pane, in the row that holds the Todo widget, click Configure Todo.
2. In the Header text field, enter the label for the widget.
3. In the Include work from section, define which assignments are displayed in the widget:
To display assignments from the worklist of the user, select the My worklist checkbox.
To display assignments of all team members in the workgroup of the user, select the Worklist of Team Members
checkbox.
To display assignments from work queues that are mapped to the user in the operator record, select the Work
Queues checkbox.
For more information about configuring work queues, see Creating a work queue.
For example: Display assignments from the worklist and work queues of the user by selecting the My worklist and Work
queues checkboxes.
Sample widget configuration

Explore Data
Explore Data provides a convenient way to analyze and manage data in your application. For example, you can access the list
of all assignments of your team, and then analyze their status to verify the remaining workload for the current release.
Explore Data feature uses a React-based landing page to improve the user experience. For more information, see Cosmos
React.
Explore Data features

The intuitive landing page provides a convenient way to manage insights in your application.
On the Explore Data landing page, you can perform the following actions:
Gain access to your application data, such as detailed information about assignments, bugs, and sales.
View and access all saved insights.
Filter, sort, or group data to view only the specific information that matches your business needs.
Create customized insights that you can use throughout the application.
If you want to show properties in Explore Data, ensure that the properties are optimized for reporting and marked as
relevant records. Embedded properties from Page Lists are not supported in Explore Data.
You can create simple associations between classes, and add them to your insights. For more information, see Creating
simple associations between classes.
Create appealing interactive charts using your application data, to conveniently analyze the results.
You can choose from several chart types, such as pie, bar, donut, or column.
The following visualization presents how to access and manage list-based insights in the Explore Data feature:
Managing a list-based insight

Search landing page overview
The search landing page helps you control what data is available for the Search and Reporting Service (SRS). You can decide
which classes of specific applications you want to index, to make them available for search. For example, you can index a
class that contains data about resolved bugs to make bug resolution data searchable.
When you access the landing page, you can perform the following actions:
Add properties or classes that you want to index by adding custom search properties.
Synchronize specific data to make the applications up-to-date.
For example, you can manually synchronize after resolving issues with broken items.
Verify the status of data that you index, and analyze potential errors.
Index the data of specific classes into the SRS.
Manage fuzzy search parameters to enable the service to search for similar words that you enter.
For example, if you search for tst, the system returns test and tests. The results depend on the fuzzy search parameters that
you set.
Extract of the search landing page

Insights help you conveniently explore and analyze application data, such as company sales, bugs, and team assignments.
You can use insights to retrieve specific data, and present the data as a list or an interactive chart.
For example, in a sales application, you can visualize data about profits that your company generates in specific regions, and
then analyze the distribution of earnings across various categories of products.
Pega Platform uses insights to transform data queries into tables or visualizations that you can then share between users and
embed in landing pages of your applications. Insights can include multiple data items that you can filter, sort, and group
according to your business requirements.
Reporting provides list-based and chart-based insights that you can access by using the Explore Data feature in your
application.
Creating interactive chart-based insight

Creating insights
Collect specific information about your application, and save it in a clear visual form to support the process of data
analysis. For example, you can create a list-based insight that provides data about resolved assignments, and then filter
the content by application users to analyze their performance.
Creating insights
Collect specific information about your application, and save it in a clear visual form to support the process of data analysis.
For example, you can create a list-based insight that provides data about resolved assignments, and then filter the content by
application users to analyze their performance.
Before you begin: Add the Explore Data page to your application. For more information, see Organizing the main navigation
for a portal.Note: You can add the Explore Data page only if your application uses a Cosmos React or Theme Cosmos in hybrid
mode.
1. Inthe navigation pane of your application, click Explore Data.

2. Inthe What would you like to explore? list, select specific type of data for which you want to create an insight.
3. Inthe upper-right corner of the screen, click Save as insight.
4. Inthe Save as insight dialog box, provide details for your insight:
a. In the Name field, enter a unique name for the insight.
b. In the Visibility list, select who can see your insight. For example: Select Shared to share the insight with your
access group.
c. Optional: To give the chart a supplementary title, select the Show title checkbox, and then customize the title.
For example: In the Title alignment list, display the chart title in the center by selecting Center.
a. Click Submit.
What to do next: You can view and access your insights in the Insights section of the Explore Data landing page.
Customizing list-based insights
Decide what data you want to present in your insights by using intuitive tools that provide options to filter, sort, and
group the data. For example, you can filter an insight to include only resolved assignments, so that you can analyze the
performance of a whole department. Then, you can group the results by teams to compare their work.
Customizing chart-based insights
Adjust the appearance and contents of chart-based insights to visualize only the specific information that is relevant to
your business needs. For example, in a flight booking application, you can visualize data about recent reservations, and
then filter the results by specific destinations to analyze the latest trends in business.
Converting tables to charts
Improve the look of your application by creating visually appealing insights that present data in a modern and intuitive
manner. For example, you can convert simple list-based insights to interactive charts to ensure a user-friendly experience
when analyzing data.
Customizing list-based insights

Decide what data you want to present in your insights by using intuitive tools that provide options to filter, sort, and group the
data. For example, you can filter an insight to include only resolved assignments, so that you can analyze the performance of
a whole department. Then, you can group the results by teams to compare their work.
mode.
1. In the navigation pane of your application, click Explore Data.

2. In the Insights section, click the insight that you want to modify.
3. Customize your insight by performing one of the following actions:
Choices Actions
a. In the upper-right corner of the insight, click Filter.

b. In the Filter by dialog box, click the Select field list, and then select the specific data that you want to
filter. For example: Select Date of order
c. In the list of relational operators, select an operator for your filter, and then specify the details.
d. If you filter results by dates, click the Compare with icon, and then specify date parts and time periods
Filter by which you want to filter results. For example: Select Relative date, then click Current day, and
data then in the Time period and Date part lists, select Current and Week(s) respectively, to display
results from the current week only.
e. Optional: To apply more filters, click the Add icon.
f. Optional: To define more complex filters, click Advanced mode, and then enter the filter logic. For
example: If you apply two filters, enter 1 OR 2 to filter data by either of the conditions.
g. Click Submit.
a. In the upper-right corner of the insight, click Sort.

b. In the Sort by dialog box, in the Select field list, select a column that you want to sort.
Sort c. In the Select list, select the way you want to sort the data. For example: Click Descending to display
data values from highest to lowest.
d. Optional: To sort more columns, click Add.
e. Click Submit.
a. In the upper-right corner of the insight, click Group.

b. In the Group by dialog box, in the Select field list, select how you want to group the insight data. For
Group example: Select Create Date/Time, and then select Months, to group data by months.
data c. Optional: To add more grouping conditions, click Add.
Note: You can group data by multiple properties to drill-down to more specific data.
d. Click Submit.
For example: The following example presents list-based insight with grouped data by months and days. Thanks to grouping
data by multiple properties, you can retrieve more specific information.
List-based insight with grouped data
Customizing chart-based insights

Adjust the appearance and contents of chart-based insights to visualize only the specific information that is relevant to your
business needs. For example, in a flight booking application, you can visualize data about recent reservations, and then filter
the results by specific destinations to analyze the latest trends in business.
You can choose from a wide range of chart types to conveniently present your data.
mode.

2. In the Insights section, click the chart-based insight that you want to modify.
3. On the right side of the insight, click Edit.
4. In the customization screen of your insight, on the DATA tab, manage the content of your insight:
Choices Actions
Change
In the Chart type section, in the types list, select the chart that you want to view.
visualization
a. From the Fields section on the right side of the screen, drag numerical data into the Measures
area.
Visualize Note: If you change the object type, the system discards all settings of the insight, such as filter
specific conditions, chart type, and selected data.
data b. Create a chart by dragging further data into the Dimensions area. For example: Drag the Loan
amount and Customer data records into the Measures and Dimensions fields respectively to
visualize the loans of specific borrowers.
a. In the Fields section, in the Measures area, next to the record that you want to edit, click More,
and then select a measure to include in the chart. For example: For the Loan amount record,
Change select Maximum to visualize records with the highest loan amount.
measures
For the Amount to insure record, select Count to visualize the number of items to insure per
customer.
a. From the Fields section, drag the data by which you want to filter the chart into the Filters area.
For example: Drag the Create date/time record to filter results by the date of creation.
b. In the list of relational operators, select an operator for your filter.
Apply basic c. If you filter results by dates, in the date parts list, select certain date part, and then specify the time
filters period. For example: Select Relative date, and then in the Time period and Date part lists,
select Current and Week(s) respectively, to display results from the current week only.
d. Click Submit.
e. Optional: To apply more filters, drag more records into the Filters area.
a. In the Filters section, click Add advanced filter, and then, in the dialog box with filters, click
Apply
Advanced mode.
advanced
b. In the Advanced condition field, enter the filter logic, and then click Submit. For example: If you
filters
apply two filters, enter 1 OR 2 to filter data by either of the conditions.
a. In the Sorting section, in the Sort by list, select the data by which you want to sort the chart.
Sort data b. In the Sort order list, specify how you want to sort the data. For example: Select Ascending to
display values from lowest to highest.
5. On the CHART tab of your insight, manage how the system displays supplementary information in the chart:
Choices Actions
In the Series section, next to the data series whose chart you want to update, click More, and then select
Manage specific option to manage.
data series
For more information, see Managing data series in insights.
Customize a. Expand the Axis section.

the range b. Manage the axes of the chart by selecting specific checkboxes. For example: Select Customize
of axes range, and then in the Minimum and Maximum fields, modify the scale of the chart.
a. In the Grid section, select the Show grid lines checkbox.

b. If your insight include only one data series, in the Line style list, select the look of grid lines.
c. If your insight include more than one data series, in the Apply grid to list, select the axis to which
you want to apply the grid.
Customize Note:
grid lines
Applying grid lines to secondary axis is available after you specify the secondary axis in the Axis
section.
You can apply grid lines for two axis at once when customizing the bubble chart.
Toggle In the Tooltips section, select the Show tooltip checkbox to display supplementary information about
tooltips the chart columns.
a. In the Legend section, and then select the Show legend checkbox.
Manage b. Customize the chart legend by providing specific details. For example: In the Type list, select
chart checkboxes to create a legend in the form of clickable checkboxes.Note: The system hides the
legend columns that correspond to the checkboxes that you clear.
6. In Choices
the upper-right corner of the insight, click Save insight. Actions
For example: You can filter data of your insights to get the specific information that you require at the moment. The following
visualization presents how to retrieve data about profits that each state generates by selling television sets that are shipped
by regular air transport.
Applying filters in insights

Improve the look of your application by creating visually appealing insights that present data in a modern and intuitive
manner. For example, you can convert simple list-based insights to interactive charts to ensure a user-friendly experience
when analyzing data.
mode.

2. In the Insights section, in the Name column, click the insight whose data you want to visualize.
3. In the upper-right corner of the screen, click Actions Create chart .
4. From the Fields section, drag specific data to the Measures and Dimensions drop zones to format the chart.
Note: Use the Measures and Dimensions drop zones to include numerical and detailed data respectively, such as the
number of mortgages and the loan requestor's personal information.
For example: Drag the Profit record to the Measures drop zone, and then drag the Department record to the
Dimensions drop zone to visualize the income of specific departments in your company.
For more information, see Customizing chart-based insights.
5. Optional: To change the visualization, in the Chart type section, from the type list, select the specific chart.
For example: The following visualization presents how to create an interactive chart-based insight from a table:
Converting list-based insight to chart-based insight
Creating a landing page for an application

Build an application that matches the needs of your users by configuring landing pages. You can populate the pages with
fields, controls, and resources that improve user efficiency and workflows.
For example, portals for managers might include a page that contains a list of case workers and their workloads, which
provides improved insight into resource allocation.
Note: Landing pages are view-based. For applications that use section-based UI without view-based landing pages, see
Creating and managing pages for applications.
b. In the Current channel interfaces section, click the icon that represents the portal to which you want to add a
custom page.
2. On the portal page, on the Content tab, click the Landing pages category.
3. In the Landing pages pane on the left side of the screen, click Add.
4. In the Add a page dialog box, in the Name field, enter a unique page name.
5. In the Template list, select the template that you want to use.
6. Click Submit, and then click Save.
What to do next: Add content to the newly created page:
If the page uses a list page template, configure table settings. For more information, see Configuring a list-based landing
page.
If the page uses a column template, add UI elements to the page. For more information, see Configuring a column-based
landing page.
If the page uses a tab template, configure tabs and their content. For more information, see Configuring a tab-based
landing page.
If the page uses a dashboard template, configure the dashboard layout and content. For more information, see
Configuring a dashboard.
Configuring a column-based landing page
Help users work more efficiently by aligning landing pages with the latest needs of your business. You can quickly rework
landing pages to present users with the information they need in a friendly, intuitive interface that uses prefabricated,
low-code components.
Configuring a list-based landing page
Help users quickly process large amounts of information by setting up list views. Pega Platform applications display lists
as tables or tiles, which you can configure to support filtering, sorting, and custom presentation options.
Configuring a tab-based landing page
Organize case data by categories with a tab-based landing page template. By using tabs, you can create a familiar and
intuitive UI that saves screen space and helps users find the information they need with less effort.
Configuring a dashboard
Increase the productivity of your team by configuring a dashboard that displays relevant data in a convenient form. For
example, you can design a workspace that includes a number of insights that help managers oversee work by displaying
case status, sales data, and burndown charts.
Configuring a column-based landing page

Help users work more efficiently by aligning landing pages with the latest needs of your business. You can quickly rework
landing pages to present users with the information they need in a friendly, intuitive interface that uses prefabricated, low-
code components.
Before you begin: Prepare the configurable components:
Create a landing page that uses the column template. For more information, see Creating a landing page for an
application.
Create the views and insights that you want to add to the landing page. For more information, see Creating views in
Cosmos React and Creating insights.
1. Open the page that you want to edit:

b. In the Current channel interfaces section, click the icon that represents the portal with the page that you want to
edit.
d. In the Landing pages pane on the left side of the screen, click the page that you want to edit.
2. Edit the page by doing any of the following actions:
To change the name of the page, in the Page title field, enter the updated page name.
To change the icon associated with the page, click Choose icon, and then select an image that you want to use.
To change the page template, click Edit, and then click the template that you want to apply to the view.
To add a widget, view, an insight to the page, click Add, and then select the UI component that you want to
add.Note: The view menu contains list views that you defined in the application. In hybrid applications, the widget
menu contains only Cosmos React widgets.
To change the position of a widget or a view on the page, drag the component into place.
To remove a widget or a view from the page, click Remove.
For example:
In this scenario, the view uses a two-column template.

A sample two-column view at run time
Configuring a list-based landing page

Help users quickly process large amounts of information by setting up list views. Pega Platform applications display lists as
tables or tiles, which you can configure to support filtering, sorting, and custom presentation options.
For example, a portal for loan officers can include a table that lists mortgage applications. Each manager can then gain quick
insight into upcoming work and the status of ongoing cases. You can also set up multiple views to help users filter the data
according to their needs.
Create a landing page that uses the list page template. For more information, see Creating a landing page for an
application.
Identify a data page from which you want to source the list content. For more information, see Creating a data page.
1. Open the list page that you want to edit:

edit.
2. Change the icon of the page by clicking Choose icon, and then select an image that you want to use.
Pega Platform includes a set of default icons.
3. From the options under the List page title field, select Custom list page.
Tip: If you have a configured list that you want to include in the landing page, you can select Use existing lists and skip
the configuration.
4. In the Data page list, select the data page from which you want to source the table contents.
5. In the Display name field, enter the name for the view, and then define how you want to present the data to the user:
Choices Actions
Table In the Template list, select Table.
a. In the Template list, select Gallery.

Tile-based b. In the Card header list, select the field that you want to use as the header for your tile.
gallery c. In the Secondary text field, select the field that you want to use as the source of additional text
on your tile.
6. In the Columns section, add the columns that you want to include in the view by clicking Add, and then selecting the
field that you want to associate with the column.
Note: The type of fields that you can add as columns vary depending on the data page configuration. For more
information, see Available columns.
7. In the Column to take up remaining width list, select which column stretches to fill free space in your table.
8. Optional: To define what data is displayed in the table, set one or more filters:
a. In the Filter by list, select Custom, and then click the Properties icon.
b. In the Condition Builder window, define the expression that you want to use to filter the table contents.
For more information, see Using conditional logic in Cosmos React.
9. Define how the application sorts data in the table:
a. In the Sort by list, add the property by which you want sort the list by clicking Add, and then selecting the field that
you want to use as a filter.
b. In the list that appears next to the property field, select the order in which you want to sort the table.
10. Optional: To group the table contents by a property, in the Group by list, add the property by which you want group
the table by clicking Add, and then selecting the target field.
11. Optional: In Cosmos React applications, to enable bulk processing of list items, select the Allow bulk actions
checkbox.
Tip: Bulk processing is available for tables on case pages and landing pages in Cosmos React applications only. The
actions in the bulk action menu are case-wide actions. For more information, see Adding optional actions to cases and
Troubleshooting errors in bulk processing.
12. Optional: To define additional table behavior, select any of the checkboxes in the Editing and User Personalization
sections. For example: Select the Allow saving custom views checkbox.
13. Optional: To add a new view to the list, under the data source list, next to the Default view tab, click +Add.
For example: If you configure several views for your list, at run time, the table includes a view picker similar to the one that
is presented in the following figure:
View picker
If you configure your view as a gallery, the UI displays list entries as tiles. The following image represents a sample gallery tile:
Sample tile of a gallery-based list

Configuring a tab-based landing page
Organize case data by categories with a tab-based landing page template. By using tabs, you can create a familiar and
intuitive UI that saves screen space and helps users find the information they need with less effort.
Create a landing page that uses the tab template. For more information, see Creating a landing page for an application.
Cosmos React, Creating views for case types and Creating insights.

edit.
2. Change the icon of the page by clicking Choose icon, and then select an image that you want to use.
Pega Platform includes a set of default icons.
3. In the Tabs section, click Add.
4. In the New tab dialog box, enter the name for your tab, and then click Submit.
5. In the Tabs section, next to the newly added tab, click the Drill in icon.
6. In the Edit tab pane, configure the tab by doing any of the following actions:
To change the tab template, click Edit, and then click the template that you want to apply to the tab.
To add a widget, view, or an insight to the page, click Add, and then select the UI component that you want to
To change the position of a widget or a view on the page, drag the component into place.
To define when the tab appears in the view, in the Visibility list, define the visibility condition.
7. At the top of the Edit tab pane, click Back to return to the main view.
8. Optional: To create additional tabs, repeat steps 3 through 7.
For example: In this scenario, the Pulse and History views are sharing a tabbed template.
Sample tabbed view at run time

Configuring a dashboard
Increase the productivity of your team by configuring a dashboard that displays relevant data in a convenient form. For
example, you can design a workspace that includes a number of insights that help managers oversee work by displaying case
status, sales data, and burndown charts.
The dashboard consists of three regions, with the upper part of the screen divided into two columns, and the lower part
comprising a single, full-width column region.
Create a landing page that uses the dashboard template. For more information, see Creating a landing page for an
application.
Cosmos React and Creating insights.

edit.
2. Edit the page by doing any of the following actions:
To change the name of the page, in the Page title field, enter the updated page name.
To change the icon that is associated with the page, next to the Page title field, click Choose icon, and then select
an image that you want to use.
To add an insight, view, or a widget to the page, click Add, and then select the UI component that you want to
3. In the Filters section, click Add, and then select which filters you want to make available to the users of the dashboard.
Note: The filters apply to the insights on the dashboard. The top level of filters contains filters based on common fields,
such as case status. The case sub-menu contains filters sourced from the fields in the insights on the dashboard. If a filter
is based on a field that is not used in all insights, the system applies that filter to the insights that have that field. The
other insights ignore that filter.
Filter menu
For example: Sample dashboard with widgets illustrating sales data.
Dashboard with insights

Removing a landing page from an application
Keep the content of your portal concise and relevant by removing obsolete pages. By disabling an existing landing page, you
ensure that users cannot add it to their menus.
A page that you remove from an application is no longer available in the Landing pages list.Note: You can still use the
resources that the inactive page contains, and access the page through the Relevant records menu in Dev Studio. For more
information, see Relevant records for rule reuse.

b. In the Current channel interfaces section, click the icon that represents the portal from which you want to remove
a custom page.
2. On the portal page, on the Content tab, click the Landing pages category.
3. In the Landing pages pane on the left side of the screen, locate the page that you want to delete.
4. Hover over the page name, and then click the More icon.
5. Click Delete.
Organizing the main navigation for a portal

Build a navigation menu that effectively organizes the content of your portal by adding pages to the menu and determining
the available case types.

b. In the Current channel interfaces section, click the icon that represents the portal whose menu you want to edit.
2. On the portal page, on the Content tab, click the Navigation category.
3. In the Navigation menu section, configure the look of your navigation menu:
To add a page to the menu, click Add item, and then select the page from the list.
To remove a page from the menu, click the Remove icon next to the page name.
To change the order in which pages appear in the menu, drag the pages to rearrange their positions.
The preview on the right side of the work area reflects the changes that you make to the menu.
4. In the "Create" menu section, define which cases the user can create by clicking the Add case type menu item:
You can add only parent cases to the menu.
a. To add a case type to the menu, click Add case type, and then select the case type.
b. If you want to remove a case type from the menu, click the Remove icon next to the case type name.
c. If you want to change the order in which cases appear in the menu, drag the case types to rearrange their positions.
5. Click Save.
Creating a portal
Portals for personas

You can use portals to design custom web interfaces for various personas in your application. Portals help you to control the
content with which each user interacts.
Users have different needs that align with the roles they play within the case management process. To improve their
experience, you can design a web interface that provides them with the information and functionalities they need, but hides
options that are not relevant to their role. This method contributes to a cleaner user interface and makes navigation quicker
and more convenient.
Depending on the needs of your organization, you can set up a single portal and control the visibility of particular UI elements
through personas and access privileges, or create separate portals for individual user groups. In the case of multiple portals,
each version uses the same ready-to-use designs, which provide a reliable basis for a flexible user interface. The streamlined,
single-design approach improves run-time performance and reduces development effort.
Providing persona-based access to a portal

Create a personalized user experience by providing each user group with a specialized interface. By associating personas with
portals, you can ensure that users see only the content that they need, which improves efficiency and makes navigation more
convenient.
You can assign as many personas as you need to each portal.

b. In the Current channel interfaces section, click the icon that represents the portal that you want to edit.
2. On the Configuration tab, in the Personas section, assign a persona to the portal:
Choices Actions
Existing persona Click Add, and then click the persona to which you want to give access to the portal.
a. Click Add New persona .

New persona b. In the New persona window, provide a name, icon, and a description for the new persona.
c. Click Submit.
3. Optional: To assign more personas to the portal, repeat step 2.
4. Optional: To exclude a persona from the portal, click the Delete icon.
5. Click Save.
What to do next: You can gain a more granular control over the content by defining default channels and visible pages for
each persona. For more information, see Granting personas access to channels and pages.
Creating a portal
Previewing a portal
Preview a portal that you develop to verify that different types of devices, such as a desktop computer or a tablet, correctly
display the user interface.
Note: Device preview is not a substitute for application tests on an actual device.
1. In App Studio, click Preview, and then select a portal that you want to preview by clicking the portal list next to the
application name.
2. In the navigation pane of App Studio, check the preview size by hovering over the monitor and tablet icons. Result:
Different preview shapes indicate the screen size for every device.
3. Display the application preview for a device by clicking that device icon.
Note: When you preview a web portal on a mobile device, App Studio displays it in a mobile browser. The browser
interface is different from a Mobile Client channel, which is a separate, mobile-native interface.
4. For tablets, toggle the viewing modes:
a. Switch between landscape and portrait modes by clicking the device icon again.
b. Preview the app for a specific mobile device, in the drop-down list next to the device icons, select a device model.
You can edit the list of devices in Dev Studio. For more information, see Adding, editing, and deleting a preview
device.
For example: The following visualization shows how to preview a portal at run time.
Adding, editing, and deleting a preview device

To preview how a specific device, such as a phone or a tablet, displays your application, modify the list of devices for which
you can generate a preview. If you have access to Dev Studio, you can add a new device to the list, edit an existing device in
the list, or delete a device from the list.
Before you begin: Ensure you have access to Dev Studio.
1. In the navigation pane of Dev Studio, click Data types.

2. Click Options Add data type .
3. In the Add data type dialog box, click Existing data type.
4. In the Label field, enter Device, and then select the Pega-DevicePreview-Device rule.
5. Click Submit.
6. In the Pega-DevicePreview-Device rule, click the Records tab, and then update the device list:
To add a device, click Add record at the bottom of the list, enter the device details, and specify the user-agent
string for the device browser.
To edit an existing device, select and edit the fields that you want to change.
To delete a device, click the Delete icon next to the device that you want to remove from the list.
Result: The device information is saved automatically when you navigate away from the editable fields.
Result: The device list for app previews shows the changes that you made.
Previewing a portal
Working with views

You use views to display and collect information in your applicaton, for example, to fulfill requests or process cases. By setting
up intuitive views and populating them with fields, you help users process their work with less effort.
Cosmos React introduces a new approach to view authoring. For a brief overview of the most important changes, see
Configuring Cosmos React.
Collecting and displaying information

Users interact with your applications by using views, which comprise the interface of each assignment in the case life cycle
and each data object. The forms that you can edit to collect user information, tables that display case data, and read-only tabs
are all examples of views.
Cosmos React provides you with ready-to-use view templates that cover a many common UX layouts and scenarios. You can
edit the views built on certain templates, which enables you to use them to gather user data, while other templates are read-
only and are meant for displaying only data that is already in the system. You can reuse most views to improve consistency,
and you can make editable views read-only in a different context.
You can find the views associated with your case type or object on the User Interface tab.
For example: The following figure represents a sample User Interface tab in a mortgage application.
UI tab in the case type

The view list on the left side of the tab includes all views in the case, including views that the application does not use
currently and views that the application creates automatically, for example, full case views.
You use the central Edit pane to configure the content of your view. The Preview presents an image of what your view might
look like in context.
Types of views
The Cosmos React framework includes the following types of views on the views pane:
View Description Editability Configuration
The main interface where the user processes case work or

Full view accesses information about a data object. The system Read-only Configuring a full view
creates one full view for each case or data object.
A view that you create for a specific case or object. These

views include custom views that you create during
Case view application development and default views that the
(for case application creates, namely the Details, Preview, and
types) and Summary views. When enabled, the Confirmation view Configuring case and object
Read-only
object view also appears in the case views list. views
(for data
objects) By default, the system sets Details and Summary views as
tabs on the full view page.
A view that relies on a data source. Depending on the

configuration, the system can display lists as tables or tile- Editable and
List Configuring list views
based galleries. By default, every case includes a list that read-only
contains open cases. Data objects do not use list views.
A view that the user interacts with when working on the

case. The system creates a from view for each step in the
workflow when you click Configure view on the Workflow
tab. The Create and Edit views, which appear automatically
Editable and
Form in the Form list, represent the opening form of your Configuring forms
read-only
application and the form that is connected to the edit button
in the case header respectively. The form list also includes
the default case history list view. Form views use the default
form template or simple column templates.
Populating views with content

You can populate views with UI elements, such as text fields, checkboxes, lists, and other views. You can reuse the same fields
in different views and contexts and configure their behavior to meet your business needs. For more information, see
Configuring fields.
Depending on whether your view is editable or read-only, the same field, or the same reused view, might look differently.
For example: In the following scenario, a mortgage application includes a Mortgage type view. The view is a form, and it is
attached to a step in the case workflow. As an editable form, the view includes drop-down lists and editable fields.
Sample editable view
On the other hand, the same Mortgage type view can be iin a read-only context. In this case, the view is in the Details tab
of the case.
Sample read-only view
The application displays the same fields as read-only.
Creating views in Cosmos React
Create personalized views for your cases and data objects to capture and display the information that your users need.
By creating a view, you can lower application development time and costs because you can reuse views for multiple
contexts.
Configuring views
When users interact with your application, the interface they see is composed of views. Views hold UI components, such
as fields, widgets, and other views, and organize them by using out-of-the-box layouts that match common interface
scenarios. By configuring a view, you decide which template to use, and what kind of content to display in your view.
Configuring fields
Fields model data in your application UI and define what information you need to provide to reach your business goals.
Creating views in Cosmos React

Create personalized views for your cases and data objects to capture and display the information that your users need. By
creating a view, you can lower application development time and costs because you can reuse views for multiple contexts.
For example, you can create a view that captures feedback from a customer after you resolve a case, such as a loan request,
and then save time by reusing the view for other case types for which you need to collect feedback.Note: When you create a
case or data object, Pega Platform generates the following out-of-the-box views:
Details view
Full view
Preview
Summary data view
1. In the navigation pane of App Studio, click Case types, and then click the case type that you want to open.
2. Create a view:
Choices Actions
a. On the Workflow tab, in the Life cycle section,

click an assignment or an approval step.
b. In the Step properties panel, click Configure
For a new step
view.
c. On the Display tab, next to the template
miniature, click Edit.
a. On the User interface tab, in the Views pane on

From the views listNote: The Forms list includes only the the left side of the screen, click Add.
views for new steps that you initially configured in the b. In the Create a new view dialog box, in the
Workflow tab. Name field, provide a meaningful name for your
view.
a. On the Data model tab, in the Options column,

click the data object for which you want to create
a view.
b. On the User interface tab of the data object, in
For data objectsNote: Data object views are read-only. the Views pane on the left side of the screen,
click Add.
c. In the Create a new view dialog box, in the
Name field, provide a meaningful name for your
view.
3. In the list of templates, select the type of template that you want to use:
To create a read-only view that is specific to the case, select one of the Details templates.
To create a read-only view with tabs that you manually define, select Details (Sub tabs).
To create an editable smart form view that adjusts its size and layout to content, select Default form.
To create a read-only view that automatically sources tabs from a data object, select Dynamic tabs (list).
To create an editable simple form view, select one of the columns templates.
To create a view with a table, timeline or tile gallery, select Table.
For example: If you want to create a read-only view with three columns, select Details (Three column).
View templates
Note: When you create views for steps in the Workflow tab, the list includes only column-based views.
4. Click Submit.
What to do next: Add content to the newly created view:

If the view uses a details template, add UI elements to the view. For more information, see Configuring details views.
If the view is for a step, add UI elements to the view. For more information, see Configuring forms.
If the view uses a table template, configure the table settings. For more information, see Configuring tables and
Configuring a timeline.
If the view uses a tab template, configure the tabs and their content. For more information, see Configuring tabs and
Configuring dynamic tabs.
Configuring views
When users interact with your application, the interface they see is composed of views. Views hold UI components, such as
fields, widgets, and other views, and organize them by using out-of-the-box layouts that match common interface scenarios.
By configuring a view, you decide which template to use, and what kind of content to display in your view.
Whenever you configure your view, the basic setup of your workspace is similar. The following figure presents a sample
representation:
A case view on the User Interface tab
While your workspace setup does change depending on the type of view you are editing, it generally includes the following
elements:
1: Add view button

Use to create new views.
2: Views list
When you access views through the User Interface tab of your case type, this list displays all views related to the
specific case, divided by type.
3: Template options
Use to select a template for your view. Depending on the type of your view, the available templates might vary. For
example, landing pages use different templates than forms.
4: Label and heading
Help you identify your view. The label is used internally in your application, for example on view lists, while the header is
displayed above your view at run time.
5: Additional settings
Other settings for adjusting the look and behavior of your view. Depending on the type of your view, the available choices
might vary. For example, additional settings in a table include options for defining the data source for the table.
6: Fields
Display and collect information in your application. You can use the icons next to the field name to remove the field or
access extra configuration settings. The configuration settings for fields include common settings, such as visibility or
helper text, and field-specific settings. For example, currency fields have options for defining a currency symbol.
7: Views
Embedded views. The link in the view name opens the configuration options for that view.
8: Add button
Allows you to populate the view with another existing UI component, such as a field or a view. In some views, for example
landing pages, you can also use this button to add insights and widgets.
9: Preview
Shows an example of what your view looks like. The preview reflects changes you make to the configuration in real time.
Configuring a full view
Give cases and data objects a visual representation to help users access the data that they need to successfully process
work. When you create a case type or data object, the application automatically adds a view that represents the visual
framework for processing related information.
Configuring case and object views
Cluster UI components into a convenient module that you can reuse in different contexts throughout your application by
using case and object views. You can use case views for case types and object views for data objects in read-only
scenarios, for example, as tabs on the full view page.
Configuring list views
Help users access and compare data with lists. Use tables, timelines, and tile galleries in your applications as a flexible
basis for users to process large amounts of information. For example, tables in a price comparison application can help
users efficiently identify the best offer.
Configuring forms
Help users complete their work efficiently by configuring intuitive form views. For example, in a loan application, you can
create a view with fields for collecting data about a secondary applicant and, when needed, reuse that view in different
contexts throughout the application. By default, the system creates one form view for each step in the workflow.
Configuring a full view

Give cases and data objects a visual representation to help users access the data that they need to successfully process work.
When you create a case type or data object, the application automatically adds a view that represents the visual framework
for processing related information.
You can find the full view in the views pane on the User Interface tab of a case or a data object.
Full view on the User Interface tab

Before you begin: Prepare data components that you want to add to a view. For more information, see Configuring a data
model for a case.
2. Open the full view that you want to configure:
Choices Actions
On the User interface tab, in the Views pane on the left side of the window, click
Case view
Full case view.
a. On the Data model tab, in the Options column, click the data object for which
Data viewNote: Data object you want to create a view.
views are read-only. b. On the User interface tab of the data object, in the Views pane on the left
side of the screen, click Full data view.
3. Define the header for the page:
a. In the Header list, select the field whose content you want to display as the main header.
b. In the Subheader list, select the field whose content you want to display as the secondary header.
c. Optional: To remove the default case icon from the header, clear the Show icon in header checkbox.
d. Optional: In the case view, to remove the life-cycle chevrons from the header, clear the Show case life cycle
checkbox.
The preview on the right side of the work area reflects the changes that you make to the page.
4. In the Tabs section, manage the tabs in the pane on the left side of the case page:
By default, the application creates the Details and Pulse tabs.
To create a new tab, click Add, and then enter the name for the tab.
To remove a tab, click the Remove icon.
To change the position of a tab, drag the tab into place.
5. Optional: To edit the content of each tab, click the Drill in icon for that tab, and then updates the tab:
To change the name of the tab, in the Tab name field, enter a new name.
To add a widget, view, field, or an insight to the tab, click Add, and then select the item that you want to add.
To change the position of a field or a view on the page, drag the component into place.
To remove a field or a view from the page, click the Remove icon.
Note: All views in a full view are read-only, including embedded form views.
6. In the Utilities section, manage the widgets in the expandable pane on the right side of the full view:
For case views, the application adds the Attachments, Related cases, and Followers widgets automatically to the
Utilities section.
To add a new widget, click Add, and then select the widget that you want to use.
To change the name of a widget, click the Configure icon, and then provide the new widget name.
To remove a widget, click the Remove icon.
To change the position of a widget, drag the component into place.
7. Click Save.
For example: In this scenario, the full case page includes a promoted action button in the header (1), four tabs (2), case life
cycle chevrons (3), and a utilities pane with Followers, Attachments, and Related cases widgets (4).
Sample full view configuration in a case

What to do next: Configure the other components that appear in the full view:
To configure the details view see Configuring details views.

To configure the summary information view, see Configuring the summary data view.
To configure the preview, see Configuring the preview.
Widgets in Cosmos React
Cosmos React provides a wide range of widgets that you can add to your application to improve usability by gathering
helpful functions in one place. For example, a banking application can include the Attachment widget with which users
can upload documents to speed up the mortgage process.
Configuring common field settings

Cosmos React provides a wide range of widgets that you can add to your application to improve usability by gathering helpful
functions in one place. For example, a banking application can include the Attachment widget with which users can upload
documents to speed up the mortgage process.
Some widgets are customizable and require additional configuration to fully work, while others are ready to use by default. For
example, you can help users maintain clarity in attachments by defining custom categories for the attachments that they
upload to cases.
You can customize your Pega Platform applications with various widgets:
App announcements
Displays a welcome banner for the user on the portal Home page. You can modify the text and the background of the
announcement, as well as the destination of the action button.
For more information, see Configuring the Home page welcome banner.
Attachments
Supports adding files and links to assignments. For more information, see Categorizing case attachments.
Case history
Shows details about assignments in the form of a table. For example, the information includes names of users who
perform actions in an assignment.
The widget does not require additional configuration and is ready to use by default.
Case operator
Includes the name of the user who submits an assignment.
The widget does not require additional configuration and is ready to use by default.
Followers
Shows the list of users who track the progress of a certain case. For more information, see Following a case.
Pulse
Displays a message feed.
Pulse
Provides users with a message feed in which to communicate with each other.
The widget does not require additional configuration and is ready to use by default. For more information, see Configuring
Pulse for case types.
Related cases
Shows the list of cases that are related to a certain case.
The widget requires additional configuration. For more information, see Configuring the Related cases widget.
Stakeholders
Shows the list of users who are the first points of contact for a certain case.
The widget requires additional configuration. For more information, see Configuring case participants.
Tags
Shows the list of tags that are relevant to a certain case.
The widget requires additional configuration. For more information, see Configuring the Tags widget.
To do
Displays list of open cases assigned to the user on a portal landing page. For more information, see Configuring the Todo
widget

Configuring the Related cases widget
Help users get a broader perspective on assignments by providing the option to include related cases in a dedicated
widget. For example, in a loan application case, users can add interrelated cases about their credit history to ensure that
all relevant information is in one place.
Configuring the Tags widget
Help users find relevant information by providing a readable landing page that stores data with assigned tags. Displaying
tagged data in one place saves users' time and enhances the process of analysis.
Configuring case participants
Identify the people, businesses, and organizations that receive case notifications by defining case participants. For
example, you can create a group of customer service representatives so that they can receive notifications about new
assignments and upcoming goals and deadlines.
Configuring the Related cases widget

Help users get a broader perspective on assignments by providing the option to include related cases in a dedicated widget.
For example, in a loan application case, users can add interrelated cases about their credit history to ensure that all relevant
information is in one place.
Configuring the widget
2. On the User interface tab, open the full view.
3. In the Edit view pane, in the Utilities section, click the Configure related cases icon.
Note: The Related cases widget appears in the utilities pane of the full view by default.
4. If you do not see the widget, add it to your application by clicking Add Related cases Add .
5. In the Edit widget: Related cases dialog box, manage the widget settings, and then click Save. For example: In the
Visibility list, select Custom condition and configure the widget to appear when the assignment status is Open.
Managing related case types
6. In the case type, click the Settings tab.

7. In the menu on the left side of the case type, click Related case types, and then, in the main pane, click Add related
case type.
8. In the drop-down list, select the case types that you want to show in the widget.
9. In the upper-right corner of the case type, click Save.
For example: The following visualization presents the related cases widget at run time. In this example, the user adds
several cases to the loan application assignment.
Run time use of the Related cases widget

Using conditional logic in Cosmos React
Configuring the Tags widget

Help users find relevant information by providing a readable landing page that stores data with assigned tags. Displaying
tagged data in one place saves users' time and enhances the process of analysis.
After user clicks a certain tag, the system displays a comprehensible landing page with cases and Pulse comments that
contain that tag. For example, if you click the Testing tag, the system retrieves all cases and Pulse comments with that tag.
To use the Tags landing page, you configure the pyConfigureTagsLandingPageURL data transform that maps properties with a
URL that holds the landing page.Note: If you do not configure the data transform, then after clicking a tag, the system opens
a list of cases with tags in a modal dialog box.
1. In the navigation pane of Dev Studio, click Records.

2. Expand the Data Model category, and then click Data Transform.
3. In the list of data transforms, select pyConfigureTagsLandingPageURL.
4. In the editing view for the data transform, choose the property for URL mapping:
a. On the Definition tab, in the Action list of the .pyURLContent property, select Set.
b. In the Source field, select a property that holds the URL mapping.
5. In the upper-right corner of the data transform view, click Save.
For example:
Tags landing page
The following example shows the Tags landing page with all cases and Pulse posts that include the #ui tag.
Configuring case participants
Identify the people, businesses, and organizations that receive case notifications by defining case participants. For example,
you can create a group of customer service representatives so that they can receive notifications about new assignments and
upcoming goals and deadlines.
You can define internal participants that are users of your application, and external participants that do not have an account in
your application, such as stakeholders. You can also refer to participants as work parties.
2. In the case working area, click the Settings tab.
3. In the settings pane, click Participants.
Note: At run time, the widget is called Stakeholders.
4. In the Participants section, click Add participant.
5. In the Participant configuration window, in the Role name field, enter a unique name that indicates the relationship
of the participant to the case type, for example, Worker.
6. Define role preferences for the participant:
Choices Actions
a. In the Role has user account with this application section, select Yes.
b. Optional: To populate information about a participant, in the Preferences section, associate the
participant with the current user or a reporting manager of the current user, by clicking Map
participant, and then selecting either Current user or Reporting manager. For example: If you
Participant
map a participant to a current user, an application populates participant information with values that
with an
describe a user who currently processes the case at run time, without using a separate data
account in
transform for each user.
your
c. Optional: To save time and create more participants that have the same notification settings, enable
application
creation of multiple participants for this role by selecting the Allow multiple participants for this
role checkbox.
d. Optional: To speed up case creation, enable automatic creation of participants when the case starts
by selecting the Create participant automatically when the case starts checkbox.
Participant
a. In the Role has user account with this application section, select No.
without an
b. Optional: To save time and create more participants that have the same notification settings, enable
account in
creation of multiple participants for this role by selecting the Allow multiple participants for this
your
role checkbox.
application
7. Click Done.
8. Click Save.
For example: The following visualization presents the Stakeholders widget at run time.
Configuring case and object views
Cluster UI components into a convenient module that you can reuse in different contexts throughout your application by using
case and object views. You can use case views for case types and object views for data objects in read-only scenarios, for
example, as tabs on the full view page.
Case and object views include custom views that you create during application development and default views that the
application creates automatically, namely, the Details, Preview, and Summary views. When enabled, the Confirmation
view also appears in the case views list.
By default, the system sets Details and Summary views as tabs on the full view page.
You can case and object views in the views pane on the User Interface tab of a case or a data object.
Case views on the User Interface tab

Configuring the preview
Help your users get the main facts about a case or a data object without opening a new browser tab. By configuring a preview,
you can decide which fields the preview panel displays on the right side of the application when the user clicks the preview
option.
2. Open the preview that you want to configure:
Choices Actions
Case
On the User interface tab, in the Views pane on the left side of the window, click Preview.
view
a. On the Data model tab, in the Options column, click the data object for which you want to create a
Data view.
view b. On the User interface tab of the data object, in the Views pane on the left side of the screen, click
Preview.
3. Adjust the appearance of the preview pane by doing any of the following actions:
To remove the case life cycle chevron from the preview, clear the Show case life cycle checkbox.
To hide related assignments, clear the Show assignments checkbox.
For example: In this scenario, the preview presents the details of a loan attestation case.
Sample preview configuration for a case

Configuring the summary data view
Give your users a convenient way to check important case or data object information by configuring the summary data view.
The summary data view appears on the left side of the case page and lists data, such as case priority, status, or history.
2. Open the summary view that you want to configure:
Choices Actions
Case
On the User interface tab, in the Views pane on the left side of the window, click Summary data.
summary
a. On the Data model tab, in the Options column, click the data object for which you want to create
Data a view.
summary b. On the User interface tab of the data object, in the Views pane on the left side of the screen, click
Summary data.
3. In the Highlighted fields section, click Add, and then select which fields and widgets you want to display at the top of
the case summary pane. For example: To add a widget that displays links to related work items, click Add Widgets
Related cases .
4. In the Fields section, click Add, and then select which fields and widgets you want to display below the primary fields on
the case summary pane. For example: Click Add Fields Case ID .
For example: In this scenario, the summary data view displays Priority and Borrower primary fields, as well as several
case-related secondary fields, including Purchase Price and Mortgage amount.
Sample summary data view configuration for a case
The fields that you map into the Highlighted fields region render inline from left to right, and their values render with a
pronounced visual treatment. The fields that you map into the Fields section stack vertically along the summary panel with
the field label on the left and the value on the right.
Configuring details views

Build case-wide UI modules by defining the form and content of a details view. Details views are clusters of UI components,
such as fields, that you reuse in different contexts across your application in read-only mode.
For example, in a loan application, you can create a view with account details of the loan applicant.
Create a column-based details view. For more information, see Creating views in Cosmos React.
Prepare the data components that you want to add to the view. For more information, see Configuring a data model for a
case.
2. Open the view that you want to configure:
Choices Actions
Case
On the User interface tab, in the Views pane on the left side of the window, click Details.
view
Data
Choices view.
Actions
view b. On the User interface tab of the data object, in the Views pane on the left side of the screen, click
Details.
3. In the Edit view section, define the layout and header for the view:
To change the view template, click Edit, and then click the template that you want to apply to the view.
To change the name under which the view appears on the view list, in the View name field, enter a new view name.
To change the text of the label that appears at the top of the view at run time, in the View label field, enter a new
label text.
To display the view without a label at the top, clear the Show label checkbox.
4. Optional: To display selected fields in a prominent position on the top of the view, perform the following actions:
a. Select the Enable highlighted fields checkbox.
b. In the Highlighted fields section, click Add, and then select the field that you want to highlight.
5. In the Region section, define the content of the view:
To add a field, view, data relationship, or UI component to the view, click Add, and then select the item that you
want to include.
To change the position of a field or view on the page, drag the component into place.
To remove a field or view from the page, click the Remove icon.
6. In the row with the new item, click the Configure icon, and then define additional settings, such as labels and visibility.
For more information, see Configuring fields.
7. Click Save.
For example:
In this scenario, the details view displays fields that contain information about the loan originator.
A sample details view for a case
Configuring tabs
Group fields together in your application by category with a tabbed view template. By using tabs, you can create an intuitive
UI that saves screen space and helps users find the information they need with less effort.
Depending on your business needs, you can also nest tabs views inside other tab views.
Create a view that uses the tabbed template. For more information, see Creating views in Cosmos React.
Prepare data components that you want to add to the view. For more information, see Configuring a data model for a
case.
2. On the User interface tab, click the tabbed view that you want to edit.
Data objects do not support simple tabs.
3. In the Edit view section, define the header for the view:
To change the text of the label that appears at the top of the view at run time, in the Header field, enter a new label
text.
To display the view without a label at the top, clear the Display header checkbox.
4. In the Tabs section, click Add.
5. In the New tab dialog box, enter the name for your tab, and then click Submit.
6. In the Tabs section, next to the newly added tab, click the Drill in icon.
7. In the Edit tab pane, configure the tab by doing any of the following actions:
To change the tab label, in the Tab name field, enter the new label text.
To add a widget, view, field, or an insight to the page, click Add, and then select the UI component that you want to
add.
To change the position of a UI component on the page, drag it into place.
To remove a component from the page, click the Remove icon.
To define when the tab appears in the view, in the Visibility list, define the visibility condition.
8. At the top of the Edit tab pane, click Back to return to the main view.
9. Optional: To create additional tabs, repeat steps 4 through 8.
For example: In this scenario, the Pulse and History views are sharing a tabbed template.
Sample tabbed view configuration for a case

Configuring dynamic tabs
Source your UI from data objects to keep your UI up to date with minimum effort. By linking a dynamic tab in your application
to a data object, you can ensure that the system automatically updates the UI to match any changes to the data.
For example, you can use dynamic tabs to display information about your customer's subscriptions. You create a Subscriptions
data object that holds the list of services that the customer uses, and then use that object as a data source for dynamic tabs,
with separate tabs for each service. If the user adds a new subscription service to the list, the system automatically adds a
new tab for that service, with no additional configuration required.
Before you begin: Prepare the tab components:
Create a data object.

In the case type, create a view that uses the dynamic tabs template.
In the data object, create a view that you want to use for the tab.
For more information, see Adding data objects to organize data and Creating views in Cosmos React.
Choices Actions
On the User interface tab, in the Views pane on the left side of the window, click the dynamic tabbed view
Case
that you want to edit.
Data view.
object b. On the User interface tab of the data object, in the Views pane on the left side of the screen, click the
dynamic tabbed view that you want to edit.
To change the name under which the view appears in the view list, in the View name field, enter a new view name.
To change the text of the label that appears at the top of the view at run time, in the Header field, enter the new
label text.
4. In the Data page field, select the list for the data object from which you want to source the tab information. For
example: Select List subscriptions, which is the auto-generated list for the Subscriptions data object.
5. In the Tab label field, select the data object property that determines how the system divides content into tabs. For
example: Select Subscription name.
In the Subscriptions data object, the Subscriptions name field has three records: TV, Internet, and Mobile. Consequently,
the system sources three tabs, TV, Internet, and Mobile, each representing a single record.
6. In the Tab content field, select the data object view that you want to display on the tab. For example: Select Details.
For example: In this scenario, the tabs represent records in the Subscriptions data object.
Sample dynamic tabs at run time

Configuring a confirmation view
Help your users better understand the next steps in their work by configuring an out-of-the-box confirmation view. A
confirmation view appears when the user completes all of their assignments, and you can configure it to display custom
instructions or a list of open tasks that might interest the user later in the process.
For example, you can use your application to register customer complaints. When the case worker completes processing a
complaint and has no more work assigned, the confirmation view displays guidance on what to communicate to the user who
logged the complaint.
Enabling the confirmation view
2. In the case type, click the Settings tab.
3. In the menu on the left side of the case type, click General.
4. In the Assignment processing section, select the Display custom view when no more assignments are available
to the user checkbox.
5. Click Save, and then, click Actions Refresh .
Configuring the view
6. On the User interface tab, in the Case views section, click Confirmation.
To change the text of the label that appears at the top of the view at run time, in the View label field, enter the new
label text.
To display the view without a label at the top, clear the Show label checkbox.
8. In the Region A section, define the content of the view:
To add a field, view, data relationship, or a UI component to the view, click Add, and then select the item that you
want to add.
To remove a field or a view from the page, click Remove this field.
9. In the row with the newly added item, click the Configure icon, and then define additional settings, such as labels and
visibility.
10. Optional: To hide open assignments from the view, clear the Show tasks checkbox.
Tip: You can edit the What's next message by editing the contents of the pyWhatsNext property. For more information,
see Configuring page, page group, and page list properties.
For example: In this scenario, the view uses a two-column template.
A sample confirmation form at run time

Configuring list views
Help users access and compare data with lists. Use tables, timelines, and tile galleries in your applications as a flexible basis
for users to process large amounts of information. For example, tables in a price comparison application can help users
efficiently identify the best offer.
You can also configure views to support editing, sorting, and custom presentation options.Note: Data objects and case objects
do not use list views, but can produce tables through field configuration. For more information on configuring data and case
objects as tables, see Configuring fields associated with case and data objects.
You can find list views in the views pane on the User Interface tab of a case. Data objects do not use list views.
List views on the User Interface tab

Create a view that uses the list template. For more information, see Creating views in Cosmos React.
Identify a data page from which you want to source the table content. For more information, see Creating a data page
and Creating fields for capturing data.
Configuring tables
Present large amounts of information in a clear and consistent way by using tables. Tables are flexible and familiar user
interface components, and provide a reliable basis for users to view or compare information.
2. On the User interface tab, click the list that you want to edit.
Note: The Case history view, which is listed under Forms, is fully configured out-of-the-box to display the log of all user
actions that are related to the case. You can edit presentation options, such as sorting and grouping, but changing data
page and parameter settings might cause the view to display errors.
3. In the Data page field, select the data page from which you want to source the list contents.
4. In the Display name field, enter the name for the view.
5. In the Template field, select Table.
6. In the Columns section, add the columns that you want to include in the view by clicking Add, and then select the field
that you want to associate with the column.
7. In the Column to take up remaining width , define which column stretches to fill free space in your table.
9. Define how the application sorts data in the table:
10. Optional: To group the table contents by a property, in the Group by list, add the property by which you want group
the table by clicking Add, and then selecting the target field.
11. In the Max height (rows) list, select the maximum height of the list view.
12. Optional: To enable bulk processing of list items, select the Allow bulk actions checkbox.
Tip: Bulk processing is available for tables on case pages and landing pages. The actions in the bulk action menu are
case-wide actions. For more information, see Adding optional actions to cases and Troubleshooting errors in bulk
processing.
13. Optional: To define additional table behavior, select any of the checkboxes in the Editing and User Personalization
section. For example: Select the Allow adding new records checkbox, and then in the Action label field, enter the
label for the action, such as New mortgage case .
You can populate the new row with default values by setting up a pre-processing data transform. For more information,
see Adding data transform to a process.
14. Optional: To add a new view to the list, under the data source list, next to the Default view tab, click Add, and then
repeat steps 5to 13
15. Click Save.
For example: If you configure several views for your list, at run time, the table includes a view picker similar to the one that
is presented in the following figure:
View picker
Configuring galleries
Automate the display of repetitive data records with a tiled gallery. For example, you can use a gallery template to arrange
data about pending mortgages into a series of standardized cards that display the name, mortgage amount, and an case ID of
each application.
2. On the User interface tab, click the list that you want to edit.
3. In the Data page field, select the data page from which you want to source the list contents.
4. In the Display name field, enter the name for the view.
5. In the Template field, select Gallery.
6. In the Card header list, select the field that you want to use as the header for your tile.
7. In the Secondary text field, select the field that you want to use as the source of additional text on your tile.
8. In the Columns section, add the columns that you want to include in the view by clicking Add, and then select the field
that you want to associate with the column.
9. In the Column to take up remaining width , define which column stretches to fill free space in your table.
11. Define how the application sorts data:
12. In the Max height (rows) list, select the maximum height of the list view.
13. Optional: To define additional gallery behavior, select any of the checkboxes in the User Personalization section.
repeat steps 4 to 12.
15. Click Save.
For example:
If you configure your view as a gallery, the UI displays list entries as tiles. The following image represents a sample gallery tile:
Sample tile of a gallery-based list
Configuring a timeline
Provide users with insight into your business process by displaying data in chronological order. A timeline view presents a
progression of events that is sourced from a data page that includes information about the time and the nature of the event.
For example, in a loan application, you can use a timeline view to present the employment history of the applicant, arranged in
reverse chronological order, with the current employer displayed first.
Create a view that uses the table template. For more information, see Creating views in Cosmos React.
Identify the data page from which you want to source the timeline content. For more information, see Creating a data
page and Creating fields for capturing data.
Ensure that the data page you want to reference includes a Date Time field and a field with a label for the event.
2. On the User interface tab, in the List section, click the view that you want to edit.
3. In the Data page list, select the data page from which you want to source the list contents.
4. In the Display name list, enter a name for the view.
5. In the Template list, select Timeline.
6. In the Date list, select the Date Time field that holds the information about the time of the event.
7. In the Title list, select the field that holds the description of the event and appears as the heading for the timeline entry.
8. Optional: To define additional timeline settings, perform the following actions:
a. To add an icon to each timeline entry, in the Icon list, select the property that holds the icon reference.
Note: The icon reference must be a string that contains the name of the icon in the Cosmos design library, for
example 'car-solid'.
b. To add a status indicator, in the Status list, select the property that holds the status reference.
c. To add fields to a collapsible section inside each event, in the Additional fields section, click Add, and then select
the target fields.
9. In the Date grouping list, define the time period by which you want to sort the entries.
10. In the Filter by list, define whether you want to filter the entries.
11. In the Sort by list, define the order in which the timeline displays the entries.
Note: The settings in the User personalization sections and the Max height (Rows) setting do not apply to the
timeline view. The timeline also does not support grouping or search.
repeat steps 5 to 11.
13. Click Save.
For example: In this scenario, the timeline view displays the employment history of the applicant:
A sample timeline view at run time

Reordering records on lists
Help users edit records in a data object by making table rows draggable. For example, in a customer service application, you
can use this feature to provide users with convenient tools to reshuffle the priority of outstanding work.
Pega Platform comes with an out-of-the-box pyMoveRecords data transform in which you can define the logic that you want
the application to apply when the user drags a table row. In the case of the customer service application, you can set up a
logic that increases the priority of work items when they move up in the list.
Before you begin: Create and configure a view that uses the table template.
Enabling moving records in App Studio
2. On the User interface tab, in the Lists section, select the list that you want to edit.
3. In the Editing section, select the Allow moving records checkbox.
Adding the pyMoveRecords data transform to the data list class in Dev Studio
4. In Dev Studio, search for and open the pyMoveRecords data transform.
5. On the pyMoveRecords tab, click Save as.
6. On the New tab, in the Apply to field, enter the class of the data list that you use to provide records to your table.
7. Click Create and open .
Editing the data transform
8. In the class-specific pyMoveRecords rule that you created, on the Definition tab, define what the application does when
the user changes the order of table rows.
For more information on composing data transforms, see Data transforms.
9. In the rule form, click Save.
Available columns
When you configure tables, the configuration of the data page from which you source the table content determines the list of
fields that you can include in the table as columns.. By understanding the characteristics and limitations of each data page
configuration, you can build better table views.
Data page with a report definition

If the data page that you use to source table content uses a report definition, you can add the following fields to your table:
Basic fields that you add as columns on the backing report if the fields are optimized for reporting and marked as relevant
records for the current class.
Embedded properties from pages (single page properties) that you add as columns to the backing report if the properties
are optimized for reporting and marked as relevant records for the current class.
Properties from associations rules that you add as columns to the backing report if the association rule is a simple
association and the properties are optimized for reporting and marked as relevant records for the current class. The
complex version of the association rule form is not supported.
For example:
Simple rule form for association rules
The data page with a report definition cannot support the addition of the following types of fields to tables:
Fields that are specified in the backing report that require complex associations or joins that are specified in the report
definition.
Embedded properties from page lists.
Embedded properties from page groups.
Data page without a report definition

If you source table content from a data page without a report definition, you can dd only basic fields to your table.
The data page without a report definition cannot support the addition of the following types of fields to tables:
Embedded properties from pages.

Embedded properties from page lists.
Embedded properties from page groups.
Properties from association rules.
Configuring forms
Help users complete their work efficiently by configuring intuitive form views. For example, in a loan application, you can
create a view with fields for collecting data about a secondary applicant and, when needed, reuse that view in different
contexts throughout the application. By default, the system creates one form view for each step in the workflow.
You can find forms in the views pane on the User Interface tab of a case or data object.
Forms on the User Interface tab

Create a view for a step. For more information, see Creating views in Cosmos React.
Prepare the data components that you want to add to the view. For more information, see Configuring a data model for a
case.
Choices Actions
CaseNote: The list includes only the views for

On the User interface tab, in the Views pane on the left side of
new steps that you initially configured in the
the window, click the form view that you want to edit.
Workflow tab.
a. On the Data model tab, in the Options column, click the

data object for which you want to create a view.
Data object b. On the User interface tab of the data object, in the Views
pane on the left side of the screen, click the form view that
you want to edit.
3. In the Edit view section, define the layout for the view:
To change the view template, click Edit, and then click the template that you want to apply to the view.
To change the name under which the view appears on the view list, in the View name field, enter a new view name.
4. For the Default form template, define additional template settings:
To change the number of columns, in the Number of columns list, select the target value.
To ensure that embedded views maintain their templates, in the Template for embedded view list, select Use
template.
5. In the Region section, define the content of the view:
To add a field, view, data relationship, or a UI component to the view, click Add, and then select the item that you
want to add.
To remove a field or a view from the page, click Remove this field.
6. In the row with the newly added item, click the Configure icon, and then define additional settings, such as labels and
visibility.
7. Click Save.
For example: In this scenario, the view uses a two-column template.
A sample two-column view at run time
Configuring fields
Fields model data in your application UI and define what information you need to provide to reach your business goals.
For example, in a process of hiring new employees, you can create properties that correspond with the personal details of a
candidate, such as a name, a surname, and an address.
You can adjust the type of your field to match the data that you want to collect, and pair the field automatically with a control
in the UI. For example, if you want the candidate to provide an email address, you can set up a field with the type "email." In
the user interface, the system renders the field as an Email control. To make the development process more efficient, each
field type defaults to the most intuitive control, such as a checkbox for a Boolean expression.
Field types
The following table presents available fields:
Field type Description Configuration Example (editable)
Captures alphanumeric values from a single line of text. You

can define a maximum length for the text input field, which
Text
Field(single
type determines the number of characters that are exposed in the
Description Configuring
Configuration Example (editable)
Text
line) database entry for that field's value. common field
settings
For example, you can use this field to capture the patient's
name.
Captures alphanumeric values from a box with multiple lines

of text. You can define a maximum length for the text input
field, which determines the number of characters that are
exposed in the database entry for that field's value. With
additional field configuration, you can decide whether this Configuring Text area
Text
field captures text in markup, or just plain text.Note: When common field Rich text
(paragraph)
you limit the maximum length for this field, markup content, settings editor
such as tags, also counts as characters towards that limit.
For example, you can use this field to capture the description
of symptoms that the patient provides.
Captures true or false values. By default, the UI control for

that field is a checkbox. Configuring
Boolean common field Boolean
For example, you can use this field to capture the patient's settings
agreement for storing their personal information.
Captures positive and negative decimal numeric values. The

UI displays the field with a currency code that reflects the
default currency type for the application user. Configuring a
Currency Currency
Currency field
For example, you can use this field to capture a cost of a
medical procedure.
Captures values for date and time, which Pega normalizes to

a GMT format. The UI displays the field value in a localized
format for the user. Configuring a Date
Date & time Date Time
Time field
For example, you can use this field to capture the date and
time of the patient's appointment.
Captures values for a date, which Pega normalizes to a GMT

format. The UI displays the field value in a localized format for
the user, taking into consideration the standards for digit
Configuring a Date
Date only grouping and decimal separators of the localized format. Date Time
Time field
date of birth.
Captures positive and negative decimal numeric values.

Configuring Number
Decimal
For example, you can use this field to capture the patient's Decimal fields Slider
weight.
Captures alphanumeric values that must pass a regular

expression validation for a correct email address format; the
input must include the at sign (@) followed by a domain. The Configuring
UI displays the field value as a link that launches the user's common field
Email Email
default email application. settings
email address.
Captures positive and negative whole numeric values,

including zero (0).
Configuring Integer Number
Integer
For example, you can use this field to capture the patient's fields Slider
age.
Field type Description Configuration Example (editable)
Captures positive and negative decimal numeric values that

the application displays as a percentage.
Configuring
Percentage Number
For example, you can use this field to display the body fat Percentage fields
percentage after the patient's examination. A field value of
0.25 equals 25%.
Captures numeric values. The field validates the user's input

to conform to the region-specific phone number format. The
UI displays the field value as a link that initiates a phone call Configuring
Phone on a mobile device. common field Phone
settings
For example, you can use this field to capture a patient's
contact number.
Captures an alphanumeric value that is a single choice from a

list of valid options. You can define various sources for
picklists, such as data pages or other field values. Configuring Picklist Radio button
Picklist
fields Selector
marital status.
Captures values for time, which Pega normalizes to a GMT

format. Configuring a Date
Time only Date Time
Time field
preferred appointment time.
Captures alphanumeric values that must pass a validation for

a correct URL format; the input must begin with http:// or https://
and be followed with any string. The UI displays the field
value as a link that launches the user's default browser with Configuring
URL the target web address. common field URL
settings
For example, you can use this field to display an external web
address of a medial facility where a patient can book a
procedure.
Captures files through drag-and-drop or selecting files on the

user’s device. Configuring
Attachment common field File
For example, you can use this field to receive PDF files with
settings
the patient's test results.
Captures coordinates for geolocation.

Configuring
Location For example, you can use this field to display an address common field Location
settings
where a patient needs to deliver a testing sample.
Captures a single choice from a list of all system operators

that have access to the application. This field is a special
linked field that stores a list of operators who have access to
the application. Depending on your configuration, the UI Configuring fields
displays the field as a search box or a drop-down list. associated with Table
User reference
case and data Field group
For example, you can use this field to help a patient pick a objects
primary doctor from a list of doctors that have access to the
application. The application can use that choice to directly
route work items to the chosen doctor.
Captures single or multiple records that the system sources

from a selected case type. The UI displays the field as a drop-
down in which users can choose one (single record) or Configuring fields
Case reference
Field type multiple (list of records) options from a given case type.
Description associated with
Configuration Example Table
(editable)
For example, you can use this field in the Appointment case to objects
reference one or more medial procedures from the Medical
procedure case.
Captures single or multiple records that the system sources

from a selected data object. The UI displays the field as a Configuring fields
drop-down in which users can choose one (single record) or
associated with Table
Data reference multiple (list of records) option from a given data object.
For example, you can use this field in the Appointment case to objects
reference data from the Patient data object.
Captures single or multiple records from the user-supplied

data that the application stores and sources from inside a Configuring fields
Embedded case instance or a work object. associated with Table
data case and data Field group
billing address, based on the home address they already objects
provided in the case.
Captures single or multiple records from a data page or a view

that the application stores and sources from outside a case
Configuring fields
type (other applications or systems). associated with Table
Query
For example, you can use this field to present users with a list
objects
of medical facilities in a patient's city of choice, which are
sourced from an external site.
Configuring a data model for a case
Configure a data model to define the data that you want to use in a case. For example, to include a user email address in
a case, add an email address field to the data model.
Improve the presentation of your user interface by configuring out-of-the-box fields. By adjusting options such as
visibility, helper text, or on-click behavior, you can adapt the controls to the needs of your business, and build a cleaner,
more intuitive user experience.
Configuring a Currency field
Collect and display monetary information in a field that automatically formats the amount by adding language-specific
separators and a currency-specific symbol, such as the dollar sign.
Configuring a Date Time field
Standardize date and time formats and reduce the number of input mistakes by using a Date Time field. When you set up
a Date Time field, you ensure that users enter scheduling information in the right format.
Configuring Decimal, Integer, and Percentage fields
Collect numerical information by using a standard field that checks if the user-provided format of data is correct. Create
clean, intuitive forms for your users with less effort by selecting the field type that best matches your business needs.
Configuring Picklist fields
Reduce the number of user input errors by providing the users of your application with a list of values from which to
choose. A Picklist field captures a single choice from a list of valid options presented as radio buttons or drop-down lists.
Configuring fields associated with case and data objects
A data object is a template for describing an entity through fields, such as name and address. Depending on your
business needs, data objects can reference a list or a single record, and source their information from internal or external
databases. This flexibility of approach ensures optimal reuse and better data management.
Configuring cascading drop-down lists
Reduce the time that is needed to complete a form by creating a group of drop-down lists that take cues from each
other, and adjust the available options depending on choices that the user makes in the interface.

Define the logic that governs the behavior of fields in your application more intuitively with the condition builder. By
creating conditions, you can link the visibility and availability of certain parts of your UI to your business needs, and build
a cleaner, less cluttered application.
Creating a When rule
Evaluate a Boolean logical statement that involves comparisons among values of properties, to return true or false, by
creating a When rule.
Configuring a data model for a case

Configure a data model to define the data that you want to use in a case. For example, to include a user email address in a
case, add an email address field to the data model.
Before you begin:
Create a case type. For more information, see Creating a top-level case type.
If you want to create a data model for a questionnaire, create the questionnaire first. For more information, see Creating
a questionnaire.
2. On the Data model tab, click Add field.
Note: You can also add new scalar fields to the data model from a view in the User Interface tab.
3. In the field configuration dialog box, in the Field name field, enter a descriptive name. For example: Enter Email address.
4. In the Type list, select a field type.
5. If more configuration options are available for the field type that you select, perform the following actions for a field:
Choices Actions
a. In the Type list, select Text (paragraph).

b. Click the Configure paragraph icon.
c. In the Display as list, define whether to display the paragraph as plain or rich text. Result: The
following figure shows a rich text paragraph at run time that users can use to describe symptoms while
booking a doctor's appointment in an application:
Rich text paragraph
Add a text
paragraph
to the form
a. In the Type list, select picklist.

b. In the Display as list, define a display mode for the picklist.
c. In the Picklist options list, define choices for the picklist.
You can create your own choices or source them from a data page.
d. If you add your own choices, click Add choice, and then provide an option for users to select.
e. If you use a data page to provide choices, select the data page that you want to use. Result: The
following figure shows a picklist with radio buttons at run time that users can use to select an office
location:
Picklist
Add a
picklist to
the form
Choices Actions
a. In the Type list, select Attachment.

b. In the Attachment category list, select the category. Result: The following figure shows an
attachment field at run time that users can use to add documents to a case:
Attachment field
Add an
attachment
field to the
form
a. In the Type list, select User reference.

b. In the Display as list, define whether users can search for a user ID by using a search box or a drop-
down list. Result: The following figure shows a user reference field at run time configured as a search
box that users can use to select a doctor while booking an appointment in an application:
User reference field

Add a user
reference
to the form
Add a field
to capture
For more information about adding a field to capture data, see Creating fields for capturing data.
data
6. Click Save.
What to do next: Configure a view for your case type that includes the fields from the case type data model. For more
information, see Views for cases.

Improve the presentation of your user interface by configuring out-of-the-box fields. By adjusting options such as visibility,
helper text, or on-click behavior, you can adapt the controls to the needs of your business, and build a cleaner, more intuitive
user experience.
The basic settings are shared by most fields and appear in different contexts throughout Pega Platform.
Common field settings

Configuring field behavior
Ensure that users complete the fields that are relevant to their case by defining the conditions that govern the fields' behavior.
Depending on your business needs, you can mark fields as required, disable them under certain circumstances, or hide them
completely.
For example, in a loan application, you can mark the fields that contain the name and address of the applicant as required. In
this way, you ensure that the user who completes the form does not skip information that is crucial to process the case
successfully.
2. On the User interface tab, click the column-based view that you want to edit.
3. In the Edit view section, click the Configure icon next to the field whose behavior you want to change.
4. In the Edit field dialog box, in the Conditions section, define the target behavior of the field:
a. In the Required list, specify whether the field must be completed by the user.
b. In the Disable list, specify when the field is visible but not available to users.
c. In the Visibility list, define when the form should display the field.
Tip: You can use conditional logic or when rules to define the behavior of a field. For more information, see Using
conditional logic in Cosmos React and Creating a When rule.
5. In the Edit field dialog box, click Save.
Managing editing options for a field

Control the data in your application by defining the conditions in which users can input new information. You can configure a
control to be fully editable, fully non-editable (read-only), or to switch to read-only mode under specific circumstances.
For example, when you create a new user account in an application, the text fields that contain the personal data of the
customer are editable. During the next step, when the user has to confirm the data, you can configure the form to be read-
only, and disable editing.
3. In the Edit view section, click the Configure icon next to the field whose behavior you want to change.
4. In the Edit field dialog box, in the Edit mode list, define the target behavior of the field:
To copy edit settings from the parent view, select Auto.
To disable editing, select Read-only.
To disable editing under specific conditions, select Read-only (custom condition), and then click the Properties
icon to define the logic in the condition builder.
To disable editing based on a when rule, select When rule, and then in the Read-only when list, select the when
rule that you want to use.
For more information on conditional logic, see Using conditional logic in Cosmos React and Creating a When rule.
Adding text to a field

Ensure that users fill in the forms in an application correctly by supplying brief instructions. By using labels, helper text, and
placeholders, you define what kind of input goes into each control, which reduces the time that is required to fill in a form.
For example, a helper text might clarify differences in available options depending on the context:
Sample helper text
You can define helper text for editable input fields, such as text areas or checkboxes. Helper text does not appear above fields
that are in a read-only view or are not used for inputting data, such as paragraphs.
Text prompts are also important for accessibility, because they ensure that users who rely on assistive technologies receive
reader-friendly guidance. Note the following accessibility best practices:
Use only one method to label a field. For example, do not duplicate the content of the label in helper text.
Use simple, clear language that is descriptive and does not include technical jargon.
3. In the Edit view section, click the Configure icon next to the field that you want to edit.
4. In the Edit field dialog box, in the Field label field, enter the name that you want the application to display next to the
field.
5. In the Input settings section, define additional text for the field:
To specify the text that appears in the field when the field has no value assigned, in the Placeholder field, enter the
text that you want to use.
To specify the text that appears below the field, in the Helper text field, enter the text that you want to use.
Configuring a Currency field

Collect and display monetary information in a field that automatically formats the amount by adding language-specific
separators and a currency-specific symbol, such as the dollar sign.
3. In the Edit view section, click the Configure icon next to the Currency field that you want to edit.
4. Configure standard field settings, such as visibility and labels.
For more information, see Configuring common field settings.
5. In the Edit field dialog box, in the ISO code selection list, define how you want to source the currency name:
To enter the currency name manually, select Constant, and then, in the Currency ISO code field, enter the three-
letter code of the currency.
To source the currency name from a property, select Property reference, and then, in the Currency ISO code,
select the property that holds the currency name.
6. Optional: To display decimals, select Allow decimals.
Configuring a Date Time field

Standardize date and time formats and reduce the number of input mistakes by using a Date Time field. When you set up a
Date Time field, you ensure that users enter scheduling information in the right format.
For example, for scheduling appointments, you can set up a one hour default step, so that a user cannot schedule a meeting
that starts at quarter past an hour.
3. In the Edit view section, click the Configure icon next to the Date Time field that you want to edit.
5. In the Edit field dialog box, in the Clock list, define the format in which you want to display the time:
To use the default format of the language of the application, select use locale.
To use a 12-hour clock, select 12 hours.
To use a 24-hour clock, select 24 hours.
6. Optional: To include seconds on the field clock, select Display seconds.
7. Define the range of dates that are available in your field:
a. In the Next field, enter how many years into the future the field displays.
b. In the Previous field, enter how many years into the past the field displays.
8. Optional: To include week numbers on the field calendar, select Display week numbers on calendar.
9. In the Time picker list, define the length of the step between time values in the field.
10. Optional: To display the field value as text, in the Read-only settings section, select the Show as formatted text
check box.
11. In the Format list, select how you want to display the value of your field:
To use the default format (Feb 3, 2021, 10:27 AM), select Default.
To use the abbreviated format (Feb 3, 2021), select Date.
To display time lapsed since the date associated with the field (2 years ago ), select Since.
To display only the hour associated with the field ( 10:27 AM), select Time only.
Configuring Decimal, Integer, and Percentage fields

Collect numerical information by using a standard field that checks if the user-provided format of data is correct. Create clean,
intuitive forms for your users with less effort by selecting the field type that best matches your business needs.
Configuring Decimal fields

Configure fields that record positive and negative numbers with a fractional component. For example, you can use this field to
capture the weight of the patient.
5. In the Decimal places fields, enter the number of decimal places that you want to display in the field.
6. Optional: To use a numerical separator in your field, select the Show thousands separator checkbox.
7. In the Read-only settings section, define how to display the field in non-editable contexts:
a. In the Format list, define how to present the number in read-only forms.
b. For the Currency format, complete the additional configuration. For more information, see Configuring a Currency
field.
8. Click Save.
Configuring Integer fields

Configure fields for storing positive and negative integers. For example, you can use integer fields to capture the age of a
borrower.
4. Configure the standard field settings, such as visibility and labels.
5. Optional: To use numeric separators in your field, select the Show thousands separator checkbox.
6. In the Input settings section, in the Display as list, select how the users interact with the field in editable views:
Choices Actions
Enter value Select Input.
Use buttons to
Select Stepper.
change value
a. Select Slider.
b. In the Min value field, enter the minimum value for the field.
c. In the Max value field, enter the maximum value for the field.
Select from a sliding d. In the Default value field, enter the default value for the field.
range e. In the Increment field, define the step for the slide.
f. Optional: To hide the field that displays the number that the user selects on the slide, clear
the Show numeric input checkbox.
g. Optional: To hide the ticks that indicate the slider step, clear the Show ticks checkbox.
For more information, see Number input and Range slider articles at the Pega Design website.
7. In the Read-only settings section, define how to display the field in non-editable contexts:
a. In the Format list, define how to present the number on read-only forms.
b. For the Currency format, complete the additional configuration. For more information, see Configuring a Currency
field.
8. Click Save.
Configuring Percentage fields

Configure fields that store positive and negative decimal numeric values that the application displays as a percentage. For
example, you can use this field to display the interest rate on a mortgage.
4. Configure the standard field settings, such as visibility and labels.
5. In the Decimal places fields, enter the number of decimal places to the right of the decimal that you want to display in
the field.
6. Optional: To use numeric separators in your field, select the Show thousands separator checkbox.
7. Click Save.
Configuring Picklist fields

Reduce the number of user input errors by providing the users of your application with a list of values from which to choose. A
Picklist field captures a single choice from a list of valid options presented as radio buttons or drop-down lists.
5. In the Display as list, define how users see your field:
Choices Actions
a. Select Dropdown (default).

Simple drop-down list b. In the Placeholder field, enter the text that is displayed when the field is
empty.
a. Select Radio buttons.

Radio buttons b. Optional: To arrange the options horizontally, select the Inline alignment
checkbox.
a. Select Search box.

Drop-down list with a search
b. In the Placeholder field, enter the text that is displayed when the field is
option
empty.
6. Click Save.
Configuring fields associated with case and data objects

A data object is a template for describing an entity through fields, such as name and address. Depending on your business
needs, data objects can reference a list or a single record, and source their information from internal or external databases.
This flexibility of approach ensures optimal reuse and better data management.
Case and data objects produce the following fields:
Case reference
Single or multiple records from a selected case type. Case references can refer to other cases or data objects. For
example, in a mortgage request case, you can use a case reference to call an Appraisal case. Alternatively, you can use a
case reference to refer to the borrower, a data object. At run time, case references are displayed as a contextual link.
Data reference
Single or multiple records from a selected data page. In a mortgage request case, you can use a data reference provide
the user with a list of available mortgage types. At run time, data references are displayed as a contextual link.
Embedded data
User-supplied data such as a name and address that is stored and sourced from inside a case instance or a work object.
For example, in a mortgage request case, you can use embedded data to store the borrower's monthly income or
employment history. Supports single and multiple records.
Query
A data page or view that is not sourced from inside the case type. The data page defines parameters that the Query data
relationship is configured to use. Unlike a data reference, the query field does not require a key. A loan application might
use a query field to source information on the current prime mortgage rate.
For more information on data objects, see the Pega Academy article Data relationships.
Configuring a single-record reference field

Simplify the structure of your application by reusing data in different contexts. Case and data reference fields help you
efficiently reuse resources without detailed knowledge about how the system stores data.
For example, in a mortgage application, a Get appraisal case reference can fetch data about the house appraisal if the user
enters the ID of the related case.
Before you begin: Add a single-record data or case reference field to a view. For more information, see Creating fields for
capturing data and Configuring details views.
3. In the Edit view section, click the Drill in icon next to the case or data reference field that you want to edit.
4. In the Edit field pane, in the Mode list, select how you want to display the field:
To restrict the user's choice to a single item, select Single-select.
To prevent users from editing the field, select Read-only.
Important: Read-only fields support fewer configuration options.
5. For Single-select fields, in the Display as list, select the control that you want to use with the field:
Choices Actions
a. Select Autocomplete.
b. In the Display field list, select the name of the field that you want to
display in the control. For example: Select Case ID to source appraisal
data by case number.
AutocompleteTip: Useful for a large
c. Optional: To display additional fields from the case, in the Show
number of options.
details (optional) section, click Add, and then apply additional views to
the field.
Tip: See the live preview on the right side of the screen to observe how
the additional details impact the field.
a. Click Dropdown.
b. In the Display field list, select the name of the field that you want to
display in the control. For example: Select Case ID to source appraisal
data by case number.
DropdownTip: Useful for a limited
c. Optional: To display additional fields from the case, in the Show
number of options.
details (optional) section, click Add, and then apply additional views to
the field.
See the live preview on the right side of the screen to observe how the
additional details impact the field.
a. Click Table.
b. In the Columns section, click Add, and then, from the list of fields, select
the columns for your table.
c. Configure the new fields by clicking the Configure icon and defining field
settings.
TableTip: Useful for listing options
For more information, see Configuring field behavior.
with additional contextual information
d. In the Column to take up remaining width list, select the column
in columns.
which you want to expand to fill the remaining space on the screen.
e. Optional: To apply filtering, in the Filter by list, select Custom, click
the Gear icon, and then build a logical expression.
f. Optional: To apply sorting, in the Sort by section, click Add, and then
select the column and determine its sorting mode.
6. Optional: To allow users to edit the field in read-only views, perform the following actions:
a. Select the Show as picker and persist changes in review mode checkbox.
b. Ensure that the Edit details step is a case-wide action. For more information, see Adding optional actions to cases.
c. Add the key of the reference field to the Edit view of your application. For more information, see Configuring forms.
Note: This setting is available for Autocomplete and Dropdown displays.
7. In the Conditions section, define additional properties for your field, for example, visibility.
For example:
In this scenario, the single-select field is displayed as a table and users can select only one product from the list.
Sample single-select table
Configuring a list of records reference field

Help users access complex data in a convenient way. Case and data reference lists help you source data from your application
and display that information in a table where every row represents a field in a record, or a combo-box.
For example, in a credit card fraud investigation app, a Transactions data reference can produce a list of all the transactions
that are recorded for a given credit card. The customer can study the details of each transaction, such as their time and
location, in the table columns, and mark the transactions that are fraudulent for further investigation.
Before you begin: Add a data or case reference field that uses a list of records to a view. For more information, see Creating
fields for capturing data and Configuring details views.
3. In the Edit view section, click the Drill in icon next to the case or data reference field that you want to edit.
4. In the Edit field pane, in the Mode list, select how you want to display the field:
To provide users with choice of multiple items from the list, select Multi-select.
5. For Multi-select fields, in the Display as list, select the control type that you want to use with the field:
Choices Actions
a. Click Table.
b. In the Display field list, select the name of the field that you
want to display in the control. For example: Select Vendor to
source data by the vendor name.
c. In the Columns section, click Add, and then select the
columns for your table from the list of fields.
d. Configure the new fields by clicking the Configure icon and
defining field settings.
TableTip: Useful for listing options with
additional contextual information in columns.
e. In the Column to take up remaining width, select the
column which you want to expand to fill the remaining space
on the screen.
f. Optional: To apply filtering, in the Filter by list, select
Custom, click the Gear icon, and then build a logical
expression.
g. Optional: To apply sorting, in the Sort by section, click Add,
and then select the column and determine its sorting mode.
Combo-boxTip: A combination of a list and an a. Select Combo-box.

autocomplete field. Useful for a large number of b. In the Display field list, select the name of the field that you
straightforward options. want to display in the control.
6. Optional: To allow users to edit the field in read-only views in the Combo-box mode, perform the following actions:
a. Select the Show as picker and persist changes in review mode checkbox.
b. Ensure that the Edit details step is a case-wide action. For more information, see Adding optional actions to cases.
c. Add the key of the reference field to the Edit view of your application. For more information, see Configuring forms.
Note: This setting is available for Combo-box.
7. In the Conditions section, define additional settings for your field, for example, visibility.
For example:
In this scenario, the multi-select field is displayed as a table and users can select multiple products from the list.
Sample multi-select table

Configuring an embedded data field
Create a UI that helps you gather and store case-related data in reusable lists. Embedded data fields are best suited for a list
of records that the user enters manually. For example, in a loan application, you can use a list-based embedded data field to
collect the user's employment history.
Before you begin: Add an embedded data field to a view. For more information, see Embedding data in a case and
Configuring details views.
3. In the Edit view section, click the Drill in icon next to the embedded data field whose view you want to edit, and then
check the type of your field:
If the embedded data field is a single-record field, follow standard form configuration. For more information, see
Configuring forms.
If the embedded data field is a list of records, continue to step 4.
4. In the Mode list, select how you want to display the field:
To make the field restrict the user's choice to a single item, select Editable.
5. In the Display as list, select the look of your view:
Choices Actions
a. Select Table.
b. In the Columns section, click Add, and then select the columns for your table from the list of fields.
c. Configure the new fields by clicking the Configure icon and defining field settings.
Table
d. In the Column to take up remaining width list, select the column that you want to expand to fill the
remaining space on the screen.
a. Select Field group.

b. In the Select view item list, select the data object view that you want to display on the tab.
Note: The embedded data field group only supports editable views and forms. Consequently, details
Field
views are not supported.
group
c. In the Item label field, define the text that appears as the header for each field group. For example:
When you set the Item label field to Job, the system displays Job 1, Job 2 etc, over each iteration of the
field group.
6. In the Conditions section, define additional properties for your field. For example: Set Allow adding, deleting, and
reordering records to Never to prevent users from changing records displayed by the embedded data field.
For example:
In this scenario, the list-based embedded data field is displayed as a table and a field group. Users fill in the employment
information or add new rows to the table, and the system converts that information into records in the embedded data object.
List-based embedded data field in table form

List-based embedded data field in field group form
Configuring query fields

Obtain data from other applications or systems by configuring query fields. A query field references a data page that retrieves
data from a specified data source and caches that data in memory. This approach allows citizen developers to benefit from
external data without detailed knowledge of database architecture.
For example, you can use a query field to display information about current interbank rates in a loan application.
Before you begin: Add a query field to a view. For more information, see Creating fields for capturing data and Configuring
details views.
3. In the Edit view section, click the Drill in icon next to the embedded data field whose view you want to edit, and then
check the type of your field:
If the query field is a single-record field, follow standard form configuration. For more information, see Configuring
forms.
If the query field is a list of records, continue to step Configuring fields associated with case and data objects.
4. In the Edit view section, click the Drill in icon next to the field that you want to edit.
5. In the Edit field pane, in the Display as list, choose the control type that you want to use with the field:
Choices Actions
a. Select Table.
b. In the Columns section, click Add, and then select the columns for your table from the list of fields.
c. Configure the new fields by clicking the Configure icon and defining field settings.
Table
d. In the Column to take up remaining width list, select the column that you want to expand to fill the
remaining space on the screen.
a. Select Field group.

b. In the Select view item list, select the data object view that you want to display on the tab.
Field
c. In the Item label field, define the text that appears as the header for each field group. For example:
group
When you set the Item label field to Currency, the system displays Currency 1 , Currency 2 , and so on, above
each iteration of the field group.
6. In the Conditions section, define additional settings for your field, for example, visibility.
For example:
Sample list of records query field
Sample single-record query field
Configuring cascading drop-down lists

Reduce the time that is needed to complete a form by creating a group of drop-down lists that take cues from each other, and
adjust the available options depending on choices that the user makes in the interface.
For example, in a mortgage application you can configure two cascading drop-down lists: for the mortgage type, and for the
product type. First, the user selects "New mortgage" as the type of mortgage. In response to the first selection, the product
type drop-down list displays only new mortgage products, and hides other types of mortgage loans.
Before you begin: Prepare your data environment:
Create the data objects MortgageType and LoanProducts, which hold mortgage types and loan products. For more
information, see Creating a data object.
Ensure that the D_LoanProductsList data page takes a Mortgage type parameter. For more information, see Data pages
and parameters.
Ensure that the Mortgage type parameter in the D_LoanProductsList data page is not required.
2. On the Data model tab, click Add field.
3. In the Configure field dialog box, in the Field name field, enter the name of the first drop-down list. For example:
Enter: Mortgage type .
4. In the Type list, select Picklist.
5. In the Display as list, select Drop-down list.
6. In the Picklist options list, select Data page, and then, in the empty field to the left, select the list from which you
want to source the data. For example: Click Mortgage type List Mortgage type .
7. In the Identifier field list, select the field by which you want to sort the items in the drop-down list. For example:
Select Category ID.
8. In the Display field list, select the field whose content you want to display in the drop-down list. For example: Select
Full category name.
9. Click Submit & add another .
10. In the new dialog box, configure the second drop-down list by performing 3 through 6. For example: Perform the
following actions:
1. In the Field name field, enter Loan product.
2. In the Type list, select Picklist.
3. In the Display as list, select Drop-down list.
4. In the Picklist options list, select Data page, and then in the empty field, click Loan product List Loan
products .
11. In the Data page parameters node, in the Type field, select Another field, and then in the empty field below, select
the name of the list that you defined in step 3. For example: Select Mortgage type.
12. In the Identifier field list, select the field by which you want to sort the items in the drop-down list. For example:
Select Product ID.
13. In the Display field list, select the field whose content you want to display in the drop-down list. For example: Select
Product name.
14. Click Submit.
What to do next: Add the fields to your UI. For more information, see Configuring forms.

Design systems help you introduce consistency to the applications that you build. By choosing to use a design system, you can
scale your designs to maintain a unified presence across a number of platforms with less effort.
A design system is a library of patterns and rules that determine how an interface responds to user interaction. Design
systems contain the best practice guidelines, operational assets, and UI components that are required to deliver the interface.
For example, a design system might include a reusable table component that supports sorting, filtering, and grouping. You
can source every table in your application from that component, which means that every table in the application can have the
same basic architecture and rely on consistent rules to model user interactions.
Some organizations develop proprietary design systems to unify the presentation, behavior, and structural rules of their
application interfaces. However, most businesses rely on the design system that is provided by Pega. Either approach helps
improve consistency, and creates a system that is easier to update and maintain.
Cosmos design system

Pega Platform uses the Pega Cosmos design system as its main product design resource. The system provides a consistent
library of components that form the entire user experience for both customer-facing applications andPega Platform itself.
Cosmos relies fully on templates and prefabricated components for more efficient development and performance. In addition,
a more modern design and increased focus on intuitiveness help save time on application updates and user training.
Depending on the architecture that you use, the Cosmos design system has two versions: Cosmos React, which serves the
view-based architecture, and Theme Cosmos, which relies on sections.
When creating a new application, you can choose between a view-based Cosmos React UI, or a section-based Theme Cosmos
UI, which can be further expanded to include hybrid React components.
Cosmos supports a number of JavaScript libraries, including React UI, which is the framework on which Pega Platform bases its
UI components. For more information, see Accelerate your workflow with Cosmos UI.
Changing themes in App Studio

Discover more about styling your application in the following articles:
Defining themes
Ensure that your applications meet the branding requirements of your business by configuring the graphic design of your
portal. By setting a distinct color palette for UI elements such as buttons, links, or headers, you can create a consistent
visual identity.
Adding custom fonts to a Cosmos React theme
Ensure that the UI meets the branding requirements of your business by adding custom fonts to your application. In
Cosmos React, you can add a font by referencing an external URL source or by uploading a binary file with the font to
Pega Platform.
Design tokens
UI components in Cosmos React use design tokens, which are a tool that helps you store the visual attributes of your
application as discrete options. By using a design token, you can unify style elements across different channels, tools,
and applications.
Defining themes
Ensure that your applications meet the branding requirements of your business by configuring the graphic design of your
portal. By setting a distinct color palette for UI elements such as buttons, links, or headers, you can create a consistent visual
identity.
Note: Cosmos React applications come with two ready-to-use themes: Cosmos and Dark. These themes are the system
default and you cannot edit them.
1. In the navigation pane of App Studio, click Settings Branding and themes .
2. Click Add, and then, in the Create new theme dialog box, provide a name for the theme.
3. In the Themes list, click the theme that you want to edit.
Tip: Any change that you make to the theme is reflected in the interactive preview.
4. In the list of UI components, change the colors of the components in your application:
a. Click the square representing the component color that you want to change.
b. Use the color picker to select a color.
Tip: The color picker displays a warning icon if the color combinations in the palette do not meet WCAG Level AA
contrast ratios.
Low contrast warning
5. In the Base font field, define the default size of text in the application.
6. In the Font family field, define the default font for the application.
7. In the Card border radius field, define the shape of the sections that constitute the user interface.
8. In the Button border radius field, define the shape of the buttons in the application.
9. In the Input border radius field, define the shape of the fields in your application.
10. Click Save.
What to do next: Attach the theme to a portal. For more information, see Selecting a theme for a Cosmos React portal.
Selecting a theme for a Cosmos React portal

Assign a distinct theme to your portal to ensure that its color palette, font use, and UI component styling matches the
branding requirements of your business.
Cosmos React applications come with two ready-to-use themes: Cosmos and Dark. The Cosmos theme is the default for all
new applications. For more information on creating new themes in Cosmos React, see Defining themes.

b. In the Current channel interfaces section, click the icon that represents the portal whose theme you want to
change.
2. On the Configuration tab, in the Theme list, choose the color scheme that you want to use for the portal.
Tip: The following preview shows the selected color scheme, and a quick link to the theme editor.
Link to theme editor in the preview

3. Click Save.
Adding custom fonts to a Cosmos React theme

Ensure that the UI meets the branding requirements of your business by adding custom fonts to your application. In Cosmos
React, you can add a font by referencing an external URL source or by uploading a binary file with the font to Pega Platform.
Before you begin: If you want to use a binary file as a source, upload the .woff2 file to Pega Platform. For more information,
see Uploading custom font files.

2. Expand the Technical category, and then click Text File.
3. From the list of files, open pyC11nCustomFonts.css.
4. In the text field, enter the reference to the new font by referencing the examples in the comment section of the file. For
example: In this scenario, you reference a RobotoBlack font in an uploaded file named RobotoBlack.woff2.
@font-face {
font-family: 'RobotoBlack';
src: url('webwb/RobotoBlack.woff2') format('woff2');
font-weight: normal;
font-style: normal;
}
5. On the file form, click Save.

6. In the header of your workspace, click the Switch Studio menu, and then click App Studio.
7. In the navigation pane of App Studio, click Settings Branding and themes .
8. Create the theme in which you want to use the new font.
For more information, see Defining themes.
9. In the Font family field, select Other.
10. In the Font family name field, enter the name of the font that you defined in the font-family line of the pyC11nCustomFonts.css
file. For example: Enter RobotoBlack.
Result: The new font is now available for use in the theme.
Uploading custom font files

Ensure that your user interface meets the branding requirements of your company by adding new fonts to Pega Platform. Your
custom font files can comprise standard fonts or icon fonts, which you can then add to the default icon set for your application.
In Pega Platform, you store font files as binary files.
1. In the header of Dev Studio, click Create Technical Binary File .

2. On the Create Binary File tab, in the Label field, enter a name for your font.
3. In the App Name (Directory) field, enter the name of the folder that contains your font file. For example: Enter webwb.
4. In the File Type (extension) field, enter woff2.
5. Click Create and Open.
6. On the Edit Binary File form, click Upload file.
7. In the Upload file window, click Choose file, select the font file, and then click Upload file.
8. Click Save.
9. Optional: To use other font weights that belong to the same text font family, repeat steps 1 through 8, and then upload
font files for each of the weights. For example: You can upload fonts as MyFontNameBold.woff2 and MyFontNameLight.woff2.
A TTF file contains one font weight only.
What to do next: Add the new font CSS to the skin of your application. For more information, see Creating a CSS font file.
Design tokens
UI components in Cosmos React use design tokens, which are a tool that helps you store the visual attributes of your
application as discrete options. By using a design token, you can unify style elements across different channels, tools, and
applications.
When you style a Cosmos React application on the App Studio Branding and Themes landing page, Pega Platform
automatically updates the theme rule for you. However, you can gain a more granular level of control over your theme by
manually editing the theme JSON file in Dev Studio.
You can search for the theme JSON file by entering the name of the theme in the Dev Studio search box, or by exploring the
Rule-UI-Theme class.
For a list of design tokens and sample values, see Pega Cosmos.
For example: In this scenario, a sample Customer service theme is expanded to include palette tokens, such as brand-primary,
foreground-color, and app-background.
Sample theme JSON file with added tokens

Configuring an accessible UI
Reach the broadest audience for your application by building a user interface that addresses the needs of users with
disabilities. Designing a UI for assistive technologies, such as screen readers, is important for compliance and provides
essential access to users who have visual impairments.
Web Accessibility Initiative – Accessible Rich Internet Applications (WAI-ARIA) is a set of principles published by the World Wide
Web Consortium (W3C) that governs accessibility in applications. A large array of Pega Platform features supports these
principles out-of-the-box, for example, by providing cues about screen content to screen readers. However, following best
practices and avoiding common mistakes is crucial when creating an application that combines many UI features.
Pega Platform also includes the Accessibility Inspector that helps you check the level of accessibility in your application to
ensure the highest possible compliance. If your business needs are more complex, you can further customize various aspects
of your UI, such as WAI-ARIA roles, upon which assistive technologies rely.
For example:
The Accessibility Inspector includes a color confusion simulator that helps you check if the colors that you use in your
application are readable to users with color blindness.
Sample UI component with no filter (left) and simulated red-green confusion filter (right)
For related training materials, see the Enabling accessibility features in applications module on Pega Academy.
What to do next: Discover more about accessibility in your UI in the following articles:
Accessibility standards in Pega Platform
Pega supports users with disabilities by continuously integrating the W3C Web Accessibility Initiative (WAI) standards into
the architecture of applications that you develop. As a consequence, applications include accessibility features by
default, which makes them more convenient for users who rely on assistive technology.
Out-of-the-box accessibility features
Because accessibility is a design principle rather than a set of options that the user can enable or disable, many of its
features are included by default in the architecture of Pega Platform applications.
Best practices for accessibility
Accessible design helps users with disabilities access the full range of application features. By following best practices for
accessibility, you ensure that your application meets the industry standards for all types of users.
Inspecting accessibility
Identify and fix accessibility issues to ensure that users with disabilities can quickly access and efficiently operate your
application. By using the Accessibility Inspector tool, you can check what your application looks like to users of varying
visual ability and review UI components that are not accessible.

Pega supports users with disabilities by continuously integrating the W3C Web Accessibility Initiative (WAI) standards into the
architecture of applications that you develop. As a consequence, applications include accessibility features by default, which
makes them more convenient for users who rely on assistive technology.
WCAG standards
Pega strives to create an inclusive product experience by following the W3C Web Content Accessibility Guidelines (WCAG) 2.1
AA. Pega Platform components use the recommended standards to reach compliance with Section 508 of the US Rehabilitation
Act, the European standard EN 301 549, the European Accessibility Act, and the Barrierefreie-Informationstechnik-Verordnung
(BITV).
Consequently, all applications that users develop include accessible markup by default. As a developer, you only need to put
content into the existing out-of-the-box framework.
For example: To make your application accessible, you might need to add helper text to controls and ensure that all layouts
use proper headings that reflect the structure of the document. If you use custom components that have unusual functions,
such as clickable layouts, you can assign ARIA roles that match the document role manually.
The following image illustrates out-of-the-box accessibility settings in a sample search field.
Sample search field configuration
Voluntary Product Accessibility Template

The Voluntary Product Accessibility Template (VPAT) report represents Pega Platform compliance with the WCAG 2.1 AA
guidelines published by the W3C. For more information, go to the VPAT for Pega version 8.7 website.
Web Accessibility Initiative resources

For more information about WAI-ARIA roles, accessibility standards, and best practices for designing for people with
disabilities, go to the Web Accessibility Initiative website.
Out-of-the-box accessibility features

Because accessibility is a design principle rather than a set of options that the user can enable or disable, many of its features
are included by default in the architecture of Pega Platform applications.
With no single setting to control accessibility, building an inclusive interface requires little additional effort apart from the
consistent use of existing accessibility frameworks.
Accessibility features
Keyboard and screen reader navigation
Keyboard accessibility, or the ability to reach and operate any UI element by keyboard alone, is necessary for users with
motor and visual disabilities. UI components are developed in accordance with WAI-ARIA Authoring Practices 1.1.
Consequently, most Pega UI components support accessible navigation without additional markup or configuration.
For more information, see Supported keyboard navigation.
WAI-ARIA roles
The Pega Platform accessibility architecture relies primarily on HTML 5 semantics, but uses WAI-ARIA markup where
HTML is not sufficient, for example, to convey rich application functionalities. WAI-ARIA roles provide additional
information about your application to assistive technologies, such as screen readers. Consequently, the user can be
constantly aware of the roles, states, and properties of interface components.
For more information, see WAI-ARIA roles in a screen layout.
Labels
Labels, placeholders, and alternative text help users understand the UI and visualize the tasks that they must complete.
Controls and layouts include fields for text aids by default.
For more information, see Adding text to controls.
Table navigation
Optimized table layouts support WAI-ARIA keyboard navigation standards.
For more information, see the Tables row in Supported keyboard navigation.
Skip links
Skip links provide users with tools to navigate to the most important parts of the application, and represent one of the
most basic accessibility requirements. For example, a skip link can direct the user straight to the navigation menu, so
that the user does not have to tab through the page to reach it.
Pega Platform automatically adds a default pySkipLinksToTarget section to your application. The section provides skip
links to the main content, the search bar, and the navigation pane, so that you do not need to configure it.
Error alert management

Application forms support client-side and server-side validation by default. If the application detects an error, the
application communicates the problem to the user in text, in a manner that is clear, specific, and accessible to screen
readers.
For more information, see the Error messages row in Supported keyboard navigation.
PDF/UA files
By default, PDF files that a Pega application generates use the accessible PDF/UA ISO standard. While you can change
this setting to improve archiving, this is not a recommended practice.
For more information, see Setting PDF file versions.
Supported keyboard navigation

Accessible UI components provide run-time behavior that helps users who rely on assistive technology (AT) to navigate your
application with less effort.
UI components are developed in accordance with WAI-ARIA Authoring Practices 1.1. Consequently, most Pega UI components
support accessible navigation without additional markup or configuration.
Accessible UI components
The following table lists the most important accessibility components along with the corresponding keyboard navigation:
Control/feature Keyboard navigation Additional information
Tab to change focus Pressing Tab from the header moves

Up arrow and Down arrow to the focus to the first editable field in the
Accordion layout navigate between accordion headers container.
Home to skip to the first tab In numbered accordions, the numbers
End to skip to the last tab do not receive focus.
Tab to change focus Pressing Tab from the header moves the
AJAX containers Left arrow and Right arrow to focus to the first editable field in the
navigate between tabs container.
Buttons include unique IDs to help AT

Buttons Enter or Spacebar to activate
manage page focus.
Tab to skip to a control in the header (if

expanded) or outside the header (if
collapsed)
Screen readers announce whether the layout
Collapsible layout Up arrow and Down arrow to
is expanded or collapsed.
navigate between tabs
Home to skip to the first tab
End to skip to the last tab
Enter or Spacebar to engage with the

Controls control
Arrow keys to navigate
Dynamic layouts Tab to change focus
For client-side validation errors, the AT

reads the error message in the alert
box and moves focus to the first field
that contains an error.
For server-side validation errors, the AT
Error messages Enter to close the alert box
reads the error banner and moves focus
to the first field that contains an error.
For errors in tabs, the AT announces
errors when the focus falls on the tab
header.
The message is readable when a change

Field-level error messages No
causes the error, such as a failed validation.
Icons Yes Alternative text is configurable.
Up arrow and Down arrow to navigate

Menu layout
between items
Modal windows Esc to close
Overlays Yes
Labels and text alternatives are

Read-write controls Yes
configurable.
Tabs, arrows, and all modifier keys are

Registry of keyboard shortcuts N/A
stored in a single file location.
Tab to enter and exit the repeating When focus rests on the layout, the AT
dynamic layout reads the summary information about
Arrow keys to navigate between the layout and the number of rows in
repeating sections the layout.
Enter key to engage with items in the After loading new content, the focus
Repeating dynamic layout
repeating section rests on the newly added elements.
Esc key to leave an interactive item in You can revert to tab navigation by
a repeating section selecting the Use form navigation
Right arrow and Left arrow keys to (by tab) checkbox in the Accessibility
navigate inside the repeating section node of the layout properties.
Control/feature
Rich text editor KeyboardYes
navigation The textAdditional information
is fully editable by keyboard.
Screen layouts Tab to change focus
Skip to content area Yes
SmartInfo Tab to change focus
Smart tips Yes The parent control receives focus.
The header and container do not receive

Stacked layout Tab to change focus
focus.
If the table cell contains a component

Tab to exit the table
with which the user can interact, the
Arrow keys to navigate between cells
focus rests on that component when
or interactive items in a cell
you press Enter.
Tables Enter to engage with interactive items
The AT reads the header label as a
in a cell
button to inform the user that the label
Esc to deselect an interactive item in a
is a clickable element that enables
cell
sorting.
Tab to change focus

The component is activated
Left arrow and Right arrow to
automatically on focus.
Tabs navigate
The AT reads the tab name when the
Home to skip to the first tab
focus falls on the tab pane.
End to skip to the last tab
The system can inform the AT about loading

Wait indicator N/A status. You can edit the load text in the
pyThrobberLoadingText rule.

Accessible design helps users with disabilities access the full range of application features. By following best practices for
accessibility, you ensure that your application meets the industry standards for all types of users.
General guidelines
Review the Web Content Accessibility Guidelines (WCAG) Checklist, which is the primary source for meeting industry
standards for accessibility.
Run the accessibility inspector to check your application. For more information, see Inspecting accessibility.
Design guidelines
Avoid inline styles, which might override custom settings that help users understand a page better.
Add labels to all fields, controls, cards, and images, but use only one method to label a field. Place labels above the fields
that they describe.
Ensure that the UI alerts users of dynamic changes visually and through Live ARIA.
Provide meaningful error messages.Tip: Write "The password must contain at least 8 characters" rather than "This entry
is invalid."
Avoid timed events, which require complex configuration to comply with accessibility guidelines.
Avoid hover and right-click events.
Do not use link controls as buttons.
Use visibility conditions to control the appearance of the form. Do not use controls in disabled mode.
When you provide helper text, avoid referencing the color, shape, or visual location of a UI component.Tip: Write "Click
the Submit button" rather than "Click the blue button."
Apply placeholder text for input fields but do not substitute labels with placeholders.
Avoid technical language and jargon in labels, placeholders, and helper text.
Navigation guidelines
Check if users can navigate your design with keyboard only.
Avoid key commands. Key commands can conflict with screen readers.
Add paging to tables.
Give links meaningful text.Tip: Write "Main page" instead of "Click here".
For each onclick event, configure a keyboard alternative.
Screen organization guidelines
Use headers and titles on layouts. Define headings through markup rather than formatting. Always configure a level one
heading and use header levels correctly.
Limit the use of modal dialog boxes and overlays.
Do not force landscape or portrait mode in mobile apps.
Organize content on the UI and in the document object model linearly to accommodate screen readers.Tip: If your UI
includes a large conditional section, consider making the transition explicit by putting the conditional content in multiple
assignment steps.
Use responsive layouts. Layouts and forms that have fixed window sizes might cause problems for users who need to
resize their screens.
Do not use more than one main section on a page.
Do not use tables to define areas on your page. Use tables only to present collected data.
Image guidelines
Use caution when you introduce multiple icons. Ensure that the icons are labeled properly and can receive focus from the
keyboard.
Do not wrap text in images.
Add meaningful alternative text and avoid reusing the same descriptive text for different resources.
Avoid adding alternative text to unimportant or decorative elements. Unnecessary text crowds the feedback from
assistive technology such as screen readers.
Color use guidelines

Do not use color as the only indicator of a change of state. For example, if an error causes the field to display a red
border, but does not produce any other indicators, the field is not accessible.
Use a 4.5:1 contrast ratio for text against the background color.
For meaningful icons, such as warning icon, use a 3:1 contrast ratio against the background color.
For form fields, use a 3:1 contrast ratio against the background color and the border.
Inspecting accessibility
Identify and fix accessibility issues to ensure that users with disabilities can quickly access and efficiently operate your
application. By using the Accessibility Inspector tool, you can check what your application looks like to users of varying visual
ability and review UI components that are not accessible.
1. Open the application or portal that you want to inspect.
2. In the developer toolbar, click the Accessibility icon ( ).

3. In the Accessibility Inspector pane, check if your application is compliant with best practices for accessibility:
a. In the Disability preview list, select the visual ability preview.
The list includes various types of color blindness to simulate each condition and help you make design decisions.
For example: Select Protanopia to check if the design and contrast level of your application is suitable for users
with red-green confusion.
Sample UI component with no filter (left) and red-green confusion filter (right)
b. In the list of issue categories, expand each node, and then navigate to the rules that impact accessibility. For
example: Click Content Provide an associated label Driver to open and edit the section that is missing a
label.Tip: Not all warnings require an intervention. For example, adding labels to decorative images might crowd out
useful information in screen readers.
List of UI issues in the Accessibility Inspector

4. Optional: To highlight page elements that are affected by issues, do the following actions:
a. In the Accessibility Inspector pane, click the Display menu options for Accessibility Inspector icon ( ).
b. Click Draw outline around on-page issues .
What to do next: Discover more about accessibility standards and best practices, which reduce the number of issues, in the
following articles:

Internationalization and localization

Internationalization and localization help you reach a wider audience by making your application available to users who speak
different languages. Localization is the process of translating application text and converting locale-specific components, and
internationalization is a general design principle that makes software more convenient to localize.
Pega Platform applications are designed to support multiple language versions and provide a user-friendly localization process
that uses wizards, existing browser settings, and standard Pega rulesets. App Studio and user portals that you generate in the
application all support localization. However, Dev Studio does not support full localization and might display untranslated
content.
Localization landing page

The Settings menu in App Studio includes a Localization landing page, which you can use to manage the language versions
of your application.
The Localization landing page in App Studio

Locale
Your locale determines the language settings of your application. Pega Platform determines the initial locale of the operator by
first looking at the locale selected in the current browser. If the operator's profile specifies a locale other than the locale set for
the browser, Pega Platform uses the profile locale. You can override the locale setting temporarily by calling the PublicAPI
method setLocale(). The new locale setting is then valid until the user session ends or until a later call to the setLocale()
method. If the application does not contain a ruleset for the locale that you select, the UI displays the default language
(English).
Pega Platform uses the Unicode standards for date and time patterns. Implementation of daylight saving time support depends
on the Java Virtual Machine version that supports your system. For a list of locales in Oracle's Java Development Kit, see the
Oracle documentation.
East Asian language support

Pega Platform supports the Microsoft Windows Input Method Editor (IME), which helps users enter characters in four different
East Asian languages (simplified and traditional Chinese, Japanese, and Korean) by using the standard keyboard. For more
information, see Installing and Using Input Method Editors on the Microsoft website.
Character sets
Pega Platform and the PegaRULES database support the UTF-8 or UTF-16 Unicode character sets. Note: After you install a
UTF-8 system, you cannot enable UTF-16.
Localizing your application
Localizing your application helps users work in their preferred language, which improves their experience and ensures a
better understanding of the product. By localizing an application, you can expand your operations to new markets
regardless of language barriers.
Converting your UI for right-to-left languages
Meet the needs of audiences who use languages such as Arabic or Urdu by adapting your user interface to accommodate
the right-to-left (RTL) text direction. By localizing your application into RTL languages, you expand your user base and
provide native RTL language speakers with an interface that is friendly and intuitive.
Localizing your application
Localizing your application helps users work in their preferred language, which improves their experience and ensures a better
understanding of the product. By localizing an application, you can expand your operations to new markets regardless of
language barriers.
Localization adapts your application for a specific language or region. During the localization process, the text in your
application is translated into the target language, and imported back into Pega Platform. Text that you can localize includes
labels, captions, tooltips, and instructions that appear in user-facing components, such as views and portals.
Localization limitations
Localization in Cosmos React applications is an expanding feature. Consequently, it includes certain use case limitations. By
understanding the scope of localization support in Pega Platform version 8.7, you can plan your application better.
In Cosmos React applications, you cannot localize the following rules:
Decision tables and decision trees.

Case statuses.
Radio buttons and drop-down controls in a table.
In addition, localization has the following limitations:
If you save a view manually through Dev Studio, and not in the App Studio authoring environment, the system does not
update the localization file.
The translation package does not automatically include the text from radio buttons and drop-down controls that use data
pages. For more information about adding that text manually, see Localizing controls that rely on data pages.
The translation package does not automatically include the text from properties with prompt lists. For more information
about adding that text manually, see Localizing properties with more than one value.
Deleted views are not deleted from the translation package.
You cannot delete localization rules.
Creating a translation package in Cosmos React

Expand the user base of your application by translating it into different languages. By creating a translation package, you
bundle all the text in your application into a single JSON or Microsoft Excel file, which translators can then process more
conveniently.
1. In the navigation pane of App Studio, click Settings Localization .

2. On the Localization landing page, on the Translation packs tab, click New.
The New button on the Localization page
3. In the New translation dialog box, click Add language.

4. In the language list, select the language to which you want to localize the application.
5. Optional: To overwrite a previous translation, select the Re-translate existing translations checkbox.
6. Click Next. Result: The system generates a raw translation package.
7. Click Download, and then select the format of the translation package.
8. Click Done.
Tip: You can download the translation package at any time, in either format, from the Language list on the
Localization landing page.
Importing a translation package in Cosmos React

Create multiple language versions of your application by localizing translation packages and then importing the packages into
your application. You can upload a newly translated package on the Localization landing page, which offers a convenient way
to manage the language versions of your application.
In addition, you can use the Localization page to import Pega language packs, which provide a translated ruleset with values
of fields that typically appear in every application, such as button labels or prompts.
Before you begin: Obtain a file with the translation or a Pega language pack. For more information, go to Pega
Marketplace.Note: Ensure that your language pack is the same version and UI type as your application. For example, Cosmos
React applications built on Pega Platform version 8.7 do not support language packs for version 8.6, or for section-based 8.7
applications.

2. On the Translation packs tab, in the row that represents the language of your translation, in the Status column, click
the More icon.
The More icon on the Translation packs tab
3. Click Import translation.

4. In the Import translation modal dialog box, upload the file with the translation.
5. Click Next.
Tip: If the system shows import errors, check the ruleset for locked rules.
6. When the import completes, click Done. Result: The status of the translation changes to Resolved.
Creating localization rules in Dev Studio

Gain a more granular level of control over the localization process by generating localization rules in Dev Studio. For example,
you can use localization rules to manually add properties to a translation package, even when the system omits them.
Before you begin: Ensure that you are working in a development branch. For more information, see Developing applications
in branches.
1. In the header of Dev Studio, click Configure User Interface Application Readiness Constellation .
2. In the Upgrade section, in the Upgrade branch name list, select the branch where you work.
3. Click Upgrade views. Result: The system launches an upgrade process that generates localization rules for all views in
your application.
Localizing controls that rely on data pages

Ensure that your interface does not include untranslated picklists and radio buttons by adding controls that source entries
from data pages to the translation package. Because data pages are empty when the system generates the translation
package, you must add their content manually.
Before you begin: Generate localization rules for the application. For more information, see Creating localization rules in Dev
Studio.

2. On the Additional text tab, find the data page related to the control that you want to localize, and then click the More
Edit record icon.
The More icon on the Additional text tab

3. In the Edit record modal dialog box, populate the data page with the values that you want to localize by entering each
value in a separate row. For example: Your vehicle loan application includes a Vehicle type picklist that lists the
following vehicle types: car, van, truck, and motorcycle. The vehicle types are sourced from the D_AutoLoanList data
page. You want to include the vehicle types values in the translation package. In the Edit record, you then enter the
same values:
Car
Van
Truck
Motorcycle
4. Click Submit.
What to do next: Rebuild the translation package. For more information, see Creating a translation package in Cosmos
React.
Localizing properties with more than one value

Provide your localization team with access to all properties and ensure that no element of your interface remains untranslated.
When generating a translation package, the system omits local properties that have multiple values, such as properties
associated with picklists. You can add these properties to the translation package manually by editing their localization file in
Dev Studio.
Before you begin:
Generate localization rules for the application. For more information, see Creating localization rules in Dev Studio.
Perform a private edit to set pxEnableC11nDev to true. For more information, see Performing a private edit.
1. In the navigation pane of Dev Studio, click App.

2. Click Branches.
3. In the application node, expand the branch where you work, and then expand the Localization node. Result: The node
displays a list of localization rules for the application.
Localization node in a sample application

4. On the localization rule list, select the rule associated with the property that you want to include in the translation
package.
5. On the rule form, click Check out.
6. On the Default tab, select the Mark as editable checkbox.
7. In the Locale Json field, enter the values that you want to translate in a JSON form. For example: Your mortgage
application might include a drop-down where you select what kind of asset the loan is for. In this scenario, your JSON file
could have the following structure:
{
"AssetType": {
"House": "House",
"Apartment": "Apartment",
"Land": "Land"
}
}
8. On the rule form, click Save, and then click Check in.
9. In the Check in modal dialog box, in the Check-in comments field, enter a comment that describes your changes to the
rule.
10. Click Check in.
Converting your UI for right-to-left languages

Meet the needs of audiences who use languages such as Arabic or Urdu by adapting your user interface to accommodate the
right-to-left (RTL) text direction. By localizing your application into RTL languages, you expand your user base and provide
native RTL language speakers with an interface that is friendly and intuitive.
Pega Platform uses tools built into Java and HTML to automatically handle RTL conversion based on the user's (operator)
locale. When you assign an RTL language as the default for an operator, that operator sees the application in RTL alignment,
with menus on the right, and breadcrumbs arranged right-to-left. If you do not set a default language for the operator, the
system sources it from the browser's region settings.
Note: The system handles font sizes and layout alignment automatically, but does not reverse icons. You can provide RTL
versions of left-to-right (LTR) icons by saving them under the same name followed by _rtl. For example, an LTR name.png icon has
an RTL counterpart name_rtl.png that the application displays in RTL locales.
1. Change the locale settings for the operator:

Choices Actions
a. In the footer of Dev Studio, click the operator icon, and then click Operator.
b. On the operator tab, in theLocalization section, in the Default locale field, enter the target
Yourself
language ISO code. For example: For Arabic (Saudi Arabia), enter ar_SA.
c. Click Save.
a. In the navigation pane of Dev Studio, click Records.

b. Expand the Organization category, and then click Operator ID.
Another c. Open the operator record that you want to edit.
operator d. On the operator tab, in theLocalization section, in the Default locale field, enter the target
language ISO code. For example: For Arabic (Saudi Arabia), enter ar_SA.
e. Click Save.
2. Optional: To keep the Dev Studio interface in English, perform the following actions:
a. In the footer of Dev Studio, click the operator icon, and then click Preferences.
b. In the Preferences window, select the Ignore locale checkbox.
c. Click Save, and then re-log to the application.
For example:
Left-to-right portal
Right-to-left portal
You can choose parts of Pega Platform UI that suit your business needs and make them available to users of your websites by
creating a Web embed channel and inserting the auto-generated markup into any web page.
Web embedding helps you incorporate specific Cosmos React landing pages and case experiences into your existing web
assets regardless of your current adopted front-end framework.
An embedded channel in an external web page

Unlike the Pega web mashup which uses <iframe> components, the web embed in a Cosmos React application relies on
HTML5 Web Component. This standard provides a means of defining custom full-fledged HTML elements, such as the pega-embed
tag in the following example:
<script src='https://static.pega.com/pega-embed.js' ></script>

<pega-embed id='theEmbed' action='createCase' caseTypeID='OPB1HW-Compass-Work-NewFeedback'
appAlias='compass' pegaServerUrl='https://sample.pega.com' staticContentUrl='https://static.pega.com/'
authService='pega' clientId='55781676112059009508' >
</pega-embed>
Note:
Before using a custom element, the JavaScript code that defines the behavior of the element must first be loaded. For the
pega-embed custom element, this is accomplished by the HTML script reference to pega-embed.js.
All custom elements, including the pega-embed element, require a start and end tag. A self-closing tag style is not
supported.
Web Components tags work only when the page is served from a web server that uses the http: or https: protocols. Local
HTML files that use Web Component markup are not supported. The http-server npm module provides a way to serve up local
files using the http: or https: protocol.
Creating web embed

Embed existing Microjourney experiences within any web page or application. For example, you can embed a feedback
form within your website so that the users who access the page can share their comments.
Custom code in the web embed snippet
The web embed snippet that you generate on the Web embed channel page is ready to use out of the box. However, if
your business case requires that the web embed behave in a more complex manner, you can edit the snippet manually
and expand it to use additional supported attributes.
Troubleshooting web embeds
Ensure that your web embeds work as intended by learning about potential issues and their resolutions.
Authentication in web embed
Authentication ensures that only users and systems with a verified identity use the web embed and that all permitted
manipulations of the data occur as the current user identity.
Creating web embed

Embed existing Microjourney experiences within any web page or application. For example, you can embed a feedback form
within your website so that the users who access the page can share their comments.
Before you begin: Ensure that you have at least one case type in your application. For more information, see Creating a top-
level case type.
1. In the navigation pane of App Studio, click Channels.

2. In the Create new channel interface section, click Web Embed.
3. On the New web embed interface form, in the Basic options section, in the Name field, enter a name for the
channel. For example: Enter Feedback item .
4. Optional: To distinguish this channel interface from other embedded channel interfaces, in the Description field,
specify the purpose of this channel interface. For example: Enter Case type for user feedback .
5. In the autopopulated URL field, verify the URL for your Pega Platform instance.
6. In the Static server URL field, verify the URL of the Constellation Static Content service.
7. In the Authentication service field, select the name of the authentication provider for the web embed.
8. In the Configuration section, in the Action list, select an action for the embedded code:
To enable users to create a new case, select Create a case, and then, in the Case type field, select the target case
type.
To load a specific page, select Display a page, and then, in the Page field, select the target page.
To open an assignment, select Open an assignment, and then, in the Assignment ID, enter the target
assignment ID.
To open a case by ID, select Open a case, and then, in the Case ID field, enter the ID of the target case.
For example: Select Create a new case , and then, in the Case type field, enter New feedback.
Sample web embed configuration

9. For case and assignment actions, in the Display option field, select what appears in the web embed.
10. Optional: To delay the loading of the main content on the host web page until an event occurs, turn on the Defer
embed load switch.
11. In the What is web embedding? section, click Generate web embed code.
12. In the Show web embed code snippet window, click Copy. For example: Sample snippet:

</pega-embed>
13. Close the Show web embed code snippet window.

14. Click Save.
15. Paste the HTML snippet from the Show web embed code snippet window into a static web page or webview of an
external web application to display your embedded case.
Result: When you next load your host site, host page displays the application.For example:
The feedback item embedded in a host page

Custom code in the web embed snippet
The web embed snippet that you generate on the Web embed channel page is ready to use out of the box. However, if your
business case requires that the web embed behave in a more complex manner, you can edit the snippet manually and expand
it to use additional supported attributes.
Similarly, you can add JavaScript code to invoke one of the supported methods and add event handlers to listen for and react
to specific supported events. This approach helps you adapt the web embed to your needs.
Customizing autogenerated markup

For example, a sample HTML markup that you generate in App Studio might be as follows:

</pega-embed>
You can customize it by adding an attribute, for example startingFields:

authService='pega' clientId='55781676112059009508'
startingFields='{"Priority":"Normal","Language":"English"}' </pega-embed>
The startingFields attribute passes values to the new case. In this way, you can set up defaults for your case.
Notes on code
The definition of the <pega-embed> web component is in the pega-embed.js file that is located on the Constellation service. The script
tag must come before the <pega-embed> tag.
For JSON structures, such as the ones that the startingFields attribute uses, single quotes are recommended.
You can also manipulate the web component by using standard HTMLElement methods. For example, you can use a
document.createElement("pega-embed") to create an element and pass structures. Alternatively, you can use a mixed approach with
some HTML markup and some JavaScript by specifying deferLoad="true" and then obtaining a reference to the element using the
specified ID to update or define attributes. For example:
<script>
let el = document.getElementById("theEmbed");
let options={"accountID":37394984,"Rewards":"Platinum"};
el.setAttribute("startingFields", JSON.stringify(options));
el.load();
</script>
Note: The fields you set in the startingFields attribute must be exposed in AllowedStartingFields. For more information, see
Adding fields while creating cases in DX API v2.
Discover the attributes, methods, and events supported by the web embed in the following articles:
Attributes in web embed
You can add a number of attributes to your web embed snippet to expand its functionality.
JavaScript methods in web embed
The host page can use JavaScript (JS) to invoke methods that support querying or manipulating the web embed. This
functionality provides you with the tools to meet the needs of your particular use case.
Events in web embed
The host page can add event handlers that execute and perform custom processing when specific supported events fire,
which helps you better integrate Pega UI with the host environment.
Attributes in web embed

You can add a number of attributes to your web embed snippet to expand its functionality.
Note: To simplify the code, attributes with default values are removed from the automatically generated web embed snippet.
General
Note:
The web embed supports general HTML element attributes and methods, such as addEventListener. For more information, see
the W3C HTML reference information.
For JSON objecs, use single quotes around the entire string representing the object contents.
Generated
Name Description Type Default value
automatically
Id Unique ID for embedding element. String none
Embedding is initially loaded as not

deferLoad Boolean false
shown.
If true, the system prompts for re-

popupReauth authentication when the refresh token Boolean false
expires.
Specifies which page to open. The

following values are available:
full
Uses the full case page when
displaying case-related UI.
assignment
Uses an alternate page, which
casePage constrains the UI to the assignment Constant assignment
flow action area.
assignmentWithStages
Uses an alternate page, which
Generated
Name Description
constrains the UI to just the Type Default value
automatically
assignment flow action area and
includes stages.
Theme
Generated
automatically
Stringified JSON object that represents the defaults to the out-

theme theme of the web embed. The theme JSON object of-the-box Cosmos
property is optional. theme
The theme is a JSON Object that contains the value of the rule-ui-theme that you use to render the web embed. For more
information on themes, see Defining themes.
For example: The following snippet contains sample values that you can set inside the theme:
{
"base": {
"palette": {
"brand-primary": "#3c8712",
"foreground-color": "#5e4242",
"app-background": "#b1bde6"
}
}
}
You can pass the theme object as an attribute to the <pega-embed> tag. The object must be serialized and passed as a
string:
<pega-embed id="theEmbed" action="https://docs-previous.pega.com/openPage" pageid="pyWorklist" pageclass="Data-Portal" appalias="enrollment1"

pegaserverurl="https://X.X.X.X/prweb" staticcontenturl="https://Y.Y.Y.Y/c11n/"
authservice="pega" clientid="11111111111111"
theme='{"base":{"palette":{"brand-primary":"#3c8712","foreground-color":"#5e4242","border-line":"#5ac538","app-background":"#b1bde6"}}}'>
</pega-embed>
Alternatively, you can pass the theme JSON object directly to the web component tag – either during creation of the <pega-
embed> tag, or in conjunction with the ‘deferLoad’ attribute and the load function.
The following code illustrates an object passed directly during the creation of the web component tag:
var el = document.createElement("pega-embed");
el.theme= { "base": { "palette": { "brand-primary": "#3c8712", "foreground-color": "#5e4242", "app-background": "#b1bde6" } } };
The following code illustrates an object passed to the web component tag before calling the load method:
var el = document.getElementById("theEmbed")
el.theme= { "base": { "palette": { "brand-primary": "#3c8712", "foreground-color": "#5e4242", "app-background": "#b1bde6" } } };
el.load();
For more information, see JavaScript methods in web embed.
Action
Generated
automatically
Defines the action that the web embed

performs. The following values are
available:
action createCase Constant none

openCase
openAssignment
openPage
ID of the case type. Valid only for the

caseTypeID String none
createCase action.
ID of the case. Valid only for the openCase

caseID String none
action.
assignmentID ID of the case. Valid only for the String none

action.
openAssignment
Generated
ID of the page. Valid only for the openPage automatically
pageID String none
action.
Class of the page. Valid only for the

pageClass String none
openPage action.
Stringified JSON object that represents

additional values to pass to createCase. Valid
only for the createCase action.Note: The
fields you set in the startingFields
startingFields JSON object none
attribute must be exposed in
AllowedStartingFields. For more
information, see Adding fields while
creating cases in DX API v2.
For example: The following snippet represents a startingFields JSON:
‘{"FirstName":"Adam","LastName":"Smith","Vehicle":{"Make":"Honda","Model":"Accord"}}’
You can pass the startingFields object as an attribute to the <pega-embed> tag. The object must be serialized and passed as
a string:
<pega-embed id="theEmbed" action="https://docs-previous.pega.com/openPage" pageid="pyWorklist" pageclass="Data-Portal" appalias="enrollment1"

pegaserverurl="https://X.X.X.X/prweb" staticcontenturl="https://Y.Y.Y.Y/c11n/"
authservice="pega" clientid="11111111111111"
startingFields=‘{"FirstName":"Adam","LastName":"Smith","Vehicle":{"Make":"Honda","Model":"Accord"}}’>
</pega-embed>
Alternatively, you can pass the JSON object directly to the web component tag – either during creation of the <pega-embed> tag, or
in conjunction with the ‘deferLoad’ attribute and the load function.
The following code illustrates an object passed directly during the creation of the web component tag:
var el = document.createElement("pega-embed");
el.startingFields=‘{"FirstName":"Adam","LastName":"Smith","Vehicle":{"Make":"Honda","Model":"Accord"}}’;
Configuration
Generated
automatically
pegaServerUrl URL to the Pega Infinity server. String none
URL to the Constellation Static Content

staticContentUrl service, from where the system loads the String none
UI engine code.
The alias of the embedded

application.Note: If the appAlias
argument is not specified, resulting REST
appAlias endpoints cannot add the “app/appAlias” String none
segments. In this case, the system does
not support using non-primary Access
Groups within an Operator record.
Authentication
Generated
automatically
Authentication header such as “Bearer

<token>” that you use for DX API
transactions invoked by the Constellation
UI Service. The token is used to pass the
authHeader authentication header. As a best practice, String none
do not specify this, and use the
ssKeyTokenInfo attribute instead. The
system ignores the attribute if the
ssKeyTokenInfo attribute is also specified.
Key name to use with the

API to pass the token
sessionStorage.getItem
information to the embedding. The
attribute should contain the JSON.stringify
ssKeyTokenInfo of the token endpoint response. String none
This attribute contains access_token,
Generated
Name Description
token_type , refresh_token and session_index values. Type Default value
automatically
Specifies the number of milliseconds that

the system waits for authentication to
complete in a hidden iframe.
You can set the value to 0 to avoid an

silentTimeout Integer 5000
attempt to authorize the endpoint
transaction in a hidden iframe. This
setting is relevant for authentication
services other than Pega.
OAuth 2.0
Generated
automatically
Client ID from the OAuth 2.0 client

clientId String none
registration record.
Redirect URI from the OAuth 2.0

client registration record. The URI is staticContentUrl +
redirectUri String
invoked after a successful visible “embed/auth.html”
authorization challenge.
pegaServerUrl +
authorizeUri OAuth 2.0 authorization end point. String “/PRRestService/oauth2/v1/”
+ authorize
pegaServerUrl +
tokenUri OAuth 2.0 token end point. String “/PRRestService/oauth2/v1/”
+ token
pegaServerUrl +
OAuth 2.0 token revocation end
revokeUri String “/PRRestService/oauth2/v1/”
point.
+ revoke
Authentication Service Alias for

invoking the authorize
endpoint.Note: For more information
authService String pega
on configuring external
authentication services, see Creating
an authentication service.
Special attributes
Note: Not for production use. Special attributes are useful for testing and demo scenarios. You must use the attributes
together, and they only work with the pega authentication service.
Generated
automatically
The user identifier value that you use to

userIdentifier String none
log in and generate OAuth access tokens.
The password for the userIdentifier

password String none
attribute encoded in base64.
JavaScript methods in web embed

The host page can use JavaScript (JS) to invoke methods that support querying or manipulating the web embed. This
functionality provides you with the tools to meet the needs of your particular use case.
Note: For Cosmos React web embeds, you invoke the JavaScript API directly by accessing the element and calling the method.
For example:
document.getElementById("theEmbed").load();
JS API methods
Web embeds support the following JS methods:
load
Used in conjunction with the deferLoad=true attribute to delay the load of the embed until this API is invoked.
Arguments: None
reload
Used to return the web embed to its original attributes. You can use this method to get the user back to the first page
that loaded.
For example, if a page contains links to work objects, and the user opens those objects, the embedding displays the case
screen associated with the object. The reload method provides a way to return to the original page. This method is
similar to the load method, but when the action is createCase, this method remaps the embed to an openAssignment action. In
this case, the system uses the ID from the prior createCase invocation for the openAssignment call.
Arguments: None
getEmbedData
Gets the value of a specified property.
Arguments: propName
setEmbedData
Sets the value of a specified property.
Arguments: propName, value
getEmbedInfo
Returns a structure with information about the loading outcome and uncommitted properties.
Arguments: None
logout
Ends the active server session by revoking tokens and removing the content in the web embed. This method also
releases open object locks.
Arguments: None
updateTokens
Passes the token object returned from a OAuth token endpoint back to the embedding when popupReauth is specified as
“false”.
Arguments: token
getEmbedData
setEmbedData
getEmbedInfo
updateTokens
Passes the token object returned from a OAuth token endpoint back to the embedding when popupReauth is specified as
“false”.
getEmbedData
Signature
getEmbedData(propName)
Returns
Property value.
This method returns the latest values from the assignment's flow action, which means some of the values might still be
uncommitted.
Parameters
Name Description Type Required
Name of property value to retrieve. For embeddings related to case pages, use a leading dot
propName String
to mark case-related properties (e.g. “.FirstName”).
For example:
document.getElementById("theEmbed").getEmbedData(".FirstName");
setEmbedData
Signature
setEmbedData(propName, value)
Returns
This method sets the latest values from the assignment's flow action, which includes values that are possibly uncommitted.
Parameters
Name of property value to retrieve. For embeddings related to case pages, use a leading dot
propName String
to mark case-related properties (e.g. “.FirstName”).
value Target value of the propName property. String

For example:
document.getElementById("theEmbed").setEmbedData(".FirstName", "Adam");
getEmbedInfo
Signature
getEmbedInfo()
Returns
The properties within the returned structure are as follows:
Name Description Type
Indicates whether the embed loads

isLoaded Boolean
properly.
Indicates that the assignment contains

isDirty Boolean
uncommitted changes.
Parameters
None
For example:
document.getElementById("theEmbed").getEmbedInfo();
updateTokens
Passes the token object returned from a OAuth token endpoint back to the embedding when popupReauth is specified as “false”.
The embedding host gets updated access_token and refresh_token from a Pega server and passes them back to the web embed.
Signature
updateTokens(<token>)
Returns
Not applicable.
Parameters
<token> JS object returned from the token endpoint. JS object

For example:
document.getElementById("theEmbed").updateTokens("<token>");
Events in web embed

The host page can add event handlers that execute and perform custom processing when specific supported events fire,
which helps you better integrate Pega UI with the host environment.
Event listeners
To listen on an event in the web embed, you can define an event listener on the embedded HTML element using the
addEventListener() method on the web embed.
For example:
let elEmbedding = document.getElementById("theEmbed");
elEmbedding.addEventListener("embedready", handleEmbedReady);
Events
embedprocessingend
Occurs when assignment processing is complete. The embedprocessingend event fires only when case processing is complete,
and not on each assignment screen or flow action transition.
embedready
Occurs before the system displays the UI of the embed.
You can use embedready to tell the host that the PCore infrastructure is ready, which means that the getEmbedData and
setEmbedData methods can be used to adjust some displayed values. You can also use this event with the createCase action
to get details about the current case and assignment IDs.
embedreauth
Indicates that the refresh token has expired and that the user needs to be presented with a login screen to continue the
session.
If popupReauth is true, the embed displays a credential challenge screen for the specified authorization service. If popupReauth
is set to false, the embedreauth event is fired.
embedassignmentsubmission
Occurs when the system detects a Next or Previous assignment submission.
embedcloseconfirmview
Occurs when the user clicks the Done button on a confirmation view.
Troubleshooting web embeds

Ensure that your web embeds work as intended by learning about potential issues and their resolutions.
Web embed displays host page formatting

Including a web embed in a host page may produce formatting issues. To solve the problem, adjust the HTML markup of your
host page.
Condition
When you deploy the web embed on a host page, the web embed formatting includes the styles of the host page (style bleed-
through).
Remedy
Wrap the <pega-embed> element in a <div>.
Apply styles directly to the <pega-embed> element or the <div> element that hosts the embed.
Pop-up window flashes in the web embed after a lengthy delay

Web embeds might encounter issues with pop-up windows during authentication.
Condition
After a five second delay, a pop-up window appears and then quickly disappears before the web embed content is displayed.
Cause
The web embed uses a pop-up window to invoke the authorization endpoint to avoid disrupting the content on the host page.
When the authentication service is other than Pega, the system assumes the external authentication service uses single sign-
on. This means that in most scenarios, the application might not require a login screen. The application first tries to invoke the
authorization endpoint by using a hidden iframe. If the authentication succeeds, the pop-up window does not appear.
However, in some cases, the server configuration interferes with the attempt to authenticate in the hidden iframe. If the
authentication does not complete successfully in five seconds (the initial delay set in the silentTimeout attribute) the web embed
opens an authorization endpoint in a visible window. If the user does not have a valid SSO authentication context, a login
screen might appear in the pop-up window for the user to re-authenticate. If the user has already authenticated in some other
context, no login is required, the authorization code is returned immediately, and the window closes.
Remedy
In Chromium-based browsers, ensure that in the Cross-site Request Forgery system setting, in the Cookie settings
section, the Enable samesite cookie attribute is checked, and the Sometime options drop-down list is set to None.
For more information, see Mozilla developer guidance.
Verify if the Content-Security-Policy header returned by one of the redirect responses is not stopping the authorization
from completing in the hidden iframe. Values to consider are: script-src, frame-src, sandbox, frame-ancestors, and navigate-to.
If the redirect sequence to the identity provider is very slow, then increasing the timeout interval might prevent the pop-
up window from appearing.
If the authentication fails in the hidden iframe, ensure that the server that authorizes the endpoint is not configured to
return the X-Frame-Options header with a response of SAMEORIGIN or DENY. If you fix this configuration, the authentication
redirects in the hidden iframe should succeed. Consequently, the pop-up window does not appear.
For more information, see Mozilla developer guidance.
Set the silentTimeout attribute in the web embed to 0 to prevent the system from attempting the silent authentication in the
hidden iframe. This saves authorization time by decreasing the amount of time the application waits before launching a
visible pop-up window and re-attempting authentication.
Authentication in web embed

Authentication ensures that only users and systems with a verified identity use the web embed and that all permitted
manipulations of the data occur as the current user identity.
OAuth 2.0
The OAuth 2.0 protocol allows external applications to access Pega Platform REST services by using access tokens.
When you create a web embed, Pega Platform automatically defines an OAuth 2.0 client registration data instance that you
can access in the records explorer, in the Security OAuth 2.0 Client Registration node.
The client is automatically set up as public. You cannot modify this setting.
For more information, see Creating and configuring an OAuth 2.0 client registration.
Authentication services
Web embed supports the same authentication services as its parent application. If an authentication service is defined in the
application, you do not need to define it again for the web embed.
For more information, see Creating an authentication service.
Integrating Cosmos React applications

Cosmos React is an opinionated design system that promotes out-of-the-box, low-maintenance solutions. However, its
architecture includes tools that allow experienced developers integrate Cosmos React applications with other design systems
or older applications that rely on sections.
Learn more about making Cosmos React work with existing frameworks in the following articles:
Launching Theme Cosmos pages from Cosmos React portals
Give your users access to Theme Cosmos pages from Cosmos React portals. This approach helps you maintain
application continuity while you rebuild your existing pages in Cosmos React.
Using PCore and PConnect Public APIs
In Cosmos React applications, the Constellation UI Service relies on PCore and PConnect Public APIs to deliver the
application's UI. This approach delivers access to state management, actions, events, and a higher level of abstraction to
the DX APIs.
Exploring Pega Digital Experience (DX) API
Pega Digital Experience (DX) API is a set of model-driven REST API endpoints that enable you to programmatically view,
create, and update cases and assignments.
Messaging service for Pega Constellation
The Pega Constellation messaging service intermediates between the case engine and UI components in browsers that
act as information publishers and subscribers. The new service accepts HTTP-based information and forwards it to
WebSocket subscribers.
Creating custom DX components
While Cosmos React has an extensive library of out-of-the-box assets, the framework provides tools for expanding the UI
by adding Cosmos digital experience (DX) components. This still-evolving framework helps early adopters build interfaces
tailored to their specific business needs.
Launching Theme Cosmos pages from Cosmos React portals

Give your users access to Theme Cosmos pages from Cosmos React portals. This approach helps you maintain application
continuity while you rebuild your existing pages in Cosmos React.
For example, your business owns a Pega mortgage application that is designed in Theme Cosmos. You want to rebuild the
application in Cosmos React. To save time to minimum viable product, you incorporate the existing Theme Cosmos documents
landing page in the new application instead of building a new page.
Before you begin: Check the applications that you want to integrate:
Ensure that both the Theme Cosmos and Cosmos React applications have the same name but different version
numbers.
Ensure that both applications use single sign-on (SSO) authentication. For more information, see Creating an
authentication service.
Creating an openHarness activity

Create an activity that opens a harness in a new browser tab to use for integration of Theme Cosmos pages with Cosmos
React applications.
1. Open the Theme Cosmos application whose pages you want to display in Cosmos React.
2. In the Work- class, create a openHarness activity.
For more information, see Creating an activity.
3. Click Add a step, and then, in Step 1, define the thread of the activity:
a. In the Method field, enter Property-Set.
b. In the Step page field, enter pxThread.
c. Click the Expand to see the method parameters arrow.
d. In the PropertiesName field, enter Param.ThreadName.
e. In the PropertiesValue field, enter .pxThreadName.
4. Click Add a step, and then, in Step 2, define the action:
b. Click the Expand to see the method parameters arrow.
c. In the PropertiesName field, enter Param.actionName.
d. In the PropertiesValue field, enter showHarness.
5. Click Add a step, and then, in Step 3, set the portal name to default:
b. Click the Expand to see the method parameters arrow.
c. In the PropertiesName field, enter Param.PortalName.
d. In the PropertiesValue field, enter "UserPortal" .
6. Click Add a step, and then, in Step 4, in the Method field, enter call pxOpenWorkItemNewTab.
7. In the Method Parameters section, select the Pass current parameter page checkbox.
Configuration of the openHarness activity
8. On the Parameters tab of the activity, add the following parameters:

tabName
className
ruleName
preActivityName
preActivityParams
preDataTransform
9. In the rule form, click Save.
Configuring URL mapping in the Theme Cosmos application

Set URL mapping in your Theme Cosmos application to create a URL address that you can reference from the Cosmos React
application.
Before you begin: Define an openHarness activity. For more information, see Creating an openHarness activity.
1. Open the Theme Cosmos application whose pages you want to display in Cosmos React.
3. Expand the Technical category, and then click URL Mappings.
4. In the list of mapping instances , click pyDefault.
5. On the rule form, in the Landing pages section, click Add URL alias.
6. In the Define URL mapping dialog box, configure the URL path:
a. In the Identifier field, enter a label for your resource.
b. Clear the Map path elements for URL generation checkbox.
c. In the Path element type list, select Constant.
d. In the Value field, enter the URL extension that you want to associate with the page.
e. Click Next.
7. In the Edit processing activity dialog box, configure the activity that starts when the user opens the URL:
a. In the Class field, enter Work-.
b. In the Activity field, enter openHarness.
c. In the Parameter section, provide the parameters for your activity. For example:
Sample activity configuration with parameters
d. Click Finish.
8. On the rule form, click Save as.
9. On the New tab, ensure that the context points to the application ruleset, and then click Create and open.
Overriding the pyIsAutoGenThread
Ensure that the mapped URL address of the target Theme Cosmos landing page opens correctly in a portal by adjusting the
pyIsAutoGenThread when rule.
1. In the ">Theme Cosmos application, in the header of Dev Studio, search for and open the pyIsAutoGenThread when rule.
2. On the Advanced tab of the rule form, define the new logic for the when rule:
a. To the right of the row A of the condition, click the Configure advanced conditions here arrow.
b. In the list of logic structures, select [condition evaluates to true].
c. In row A, enter @String.contains(@toUpperCase(pxThread.pxThreadName),@toUpperCase("autothread")). For example:
When rule configuration and the advanced conditions arrow
3. On the rule form, click Save as.

4. On the New tab, ensure that the context points to the application ruleset and the @base class, and then click Create
and open.
Adding Theme Cosmos landing pages to the navigation menu

Give Cosmos React users access to portal pages from Theme Cosmos applications by adding the pages to the main navigation
menu. With this access, you can expand the scope of your application and better support a gradual phase-out of Theme
Cosmos technology.
You can add items to your navigation menu by editing the out-of-the-box pyPopulateAdditionalNavPages data transform,
which is the source for the data page that defines the contents of the menu. You can use the same method to add external
web pages to the main menu.
Before you begin: Map the URL address of the target Theme Cosmos landing page. For more information, see Configuring
URL mapping in the Theme Cosmos application.
1. Open the Cosmos React application.

2. In the header of Dev Studio, search for and open the pyPopulateAdditionalNavPages data transform.
3. On the Definition tab, click Add a row, and then define the parent row for the logic that appends the Theme Cosmos
page to the navigation menu:
a. In the Action list, select Append and Map to.
b. In the Target field, enter Primary.pxResults.
c. In the Relation list, select a new page.
4. Under the Append and Map to action, add and configure the first child action that defines the label for the Theme
Cosmos page:
a. In the Action list, select Set.
b. In the Target field, enter .pyLabel.
c. In the Relation list, select equal to.
d. In the Source field, enter the label for the page in double quotes.
5. Under the Append and Map to action, click Add a row, and then configure the second child action that defines URL
address for the Theme Cosmos page:
b. In the Target field, enter .pyURLContent.
d. In the Source field, enter the URL path that you mapped in Configuring URL mapping in the Theme Cosmos
application.
6. Under the Append and Map to action, click Add a row, and then configure the third child action that defines menu icon
for the Theme Cosmos page:
b. In the Target field, enter .pxPageViewIcon.
c. In the Relation field, list equal to.
d. In the Source field, enter the name of the icon that you want to use in double quotes.
The name of the icon must be preceded by pi pi-. For more information on out-of-the-box Pega Cosmos icons, see Icon
reference.
For example:
Sample configuration of the pyPopulateAdditionalNavPages data transform
7. On rule form, click Save as.

Adding Theme Cosmos landing pages to the case view actions menu
Expand the case view actions menu by adding links to Theme Cosmos landing pages. This approach helps you integrate
existing landing pages with your new Cosmos React application.
You can use the same method to add external web pages to the actions menu in the case view.
Before you begin: Map the URL address of the target Theme Cosmos landing page. For more information, see Configuring
URL mapping in the Theme Cosmos application.
1. Open the Cosmos React application.

2. In the header of Dev Studio, search for and open the pyDefault data transform.
3. On the Definition tab of the rule form, click Add a row, and then define the parent row for the logic that appends the
Theme Cosmos page to the actions menu:
a. In the Action list, select Append and Map to.
b. In the Target field, enter .pyCaseLinks.
c. In the Relation list, select a new page.
4. Under the Append and Map to action, configure the first child action that defines URL address for the Theme Cosmos
page:
b. In the Target field, enter .pyURLContent.
d. In the Source field, enter the URL path to the target page.
The URL of the target place is the URL of the target application, which you can find in the application definition,
combined with the name that you mapped in .
5. Under the Append and Map to action, configure the second child action that defines the label for the Theme Cosmos
page:
b. In the Target field, enter .pyLabel.
d. In the Source field, enter the label for the page in double quotes.
For example:
Sample configuration of the pyDefault data transform

6. On rule form, click Save as.
Using PCore and PConnect Public APIs

In Cosmos React applications, the Constellation UI Service relies on PCore and PConnect Public APIs to deliver the application's
UI. This approach delivers access to state management, actions, events, and a higher level of abstraction to the DX APIs.
PCore and PConnect objects provide public APIs that connect your Cosmos React application to a specific implementation of a
UI library and the related design system that is used to render the application’s user interface with the DX APIs. For example,
Pega’s Cosmos design system (built on the React UI library) is the default design system that Constellation connects to the
Infinity server.
For more information, see Using PCore and PConnect Public APIs.
Constellation Client Architecture

Exploring Pega Digital Experience (DX) API
Pega Digital Experience (DX) API is a set of model-driven REST API endpoints that enable you to programmatically view,
create, and update cases and assignments.
DX APIs are best used in web self-service use cases where it is important to align your user experience with your digital
strategy while continuing to enable your business users to define and modify your application cases and user interface within
Pega’s no-code model.
DX APIs provide UI metadata that helps you develop a seamless user experience within your chosen front-end framework,
while using the power of Pega’s case management capability. If the custom front end is correctly built by using the DX API
responses, it can automatically adjust to changes in Pega Platform. As a result, an single model can supply a interface that is
rendered through standard Pega UI, mobile, web embed, or a custom front end.
For more information about DX APIs, see the Pega Digital Experience (DX) API Community page.
Messaging service for Pega Constellation

The Pega Constellation messaging service intermediates between the case engine and UI components in browsers that act as
information publishers and subscribers. The new service accepts HTTP-based information and forwards it to WebSocket
subscribers.
A third-party integration service can also act as a publisher.
The following diagram represents the messaging service architecture.
Messaging service architecture
An IP address exposes the messaging service to browsers and publishers. The URL for the service is passed to the browser
during the initial portal load from the dynamic system settings in Pega Platform. The publishers and subscribers use the same
IP address for HTTP POST calls and WSS connections.
For more information about installing and configuring the service, see the Constellation messaging installation site with
advanced developer documentation.
For more information about the Messaging Service, see Working with Messaging Service.
Creating custom DX components

While Cosmos React has an extensive library of out-of-the-box assets, the framework provides tools for expanding the UI by
adding Cosmos digital experience (DX) components. This still-evolving framework helps early adopters build interfaces tailored
to their specific business needs.
While using custom DX components in Cosmos React, keep in mind that it is an expanding product with a narrower feature
set. Consequently, the framework might not support some classic Constellation features. You might also encounter unforeseen
issues.
To maintain a consistent, branded experience across channels, Cosmos React applications rely on the Pega Cosmos design
system for styling. The goal of the Cosmos DX component toolkit aims to extend the library of existing Cosmos components
and create new components that integrate seamlessly within the set of out-of-the-box components. You can use Cosmos DX
components to expand Cosmos React in specific scenarios where out-of-the-box components might not meet immediate
business needs.
For more information about custom DX components, see the Cosmos DX components in Cosmos React Community page.
Constellation UI service
Cosmos React applications rely on a static content microserivce that delivers front-end components and other static content to
the browser.
To obtain configuration, context, and data for Cosmos React applications, the client interacts with the server exclusively
through DX APIs. By keeping the Constellation container separate from other services, you avoid dependencies, give
developers the tools to create new UI components without interfering with other work, and improve overall application
performance.
When creating a new application, you can choose between a view-based Cosmos React UI, or a section-based traditional UI
architecture, which can be further expanded to include hybrid components.
Availability
For Pega Cloud customers, the regional multitenant Constellation service is automatically configured during Pega Infinity
deployment. There is no need for you to install or configure the Constellation engine.
Clients running Pega applications using VM-based or containerized deployments can deploy one Constellation service for your
organization to handle static content requests from any of your Pega Infinity deployments.
For more information about Constellation, see the Constellation UI static content delivery service site for advanced developer
documentation.
Enabling Cosmos React for an application

Enable Cosmos React in your application to explore the new development environment, which improves performance,
interactivity, and response times.
Before you begin: Prepare for implementation:
Review the process of implementing the Constellation UI Service on your system. For more information, see Hybrid mode.
Ensure that Pega Infinity is using a secure HTTPS protocol.
1. In the header of Dev Studio, click the name of the application, and then click Definition.
2. In the Advanced node, select the React-based UI option.
3. Click Generate routing table, and then click Save.
Enabling the hybrid mode in Dev Studio

Result: The React UI environment is now active in your application.
Configuring Docker authentication

Set up the first download of a Docker image from a Pega repository by configuring a Docker authentication config.json file. This
configuration is required when installing the Constellation UI Service with Docker for the first time.
Before you begin: Obtain an API key from the Pega Digital Delivery site. For more information, see Using Pega-provided
Docker images.Note: If you cannot see the Request access key tile on the Digital Delivery site, contact Pega Support. For
internal users, you can create a Service Management request to get the Docker image access privilege. Pega requires re-
authenticating to download Docker images from its repository. As a Linux user, you can set up an authentication file to store
your credentials for the Pega Docker repository. In this way, you can use the file with Docker commands to conveniently
authenticate your identity when you download a new image.
1. In a Linux bash shell with root privileges, in the /home/<Linux_username>/ folder, create a .docker directory.
2. In the /home/<Linux_username>/.docker/ folder, create a config.json file.
3. In the terminal window, encode your user ID and API access key in base64 by entering echo -n'<ID> :<key>' | base64
The variables have the following values:<ID> is the user ID that you receive in an email from Pega Delivery.<key> is the
access key that you receive in an email from Pega Delivery.
4. In the config.json file that you created in step 2, enter the following code:
{
"auths": {
"pega-docker.downloads.pega.com": {
"auth": "<encoded_ID_and_key>"
}
}
}
<encoded_ID_and_key> is the string that you generated in step 3.

Important: You must paste the encoded ID and key in a single line in the config.json file.
5. Save the file.

Cosmos React PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Cosmos React PDF

Uploaded by

Copyright:

Available Formats

Cosmos React

Cosmos design system

For more information, see Constellation UI service.

Configuring Cosmos React

Working with views

Branding your application

Internationalization and localization

Embedding Pega Platform UI in web pages

Integrating Cosmos React applications

Configuring Docker authentication

Cosmos full case page

Cosmos work area

Configuring Cosmos React

Use fields in views. The

Feature limitations in Cosmos React

Data visualization features in Cosmos React

Tools for debugging Cosmos React

Embedding Pega Platform UI in web pages

User interface choice in Pega Platform version 8.7

Theme Cosmos Cosmos React

See Choosing a UI See Choosing a UI

See Choosing a UI See Choosing a UI

See Choosing a UI See Choosing a UI

Mashup (web embed) ✓ ✓

Simple reporting and data exploration ✓ ✓

Complex reporting with sub-reports and joins ✓ ✓

Application UI that uses data from reports with complex joins ✓ ✓

Attribute-based access controls (ABAC) ✓ ✓

OAuth 2.0 authentication ✓ ✓

Best practices overview

Recommendation 8.5 8.6 8.7

Existing applications No UI changes No UI changes No UI changes

Integrations with websites

Guidelines for new applications

For more information, see Feature limitations in Cosmos React.

Guidelines for existing applications

For more information, see Updating Theme Cosmos in your application.

Feature limitations in Cosmos React

For more information, see Choosing a UI version.

Case management limitations

Automations for generating PDFs and documents.

The following question types:

Adding tags from the tags overlay

Data visualization features in Cosmos React

Cosmos React and Theme Cosmos comparison

Theme Cosmos: Report Theme Cosmos: Theme Cosmos: Data Cosmos

Single Axis Combo Chart

Dual Axis Combo Chart

Area (Overlaid, Stack, 100%)

Pie (Normal, Exploded,

Gauge – 270 Arch

Gauge – Half Arch

Gauge – Horizontal LED

Gauge – Vertical LED

Tools for debugging Cosmos React

Cosmos React supports the following debugging methods.

Field values on the Definition tab and the application UI setup

Use react-based landing

View-based architecture with

Server-rendered UI Theme-Cosmos For portal configuration, see

Hybrid Theme Cosmos UI.

For configuration details, see

For configuration details, see