Author Info

Chris Malek

Chris Malek is a PeopleTools® Technical Consultant with two decades of experience working on PeopleSoft enterprise software projects. He is available for consulting engagements.

About Chris Work with Chris

Looking for pain-free PeopleSoft web services? 😀

PeopleSoft Simple Web Services (SWS)

Introducing a small but powerful PeopleSoft bolt-on that makes web services very easy. If you have a SQL statement, you can turn that into a web service in PeopleSoft in a few minutes.

Add MetaData in all Responses

This section discusses a subtle practice that can add immense value for production support and debugging. It adds a metadata node to return data about the context of the request.

Let’s imagine that you have a simple request/reply asynchronous service operation.

It takes in EMPLID as a parameter
It returns the name associated with the EMPLID.
This service is XML based but this can easily be ported over to JSON.

The important part I want to highlight here is the meta element where we return:

dbname - The name of the database this ran in.
toolsVer - The tools version that this ran in.
psftTransactionId - The PeopleTools Integration Broker GUID that can be used to lookup the request in the IB monitoring tables.
currentUser - The OPRID running the PeopleCode.
responseDTTM - The date-time this was run
dbType - The database type.
request* - A singular node or nested node that contains the request parameters. This may not be feasible for large payloads.
serverTimeZone - The time zone of the server.

I have code running at different clients. When one of them experiences an issue all that information can be extremely useful and expedite troubleshooting. I often get a pasted response or screenshot of the PeopleSoft output from a user mentioning an issue. When these metadata elements are present, I have found it can answer many up front questions that may not have been provided. A user may just say “the web service is not working” and send a screenshot of the response. This response metadata can quickly provide that information up front without any back and forth. Perhaps the person has the wrong URL and is connecting to the wrong system. If you have the database name and the user they are authenticating as you can rule that out straight away. Additionally, if you echo back the request parameters typos and other simple but inevitable errors are quickly spotted.

Here is the HTTP signature of the request.

GET http://test.psft.cedarhillsgroup.com/PSIGW/RESTListeningConnector/PSFT_CS/CHG_PERSON.v1/SF0001 HTTP/1.1
Authorization: Basic .....

Here is a sample response. Take a look at lines 13 to 21.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


HTTP/1.1 200 OK
Connection: close
Date: Sun, 23 Aug 2020 16:08:28 GMT
Content-Length: 234
Content-Type: text/xml; encoding="UTF-8"
Content-Encoding: gzip
Set-Cookie: JSESSIONID=FrMcFAah28q8ngzYwYGMVGkjSdftPjc54scmjEJQzTeHBPvBimGu!-605235278; path=/; HttpOnly,psmap=; domain=.c.peoplesoftdemo-1470578694381.internal; path=/

<?xml version="1.0"?>
<response>
  <emplid>SF0001</emplid>
  <name>Sandra Epstein</name>
  <meta>
    <dbname>CS92U009</dbname>
    <toolsVer>8.56</toolsVer>
    <psftTransactionId>7fa9758b-e55d-11ea-a58d-c780246cd91c</psftTransactionId>
    <currentUser>PS</currentUser>
    <responseDTTM>Sun, 23 Aug 2020 23:27:13 GMT</responseDTTM>
    <dbType>ORACLE</dbType>
    <requestEmplid>SF0001</requestEmplid>
    <serverTimeZone>PST</serverTimeZone>
  </meta>
</response>

Here is a basic handler to output the meta-data.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


method OnRequest
   /+ &msgRequest as Message +/
   /+ Returns Message +/
   /+ Extends/implements PS_PT:Integration:IRequestHandler.OnRequest +/
   
   Local Message &response;
   
   Local Document &reqDOC = &msgRequest.GetURIDocument();
   Local string &EMPLIDParameter = &reqDOC.GetElement("EMPLID").value;

   &response = CreateMessage(@("Operation." | &msgRequest.OperationName), %IntBroker_Response);
   
   Local XmlDoc &xmlout;
   Local XmlNode &childNode;
   
   &xmlout = CreateXmlDoc("<?xml version='1.0'?><response/>");
   
   &childNode = &xmlout.DocumentElement.AddElement("emplid").AddText(&EMPLIDParameter);
   
   Local Record &recName = CreateRecord(Record.PERSON_NAME);
   &recName.EMPLID.Value = &EMPLIDParameter;
   &recName.SelectByKey();
   
   &childNode = &xmlout.DocumentElement.AddElement("name").AddText(&recName.NAME_DISPLAY.Value);
      
   Local XmlNode &metaNode;
   &metaNode = &xmlout.DocumentElement.AddElement("meta");
   
   &childNode = &metaNode.AddElement("dbname").AddText(%DbName);
   &childNode = &metaNode.AddElement("toolsVer").AddText(%ToolsRelease);
   &childNode = &metaNode.AddElement("psftTransactionId").AddText(&msgRequest.IBInfo.TransactionID);
   &childNode = &metaNode.AddElement("currentUser").AddText(%OperatorId);
   &childNode = &metaNode.AddElement("responseDTTM").AddText(DateTimeToHTTP(%Datetime));
   &childNode = &metaNode.AddElement("dbType").AddText(%DbType);
   childNode = &metaNode.AddElement("serverTimeZone").AddText(%serverTimeZone);
   /* echo out inbound parameters for debugging - of time errors are from invalid input */
   &childNode = &metaNode.AddElement("requestEmplid").AddText(&EMPLIDParameter);

   &response.SetXmlDoc(&xmlout);
   
   Return &response;
   
end-method;

If you spend a few extra minutes adding this or creating an application class to append this information to all responses you will benefit from it.

Chris Malek

PeopleSoft Simple Web Services (SWS)

Contents

Add MetaData in all Responses