Create a GET JSON REST API in PeopleSoft

These are the steps necessary to create a JSON REST API. To change from JSON to XML is easy, but I will focus on JSON.

• Create or identify the record that you will be using. I created four records. Three records that will be used for employee data. X_ERROR will be used to place error messages coming from the API.

• Create documents from the records. Each of the records created will be used to create a document.

These are the documents that were created based on records

• Create additional documents to be used in your http GET and POST requests. The documents created from records are not enough to get all the information that you need. In this case I want to retrieve the employee id, name, all her email addresses, and all her phone numbers. To accomplish that, I need create another document. This additional document will use the documents that were created from records.

• Create messages based on documents. I will only create two messages. One to be used as template and the other that will contain the employee data and error messages (if any)

• Create Service. One service needs to be created in which different Service Operations can be added

• Create Service Operation within Service. Once the Service has been saved, Service Operations can be added. In this case I am adding the GET Service Operation. A couple of things to note here. One is the URL that will be used to get the data and the other is the word "nothing" The template needs to have something there. "nothing" is there to identify that nothing will be passed on the template.

• Add Security to Service Operation. This security is a permission list that will access to this Service Operation. Since this is just a demo, I am granting access to PTPT1000 but on a production environment, this will be decided by your favorite security administrator.

• Create application package. The code below is used to populate the data into the message that will be sent to the user.

• Update Service Operation Handlers with the application package. The Service Operation needs to have a request handler.

• Test. Remember thing 1 from the Service Operation image, that is the URL that will be used for testing. In my PUM image, the URL is http://hostname:8000/PSIGW/RESTListeningConnector/PSFT_HR/X_GET_EMPLOYEE_DATA.v1/nothing

Final thoughts. If everything went well, you will have see a nice empty JSON result. If you want to see some data, you can do some insert statements on the three employee records and refresh your page. This URL with the security that was added will always return the PS data because that will be default user. If you scroll back to the Service Operation Image, you will see on the top right that there is a checkbox for User/Password Required. For this demo, that was left unchecked but in practice you should enable at least Basic Authentication and SSL. 

Thanks,

Manoranjan

Document Object in Peoplesoft

RESTful web service uses document type messages in service operations. We need to create message structure in document and then need to create a new message using this structure. Understanding the People Tools Document object is necessary to building REST based web services in People Soft so let's cover some of the basics.

Documents represent a hierarchical data structure a lot like a Rowset object.  They have a logical representation and a physical representation in the form of XML, HTML and JSON (from Tools 8.53).

Documents can be grouped together in a Package and like other Integration Broker object definitions can be versioned.

A document is a tree structure representing data.  As such, every document has ROOT element that is the name of the Document. 

There a four basic data types
*Primitive.  An element that has one of the simple data types of integer, string, character, date, time, etc.

*Compound.  An element that contains 1 or more primitives (think Record definition)

*Complex Primitive Compound.  A primitive element that has attributes. (think XML attributes ElementValue )

*Collection.  An element that is a repeating group of Compound and/or Primitives. (think Rowsets)

A Document is required to collect the inbound URI parameters from a REST web service call.  This is done by mapping the URI parameters to document element names.  This is called the Document Template.

Thanks,
Mano

Ways to access PeopleSoft RESTful Web Services

Well, People soft allows RESTful web services fully starting 8.53. I will post steps to create web services in my next blogs. Today we will see the ways to access Restful web services.

1. SOAP tester Tool
2. Advance REST client
3. CURL command 

Lets focus on CURL command which allows accessing web services from command prompt.

1. Download the CURL.exe from below site(download based on your OS) and place in one working directory.   https://curl.haxx.se/download.html

2. After creating Service Operation, You can get a uri(unique resource identifier) which looks like below.

http://<hostname>:<portname>/PSIGW/RESTListeningConnector/<node>/<service operation>/employee/{EmployeeID}/profile

3. In case you want to add custom header to your request, use -H to add the heaer value.

Curl Command for GET verb with Header: 

