Difference between revisions of "Updating login and error screens to match the context of your application"

From PegaWiki
Updating login and error screens to match the context of your application
Jump to navigation Jump to search
Tag: Visual edit
(Changed Application name - Daniela Siek)
Tag: Visual edit
 
(6 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{New request
+
{{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}}
  
|Request to Publish=Yes
+
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.
  
|Curator Assigned=
+
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.
|Description=
 
|Applications=
 
|Capability Area=
 
|Version=
 
  
}}
+
== Customizing login screens ==
↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓  '''<big>Please Read Below</big>''' ↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓
+
'''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).
  
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.
+
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.
  
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.  
+
'''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.
  
↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓ '''<big>The above text will be removed prior to being published</big>''' ↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓
+
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.
  
== Customizing Login Screens ==
+
You can customize login screens in different ways.
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.
+
=== 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.
  
'''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).
+
To customize the '''Forgot password''' screen, you can use the ''pyForgotPassword'' rule to modify or add your custom code.
  
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.
+
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].
  
'''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.
+
=== 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.
  
In most of the use cases applications may be using 3rd party login services like [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.
+
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 update/customize Login screens in different ways:'''
+
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).
  
=== 1) Editing HTML Source ===
+
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].
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.
+
== 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.
  
'''For more details steps visit Pega community article:''' [https://community.pega.com/knowledgebase/articles/user-experience/85/customizing-login-screens-your-pega-application Customizing login screens for your Pega application]
+
Alternatively, you can identify the respective error code and add your own custom HTML files in <code>web.xml</code>.
  
=== 2) Editing Skin/CSS text rules: ===
+
'''Note:''' This method is not recommended for Pega Cloud because it requires a CCB request and might cause upgrade issues.
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.
+
[[File:Pega Customized login screen.png|thumb|''(Changed background - example)''|left]]
 
 
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:''' [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: ===
 
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.
 
[[File:Pega Customized login screen.png|thumb|''(Example of changing background)'']]
 
 
 
== 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 **
 
 
 
== Results ==
 
What do you expect the user to see or be able to do after they complete this design pattern?
 

Latest revision as of 16:15, 10 June 2021

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[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)