Deep linking and Semantic URL

[sriks1 (Sravan Srikakolanu)]

Deep linking capabilities in Pega Constellation

Deep linking allows users to access specific content or pages within a Pega Constellation application directly, bypassing the need to navigate through the entire application from the homepage. This enhances user experience and can be crucial for various business needs like marketing campaigns, referrals, and seamless access to specific information or features

Example
Suppose you have a Pega Constellation app for managing customer issues. You can create a deep link that opens the details page for a specific issue, using its Case ID. Instead of searching through Application to find out the CaseID, the user can click the link and go directly to that issue’s details.

How Deep Linking Works in Pega Constellation:

1. Custom URL Schemes: Deep links utilize custom URL schemes that are recognized by the Constellation application.
   Example: https://app.pega.com/prweb/app/AppName

2. Routing: When a user clicks on a deep link, the app checks the URL and figures out which page or view to show, based on the link’s details.

3. Direct Navigation: The app then takes the user straight to the right page, such as a specific case, dashboard, or item, without going through the home page or menus.

What is a Semantic URL and Why Should We Use It?

A semantic URL is a web address that uses clear, simple words to convey the content of the page, making it easily understandable for both people and search engines. This type of URL structure is an out-of-the-box (OOTB) feature in Pega’s Constellation architecture and is beneficial for various elements such as case types, data types, and landing pages. The routing table plays a crucial role in organizing these elements, ensuring that new case types or data types are properly integrated.

By using semantic URLs, users can quickly grasp the content they are about to access, leading to higher trust and click-through rates and making the links easier to share and reference.

The Evolution from Complex to Semantic

Traditional Pega URLs were challenging to work with because they:

• Contained lengthy and complicated internal information

• Were complex and difficult to comprehend

• Didn’t copy and paste well due to space dependencies

• Provided no Search Engine Optimization (SEO) benefits

• Made sharing between users problematic

Traditional Pega URL might look like

Example:

https://app.pega.com/prweb/PRServlet?pyActivity=OpenWorkByHandle&pzInsKey=CASE-123

Semantic URLs address these limitations by providing:

• Clean, meaningful URL structures

• Application-specific identifiers

• Improved user experience for navigation

• Better support for modern web standards

Semantic URL in Constellation would be:

Example:

https://app.pega.com/prweb/app/AppName/cases/CASE-123

For Traditional way of URL Mapping Pega Documentation: Defining URL patterns for work items.

How Pega Forms Semantic URL Structures

1. Case types
When you open a case, the URL is structured to include the case type and the case ID, making it easy to understand which case is being viewed.

Example:

https:///prweb/app///

• is the name of case, like “Employee onBoard”
• is the unique identifier for that specific case.

Sample:

https://sample.pega.com/prweb/app/HRApp/employee-onboards/E-28010

Limitations

• At present, semantic URLs are not supported for assignments.

2. Data types

When viewing a data record, the URL structure includes the data type’s default record lookup data page and the associated parameters.
Before this functionality can be used, the default data source for the data type must be configured. This setup supports CRUD operations and enables users to preview or open records in a new tab.

Example:

https:///prweb/app//data/?dataViewName = <D_LookupDpage>&<PrimaryKey(s)>=<ID(s)>

• < data-type > is the name of data type, like “Employee”

Sample:

https://sample.pega.com/prweb/app/HRApp/data/employee?dataViewName=D_Employee&EmployeeID=A2021002

3. Landing Page
   Landing pages (such as dashboards or reports or case type list ) have URLs that reflect their function, often using the name of the landing page or feature.

Example:

https:///prweb/app//

• is “employee-onboarding-process”

Sample:

https://sample.pega.com/prweb/app/HRApp/employee-onboarding-process

What is a Routing Table and How Are Route Keys added to the URL?

The pyRoutingTable (Rule-UI-Routing) rule in Pega defines how user-friendly URLs are generated and mapped to the appropriate case types, data records, and landing pages, making navigation and record access clear and efficient within the application.

