CON7553 PeopleTools REST Web Services: Everything You Need to Know

CON7553
PeopleTools REST Web Services:
Everything You Need to Know
Graham Smith - OXFAM GB
PeopleSoft Technical Lead & System Architect
Oxfam
Oxfam is a vibrant global
movement of dedicated
people fighting poverty
70 years experience in 94 countries
Syria - Helping over 200,000 refugees
Page 2
PeopleSoft @ OXFAM
• HCM & FSCM Applications
• 4,500+ users in 70+ countries
• Working on 9.2 upgrade to FSCM
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
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)
Page 5
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
Page 6
What is SOAP & REST?
• Both are used to access Web Services
• One is a protocol (SOAP) with defined specification
http://www.w3.org/TR/soap/
• One is an architectural style (REST)
Page 7
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
Page 8
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
Page 9
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
Page 10
What is XML & JSON?
• XML eXtensible Markup Language
• JSON JavaScript Object Notation
JSON now supported PeopleTools 8.53
Page 11
Configuring PeopleTools for REST
• Set REST Target Locations in Service Configuration
• Specify optional node name Target URL
Page 12
Configuring PeopleTools for REST
• Activate ~~Any~~ to Local Routing on GETWADL Service Op
Page 13
Configuring PeopleTools for REST
•
•
Set default application server in Gateway Setup Properties
Check and set PeopleTools version (inc. Patch number)
Page 14
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
8.53.06
Page 15
PT_LOOKUPXLAT_REST_GET
http://server/PSIGW/RESTListeningConnector/PTLOOKUPXLAT_R
EST.v1/XLAT_Lookup/RUNSTATUS?fieldVal=7
Page 16
REST URI - Uniform Resource Identifier
• Identifies the name of a web resource
http://myserver/orders/data.html
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
dewdewdewdewewd
ewdewdewdewdwe
Page 17
REST URI - Uniform Resource Identifier
• REST operates in a similar way to the WWW
http://myserver/operators
oprid
oprid
oprid
oprid
oprid
oprid
oprid
oprid
oprid
oprid
oprid
xxxxxxxxxxxx
xxxxxxxxxxxx
xxxxxxxxxxxx
xxxxxxxxxxxx
xxxxxxxxxxxx
xxxxxxxxxxxx
xxxxxxxxxxxx
xxxxxxxxxxxx
xxxxxxxxxxxx
xxxxxxxxxxxx
xxxxxxxxxxxx
http://myserver/opeators/oprid=VP1
VP1 xxxxxxxxxxxxxx
Page 18
REST URI – Resource Templates
http://myserver/operators
Resource name
http://myserver/operator/oprid=VP1
Resource name
RESOURCE TEMPLATES
Page 19
REST URI – Resource Document
http://myserver/operators/oprid=VP1
/operators/oprid={oprid}
Template
Mapping by
element name
Page 20
How to Build a REST Web Service
1.
2.
3.
4.
5.
6.
Create Document
Test Document
Create Message
Create Service
Create Handler
Create Service Operation
a)
Resource Template
7. Test Handler
8. Create Routings
9. Test Service Operation
10. Publish Web Service (if WADL is needed)
Using delivered image FSCM 9.2.002.
Page 21
REST Web Service Components
REST Service
Service Operation
Service Operation
• Resource Definition
• URI Definition
Template(s)
• Resource
Document
Template
• • URI
Template(s)
• • Response
Message
(20
Document
Template
Fault Message
(400)
• • Response
Message
(200)
• Fault Message (400)
Resource
Document
Message
Response
Document
Handler (OnRequest)
Handler (OnRequest)
Page 22
Example REST Service
Return the name and email address of a given operator.
Service = OOW_OPERATOR
Service Operation = OOW_OPERATOR_GET
http://myserver/operator/vp1
Application Designer project OOW_REST
Download from http://goo.gl/KUX9F2
Page 23
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
Page 24
1) Document Data Types
• ROOT element
• Collection
• Record Compound
• Primitive
• Complex Primitive Compound
Page 25
1) Documents Needed
• Document Template
• 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
Page 26
1) Create Document
Page 27
1) Create Document – Relational
Allows mapping of document elements to PeopleSoft records and fields.
Page 28
2) Document Tester
Page 29
2) Document Tester - XML
Page 30
2) Document Tester - JSON
Page 31
2) Document Tester - PeopleCode
Page 32
2) Document Tester – Create XSD
Page 33
3) Create Message
The DOCUMENT is not enough. A message of type Document must be created.
Page 34
4) Create Service
Page 35
5) Create Handler
1. Create an Application Class that implements
PS_PT:Integration:IRequestHandler
2. Create document from inbound URI
Local Document &oprDoc = &_MSG.GetURIDocument();
3. Get inbound URI element values from document
&oprid = &oprDoc.GetElement("oprid").value;
4. If POST then get content body
&str = &_MSG.GetContentString();
Page 36
5) Create Handler
5. Create return message
&returnMsg = CreateMessage(Operation.OPERATOR_GET,
%IntBroker_Response);
6. Populate return message
&returnDoc = &returnMsg.GetDocument();
&returnCom = &returnDoc.DocumentElement;
&returnCom.GetPropertyByName("oprid").value = &oprid;
&returnCom.GetPropertyByName("oprdefndesc").value
= &descr;
Page 37
5) Use Document Tester to get
PeopleCode for Handler class
Page 38
6) Create Service Operation
Page 39
6) Resource Definition
Page 40
REST URI – Resource Document
http://myserver/operators/oprid=VP1
/operators/oprid={oprid}
Template
Mapping by
element name
Page 41
6) Resource Template Builder
Page 42
6) Response Definition
Page 43
6) Service Operation Security
Page 44
6) Assign Handler to Service Op
Page 45
7) Test Handler
Page 46
7) Test Handler
Page 47
8) Create Routing
Local-to-Local needed to use Service Operation Test utility.
Any-to-Local needed to test service outside PeopleSoft.
Page 48
9) Test Service Operation
Page 49
10) Publish Web Service
Integration Broker > Web Services > Provide Web
Services
Only need to publish if you need the WADL document.
Page 50
Test Web Service
• SOAPui friom SmartBear
• www.soapui.org
• PeopleTools SendMaster
• %PS_HOME%\sendmaster
• Any Browser (to test GET)
• Fiddler (to test GET/POST/PUT/DELETE)
Page 51
REST Security
• PeopleTools supports no authentication (ie public)
• BASIC Authorization with or without SSL
• Adds HTTP header to Request
Authorization: BASIC <oprid:password>
Page 52
Base64
Demonstration of REST
Jim Marion
• Principal Applications Technology Consultant, Oracle
• Author of two fine books on PeopleTools
• Jim’s Journal @ http://jjmpsj.blogspot.co.uk/
Page 53
Any questions
Graham Smith
PeopleSoft Technical Team Leader
Oxfam GB
gsmith@oxfam.org.uk
i-like-trains.blogspot.com
Page 54