Sibling Records

Sibling records are used as a way to bolt on to delivered PeopleSoft records and minimize customizations. The theory being that the delivered record can change, and the sibling record will not be impacted provided that the keys on the delivered record are not modified. This article goes through a simple example using the delivered PeopleSoft message catalog tables.

Standard Customization

Say we wanted to add another field called DEBUG_INFO to all message catalog entries. The purpose of this field would be to provide additional information related to the message for debugging purposes. Obviously not every message would need or want debugging information, so this would be an optional field. Also, given the delivered data in the message catalog, this field may relate more specifically to our own message catalog entries than the PeopleSoft delivered ones. However, in some cases (e.g. a known workaround) the debug info could be stored with the delivered message.

One way to do this would be to simply customize the delivered message catalog functionality using something like the steps below:

  • Create a new field called PW_DEBUG_INFO
  • Add the field PW_DEBUG_INFO to the delivered message catalog record, PSMSGCATDEFN
  • Alter the table structure in the database
  • Modify the page MESSAGE_CATALOG by adding the new field to it and rearranging the layout.

While this is very straightforward, at this point, we've made two customizations, one to a record and one to a page. Of particular concern are customizations to records because a record can be used in a number of places. Customizations to pages can also be troublesome if they are used in more than one component or are subpages used on more than one page. Oracle regularly deliver new message catalog entries, so the above will have patching implications and make impact analysis more difficult.

These are some reasons to look at using a sibling record.

A note for discretion at this point. Sibling records aren't a silver bullet for avoiding customizations. I've seen cases where developers have gone to extraordinary lengths and complexity to get a sibling record working when the patching implications really didn't warrant it. You can go too far with this approach. If support and maintenance of your sibling records/bolt-on customization causes more work on a regular basis than the impact it has on patching, then in reality you've actually made things worse not better. Good judgement is always required here, and you need to do some impact analysis. Tools like iMPACTUS! can be really helpful for this.

Sibling Record

