Five Reasons to Adopt the Application Services Framework

PeopleSoft's Integration Broker has support for REST and JSON. But, it is clear from the metadata, design, and history that Integration Broker favors SOAP and XML (Web Services). Is there a better alternative? YES! As of PeopleTools 8.59, we have a module designed specifically for REST: the Application Services Framework (ASF).

Here are five reasons you should consider ASF for your next integration project:

1. URL Design

REST focuses on objects and data. In an enterprise system, business objects might be Employees, Students, or Vouchers. In ASF, we might call these root resources. Continuing with the Voucher example, we might have the following URLs:

• .../ap/vouchers
• .../ap/vouchers/000000012567

When constructing an Application Service, we would have the "ap" service, which would then have a "vouchers" root resource. We could then define URI templates for:

• vouchers (get a list of all vouchers)
• vouchers/000000012567 (get a specific voucher)

We would further define HTTP methods, such as GET, PUT, PATCH, or POST, to fetch, update, or create business objects within the respective collections.

The Application Services framework helps us design URLs by first thinking about the module → then the collection → and then the specific object (generic to specific).

When we browse the Internet, we expect to find an organized collection of documents (endpoints) conveniently filed in meaningful folders. Computers browse the Internet, and those computers should expect an organized collection of business "documents" as well.

2. 201 Created Success Status Code

Web Services and SOAP use a protocol within a protocol. The typical Web Service request uses HTTP as the transport protocol and SOAP for the transaction protocol. Therefore, a Web Service might return a 200 HTTP status code to report success even though the SOAP transaction failed.

REST HTTP status codes have meaning. HTTP status codes in the 200 range represent successful responses. The most important HTTP status codes for a PeopleSoft developer are 200, 201, 202, and 204. These are the ONLY HTTP success status codes supported by ASF. Integration Broker REST-based Service Operations, on the other hand, support several other 200-level status codes, but with one critical omission: REST-based Service Operations do not support 201. 201 is the status code for "created." Assuming a PUT or a POST, the proper response may be a 201 - Created. This is critical. If the service handler immediately creates a transaction, then it should return a 201. The Application Services Framework supports this, but traditional REST Service Operations do not.

3. 401 Unauthorized Bad Request Status Code

PeopleSoft takes control of the HTTP Authorization header for several reasons. Here are a couple:

• To determine if the requester is authorized to access the requested service.
• To assume the identity of the user making the request, allowing PeopleCode to run as the proper user.

If PeopleSoft determines the requester does not have access (based on roles and permission lists), then PeopleSoft will return the 401 Unauthorized HTTP status code. This happens at the Integration Broker level, and it is fantastic!

But what if your business logic needs to return a 401 Unauthorized? Traditional REST-based Service Operations do not allow this.

Consider the following example. Let's say that a user is authorized for our /ap/vouchers service (the example above). That user might be authorized to access certain vouchers, such as .../ap/vouchers/000000012567, but not .../ap/vouchers/000000012568. This is called row-level security. In this scenario, we should return a 401 - Unauthorized. The user is authorized for the service, but not the data.

Traditional REST-based Service Operations do not allow you to return a 401 Unauthorized EVER. ASF does. 401 is an acceptable failure response from an Application Service.

4. OpenAPI

Metaphorically speaking, OpenAPI is the WSDL of REST. ASF generates OpenAPI specifications for us. We can plug these OpenAPI URLs or downloaded descriptors into various consumers, including Oracle Digital Assistant, Oracle Integration Cloud, Oracle Visual Builder, and more!

5. PeopleCode

ASF was designed to expose Application Classes as REST services. The framework includes an API designed to construct single-row and multi-row responses. The API was designed for REST with support for HTTP status codes and HTTP methods.

6. (Bonus) Metadata Design

ASF metadata consists of:

• Module
• Root Resource
• URI Templates
• Parameters
• Result States
• HTTP Headers

All of these are common and expected REST metadata concepts. Traditional REST Service Operations, on the other hand, include Messages, Services, Service Operations, and Documents; metadata structures that are more appropriate for Web Services than REST.

What to learn more? Create a free account at jsmpros.com and explore our free webinar replays to learn the basics of the Application Services Framework. Next, join us for our three-day live virtual Integration Tools Update course. Prefer to learn at your own pace? This same material is available on demand! Watch the videos whenever and wherever you like, and then complete the hands-on activities on your own server.

PTF: Recorder is unable to load... Now What?

I love PTF! With Selective Adoption, Continuous Delivery, and Customization Isolation strategies, PTF is more important than ever. Since Event Mapping, Drop Zones, and Page and Field Configurator don't appear on compare reports (and that is the point), we need a tool like PTF to expose regressions we would have found through the traditional retrofit analysis. The traditional retrofit approach required us to analyze and retrofit every customization. Event Mapping, Drop Zones, and Page and Field Configurator free us to focus on just what broke during the upgrade. And this is why PTF exists. The PTF regression test is how we find what broke. PTF is the linchpin that holds the whole isolated customization strategy together. Without it, we either go live with undiscovered errors or we continue to analyze and retrofit everything.

But what if you launch the PTF recorder and suddenly see this?

What happened? The PTF recorder is a Chrome/Edge plugin. That plugin needs to be loaded for the recorder to function. The PTF application attempts to install this plugin each time it launches the recorder. Depending on your enterprise settings, however, Chrome may deny that request. This is what happened to me. Enterprise customers have been dealing with this since PeopleSoft switched to the Chrome recorder. However, this is what surprised me: I'm simply using a standard Chrome download on an unmanaged server. In fact, PTF used to work just fine on this very server, and this behavior is a recent development. Perhaps Chrome altered its security policy?

Fortunately, this is a known and documented issue. Enterprise customers with highly controlled Chrome environments have been experiencing this issue since PTF switched to the Chrome recorder. Take a look at MOS Doc ID 2922127.1. This document outlines the steps necessary to correct the issue. Following those steps, I launched Chrome as an Administrator by:

1. Typing Chrome into the Windows Menu and
2. Right-clicking the Google Chrome entry and choosing Run as Administrator from the popup menu

I then navigated to chrome://extensions/ and turned on Developer Mode:

Finally, I dragged the Chrome extension psTstRecCh.crx file onto the Chrome extension window:

But after a restart, it still didn't work. I could now see the extension listed in Chrome, but it was disabled, and no matter how many times I clicked, it wouldn't enable itself!

Even though the extension was installed, Chrome wouldn't trust it. Even as an Administrator, I could not enable the extension. The final step is to override Chrome's behavior by encouraging it to trust Oracle's PTF extension. We do this through the Windows Registry. The appropriate Windows Registry keys are listed in PeopleBooks under Installing a PTF Client > Configuring Browser Settings. Here is the contents of my *.reg file I imported into my Windows Registry.

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome]

[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\ExtensionAllowedTypes]
"1"="extension"

[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\ExtensionInstallAllowlist]
"1"="boainbfkaibcfobfdncejkcbmfcckljh"

[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\ExtensionInstallBlocklist]
"1"="*"

Please note that editing the Windows registry can be risky and potentially cause serious problems, including system instability or even rendering Windows unbootable. Therefore, it's crucial to proceed with extreme caution and only if you are confident in your actions. Always back up the registry before making any changes, and keep detailed records of modifications.

