View source for Updating login and error screens to match the context of your application

{{Design pattern|Title=Customizing login and error screens|Description=Updating login and error screens to match the context of your application|Version=8.5|Applications=Pega Platform|Capability Area=User Experience|Owner=Atthelli, vinay kumar}}

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 [https://community.pega.com/knowledgebase/articles/security/85/oauth-20-management-services 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 [https://community.pega.com/knowledgebase/articles/user-experience/84/customizing-login-screens-your-pega-application 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 <code>webweb</code> (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 [https://community.pega.com/knowledgebase/articles/user-experience/85/editing-text-rules-containing-source-css-login-screens Editing the text rules containing the source CSS for login screens].

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

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

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

[[File:Pega Customized login screen.png|thumb|''(Changed background - example)''|left]]