curl -i -H "Content-Type: application/json" -X GET http://<hostname>:portname>/PSIGW/RESTListeningConnector/<node>/<serviceoperation>/employee/{EmployeeID}/profile

Curl command for POST verb with header:

curl -i -H "Content-Type: application/json" -X POST -d "{\"myRequestID\": 0,\"myPayType\": \"XXX\",\"myPaySubType\": \"YYY\"}" http://<hostname>:portname>/PSIGW/RESTListeningConnector/<node>/<serviceoperation>/employee/{EmployeeID}/payPost

4. Go to Command prompt, Navigate to the folder where curl.exe is placed. Paste this command and fire. You will get the response with http status code.

This was you can access your webs services if autorization token is not enabled in service operations. If enabled, you need to pass the authorization token in header parameter.

Hope this helps!

Thanks,
Manoranjan

Custom Header in RESTful webservice Peoplesoft

If you are using Restful web services in Peoplesoft, you can set your custom header in response message. Below piece of code helps to set header for response message.

In addition you need to make sure below change to service operation routing tab to read the header from request message IBInfo class and populate the same in response message.

There is a bug with People toolset (8.54.12 or below), for incoming GET request has the capability of capturing the header details in IBInfo class where for POST and PUT, the details are not captured.
As a workaround, you need to modify the RestListeningConnector.class file to capture the header details for POST and PUT as well.

Otherwise ORACLE has already included this fix with next patch (8.54.21). Hope this helps!

Thanks,
Manoranjan

Basic Authorization between PeopleSoft and Third Party Systems

Today, I am going to share few important points on security in case you are integrating Peoplesoft with other system via Web services. (Which I experienced in my recent work)

Let you are integrating Peoplesoft with a third party via Restful/SOAP synchronous web services, we can authenticate the incoming Request to Peoplesoft via basic authentication/PS Token/SSL/None. Below are the steps mentioned in People book for securing your application.

1. Attach Permission list(who has access to Integration Broker) to Service Operation.

2. Set Service Operation page 'Required Verification' to desired one. If you will set the value to  NONE, any of the validation at peoplesoft end will be triggered for incoming request(This was my assumption with Tool version 8.54.12)

So when we set the value to 'Basic Authorization', Incoming message should contain a header with basic Authorization value as 64bit encoded NodeUser:Password

Peoplesoft Node user is validated for each incoming request from third party.

There is a bug with People Tool set that if you will set the value to NONE, still it validates the node user and the request will fail if message does not contain basic authorization header or contain wrong values. You need to do below as a workaround,

1. Customization needed to RESTListeningConnector.class file on web server until Oracle puts a fix in next patch level(those who are in 8.54.12 or below)

2. This connector class searches for string 'BASIC' in incoming message and does validation without checking whether the validation flag is set to NONE or Basic Authorization on service operation page. Either you need to comment this or make conditional check for flag.

After modification to class file, place it in same path and restart the services. Hope this will help people who have faced such issue in their implementation. Good luck !

Thanks,
Manoranjan

SOAP vs REST

Below is a comparison for which web service is good to opt for when integrating People soft with third party.

RESTful applications is simple, lightweight, and fast compared to SOAP.

REST’s decoupled architecture, and lighter weight communications between producer and consumer, make REST a popular building style for cloud-based APIs.

REST uses a smaller message format than SOAP. Where as SOAP uses XML for all messages, which makes the message size much larger, and thus less efficient.

REST provides better performance, as well as lowers costs over time. Moreover, there is no intensive processing required, thus it’s much faster than traditional SOAP.

The use of REST is often preferred over the more heavyweight SOAP (Simple Object Access Protocol) style because REST does not leverage as much bandwidth, which makes it a better fit for use over the Internet.

Sample RESTful URI:

http://machine/PSIGW/RestListeningConnector/Employee.v1/123-45-6789/DCenido/FullTimeEmployee

Sample SOAP message:

<SOAP-ENV:Envelope xmlns:SOAP ENV="http://schemas.xmlsoap.org/soap/envelope/">   

