IMS09 IMS ES SOAP Gateway - IMS UG June 2013 Sydney

IMS Enterprise Suite 2.2 SOAP Gateway June 2013With thanks to Ken Blackman

Alison Coughtrie - European IMS Architecture Team

© 2013 IBM Corporation1

Important Disclaimer

© Copyright IBM Corporation 2013. All rights reserved.

U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

THE INFORMATION CONTAINED IN THIS PRESENTATION IS PROVIDED FOR INFORMATIONAL PURPOSES

ONLY. WHILE EFFORTS WERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATION CONTAINED IN THIS PRESENTATION, IT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN ADDITION, THIS INFORMATION IS BASED ON IBM’S CURRENT PRODUCT PLANS AND STRATEGY, WHICH ARE SUBJECT TO CHANGE BY IBM WITHOUT NOTICE. THE INFORMATION ON NEW PRODUCTS IS FOR INFORMATIONAL PURPOSES ONLY AND MAY NOT BE INCORPORATED INTO ANY CONTRACT. THE INFORMATION ON ANY NEW PRODUCTS IS NOT A COMMITMENT, PROMISE, OR LEGAL OBLIGATION TO DELIVER ANY MATERIAL, CODE OR FUNCTIONALITY. THE DEVELOPMENT, RELEASE, AND TIMING OF ANY FEATURES OR FUNCTIONALITY DESCRIBED FOR OUR PRODUCTS REMAINS AT THE SOLE DISCRETION OF IBM. IBM SHALL NOT BE RESPONSIBLE

FOR ANY DAMAGES ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, THIS PRESENTATION OR ANY


FOR ANY DAMAGES ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, THIS PRESENTATION OR ANY OTHER DOCUMENTATION. NOTHING CONTAINED IN THIS PRESENTATION IS INTENDED TO, NOR SHALL HAVE THE EFFECT OF, CREATING ANY WARRANTIES OR REPRESENTATIONS FROM IBM (OR ITS SUPPLIERS OR LICENSORS), OR ALTERING THE TERMS AND CONDITIONS OF ANY AGREEMENT OR LICENSE GOVERNING THE USE OF IBM PRODUCTS AND/OR SOFTWARE.

IBM, the IBM logo, ibm.com, Information Management, IMS, and z/OS are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. If these and other IBM trademarked terms are marked on their first occurrence in this information with a trademark symbol (® or ™), these symbols indicate U.S. registered orcommon law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at “Copyright and trademark information” at ibm.com/legal/copytrade.shtml

Other company, product, or service names may be trademarks or service marks of others.

• SOAP Gateway Overview

• SOAP Gateway 2.2 Enhancements

– Advanced installation and maintenance

– Graceful shutdown

– WS-Security

Topics


– Support for multiple connection bundles for synchronous callout

applications

– Transaction tracking

– Java Management Extensions (JMX) Monitoring

IMS Enterprise Suite

• Part of the IMS SOA Integration Suite

– Collection of IMS middleware functions and tools

– Available for download from IMS Enterprise Suite Web page

ibm.com/software/data/ims/soa-integration-suite/enterprise-suite/

• Packaging method for the most current versions of selected IMS SOA

Integration Suite components

– IMS Enterprise Suite SOAP Gateway


– IMS Enterprise Suite SOAP Gateway

– IMS Enterprise Suite DLIModel Utility plug-in

– IMS Enterprise Suite Connect APIs for Java and C

– IMS Enterprise Suite IMS Explorer for Development

– IMS Enterprise Suite JMS API

• Latest Version 2.2

– SOAP Gateway 2.2.0.1 is equivalent to APAR PM78757

IMS SOAP Gateway

• A light weight Web Service solution for IMS TM access without a Java EE

Server

• Integrates IMS assets into a Service Oriented Architecture

• Provides end-to-end interactions between IMS transactions and Web services

clients in an On Demand environment

• Enables IMS as a Provider and Consumer of Web Services

• Secure

•

SOAPSOAPA standardized way of A standardized way of using XML to define using XML to define

both a message and the both a message and the target applicationtarget application


• Utilizes Advanced Tooling

– Utilizes Rational Developer for System z tooling to create converters for

transforming XML messages to IMS messages and vice versa

– No need to change existing IMS application code

Web Service Client

(.NET, SAP, java, etc.)

IMS SOAP Gateway