And that was all it took! My PTF recorder is now working as well as ever!

At JSMpros, we teach PeopleSoft tips like this every week. Check out our schedule to see what we are offering next! Have a large group you would like to train? Contact us for scheduling and group pricing.

Mock Service URLs for PeopleSoft Testing

 As you create, learn, and discover Integration Broker's capabilities, it is helpful to have mock APIs for testing purposes. Here is a list of my favorites.

• {JSON} Placeholder (REST: scroll to the middle to see the list of URLs)
• "Dummy" REST Api (REST: Employee services)
• Reqres (REST)
• CDYNE SOAP Services (Note: These often have "free for testing" license keys)
• Sample SOAP Server Time Service

Many of these services have secure and non-secure alternatives. The value of insecure testing is you don't have to import certificates. On the other hand, the secure versions help you prove your PeopleSoft certificate import skills.

Do you have some sample APIs you use? If so, please share them in the comments!

At JSMpros, we teach PeopleSoft REST and SOAP integrations regularly. Want to learn more? Check out our Integration Tools Update course to learn best practices and strategies for incorporating REST and JSON into your development process!

Which Query Security Tree?

Here is the scenario:

A user needs to create a query, but doesn't have security access to view a record. The user asks you for help.

Before running or writing queries, a user must have access to records through Query Security Trees. We assign records to trees, trees to permission lists, permission lists to roles, and roles to users. The solution is trivial: grant security access through a security tree. The difficult part is deciding which tree and which permission list. When I receive a request like this, I have two groups of questions:

1. Is there already a query security tree that grants access to the target record? If so, which one and which permission lists? Would any of those permission lists be appropriate for this user?
2. Is there already a query security tree available to this user that would be a good fit for this record?

Here are some SQL statements I created to help answer these questions.

Find existing trees that include the target record:

Finding Permission Lists that grant access to a specific record is more challenging. Locating permission lists that contain a tree that contains a record is trivial. Narrowing that list based on Access Group is more challenging because Access Groups represent node hierarchies and therefore require recursive logic:

Do you have SQL statements and tricks to help you manage Query Security? If so, share them in the comments!

At JSMpros, we teach PeopleTools tips like this every week. Check out our website to see what we are offering next!

It's a wrap! Blueprint 4D 2022 PeopleTools Recap

We just finished the fantastic Blueprint 4D conference, full of great sessions and incredible networking. It is always a pleasure to meet our JSMpros student alumni and connect with members of the PeopleSoft community.

The conference started with a great lineup from Product Strategy, including Paco sharing a broad perspective of what to expect in future PeopleSoft applications, and then focused strategy breakout sessions. It is very clear PeopleSoft is still a top-tier ERP solution. If you are a PeopleSoft developer, here are some things to watch in future releases:

• New theme for PeopleTools 8.60. We've been watching the steady transition to the Oracle Redwood theme, and it appears the transition is complete.
• Global Search is visible all the time, not just on homepages. To make room, PeopleSoft moved the page title down a row, in line with the component header.
• Recent and favorite icons from the 8.59 homepage move up to the left side of the header. To make room, the back button is collapsed to an image.
• The global actions header is now detached from an optional component-specific header. While the proliferation of dot-dot-dot menus may seem confusing, I'm pleased with the change as it is now visibly clear if a component has custom actions.
• Configurable search is coming! Configurable search appears to be based on keyword search, which is a viable option if real-time indexing is enabled. Configurable search will be available for both Classic and Fluid. In summary, configurable search lets you configure search fields and list box items, rather than relying exclusively on search record metadata. Besides Configurable Search, using keyword search (Elastic at this time) also allows you to search for transactions from the global search bar, and the global search bar will show transaction search suggestions from your keyword search history.
• Fluid is getting SQL Search. My interpretation of this new feature is that Fluid will finally leverage search record metadata to build search pages for us just like Classic. This will be a great time saver since current Fluid search strategies include Pivot Grids, Elastic Search, custom search pages, and custom components.
• PeopleSoft will transition from Elastic Search to OpenSearch to be consistent with Oracle Cloud. No mention of the impact on Kibana. The timing for this is unknown as the 8.60 planned release will use ELK 7.10. Regardless, the change should be transparent as our users use the PeopleSoft search framework, not Elastic directly. Elastic changed the license with 7.11, which is why Oracle is staying with 7.10 for now, and will migrate to OpenSearch, which is based on ELK 7.10. Oracle encourages to continue creating Kibana dashboards, building indexes, etc as the change should be transparent.
• Future releases of Cloud Manager should support using Data Science to automatically scale up and down based on load and customer-configured thresholds.
• CSS custom properties (variables) will replace branding macros. I am very excited about this. We just released a YouTube video showing how to apply a hover effect to rows through CSS. As of 8.59, we must hardcode the hover color, border, etc. In the video, I specifically stated these colors are different than 8.57 and earlier, and hard-coded colors could present a maintenance challenge. If we can leverage PeopleSoft CSS variables, we may be able to reduce future maintenance. With each release, we still expect variable changes (new variables, etc.) just as prior releases brought new Branding Macros, but finding and updating the list with future additions should be trivial with a text compare tool.

Campus Solutions

• PI 24 delivered Drop Zones to the following three components: Personal Details, Biographic Details, and Emergency Contacts. This is fantastic as it allows us to collect additional information about students without customizing the Oracle-delivered pages.
• Future Fluid components will include Drop Zones and CAF.
• 2023 planned Fluid releases include Transfer Credit, Degree Progress, Research Activities, and Program Enrollment.
• Roadmap items include Integration with Student Management Cloud and Student Financial Planning (cloud)
• Continued WCAG 2.1 enhancements.
• Continued Classic Plus conversions.

Notes from Sasank's 8.59 PeopleTools session

• Search: suggestions show history, corporate history, and the menu.
• For your history and corporate history to appear in the list, you must enable the following indexes: PTSF_RECENT_KW and PTSF_RECENT_MENU
• For your recent history to appear, you should also enable real-time indexing.

PeopleTools Platforms Roadmap

We could summarize the 8.60 platforms roadmap by stating that PeopleSoft has or will certify on platforms supported by the vendors of those platforms at the time of release. For example, 8.60 drops support for Windows Server 2016. A more accurate way to state that is Microsoft dropped support for Windows Server 2016, making it no longer supported by Oracle. Likewise, IE11 is missing from the browser certification matrix. Given the Oracle OpenSearch announcement made by Dave Bain. It was interesting to note PT 8.60 will release with Elastic 7.10, Kibana 7.10, Logstash 7.10. The 7.10 release predates the ELK 7.11 license change. Mark assured us ELK's support policy and end of service dates are irrelevant because Oracle maintains their own version of ELK with their own patches and their own support. In that sense, you might say we are already on Oracle OpenSearch as OpenSearch is a fork of ELK 7.10.

On another interesting note, PeopleTools 8.60 adds Excel from the Office 365 suite to the list of supported Excel versions. As Mark noted, however, this is not necessarily a product/version certification, but a license model, as Office 365 is not a version, it is a subscription license. This could be interesting as Office 365 is always current and doesn't necessarily follow numbered release versions.

Cloud Manager 14 Highlights

• Data Science for Auto Scaling: Automatically scale up nodes on increased load. Uses Health center to identify anomolies for scaling.
• Support for custom domain names to Cloud Manager.

