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.

REST URI Templates

When configuring a REST Service operation, you have a broad array of options to pass parameters in the URL. These work in conjunction with the Document Template and your handler code. PeopleBooks does have some good discussion on this but the documentation is dense and hard to understand. I have read it several times and I am positive I have only scratched the surface. Let’s try some examples to clarify some common use cases.

Configuring “Synonym” Templates

Here is our example service operation that does an “Person Get”. The only parameter is the EMPLID.

We have configured five different templates to pass EMPLID. This is a rather extreme example but you could see something like this if some clients use different nomenclature to reference the ID. In this example, we have configured the service operation to be able to “speak the client’s language” and they can pass EMPLID in several ways. These templates are case sensitive.

{EMPLID}
?EMPLID={EMPLID}
?ID={EMPLID}
?id={EMPLID}
?student-id={EMPLID}

The document template only has one parameter.

If you were trying to get information in EMPLID 12345 you could use any of these URL patterns.

http://testserver.dev/PSIGW/RESTListeningConnector/PSFT_CS/CHG_PERSON.v1/12345
http://testserver.dev/PSIGW/RESTListeningConnector/PSFT_CS/CHG_PERSON.v1/?EMPLID=12345
http://testserver.dev/PSIGW/RESTListeningConnector/PSFT_CS/CHG_PERSON.v1/?ID=12345
http://testserver.dev/PSIGW/RESTListeningConnector/PSFT_CS/CHG_PERSON.v1/?id=12345
http://testserver.dev/PSIGW/RESTListeningConnector/PSFT_CS/CHG_PERSON.v1/?student-id=12345

In your handler, in order to parse the EMPLID parameter for all these different URL patterns is the following two lines of code.

.
Local Document &reqDOC = &msgRequest.GetURIDocument();
Local string &EMPLIDParameter = &reqDOC.GetElement("EMPLID").value;

No matter what URL pattern that was used, those two lines of code would end up populating the &EMPLIDParameter variable with the parameter. Your handler code does NOT need to try to determine what pattern was used. It just works. A client must use one of those patterns or they will get a cryptic 500 errors. (See the common issues chapter).

Passing CSV Lists in the Query String

There can be times when you need to pass a comma separated list of values in the URL query string as a parameter. Let’s look at an example by expanding our person get example.

Let’s imagine that we allow the client to pass in a CSV list of phone types they want back. Our code will parse those values and only return those phone types if they exists. We have to make some changes to both the Document Template and the URI templates.

First we need to add collection to the document and a child text primitive.

Collection: A data type on the document that can have multiple “rows” or values. You can think of it as similar to an array.

Now we can add a new URI template with some special syntax to tell the REST IB listener to expect a list value.

The new template is {EMPLID}?phones={phoneTypes*} with special emphasis on the use of both phoneTypes which references the collection in the document template. You have to pay special attention to case and misspellings. Also there is a * character which is a reserved word to tell the parser to expect a collection here. This will allow you to parse the values in the handlers using a “collection” data type against the “request document”.

Now lets look at what is required in the handler to accept the CSV values and populate an array of strings with the values from the URL.

If this URL were used: http://testserver.dev/PSIGW/RESTListeningConnector/PSFT_CS/CHG_PERSON.v1/12345?phones=HOME,MOBL you can populate a two element array by having this code in your handler. At the end of this code running the array &phoneTypes would have two elements that were: HOME, MOBL.

   Local Document &reqDOC = &msgRequest.GetURIDocument();
   Local string &EMPLIDParameter = &reqDOC.GetElement("EMPLID").value;
   Local Compound &paramsCompound = &reqDOC.DocumentElement;
   Local Collection &phoneTypesCollection = &paramsCompound.GetPropertyByName("phoneTypes");
   Local integer &i;
   
   Local array of string &phoneTypes;
   &phoneTypes = CreateArrayRept("", 0);
   
   For &i = 1 To &phoneTypesCollection.Count
      &phoneTypes.Push(&phoneTypesCollection.GetItem(&i).value);
   End-For;

Chris Malek

PeopleSoft Simple Web Services (SWS)

Contents

REST URI Templates

Configuring “Synonym” Templates

Passing CSV Lists in the Query String