IMSIMS

Connect

z/OS

HTTP / SOAP TCP/IP / XML

Windows/AIX/Linux/z/OS

SOAP Envelopewith XML message XML message

IMS message

XML XML TransformerTransformer

target applicationtarget application

IMS SOAP Gateway – Web Service Provider

• .NET Client Invokes IMS COBOL Application as a Web Service

IMS SOAP Gateway …with XML AdapterXMLXML

<INPUTMSG><in_ll>32</in_ll><in_zz>0</in_zz><in_trcd>IVTNO</in_trcd><in_cmd>DISPLAY</in_cmd><in_name1>LAST1</in_name1></INPUTMSG>

z/OS

IMS Connect

IMS SOAP GatewayAdapter Task

Manager

Byte ArrayByte Array

IMS

O

32 0IVTNO DISPLAY LAST1

SOAPSOAP

<?xml version="1.0"?><soap:Envelope><soap:Body><INPUTMSG><in_ll>32</in_ll><in_zz>0</in_zz><in_trcd>IVTNO</in_trcd><in_cmd>DISPLAY</in_cmd><in_name1>LAST1</in_name1></INPUTMSG></soap:Body></soap:Envelope>


SOAP Clients

(Java, SAP, .NET)HTTP/

SOAP

<cbl:OUTPUTMSG><out_ll>93</out_ll><out_zz>0</out_zz><out_msg>ENTRY WAS DISPLAYED</out_msg><out_cmd>DISPLAY</out_cmd><out_name1>LAST1</out_name1><out_name2>FIRST1</out_name2><out_extn>8-111-1111</out_extn><out_zip>D01/R01</out_zip><out_segno>0001</out_segno>

</cbl:OUTPUTMSG>

Manager

XML Adapter

COBOL

Converters

Web Service TCP/IP

IMS

Application

O

T

M

A

93 0ENTRY WAS DISPLAYEDDISPLAYLAST1 FIRST18-111-11111D01/R01 0001

<?xml version="1.0"?><soap:Envelope><soap:Body><cbl:OUTPUTMSG><out_ll>93</out_ll><out_zz>0</out_zz><out_msg>ENTRY WAS DISPLAYED</out_msg><out_cmd>DISPLAY</out_cmd><out_name1>LAST1</out_name1><out_name2>FIRST1</out_name2><out_extn>8-111-1111</out_extn><out_zip>D01/R01</out_zip><out_segno>0001</out_segno>

</cbl:OUTPUTMSG></soap:Body>

</soap:Envelope>

The IMS Applicationcan remain unchanged

IMS SOAP Gateway – Web Service Consumer

IMS SOAP Gateway

0Resume TPIPE TP1

token

DEST1

TP1

HWS1

HWSXMLA0

XMLCNV1D

DescriptorHWS1

IMS Connect

IMSOTMA

TPIPE

TP1

IMS Application

1

XML Adapter

3

Bytes

XML

2 Send Request Msg with a correlation token

AIBTDLIDescriptor nameTimeout

IMS SOAP Gateway can act as a Web

Services Caller for

IMS, as well as provide its

traditional role as a Web

Services

Server for


ACK 5

Send

Response

8

Web Service

Provider

Invoke Web

Service57

token

XML

XML Adapter

HWSXMLA0

XML ConverterXMLCNV1D

10Bytes

IWAIT with timer4

Send Only

Response Msg

with token

6Lookup Web

Service info from

Correlator file

9

Internal flow

External flow

Server for IMS

Runtime and Development Environment

Runtime EnvironmentRuntime Environment z/OS

IMS ConnectIMS SOAP Gateway IMS

IMS

Application

Adapter Task

Manager

XML Adapter

Web ServiceSOAP Clients

(Java, SAP, .NET) HTTP/SOAP TCP/IP

O

T

M

A

SOAP

Specifies connection &

security properties e.g.

IMS Connect host

name, IMS connect

port, IMS datastore,

SSL info.


COBOL/PLI

Converters

SOAP

Gateway

Deployment

Utility

COBOL/PLI

Converters COBOL

Copybook

/PLI

structure

Correlator

File

.XML

UDDI

Registry

Execution

Generation

Development Environment Development Environment –– IBM Rational Developer for System z (RDz)IBM Rational Developer for System z (RDz)

Web Service Description

Language file – XML

document specifies

location of the service