Page and Field Configurator Planned Features

• Allow page changes dynamically as the user updates information in response to FieldChange events.
• Use system variables as criteria (date, time, etc.).
• Streamline selection of fields for the administrator.
• Track changes made by users to pages (change tracker). This will be field and role-based and will store before and after values. Users will be able to view change history through related content associated with the transaction. Page and Field Configurator configuration component will have a button to activate the Related Content on the target component for you. This related content will work with both Classic and Fluid. Note: This does not replace PeopleTools Audit Tables.
• Page and Field Configurator will track views of sensitive information, logging each time a user accesses that sensitive information. By the way, this is a common feature of the Pathlock/Appsian Security Platform, usually implemented through click-to-view.
• Changes coming for search pages: ability to change labels and apply default values.

And finally, as the conference wrapped up, Oracle completed its acquisition of Cerner. I'm expecting to hear more announcements at the HIUG Interact conference next week!

Thank you to everyone that shared at Blueprint 4D! Be sure to mark your calendars for May 8-11 for the 2023 Blueprint 4D conference!

At JSMpros, we lead PeopleTools training using the latest releases and up to date curriculum. Be sure to check out our website to see what we are offering next!

Where is that Content Reference?

New user 'X' needs access to 'Y.' Piece of cake, right? At least it was in Classic. The entire PeopleSoft navigation model stems from Content References. The classic "Navigator" and bread-crumb menus rendered the "Structure and Content" hierarchy. Finding content references under the classic model was trivial because the online visual rendering matched the "Structure and Content" portal registry hierarchical model. After finding a Content Reference, we could review the menu/component combination as well as existing permission lists to derive a solution.

What about Fluid? Most Fluid components exist somewhere in "Structure and Content." The question is, "Where?" The Fluid navigation model consists of homepages, dashboards, tiles, navigation collections, activity guides, and WorkCenters. And we can add any Content Reference to any one of these definitions. There is no structure. We use two tools to help us find Content References:

1. Enterprise Components > Find Object Navigation
2. SQL

If you know the menu/component combination or the CREF ID, you can look up the path using Enterprise Components > Find Object navigation. This is very helpful.

Unfortunately, many Fluid content references share the same component, a framework component such as PT_FLDASHBOARD or PT_AGSTARTPAGE_NUI. Everyone has access to these components. Let's consider the Personal Details tile on the HCM Employee Self-Service homepage. The menu/component combination is exactly the same as Payroll. Both use a framework component. What differentiates one tile from the next is the additional URL parameters. So we put together a SQL statement to help us locate content references by URL fragment. The following SQL is Oracle-specific. Notice the URL in the WHERE clause. Replace that URL with your own. Since this SQL uses regular expressions to filter CLOB data, be sure to regex escape special characters.

There is one other way to find a CREF ID. If the target is a Fluid Dashboard, then you may visit PeopleTools > Portal > Dashboards > Manage Dashboard Pages. The properties link shows both the parent folder and the dashboard's CREF ID.

Are you interested in learning more about PeopleSoft Fluid administration and development? Check out our website for live virtual and on-demand recorded PeopleSoft Fluid training.

The "Unable to get image extents" Error for SVGs

At JSMpros, we love Scalable Vector Graphics! Fluid loves them because they resize (scale) well. We love them because they are just XML documents describing an image. And since they are XML, we can recolor them with browser developer tools or even a simple text editor. In fact, We have videos showing how trivial it is to clone and alter the colors of Oracle-delivered Fluid icons through browser inspector tools (watch online Manipulating SVG Images).

Since we usually just change colors, we prefer to edit Oracle-delivered SVG images through Chrome's inspector and then copy the entire document to a new SVG file. We can then upload the new file through App Designer and use it anywhere. But we discovered an interesting issue. It appears PeopleSoft's internal code doesn't like our new images. When using the Navigation Collections image inspector or uploading a modified SVG through the online branding module, PeopleSoft throws an "Unable to get image extents" error message. What we didn't realize is that copying XML out of Chrome's inspector doesn't copy the XML prolog. All XML documents begin with an XML prolog

<?xml version="1.0" encoding="utf-8"?>

Since SVG is XML, it is required to have a prolog. Browsers are forgiving and will ignore the missing prolog, but PeopleSoft's internal code doesn't.

So what's the solution? We still edit SVG using Chrome's inspector tool, but now we manually insert the XML prolog as the first line. It appears we aren't the only ones to hit this issue. Check out MOS document 2426154.1 for more details.

Are you interested in learning more about PeopleSoft Fluid and Fluid development? Check out our latest live virtual and on-demand offerings.

Live Three-day Fluid Training Event in Seattle Dec 4

Are you interested in learning PeopleTools Fluid? Have you already taken a Fluid training course, but still don't feel comfortable with Fluid? Please join us in beautiful downtown Seattle from December 4th through the 6th to learn all about PeopleTools Fluid. Our curriculum starts with Fluid navigation, works its way into Fluid page construction, and finishes with advanced topics such as site-specific CSS3, JavaScript, and event mapping. This course is packed with best practices and tips.

Through the material in this course you will become comfortable with Fluid and proficient with Fluid development. You will learn the skills necessary to apply PeopleSoft-specific CSS and how to write your own custom CSS. You will learn several shortcuts for converting existing custom Classic pages to Fluid.

With most of HCM Employee Self Service Classic set to retire on December 31st of this year (MyOracle Support document 1348959.1), there is no better time to learn Fluid. Space is limited and the early bird discount expires soon so Register now to ensure a seat in the best Fluid class available!

Export PeopleSoft Attachments using PL/SQL

Oracle provides PeopleTools developers with the ability to store files with transactions using the File Attachment API. Likewise, the File Attachment API includes PeopleCode functions for extracting and displaying attachments. What if you need to export attachments directly from a database or from SQR where you don't have access to the File Attachment PeopleCode functions? Here is some PL/SQL demonstrating how to export attachments. You just need to set the file name and the attachment record name. I labeled the values you need to change with TODO:. Code for other databases should be relatively similar.

CREATE OR REPLACE DIRECTORY TEMP_DIR AS 'c:\temp'
/

DECLARE
  -- Max PS attachment chunk size is 28000
  CV_BUFFER_MAX    NUMBER        := 28000;

  -- Name of file to export. This is the name that was used to store the file
  -- and is the name that will be used to create a new file.
  -- TODO: change the name to match the name of your exported file
  lv_file_name     VARCHAR2(128) := 'theattachedfile.xls';
  lv_buffer        RAW(28000);

  lv_file_ref      utl_file.file_type;
  
BEGIN
  lv_file_ref := utl_file.fopen('TEMP_DIR', lv_file_name, 'WB');

  FOR r_chunks IN
      (SELECT FILE_DATA
            , FILE_SIZE
     -- TODO: Change record to the name of your attachment record
         FROM PSFILE_ATTDET
        WHERE ATTACHSYSFILENAME = lv_file_name) LOOP

    dbms_lob.read(r_chunks.FILE_DATA, r_chunks.FILE_SIZE, 1, lv_buffer);
    utl_file.put_raw(lv_file_ref, lv_buffer, true);
  END LOOP;

  utl_file.fclose(lv_file_ref);

  EXCEPTION
    WHEN OTHERS THEN
    -- Close the file if something goes wrong.
      IF UTL_FILE.is_open(lv_file_ref) THEN
        UTL_FILE.fclose(lv_file_ref);
      END IF;
    RAISE;
