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
Jims 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