CHAPTER

8

REST Controllers

In this chapter, you will learn how to connect an HTML5 user experience to PeopleSoft through REST services. While working through the content in this chapter you will gain experience with JSON, PeopleSoft Query, and the Apache web server.

What is REST?

The word REST is an acronym for REpresentational State Transfer. The term was coined by Roy Fielding in his doctoral dissertation Architectural Styles and the Design of Network-based Software Architectures. Chapter 5 of the dissertation introduces REST and is available online at http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm.

I describe REST as the opposite of SOAP web services. Rather than add new standards and vocabularies (like SOAP), REST leverages that which already exists. The focus of REST is the target resource (or data), whereas SOAP is more concerned with remote method invocation. This makes REST well-suited for standard Create, Read, Update, and Delete data operations. The nature of the REST request makes it much easier to use in client-side web requests because it doesn’t require complex WSDLs, data structures, security policies, and “envelopes.”

Building REST Service Operations

PeopleSoft REST service operations require the following metadata definitions:

  Documents

  Messages

  Services

  Service Operations

  PeopleCode Service Operation Handlers

  Routings

PeopleTools REST support varies by release. PeopleTools 8.52 was the first PeopleTools release with the RESTListeningConnector. REST-like services have been possible, however, since PeopleTools hit the Internet. For this chapter, we are most concerned with passing values to PeopleCode through a URL and then receiving a properly formatted result. PeopleTools 8.42 through 8.51 offered this through the IBConnectorInfo object and only supported URL values through query string parameters (see http://jjmpsj.blogspot.com/2011/10/rest-like-peoplesoft-services.html for more details). PeopleTools 8.52 gives us a true REST URL pattern as well as HTTP(S) authorization headers and common REST content types. In this chapter, we will use the RESTListeningConnector to read REST URLs and serve both JSON and HTML responses. Our jQuery Mobile and AngularJS applications will both use the BMA_PERSONNEL_DIRECTORY.SEARCH_FIELDS and BMA_PERSONNEL_DIRECTORY.EMPLID documents we created in Chapter 4. Since the jQuery Mobile and AngularJS applications both require a different response file format, we will create separate Service Operations for each.

jQuery Mobile with the RESTListeningConnector

Similar to Chapter 7, in this chapter we are going to transform the jQuery Mobile static application into a data-driven tool.

Creating Message Definitions

A Message definition is an abstract descriptor for a Service Operation payload. It is the web service structural synonym of an Interface or Abstract Class. Service Operations point to Messages without regard for Message implementation details. To use our Documents in Service Operations, we need to create corresponding Message definitions. Through your online PeopleSoft application, navigate to PeopleTools | Integration Broker | Integration Setup | Messages.

Defining the Search Parameter Document Message Definition

When you navigate to the Messages component online, PeopleSoft presents you with a search page. Click the Add a New Value link to transfer to Add mode. Enter the values from Table 8-1 into the Add New Message page.

TABLE 8-1.  BMA_PERS_DIR_SEARCH_PARMS values

When you click the Add button, the following screen will look suspiciously like the original Document definition screen. This is intentional. A Document already contains all of the metadata required for Integration Broker. Nevertheless, Integration Broker needs a Message definition to act as an abstraction layer between the Service Operation and its structure definition. Be sure to save the new definition or your Message will not exist.

NOTE

Even though the Message definition looks exactly like the underlying Document definition, be sure to click the Save button.

Defining the Details Parameter Document Message Definition

From the search results page we want to be able to select an item from the list and view the item details. To view the item (person) details, we need to send a unique identifier (employee ID) to the Service Operation to identify the desired item. Create a new Message definition named BMA_PERS_DIR_DETAILS_PARMS. Use the values from Table 8-2 to populate the Message metadata.

TABLE 8-2.  BMA_PERS_DIR_DETAILS_PARMS values

NOTE

When adding another Message, if your navigation breadcrumbs show that you are on the Messages component, but the content looks like the Documents component, then don’t click the Return to Search link. Clicking this link will take you to the Document search page, not the Messages search page.

The REST Service Container

PeopleTools requires all Service Operations to belong to a Service definition. Let’s create a Service definition container for our jQuery Mobile Service Operations. Log into your PeopleSoft application online and navigate to PeopleTools | Integration Broker | Integration Setup | Services. Add the new value BMA_PERS_DIR_JQM and check the REST Service box. Figure 8-1 is a screenshot of the Add New Service page. Click the Add button to move to the next page.

 

FIGURE 8-1.  Add New Service page

When the Service definition page appears, enter the description Personnel Directory JQ Mobile and then click the Save button. Figure 8-2 is a screenshot of the Service definition.

 

FIGURE 8-2.  Service definition

Creating Service Operations

We add Service Operations directly to Service definitions. The new service operations will be very similar to the iScripts we created in the last chapter. They will receive criteria in the URL and return jQuery Mobile page fragments. In fact, many of them will use the same HTML templates we created in Chapter 7. The only difference will be the URL pattern and delivery mechanism.

The Details Service Operation

When we consider how our users will interact with a Personnel Directory application, the search results page is the first dynamically generated page. Because it links to the details page, however, we will start with the details Service Operation. As with the iScript example, we want to dynamically generate that link for the details service. Unlike the iScript example, however, we can’t generate that link unless the target exists.

At the bottom of the Service definition, you will see a group box titled “Service Operation.” In the Service Operation field, enter the text BMA_PERS_DIR_DTL_JQM. This will be the name (or alias) used to identify the Service Operation. Select the value Get as the REST method. The GET HTTP verb tells the REST provider (PeopleSoft) to fetch data. This stands in contrast to other verbs such as POST, PUT, and DELETE which all manipulate data. Figure 8-3 is a screenshot of the Service Operation group box. Click the Add button to create and define the Service Operation.

 

FIGURE 8-3.  Service Operation group box

On the Service Operation page, enter the description Person directory details JQM. Figure 8-4 is a screenshot of the top section of the Service Operation page.

 

FIGURE 8-4.  Top of the Service Operation page

NOTE

When creating the Service Operation, we entered the name BMA_PERS_DIR_DTL_JQM. PeopleTools, however, created a Service Operation named BMA_PERS_DIR_DTL_JQM_GET. PeopleTools appends the REST method to the Service Operation name when creating new REST Service Operations.

Moving further down the page, you will see the REST Resource Definition group box. The REST Resource Definition describes the URL patterns associated with this Service Operation. Integration Broker uses the information in this section to map fragments of the URL into properties of a Document structure. In this section, select the Document Template BMA_PERS_DIR_DETAILS_PARMS.v1. After selecting the Document, you can either:

  Manually enter a URL template that matches the jQuery Mobile search form’s input fields.

  Use the Build button to create the URL template.

Here is the URL template text:

Figure 8-5 is a screenshot of the REST Resource Definition section of the Service Operation definition.

 

FIGURE 8-5.  REST Resource Definition

NOTE

If your REST Base URL is blank, then navigate to PeopleTools | Integration Broker | Configuration | Service Configuration and click the Setup Target Locations link. Verify that the REST Target Location has a value.

Move down to the Default Service Operation group box and enter an appropriate version description. Since the version identifier is v1, the value Version 1 seems appropriate. While still in the Default Service Operation section, move down to the Message Instance group box. Specify a Message.Version value of IB_GENERIC_REST.V1. Our jQuery Mobile REST responses will be HTML page fragments, and not structured data, so we can use an unstructured, delivered Message definition. Select text/html for the Content-Type. Save the new Service Operation. Figure 8-6 is a screenshot of the Default Service Operation Version section after saving.

 

FIGURE 8-6.  Default Service Operation Version

After saving the Service Operation, a new link appears near the top and is labeled Service Operation Security. Select this link to add this Service Operation to a permission list. For development purposes, we can add this Service Operation to PTPT1000 and PTPT1200. Before deploying to a production system, work with your system security administrator to determine the appropriate permission list for this Service Operation.

NOTE

Service Operation Security opens as a popup. Be sure your browser allows popups from your PeopleSoft instance.

Details Service Operation Handler     The metadata generated thus far tells Integration Broker what data to generate (response Message definition), who can generate it (Service Operation security and routings), and when to generate the response (URL pattern). Next, we need to tell Integration Broker how to generate the response. The Service Operation Handler tells Integration Broker the PeopleCode to execute when it receives a request for the BMA_PERS_DIR_DTL_JQM service. Before configuring the handler, we need to write some PeopleCode. The handler’s PeopleCode will look very similar to the iScript request handler from Chapter 7 but with the following changes:

  The REST handler does not have %Request and %Response system variables. Instead, the Service Operation Handler must collect its incoming parameters from the &MSG method parameter and return a new Message object containing the Service Operation response.

  We cannot use %Response.WriteBinary to send the employee’s picture to the client browser.

Item one will be trivial because we will use a standard Service Operation Handler design pattern. Item two is more difficult. To send photos to the browser through a Service Operation Handler, we will need to convert image data into a text format that the browser can interpret.

Log into PeopleTools Application Designer and create a new Application Package named BMA_PERS_DIR_JQM. To this new package, add the class DetailsRequestHandler. Open the DetailsRequestHandler PeopleCode event editor and enter the following PeopleCode. Differences between the handler PeopleCode and Chapter 7 iScript_Details function are emphasized with bold type.

Our PeopleCode first declares the Application Class structure and then implements the OnRequest method. The OnRequest method is really defined in the class base interface PS_PT:Integration:IRequestHandler. We are required to implement this method because Integration Broker will execute the OnRequest method when it receives a REST request.

This OnRequest handler uses the same logic, SQL, and HTML definitions as the iScript version from Chapter 7. A critical difference is the way we handle the photo’s URL. Instead of generating a URL, we are going to convert the binary image into a base64 representation. This is because Integration Broker does not contain a mechanism for serving binary data. The result will contain approximately one-third more bytes than the original image.

The database contains binary data that we need to convert into base64 text. One way to accomplish this is to use a combination of PeopleCode and database-specific functions to perform the base64 encoding. Why not use PeopleCode? PeopleCode does not contain functions or data types for manipulating binary data. Here is the PeopleCode for generating the &photoUrl. Add this to the end of the Application Class event handler.

The above code listing contains two methods:

  getPhotoDataUrl

  getImageDataUrl

The getPhotoDataUrl method determines if an employee photo exists. If it does, then it invokes getImageDataUrl with the employee photo SQL statement. If the photo does not exist, then it uses the “dummy photo” SQL statement.

The getImageDataUrl method is the method that actually executes the base64 conversion SQL. Since the Oracle database base64 conversion routine (UTL_ENCODE.BASE64_ENCODE) has a size limitation, the getImageDataUrl method performs the base64 conversion in chunks and then concatenates the converted text into a final result.

Before saving the new Application Class, you will need to create the following four SQL definitions:

BMA_EMPL_PHOTO_LENGTH:

BMA_EMPL_PHOTO_B64:

BMA_DUMMY_PHOTO_LENGTH:

NOTE

The data in PSCONTENT may span multiple rows. The PT_DUMMY_PHOTO image is small enough to fit in one row. If your placeholder image is larger, then you may have to alter the getImageDataUrl PeopleCode method to iterate over multiple rows.

BMA_DUMMY_PHOTO_B64:

NOTE

Microsoft SQL Server and other PeopleTools database platforms have their own platform-specific base64 routines. Another alternative to the Oracle PL/SQL solution is to use File.WriteRaw to move binary data into a file and then File.GetBase64StringFromBinary to convert the binary data into base64 text.

We can now associate our PeopleCode OnRequest handler with the BMA_PERS_DIR_DTL_JQM_GET Service Operation. Return to the BMA_PERS_DIR_DTL_JQM_GET Service Operation definition in your PeopleSoft online application and switch to the Handlers tab. Within the Handlers section, enter a Name, select the On Request Type, and Application Class Implementation. The name you enter within this grid is not important. After entering the Application Class details, the component will automatically set the Name field to REQUESTHDLR. Figure 8-7 is a screenshot of the configured handler prior to clicking the Details link.

 

FIGURE 8-7.  On Request PeopleCode handler

Click the details link and enter the Package Name BMA_PERS_DIR_JQM, the Path “:”, and Class ID DetailsRequestHandler. Select the Method OnRequest. Figure 8-8 is a screenshot of the handler details.

 

FIGURE 8-8.  Service Operation OnRequest handler details

After saving, test the Service Operation by navigating to http://<server>:<port>/PSIGW/RESTListeningConnector/<default local node>/BMA_PERS_DIR_DTL_JQM.v1/<emplid>, replacing values in the URL to match your environment-specific values. Here is the URL for my demo system: http://hr92dm05:8000/PSIGW/RESTListeningConnector/PSFT_HR/BMA_PERS_DIR_DTL_JQM.v1/KU2001. When the page loads, you should see the details page for the selected employee. Figure 8-9 is a screenshot of employee KU2001’s details (who happens to be one of the authors of this book).

 

FIGURE 8-9.  Details jQuery Mobile page fragment accessed as a REST service

NOTE

PSFT_HR is the delivered name of the default local node. One of the first steps you should take when configuring a PeopleSoft system is renaming the default local node. The node name is used to create a trust relationship between PeopleSoft instances. Failure to change your node name may compromise your application security.

The Search Service Operation

The Search Service Operation receives search criteria as query string parameters in a manner very similar to the Chapter 7 iScript_Search function.

Return to the BMA_PERS_DIR_JQM Service definition. In the Service Operation field, create a new Service Operation by entering the text BMA_PERS_DIR_SRCH_JQM. Select the value Get as the REST method. Figure 8-10 is a screenshot of the Service Operation group box. Click the Add button to create and define the Service Operation.

 

FIGURE 8-10.  Service Operation group box

On the Service Operation page, enter the description Person directory search JQM. Figure 8-11 is a screenshot of the top section of the Service Operation page.

 

FIGURE 8-11.  Top of the Service Operation page

In the REST Resource Definition section, select the Document Template BMA_PERS_DIR_SEARCH_PARMS.v1. Set the URL template text to:

Figure 8-12 is a screenshot of the REST Resource Definition section of the Service Operation definition.

 

FIGURE 8-12.  REST Resource Definition

NOTE

Figure 8-12 was taken after saving the Service Operation. Prior to saving, the REST Base URL was http://hr92dm05:8000/PSIGW/RESTListeningConnector/PSFT_HR// and was enabled for editing.

Move down to the Default Service Operation group box and enter an appropriate version description. Since the version identifier is v1, the value Version 1 seems appropriate. While still in the Default Service Operation section, move down to the Message Instance group box. Specify a Message. Version value of IB_GENERIC_REST.V1. Our jQuery Mobile REST responses will be HTML page fragments, and not structured data, so we can use an unstructured, delivered Message definition. Select text/html for the Content-Type. Save your Service Operation. Figure 8-13 is a screenshot of the Default Service Operation Version section after saving.

 

FIGURE 8-13.  Default Service Operation Version

Scroll back to the top of the Service Operation and select the Service Operation Security link. Add the appropriate permission lists. In the absence of an application-specific permission list, PTPT1000 and PTPT1200 will work.

Search Service Operation Handler Log into PeopleTools Application Designer and open the Application Package BMA_PERS_DIR_JQM. To this Application Package add the class SearchRequestHandler. Open the SearchRequestHandler’s PeopleCode event editor and enter the following PeopleCode. Deviations from the Chapter 7 jQuery Mobile iScript_Search function are emphasized with bold type.

NOTE

The PeopleCode above uses SQL definitions from Chapter 4 and HTML definitions from Chapter 7.

Besides the obvious differences of wrapping this code in an Application Class and using Documents and Service Operations, the REST event handler differs from the iScript version in the way it generates URLs. Since REST has no concept of %Portal and other online interactive variables, we can’t use the standard GenerateXxx functions to create URLs. Instead, we use the %IntBroker.GetURL method, passing in a parameter the Document object to use when populating the target Service Operation URL template.

Return to the BMA_PERS_DIR_SRCH_JQM_GET Service Operation online and switch to the Handlers tab. Within the Handlers section, enter a Name, select the On Request Type, and Application Class Implementation. Click the details link and enter the Package Name BMA_PERS_DIR_JQM, the Path “:” and Class ID SearchRequestHandler. Select the Method OnRequest.

Search Service URL Templates Test the Service Operation by navigating to your version of http://hr92dm05:8000/PSIGW/RESTListeningConnector/PSFT_HR/BMA_PERS_DIR_SRCH_JQM.v1?emplidSearch=KU00&nameSearch=A&lastNameSearch=S using test data that matches your environment data. You should see a basic search results list similar to the one in Figure 8-14.

 

FIGURE 8-14.  REST search results

Our search page is supposed to accept a variable number of parameters. Try removing one of the parameters (lastNameSearch, for example) and verify your results. Depending on your tools release and cache state, you will either see the search page fragment with no results or an Exception message. The reason it doesn’t work with fewer parameters is because Integration Broker is not able to find a URI template that matches the URL in the browser address bar. Return to the BMA_PERS_DIR_SRCH_JQM_GET Service Operation and add the following additional URI templates:

Save and then test a few different URL search patterns. You should now see valid results. Just for fun, swap some of the parameters and view the results. For example, place nameSearch at the front of the query string and emplidSearch at the back. Notice that changing parameter placement won’t match a URI template and therefore won’t return results. Figure 8-15 is a screenshot of the URI templates.

 

FIGURE 8-15.  URI templates

My Profile Service Operation

The personal profile page Service Operation differs from the details Service Operation in the following ways:

  It returns information about the logged-in user.

  Requires authentication to identify the current user.

Create the profile Service Operation by returning to the BMA_PERS_DIR_JQM Service definition and creating the new Service Operation BMA_PERS_DIR_PROF_JQM. Just like the other Service Operations, select the value Get as the REST method and then click the Add button.

When the Service Operation definition page appears, enter the description Person directory profile JQM. Check the box labeled User/Password Required and then select Req Verification of Basic Authorization. This will force the user to authenticate prior to accessing the profile service. Figure 8-16 is a screenshot of the top section of the Service Operation definition.

 

FIGURE 8-16.  Top section of secure Service Operation

NOTE

PeopleTools 8.54 adds the Req Verification values PeopleSoft Token and PeopleSoft Token and SSL.

Even though this Service Operation requires no parameters, Integration Broker requires each Service Operation to contain at least one URI template. In the REST Resource Definition section, create a URI template containing the single word profile. Figure 8-17 is a screenshot of the REST Resource Definition.

 

FIGURE 8-17.  Profile Service Operation URI definition

Scroll down to the Default Service Operation Version and fill in the same values that were used for the search Service Operation (described earlier in Figure 8-13). After saving, scroll back to the top of the Service Operation and select the Service Operation Security link. Add the appropriate permission lists. For development purposes we can use PTPT1000 and PTPT1200.

My Profile Service Operation Handler The profile page is similar to the details page, but with a different template. We could use the same SQL as the details page, but let’s do something a little different this time. In Chapter 7, we used PeopleSoft Query and Pagelet Wizard to display the profile page. Let’s use the same query inside a REST service handler. For the HTML, rather than create an HTML definition using Application Designer, we will upload it using the online Branding Objects component that was added to PeopleTools in 8.53. By moving both the data and display template into online components, we convert this portion of the application into something that designers, developers, and super users can maintain without Application Designer access.

NOTE

If you are using a version of PeopleTools older than 8.53, then create your HTML definition using Application Designer.

First, let’s write a PeopleCode handler that runs the query we created in the last chapter. Log into PeopleTools Application Designer and open the Application Package BMA_PERS_DIR_JQM. To this package, add the class ProfileRequestHandler. Open the ProfileRequestHandler’s PeopleCode event editor and enter the following PeopleCode.

Just like the details page, the profile page displays a photo. By making the DetailsRequestHandler photo-encoding method getPhotoDataUrl public, we are able to use the same method in the profile handler.

Return to your PeopleSoft online application and open the BMA_PERS_DIR_PROF_JQM_GET Service Operation. Within the Handlers section, enter a Name, select the On Request Type, and Application Class Implementation. Figure 8-18 is a screenshot of the configured handler prior to clicking the Details link. Remember, the name you choose is irrelevant because the component PeopleCode will automatically rename the handler REQUESTHDLR.

 

FIGURE 8-18.  Profile Service Operation handler metadata

Click the Details link and fill in the handler’s Application Class information:

  Package Name: BMA_PERS_DIR_JQM

  Path: “:”

  Class ID: ProfileRequestHandler

  Method: OnRequest

Figure 8-19 is a screenshot of the handler’s Application Class metadata.

 

FIGURE 8-19.  Application Class metadata

Save the Service Operation and copy the REST Base URL. For my demo server the REST Base URL is http://hr92dm05:8000/PSIGW/RESTListeningConnector/PSFT_HR/BMA_PERS_DIR_PROF_JQM.v1/. Set this URL aside for testing after we create the HTML definition.

Using your web browser, log into your PeopleSoft application and then navigate to PeopleTools | Portal | Branding | Branding Objects. On the HTML tab, click the Upload HTML Object link to create a new HTML definition. Name the new HTML definition BMA_JQPD_PROFILE_PAGE and provide a reasonable description. Paste the following into the main long edit field of the Add/Edit Branding Object dialog:

Figure 8-20 is a screenshot of the HTML definition online editor.

 

FIGURE 8-20.  Online HTML definition editor

Save the HTML definition and then test the Service Operation. To test this Service Operation, use the REST Base URL you copied and append the text profile as in: http://hr92dm05:8000/PSIGW/RESTListeningConnector/PSFT_HR/BMA_PERS_DIR_PROF_JQM.v1/profile. When your browser attempts to load the target URL, it will prompt you for credentials. Enter your PeopleSoft user name and password. This is a critical difference from the Chapter 7 iScript prototype: through configuration we can determine what to secure. Your results should appear similar to Figure 8-21.

 

FIGURE 8-21.  Unstyled profile page

Preparing the jQuery Mobile Application

Do you still have a copy of the jQuery Mobile prototype from Chapter 5? If not, see the sidebar titled “Resetting your jQuery Mobile Prototype” on the next page. When you are ready, open the search page (search.html) and find the form element. Replace the action URL with /PSIGW/RESTListeningConnector/<DEFAULT_LOCAL_NODE_NAME> /BMA_PERS_DIR_SRCH_JQM.v1. Now scroll to the bottom of the page and identify the profile hyperlink. Replace the links’ URL with /PSIGW/RESTListeningConnector/<DEFAULT_LOCAL_NODE_NAME>/BMA_PERS_DIR_PROF_JQM.v1/profile. After making the change, your search.html file should contain the following code fragment. I included a couple of lines on each side of the change for context. The required change is in bold text.

NOTE

The HTML sample that follows uses the delivered default local node PSFT_HR. For security reasons you should rename your default local node.

Configuring a Reverse Proxy

The REST services are served by the PeopleSoft server, whereas the jQuery Mobile app runs locally through a NetBeans embedded web server. Just like the iScript version from last chapter, we need to get both running in the same domain since browsers block cross domain AJAX requests. Rather than upload our modified jQuery Mobile app to the PeopleSoft server, this time we will reverse proxy the PeopleSoft REST services through the local Apache web server instance we installed in Chapter 1.

Configuring Apache httpd

Each operating system (and Linux distribution) configures the Apache web server a little differently. The Apache configuration for some Linux distributions, for example, contains the rule Include conf.d/*.conf, which means you configure the Apache httpd instance by adding configuration files to the conf.d directory. The installation for other operating systems, such as Microsoft Windows, however, requires you to add your own Include directives and configurations to the default httpd.conf. The following instructions assume a Windows installation similar to the installation described in Chapter 1. Please adjust accordingly for your operating system.

Creating a URL Alias

Using your favorite text editor, open the httpd.conf file located inside your c:Apache2.4conf directory. Scroll to the end of the file and add the following directive:

Now while still inside the c:Apache2.4conf directory, create a new directory named bma. We will place our custom Apache configurations inside this directory.

NOTE

If your httpd.conf file already contains conf/*.conf, then you don’t need to add the custom bma rule. Instead, any file you add to the conf directory will automatically be added to the Apache web server configuration. The benefit of using the delivered conf rule is that you can upgrade Apache without having to modify your configuration.

Inside the bma directory, create a new text file named pdjqm.conf. We will add rules to this file that tell the Apache web server to access our jQuery Mobile application from the NetBeans project directory. First, let’s map the project’s long folder path into an alias that is shorter and easier to access from a URL. The following code listing contains two references to the public_html folder of my NetBeans project. Open the new pdjqm.conf file and add the following text, changing the file references to match your project’s directory location. Each directive should be on its own line. For formatting purposes, the path and file names in the code listing span multiple lines.

NOTE

Apache 2.4 uses the Require directive, whereas older releases use the Allow directive. Adjust the directives to match your version

Now is a good time to test your configuration to make sure you can access the jQuery Mobile application from a web browser. First, save the changes to pdjqm.conf file and then start the Apache web server. To start Apache, open a command prompt and navigate to c:Apache2.4in. From this directory run httpd.exe. Now open a web browser and attempt to load http://localhost/pdjqm/search.html. You should see your jQuery Mobile search page. If the page won’t load properly, check your web browser’s JavaScript console and network resource tab for errors.

Don’t try to execute a search yet. We haven’t added proxy rules to reverse proxy a PeopleSoft instance into the same URL as our jQuery Mobile application. Let’s add those rules now.

Configuring a Reverse Proxy

WARNING

Improperly configuring an Apache web server will turn it into an open relay. See http://httpd.apache.org/docs/current/mod/mod_proxy.html#access for more information.

Some rules are application specific, such as the Alias we just defined. Other rules apply to the entire server and should be defined in a central location (such as httpd.conf). Loading modules is one of those common configurations. It is possible to load Apache modules from application-specific configuration files. A decentralized approach, however, makes it difficult to enable and disable modules. Therefore, we will make the following changes directly to httpd.conf. Ensure that your Apache web server instance is configured to load the proxy modules by searching the httpd.conf file for the following lines:

  LoadModule headers_module

  LoadModule proxy_module

  LoadModule proxy_html_module

  LoadModule proxy_http_module

  LoadModule xml2enc_module

If you find these lines, but they are prefixed with a hash (#), then delete the hash (the presence of the hash symbol disables a line). Your LoadModule section should appear similar to the following:

Next, scroll to the bottom and add the following proxy configuration right before the line Include conf/bma/*.conf:

The rest of our proxy configuration is application (or PeopleSoft) specific and belongs in a less generic (but still somewhat generic) configuration file. Create the file bmaproxy.conf and add the following:

NOTE

This generic proxy configuration allows anyone to access a PeopleSoft Integration Broker service through the reverse proxy. This loose configuration will come in handy later when we want to reverse proxy different PeopleSoft Service Operations.

A few pages ago we used %IntBroker.GetURL to turn search result items into hyperlinks that point to the details service. That worked great when we tested the search Service Operation directly from Integration Broker. Unfortunately, when we reverse proxy this content, the links retain pointers to the original PeopleSoft server, not the reverse proxy server. The configuration described here uses mod_proxy_html directives to rewrite hyperlink URLs to match the reverse proxy configuration.

The configuration uses mod_headers to turn off compression. The browser normally sends a request header telling PeopleSoft that it can accept compressed responses. The benefit of this compression is smaller network downloads that use less bandwidth. This is especially valuable for mobile applications. Unfortunately, mod_proxy_html cannot directly inflate PeopleSoft responses. Alternatively, you can use mod_deflate with mod_proxy_html to inflate PeopleSoft responses and then deflate the content before it travels over the Internet to the client browser. I included the SetOutputFilter directive required to enable mod_deflate with mod_proxy_html, but commented the line for this prototype. Inflating and deflating requires extra processing time. Considering that most reverse proxy scenarios involve content inside a closed network in very close proximity, the performance degradation caused by wasted CPU cycles will not likely be recovered through the network benefit of compression.

NOTE

The document at http://www.apachetutor.org/admin/reverseproxies contains great information describing how to configure the Apache web server as a reverse proxy server.

Restart Apache httpd and then perform a search. For example, try the URL http://localhost/PSIGW/RESTListeningConnector/PSFT_HR/BMA_PERS_DIR_SRCH_JQM.v1?emplidSearch=KU%25&nameSearch=&lastNameSearch=.You should see a rather unattractive, basic HTML list of search results similar to what you saw earlier in Figure 8-14. The only difference should be the host name used to access this content.

Click one of the search result hyperlinks and then look at the address bar. Notice that the URL changed to match the reverse proxy server’s host name. Verify that the details page appears as expected; just plain HTML with no styling.

Testing the Reverse Proxied jQuery Mobile Application

Test the jQuery Mobile application by navigating to http://localhost/pdjqm/search.html. You should see the styled jQuery Mobile search page appear just as it did in Chapters 5 and 7. Now search for employees. You should see fully styled results. Clicking a details link should display the employee’s details and picture. Try clicking the profile link. Notice anything different? If you haven’t logged into PeopleSoft yet, then clicking the profile hyperlink will cause the web browser to prompt you for your PeopleSoft credentials. I know I am repeating myself but this is an important point: The ability to apply different security rules to content is a critical difference between the iScript solution from Chapter 7 and the Service Operation solution presented in this chapter. Through configuration, we were able to provide anonymous access to browse the personnel directory and then require authentication for sensitive information. The iScript alternative, on the other hand, required authentication before a user could access the search page.

AngularJS with the RESTListeningConnector

Integrating AngularJS with the RESTListeningConnector is similar to the jQuery Mobile solution but with one difference: Our Service Operations will populate Document definitions and return JSON results.

Creating Message Definitions

The jQuery Mobile solution presented earlier in this chapter required Message definitions in order to map URI variables into Document definitions. We will reuse those same Message definitions for our AngularJS URIs and then create new Messages for the JSON responses.

Defining the Results Document Message Definition

Log into your PeopleSoft online application and navigate to PeopleTools | Integration Broker | Integration Setup | Messages. Create a new Message definition using the values from Table 8-3.

TABLE 8-3.  BMA_PERS_DIR_SRCH_RESULTS Message values

Defining the Details Parameter Document Message Definition

Create another message definition named BMA_PERS_DIR_DETAILS_PARMS using the values from Table 8-4. Remember to save your new Message definition.

TABLE 8-4.  BMA_PERS_DIR_DETAILS_PARMS Message values

Defining the Details Document Message Definition

Return to the Messages component one last time to create the BMA_PERS_DIR_DETAILS Message definition. Use the values from Table 8-5.

TABLE 8-5.  BMA_PERS_DIR_DETAILS Message values

REST Service Operations

Just like the jQuery Mobile application, let’s create some Service Operations for our AngularJS derivative.

Defining the Personnel Directory Service

Log into your PeopleSoft online application and navigate to PeopleTools | Integration Broker | Integration Setup | Services. On the Service search page, click the Add a New Value link that is to the right of the Service search box. Now that you are in Add mode, name the new Service BMA_PERS_DIR and check the REST Service checkbox. Figure 8-22 is a screenshot of the Add Service dialog. Click the Add button to define this Service and its related Service Operations.

 

FIGURE 8-22.  Adding a Service

Set the Service definition Description field value to Personnel Directory and ensure that both the REST Service Type and Is Provider checkboxes are checked. Figure 8-23 is a screenshot of the Service definition. Click the Save button located in the lower left corner of the page.

 

FIGURE 8-23.  Service definition

Defining the Search Service Operation

The search request page will submit search parameters to PeopleSoft and expects to receive a list of matching results. Service Operations are the metadata definitions Integration Broker uses to map incoming requests to response handlers.

Search Service Operation General Settings     While still viewing the BMA_PERS_DIR Service definition, move down to the Service Operations group box and enter BMA_PERS_DIR_SEARCH. From the REST Method drop-down box, select Get. Figure 8-24 is a screenshot of the Service Operation definition.

 

FIGURE 8-24.  BMA_PERS_DIR_ SEARCH Service Operation definition

Next, click the Add button that is to the right of the REST method drop-down box (not the Add button located at the bottom of the screen). This will take you to the Service Operation definition page.

In the Service Operation definition component, set the description to Person directory search. The top half of the BMA_PERS_DIR_SEARCH_GET Service Operation will look similar to Figure 8-25.

 

FIGURE 8-25.  Top half of Service Operation definition

Search Service Operation URI Definition     Move down to the REST Resource Definition area of the Service Operation definition. We use this region to map the Service Operation URI pattern to a Document’s structural properties. We are actually going to start at the bottom of this group box and work our way to the top. In the Document Template field, select the BMA_PERS_DIR_SEARCH_PARMS.v1 message. This is the message encompassing our search parameters Document. Enter the following for the Template URI: ?EMPLID={EMPLID}&NAME={NAME}&LAST_NAME_SRCH={LAST_NAME_SRCH}. Figure 8-26 is a screenshot of the REST Resource Definition prior to save (after saving, it will show additional information).

 

FIGURE 8-26.  REST Resource Definition

Search Service Operation Response Definition     After configuring the request portion of the Service Operation, we continue to the response metadata. Move down the page to the Default Service Operation Version information. Complete this section as shown in Figure 8-27. Enter v1 in the Version field and Version 1 in the Version Description field. For the Message Instance section, enter BMA_PERS_DIR_SRCH_RESULTS.v1 into the Message. Version field and choose application/json for the Content-Type.

 

FIGURE 8-27.  BMA_PERS_DIR_SEARCH_GET Service Operation Version

NOTE

If you are using PeopleTools 8.52, you may choose the application/xml content type instead of application/json.

Save your Service Operation before continuing. After saving, move back to the top and click the Service Operation Security link. Add a permission list for which you have access so you can test this Service Operation. If you are using demo data in a demo system, then add either permission list PTPT1000 or PTPT1200.

Search Service Operation Handler PeopleCode  Launch Application Designer and create a new Application Package named BMA_PERS_DIR. To this new Application Package, add an Application Class named SearchRequestHandler. Open the SearchRequestHandler Application Class PeopleCode editor and enter the following Service Operation stub handler. All Service Operation handlers start with this same boilerplate code.

Our Service Operation–specific code goes inside the OnRequest method. Let’s build the OnRequest method a few segments at a time. First, let’s write some code to access the incoming request parameters:

Notice the hierarchical structure of a Document. First, we start with the request Message. From there we traverse into the URI Document. The URI Document was described in our Service Operation metadata using the BMA_PERS_DIR_SEARCH_PARMS.v1 Document Template. Next, we traverse into the root Compound object—the object containing the three URI query string values: EMPLID, NAME, and LAST_NAME_SRCH.

Now let’s add a code fragment that declares our Response Message and Document structure:

The REST response variables and Document declarations look very similar to the request PeopleCode above. This is because we are working with the exact same types of definitions. Documents have no concept of request or response. They are simply structural containers. There is one key difference between our request and response PeopleCode: the response includes a Collection definition. Our search results may contain multiple rows. We must add each row to the response collection.

The next fragment contains the same variable declarations as Chapter 7. Add the following code to your OnRequest method:

Notice that this code fragment contains two arrays. The first one is for our SQL bind values (&sqlParms). The second is for our dynamic SQL where clause (&criteriaComponents). This second array exhibits a string builder design pattern that I use when assembling text fragments. Later you will see how we use the Array Join method to connect these fragments into a single string.

This code fragment also demonstrates the use of the lesser known function FetchSQL. The FetchSQL function returns the SQL statement stored in a PeopleTools SQL definition. Best practices recommend that we store SQL statements in SQL definitions, not as text in PeopleCode definitions. The FetchSQL function allows us to retrieve the SQL fragment we previously stored so we can embellish it with a very important, dynamic SQL where clause.

Let’s finish our variable declarations by adding variables corresponding to our SQL select columns:

The next step is to construct a dynamic SQL where clause. This code is very similar to the Chapter 7 search iScript PeopleCode.

This code fragment checks each parameter for a value. If the parameter has a value, then the value is added to the collection of bind values and the represented field is added to the SQL where clause. When building dynamic SQL statements, it is critical that we don’t append any information that came from the request. In the code above, you will see that I used the database platform independent meta-SQL %Concat. This is another PeopleTools best practice. Whenever possible, avoid using platform-specific constructs to improve cross-platform compatibility and avoid vendor lock-in. Here we are using the database-specific concatenation operator to add a wildcard search character to the end of the search string. For this scenario, we are assuming that a user intended a begins with type of search. We could give the user more control over the results by removing this wildcard concatenation and expect the user to enter wildcards where desired.

As a final step, let’s iterate over the SQL results and append matching rows to the response:

NOTE

The complete code listing is available from this book’s download site as described in the introduction.

Search Service Operation Handler Metadata     While still viewing the BMA_PERS_DIR_SEARCH_GET Service Operation, switch to the Handlers tab. Within the Handlers section, enter a Name, select the On Request Type and Application Class Implementation. The name you enter within this grid is not important. After entering the Application Class details, the component will automatically set the Name field to REQUESTHDLR. Figure 8-28 is a screenshot of the Handlers tab.

 

FIGURE 8-28.  Screenshot of the Handlers overview tab

Click the Details link to select an Application Class. Set the Description to Search request handler, the Package Name to BMA_PERS_DIR, the Path to :, the Class ID to SearchRequestHandler, and the Method to OnRequest. Save the Service Operation before continuing.

Testing the Search Service Operation  We now have enough information to test the BMA_PERS_DIR_SEARCH_GET Service Operation. From the General tab of the Service Operation, select the REST Base URL and the URI Template. Concatenate these two values into a single string and then replace each of the template bracketed items with a real value. Here is a sample URL from the HCM 9.2 demo image: http://hr92dm05:8000/PSIGW/RESTListeningConnector/PSFT_HR/BMA_PERS_DIR_SEARCH.v1/?EMPLID=KU00&NAME=A&LAST_NAME_SRCH=S. In my demo image, this URL returns the following JSON (formatting from http://jsonlint.com/):

Let’s try one more test before moving onto the next Service Operation. In your URL, eliminate values for each of the fields except EMPLID. For the EMPLID field, enter a full EMPLID. From the example results above, I chose KU0010. Here is my sample URL: http://hr92dm05:8000/PSIGW/RESTListeningConnector/PSFT_HR/BMA_PERS_DIR_SEARCH.v1/?EMPLID=KU0010&NAME=&LAST_NAME_SRCH=. Here is the response:

Compare this to the prior response. Specifically, look at the JavaScript notation immediately following the SEARCH_FIELDS property declaration. The prior results used bracket ([) JavaScript array notation. This last test that only returned one row, however, uses the curly brace ({) JavaScript object notation. If a JSON response includes multiple rows, Integration Broker will use array notation. Otherwise, it will use object notation. It does not matter that the underlying Document specifies that the SEARCH_FIELDS Compound is a member of a Collection.

Search Service Operation Optional Parameters     Let’s finish this Service Operation definition by creating URI templates for each of the optional query string parameters. Add the following URI templates:

  ?EMPLID={EMPLID}

  ?EMPLID={EMPLID}&NAME={NAME}

  ?EMPLID={EMPLID}&LAST_NAME_SRCH={LAST_NAME_SRCH}

  ?NAME={NAME}

  ?NAME={NAME}&LAST_NAME_SRCH={LAST_NAME_SRCH}

  ?LAST_NAME_SRCH={LAST_NAME_SRCH}

Content-Type Extra Credit     Just for fun, return to your Service Operation and change the Message Instance Content Type to application/xml and rerun your test in the browser. Notice that the response is now XML. This is one of the benefits of using Documents to model data: It abstracts the rendered data format from the Document structure. Be sure to change the response content type back to application/json before continuing.

Defining the Details Service Operation

Return to the BMA_PERS_DIR Service definition and add a new Service Operation named BMA_PERS_DIR_DETAILS that uses the Get REST Method. When the Service Operation definition appears, set the description to Personnel Directory Details. Move down to the URI section and select the BMA_PERS_DIR_DETAILS_PARMS.v1 Document Template. For the URI template, enter {EMPLID}. The URI template has the same values as the jQuery Mobile Details Service Operation described earlier in this chapter and portrayed in Figure 8-5.

Move to the end of the Service Operation definition and select the response message BMA_PERS_DIR_DETAILS.v1. Set the Response Content Type to application/json. Save, and then return to the top of the Service Operation to click the Service Operation Security link. For testing purposes, add this Service Operation to the PTPT1000 and PTPT1200 permission lists.

Details Service Operation Handler     Launch Application Designer and open the Application Package BMA_PERS_DIR. Add the new Application Class DetailsRequestHandler. To the PeopleCode editor, add the following code:

Return to the Service Operation online and create an OnRequest Application Class handler with the following details.

Package Name: BMA_PERS_DIR

Path: “:”

Class ID: DetailsRequestHandler

Method: OnRequest

Test the Service Operation by using a URL similar to http://hr92dm05:8000/PSIGW/RESTListeningConnector/PSFT_HR/BMA_PERS_DIR_DETAILS.v1/KU0007. Here is a sample template: http://<server>:<port>/PSIGW/RESTListeningConnector/<default_local_node>/BMA_PERS_DIR_DETAILS.v1/<employee_id>. Be sure to update the server name, port, node, and employee ID to match your system data. Your results should appear similar to the following:

Creating an Employee Photo Service

For the detail view photo we could add a base64 member to the details Document, but that doesn’t seem quite right considering the potential length of a base64-encoded photo. Instead, let’s create a new service that returns the same base64 data generated by our earlier jQuery Mobile employee photo method.

From the BMA_PERS_DIR service, create the Service Operation BMA_PERS_DIR_PHOTO using the Get REST Method. The Document and URI template are the same as the BMA_PERS_DIR_DETAILS Service Operation. The Document template is BMA_PERS_DIR_DETAILS_PARMS.v1 and the URI is {EMPLID}.

For the response message we will just return plain text so set the Content Type to text/plain. We can use the IB_GENERIC_REST.V1 message since our response has no structure. Save, and then return to the top to add permission lists through the Service Operation Security hyperlink.

Employee Photo Service Operation Handler  In Application Designer, open the BMA_PERS_DIR Application Package and add the class PhotoRequestHandler. Open the PeopleCode event editor and enter the following PeopleCode:

Return to the BMA_PERS_PHOTO_GET Service Operation and switch to the Handlers tab. Add an On Request Application Class handler. In the Application Class details enter the following:

Package Name: BMA_PERS_DIR

Path: “:”

Class ID: PhotoRequestHander

Method: OnRequest

Test the Service Operation using a URL similar to http://hr92dm05:8000/PSIGW/RESTListeningConnector/PSFT_HR/BMA_PERS_DIR_PHOTO.v1/KU0007. Your browser should display a lot of unintelligible base64 data.

Defining the Profile Service

The profile service differs from the details service in that it uses the employee ID of the logged-in user. Let’s create the profile service now. Return to the Service BMA_PERS_DIR definition and create a Get Service Operation named BMA_PERS_DIR_PROFILE. Set the description to something meaningful such as Person directory profile. Check the User/Password Required checkbox and set the Req Verification to Basic Authentication.

Moving down to the REST Resource Definition group box, set the URI template to the text: profile. This REST Service Operation has no parameters, and, therefore no Document Template or complex URIs.

In the Default Service Operation Version section set the Message. Version to BMA_PERS_DIR_DETAILS.v1. Next, set the Content-Type to application/json. Save the Service Operation.

After saving the Service Operation, the Service Operation Security link will appear. Be sure to add a permission list to which your test user belongs. PTPT1000 are PTPT1200 common permission lists. They work great when testing content from a book, but I don’t recommend using them to deploy a real solution.

Profile Service Operation Handler  Return to Application Designer to write a Service Operation handler for the profile Service Operation. This will be really easy because it is the same code as the DetailsRequestHandler, but without parameters. Open the BMA_PERS_DIR Application Package and add the class ProfileRequestHandler. Save the Application Package and then open the ProfileRequestHandler PeopleCode editor. Enter the following PeopleCode. Alternatively, if you already have the DetailsRequestHandler PeopleCode you can copy the DetailsRequestHandler and implement the changes noted in bold text.

Save the Application Package and Class and then return to the BMA_PERS_DIR_PROFILE_GET Service Operation online. Switch to the Handlers tab and fill in the Handlers table as we have for every other Service Operation. Give the handler a name (REQUESTHDLR seems appropriate), set the Type to On Request, and choose Application Class for the Implementation. Click the Details link and enter the following:

Package Name: BMA_PERS_DIR

Path: “:”

Class ID: ProfileRequestHandler

Method: OnRequest

After saving, test the Service Operation by visiting your environments version of the URL: http://hr92dm05:8000/PSIGW/RESTListeningConnector/PSFT_HR/BMA_PERS_DIR_PROFILE.v1/profile (change the server, port, and node to match your URL).

Reverse Proxying the AngularJS Prototype

We already created reverse proxy rules for Integration Broker when we created the proxy.conf file. You can test the existing proxy configuration with the following URLs. Be sure to change the node to match your environment’s node name (node name is in bold type):

  http://localhost/PSIGW/RESTListeningConnector/PSFT_HR/BMA_PERS_DIR_SEARCH.v1?EMPLID=KU00&NAME=A

  http://localhost/PSIGW/RESTListeningConnector/PSFT_HR/BMA_PERS_DIR_DETAILS.v1/KU0007

  http://localhost/PSIGW/RESTListeningConnector/PSFT_HR/BMA_PERS_DIR_PHOTO.v1/KU0007

  http://localhost/PSIGW/RESTListeningConnector/PSFT_HR/BMA_PERS_DIR_PROFILE.v1/profile

Updating the AngularJS Project’s Source Code

Open PersonnelDirectory-ajs project in NetBeans and then locate the services.js and controllers.js files. Both of these files contain JavaScript that points to static text files. We need to replace the static text file references with references to our new Integration Broker REST Services

Controllers.js     Find the DetailsCtrl Controller and update the URL as shown in the following code listing. Required code changes are in bold text:

Did you notice that I snuck in some code to call the photo service as well? Let’s update the partials/details.html file to use the new photo scope field:

NOTE

I switched from the src attribute to the ng-src attribute. This keeps the browser from attempting to render something until we are ready.

The ProfileCtrl controller is very similar to the details controller. Find the ProfileCtrl controller in js/controllers.js and update it as follows:

NOTE

I once again snuck in a call to the photo service. This time, instead of invoking the photo service asynchronously, I intentionally waited for the profile service to return a value. This is because the photo service expects an employee ID, and we don’t have the logged-in user employee ID until the profile service returns.

Besides updating the controller, we also need to update the partials/profile.html.

Services.js     Open the file js/services.js and find the SearchService factory. Inside $http replace the URL test-data/SEARCH_RESULTS.json with /PSIGW/RESTListeningConnector/PSFT_HR/BMA_PERS_DIR_SEARCH.v1. After changing the URL your code should appear similar to the following fragment:

NOTE

As with all URLs presented in this book. Verify site-specific information, such as node names, and update the URL accordingly. For example, if your HRMS default local node is HC92SBX, then replace PSFT_HR with HC92SBX.

Aliasing the AngularJS Project for Apache httpd

Let’s make the AngularJS project available to our local Apache web server by creating an alias. From within the c:apache24confma directory, copy the file pdjqm.conf into pdajs.conf. Now open the new pdajs.conf file and replace each instance of jqm with ajs. Your pdajs.conf file should contain text similar to the following (paths may vary, of course):

Save the file and restart Apache httpd. Now verify that your AngularJS mobile application works as expected by using your web browser to visit the URL http://localhost/pdajs/. If it does, congratulate yourself on a job well done. If it doesn’t work, congratulate yourself anyway because you accomplished a lot in this chapter; now troubleshoot your application using tools such as Firefox Firebug, Chrome developer tools, etc. The JavaScript console and network tabs will show you errors the browser identified, but didn’t necessarily tell you about.

Conclusion

In this chapter you learned how to:

  Create REST services that return JSON and HTML.

  Use PeopleSoft Query to create configurable data sources.

  Edit HTML definitions online using the Branding Objects component.

  Configure Apache web server as a reverse proxy.

  Convert database binary objects into base64.

  Wire all of these ideas together to serve both anonymous and secure mobile applications.