Moving on, this is a pretty clear cut example where a sibling record is a far better approach. Here's an approach you could take to achieve essentially the same outcome:

  • Create a new field called PW_DEBUG_INFO (of course reuse an existing field if that works too). Make it a Long Character field.
  • Create a new record, PW_MSGCATDBGINF (name this appropriately based on your site's conventions)
  • Add the same keys to PW_MSGCATDBGINF as those on PSMSGCATDEFN. These are MESSAGE_SET_NBR and MESSAGE_NBR. This is what makes your new record a sibling record. Make sure your search keys are also the same.
  • Add the field PW_DEBUG_INFO to PW_MSGCATDBGINF.

So here's how our sibling record looks at this stage:

message-catalog-sibling-record.png

Keys are very important here, so double check you have that correct before proceeding.

Also remember to build your record as a table in your database at this point! Otherwise you'll have SQL errors later.

Sibling Page

To continue with the bolt-on methodology, we'll also create a separate sibling page rather than modifying the delivered page. Again discretion is required here, and you may find it more complicated to add your own page and make it work in the context of the component than simply customizing the delivered page. Also keep in mind the impact on end users. Do you really want them to have to navigate to another page simply to set a check-box for one extra field? Will they forget? Will the errors confuse them when they do? Don't lose sight of the fact that creating unnecessary complexity is always worse than a minor, contained customization.

Having decided that a sibling page makes sense, we'll create another page with the same key structure as the delivered MESSAGE_CATALOG page. This page needs to transfer key data from the delivered record PSMSGCATDEFN to our bolt-on record PW_MSGCATDBGINF. What this means is that we just want to add our additional fields from the bolt-on record to the page, and let the scroll levels do the rest of the work automatically for us.

The steps to accomplish this are:

  • Create a sibling page called PW_MSGCAT_DBGINF (name this appropriately based on your site's conventions)
  • Modify the page title to Message Catalog Debug Information
  • At scroll 0, add the fields MESSAGE_SET_NBR and DESCR from PSMSGSETDEFN. Note the description field is for informational purposes, not for passing key data. The best way to do this is to have the delivered page open and drag the fields across to your new page.
  • At scroll 1, add the fields MESSAGE_NBR and MESSAGE_TEXT from PSMSGCATDEFN. You don't need the key field MESSAGE_SET_NBR here as that has already been set at scroll 0. Again the MESSAGE_TEXT is for informational purposes, not passing key data. Have the delivered page open and drag these fields across.
  • Create a scroll at level 2 (occurs level 2) and add the field PW_DEBUG_INFO from PW_MSGCATDBGINF as a long edit box.

This is how the page looks in layout mode:

message-catalog-sibling-page-layout.png

And this is the page structure in order mode:

message-catalog-sibling-page-order.png

What's probably confusing at this point is why your sibling record and field are at scroll 2 instead of scroll 1? The answer is that in order to automatically pass the keys from PSMSGCATDEFN (the delivered record), you need to be one level down from it. Putting the sibling record at scroll 1 assumes that all keys come directly from scroll 0 which contains only the PSMSGSETDEFN record and this is not the case (the key field MESSAGE_NBR comes from scroll 1 - PSMSGCATDEFN).

The records may be siblings in terms of key structure, but the way they behave on the page/scroll is actually more like a parent-child relationship. This means that you can't use this convention if you have a sibling record on a page where the delivered record is at scroll level 3, as you can't put your sibling record at scroll 4 (there is no scroll 4, PeopleSoft restricts this to a maximum of scroll 3). In such cases you would have to set the keys of the sibling record using PeopleCode.

Bolt-on to Component

In order to bolt-on our sibling record and page, we need something to bolt it to. That's the delivered component, MESSAGE_CATALOG1. This is where the customization has to occur. However it has minimal impact as we only need to add one page to one component. Drag your sibling page PW_MSGCAT_DBGINF into the delivered component and give it an appropriate item label.

message-catalog-bolt-on-to-component.png

Make sure you tag the customization in the comments of the component properties:

message-catalog-component-tag-customization.png

Also, in order to see the sibling page, you'll need to enable the Display Folder Tabs (top) setting in the Internet tab of the component (as this will be disabled as delivered).

message-catalog-component-display-folder-tabs.png

Security

In order to see your new page, you'll need to add security to it in a relevant permission list. To find which permission lists are already associated with the MESSAGE_CATALOG page, use the following SQL:

select *
from PSAUTHITEM
where PNLITEMNAME = 'MESSAGE_CATALOG';

One of the permission lists (CLASSID) returned is PTPT1200 and I'm going to use this one.

Like the rest of steps in this article, you should avoid modifying a delivered permission list, and instead use a cloned/custom one if possible. This ensures you don't lose security to your sibling page next time you apply a PeopleSoft patch.

  • Navigate to PeopleTools > Security > Permissions & Roles > Permission Lists and open PTPT1200.
  • Switch to the Pages tab and find the UTILITIES menu and choose Edit Components.
  • Find the MESSAGE_CATALOG1 component and choose edit pages
  • Authorize the Debug Information page on this component
message-catalog-sibling-page-security.png

Press OK, and OK again, and make sure you save the permission list!

Testing

Right, time to test it and see if it works. Navigate to the message catalog:

PeopleTools > Utilities > Administration > Message Catalog

Open a message set. You should see the debug information page as well.

message-catalog-debug-information.png

If you don't, a few things could be causing the problem:

  • Did you save your permission list changes?
  • Does the user you are logged in have access to that permission list?
  • Did you enable the Display Folder Tabs (top) setting on the component?
  • If the item appears in the table PSAUTHITEM then it's a caching issue. First start with clearing your browser cache/restarting your browser. If that doesn't work, try application server, and web server cache.

To complete the test, enter some debugging information and save. Verify that the page saves correctly and that you see this data in the sibling table:

select * from PS_PW_MSGCATDBGINF;

You should also return to search and reopen the entry and confirm the debugging information is loaded and displayed.

Source Code

The source code for this article can be downloaded from the PeopleSoft Wiki Google Code site. If you use this project, you'll still need to apply security as per the security steps above.

Comments

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License