and how the input &

output messages should

appear in order to invoke

the service

Connection Bundle

Specifies transaction

& runtime properties

e.g. XML converter

name, connection

bundle, timeout, IMS

tran code

WSDL

Rational Developer for System z

• Two limited use licenses (without support) of IBM Rational Developer for

System z are provided for each physical System z mainframe for which

IMS Version 10, Version 11, or Version 12 is licensed. Terms and

conditions are outlined in the Rational Developer for System z licensing

information. Rational Developer for System z IMS Edition can be

downloaded from the IMS Enterprise Suite download website. V8.0.3 is

the last version for which an IMS edition is made available to IMS

customers. For newer versions, you can download the trial version for


customers. For newer versions, you can download the trial version for

an evaluation period of 90 days from

ibm.com/developerworks/downloads/r/rdz/.

SOAP Gateway 2.2 enhancements


The new installation architecture

• In Version 2.2, the SOAP Gateway installation is divided into three

components:


• Server is divided into three components

– Imsserver – can be mounted as READ only

• Contains the servers executable code

– Imsbase – can be mounted as READ and WRITE

• Contains the servers configurations and log

– Imssoap - can be mounted as READ and WRITE

• Contains the user-deployed web service-related files

• WSDL's, correlators, connection bundles

– Benefits

•

Advanced installation and maintenance


• Easier to apply maintenance

• Allocate additional disk space when more web services are added without disrupting server

• IBM® Installation Manager for z/OS® V1.5.3

– Supports centralized repository delivered through the SMP/E process

– Benefits

• Simplifies maintenance process

• Multiple SOAP Gateway server instances

– Share a single instance of the Java™ Virtual Machine (JVM)

– Benefits

• Reduces the amount of storage required for each additional server instance

What is IBM Installation Manager for z/OS?

• IBM Installation Manager has been used

on distributed platforms for many years

for installing IBM products and applying

updates

• It installs from a repository

– A repository contains a

repository.config file that stores the


repository.config file that stores the

metadata on how to install and lay out

the selected packages on the system

• More and more IBM z/OS products are

using IBM Installation Manager for z/OS,

including WebSphere Application Server

for z/OS

• IBM IM for z/OS is included in IMS ES 2.2

order

Installing multiple copies of SOAP Gateway

• The SOAP Gateway repository is a

compressed file (.zip file) that you

obtain after you go through the

standard SMP/E process

– Accessible through FTP, HTTP or

shared disk

SOAP Gateway

repository

HTTP, FTP, shared disk


shared disk

• The Installation Manager for z/OS will

connect to the repository and install

SOAP Gateway

• You can install multiple copies of SOAP

Gateway from the same SMP/E

managed repository

LPAR 1 LPAR 2 LPAR 3 LPAR 4

Installation ManagerInstallation Manager

SOAPSOAP SOAP SOAPSOAP SOAPSOAP

Sysplex

The new installation process


The new installation process


Before the installation,

you will need to apply

PTF UK79476

to upgrade to V 1.5.3 of the

Installation Manager.

Advanced installation and maintenance

• Enhanced migration support of server properties

– the -migrate command is enhanced to support the migration of

server properties and web services

• supports the migration of existing server properties

• propagates the server configuration to multiple server instances

• Go to the directory where the V2.2 SOAP Gateway management utility is

: install_dir/imsserver/deploy.


: install_dir/imsserver/deploy.

– For z/OS or Linux:

./iogmgmt -migrate path_to_2.1_install_dir

– For Windows:

iogmgmt -migrate path_to_2.1_install_dir

• Benefits

– Eliminates the need to reconfigure the server

Note:

If the imsserver

component is

read-only, you

must change it to

read/write mode

before you run

the migration

tool.

Graceful Shutdown

• Enhanced Server shutdown

– Graceful shutdown: Process all in-flight messages before the

shutdown

• Blocks inbound web service requests

• Interrupts IMS Connect socket to stop further Outbound callout requests

• After 5 minutes, the server forces a shutdown


• After 5 minutes, the server forces a shutdown

– Immediate shutdown

• Discards any in-flight messages and immediately stops the server

• Benefits

– Graceful shutdown ensures all web service requests or callout

requests are processed before the server goes down

Multiple Connection Bundles for Synchronous Callout Applications

• Multiple connection bundles for synchronous callout applications