END;
/

You will notice that this code exports an attachment to the database server's file system.

How do you find file attachment records? The easiest way I can think of is to query the PSRECFIELD table for all record definitions that contain the FILE_ATTDET_SBR sub record. Here is the SQL:

SELECT *
  FROM PSRECFIELD
 WHERE FIELDNAME = 'FILE_ATTDET_SBR'

AppEngine Output Tricks, Reporting, Logging, Etc

Reporting

When I took the AppEngine course several years ago, my instructor made sure his students knew that AppEngine was a batch processing tool, not a reporting tool, unlike SQR, which could do both. At that time, PeopleSoft offered Crystal Reports, PS/nVision, PS Query, and SQR as reporting options, and he encouraged us to use those tools for reporting. AppEngine was strictly labeled a batch processing tool. While debugging some jobs containing AppEngines (dunning letters, training letters, etc), I noticed that these AppEngines created and/or read files from the process output directory. Looking at the process monitor, I knew that those same files were available from the View Log/Trace link on the process details page. This got me thinking... if I could create a Microsoft Word file from AppEngine, I could place it in that process output directory and not have to run the WINWORD process on a headless server. Now, the trick, creating a Microsoft Word file from an AppEngine... Here are a couple of options

• Word HTML format
• Word XML format
• RTF

By using various methods, I can convert my mail merge source data into XML format and transform it into either of these three Microsoft Word recognized formats using XSL. Of course, as of PeopleTools 8.48, we can use XMLPublisher to generate the same result. Nevertheless, if you need to process your data prior to generating a report, then a multi-step AppEngine reporting solution might be easier for you to manage than a multi-step job.

The same options are available for creating Microsoft Excel and OpenOffice documents. If you want to create Microsoft Excel binary files from AppEngine, then you can use Apache's POI Java libraries from PeopleCode. If you are interested in creating OpenOffice documents, you can generate the appropriate XML files, and then use Java to zip them into a single file. In fact, you could use this same approach to generate OpenOffice Impress presentations or Microsoft PowerPoint 2007 presentations.

For reporting, why choose AppEngine over SQR? AppEngine components (PeopleCode, SQL, etc) are managed objects. PeopleTools managed objects participate in the change management features available in PeopleTools. SQR text files do not.

Can I create a PDF from an AppEngine? Yes. Using an XSL-FO processor, you can trasform XML into PDF using a user defined XSL template. Likewise, you can use one of the PDF Java libraries to print text to a PDF file using PeopleCode similar to the way you would print output to a PDF in SQR, but with rich text features. Other reporting options: Any reporting/output tool that has a Java API can be called from AppEngine PeopleCode. For example, JasperReports, BIRT, JFreeReport, FOP, etc.

File Output Location

Suppose I want to create a file (printable report, log file, etc), where should I create the file? If you want the file available from the View Log/Trace link, then use the following SQL to determine the process's output directory:

SELECT PRCSOUTPUTDIR FROM PSPRCSPARMS WHERE PRCSINSTANCE = %ProcessInstance

Logging

I've already mentioned using log4j from PeopleCode. You can read about that in my posts: Logging PeopleCode Using log4j to debug applications and log4j and PeopleCode Part II. Other options include the Peoplecode MessageBox function, the PeopleCode File object, and the Java System.out/System.err methods. I prefer the Java System output methods over the PeopleCode MessageBox function because Java gives me complete control over the output. Unfortunately, you can't call the Java System output methods directly because the PrintStream output methods are overloaded. Instead, we need to use reflection to call the print methods. Here are some functions you can place in a FUNCLIB that allow you to print to stdout and stderr from PeopleCode:

/*
 * Print a line of text to stdout
 */
Function println_to_stdout(&message As string)
   Local JavaObject &jSystem = GetJavaClass("java.lang.System");
   Local JavaObject &jOutStream = &jSystem.out;
   Local JavaObject &jCls = GetJavaClass("java.lang.Class");
   Local JavaObject &jStringClass = &jCls.forName("java.lang.String");
   Local JavaObject &jPrintStreamCls = &jOutStream.getClass();
   Local JavaObject &jPrintlnArgTypes = CreateJavaObject("java.lang.Class[]", &jStringClass);
   
   Local JavaObject &jPrintlnMethod = &jPrintStreamCls.getDeclaredMethod("println", &jPrintlnArgTypes);
   
   &jPrintlnMethod.invoke(&jOutStream, CreateJavaObject("java.lang.Object[]", &message));
   rem ** I didn't find flushing necessary, but here is where you would flush the buffer if desired;
   rem &jOutStream.flush();
End-Function;

/*
 * Print a line of text to stderr
 */
Function println_to_stderr(&message As string)
   Local JavaObject &jSystem = GetJavaClass("java.lang.System");
   Local JavaObject &jOutStream = &jSystem.err;
   Local JavaObject &jCls = GetJavaClass("java.lang.Class");
   Local JavaObject &jStringClass = &jCls.forName("java.lang.String");
   Local JavaObject &jPrintStreamCls = &jOutStream.getClass();
   Local JavaObject &jPrintlnArgTypes = CreateJavaObject("java.lang.Class[]", &jStringClass);
   
   Local JavaObject &jPrintlnMethod = &jPrintStreamCls.getDeclaredMethod("println", &jPrintlnArgTypes);
   
   &jPrintlnMethod.invoke(&jOutStream, CreateJavaObject("java.lang.Object[]", &message));
   rem ** I didn't find flushing necessary, but here is where you would flush the buffer if desired;
   rem &jOutStream.flush();
End-Function;

If you want to use the PrintStream.print method instead of the println method, copy the code above, rename the function, and change the &jPrintlnMethod assignment from "println" to "print".

If you've worked with Java, then you know that you can redirect stdout and stderr to another PrintStream. For example, you can redirect stdout to a file or a network socket connection. Here is some code demonstrating how to redirect stdout and stderr to a different file:

/*
 * Redirect stdout to file
 */
Function redirect_stdout(&fileName as string)
   Local JavaObject &jSystem = GetJavaClass("java.lang.System");
   Local JavaObject &jfos_out = CreateJavaObject("java.io.FileOutputStream", &fileName, True);
   Local JavaObject &jps_out = CreateJavaObject("java.io.PrintStream", &jfos_out, True);
   &jSystem.setOut(&jps_out);
End-Function;

/*
 * Redirect stderr to file
 */
Function redirect_stderr(&fileName as string)
   Local JavaObject &jSystem = GetJavaClass("java.lang.System");
   Local JavaObject &jfos_out = CreateJavaObject("java.io.FileOutputStream", &fileName, True);
   Local JavaObject &jps_out = CreateJavaObject("java.io.PrintStream", &jfos_out, True);
   &jSystem.setErr(&jps_out);
End-Function;

By redirecting stdout and stderr, you could actually create 3 separate output files without using the File object. The benefit of using a redirected stdout over a File object is that you can setup your stdout location in one step of your program and write to that same file from anywhere else in the program without having to open/close a File object on every step.

The App Server

