Transcript Document

SOA for the
Payroll/Personnel System
Web services that inquire or
update the EDB
1
Presentation Overview

New capabilities available in CICS have made it possible to expose the existing CICS programs that
underlie current EDB Entry/Update screens as Web Services. This provides an opportunity to
reinvigorate data presentation and entry by writing new web applications that require only a Web Browser
on the user’s PC. Numerous improvements in the user interface are possible as a result

Today’s presentation is in two parts


Part I - describes the design of the new CICS hosted Web Services that support web applications
under development

Part II - describes the design of new JAVA web applications
Important concepts



A WSDL is a Web Service Description Language file. Each Web Service must have a WSDL that
defines the input and output of the service
CICS Web Services are implemented using SOAP encoded XML over HTTP
In PPS there are two types of data element numbers

Scalar value – has one value assigned to the DEN

Repeating value – has a list of occurrence key/value pairs assigned to the DEN
2
`
SOAP o
ve r H
z/OS
Hosting
CICS
Web Services
(CICS TS V3.2)
TTPS
Web Application Server
3
EDB Inquiry / Update Web Service
Design Goals





Provide authentication of end users via existing userid / password
signon process
Reuse existing PPS EDB UPDATE CICS programs for
 DB2 database access
 value / range edit process
 Consistency edit process
 ARSM and $PPSFUNC authorization process
Enable creation of Web Applications that do not use SQL
Minimize the need to change the Web Services when new data
elements are added to the EDB
Provide authentication of requesting Web Application Server by the
Web Service providing CICS region to support point to point security
4
- <q0:s010_input>
<q0:s010_user_id>paypxp</q0:s010_user_id>
<q0:s010_password>secret</q0:s010_password>
<q0:s010_new_password />
</q0:s010_input>
Provide authentication of end users via existing RACF userid and password
signon



A Web Service hosted by each campus PPS
CICS region checks users id and password
entered by the end user
If the userid / password are valid a token is
created and saved in storage in the CICS
region – the user is then ‘logged on’ to a
specific region
The logged on user’s id can be fetched from
storage with the token
- <s010_output>
<s010_user_token_out>0810595977</s010_user_token_out>
<s010_return_code>0000</s010_return_code>
</s010_output>
5
Use existing CICS


- <q0:PS006INPUT>
-<q0:webserv_user_token_in>0810595977</q0:webserv_user_token_in>
<PS001OUT xmlns="http://www.PS001O.com/schemas/PS001OInterface">
<ps001_return_cd>0000</ps001_return_cd>
<q0:ps006_request_code
/>
DB2
database access
-<q0:ps006_action_code
<ps001_return_entry>
/>
<ps001_return_data_elem_no>0001</ps001_return_data_elem_no>
<ps001_return_occur_key>010020</ps001_return_occur_key>
<q0:ps006_input_employee_id>000000001</q0:ps006_input_employee_id>
<ps001_return_value>2006-03-16</ps001_return_value>
- <q0:ps006_input_element_array>
<ps001_return_data_type>D</ps001_return_data_type>
<ps001_return_de_num_sw />
- <q0:ps006_input_element_entry>
</ps001_return_entry>
<q0:ps006_input_data_elem_no>0108</q0:ps006_input_data_elem_no>
….
<q0:ps006_input_occur_key />
- <ps001_return_entry>
<q0:ps006_input_value>M</q0:ps006_input_value>
<ps001_return_data_elem_no>0105</ps001_return_data_elem_no>
</q0:ps006_input_element_entry>
- <PS006OUTPUT
<ps001_return_occur_key />
</q0:ps006_input_element_array>
xmlns="http://www.PS006O.com/schemas/PS006OInterface">
<ps001_return_value>PRESIDENT,EXEC</ps001_return_value>
<ps001_return_data_type>A</ps001_return_data_type>
</q0:PS006INPUT>
<ps006_return_code>0000</ps006_return_code>
- <q0:PS001IN>
<ps001_return_de_num_sw />
<ps006_msg_number>U0007</ps006_msg_number>
<q0:ps001_req_emp_id>000000001</q0:ps001_req_emp_id>
</ps001_return_entry>
<ps006_msg_text>U0007
Update process complete</ps006_msg_text>
<q0:webserv_user_token_in>0810595977</q0:webserv_user_token_in>
….
</q0:PS001IN>
<ps006_output_employee_id>000000001</ps006_output_employee_id>
- <ps001_return_entry>
- <ps006_output_element_array>
<ps001_return_data_elem_no>6000</ps001_return_data_elem_no>
- <ps006_output_element_entry>
<ps001_return_occur_key>008U</ps001_return_occur_key>
<ps001_return_value>22,000.00</ps001_return_value>
<ps006_output_data_elem_no>0108</ps006_output_data_elem_no>
<ps001_return_data_type>N</ps001_return_data_type>
<ps006_output_occur_key
/>
<ps001_return_de_num_sw />
PPEDBFET for inquiry
PPEDBUPD for update
<ps006_output_value>M</ps006_output_value>
<ps006_data_elem_status>0</ps006_data_elem_status>
</ps006_output_element_entry>
</ps006_output_element_array>
<ps006_output_conedit_array />
</PS006OUTPUT>
6
Use existing CICS value / range edit process

PPVREDO
- <q0:PS015INPUT>
<q0:webserv_user_token_in>0810595977</q0:webserv_user_token_in>
<q0:s015i_request_code>1</q0:s015i_request_code>
- <q0:s015i_element_array>
- <q0:s015i_element_item>
- <PS015OUTPUT
<q0:s015i_elem_number>1171</q0:s015i_elem_number>
xmlns="http://www.PS015O.com/schemas/PS015OInterface">
<q0:s015i_entered_data>22</q0:s015i_entered_data>
<s015o_return_code>00001</s015o_return_code>
<q0:s015i_related_data />
<s015o_return_msg>Element errors encountered</s015o_return_msg>
</q0:s015i_element_item>
- <s015o_element_array>
- <q0:s015i_element_item>
- <s015o_element_item>
<q0:s015i_elem_number>1171</q0:s015i_elem_number>
<s015o_elem_number>1171</s015o_elem_number>
<q0:s015i_entered_data>15</q0:s015i_entered_data>
<s015o_entered_data>22</s015o_entered_data>
<q0:s015i_related_data />
<s015o_edb_data />
</q0:s015i_element_item>
<s015o_screen_data>22</s015o_screen_data>
</q0:s015i_element_array>
<s015o_elem_status_code>1</s015o_elem_status_code>
</q0:PS015INPUT>
</s015o_element_item>
- <s015o_element_item>
<s015o_elem_number>1171</s015o_elem_number>
<s015o_entered_data>15</s015o_entered_data>
<s015o_edb_data>15</s015o_edb_data>
<s015o_screen_data>15</s015o_screen_data>
<s015o_elem_status_code>0</s015o_elem_status_code>
</s015o_element_item>
7
</s015o_element_array>
</PS015OUTPUT>
===== Examples of the type of changes needed in UCROUTER ========
**************************************************************
* INCLUDE WEB SERVICE EXTERNAL
**************************************************************
01 CPWSWEBS-WEB-INFO EXTERNAL.
COPY CPWSWEBS.
Use existing CICS conedit process

UCROUTER
Minor changes to
UCROUTER allow
reuse of existing
EDB update
process.
****************************************************************
* FOR A WEB SERVICE CALL, IDENTIFY AN INITIAL CALL THROUGH
* THE CPWSWEBS EXTERNAL RATHER THAN EIBCALEN
****************************************************************
IF CPWSWEBS-WEB-CALL
IF CPWSWEBS-WEB-INITIAL-CALL
PERFORM 0200-SETUP
ELSE
PERFORM 0300-ITERATION
END-IF
ELSE
IF EIBCALEN = ZERO
PERFORM 0200-SETUP
ELSE
PERFORM 0300-ITERATION
END-IF
***************************************************************
* DON'T ISSUE CICS RETURN FOR A WEB SERVICE CALL. MUST GO
* BACK TO CALLING PROGRAM.
***************************************************************
IF CPWSWEBS-WEB-CALL
GOBACK
ELSE
EXEC CICS
RETURN
END-EXEC
8
END-IF
Use existing CICS ARSM and $PPSFUNC authorization process


UCPPPEDB
UCFNAUTH
Call from Web Services to
check ARSM rules
Call from Web Services to check $PPSFUNC
RACF resources
9
Enable creation of Web Applications that do not use SQL


Existing CICS screen handling programs
provide Entry / Update access to the EDB
without SQL
Web Applications using PPS Web Services
provide Entry / Update access to the EDB
without SQL
Eliminates vulnerability of Web
Applications to SQL injection
Design increases reusability of the
Web Application since it is decoupled
from the datastore
10
Minimize the need to change the Web Services when new data
elements are added to the EDB


Identify data by data element
number/occurrence key
The following changes will be reflected in web services
without the need to change them:
• new data element added to the EDB
• changes to value range edits made via the DET table
• changes to the conedit process made via the DET,
PGT, RTD
Using data element number/occurrence key
to identify data makes using the Web Service
harder
11
Point to point security
`
Client Certificate
sent to CICS
region for client
authentication.
Server Certificate
Sent to Web
Application
Server for Server
authentication
SSL wit
h Serve
z/OS
Hosting
CICS
Web Services
r authen
tication
and Clie
nt authe
SS
L
ntication
Web Application Server
12
Provide authentication of requesting Web Application Server

