Customizing login and error screens

From PegaWiki
Updating login and error screens to match the context of your application /
Revision as of 14:58, 10 December 2020 by Kutzg (talk | contribs) (Updated capability name)

Jump to navigation Jump to search

Customizing login and error screens

Description Updating login and error screens to match the context of your application
Version as of 8.5
Application 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[edit]

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[edit]

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[edit]

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[edit]

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)