Just a side note: Many of the techniques demonstrated in this post can be used online. Using System.out.println, you could print to the app server's stdout file. Likewise, the reporting solutions above could be used from an online PeopleCode event to generate reports online.

Keep the Last Visited Homepage Tab Active

If you have used PeopleSoft's Enterprise Portal, then you may have noticed that the active homepage tab is only active when you are viewing that specific homepage tab and that none of the homepage tabs are active when you navigate away from a homepage. As a new PeopleSoft user, I didn't understand why none of the tabs were active once I navigated away from a homepage. To me, it seemed that keeping the last visited homepage tab visibly differentiated as the active tab helped me know what portion of the application I was using after I left a homepage. For example, if I was creating a purchase requisition, then I wanted the Procurement tab to stay active. Likewise, if I was modifying a branding header, then I wanted the Administration tab to stay active. As I continued to work with the PeopleSoft applications, however, I realized that my active tab navigation paradigm didn't make sense given the fact that all the pages inside my PeopleSoft Enterprise Portal displayed the same Enterprise Menu. Because the Enterprise Menu exists on every page, it would be possible for someone to start on a Manager Self Service tab, initiate an employee transfer, and then use the Enterprise Menu to navigate to the purchase requisition component, a business process better aligned with the Procurement tab. In this scenario, the active tab would still be Manager Self Service even though the user is entering a purchase requisition.

At Collaborate '08, a customer asked me, "How do you keep the active tab active after you navigate away from a homepage?" Since I had been through this thought process myself, I answered him with the explanation above. Nevertheless, because PeopleSoft is so flexible, it is possible for you to implement your Enterprise Portal in a manner that separates Procurement content from Manager Self Service content. For example, you could change the default content reference template from DEFAULT_TEMPLATE to MY_CUSTOM_MENU_TEMPLATE and use a custom menu implementation that shows content targeted to the active tab. If you implemented PeopleSoft's Enterprise portal in this manner or if keeping the last visited tab active just makes sense to you, then here is the code to help you keep that last visited tab active. You will need to add this code to the HTMLProcess method of the HTMLProcess class contained in the EPPBR_BRANDING Application Package (the constructor of the EPPBR_BRANDING:HTMLProcess application class). I included seven lines above the modification and seven lines below the modification to help you find the correct place to add this code (14 lines of context). The code you need to add is the 6 lines in bold below between the 7 lines of delivered code.

   ...
   &strRefreshHomePage = "";
   &strContentHref = "";
   &strLayoutHref = "";
   &dEffdt = %Date;
   /* override effdt is for editing only, the value should be set when called from configuring site overrides */
   &OverrideEffdt = &dEffdt;
   &strActiveTab = &Request.GetParameter("tab");

   REM ** BEGIN ABC_123456; me@mycompany.com; 14-MAY-2008; keep last active tab active;
   Local string &tempActiveTab = &strActiveTab;
   If (None(&tempActiveTab)) Then
      &strActiveTab = %HPTabName;
   End-If;
   REM ** END ABC_123456; me@mycompany.com; 14-MAY-2008; keep last active tab active;

   If &strLocation = "M" Then
      &strHdrFtrType = "P";
   Else
      &strHdrFtrType = &strLocation;
   End-If;
   
   If &strLocation = "P" And
   ...

As you can see from the 7 lines preceding the modification, the delivered behavior is to determine the active tab from the tab query string parameter that exists on homepage URL's. The reason the active tab doesn't stay active when you navigate to content surfaced through your Enterprise Portal is because the tab query string parameter doesn't exist on those other pieces of content. To work around this, we can use the %HPTabName system variable to determine the most recently active tab.

If you make this change, you will be modifying code delivered by Oracle. If you document your modification, then you should be able to carry this modification through bundles and upgrades with little impact. The key to a successful modification is documentation. By documentation I mean, you include this modified PeopleCode in a project and you document the PeopleCode change within the PeopleCode object. At bundle/upgrade time, your compare reports will show the PeopleCode changes line by line. If you documented the start and end of your modification with a PeopleCode comment and include a site specific identifier in that comment, then it should be easy for you to find that modification and reapply it. For example, in the code above, I use ABC_123456 as my site specific identifier. The ABC portion identifies the code as created by my company, not Oracle, and the 123456 portion is the modification specific identifier used by me to track this specific modification.

%HPTabName uses a cookie to determine the active tab if the URL does not contain a tab query string parameter. If a user enters the PeopleSoft application through a link from a workflow e-mail, then that user will see an active tab matching the last tab visited, which may or may not be relevant for the URL specified in the workflow e-mail. Likewise, if the user cleared his or her cookies, then that user would not have an active tab. You could work around this limitation by creating your own method for tracking and setting the active tab. For example, if the target is not a homepage (no tab query string parameter and/or the presence of /h/ in the URL), then, using PeopleCode functions and system variables, you could determine the node that provides the target content and change the active tab accordingly. Another idea would be to set a default tab attribute on every relevant content reference and use that attribute to determine which tab should be the active tab for the target URL.

Simplify HTML Pagelet Migration with a Custom Transformer

Generally speaking, IT organizations like to keep development code separate from production code. When development code is ready for production, good change management rules dictate a graduation/migration path, usually something like DEV > TEST > QA > PRO. Likewise, on occasion, a development team may request a fresh copy of a production database. With PeopleTools managed objects, we can easily migrate Application Designer projects between our environments without much concern for environment specific code. Pagelet Wizard created pagelets, however, are not managed objects and need to be migrated using Data Mover Scripts. Some pagelets, like Query pagelets, require managed objects in order to function. Other pagelets, like HTML pagelets may contain hard coded URL references to other DEV/TEST/QA/PRO servers. How can we effectively manage these URL's? Can we, as PeopleSoft developers, automate the process for updating these URL's?

As we know from experience, HTML data sources typically use the Passthru display format. Passthru means the HTML content from step 2 is displayed in the Pagelet without any processing or modification. Therefore, we can't leverage Meta-HTML or any other PeopleTools functionality to simplify the management of our HTML based pagelet. We can, however, create a new transformer and display type and have this new transformer perform additional processing to help us resolve this URL maintenance problem.

Now that we have a method for implementing additional processing, how shall we maintain the actual URL's? I recommend using node definitions. Node definitions contain a portal tab where we can enter a content and a portal URL. As delivered, PeopleTools uses these node URL's when creating real URL's from portal registry content references (CREF's). Using a custom transformer, we can leverage this existing Meta-data to dynamically generate the URL's included in HTML Pagelets.

What we need is a custom Transformer that can convert a URL placeholder into a full URL using database driven Meta-data. Keeping with PeopleTools convention, the solution below will demonstrate the creation of a transformer that resolves custom Meta-HTML tags. This custom transformer will expand the text %NodePortalURL(NODE_NAME) into the Portal URL for that node. This will allow us to write Pagelet Wizard HTML like:

<img src="%NodePortalURL(NODE_NAME)/images/dynamic-chart.png"/>

And our custom transformer will translate this HTML into:

<img src="http://other.server.name:8080/images/dynamic-chart.png"/>

