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 ChrisIntroducing 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.
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.
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).
What if you need to to determine what URI template was used? The URIResourceIndex
property of the request message can be used. You can use the following code to determine the URI template that was used.
evaluate &msgRequest.URIResourceIndex
when = 1
/* Do something if the first URI template was used */
break;
when = 2
/* Do something if the second URI template was used */
break;
when-other
/* Catch all */
break;
end-evaluate;
I have found some edge cases where the URI template are not flexible enough for me and I just want to “catch all” and parse the parameters myself. I do this with the following:
document
with a text
element for the catch all parameter.
catchAll
.?{catchAll}
or {catchAll}
or some unique combination that makes sense for you.catchAll
parameter in your handler.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 ¶msCompound = &reqDOC.DocumentElement;
Local Collection &phoneTypesCollection = ¶msCompound.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;