Whenever a new case type or data type is created, a routing table is automatically generated in the default branch or the currently open ruleset version. If a routing table is not present, you can add the data type or case type to the Application definition and then generate the routing table.

This routing table, defined by the pyRoutingTable rule, specifies how route keys (such as case type or data type names and identifiers) are included in URLs. This ensures that each case or data record can be accessed directly through a meaningful, semantic URL. Below is an example of how the pyRoutingTable rule is represented in XML format:

If we format <pyRoutes> tag, the structure looks like the following:

This approach ensures that the correct route keys are added to URLs, facilitating accurate navigation and record access within the application.

Why and how do I regenerate the routing table?

If Routing table is not generated correctly we may experience several runtime issues that impact navigation, user experience, and application functionality. The routing table is responsible for mapping URLs to the appropriate UI pages, views, or actions. Below are typical issues you may encounter:

1. Blank Landing pages: Navigating to a URL results in a page with no content. The routing table entry for the URL is either missing or points to a non-existent component.

2. Incorrectly formatted Semantic URL: When a case type is inherited from a built-on framework application (such as Customer Service or Government Platform), its class might not be included in the routing table. This can cause the semantic URL to be in the wrong format. Regenerating the routing table will correctly create the tag and fix the URL format.

Generate Routing table

1. Add Case types and Data types in Application definition – Cases & Data Tab.

   

2. Click on “Generate routing table”
   

   

Summary

Pega Constellation enhances user experience by enabling deep linking, which allows direct access to specific application content such as cases or dashboards without navigating from the homepage. This is achieved through custom URL schemes that route users directly to targeted pages. Semantic URLs in Pega provide clear, user-friendly web addresses that improve navigation, sharing, and search engine optimization by reflecting the content of pages such as case types, data types, and landing pages.

• Advantages of Semantic URLs: They replace traditional complex URLs with clean, meaningful structures that enhance user experience, support modern web standards, and improve link sharing.

• URL Structure for Cases, Data, and Landing Pages: Case URLs include the case type and ID, data URLs include data type and parameters, and landing pages use descriptive names, making URLs intuitive and easy to interpret.

• Role of the Routing Table: The pyRoutingTable rule defines how semantic URLs map to case types, data records, and landing pages, ensuring accurate navigation and direct access through meaningful URLs. It is automatically generated but can be manually created if it is absent.

• Importance of Regenerating Routing Table: Correct routing table generation prevents runtime issues such as blank landing pages or incorrectly formatted URLs, especially when inheriting case types from framework applications. Regeneration fixes these problems by updating route keys.

Reference

https://docs.pega.com/bundle/platform/page/platform/case-management/defining-default-data-sources.html

Constellation 101 series

Enjoyed this article? See more similar articles in Constellation 101 series.

[LalithKumar.J (LALITH KUMAR Jami)]

Thanks much I’m looking for this long time, Appreciate your detailed analysis. This is very informative.

[MarcCheong]

@sriks1 great article!

An often overlooked benefit of Constellation - you can open App 1 in one tab and App 2 in another tab

• https://app.pega.com/prweb/app/App1
• https://app.pega.com/prweb/app/App2

Which means you can just favourite or bookmark the above and open them when/as needed

[PraveenP16892497 (Praveen Parsa)]

@sriks1

Thanks for detailed explanation. For one of the requirements, we did like this only in Constellation.

1. Is there way we can pass parameters to landing pages using this deep linking functionality?
2. For example, in data view we have tabbed view, can we achieve which tab should be selected dynamically?
3. For calling this semantic url via DX component, any best approach instead of redirecting to entire URL?

[AVIKCEMK (Avik Chakraborty)]

@MarcCheong

There is a very common requirement , to provide one work link , in correspondence rule , so that user can click and open the work object . In traditional UI , we used to do it via Correspondence fragment rule and including that correspondence rule in specific correspondence.

In correspondence fragment rule we used to dynamically generate , the worklink or sometimes , we take help of URLMapping rule .

