1. CON7553 PeopleTools REST Web Services: Everything You Need to Know
Graham Smith - OXFAM GB
PeopleSoft Technical Lead & System Architect

2. Oxfam
Oxfam is a vibrant global movement of dedicated people fighting poverty
70 years experience in 94 countries
Syria - Helping over 200,000 refugees

3. PeopleSoft @ OXFAM HCM & FSCM Applications
4,500+ users in 70+ countries
Working on 9.2 upgrade to FSCM

4. Agenda 1) What is a web service 2) What is SOAP & REST
3) What is WSDL and WADL
4) What is XML and JSON
6) Configuring PeopleTools for REST
7) What's delivered in a SYS database that works
8) How to Build a REST service
9) Testing tools
10) Security
11) Demo
12) Questions

5. What is a Web Service?
Method of communicating between devices over the world wide web
Characteristics of a web service
Defined interface in machine readable form (WSDL or WADL)
Conveyed over HTTP/S
Systems interact using request / response messages (SOAP or REST)

6. Introduction to REST Style of doing Web Services
Defined by Professor Roy Fielding
@ UC Irvine in 2000
Co-founder of Apache HTTP Server
Principal author of HTTP specification
Emerging as the predominant web API model
Lighter weight and easier to use compared to SOAP and others
Available from PeopleTools 8.52

7. What is SOAP & REST? Both are used to access Web Services
One is a protocol (SOAP) with defined specification
One is an architectural style (REST)

8. What is SOAP? SOAP Simple Object Access Protocol
“SOAP Version 1.2 is a lightweight protocol intended for exchanging structured information in a decentralized, distributed environment”
TECHNOLOGY SPECIFICATION (W3C in 2033)
Requires custom methods (e.g. getCustomerName)
Uses HTTP POST method to send XML messages
Designed for distributed transactions
Extensible model (WS-Security, WS-Routing, etc)
Asynchronous and Synchronous communication possible
Built in error handling

9. What is REST? REST REpresentational State Transfer
ARCHITECTURAL STYLE (not a standard)
Implements standard HTTP operations (GET, POST, PUT, DELETE)
Used to locate and return the representation of a resource (URI)
No XML to parse and process (fast)
Synchronous communication only
Stateless
Easier to implement

10. What is WSDL & WADL? WSDL Web Services Description Language
XML to describe SOAP web service
Can define both SOAP and REST web services (from WSDL 2.0)
PeopleTools describes SOAP based service
W3C Recommendation 2007
WADL Web Application Description Language
XML to describe REST web services
PeopleTools describes REST services using WADL
W3C Submission in 2009 by Sun Microsystems
Limited tooling support

11. What is XML & JSON? JSON now supported PeopleTools 8.53
XML eXtensible Markup Language
JSON JavaScript Object Notation
JSON now supported PeopleTools 8.53

12. Configuring PeopleTools for REST
Set REST Target Locations in Service Configuration
Specify optional node name Target URL

13. Configuring PeopleTools for REST
Activate ~~Any~~ to Local Routing on GETWADL Service Op

14. Configuring PeopleTools for REST
Set default application server in Gateway Setup Properties
Check and set PeopleTools version (inc. Patch number)

15. Delivered Example in SYS database
Service Operation PTLOOKUPXLAT_REST_GET
Returns XLAT values for a given Fieldname.
Handler App Package PT_IB_LOOKUPREST
From 8.53 this is implemented as REST based service.
An error may occur in the Handler code if
Earlier than

16. PT_LOOKUPXLAT_REST_GET

17. REST URI - Uniform Resource Identifier
Identifies the name of a web resource
er feufhefherf her hfer fherhferfher heihfwe ew ew ew ew ew dwe dwedew dwe ew dewdwe ewwe dew wewedew weew weewdwe ewwdewdwe ew dew weewewweew dwe dewdewdewdewewdewdewdewdewdwe

18. REST URI - Uniform Resource Identifier
REST operates in a similar way to the WWW
oprid xxxxxxxxxxxx
VP1 xxxxxxxxxxxxxx

19. REST URI – Resource Templates
Resource name
Resource name
RESOURCE TEMPLATES

