Theme Cosmos - Customizing Login and Error Screens
|Request to Publish||Yes|
|Version as of|
↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓ Please Read Below ↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓
Enter your content below. Use the basic wiki template that is provided to organize your content. After making your edits, add a summary comment that briefly describes your work, and then click "SAVE". To edit your content later, select the page from your "Watchlist" summary. If you can not find your article, search the design pattern title.
When your content is ready for publishing, next to the "Request to Publish" field above, type "Yes". A Curator then reviews and publishes the content, which might take up to 48 hours.
↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓ The above text will be removed prior to being published ↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓
Customizing Login Screens
It is always a good idea to have a custom login screen specific to application or Organization wide, which gives the end-user a context of what he is accessing and make him feel he is in the right place/process.
Pega Platform provides a default login/error screens to access an application and it also provides ability to update/customize the default login and error screens to meet the design/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.
It is a good practice to create a separate ruleset to hold the rules accessed by unauthenticated users/operators. So it is recommended to 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 style sheets).
It is recommended to create custom rules following the in lines of the Pega provided login rules and to not override/customize the Pega provided rules. Instead you will need to do “save as” some of the OTB rules.
Note: Make sure to check those “Save As” rules from platform in case of any upgrades and re-incorporate any changes to those rules back into your customization layer.
In most of the use cases applications may be using 3rd party login services like oAuth or SSO and users will be redirected to a login gateway to enter their credentials.
You can update/customize Login screens in different ways:
1) Editing HTML Source
If you want to edit the source HTML of your login screens, you can do it by saving “Web-Login” rule into your custom ruleset and modify HTML source to meet your design requirements. You can also change error messages in the same rule.
For customizing ‘Forgot password’ screen you can use “pyForgotPassword” rule to modify/add your custom code.
For more details steps visit Pega community article: Customizing login screens for your Pega application
2) Editing Skin/CSS text rules:
You can also customize login screen design with CSS, Pega provides individual Text rules containing the CSS code for login & error screens.
“py-login-screen” is a text rule which contains CSS code of the login screen, you can save this into your custom ruleset and add/modify the styles.
You can just change background image of your login screen, by uploading binary image file to “webweb” (default location/folder in Pega which holds all the images) and referring the image file path inside CSS (as body element background URL property)
For more details steps visit Pega community article: Editing the text rules containing the source CSS for login screens
Editing Error screens:
Users can also edit/customize errors screens (error.jsp and status.jsp), these 2 JSP pages are available in prweb/diagnostic folder.
Another way is to Identify the respective error code and add own custom html files in web.xml
Note: This is not recommended for Pega cloud because it will require a CCB request and could cause issues with upgrade.
Use case examples
You might want to edit your application login screen to display a new logo or change background image for your application, or change the HTML Source to meet design guidelines/mocks.
Before you begin
Is it necessary to plan anything in advance, or are external steps using other tools required to achieve the goal? If any specific configuration procedures (how-tos) exist on Pega Community pages, you can link to those assets here by providing the URL.
Process/Steps to achieve objective
What do individuals need to know to achieve the outcome? What do individuals need to know to achieve the outcome? Enter the precise steps to guide the user to achieving the desired outcome. Remember to always state where in the software the user must perform an action, before giving the action.
If “How To…” documents exist for specific configuration procedures please link (using the url) to those assets on the community **
What do you expect the user to see or be able to do after they complete this design pattern?