Before We Begin
Let us have a quick refresher on Primary Key and Foreign Key in Database terminology and then get into the discussion of linked properties.
Primary Key: A primary key is a combination of one or more columns in a Database table that uniquely identifies each record in a table. It must have unique values and cannot be null. There can be only one primary key for a table.
Foreign Key: A foreign key is a combination of one or more columns in one table that refers to the primary key of a different table. In other words, foreign key helps establish a link between two different tables.
Let us understand this better with an example.
Consider that there are two tables- one for storing Customer details and another for storing Order details.
Customer table has Customer ID that is unique and not null, i.e. it acts as the primary key for the table and each record has a distinct Customer ID. Order table has Order ID as its primary key. Few sample values of these tables are given below:
Customer Table
| Customer ID | Customer Name | Location |
| C01 | John | Virginia |
| C02 | Mary | San Jose |
| C03 | Robert | Austin |
Order Table
| Order ID | Invoice Number | Customer ID |
| O1 | 24911 | C02 |
| O2 | 12378 | C01 |
| O3 | 97512 | C02 |
| O4 | 59161 | C03 |
In the above example, Customer ID is a foreign key in Order table and it points to the Customer ID column in Customer table.
What are Linked Properties?
Linked properties are single value Text properties defined in one concrete class that can establish a read-only link to a record in a different concrete class.
Consider that Customer Table corresponds to OSP-Data-Customer class where CustomerID is the primary key and the Order Table corresponds to OSP-Data-Order class where OrderID is the primary key.
There are different ways to access Customer details from Order class context as discussed below:
- We can have a thread level data page that accepts Customer ID as a parameter. This can use look-up operation of data page to pull customer details from Customer table by using the supplied Customer ID parameter. This approach involves an explicit call to data page with lookup operation to populate customer details.
- We can have a Customer property of page mode inside Order class that points to Customer class which can copy Customer records from a Data page. This customer page at runtime will have the details of Customer retrieved from the Customer table. This approach creates multiple copies of the same data.
Rather, linked properties can be used in this scenario. We can have a single value Text mode of property named Customer created inside Order class that links the record of order class to the corresponding record of Customer class. Any properties from Customer class whether exposed or not can be accessed from Order class by referring to the linked property Customer.
When to use Linked Properties?
It can be used whenever there is a need to link records from two different concrete classes.
How to use Linked Properties?
Let us discuss on how to use linked properties by considering the implementation for the above discussed example of Customer and Order tables/classes.
- Create a single value Text property Customer in OSP-Data-Order class.
- In the data access section of the property, select ‘Automatic reference to class instance (linked)’. Give the linked class as OSP-Data-Customer class. In the linked mapping use CustomerID which is the primary key of the OSP-Data-Customer class. PEGA recommends not to use Rule- classes as linked class.
- Set the value of Customer ID to Customer (linked property).
- We can refer the properties from OSP-Data-Customer class in the context of OSP-Data-Order class in read-only mode. Example: To access Customer Name and Location in a section we can use the syntax: .Customer.CustomerName and .Customer.Location respectively.
- At run time, PEGA retrieves the Customer Details corresponding to the Customer ID and is made available on the current requestor session. In Clipboard, linked properties are visible under Linked Property Pages section.
- A subsequent commit on the top level page which holds this linked property will remove the linked property pages from the Clipboard.
- If any access is made to the Customer Details when the linked property page is available in Clipboard, the same page is used and it avoids another DB hit.
- Each Customer ID will have its own linked property page created in clipboard when it is first referred.
- Linked properties can be referred in Sections, Report Definitions and Expressions but, cannot be used in Activities and Data transforms as target.
- If there are more than 1 key defined as primary key for the linking class, then we need to complete the mapping of all the keys. This is covered as another example in the later part of this post.
Debugging Linked Properties
Tracer tool has an option for tracing Linked Page Hits and Linked Page Misses which allows us to debug linked properties.
When Customer properties like customer name and location are referred while the Customer (linked property) is not set, Linked Page miss happens and this can be determined from the tracer as shown below:
Implementation of Linked Properties with multiple keys in Target class
Consider that we have a class and a table corresponding to Customer Address where the combination of Customer ID and Address Type (Home/Work) act as primary keys.
Let us assume that we need to enhance the Review Purchase Request form with Work Address of Customer. To achieve this, we can create a linked property Address in Order class.
If we have more than 1 primary key for the target class, we will need to map all the keys while defining the linked property.
Both the source properties CustomerID and Address needs to be set in the order class context before accessing the address details using the linked property.
Once done, we can add a column to display Work Address in the Review Purchase Request section and refer the value using the syntax .Address.AddressDetail
- .Address -> Linked property in OSP-Data-Order class
- .AddressDetail -> Property to hold address value in OSP-Data-CustomerAddress class
OOTB Linked Properties in PEGA
PEGA has multiple OOTB linked properties and the list can be viewed from PEGA Help under Reference >Standard Rules > Property Rules >Linked properties.
Advantages of Linked Properties
Linked properties can be used as a substitute to Obj-Open in activities or data join in report definitions or look-up in Data page as they improve performance and present better UI experience.
where should we refer the above data transform and what is the configuration that is to be given in the pages and classes tab???
sabari:
1) Data transform that has the mapping for linked property can be referred anywhere before the section that displays the properties gets rendered. Few examples are: Pre-Data transform of flow action, Defer load data transform for layouts etc.
2) No configuration is needed in Pages and classes tab since we are dealing only with single value text property.
Let us know if you need any assistance during implementation of linked properties. We are happy to help you anytime 😊
Though I have the idea on this concept but your explanation in this regards is really good 👍
Thanks @Ravi Kumar Pisupati
Stay tuned for future posts🙂
Hello Greetings..!
This is really good, now can open a single record without obj-open and join tables with using joins in report definition.
Thanks OSP.
Thanks @Jon snow
We are happy with your learning from OneStopPEGA 😊
Please share us screenshots of property and tracer and clipboard for each scenario for better understanding of linked properties
Sure @Abishek.
We would request you to do hands-on post reading our article for better understanding. We will be happy to guide you on any blockers.
Going forward, we will try to address what you have said.
Very easy to understand. I am liking all the article on case management. Please post more like this. Great job guys
Thanks @Aditya Kunal
Happy Learning 😊
Hi Team,
I have created a text property in “TGB-HRApps-Work-Candidate” class and on that property i have enabled ” Automatic reference to class instance ” with Linked class as “TGB-HRApps-Data-ShowDepts” and unbder linked mapping Source property and Linked class Key properties are populated automatically.
Under Display and Validation:
UI Control: pxAutoComplete
Table Type: Class Key Value : where validation class given as :TGB-HRApps-Data-ShowDepts
I am not able to fetch the records for the Autocomplete source for the above configuration ?
but when i refer ” Data-Admin-Operator-ID” class for that Autocomplete i can able to see the results from the operator table.
Please let me know what would be the configuration?
@Krishna, I saw your question and got very curious. Are you setting the text property to any key value from ur showdepts class? I believe osp guys set the property using data transform. I followed the steps they gave and got output.
hi team, can you help me resolve this….while configuring data transform i am getting this error
Source—
Property GoGoCM-Serv-Auto-Flipkart-Work.CustomerID is undefined.
Source—
Property GoGoCM-Serv-Auto-Flipkart-Work.InvoiceNumber is undefined.
Source—
Property GoGoCM-Serv-Auto-Flipkart-Work.OrderID is undefined.
Source—
Property GoGoCM-Serv-Auto-Flipkart-Work.CustomerID is undefined.
sabari. To introduce myself I am Aditya Kunal, an active follower of this wonderful and informative blog. Can you please elaborate your issue sabari? Are the properties which errored as undefined created in ur linked class?
Starting with DB concept and converting it to Pega terms- wow such a great thought process. Example given is also so appropriate for the concept. You have covered a to z on linked properties. Clipboard structure and tracer showing what is happening is adding more value. Keep up the good work OSP team.
Thanks and happy to see you learn from OSP 😊
Yes guys. We can use this instead of obj-open. A good eye opener for me who always writes obj-open. Explained very good. Awesome to see posts like this. @shashankey: try this poc.
Yes Chaitanya pinnireddy. I started using this in my project and have asked cowsick pannipolamarasetty also to do the same!! It saves lot of time.
I tried this poc today as I worked from home today. Nicely explained. Thanks so much osp team. U are explaining it very nicely. It is like peeling off banana skin and feeding cow. Such a great explanation on linked property. This article ranks number 1 among all others though each and every thing is great and awesome…. @chaitanya: thanks for letting me know about this post.
Happy to hear you learning @Shashankey Pinnireddy
Hi..
I have created 2 data types (Customer,Order) having records. Created one text property (Customer)as linked property. In section, I have referred table and source is OrderList. OrderList is a pagelist property and gave page definition as Order Datatype Class. and created datatransform for setting the customer id.
Where to call that data transform (SetCustomerID)?
I called it in pre process datatransform in flow action. while running the case, it’s not displaying the customer Name, Location values.
Can you please let me know how it can be better in Performance as compared to Data Pages..Linked Property also hits DB and gets all the details and stores in Clipboard as Linked Property Pages so does the Data page as well with added configurable Load Management .
Other question is how Linked Properties and Reference Properties(Property-Ref) differ? Can you please explain
To answer your first query : Linked property works almost the same way as a data page which uses lookup as source. additionally , if the source data changes , if you are using a data page, a developer will have to explicitly clear the data page to see the updated information. If you are using a linked property , Pega will automatically handle the change.
Crystal Clear Explanation with Simple examples for understanding. Kudos to you guys
Rocking LSA’s
Very well done
Hi Team,
I can see that even though we show the customer name to the enduser, the clipboard value for customer is customer id and not the name, which also makes sense. But when it comes to real time scenario, could you please tell me where can this be used.
Thanks for finally talking about > When and how too uuse linked
properties in PEGA? – OneStopPega php patterns
Hi OSP Team,
Thank you very much for this article on Linked properties. I have learned about a new topic today. But, I have a question here. In the artical there is a point saying “Linked Properties cannot be Target properties in Activities and Data Transforms”. Then how can we assign the value to the linked property to retrieve the instance? And in the article itself the value of CustomerID assigned to Customer linked property in a data transform only. So, isn’t it contradicting the statement?
I am in confusion now. Could you please clarify me?
Thanks,
Durga Prasad
hi,
In the above example, say i have another datatype called “Product” and I need to establish a relation between product and the orders so i create a ProductOrderRel datatype.
On the UI, when user selects the Product first, i need to display all the locations where the orders were made for that selected product from the Customer table? Is this possible with linked properties? If not please can you brief on possible solutions.