– Allows synchronous callout response messages to be returned to

the correct originating IMS Connect

• Management Utility command to specify multiple connection bundles

iogmgmt –corr … –d callout_connection_bundle_name1,

callout_connection_bundle_name2, . . .

• Benefit


• Benefit

– Enables use of multiple IMS Connects for outbound processing

IMS

ConnectA

Datastore IMS1

TCP/IPIMS SOAP Gateway Server

SOAP

HTTP

Soap

IMS1

Appl

ICAL

HTTP Port 8080

Port

9998Connection

Bundle(CBA)

Port = 9998

host = ....

Correlator1

CBB

Multiple Callout Connection Bundles


Soap

Client

ICAL

Correlator2

CBA,CBB

Connection

Bundle(CBB)

Port = 9989

host = ....

IMS

ConnectB

Datastore IMS1

Port

9989

iogmgmt -corr –u –r correlator2 –d CBA,CBB

WS-Security

• WS-Security SAML unsigned tokens for synchronous callout applications

– Originating Userid (PSTUSID) for the IMS synchronous callout application is

passed to the external web service for further authentication and

authorization

– Benefit

• Provides message-level security for synchronous callout

• WS-Security enhancement for Provider web services

–


– Support for Security Assertion Markup Language (SAML) 2.0 sender-

vouches signed tokens

– Benefit

• Provides additional message integrity for service provider processing

• Extends SOAP Gateway support of WS-Security standards

SAML is an XML-based standard developed by Security Services

Technical Committee (SSTC) of Organization for the Advancement

of Structured Information Standards (OASIS).

IMSSOAP

Gateway

IMS SOAP Gateway WS-Security SAML unsigned tokens for synchronous callout applications

z/OS

IMS

TM/CTL

ServicesIMS

Connect

HWS1

Web

Service

Application Program

ICAL

DEST1

Resume

TPIPE

TPS

TPS

DEST1

TPS

HWS1

HWSXMLA0

CORTKN

USERA

XML

USERA

Initiating ClientUSERA

CORTKN

USERA Java


HWS1 DEST1OT

MA

HWSXMLA0

XMLCNV1D

ACK

Send_ONLY

HWSXMLA0

XML ConverterXMLCNV1D

CORTKN

USERA

XML

USERA

Request

data

Response

data

XML

USERA

XML

USERA

Connection

Bundle

TPS

USERA

CORTKN

USERA

Custom

Authentication

Transaction Tracking

• SOAP Gateway transaction tracking IDs and logging

– SOAP Gateway can attach 40 byte horizontal tracking ID to inbound web

service request

• ID is sent with the inbound request through IMS Connect to the target IMS

application and returned with the response message to SOAP Gateway

– IMS Connect tracking ID captured by the IMS Connect Event Recorder exit

routine (HWSTECL0)

• This information can be consumed by the IBM IMS Connect Extensions for z/OS

Note: Transaction tracking

is not supported for

callout messages


• This information can be consumed by the IBM IMS Connect Extensions for z/OS

and equivalent tools

• For IMS 12 requires APAR PM69983/UK82576 applied to IMS Connect

– IMS log records for transactions include the tracking ID

• IBM IMS Performance Analyzer for z/OS and IBM IMS Problem Investigator for

z/OS, or equivalent tools, to inspect IMS log records

– Benefits

• Correlates transactions between SOAP Gateway, IMS Connect, and IMS

• Provides information for diagnostic purposes

Transaction tracking


– SOAP Gateway can generate a unique vertical correlation ID for

every incoming request

• used to correlate all of the SOAP Gateway message processing events

associated with a service provider request using a single unique ID

• Vertical ID is in the SOAP Gateway transaction log file if enabled

– The vertical ID is always unique and is not user configurable


– The vertical ID is always unique and is not user configurable

• Can be propagated to a remote IBM Tivoli® Composite Application

Manager for Transactions (ITCAM) if one is configured

– Note: the vertical ID is not used to identify the message at other

points in the application pathway

– Benefits

• Provides information for diagnostic purposes



– Activate and configure tracking IDs

• iogmgmt -tracking -on command

– View SOAP Gateway tracking and monitoring functions

• iogmgmt -view -soapgatewayproperties

– SOAP Gateway server transaction log file

•


• provides a complete record of every request made to a SOAP Gateway

– includes both horizontal and vertical IDs

