App Classes Versus Function Libraries

If you were to create a reusable code fragment, would you use an App Class or a Function Library? We asked our LinkedIn audience, and this was the result:

Do these results surprise you? Here are some insightful comments from the poll participants:

"Application Classes... For so many reasons:

1. Application Classes hold state across method calls
2. You get maintenance savings from classes
3. Application Packages can bundle related code
4. Classes give you public, protected, and private methods
5. Encapsulation and state
6. Clear Namespaces"

"I have always preferred application classes over function libraries because I find the discoverability of functions to be severely lacking. They can be placed just anywhere in any field in any record. And I can never remember the format for the declare statement."

"Don't forget about the variable declarations and type checking, which can avoid lots of problems at Runtime. That is on top of a clear inventory of available methods at the top of the class."

"Hands down application class..."

"My personal problems with functions:

1. Keep forgetting library records 
2. Can’t group code without creating a new library
3. Can't use them for configuration such as IB Handlers"

"I haven't willingly created a new function library in years.

• Application classes are much neater
• Nicer to implement
• Like the OO[P] reference
• Not nested in other code"

"A bonus of using Application Classes is being able to test any of your code from a delivered component in the PIA with the Application Class Tester. Navigation: Enterprise Components > Component Configurations > Application Class Tester. One of the best development tools that Peoplesoft delivers!"

Let's do a side-by-side comparison of the differences identified in the comments:

	App Classes	Function Libraries
All variables must be declared	✓
Stateful	✓
Testability	✓
PeopleCode-specific container	✓
Dynamic execution	✓
Object-oriented concepts such as Inheritance and Composition	✓
May be used by frameworks (IB, etc.)	✓
Stateless		✓

While the App Class column has the most checkmarks, is it the right answer for every situation?

All Variables Must Be Declared

Function libraries allow us to use variables without declaring them. An undeclared variable becomes implicitly declared as a generic data type upon first use. The problem with implicitly defined variables is that they support typos. It is really easy to mistype a variable name, which then becomes a new implicitly defined variable.

Application Classes will not compile and save unless you declare every variable. This avoids implicit typos.

At JSMpros, we teach that all variables should be defined at all times. The compilation output window, therefore, becomes a worklist. If a variable appears in the list, either declare or fix it. At the end of the day, anything in the list is a typo.

State

Application Classes are stateful, whereas Function Libraries are stateless. Both have their place. Application Classes must be instantiated prior to use. There are times when I have a code fragment that doesn't require state. Instantiating an object to perform a stateless operation seems like a waste. If the logic does not require state, then Application Classes may be overkill.

Testability

With Oracle-delivered solutions, such as the Application Class Tester, and community projects, such as PSUnit, it may seem that Application Classes are easier to test. But testability has more to do with coding practices than the container. For example, code you plan to test should avoid context-aware functions and variables. Whether you are testing App Classes or PeopleCode functions, you will write test case PeopleCode, which can be as simple as an App Designer-run App Engine.

PeopleCode-specific Container

Function Libraries are PeopleCode functions attached to events in Record Field PeopleCode. This can be challenging to manage. Having a PeopleCode-specific Container, such as an App Class makes a lot of sense. I do wish Function Libraries were stored in their own container. This doesn't impact their functionality, but it does affect lifecycle management and reuse.

Dynamic Execution

As noted in the comments, function libraries must be declared before they are invoked. We could argue that Application Classes have the same requirement in the form of import statements, but that's not exactly the case. One of the most powerful features of Application Classes is that we can instantiate objects, invoke methods, and set properties at runtime without knowing the implementing class at design time. We do this through the PeopleCode functions CreateObject, ObjectDoMethod, and ObjectSetProperty. These three functions allow for fully dynamic PeopleCode. In short, Application Classes don't need to be declared. It is this characteristic that allows PeopleSoft to build frameworks, such as Approval Workflow Engine, Event Mapping, and Integration Broker.

Object-Oriented Concepts Such as Inheritance and Composition

This is a key component to making Dynamic Execution work. We can create frameworks that code to interfaces and abstract base classes, and then use dynamic functions to instantiate full implementations at runtime.

Overall, object-oriented programming is not considered better or worse; it's just different. Poorly designed inheritance hierarchies can cause more problems than they fix. Perhaps what makes them challenging is that a solution is not static. We might create an amazing hierarchical design for the first build, but over time, that design becomes corrupted through changes. Composition is an Object-oriented concept that attempts to overcome the challenges of Inheritance.

May be used by frameworks (IB, etc.)

This feature brought to you by Dynamic Execution. Because we can code to an interface, we don't need implementation details until runtime. This makes App Classes perfect for AWE, IB, Event Mapping, PSUnit, Landing Pages, and much more!

In conclusion, each strategy has its place. Choose Function Libraries in the following situations:

• There are times when you must use Function Libraries. Signon PeopleCode is a great example.
• I also choose Function Libraries for stateless routines. If your reusable code fragment is stateless, then the overhead of App Classes may be overkill.

Choose App Classes:

• If you are building a framework, such as AWE, and want to register future event handlers, Application Classes are the right tool. You, the framework builder, would code to an interface, and later implementations provide the runtime details.

Which do you prefer? Let us know in the comments.

We teach both topics in our on-demand PeopleCode course. Already familiar with Function Libraries and want more information on Application Classes? Enroll in our on-demand course or join us for our next live virtual session!

From Idea Labs to Implementation: Access PeopleSoft Global Search with Hotkeys!

Oracle ACE Graham Smith recently posted a fantastic idea to Idea Labs: Put the cursor in Global Search when clicking Home. In a search-centric experience, this makes a lot of sense. And if you like this idea, you don't have to wait for a future PeopleTools release. We can build it ourselves with Event Mapping and a little JavaScript!

To avoid potential conflicts with accessibility and the PeopleTools-delivered tab order, the following implementation uses a keyboard combination (hotkeys) to activate the search bar. This is akin to Apple's Spotlight. I choose CTRL+SPACE. Several years ago, we recorded a SoundByte showing similar functionality:

Let's implement a slightly different version that specifically targets homepages/landing pages.

Here is what we will need:

1. HTML Definition that contains JavaScript to run when the page loads
2. Event Mapping App Class to inject our JavaScript
3. Related Content Service Definition
4. Event Mapping definition to map the App Class into the Landing Page Content Reference

The JavaScript to implement the request is trivial:

document.getElementById('PTSKEYWORD').focus();

But we are going to lock this into a key handler, so the full JavaScript looks like this:

document.addEventListener('keydown', function(e) {
    if (e.ctrlKey && (e.key === ' ')) {
        var el;

         el = document.getElementById('PTSKEYWORD');

         if(!!el) {
            el.focus();
        }
    }
  });

I threw that JavaScript into an HTML definition named JSM_GS_LP_FOCUS_JS, and then referenced it from my Event Mapping PeopleCode as follows:

import PT_RCF:ServiceInterface;

class PageActivate extends PT_RCF:ServiceInterface
   method execute();
end-class;

method execute
   /+ Extends/implements PT_RCF:ServiceInterface.execute +/
   
   AddJavaScript(HTML.JSM_GS_LP_FOCUS_JS);
end-method;

The remaining tasks are standard Event Mapping:

1. Create a Service
2. Assign the Service to the Content Reference Fluid Home
3. Test

And now you have your Hotkey! Enjoy!

At JSMpros, we teach PeopleTools Tips like this every day! Check out our events page to see what course we are offering next. Prefer to learn at your own pace? Enroll in on-demand training to learn whatever you want, whenever you want, wherever you want.

Branding System Options for Fluid

 The PeopleTools Branding System Options component allows a developer to inject custom CSS and custom JavaScript globally. This is fantastic, but it only applies to Classic/Classic+ (see Oracle Support document 2827970.1). Wouldn't it be nice to have the same functionality for Fluid? Now you can! PeopleTools 8.60 included Global Event Mapping, a feature that allows us to attach JavaScript and CSS to all Fluid components at once! We published a video a couple of years ago describing this PeopleTools feature. You may want to watch the video before continuing with this post:

Let's apply what we learned in the video to our scenario:

1. Create an Event Mapping Service App Class

In Application Designer, let's create a Global Event Mapping App Class. A Global Event Mapping App Class is just like any other Event Mapping App Class. They all start with the same PeopleCode. You may download our Event Mapping PeopleCode template from our GitHub repository. Here is a PeopleCode template to get you started:

import PT_RCF:ServiceInterface;

class FluidBrandingSystemOptions extends PT_RCF:ServiceInterface
   method execute();
end-class;

method execute
   /+ Extends/implements PT_RCF:ServiceInterface.execute +/
   
   If (IsFluidMode()) Then
      REM ** Insert JavaScripts;
      REM AddJavaScript(HTML.ABC123);
      
      REM ** Insert Stylesheets;
      REM AddStylesheet(Stylesheet.DEF456);
   End-If;
end-method;

2. Create an Event Mapping Service Definition

Every Event Mapping solution requires a Related Content Service Definition. As of PeopleTools 8.59, we can use a dedicated page for Event Mapping, but we don't have to. We can create our Global Event Mapping service definition the same way we have always created Related Content Service Definitions. Here is a screenshot of my service definition:

3. Run PeopleCode to Apply Global Event Mapping

Since there is no user interface to manage Global Event Mapping, we must invoke a few lines of PeopleCode to register our Global Event Mapping solution. I like to use App Engines for this, because I can run them directly from App Designer. Here is the PeopleCode I placed in my App Engine:

import PTCS_GLOBALEVENTMAPPING:*;

Local PTCS_GLOBALEVENTMAPPING:GlobalEventMapping &gem = create PTCS_GLOBALEVENTMAPPING:GlobalEventMapping();
Local boolean &bstatus = &gem.CreateGlobalEventMappingConfig("JSM_GBL_BRAND", "JSM_GBL_FL_BRAND");

4. Refactor Your Solution into a Table-Driven Framework (Optional)

Fantastic! We can now add or remove CSS and JavaScript globally by adding and removing lines from our App Class PeopleCode. Alternatively, would you like to maintain your list of assets through an online configuration page? The solution requires a bit more effort, but would involve the following:

• A table to store JavaScript and Stylesheet names,
• A page for configuring (likely with grids for JavaScript and Stylesheet assets), and
• An online component.

I'll leave this final step to you. Personally, I prefer the static code listing, as it performs better (critical for Global Event Mapping), and my list of Stylesheet and JavaScript resources doesn't change very often. I also like the change control required by PeopleCode that would not exist if I had an online configuration table.

As noted in the video, be careful not to break Global Event Mapping. One misstep and your entire system is broken! As also noted in the video, correcting an error is trivial. Just comment out the offending code.

Are you interested in learning more about Event Mapping? Check out our Event Mapping on-demand course, just one of many on-demand classes included with our subscription service.

When AI Writes PeopleCode... Fact or Fiction?

I just asked Gemini the following question:

"Is there a PeopleCode variable to detect Fluid Mode vs Classic mode?"

Gemini responded with, "Yes!" I thought, "FANTASTIC!"

Here is the code snippet Gemini suggested:

If %Component.IsFluid Then
    /* Logic specific to Fluid Mode */
    MessageBox(0, "", 0, 0, "Running in Fluid Mode");
Else
    /* Logic specific to Classic Mode */
    MessageBox(0, "", 0, 0, "Running in Classic Mode");
End-If;

Wow! That is some fantastic PeopleCode! But AI is known to hallucinate. Before trusting this code, we have to ask: Fact or Fiction?

Let's start with line 1:

If %Component.IsFluid Then

It appears Gemini thinks %Component is an object. What does PeopleBooks say?

%Component returns an uppercase character string containing the name of the current component, as set in the component definition.

To confirm, let's try compiling it in Application Designer. The following is a screenshot of the compilation result:

Verdict: Fiction.

%Component contains a primitive string, not an object. Since a primitive string does not have methods. The IsFluid method would be invalid.

I followed up with Gemini by asking:

"Can you share your reference for %Component?"

Instead of sharing a bibliography of cited sources, Gemini shared what appeared to be very legitimate documentation that describes Gemini's understanding of %Component. I attached a screenshot for your reference:

I circled the last statement, because it was the only part of this listing that was true:

"Gemini can make mistakes, so double-check it"

But I have to ask: Where did Gemini get its information? 🤔 Like a crack reporter, Gemini would not reveal its sources.

The good news is that Gemini is a fast learner! I fed Gemini a few authoritative PeopleBooks, such as a reference to PeopleCode System Variables, and Gemini generated a new response. This version is clever, but does it work?

Local ContentReference &oCRef;
Local boolean &isFluidMode;

/* Get the ContentReference object for the currently running content.
This object holds the metadata for the component's setup.
*/
&oCRef = %Session.GetContentReference();

If (&oCRef <> Null) Then
    /* Check the IsFluid property on the ContentReference object */
    &isFluidMode = &oCRef.IsFluid;
End-If;

If &isFluidMode Then
    /* Execute PeopleCode specific to Fluid UI */
    /* ... */
Else
    /* Execute PeopleCode specific to Classic UI */
    /* ... */
End-If;

What do you think? Fact or Fiction?

Let's start with the first line:

Local ContentReference &oCRef;

Unfortunately, ContentReference is not a built-in PeopleCode data type. What about this line?

&oCRef = %Session.GetContentReference();

Strike 2! GetContentReference is not a documented method of the Session object.

Verdict: Fiction.

But Gemini is on to something! The Fluid Mode attribute is visible in Structure and Content, so with a bit of PortalRegistry PeopleCode and the new %CRef system variable, you could write a lot of PeopleCode to determine if the current component is using Fluid mode.

I wanted to spend a few more minutes helping Gemini find the correct answer, so I fed Gemini several more PeopleBooks entries, hoping it would derive the correct answer. Each time, Gemini gave me a new, seemingly authoritative but entirely fictitious response, inventing new App classes and creating new functions.

After a few iterations, I decided to share the correct answer with Gemini. PeopleCode has a built-in function to determine Classic from Fluid: IsFluidMode. Here is Gemini's reply:

"This built-in function provides the clean separation of logic needed when supporting the same component in both Fluid and Classic modes (emphasis added)..."

Should we tell Gemini that a single component cannot be both Fluid and Classic?

This was a fun exercise. It was like a PeopleCode puzzle: find the hidden AI hallucination, and solve the puzzle.

How about you? Do you have interesting stories about AI and PeopleSoft? If so, please share them in the comments. We love hearing your stories!

Today, there is no substitute for experience and a strong personal understanding of PeopleCode. Want to become a PeopleSoft development expert so you can better determine fact from fiction? Enroll in the JSMpros All-access training pass and start learning!

PeopleSoft Reconnect 2025 | Dive Deep

The premiere PeopleSoft conference, Reconnect | Dive Deep, begins in just a few days. If you are not already registered for this live virtual conference, be sure to do so ASAP. If you are already registered, then be sure to log in to the conference app to build your agenda. Some sessions have capacity limits, and you don't want to miss them!

Here is the list of sessions I am presenting at this year's conference:

Monday

• 4:45pm EDT P-051853, PeopleSoft Test Framework: More than Automated End-user Testing

Tuesday

• 11:15 am EDT P-051448, Replacing Customizations with Configurations in Campus Solutions
• 1:45 pm EDT P-051447, Enterprise Components: The "Other" Toolset
• 4:15 pm EDT P-051446, PeopleSoft Fluid Best Practices

Wednesday

• 12:30pm EDT P-051861, What's New in 8.62 for Campus Solutions!

Thursday

• 12:30 pm EDT P-051442, Getting the Most out of PeopleSoft PeopleTools: Tips and Techniques
• 1:45 pm EDT P-051445, Isolate and Configure: Don't Customize!

As a registered attendee, be sure to check out our virtual booth to watch replays from prior conference sessions. I look forward to seeing you online next week!

Parsing JSON Arrays with PeopleCode

PeopleCode includes built-in support for parsing JSON through a native object called the JsonParser. Let's review a couple of JSON strings and then see how the JsonParser interprets them. First, let's review a JsonObject:

{
  "course": "PT1",
  "description": "PeopleTools",
  "courseType": "T",
  "duration": 4
}

Assuming that the JSON text is in the string variable &jsonStr, then we might parse it with code similar to:

Local JsonParser &p = CreateJsonParser();

If (&p.Parse(&jsonStr)) Then
  REM ** Woo Hoo! It parsed!;
End-If;

Parsing means the JsonParser created an in-memory structure. To leverage the JSON, we need to access that in-memory structure. The JsonParser includes one documented method to access the JSON Structure: GetRootObject(). The GetRootObject method returns a JsonObject. According to the documentation, the following PeopleCode should give us the value of the description attribute from the JSON above:

Local JsonObject &course = &p.GetRootObject();
Local string &descr; = &course.GetString("description");

What about a JSON Array? Here is my concern: There is no GetRootArray method. What if the "root object" is not an "object," but an Array? Here is what a valid JSON Array might look like:

[{
  "course": "PT1",
  "description": "PeopleTools",
  "courseType": "T",
  "duration": 4
}, {
  "course": "PC",
  "description": "PeopleCode",
  "courseType": "T",
  "duration": 5
}]

We would parse it using the same code as above. But how would you access the Array? Since the Parser has a GetRootObject method, let's invoke it, and then ToString the root object to see its JSON output. Here is the PeopleCode:

MessageBox(0, "", 0, 0, "%1", &p.GetRootObject().ToString());

... and here is the JSON:

{[
    {
        "course": "PT1",
        "description": "PeopleTools",
        "courseType": "T",
        "duration": 4
    },
    {
        "course": "PC",
        "description": "PeopleCode",
        "courseType": "T",
        "duration": 5
    }
]}

Do you notice anything unusual about that JSON? Notice the extra curly braces ({}). The "root" object is a JSON object. But here is where it gets interesting. The printed JSON is not valid. An object must have an attribute. The array should be assigned to an attribute. Now, does this matter? I think Oracle is allowed to internally represent JSON any way they desire. You might say that what we did was unexpected. We asked PeopleSoft to print an internal representation, not a true, expected JSON Object. But my question is the same: How do you access the Array that is now inside the root object? Here is the answer:

&p.GetRootObject().GetJsonArray("");

The GetJsonArray method expects an attribute name. We don't have one. So we don't give it one. Just use a zero-length string.

Want hands-on experience with REST services and PeopleCode parsing techniques? Join us on Tuesday, September 23, for two hands-on, live virtual workshops focused on integration! Details for the entire September series are available online.

We teach PeopleTools tips like this every week. Check out our website to see what we are offering next. Prefer to learn at your own pace? Our entire catalog is available online.

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.