In Constellation -is it the same correspondence fragment path we need to use or this sematic URL concept we need to use ?If we need to use semantic URL can some one pls share the steps for it ?

[Kuresh_Surury]

@sriks1@MarcCheong For custom Auth services what we found works best for semantic URL is below

https:///prweb/PRAuth/app//

In Case you have different authentication pattern for Internal(SAML) vs external users(OpenID)

for Case ID semantic URL it will end up looking like below when embedding in corr or otherwise

https:///prweb/PRAuth/app////

[AVIKCEMK (Avik Chakraborty)]

@Kuresh_Surury @MarcCheong @sriks1

We have formed the URL like below and we are able to open the case directly from email ( Correspondence)

https:///prweb/PRAuth/app//// .

As of now , we haven’t put the auth service name in Application rule ( in security tab) as , we have put the custom Auth service name in the URL itself .

Say the user is having multiple Access group for the application and each access group is having their own portal. With the current semantic URL approach , We are observing , what ever the 1st access group , present in the Operator id, for the respective application -->PEGA is taking that and opening the case . Can some one please guide , how to pass the Portal Name as well in this context , so that this discrepancy will not happen ?

[sriks1 (Sravan Srikakolanu)]

Hello @AVIKCEMK

It is possible to pass the Portal parameter within a semantic URL by appending ?portal=<PortalName> at the end of the URL.

Example: https://sample.pega.com/prweb/app/HRApp/employee-onboards/E-28010?portal=WebPortal

Please let me know if you need further clarification.

[MarcCheong]

@PraveenP16892497really good questions. Unfortunately, neither is possible right now, within the current Semantic URL infrastructure.

There are asks on our backlog for this (EPIC-102157), you’re not the first to ask. It’s not in for '25 though.

[sriks1 (Sravan Srikakolanu)]

Hello @AVIKCEMK

In Constellation, there is no need to use the Correspondence fragment; we can utilize the Semantic URL instead.
We need to construct the URL (Example: pxRequestor.pxReqContextURI + “/” + pxRequestor.pxReqServletNameReal + "// " + .pyID) and push it into a field/parameter before calling correspondence, so that it can be used.

[MarcCheong]

@AVIKCEMK if the custom auth service is defined on the application rule then it should call that auth service as part of the SSO? so just https:///prweb/PRAuth/app/ ?

That is how i’ve done it in the past (pxRequestor.pxReqContextURI + “/” + pxRequestor.pxReqServletNameReal) then let the app rule call the authentication. I only mention this because i find a lot of people don’t do this and as you outline, trying to be explicit in the URL path instead to ensure you hit it.

That said, if you have multiple authentication, then you need to think more about that configuration. So you could use a default service OR trace this copy link button to figure out how pega constructs it?

[VenuGopalaKrishnK17232485 (Venu Gopala Krishna Kondagudupu)]

@AVIKCEMK any reason , multiple access groups having the same app rule pointed. May be you can have unique app rules pointed to each AG of the same operator and use this unique app name in the url.

[MarcCheong]

This is covered further in another 101 series article:

Switching portals and access groups in Constellation | Support Center

[MarcCheong]

@AVIKCEMK music to my ears! Much easier and best practice these days.

[AVIKCEMK (Avik Chakraborty)]

@sriks1

We have a custom SAML SSO authentication and to access any case, user needs to go via that .

In Tradition UI , In Correspondence fragment , we used to form the base url as https:///prweb/PRAuth/app//CustomAuthService( User’s needs to be authenticated via a custom SAML auth service ) .

For semantic URL , If we concatenate pxRequestor.pxReqContextURI + “/” + pxRequestor.pxReqServletNameReal—>This is not forming the URL with CustomAuthService as none of the property hold custom auth service name . In the pxRequestor page , we do see pyAuthServiceAlias which holds our custom auth service name but not sure , how it can be used here .

Considering this custom auth service , Can you please suggest , how to form the case link , in constellation?

[AVIKCEMK (Avik Chakraborty)]

@MarcCheong Thanks for the clarification. I think, for our application, we will be able to manage a single Access group for a User.