Customizing login and error screens

Customizing login and error screens

Description	Updating login and error screens to match the context of your application
Version as of	8.5
Application	Pega Platform
Capability/Industry Area	User Experience

It is always a good idea to have a custom login screen specific to an application or organization. Custom screens give users a context of what they are accessing and make them feel that they are in the right place or following the right process.

Pega Platform provides a default login and error screens, but you can also customize the default screens to meet the design and branding needs of the current application. However, to make any changes, you need to create and deploy a custom ruleset that contains rules that hold and display your custom code.

Customizing login screens

As a best practice, create a separate ruleset to hold the rules accessed by unauthenticated users or operators. Create a custom ruleset for all the rules related to login screens, which include the login screen, authentication screen, logout screen, and other screens (all screens with source HTML and custom cascading stylesheets).

Develop custom rules based on the default login rules and do not override or customize the rules that are provided in Pega Platform. Instead, use the Save as option for the out-of-the-box rules.

Note: Check those “Save as” rules in Pega Platform in case of any upgrades, and then re-incorporate any changes to those rules back into your customization layer.

In most of the use cases, applications can use third party login services, such as oAuth or SSO, and users will be redirected to a login gateway to enter their credentials.

You can customize login screens in different ways.

Editing HTML source

If you want to edit the source HTML of your login screens, you can do it by saving the Web-Login rule in your custom ruleset, and then modifying the HTML source to meet your design requirements. You can also change error messages in the same rule.

To customize the Forgot password screen, you can use the pyForgotPassword rule to modify or add your custom code.

For detailed steps, see Customizing login screens for your Pega application.

Editing skin and CSS text rules

You can also customize your login screen design with CSS. Pega Platform provides individual text rules containing the CSS code for login and error screens.

The py-login-screen rule is a text rule which contains the CSS code of the login screen. You can save this rule in your custom ruleset and then add or modify the styles.

You can change the background image of your login screen by uploading a binary image file to webweb (the default folder in Pega Platform which holds all the images), and then adding the image file path in CSS (as a body element background URL property).

For detailed steps, see Editing the text rules containing the source CSS for login screens.

Editing error screens

You can also customize error screens (error.jsp and status.jsp). These two .jsp pages are available in the prweb/diagnostic folder.

Alternatively, you can identify the respective error code and add your own custom HTML files in web.xml.

Note: This method is not recommended for Pega Cloud because it requires a CCB request and might cause upgrade issues.

(Changed background - example)

A business solution that automates workflows in your organization. Multiple, unrelated applications can be hosted in the same system. You create an application by running the New Application wizard.

A business solution that automates workflows in your organization. Multiple, unrelated applications can be hosted in the same system. You create an application by running the New Application wizard.

The top level of the three-level organization hierarchy that is available for use in all of your applications. The organizational structure affects the management reports, statistics, and rules that are available to users in that organization. One system can support multiple organizations. An organization is an instance of the Data-Admin-Organization class.

The basic building blocks of an application, rules define the behavior of an application. There are many types of rules, each defining a different type of behavior. For example, rules define the display of a form, the fields that are used in your application, and the flows that define the process of completing work.

The system can reuse rules throughout your application. For example, in an application for ordering replacements parts, you can define a user interface to capture an address, and reuse the same rule for the UI to capture both the mailing address and the billing address for the order.

You define rules in an application to create a business solution for your organization and customers. Rules provide flexibility during the development process and help you design applications more efficiently, so that they can be implemented again in future projects.

Parameters that authenticate users or external processes that need to access applications, enabling users to log in with appropriate security permissions. Credentials typically consist of a user name and password. The user name is the key to an operator ID instance. The password can be stored in that instance (in encrypted form), or in a corporate directory service, such as the one provided by Microsoft Active Directory.

A collection of rules (the basic building blocks of applications built with Pega Platform) that describe key components and how part of an application works. Rulesets help you store, categorize, and version the rules in an application.

A ruleset consists of ruleset versions that store the updated versions of rules. For example, in an application used for hiring new employees, the application might include several rulesets, one dedicated to defining the UI and processes used to hire employees, and another ruleset that defines the application's integration with a Job website.

You usually implement several rulesets when developing a large application. Once the rulesets are adequately tested and make it into a production environment, you can create a new version of the rulesets to develop and test during the next development cycle.

The basic building blocks of an application, rules define the behavior of an application. There are many types of rules, each defining a different type of behavior. For example, rules define the display of a form, the fields that are used in your application, and the flows that define the process of completing work.

The system can reuse rules throughout your application. For example, in an application for ordering replacements parts, you can define a user interface to capture an address, and reuse the same rule for the UI to capture both the mailing address and the billing address for the order.

You define rules in an application to create a business solution for your organization and customers. Rules provide flexibility during the development process and help you design applications more efficiently, so that they can be implemented again in future projects.

Skins determine the general visual style of your interface and let you define the typography, placement, and appearance of UI elements. The skin separates content from presentation, so that you can reuse your configurations and keep a consistent UI design. For example, you can reuse a section anywhere in your application and retain a uniform style that is specific to your company.

A case in a concrete class that inherits from the Work-Folder- class. A folder object holds a collection of one or more cases, including covers and other folders, to provide access for analysis and reporting.

An entity that models data in your business processes and defines what information you need to provide to reach your business goal. For example, in a process of hiring new employees, you can create properties that correspond to the personal details of a candidate, such as a name, a surname, and an address. Then, when you review applications from different candidates, you provide values specific to each candidate. To save time and make your application more relevant to customers, you can reference properties in different elements of your application, and then populate them with data at run time. For example, you can include a property that references a customer name in an email that your application sends automatically. As a result, each time that the email message is personalized and includes an actual customer name. Properties help you collect and provide consistent data irrespectively of the method in which users interact with your application. By referencing properties, you ensure that a user receives the same information through a website, an email, or a mobile app.

A Pega Platform method, distinct from a Java method. An operation that can be performed by one step of an activity ( Rule-Obj-Activity rule type), or by a Parse Structured rule ( Rule-Parse-Structured rule type).