To implement this solution we need an Application Package to store our custom App Class. For demonstration purposes, we will call this Application Package CUSTOM_TRANSFORMERS. I expect in your environment, you will prefix this new Application Package with your site specific prefix. In this new Application Package, we will add a new package called Transform. And, to this new package, we will add the class NodePortalUrlTransformer. This new class, NodePortalUrlTransformer will contain the code required to implement our URL transformation feature. The path for our new Application Class should look something like CUSTOM_TRANSFORMERS:Transform:NodePortalUrlTransformer. Here is the code you will need to paste into this new Application Class:

import PTPPB_PAGELET:UTILITY:*;
import PTPPB_PAGELET:Transformer:*;
import PTPPB_PAGELET:*;

/**
  * Transforms Text by replacing %NodePortalURL(NODE_NAME) with the Portal URI
  *   of the node NODE_NAME.
  */
class NodePortalUrlTransformer extends PTPPB_PAGELET:Transformer:Transformer
   method NodePortalUrlTransformer(&ID_param As string);
   method execute(&pageletID As string) Returns string;
   method Clone() Returns PTPPB_PAGELET:Transformer:Transformer;
end-class;

/** 
  * Constructor.
  *
  * @param id_param ID of this object.  Should be unique.
  */
method NodePortalUrlTransformer
   /+ &ID_param as String +/
   %Super = create PTPPB_PAGELET:Transformer:Transformer(&ID_param);
end-method;

/**
  * Replaces%NodePortalURL(NODE_NAME) with the Portal URI
  *   of the node NODE_NAME.
  *
  * @param pageletID ID of the pagelet being executed.
  */
method execute
   /+ &pageletID as String +/
   /+ Returns String +/
   /+ Extends/implements PTPPB_PAGELET:Transformer:Transformer.execute +/
   Local JavaObject &pattern;
   Local JavaObject &matcher;
   Local string &sourceText = %This.DataToTransform.Value;
   Local string &transformedText = &sourceText;
   Local string &nodeName;
   Local string &nodeUrl;
   
   REM ** Resolve %NodePortalURL tags;
   &pattern = GetJavaClass("java.util.regex.Pattern").compile("(?i)%NodePortalURL\((\w+)\)");
   &matcher = &pattern.matcher(CreateJavaObject("java.lang.String", &sourceText));
   While &matcher.find()
      &nodeName = &matcher.group(1);
      If (&nodeName = "LOCAL_NODE") Then
         &nodeName = %Node;
      End-If;
      SQLExec(SQL.GET_NODE_URI, &nodeName, "PL", &nodeUrl);
      &transformedText = Substitute(&transformedText, &matcher.group(), &nodeUrl);
   End-While;
   &pattern = Null;
   Return &transformedText;
end-method;

/**
  * Make an exact copy of this object.
  *
  * @return Text Exact copy of this object
  */
method Clone
   /+ Returns PTPPB_PAGELET:Transformer:Transformer +/
   /+ Extends/implements PTPPB_PAGELET:Transformer:Transformer.Clone +/
   Return create CUSTOM_TRANSFORMERS:Transform:NodePortalUrlTransformer(%This.ID);
end-method;

Keeping with good PeopleTools coding practices, the code above references a managed SQL object named GET_NODE_URI. Here is the SQL for that SQL definition:

SELECT URI_TEXT 
  FROM PSNODEURITEXT 
 WHERE MSGNODENAME = :1 
   AND URI_TYPE = :2

Now that we have our code in place, we need to register our new Transformer so we can use it in our HTML pagelets. Rich Manalang wrote up an excellent transformer tutorial following the same steps, but his includes pictures. You can find a link to his tutorial below.

We will start by registering the Transform Type. Navigate to:

Portal Administration > Pagelets > Pagelet Wizard > Define Transform Types > Add

On this page, you will need to give your Transform Type a name, a description, and specify the implementing Application Class. If you have been following this example, then use the following values:

Transformation Type: NODE_PORTAL_URL
Description: Resolve Node URL Meta-HTML
Package Name: CUSTOM_TRANSFORMERS
Path: Transform
Application Class ID: NodePortalUrlTransformer

Next, you will need to define a Display Format that corresponds to your new Transform Type. Navigate to:

Portal Administration > Pagelets > Pagelet Wizard > Define Display Formats > Add

You can use the following values to define your new display format. Again, the Define Display Formats graphic on Rich's post applies. In fact, the only values you need to change are the Display Format ID, Description, and Transform Type. For reference, I've repeated the values below:

Display Format ID: NODE_PORTAL_URL
Description: Resolve Node URL Meta-HTML
Transform Type: NODE_PORTAL_URL
Page Name: PTPPB_WIZ_DISP_PST
Package Name: PTPPB_PAGELET
Path: TransformBuilder
Application Class ID: PassthroughBuilder

The last step is to associate our new Display Format with the HTML Data Type. Navigate to:

Portal Administration > Pagelets > Pagelet Wizard > Define Data Types

Select the HTML Data Type. At the bottom of this page, in the section titled Display Formats to use with this Data Type, we need to add our new Display Format: NODE_PORTAL_URL. After you save, your configuration and development for your new transformer is complete. You may now use this new Meta-HTML character sequence in your Pagelet Wizard HTML Pagelets.

The Enterprise Portal's Pagelet Wizard is one of my favorite productivity and usability tools. One of it's key features is its extensibility. The Pagelet Wizard contains components that allow you to register your own data sources, display types, and transformations. Likewise, the Internet Technology PeopleBook contains a section devoted to Pagelet Wizard configuration, customization, and usage. If you prefer examples over PeopleBooks, you can open and view the delivered Pagelet Wizard Application Packages in Application Designer. If you are interested in creating your own data source, tranformer, or display type, you may find a delivered Application Class you can copy and modify.

Additional resources:

• Enterprise PeopleTools 8.49 PeopleBook: Internet Technology > Using Pagelet Wizard
• Rich Manalang's post Markdown Text Filtering for PeopleSoft

PIA_KEYSTRUCT JavaScript Object

I was just looking at the JavaScript that PeopleSoft includes in each PIA page and noticed a JavaScript object I have not seen before: the PIA_KEYSTRUCT object. It looks like this object contains key/value pairs for each level 0 search key, primary and alternate. What can you do with this? I'm not sure yet. I've been thinking about it for a couple of weeks. My two main questions:

1. Can I use this to create new developer tools (bookmarklets, etc)?
2. Can I use this to empower users?

For now, the only example I can show you is how to open a query and pass in the PIA_KEYSTRUCT values as query bind parameters. This example passes the Role Administration component's ROLENAME key to a delivered query that displays the role's permission lists. Here is the JavaScript:

window.open("/psc/portal/EMPLOYEE/EMPL/q/?ICAction=ICQryNameURL=PUBLIC.PT_SEC_ROLE_CLASS&BIND1=" + escape(frames['TargetContent'].PIA_KEYSTRUCT.ROLENAME))

In the example above, I navigated to PeopleTools > Security > Permissions & Roles > Roles and ran this JavaScript in the Firebug console. Here is a bookmarklet that will do the same thing: Role's Permission Lists. To test this bookmarklet, right click the link and save it as a favorite/bookmark, navigate to your Role administration page, select a role, then activate your new favorite/bookmark. One of the great features about bookmarklets is that they can be added to your browser's links toolbar to "extend" the functionality of your browser. Unfortunately, this particular example is page specific. This particular bookmarklet and code will only work if you are on the PeopleTools Role administration page. Furthermore, you can provide the same functionality by combining PeopleCode with JavaScript in an HTML area or, even better, using a Pushbutton/Hyperlink on a PIA page with full access to the level 0 search keys (in other words, this is a great pedagogical example with little practical value).