20. REST URI – Resource Document
/operators/oprid={oprid}
Template
Mapping by
element name

21. How to Build a REST Web Service
Create Document
Test Document
Create Message
Create Service
Create Handler
Create Service Operation
Resource Template
Test Handler
Create Routings
Test Service Operation
Publish Web Service (if WADL is needed)
Using delivered image FSCM

22. REST Web Service Components
REST Service
Service Operation
Resource Definition
URI Template(s)
Document Template
Response Message (20
Fault Message (400)
Handler (OnRequest)
Service Operation
Resource Definition
URI Template(s)
Document Template
Response Message (200)
Fault Message (400)
Resource
Document
Message
Response
Document
Handler (OnRequest)

23. Example REST Service http://myserver/operator/vp1
Return the name and address of a given operator.
Service = OOW_OPERATOR
Service Operation = OOW_OPERATOR_GET
Application Designer project OOW_REST
Download from

24. 1) Documents Definition
Define hierarchical data structures (logical)
Map onto physical structures
XML
JSON
Database records and fields
Data types available
PRIMITIVE = string, char, integer, etc
COMPLEX PRIMITIVE = primitive with attributes
COMPOUND = set of one or more primitives
COLLECTION = set of one or more compounds

25. 1) Document Data Types ROOT element Collection Record Compound
Primitive
Complex Primitive Compound

26. 1) Documents Needed Document Template Request Document/Message
Used to retrieve inbound URI parameters
Cannot contain COMPOUND types
Supports direct variable substitution
Request Document/Message
Only required if using POST method
Response Document
Used to construct return message to client
Fault Document (optional)
Used to construct return message on error condition
They can be all the same document or different ones

27. 1) Create Document

28. 1) Create Document – Relational
Allows mapping of document elements to PeopleSoft records and fields.

29. 2) Document Tester

30. 2) Document Tester - XML

31. 2) Document Tester - JSON

32. 2) Document Tester - PeopleCode

33. 2) Document Tester – Create XSD

34. 3) Create Message
The DOCUMENT is not enough. A message of type Document must be created.

35. 4) Create Service

36. 5) Create Handler
Create an Application Class that implements PS_PT:Integration:IRequestHandler
Create document from inbound URI Local Document &oprDoc = &_MSG.GetURIDocument();
Get inbound URI element values from document &oprid = &oprDoc.GetElement("oprid").value;
If POST then get content body
&str = &_MSG.GetContentString();

37. 5) Create Handler Create return message
&returnMsg = CreateMessage(Operation.OPERATOR_GET, %IntBroker_Response);
Populate return message
&returnDoc = &returnMsg.GetDocument();
&returnCom = &returnDoc.DocumentElement;
&returnCom.GetPropertyByName("oprid").value = &oprid; &returnCom.GetPropertyByName("oprdefndesc").value = &descr;

38. 5) Use Document Tester to get PeopleCode for Handler class

39. 6) Create Service Operation

40. 6) Resource Definition

41. REST URI – Resource Document
/operators/oprid={oprid}
Template
Mapping by
element name

42. 6) Resource Template Builder

43. 6) Response Definition

44. 6) Service Operation Security

45. 6) Assign Handler to Service Op

46. 7) Test Handler

47. 7) Test Handler

48. 8) Create Routing
Local-to-Local needed to use Service Operation Test utility.
Any-to-Local needed to test service outside PeopleSoft.

49. 9) Test Service Operation

50. 10) Publish Web Service
Integration Broker > Web Services > Provide Web Services Only need to publish if you need the WADL document.

51. Test Web Service SOAPui friom SmartBear PeopleTools SendMaster
PeopleTools SendMaster
%PS_HOME%\sendmaster
Any Browser (to test GET)
Fiddler (to test GET/POST/PUT/DELETE)

52. REST Security PeopleTools supports no authentication (ie public)
BASIC Authorization with or without SSL
Adds HTTP header to Request
Authorization: BASIC <oprid:password>
Base64

53. Demonstration of REST Jim Marion
Principal Applications Technology Consultant, Oracle
Author of two fine books on PeopleTools
Jim’s

54. Any questions Graham Smith PeopleSoft Technical Team Leader Oxfam GB
i-like-trains.blogspot.com