An X.509 digital certificate identifying the
client server is required by all Web Services
hosted by PPS CICS regions to support client
authentication during the SSL handshake
13
End Part I
14
Consuming PPS Web
Services Services in
Java
From XML to Business Domain
Objects
15
XML to Domain Objects



Focus of this talk
SOAP message to Employee object
Where the rubber meets the road
16
Technology Stack: Glassfish
Metro




Sun’s WS implementation
Current state-of-the-art
Performance improvements over others
Cleaner generated code
QuickTime™ and a
decompressor
are needed to see this picture.
17
Steps from XML to Domain
Objects




WSDL import tool
Binding Customizations
Domain Interface/Adapter Strategy
Domain-Level Marshalling
18
Step One: Generate Client
Code

wsimport




WS tool included in Metro & J6SE
WSDL to framework classes
Handles XML manipulation & connection code
Schema bindings


Complex types map to classes
Elements to properties
19
PS001: EDB Employee Fetch
<complexType name="PS001IN">
<sequence>
<element form="qualified" name="ps001_req_emp_id">
<annotation>
<appinfo source="http://www.wsadie.com/appinfo">
<initialValue kind="SPACE"/>
</appinfo>
</annotation>
<simpleType>
<restriction base="string">
<maxLength value="9"/>
</restriction>
</simpleType>
</element>
[…]
</sequence>
</complexType>
20
Generated Code
public class PS001IN {
[….]
/**
* Gets the value of the ps001ReqEmpId property.
*
* @return
* possible object is
* {@link String }
*
*/
public String getPs001ReqEmpId() {
return ps001ReqEmpId;
}
21
Step Two: Customization
Bindings




”getPs001ReqEmpId” may not be our first
choice for naming
wsimport supports customized bindings
Use standard JAX-WS and JAXB bindings
Use XPath to find type/element to affect
22
Typical Customizations




Package name
Class names
Method names
Enumerations


Especially useful when service sends status
codes
Javadoc on generated classes
23
Example: PS001 JAXB
bindings
<jaxb:bindings
schemaLocation="file:PS001.wsdl#types?schema1"
node="/xs:schema/xs:complexType[@name='PS001IN']">
<jaxb:class name="PS001Input">
<jaxb:javadoc>
Wrapper around input values to service.
</jaxb:javadoc>
</jaxb:class>
</jaxb:bindings>
<jaxb:bindings
schemaLocation="file:PS001.wsdl#types?schema1"
node="//xs:element[@name='ps001_req_emp_id']">
<jaxb:property name="employeeId">
<jaxb:javadoc>
Identifies the employee for whom all non-initial EDB data elements should be
returned.
</jaxb:javadoc>
</jaxb:property>
</jaxb:bindings>
24
Example: Result
public class PS001Input
implements Serializable
{
[....]
/**
*
*
Identifies the employee for whom all non-initial EDB data elements should be
returned.
*
*
* @return
* possible object is
* {@link String }
*
*/
public String getEmployeeId() {
return employeeId;
}
25
Client Operation Becomes
Simple
EmpDataService ps001EmplFinder =
new PS001Service().getPS001Port();
PS001Input inputPayload = new PS001Input();
inputPayload.setEmployeeId( TEST_EMP_ID );
inputPayload.setUserToken( token );
PS001Output employeeData =
ps001EmplFinder.getEmpData(inputPayload);
26
A Good Start But Not Enough


PS001 for example returns an unbounded
array of data element number/occurrence
key/value elements
Would be nice to convert this data into
domain object


Employee with named fields
For example, name, last action, list of
appointments
27
Step Three, First Half:
Employee Interface



Business domain representation
Named field for each data element
Append DEN for reference

public String getName0105();

Reusable business object

Question: how do we bridge the gap from
web service return data to these fields?
28
Step Three, Second Half:
Adapter Strategy


Mediates between client code and domain object
Responsible for parsing WS return payload
/**
* Provides an adapter layer between the raw PS010 return data and an
<code>EDBEmployee</code> type.
*
* @author shunter
*
*/
public interface EDBEmployeeAdapter {
/**
* Transform the raw service data into an employee object with named fields for each data
element.
* @param ps001OutputPayload the full set of data element/value strings returned by the service
* @return an employee object.
*/
public EDBEmployee parseEmployee( PS001Output ps001OutputPayload );
29
Implementation Strategy


Adapter Impl puts all returned values into one
of two maps
Scalar values


DEN => value
Repeating

DEN => list of occurrence key/value pairs
30
Map-Backed Employee Impl


Implement each named field getter with access to
map
Scalar:
public String getArmdFrcesSrvc0344() {
return scalarDataElemValues.get( "0344" );
}
Repeating:
public String getAdditionalTax6011G() {
String value = null;
Map<String,String> occurrences = repeatingDataElemsAsMaps.get( "6000" );
if( occurrences != null ){
value = occurrences.get( "011G" );
}
return value;
}
31
Help with Special Datasets

Complex repeating sets of data elements



Leave Accrual
Appointments and distributions
Adapter parses these into data structures
available in the Emp obj
public List<IAppointment> getAppointmentList();
32
Leave Accrual Data
8024/
8023/
8022/
8104/
8111/
8118/
8125/
8101/
8108/
8115/
8122/
8027/
8026/
8025/
8107/
8114/
8121/
8128/
8102/
8109/
8116/
8123/
8106/
8113/
8120/
8127/
8103/
8110/
8117/
8124/
8105/
8112/
8119/
8126/
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
PER01
BYPASS
CYC TP
END DT
HR CD1
HR CD2
HR CD3
HR CD4
KEY1
KEY2
KEY3
KEY4
LOST P
LOST S
LOST V
P ACR1
P ACR2
P ACR3
P ACR4
PLAN1
PLAN2
PLAN3
PLAN4
S ACR1
S ACR2
S ACR3
S ACR4
TWRD1
TWRD2
TWRD3
TWRD4
V ACR1
V ACR2
V ACR3
V ACR4
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
8030/
8029/
8028/
8132/
8139/
8146/
8153/
8129/
8136/
8143/
8150/
8033/
8032/
8031/
8135/
8142/
8149/
8156/
8130/
8137/
8144/
8151/
8134/
8141/
8148/
8155/
8131/
8138/
8145/
8152/
8133/
8140/
8147/
8154/
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
LV
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
PER02
BYPASS
CYC TP
END DT
HR CD1
HR CD2
HR CD3
HR CD4
KEY1
KEY2
KEY3
KEY4
LOST P
LOST S
LOST V
P ACR1
P ACR2
P ACR3
P ACR4
PLAN1
PLAN2
PLAN3
PLAN4
S ACR1
S ACR2
S ACR3
S ACR4
TWRD1
TWRD2
TWRD3
TWRD4
V ACR1
V ACR2
V ACR3
V ACR4
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
33
Step Four: Application-Level
Marshalling

Strictly speaking marshalling means


Java datatypes => XML
We need domain object => Java WS client
objects


Client expects simple key/value pair objects
DEN => “[some string value]”
34
Update Service Input Client
public void setPs006InputDataElemNo(String value) {
this.ps006InputDataElemNo = value;
}
public void setPs006InputOccurKey(String value) {
this.ps006InputOccurKey = value;
}
public void setPs006InputValue(String value) {
this.ps006InputValue = value;
}
35
Domain Object into Client
Framework Class

Iterate on key sets for each map



Scalar
Repeating
Pull each stored value/list, add to service
input object
36
Conclusions


Exposing mainframe logic/data a great thing
Current java WS tools ease development


Autogenerate clients that are easy to use
Further programming strategies needed

Bridge gap from client objects to domain objects
37