Really, as developers, can we obtain practical value from this little piece of JavaScript that the PeopleTools developers generously provided for us? I think so. Here are a couple of ways I think we can leverage this piece of JavaScript:

• Enhance the Ctrl-J page by adding the level 0 search keys
• Simplify the Pagelet Wizard link creation process

The Power of Meta-Data

In my last post, What is a WEBLIB, I said that WEBLIB_QUERY was in permission list PTPT1000. How did I know that? I queried the PeopleTools tables. PeopleTools tables are tables in your database prefixed with PS, but no underscore. As you know, generally speaking, all Application Designer created records are prefixed with PS_. Most of the PeopleTools record names, however, don't contain underscores. If you haven't done so, I encourage you to take some time to get to know your PeopleTools tables. You can find a good reference on the PSST0101 site. With a good understanding of the PeopleTools tables, you can write queries and tools to help you significantly reduce your PeopleSoft administration overhead. Combining your knowledge of the PeopleTools tables with IScripts and Web development methods, you can create Bookmarklets that generate security and/or development/meta-data reports for components, etc.

Meta-data is one of PeopleSoft's differentiating factors. Many vendors provide meta-data in configuration files, but because a meta-data driven development architecture requires extra thought, most ERP vendors drop meta-data in favor of rapid, hard-coded values. Because PeopleSoft stores meta-data in the database, you, as a developer, user, and administrator, can extend PeopleSoft by writing your own tools that leverage existing meta-data.

Caveat: Please don't update the PeopleTools Meta-Data tables directly, unless, of course, told to do so by GSC or some other trustworthy Oracle/PeopleSoft expert.

Google Gadgets for your PeopleSoft Enterpise Portal

Have you tried using the Pagelet Wizard's HTML data source to add Google Gadgets to your PeopleSoft Homepage? If not, browse through the Google Gadgets directory and select one you like. After customizing your Gadget, click the "Get the Code" button. Notice the code is an HTML script tag. Copy this code and paste it into the HTML editor of a new Pagelet Wizard HTML data source pagelet. Publish, save and add your new pagelet to your homepage. Did you notice anything unusual... like... the Gadget appeared at the top of the homepage, not within the pagelet's designated area? If you look at the source code for your homepage from within your browser, you will notice that the script tag you copied is actually in the homepage's head element, not in the body. This behavior is the result of the way the PeopleTools portal constructs the homepage. For each pagelet on the homepage, the portal retrieves the pagelet's source and reviews it prior to inserting it into the homepage. If the pagelet's source contains a full HTML document (with HTML element, head, and body), then the portal will insert the components of the head tag into the homepage's head tag. For example, if the pagelet's head tag contains style definitions, those style definitions will be inserted into the head tag of the home page. Likewise, if the pagelet's source is not a full HTML document, but contains script, link, or style elements at the root, or top level, then those elements will be inserted into the head tag of the homepage. This behavior is by design. It allows pagelet designers to embed script and style definitions into the head element of pagelet HTML documents, the only valid place for sytle definitions.

To work around the homepage construction issue, wrap the HTML provided by Google inside a <div> tag. This will keep the portal from moving the script element. I use the following HTML to center the gadget within the Pagelet's defined box. Adjust the width to match the width of your Google Gadget plus a pixel or two.

<div style="margin-left: auto; margin-right: auto; width: 325px;">Google script...<div>

Here are some Google Gadgets you will find on my PeopleSoft homepage Google Calendar, Google Talk, and Google News.

Branding Component/Page Tabs

You can find documentation on Customer Connection about branding homepage tabs in Enterprise Portal. But, what about changing the tabs that separate pages in a multi-page component? If you've been through a few PeopleTools upgrades, you've noticed that PeopleSoft occasionally changes the tab colors and tab design, so it must be possible... right? If you save one of those tab images, you will notice that tab images follow a naming convention. Component tabs are called level 2 tabs and are prefixed with PT_TAB2. You will also notice that App Designer contains PT_TAB3 images. I'm not sure where these are used.

Component tabs are comprised of 7 images, all of them ending in a hexidecimal color. The seven images are

• PT_TAB2BAIBBBBBBCCCCCC
• PT_TAB2BIABBBBBBCCCCCC
• PT_TAB2BIIBBBBBB
• PT_TAB2LAXCCCCCC
• PT_TAB2LIXBBBBBB
• PT_TAB2RAXCCCCCC
• PT_TAB2RIXBBBBBB

BBBBBB represents the hexadecimal inactive tab background color and CCCCCC represents the hexadecimal active tab background color. If you haven't changed your default stylesheet, then PTSTYLEDEF_DARKBLUE contains the definition for your active and inactive tab colors. The style classes are PSACTIVETAB and PSINACTIVETAB. If you change the background color of either of these classes, then be sure you have all 7 new images in your database with matching color names. If you don't then your app server session will crash. It appears that the C++ code on the app server determines which image to choose based on the background colors of PSACTIVETAB and PSINACTIVETAB (hence the naming convention). Note also that the images with AI and IA prefixes list the inactive color before the active color.

Level 3 tabs follow the same conventions as level 2 tabs except for the addition of the PT_TAB3MIXBBBBBB image which represents the middle of 2 inactive tabs.

If you choose to change your tab colors to something that isn't delivered, be sure to upload all 15 images (level 2 and level 3). Otherwise, your app server session will crash each time you navigate to a component.

Update Tuesday, March 4^th, 2008

While finishing up a branding project, I noticed that the 2 in PT_TAB2 does not describe the level, but the row. A component's tab set is actually comprised of 3 rows of images, PT_TAB1, PT_TAB2, and PT_TAB3. PT_TAB3 images make up the bottom row of the tabs. You must create a new PT_TAB3 image for your new background color using the naming conventions above. PT_TAB1 images are shared by all background colors, so you do not need to create new PT_TAB1 images for each background color combination.

Get Your Mix Account and Vote

Do you have a Mix account yet? If not, then get one. After you create an account, add the PeopleSoft and PeopleTools groups to your profile. And then, be sure to vote for ideas submitted by your peers. For example, if you want Code Completion in Application Designer or Search by process name when adding process definitions to projects, then vote for it.

There are several good communities for PeopleSoft developers. Why join Mix? Mix has one thing the other communities don't. Mix has PeopleSoft developers and consultants. Yes, the other communities do have some Oracle staff, but not like Mix. Are you looking for a "Meet the Experts" experience all year, not just at OOW? Then try Mix.

Java, XPath, XML and Facebook

PeopleSoft's Integration Broker and Web Services provide an excellent framework for web services integration. But what if your PeopleSoft system needs synchronous access to another system that doesn't publish web services? For example, let's say you need to communicate with a system like Facebook that has a Java client library (yes, Facebook has a REST-based API, but using the existing Java client is much easier than creating all of the messages, handlers, and Facebook specific publishing logic). Even though we can call Java directly from PeopleCode, the Facebook methods return a value of type org.w3c.dom.Document. Since this return value is a Java object, not a PeopleCode XmlDoc, you cannot use the standard PeopleCode Node methods to extract values from the resultant document. In the absence of an additional client library, we would have to write DOM traversal code to select and concatenate the text node values contained in the Facebook response elements. Fortunately, the PeopleSoft application server installation includes the Xalan XML processor. The Xalan client library includes the org.apache.xpath.XPathAPI class that can be used to select values from a Java DOM Document similar to the XmlDoc.FindNode method. Here is an example of using the XPathAPI in PeopleCode to extract the name of the first friend from a Facebook friends query:

Local JavaObject &results = &fbClient.fql_query("SELECT uid, name, status FROM user WHERE uid IN (SELECT uid2 FROM friend WHERE uid1 = '" | &uid | "')");
Local JavaObject &xpath = GetJavaClass("org.apache.xpath.XPathAPI");
Local string &name = &xpath.selectNodeList(&results, "/fql_query_response/user[1]/name/text()");

What is an IScript?

It has been a few years since I attended my first PeopleSoft|Connect conference. As a new PeopleSoft developer, I was eager to learn all I could about PeopleSoft's Integration Broker, PeopleTools, and PeopleSoft's web UI. I spent hours pestering the experts (ask Robert Taylor, a prior Integration Broker product manager, and Tushar Chury, a former component interface developer). During one of the sessions I attended, someone from the audience asked a question about integration and the presenter replied, "I would probably create an IScript to do that." I don't remember the question. The only thing that stuck with me was the term "IScript." I had so many other questions for the experts that I didn't ask what an IScript was. Nevertheless, I left the event with a big question: "What is an IScript?" Since I had already taken the PeopleTools and PeopleCode classes and had not heard mention of IScripts, I decided they must be some legacy PeopleSoft technology that I didn't need to learn. To satisfy my curiosity, I looked up IScripts in PeopleBooks and received a... well... thorough definition... just like reading a good dictionary (see Enterprise PeopleTools 8.49 PeopleBook: PeopleCode API Reference > Internet Script Classes (iScript)). Yes, after reading the definition in PeopleBooks, I knew what an IScript was, but I just couldn't figure out why I would want to use one. Now, several years later, I find that I can't work without IScripts. Ajax, pagelets, WML, and SVG provide excellent use cases for IScripts. Each of these "technologies" requires marked up text without the overhead of the PIA rendered component HTML.

I like to think of IScripts as the PeopleTools developer's Swiss Army Knife. Besides a "cutting implement" a Swiss Army Knife might have a leather punch, a screw driver, a can opener, etc. Yes, you can do just about anything with a Swiss Army knife, but it might take you a long time to get the job done. Then, when you are done, the job might not be as satisfactory as it would have been if you had used the right tool. Have you ever opened a can with a Swiss Army Knife can opener? I'll bet you worked up an appetite. Likewise an IScript is the right tool for some jobs, but choose wisely. You can probably replicate the postback behavior of a component with an IScript, but it is a lot of unnecessary work. Likewise, you may have to consider multi-lingual translations, etc.

I compare IScripts to JSP or ASP. Basically an IScript is PeopleCode that has access to the Request and Response objects. Just like JSP and ASP, you, the developer, writes code to read parameters from the request and write information, data, etc to the response. Unfortunately, just like ASP, the response object's write methods only render text. Since the response object does not contain any binary write methods, you will have to ignore the dynamic image generation possibilities (I was hoping to use IScripts to render images stored in a user table, but I haven't figured out how to make that work since the write method only accepts plain text).

How do you create an IScript? For more information, you can look it up in PeopleBooks, but just to vaguely satisfy your curiosity, IScripts follow the same design pattern as FUNCLIBS. An IScript is a PeopleCode function stored in a record definition. The record definition name must start with WEBLIB_. The function can be in any field event of the record definition. By convention, we generally use the field ISCRIPT1 and the event FieldFormula. The function name, however, must start with IScript_ and cannot take any parameters or return a value.

How do you call an IScript? IScripts can be called a number of ways. How you call it depends on the purpose of the IScript. If your IScript is a pagelet, then you will create a CREF for your IScript in the portal registry under Portal Objects > Pagelets. If your IScript is called from JavaScript (Ajax, etc), then you call your IScript using a URL like http://server:port/psc/site_name/portal_name/node_name/s/WEBLIB_name.FIELDNAME.FieldFormula.IScript_name. To make it easier, you can generate an IScript URL using the PeopleCode built-in function GenerateScriptContentURL.

Now that you know what an IScript is, you might be interested in looking at some examples. Chris Heller posted a couple of IScripts that can be used as Bookmarklets. These Bookmarklets allow us, the developer, to exend our existing tool set by writing tools that we can use where we work: in the web browser. On Wednesday, April 4^th, 2006, Chris posted a bookmarklet/IScript that will drill into a portal registry content reference from a PeopleSoft page. In his 2006 Open World and 2007 Alliance presentations, Chris showed us how to use IScripts and bookmarklets to turn on tracing and display security information. ERP Associates also has some good PeopleSoft Bookmarklet examples.

Portal Template Settings

PeopleSoft uses Content References (CREF's) to describe how to display content within the PeopleSoft Portal (Enterprise or standard PeopleTools Portal). A very important setting for describing how to display a CREF is the CREF's template. The template describes how the content should be wrapped or "framed." Some templates proxy content into a single HTML page. Other templates use frames to display content. The most common frames template is the template that displays the header at the top, a menu on the left, and a content window on the right. If a CREF does not specify a template, then the Portal will use the default template. The default CREF template is set in PeopleTools > Portal > General Settings. If you haven't changed this setting, then your template is DEFAULT_TEMPLATE, also known as Portal default template. After looking up the default template, we can navigate to PeopleTools > Portal > Structure and Content to view the definition for this template. Templates are stored in the portal registry under Portal Objects > Templates. If your template has a storage type of "Local (in HTML Catalog)", then you can modify your template's HTML directly in this CREF. CREF's with a storage type of "Remote by URL", like the Portal default template, usually retrieve dynamic content from an IScript. Theoretically, you could store your template definition in any format or system as long as it is accessible by a URL (think of the possibilities for dynamic or even hosted templates). The IScript for the delivered Portal default template reads its settings from a different Content Reference. The name of this settings content reference is stored in the field PT_PORTAL_PROFILE of table PS_PTPP_OPTIONS.

SELECT PT_PORTAL_PROFILE FROM PS_PTPP_OPTIONS

With just a CREF name, you will have a hard time changing the template's values. The post Query for Component and/or CREF Navigation contains SQL to help you find the Structure and Content navigation for the CREF stored in PT_PORTAL_PROFILE. If you haven't customized your system, the settings CREF is PT_PORTAL_PROFILE (or PAPP_PORTAL_PROFILE if you are using Enterprise Portal). The PT_PORTAL_PROFILE CREF is stored in the Portal Registry's structure and content at Tools - Hidden > PeopleTools Portal Profile (For Enterprise Portal: Enterprise Portal - Hidden > Enterprise Portal Profile). From this CREF's attributes, you can specify the frame header height, whether to display the menu title, whether to show Search in the menu, as well as many other portal related settings. For example, if you wanted to change the frame header height from the default of 65 to 48 to give you more space for content, you would change the value of the attribute HEADER_FRAME_ROWS from 65 to 48.