<SOAP-ENV:Header></SOAP-ENV:Header>

<SOAP-ENV:Body>

<Employee>       

<id>123-45-6789</id>

<name>DCenido</name>

<type>FullTimeEmployee</type>

</Employee>   

</SOAP-ENV:Body></SOAP-ENV:Envelope>

Cheers,

Manoranjan

Understanding RESTful WebService

q REST (Representational State Transfer) is a simple stateless architecture that generally runs over HTTP.

q REST is an architectural style, and an approach to communicate that is often used in the development of Web Services.

q REST provides a set of design rules for creating stateless services that identifies resources by their unique URIs. A client accesses the resource using the URI, acts upon them using a standardized fixed set of methods, and a representation of the resource is returned. 

q When using the HTTP protocol to access RESTful resources, the resource identifier is the URL of the resource and the standard operation to be performed on that resource is one of the HTTP methods: GET, PUT, DELETE, POST, HEAD.

q The amazing thing about the REST is the fact that clients (browsers) and servers can interact in complex ways without the client knowing anything beforehand about the server and the resources it hosts.

q An API that adheres to the principles of REST does not require the client to know anything about the structure of the API. Rather, the server needs to provide whatever information the client needs to interact with the service. The client provides the location of the resource with all required fields, and server will send the matching resource details.

The following principles encourage RESTful applications to be simple, lightweight, and fast:

Ø Resource identification through URI(Uniform Resource Identifiers):

     Resources are identified by URIs, which provide a global addressing space for resource (Noun)

Ø Self-descriptive messages: Resources are decoupled from their representation so that their content can be accessed in a variety of formats, such as HTML, XML, plain text, PDF, JPEG, JSON, and others.

Ø Stateless interactions through hyperlinks: Every interaction with a resource is stateless; that is, request messages are self-contained. Stateful interactions are based on the concept of explicit state transfer. Several techniques exist to exchange state, such as URI rewriting, cookies. State can be embedded in response messages to point to valid future states of the interaction. 

Ø Uniform interface: Resources are manipulated using a fixed set of four create, update ,read, delete www operations: PUT, POST, GET and DELETE. (Verb)

To create a resource on the server, use POST.
To retrieve a resource, use GET.
To change the state of a resource or to update it, use PUT.
To remove or delete a resource, use DELETE.

Portable PS_HOME in People Tools 8.54

Ø  PeopleTools 8.50 provided the ability to split the PS_HOME directory contents into three different places:

• PIA_HOME: Contained the J2EE deployment, equivalent to the former PS_HOME/Webserv directory.

• PS_CFG_HOME: Contained logs, traces and search indexes. Basically, any file created, modified or deleted at run time.

• PS_HOME: contained the binaries and external programs such as Crystal Reports. Cobols and SQRs.

Ø   PeopleTools 8.52, together with the PeopleSoft 9.1 applications, introduced a new directory:

PS_APP_HOME: This directory contained exclusively the application binaries and external program files, leaving PS_HOME just for the specific PeopleTools files. This approach allowed a simpler maintenance of the product. For instance, you could use the same PS_HOME for both PeopleSoft HCM and FSCM, keeping the specific application files in their own PS_APP_HOME directories. This way, when you applied a PeopleTools patch on PS_HOME, it would be available for all applications.

Ø   PeopleTools 8.53, The natural evolution of PS_CUST_HOME to Clearly Identify your Customizations. This new directory was meant to hold all the customized external files. This helped not only in maintaining PS_HOME and PS_APP_HOME almost read-only (they would be updated only by PeopleTools or application upgrades),but also to clearly identify the customizations, which is a tremendous gain when performing an application upgrade.

And now... Portable PS_HOME

PeopleTools 8.54 has gone a step further in simplifying the maintenance of the PeopleSoft installation. One of the issues.