• iogmgmt -tranLog -on -fileMaxAge 1



– Remote IBM Tivoli Composite Application Manager for Transactions

(ITCAM) data collector

• provides for remote monitoring

• 1. Start the remote transaction collector.

– Note host name (or IP address) and port number of the transaction

collector.


collector.

• 2. Start the IMS SOAP Gateway ITCAM TTAPI function

iogmgmt -tranAgent -on –address server_address -port

server_port

remote transaction collector server host address and port number

Note: Before you can use this command, you must activate SOAP

Gateway-to-IMS tracking IDs for the server with the iogmgmt -

tracking -on command.

End-to-end Transaction Tracking – Provider Scenario(correlation based on Tracking ID)

IMS ES 2.2SOAP

Gateway

IMS

Connect

O

T

M

A

IMS 13

IMS App

Horizontal

Tracking ID +

(XML) request data

message

exits*

Horizontal

Tracking ID

+ message data

Tracking ID

Horizontal

Tracking ID +

(XML) response

data + CSMHorizontal

Tracking ID +

Transaction Tracking API

Request with

optional tracking ID

response

Route / generate

Tracking ID

Soap

Client


eventexit *

message data

IMSLog record

SOAPGateway

Transaction log

Transaction Tracking API

Monitoring

data*

Horizontal and Vertical

Tracking IDs

ITCAMIMS ConnectExtensions

IMS Connect

Extensionsjournal

Problem

Investigator

Performance

Analyzer

IMS

Performance Analyzer

IMS

Problem Investigator

records events with

Tracking ID

Tracking ID

Horizontal and Vertical

Tracking IDs

SOAP Log – Input Message


BPE Trace


IMS Log Record


SOAP Log – Output Message


Transaction Events Information


JMX Monitoring

• Java Management Extensions (JMX) instrumentation for SOAP Gateway

– Standard JMX instrumentation for the SOAP Gateway JVM health-check

information

• includes heap memory and CPU utilization

– SOAPGatewayProviderMonitorMBean

• provides an interface to get statistics SOAP Gateway web service provider

workload

– Does not include callout or WebSphere Business Events statistics


– Does not include callout or WebSphere Business Events statistics

– enable monitoring functions with the SOAP Gateway management utility

• iogmgmt – mbeans – port xxx

• The xxxx value is the JMX listening port for MBean requests

– Remote monitoring application

• JConsole provides generic remote monitoring application

• user-supplied JMX-compatible monitoring application

• Benefit

– Provides JMX monitoring functions

JMX MBean interface for web service provider monitoring

• C:..\IMS Enterprise Suite V2.2\SOAP Gateway\java\bin

– JConsole.exe

IMS ES 2.2SOAP

Gateway


Provider

Monitor

MBean

Apache Tomcat

MBeansJConsole

JMX-compatible

monitoring

application

JVM

JConsole sample output


IMS ES 2.2 SOAP Gateway New Samples

• IMS Exchange web site updated - Link: ibm.com/developerworks/mydeveloperworks/blogs/8a337b1c-3c0c-48a5-b7cc-

7f805884dbb9/tags/soap?lang=en


Cobol Top Down

• Target Market

– IMS Customers who want to quickly get synchronous callout running with SOAP Gateway.

– SOAP customers who want to have multi-operation support for synchronous callout.

• Challenge Addressed

– Remove the need for COBOL copybook to generate artifacts for synchronous callout.

– Remove requirement to manually map between XSD data types and COBOL data types.

•


• Solution

– Parts needed for synchronous callout can be generated from a single WSDL.

– Multiple operations defined in WSDL are now supported within the callout correlators.

• Business Value

– Ease setup of synchronous callout for SOAP Gateway.

– Reduce errors that may occur when manually creating COBOL copy book needed for callout.

– Support multiple operations for callout.

Design


Prerequisites

• Software requirements

– Enterprise Suite V2.2 SOAP Gateway

– IMS V11 or IMS V12 with integrated IMS Connect SPE (PM69983,

PM76333)

• Tooling

– IBM Rational® Developer for System z™ Version 8.5.1 or later

–


– Installation Manager V1.5.3 or later

Any Questions?


IMS09 IMS ES SOAP Gateway - IMS UG June 2013 Sydney

Technology

Transcript of IMS09 IMS ES SOAP Gateway - IMS UG June 2013 Sydney