we still faced with PS_HOME is that we could not move it to a different directory without facing issues, as there were some symbolic links and files containing absolute directory references within it. In the latest PeopleTools release, all symbolic links were removed, and all the directory references are relative,  not absolute. This allows the system administrator to easily move the directory to another location, or even to another server. Actually, you may not even need to move it. Just mounting the PS_HOME directory installed in one server into all the different PeopleSoft servers would make the trick, so you only need to apply changes in a single place.

Thanks for visiting !!

Cheers,

Manoranjan

HashWithSalt() in Peoplesoft Security

How SALT technology works with PeopleSoft, that is not included in People book. But a new field is added to PSOPRDEFN after Tools 8.53 to store hashed with salted password.

HashWithSalt(cleartext_string, &salt_string)

Description

Use the HashWithSalt function to generate a hashed (or “salted”) string. The output is Base64 encoded. For example, use the HashWithSalt function to generate a password for storage in the database. Because the HashWithSalt function generates output from the clear text password and a randomly generated salt value, it provides more secure hashing than the Hash function.

When you store a hashed password generated by HashWithSalt in PSOPRDEFN.OPERPSWD, you must also store the salt string used in PSOPRDEFN.OPERPSWDSALT.

To compare a clear text input value with an hashed value, use either the VerifyOprPassword function (for hashed and stored passwords) or the VerifyHash function for other salted strings.

Parameters

cleartext_string:   Specifies the string, such as a password, to be hashed.

&salt_string:  Specifies the randomly generated salt value as a string value.

 If the supplied salt value is a null value, then the HashWithSalt function will generate a salt value that will be returned as the value of this variable or record field..

Returns: A String value.

Example: 

The following examples demonstrate three methods for generating and storing a hashed password:

• Method 1 – Presents a loop that could process a series of passwords. In this specific case, only one salt value is generated and the loop is executed once only. Because SecureRandomGen is based on the Java security SecureRandom function, it is more efficient to call it once to return an array of required salt values than it is to call it once for each salt value required.

• Method 2 – Generates a new salt value and then generates a hashed password using this salt value.
Both the hashed password and the salt value are stored together in the database.

• Method 3 – Uses the PSOPRDEFN.OPERPSWDSALT field as a salt value to generate the hashed
password, which is then stored in the database. When PSOPRDEFN.OPERPSWDSALT is null,
Arbortext Editor Unformatted Print: langref_TEMPPasswordSaltingFunctions.dita Printed Thu
HashWithSalt generates a salt value, which in turn is stored in the PSOPRDEFN.OPERPSWDSALT
field.

/* method 1 */
Local array of string &operpwsdsalt;
Local string &resultSalt;
&operpwsdsalt = SecureRandomGen();
If (&operpwsdsalt <> Null) Then
For &i = 1 To &operpwsdsalt.Len
&resultSalt = &operpwsdsalt [&i];
&pswd = HashWithSalt(&OPRPSWD, &operpwsdsalt [&i]);
PSOPRDEFN.OPERPSWD = &pswd;
PSOPRDEFN.OPERPSWDSALT = &resultSalt;
End-For;
End-If;

/* method 2 */
Local array of string &operpwsdsalt;
&operpwsdsalt = SecureRandomGen();
&pswd = HashWithSalt(&OPRPSWD, &operpwsdsalt [1]);
PSOPRDEFN.OPERPSWD = &pswd;
PSOPRDEFN.OPERPSWDSALT = &resultSalt;

/* method 3 */
&pswd = HashWithSalt(&OPRPSWD, PSOPRDEFN.OPERPSWDSALT);
PSOPRDEFN.OPERPSWD = &pswd;

Commonly faced issue: 
1.Copy User Profiles functionality not correctly working because HashWithSalt PeopleCode is not functioning in PeopleTools 8.54.09.
2. HashWithSalt  returns blank.

Steps to resolve:

1. Find the Java class PSSecureRandomGen.class in a working environment.
2. Copy the class file in the problem environment, in the location PS_HOME\class\psft\pt8\pshttp
3. Restart the app server and re-test.

Thanks for reading !!

Regards,
Manoranjan