z/O S C o nn e ct E n t e rp r i s e E di ti o n IBM€¦ · z/O S C o nn e ct E n t e rp r i s e E...

z/OS Connect Enterprise Edition

z/OS Connect Enterprise EditionVersion 2 Release 0

IBM

NoteBefore using this information and the product it supports, read the information in “Notices” on page 331.

This edition applies to the IBM Version 2 Release 0 (product number 5655-CEE) and to all subsequent releases andmodifications until otherwise indicated in new editions.

© Copyright IBM Corporation 2015, 2017.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Chapter 1. What is IBM z/OS ConnectEnterprise Edition? . . . . . . . . . . 1z/OS Connect EE concepts . . . . . . . . . 3API design and workflow . . . . . . . . . . 4The z/OS Connect EE Build Toolkit . . . . . . 5

Chapter 2. z/OS Connect EE changehistory . . . . . . . . . . . . . . . 7

Chapter 3. Sources of information . . . 15

Chapter 4. Scenarios. . . . . . . . . 17Develop an API to invoke a CICS service via WOLA 17

Prerequisites . . . . . . . . . . . . . 17Configuring the CICS Catalog Manager exampleapplication . . . . . . . . . . . . . 18Configuring CICS to use WOLA . . . . . . 19Generate a service archive from a CICS COBOLcopybook . . . . . . . . . . . . . . 20Create an API using z/OS Connect EE APIEditor . . . . . . . . . . . . . . . 22Configuring the z/OS Connect EE server to useWOLA . . . . . . . . . . . . . . . 29Deploying an API to the z/OS Connect EE server 31Test the scenario . . . . . . . . . . . . 32

Develop an API to invoke a CICS service using theCICS service provider . . . . . . . . . . . 38

Prerequisites . . . . . . . . . . . . . 38Configuring the CICS Catalog Manager exampleapplication . . . . . . . . . . . . . 38Generate a service archive from a CICS COBOLcopybook . . . . . . . . . . . . . . 39Deploying an API to the z/OS Connect EE server 42Test the scenario . . . . . . . . . . . . 42

Create an IMS mobile service . . . . . . . . 48Prerequisites . . . . . . . . . . . . . 49Restrictions . . . . . . . . . . . . . 49Request and response messages for IMS mobileservices. . . . . . . . . . . . . . . 50High-level language and JSON schema mapping 51IMS service creation workflow . . . . . . . 54Tutorial: Create an IMS mobile service . . . . 54

Develop an API to invoke an IMS service . . . 66Prerequisites . . . . . . . . . . . . . 67API creation workflow for IMS mobile services 67Tutorial: Create a REST API for an IMS mobileservice . . . . . . . . . . . . . . . 68

Configure an HA environment that uses the WOLAservice provider . . . . . . . . . . . . . 85

Prerequisites . . . . . . . . . . . . . 86Setting up HA for the first server . . . . . . 91Adding a second server . . . . . . . . . 94Testing the scenario. . . . . . . . . . . 96Further capabilities of the HA scenario . . . . 97

Configure an HA environment that uses the IMSservice provider . . . . . . . . . . . . 102

Prerequisites. . . . . . . . . . . . . 103Setting up HA for the first server. . . . . . 104Adding a second server . . . . . . . . . 107Testing the scenario . . . . . . . . . . 108

Chapter 5. Installation information . . 111Requirements . . . . . . . . . . . . . 111Installing z/OS Connect EE . . . . . . . . 112

Creating the z/OS Connect EE shared directory 112Setting up the product extensions directory . . 113

Installing the z/OS Connect EE Build Toolkit . . . 114Updating z/OS Connect EE . . . . . . . . 115Installing z/OS Explorer and the z/OS Connect EEAPI Editor . . . . . . . . . . . . . . 115Updating z/OS Explorer and the z/OS Connect EEAPI Editor . . . . . . . . . . . . . . 116Migrating from z/OS Connect V1 . . . . . . 116

Chapter 6. Configuring . . . . . . . 119Creating a z/OS Connect Enterprise Edition Server 119Configuring services . . . . . . . . . . . 121Using the WOLA service provider . . . . . . 122

Configuring CICS to use WebSphere optimizedlocal adapters (WOLA) . . . . . . . . . 124Registering CICS with the WebSphere optimizedlocal adapter (WOLA) . . . . . . . . . 127

Using the IMS service provider . . . . . . . 129Operational requirements . . . . . . . . 130IMS service security process flow. . . . . . 130Configuring for the IMS service provider . . . 133Verifying server communication with IMS . . . 135Upgrading from the IMS Mobile Feature Pack inIMS Enterprise Suite . . . . . . . . . . 136IMS mobile service definition . . . . . . . 137IMS mobile service registry, in-memory cache,and administrative services. . . . . . . . 139Security configuration for the IMS mobilesolution . . . . . . . . . . . . . . 140Deploying an IMS service to a different targetserver . . . . . . . . . . . . . . . 144

Using other service providers . . . . . . . . 145Configuring the z/OS Connect EE REST clientservice. . . . . . . . . . . . . . . . 145Configuring interceptors. . . . . . . . . . 148

Configuring the file system logger interceptor 150Auditing and tracking . . . . . . . . . 153Configuring API specific interceptors . . . . 156

Configuring Data Transformers . . . . . . . 157Creating bind and schema files . . . . . . 158

Configuring SARs . . . . . . . . . . . . 159Configuring APIs . . . . . . . . . . . . 160Configuring Cross-Origin Resource Sharing on az/OS Connect Enterprise Edition Server . . . . 161

© Copyright IBM Corp. 2015, 2017 iii

Server configuration updates on demand . . . . 162Using an MBean to trigger updates . . . . . 163Invoking the FileNotificationMBean from a javaprogram . . . . . . . . . . . . . . 163Invoking FileNotificationMBean from the RESTAPI. . . . . . . . . . . . . . . . 165The FileTransferMBean . . . . . . . . . 165

Chapter 7. High availability . . . . . 167Workload distribution . . . . . . . . . . 167

TCP/IP port sharing . . . . . . . . . . 168Sysplex distributor . . . . . . . . . . 169Workload distribution between z/OS ConnectEE servers and service provider SORs . . . . 169WLM Classification . . . . . . . . . . 169

Sharing server configuration . . . . . . . . 170Splitting server configuration information . . . 170Server-specific configuration elements . . . . 171Location of shared configuration files . . . . 171

Maintenance of API and service deployments . . 172Administration and Operation Tasks in an HAenvironment. . . . . . . . . . . . . . 173

Stopping and starting z/OS Connect EE serversin an HA environment . . . . . . . . . 173Management of z/OS Connect EE APIs andservices in an HA environment . . . . . . 173

Chapter 8. Securing . . . . . . . . 177Overview of z/OS Connect EE security . . . . 177Configuring security for z/OS Connect EE . . . 180

Configuring security with a basic user registry 181Configuring security with SAF registries . . . 183

Configuring the Liberty angel process and z/OSauthorized services . . . . . . . . . . . 185

Chapter 9. Operating . . . . . . . . 189Starting and stopping z/OS Connect EE . . . . 189System Automation . . . . . . . . . . . 189

Chapter 10. Building a ServiceArchive (SAR) by using the BuildToolkit . . . . . . . . . . . . . . 193Building a SAR for the REST client . . . . . . 193Building a SAR for the IMS service provider . . . 194Building a SAR for the WOLA service provider 196Building a SAR from the command line . . . . 198Building a SAR with the z/OS Connect EE BuildToolkit SDK . . . . . . . . . . . . . . 199

Chapter 11. Designing and buildingAPIs in the API Editor . . . . . . . . 201RESTful web services and API design . . . . . 201Designing RESTful APIs . . . . . . . . . . 203z/OS Connect EE API Editor for defining yourAPIs . . . . . . . . . . . . . . . . 210Tips for using the API Editor for HTTP-to-JSONmapping . . . . . . . . . . . . . . . 213Handling the null type in JSON schema . . . . 215Setting preferences for the API Editor . . . . . 215

Connecting to a z/OS Connect EE server . . . . 216Configuring client certificates for serverconnections . . . . . . . . . . . . . . 217Creating a REST API . . . . . . . . . . . 219

Generating a service archive . . . . . . . 219Creating an API project . . . . . . . . . 220Modeling an API with the API Editor . . . . 220Defining HTTP-to-JSON mapping . . . . . 221Deploying an API in the API Editor . . . . . 223

Editing an existing API . . . . . . . . . . 224Re-importing changed services . . . . . . . 225Generating an API archive . . . . . . . . . 225Examining, testing, starting and stopping an API 226

Installing and trusting a self-signed certificatefor Swagger UI . . . . . . . . . . . . 227

Developing applications with Swagger documents 229Documenting your API using Swagger . . . . . 230

Chapter 12. Administering SARs . . . 231Automated SAR management . . . . . . . . 231Overriding SAR properties . . . . . . . . . 231

Chapter 13. Administering APIs . . . 233Automated API management . . . . . . . . 233Using the API Deployment utility . . . . . . 233

Deploying an API . . . . . . . . . . . 234Undeploying an API . . . . . . . . . . 235

Using the RESTful administration interface . . . 235GET a list of APIs . . . . . . . . . . . 236GET details of an API . . . . . . . . . 237GET a Service Archive (SAR) . . . . . . . 238Deploying an API . . . . . . . . . . . 238Update an API . . . . . . . . . . . . 240Change the status of an API . . . . . . . 241Delete an API . . . . . . . . . . . . 242

Chapter 14. Client applicationdevelopment. . . . . . . . . . . . 245The z/OS Connect EE administration interface . . 245Conversion for z/OS Connect Enterprise Editiondata transformation . . . . . . . . . . . 250Interacting with COBOL and TSO/ISPF . . . . 256Error responses. . . . . . . . . . . . . 261

Chapter 15. Extending z/OS ConnectEE . . . . . . . . . . . . . . . . 263Creating a z/OS Connect EE service provider . . 263Creating a z/OS Connect EE service at run time 263Creating a z/OS Connect EE interceptor . . . . 264Creating a z/OS Connect EE data transformer . . 265

Using the DataxFormExt interface . . . . . . 265

Chapter 16. Resolving problems . . . 267Enabling z/OS Connect EE server trace . . . . 267Clearing or examining the IMS service in-memorycache . . . . . . . . . . . . . . . . 268Contacting IBM Software Support . . . . . . 268

iv z/OS Connect Enterprise Edition: z/OS Connect Enterprise Edition

Chapter 17. Messages. . . . . . . . 271IMS service provider (IMS Mobile feature)messages . . . . . . . . . . . . . . . 271

GMOBA messages. . . . . . . . . . . 271GMOCR messages. . . . . . . . . . . 273GMOIG messages . . . . . . . . . . . 274GMOMW messages . . . . . . . . . . 276GMOPR messages . . . . . . . . . . . 278GMOSR messages . . . . . . . . . . . 279GMOTM messages . . . . . . . . . . 280

Chapter 18. Reference . . . . . . . 283Configuration elements . . . . . . . . . . 283

Command reference . . . . . . . . . . . 328apideploy command syntax . . . . . . . 328zconbt command syntax. . . . . . . . . 329zosconnect command syntax . . . . . . . 329zconsetup command syntax . . . . . . . 330

Notices . . . . . . . . . . . . . . 331

Glossary . . . . . . . . . . . . . 335

Index . . . . . . . . . . . . . . . 345

Contents v

vi z/OS Connect Enterprise Edition: z/OS Connect Enterprise Edition

Chapter 1. What is IBM z/OS Connect Enterprise Edition?

IBM® z/OS® Connect Enterprise Edition provides a framework that enables z/OSbased programs and data to participate fully in the new API economy for mobileand cloud applications.

IBM z/OS Connect Enterprise Edition V2.0 provides access to z/OS subsystems,such as CICS®, IMS™, WebSphere® MQ, DB2®, and Batch, that use RESTful APIswith JSON formatted messages. The framework provides concurrent access,through a common interface, to multiple z/OS subsystems.

z/OS Connect EE can help to deliver benefits for an enterprise in two ways.v It provides an intuitive workstation-based tool, the z/OS Connect EE API Editor,

that enables a developer, with or without z/OS skills, to create RESTful APIsfrom traditional z/OS based assets. The core business assets that run on z/OScan easily be adapted to the latest mobile and cloud communication techniquesand message protocol formats.

v Mobile and cloud application developers, inside or outside the enterprise, canincorporate z/OS data and transactions into their applications without the needto understand z/OS subsystems. The z/OS resources appear as any otherRESTful API.

Cloud and mobile applications reshape the way enterprises and systems interact.RESTful APIs that use JSON message formats are the predominant standards fornew application development. z/OS subsystems participate in these newapplication development standards so that application developers can use z/OSbased services and data for development of new applications.

The following diagram shows how z/OS Connect EE connects mobile and cloudapplications with z/OS assets:

Application user

z/OS LPAR

z/OS Connect EE z/OS Address Space

API ServiceService

Provider

z/OS

Asset

Figure 1. An illustration of z/OS Connect EE connecting mobile and cloud applications with z/OS assets.

© Copyright IBM Corp. 2015, 2017 1

Benefits of using z/OS Connect EE

Using z/OS Connect EE has the following benefits:v Provides a standard framework to support service providers that you can write

yourself, or can be supplied with the System of Record (SoR). The serviceprovider forwards requests to the SoR.

v Provides a unified, extensible approach for discovery and invocation of RESTfulAPIs and services for z/OS based business assets, opening up these assets tocloud and mobile-based Systems of Engagement (SoE) environments.

v Provides functions that are based on Liberty server technology. It is lightweightand easily configurable, provides z/OS differentiation with SystemAuthorization Facility (SAF) security, and z/OS Workload Manager (WLM)integration. WLM integration means different URIs can have varying levels ofpriority and performance criteria.

Note: Do not attempt to run your own applications in the same Liberty serverwhere z/OS Connect EE is running. Such usage is not supported.

v Provides security for individual or groups of z/OS Connect EE APIs andservices with SAF security. Only specified users or groups have access tospecified services.

v Can uniformly track requests from cloud, mobile, and web environments byusing z/OS System Management Facility (SMF) services. This tracking meansthat z/OS customers can use their existing processes for auditing andchargeback for requests from these environments.

v Can automatically convert the request payload from JSON form on input tobinary form. The binary form is consumable by z/OS applications such asCOBOL, PL/I, and C. For the response from the z/OS application, the outputcan be converted from binary.

z/OS Connect EE includes a new deployment artifact, called an API package,which can be deployed to the z/OS Connect EE run time as a z/OS-based RESTfulAPI. These RESTful API definitions, which are created by the supplied z/OSConnect EE API Editor, include Swagger 2.0 standard descriptions. Thedescriptions instruct other application developers how to use the API. z/OS assetsappear to mobile and cloud developers as any other system that provides RESTfulAPI services. An enterprise API catalog can be populated with z/OS ConnectEE-hosted APIs alongside any other provider and can be used in the same way.

This API package deployment can be done manually or it can be automated byextending an existing enterprise change control process. The associated deploymentcapabilities provide an enterprise with the ability to meet the demands of thefast-paced API economy. z/OS Connect EE includes a significant new mappingcapability that is used before the transformation from JSON messages to therequired format of the z/OS subsystems. This mapping capability adds a powerfulabstraction layer between the API consumer and the underlying z/OS assets andallows inline manipulation of requests, such as the mapping of HTTP headers,pass-through, redaction, or defaulting of JSON fields.

The API mapping functions improve the productivity of the z/OS developer in thecreation of RESTful APIs.

2 z/OS Connect Enterprise Edition: z/OS Connect Enterprise Edition

z/OS Connect EE conceptsUnderstand the terms used in z/OS Connect EE before you get started with z/OSConnect EE.

Service providers

A z/OS Connect EE service provider forwards requests to a System of Record(SoR).

You can write your own service provider or you can use one that is supplied withthe SoR to plug into the framework. Both WOLA and IMS service providers areincluded with z/OS Connect EE. Service providers must implement thecom.ibm.zosconnect.spi.Service SPI. The WOLA service provider can be used byboth CICS and Batch.

Interceptors

z/OS Connect EE interceptors provide you with the ability to execute some logicaround a request so you can control operations, service provider calls, and APIs.

Interceptors are written and delivered by any component to plug into theframework. The framework allows for any number of qualities of service to beinjected around the invocation of a service. For more information on using theinterceptors see “Configuring interceptors” on page 148.

z/OS Connect EE provides three interceptors:v An audit interceptor, used to log SMF data for incoming requests. It records

z/OS SMF records of request data around z/OS Connect EE operations, such asstart, stop, and invoke. For instructions on using the audit interceptor see“Auditing and tracking” on page 153.

v An authorization interceptor that allows users belonging to certain groups(administration, operator, invoke) to perform certain requests. The interceptorprovides z/OS, SAF and LDAP authorization checks for operations such as start,stop, and invoke. For instructions on using the authorization interceptor see“Configuring security for z/OS Connect EE” on page 180.

v A file system logger interceptor, which enables users to log request informationin a system file. For instructions on using the file system logger interceptor see“Configuring the file system logger interceptor” on page 150.

Data transformation providers

z/OS Connect EE provides the ability to optionally transform request and responsepayloads that are used for calling a business asset on operating systems.. Datatransformers are written and delivered by any component to plug into theframework. A data transformer is included with z/OS Connect EE:com.ibm.zosconnect.xform.service. It provides JSON to and from byte arrays thatare consumable by COBOL, PL/I, and C programs on z/OS.

Using z/OS Connect EE for message payload transformations

IBM z/OS Connect EE provides the ability to optionally do a conversion of therequest and response payloads that are used for calling a business asset on z/OS.

Chapter 1. What is IBM z/OS Connect Enterprise Edition? 3

Payload transformers can be created to satisfy specific needs by implementing therequired DataXform SPI provided by z/OS Connect EE. Payload conversion isenabled by adding a reference in the configuration to a data transformationimplementation.

z/OS Connect EE provides an implementation that requires that the request andresponse message format be JSON. It supports the conversion of the request to abyte array, which can be mapped by a COBOL, PLI, or C structure. The targetprogram's structure, or copybook (description of its parameters in/out) is used togenerate a binding file and JSON schema files by using a utility that is providedwith z/OS Connect EE. The bind file that is generated by this utility is used byz/OS Connect EE to do the data conversion between JSON and native dataformats as requests arrive and responses are returned. The JSON schemas for therequest and response message can be retrieved with a provided REST API call.

Process types on z/OS

For the Liberty runtime environment on the z/OS platform, there are two types ofprocess: the server process and the angel process.

Note:

There can only be a single instance of the angel process running on an LPAR. Ifyou have multiple products installed which require the angel process, then toensure you have the latest function, you must run the angel process with thehighest level of Liberty profile code that is shipped with any of those products.

For more information, see Process types on z/OS in the WebSphere ApplicationServer documentation.

API design and workflowBefore you plan to create your APIs for a service, consider some design issues andrequirements to ensure a smooth workflow.

Examine the following general workflow and gather the requirements for resourcesthat need to be exposed.1. Generate a service archive.v Depending on the z/OS subsystem, use the related tool to generate the

service archive. For example, for IMS, use IMS Enterprise Suite Explorer forDevelopment. For CICS access through the WebSphere Optimized LocalAdapters (WOLA), use the BAQLS2JS and BAQJS2LS utilities.

v Determine the resources that need to be exposed in the API. Expose allfields that might be needed for creating the REST API.

2. Design and create the API by using the z/OS Connect EE API Editor. For anoverview of the API Editor, see the Using the API editor in IBM z/OS ConnectEE article on developerWorks.v A Swagger document is generated, along with the HTTP-to-JSON mapping

and other API- and service-related information.v If necessary, edit the generated Swagger document in the editor. Do so before

you export your API project into an API archive.3. Deploy the API to a connected server.v You can deploy the API directly from within the editor by right-clicking the

API project and selecting the corresponding menu item.


https://www.ibm.com/support/knowledgecenter/SS7K4U_liberty/com.ibm.websphere.wlp.zseries.doc/ae/cwlp_zos_runtime_proc.html

https://developer.ibm.com/mainframe/2016/11/21/using-the-api-editor-in-ibm-zos-connect-ee/

https://developer.ibm.com/mainframe/2016/11/21/using-the-api-editor-in-ibm-zos-connect-ee/

v You can also deploy the API by using the apideploy -deploy command. Withthis approach, you export the API project as an API archive (AAR) file.

4. As a software source code management best practice, save a copy of the APIproject in your source code management system (SCM).

5. Examine and test your API in the editor by using the embedded Swagger UI.6. Generate client code (such as downloading the open source code from Swagger,

or import the Swagger document into IBM API Connect).

The z/OS Connect EE Build ToolkitThe Build Toolkit is used by third-party vendors, service providers, and users togenerate SAR files that are needed to enable APIs to connect to back endapplications.

The Build Toolkit is supplied in a compressed file called zconbt.zip that you candownload from the product installation directory. When you install a z/OSConnect EE server instance, you automatically have access to the zconbt.zip file.The compressed file contains both the command line interface (CLI) and SoftwareDevelopment Kit (SDK) versions of zconbt. A readme file that contains instructionson how to use zconbt is included in the package.

File structure of zconbt.zip

The following directories are contained in the compressed file:

bin Contains utility files that are used by zconbt.

lib Contains the Java™ classes.

pluginsIncludes REST, and IMS as standard and extensible to third-parties.

doc Contains the Javadoc files.

Running the Build Toolkit

The following example illustrates the syntax of the zconbt command as written onthe command line:

zconbt -p <properties filename> -f <output filename>

In this example, <properties filename> is the name of the properties file that containsthe configuration of the service. <output filename> is the path and file name of thearchive file that is created and must have a file type of .sar.

When you run this command, a return message indicates if the archive file wasbuilt successfully.Related concepts:Chapter 10, “Building a Service Archive (SAR) by using the Build Toolkit,” on page193You can use either the command line interface or the SDK to build your SAR filefor the REST client and for IMS services.Related tasks:“Installing the z/OS Connect EE Build Toolkit” on page 114Install the z/OS Connect EE Build Toolkit to create Service archive (SAR) files.

Chapter 1. What is IBM z/OS Connect Enterprise Edition? 5

Chapter 2. z/OS Connect EE change history

Use this information to discover the enhancements in each refresh of IBM z/OSConnect Enterprise Edition.

Table 1. Enhancements and fixes

Maintenance level Enhancements and fixes

October 2017

V2.0.10.1APAR PI86221

Enhancements

v The version of Liberty that is embedded in z/OS Connect EE is upgraded toV17.0.0.3.

August 2017

API Editor V2.0.4.6 Fixes

v The mapping function was unable to distinguish between identically-named JSONobjects that have different full paths (that is, different parent objects), and incorrectlyrendered the same contents in the mapping editor. This issue is addressed.

July 2017


Table 1. Enhancements and fixes (continued)


Server code updateV2.0.10.0APARs:PI72646PI73237PI81092PI81379PI82085PI82792

Enhancements

v When no user ID is specified in the IMS connection profile, the IMS service providerwould extract the user ID from the request subject for authentication with IMSConnect. Previously, the user ID cannot be more than 8 bytes. This restriction is nowlifted, allowing a user ID longer than 8 bytes to be passed to IMS Connect, providedthat the user ID is properly mapped to a RACF® ID. For more information abouthow the user ID is determined, see “Authentication by IMS Connect” on page 143.

v More informative status codes are provided to allow client applications todistinguish server errors from errors caused by bad input data, and take theappropriate actions. This feature is controlled by a new option useGenericErrorwhich is set to true by default to preserve the current behavior. For moreinformation, see “zosconnect_localAdaptersConnectService” on page 302 in theReference section.

Fixes

v The GMOBA0110E message, The transaction could not be executed, could bemisleading. For CM0 (commit-then-send) transactions, the transaction is alreadyexecuted before the timeout occurs. The message is changed to "A problem occurredduring transaction processing, " followed by additional error details, for variouspossible error scenarios. For more information, see “GMOBA0110E” on page 272.

v The client ID that the IMS service provider generates for requests from z/OSConnect EE no longer has a GMP prefix, but a generic HWS prefix for all IMSConnect messages. The GMP prefix is needed to help distinguish z/OS Connect EErequests coming into IMS Connect from other sources. The GMP prefix is now addedback to the client ID.

v Timeout values set in IMS Explorer for Development did not appear to be reflectedcorrectly in the IMS service provider during run time. The "Transaction executiontimeout" label in IMS Explorer for Development V3.2.1.10 is changed to "IMSConnect socket timeout" to more clearly indicate that the value is used to determinethe time the socket should remain open to wait for a reply from IMS Connect. Thelabel now is consistent with the IMS service provider runtime behavior.

v Invoking an IMS service generates a null pointer exception when the credentialpassed in is not valid. This issue is addressed. In addition, when security is disabled,you no longer have to pass in a credential.

v Stopping an IMS service resulted in an IMSGatewayException error, stating that "thecreation or change to the <serviceName> configuration element SERVICE was notprocessed by the server." This issue is addressed.

v The limitation on the API GET request is removed. A value longer than 10 digits cannow be used.

v Code has been changed to correct an ERROR 400 BAQR7018E THE HTTP REQUEST ISMISSING PARAMETER when using a mixed case HTTP header name and value.

v Using a value longer than 10 digits on an API GET request caused error messageBAQR7019E to be returned. This restriction is removed.

April 2017




Server code updateV2.0.9.0(APAR PI77278)

Enhancements

v Services for the REST Client service provider can now be deployed to a z/OSConnect EE server by copying the service archive file (SAR) to a drop-in folder inthe same way as you deploy AAR files. z/OS Connect EE dynamically reacts tochanges made to SAR files in the services directory. SAR files can be copied to thelocation directory specified on the zosconnect_services element of the server.xmlconfiguration file. Set the updateTrigger attribute of this element to polled or mbean.For more information, see “Configuring SARs” on page 159.Note: Only SAR files that are created by the build toolkit for the REST Client serviceprovider are suitable for SAR deployment.

v You can now view the z/OS Connect EE documentation in PDF format. You can alsodownload a copy of the PDF directly from this IBM Knowledge Center for usewithin your organization. If you choose to download, check the onlinedocumentation regularly to ensure that you always have the latest PDF. See .

Fixes

v After installing or upgrading to v2.0.8, IMS users can create connection profiles inIMS Explorer but cannot retrieve or edit them. Services cannot be invoked and a nullpointer exception is thrown at run time. This issue is addressed.

v When tracing is turned on for internal debugging, the IMS service provider log tracecontains duplicate entries resulting in a performance degradation. This issue isaddressed.

Server code updateV2.0.8.0

(APAR PI79272)

Enhancements


v z/OS Connect EE supports the optional screening of application data values that areinconsistent with the language structure. Instead of returning an error to theapplication, the invalid value is replaced by a default value suitable for that field.This enhancement is controlled by the DATA-SCREENING parameter of the BAQLS2JS,and BAQJS2LS utilities. For more information, see “Conversion for z/OS ConnectEnterprise Edition data transformation” on page 250.

API Editor V2.0.4.5 Enhancements

v The Swagger UI in the API editor is updated to V2.2.10. This updated versionprovides JSON field validation in a web form. When testing the API, instead ofmodifying the values enclosed in double quotes in XML format, you can now enterthe value for each input field in a web form. The value is validated based on thedefined data type, length (for strings), or allowed values. Description of the field, ifdefined, is also shown in the web form.

v You can now set up for client authentication in the API Editor for enhanced security.A client certificate can be set up to send to the z/OS Connect EE server for serveraccess authentication. The client certificate is specified in the Eclipse preferences, inthe Keystore details section under Explorer > Certificate management. With clientauthentication, the separate user ID that is added for a host connection can be usedfor authorization based on the defined security role. For more information, see“Configuring client certificates for server connections” on page 217.

March 2017


v When path segments, path parameters, or operation IDs are modified in the APIEditor, in some cases, the underlying HTTP methods would revert to the baserequest JSON schema of the assigned service in the generated Swagger documentdespite the presence of existing mappings. This issue is addressed.

February 2017

Chapter 2. z/OS Connect Enterprise Edition change history 9




v The API editor is updated to detect invalid characters in the service name when aservice is imported, and to ensure characters that are valid in a URI are supported.Valid characters for service names are alphanumeric characters (A-Z, a-z, and 0-9)and the following special characters: -._~:/?#[]@!$&’()*+,;=

January 2017


v You can now add detailed documentation in the mapping editor for service fieldsthat are not involved in any data mapping actions. Previously, to add anydocumentation to a field, the field must be involved in a move, assign, or removetransform. You can now choose Add Task transform, and then add any descriptionor documentation as needed.

Fixes

v This release addresses the issue where, after the mapping editor is reopened, savedmapping information is lost for a Move transform that was added by dragging fromthe target (on the right) to the source (on the left).

December 2016


(APAR PI73978)

Fixes

v User customizations in the ims-services.xml file, such as specification of userauthority roles, are now preserved after an IMS service definition is updated byusing the IMS Explorer for Development.

v The IMS service provider GMOIG7777I initialization message upon server startup ismodified. The old name IMS Mobile feature in the message text is changed to “IMSservice provider”, followed by the build number.

v z/OS Connect EE supports the optional optimization of payload sizes by avoidingthe return of empty tags in the JSON response payload, when the COBOL field isNULL, ZERO, character SPACES or a mix of these values. This enhancement isenabled by setting the MAPPING-LEVEL=4.1, TRUNCATE-NULL-ARRAYS andTRUNCATE-NULL-ARRAY-VALUES parameters of the BAQLS2JS utility. For moreinformation, see “Conversion for z/OS Connect Enterprise Edition datatransformation” on page 250.


(APAR PI72673)

Enhancements


v A new topic in the Operating section of the documentation explains how to usesystem automation tools with z/OS Connect EE.


v Previously, if a service that was not involved in any mapping was changed andre-imported into the API project, it was not included in the impact analysis. Theanalysis compared only services that have explicit mappings to an HTTP header,path parameter, or query parameter. The impact analysis now includes these servicesand reports new and removed fields.

v The generated Swagger document for the GET method no longer includes the HTTPbody if all service fields are mapped.

October 2016





Enhancements

v The IMS Mobile feature is now included in z/OS Connect EE as the IMS serviceprovider. The IMS Mobile feature was previously a component in the IMS EnterpriseSuite as the IMS Mobile Feature Pack for z/OS Connect EE.

v Two new scenarios are provided to demonstrate how to create an IMS service (alsoknown as an IMS mobile service) and how to develop an API to invoke an IMSservice.

v A new scenario is provided to demonstrate how to use z/OS Connect EE in a HighAvailability environment for RESTful access to IMS transactions through the IMSservice provider.


Enhancements

v A new chapter describes how you can use z/OS Connect EE in a High Availabilityenvironment. The chapter explains the concepts and components of HA and theadvantages and disadvantages.

v Drop-ins support is now provided for APIs. This allows z/OS Connect EE todynamically react to changes to AAR files in the apis directory. AAR files can bedropped into the location directory specified on the zosconnect_zosConnectAPIselement. The updateTrigger attribute of this element should be set to polled ormbean. For more information, see “Configuring APIs” on page 160.

v UTF-8 encoding is now supported in JSON payloads for APIs.

v A more detailed description of MBeans shows how they can be used to updateserver configurations on demand.

v An extension of the HA scenario is provided to demonstrate how to deploy an APIand how to add a second httpEndpoint in a High Availability environment.

v You can now build Service Archive (SAR) files for the REST client using either thecommand line interface or the SDK in the Build Toolkit.

v The description of the zosconnect_localAdaptersConnectService element has beenenhanced to explain the attributes applicable to using COMMAREA and channelpayloads on the WOLA service.

API Editor V2.0.4 Enhancements

v If a service is changed after an API is created, when it is re-imported into the project,the impact of the changes is analyzed. The impact is listed and categorized intoerrors, warnings, and other issues. If you choose to continue with the import, brokenmappings are highlighted in the mapping editor. For more information, see“Re-importing changed services” on page 225.

September 2016


v In an Assign transform, the assigned value is now validated against the constraintsof the target field, such as the data type, the minimum or maximum length forstrings, or the minimum and maximum value for numeric fields.

Fixes

v For compatibility with the Swagger Editor, minimum and maximum constraints fornumeric fields in generated Swagger documents no longer use the scientific Enotation.


v When a service (SAR) is re-imported into an API project, existing mappings are nolonger cleared. The API editor now preserves existing mappings by updating all themapping files that reference the service. If a field that a transform action refers to isno longer in the service interface, the broken mapping is highlighted in the mappingeditor.




August 2016


Enhancements


v z/OS Connect EE is enhanced so that you can set the WLP_USER_DIR environmentvariable to define the location of your server instances and user features.

July 2016


Enhancements

v A new attribute, useJsonErrorResponses is provided for the zosConnectManagerconfiguration element. When set, all error responses are returned in JSON format.For more information, see “zosconnect_zosConnectManager” on page 316 in theReference section.

v You can now authenticate users when they test your APIs in the API Editor or in aweb-based application.


v A Deploy API to z/OS Connect EE Server button is added to facilitate deploymentof the API directly from the API package editor:

v Usability of relative path specification is enhanced:

– Path validation occurs only when the user attempts to save, the path text fieldloses focus, or there are outstanding errors in the editor. The editor no longervalidates and displays errors as the user starts typing.

– A closing curly bracket ("}") is automatically inserted when the user types anopening curly bracket ("{").

v Path and query parameters now inherit the minimum, maximum, minLength,maxLength, exclusiveMinimum, and exclusiveMaximum properties of the servicefield to which they are mapped.

June 2016


Enhancements

v Deploy an API project using the RESTful administration interface or the APIDeployment utility.

v Browse, start, stop, and remove deployed APIs on connected z/OS Connect EEservers using the RESTful administration interface.

v Examine and test the operations of an API in Swagger UI.

v The DataxForm SPI is extended with a new interface DataxFormExt. This SPI has agetEncoding() method, which can be used to obtain encoding information whenusing data transformation.

v UTF-8 encoding is now supported in JSON payloads for Services.

v A new role, Reader can be assigned, allowing the user to read the Swaggerdocument, access and import APIs, read a list of all APIs and services, and getdetailed information.





The following new features in this release require z/OS Connect EE server V2.0.1.0(APAR PI62820) or later.

v Connect to z/OS Connect EE servers in the Host Connections view.

v Deploy an API project directly from the editor in the Project Explorer view.

v Browse, start, stop, and remove deployed APIs on connected servers directly in theeditor in the z/OS Connect EE Servers view.

v Examine and test the operations of an API in Swagger UI that is included in the APIeditor.Important:

Before using the "Try it out!" button in Swagger UI, take the following action:

If your z/OS Connect EE server connection is secure (SSL/TLS), install and trust theserver's certificate by using Certificate Manager (Start > Run and select certmgr.msc)in Windows, or by using Keychain Access in MacOS.

April 2016


Enhancements

v The authentication process is enhanced to always use the authenticated user on therequest subject.

v Added new attribute definition that is called preserveJsonObjectPayloadOrder,which can be set under the zosConnectManager element and applies to all configuredservices. When set, z/OS Connect EE preserves the order of JSON objects that arecontained in the payloads.

v Added support to WebSphere Optimized local adapters for use with CICSTransaction Server V5.3.

v Properties files can now be read from product extensions on z/OS.

v Added function to reestablish the link between the CICS link server and the Libertyserver instance, when the Liberty server is restarted.


Fixes

v Modify WOLA connection close processing to ensure completion when Libertyserver is canceled.

v Naming conventions for the BBO£ transaction TS Queue name creation to avoidconflict with the TS queue Names for BBO# transactions.





v Multi-select for the Assign and Remove mapping actions is now supported.

v When an Assign mapping is added, the Properties view is brought forward and thenewly created mapping is automatically selected for edits.

Fixes

v A pop-up warning message is added when you try to export an API package to anAPI archive file name that exists, and the .aar file extension for an API archive isnow enforced when you export an API package.

v A pop-up message is added to surface the underlying exception when you try toexport an API package to an existing API archive file that is locked and cannot beoverridden.

v A warning message is added to inform you that existing mappings would be lostwhen you try to change service assignment for a method with existingHTTP-to-JSON mappings.

v The mapping editor no longer shows the actions for adding data transforms on itemsthat already have a mapping.


Chapter 3. Sources of information

The IBM Knowledge Center is the primary source of information about z/OSConnect Enterprise Edition, but there are other documents that you might finduseful.

IBM Knowledge Center content

The content of this IBM Knowledge Center is also available in these formats:v As a download. You can use a locally hosted IBM Knowledge Center with z/OS

Connect Enterprise Edition product documentation for access over yourorganization's intranet or offline access on your workstation. You can install thelocally hosted IBM Knowledge Center on Windows and Linux. For moreinformation, see https://developer.ibm.com/mainframe/documentation/kc/.

v As a PDF from the PDF library.v Translated into the following national languages. Brazilian Portuguese, Czech,

French, German, Hungarian, Japanese, Korean, Polish, Romanian, Russian, andSimplified Chinese.

Other sources of informationv Configuring z/OS Connect EE inside CICS Transaction Server. https://

developer.ibm.com/mainframe/2017/03/22/configuring-zos-connect-ee-inside-cics-transaction-server/This article describes a working example of how to configure z/OS Connect EEinside CICS Transaction Server 5.3.

v Securing APIs with z/OS Connect EE. https://developer.ibm.com/mainframe/docs/securing-apis/securing-apis-with-zos-connect-ee/This article describes various aspects of securing APIs with z/OS Connect EE.


https://developer.ibm.com/mainframe/documentation/kc/

https://developer.ibm.com/mainframe/2017/03/22/configuring-zos-connect-ee-inside-cics-transaction-server/



https://developer.ibm.com/mainframe/docs/securing-apis/securing-apis-with-zos-connect-ee/

https://developer.ibm.com/mainframe/docs/securing-apis/securing-apis-with-zos-connect-ee/

Chapter 4. Scenarios

Follow the steps in these scenarios to learn how to perform tasks such asdeveloping and deploying APIs.

You can find an example of creating and deploying APIs on YouTube:https://www.youtube.com/watch?v=HjE8wdvX3I0&feature=youtu.be.

Develop an API to invoke a CICS service via WOLAUse this scenario to develop and deploy an API to invoke a CICS service viaWOLA.

You can then use that API to invoke a service that is provided by the CICS CatalogManager, one of the example applications included with CICS Transaction Server.

This scenario uses the WOLA service provider that is provided with z/OS ConnectEnterprise Edition to connect to an application program that is running in a CICSregion. WOLA connections require the Liberty angel process, the z/OS ConnectEnterprise Edition server and CICS region to run in the same z/OS LPAR. Toenable this connection, you need to configure SAF resource definitions for CICSand z/OS. These steps are described in the configuration step of this scenario.

This scenario shows you how to use the BAQLS2JS utility to generate a servicearchive from an existing CICS application, and how to use the API Editor to createan API, including mapping of the HTTP request path and query parameters. It alsoprovides instructions on how to configure a z/OS Connect Enterprise Editionserver to use WOLA to connect to a CICS region.

The following diagram shows the topology that is used in this scenario:

WOLA

HTTPport

WOLAserviceprovider

DataXform

CICS

HTTP to JSONmapping

API

Service

Liberty Server

DFHRPLWOLA modules

zosConnect feature

z/OS Connect EE

BBOC controltransaction

BBO#invocation task

transaction

WOLA BBO$ LinkServer Task

WOLA TRUE

CatalogManagerPrograms

angel process

APIrequest

PrerequisitesThese are the prerequisites used to run this scenario.


https://www.youtube.com/watch?v=HjE8wdvX3I0&feature=youtu.be

Software requirementsv z/OS Connect Enterprise Edition V2.0 installed and zconsetup install

command runv CICS Transaction Server 4.1 or higher installed and a CICS region running.

Prerequisite tasks

You need to complete the following tasks to provide the infrastructure needed bythe scenario.v Configure a started task to run a z/OS Connect EE server.

To set up the started task, customize the sample JCL <installation_path>/jcl/baqstrt.jcl and add it to your PROCLIB library. Then, enter the SAF commandto associate the name of the started task procedure with a user ID. For example,to define the BAQSTRT procedure name to run under the user ID <userid>, usethe following RACF command:

RDEF STARTED BAQSTRT.* UACC(NONE) STDATA(USER(<userid>) GROUP(<group>)PRIVILEGED(NO) TRUSTED(NO) TRACE(YES))

For more information, see “Setting up a started task to run z/OS Connect EEservers” on page 189.

v Configure the Liberty angel process as described in “Configuring the Libertyangel process and z/OS authorized services” on page 185. The angel process isrequired by WOLA to access z/OS authorized services.

v Install z/OS Explorer Aqua and the IBM z/OS Connect EE API Editor plug-in.See “Installing z/OS Explorer and the z/OS Connect EE API Editor” on page115. The API Editor plug-in is required to create the API.

Configuring the CICS Catalog Manager example applicationTo run this scenario you will need to install and configure the CICS CatalogManager example application.

About this task

This scenario uses the CICS Catalog Manager sample application as an example ofan existing CICS application to be exposed as an API. This application must beinstalled and configured in your target CICS region. If this application is not yetconfigured, follow this procedure. For more information, refer to The CICS catalogmanager example application in the CICS Transaction Server documentation

Procedure1. Install and configure the CICS Catalog Manager example application. Follow

the steps in Installing and setting up the base application. For the configurationstep, enter the transaction ECFG on a CICS terminal to start the configurationapplication. Update the following values to use a VSAM Datastore and thestubbed version of the Order Dispatcher:


http://www-01.ibm.com/support/knowledgecenter/SSGMCP_5.3.0/com.ibm.cics.ts.exampleapplication.doc/topics/dfhxa_t100.html?cp=SSGMCP_5.3.0%2F11-1


http://www-01.ibm.com/support/knowledgecenter/SSGMCP_5.3.0/com.ibm.cics.ts.exampleapplication.doc/topics/dfhxa_t230.html

CONFIGURE CICS EXAMPLE CATALOG APPLICATIONDatastore Type ==> VSAM STUB|VSAM

Outbound WebService? ==> NO YES|NOCatalog Manager ==> DFH0XCMNData Store Stub ==>Data Store VSAM ==> DFH0XVDS

Order Dispatch Stub ==> DFH0XSODOrder Dispatch WebService ==>

Stock Manager ==> DFH0XSSMVSAM File Name ==> EXMPCAT

Server Address and Port ==>Outbound WebService URI ==>

2. Test that the application has been installed and configured correctly. Follow theinstructions in Running the example application with the BMS interface.

Results

The sample application is now configured on CICS and can be run using the BMSinterface. Follow the remaining steps to access this application from z/OS ConnectEE.

Configuring CICS to use WOLAIn this step, you configure the example CICS application and configure both CICSand SAF to use WOLA.

About this task

Configure CICS to use WebSphere Optimized Local Adapters (WOLA). WOLA isthe service provider that allows z/OS Connect EE requests to interact with z/OSassets.

Procedure

Follow the instructions in “Configuring CICS to use WebSphere optimized localadapters (WOLA)” on page 124. This scenario uses the following values:

Table 2. Values used in this scenario

Parameter Region

Group CATMGR1

Name 2 CATMGR2

Name 3 CATMGR3

When you define the SAF CBIND profile, use the same values. For example, if youare using RACF, choose one of these options:v To use explicit definitions, enter the following commands:

RDEF CBIND BBG.WOLA.CATMGR1.CATMGR2.CATMGR3 UACC(NONE)PERMIT BBG.WOLA.CATMGR1.CATMGR2.CATMGR3 CLASS(CBIND) ACCESS(READ) ID(CICSID)

v To use wildcards, and create only a single definition, enter the followingcommands:

RDEF CBIND BBG.WOLA.* UACC(NONE)PERMIT BBG.WOLA.* CLASS(CBIND) ACCESS(READ) ID(CICSID)

Chapter 4. Scenarios 19

http://www-01.ibm.com/support/knowledgecenter/SSGMCP_5.3.0/com.ibm.cics.ts.exampleapplication.doc/topics/dfhxa_t330.html?cp=SSGMCP_5.3.0%2F11-1-2

v Use your own values. If you choose this option, ensure that you use the samevalues in the corresponding steps later in the scenario. You must create a uniquedefinition for each server.

Generate a service archive from a CICS COBOL copybookGenerate a Service Archive (SAR) file that can be used by the API Editor.

About this task

At runtime, z/OS Connect Enterprise Edition APIs start z/OS Connect EnterpriseEdition services. Before you can create an API, you need to generate a ServiceArchive (SAR) file, which provides information about the service, including itsexpected request and response JSON schemas. SAR files for CICS services aregenerated by using the z/OS Connect Enterprise Edition utilities. This task showsyou how to use IBM Explorer for z/OS to create a service archive file by using thesample BAQLS2JS JCL from an existing CICS COBOL application, the CatalogManager example application.

Procedure1. Establish an FTP connection to your z/OS LPAR.

a. In IBM Explorer for z/OS, go to the Host Connections view.b. Under z/OS, select z/OS FTP then click Add.c. Type in your host name, then click Save and Close.

Your connection is listed as shown in the screen image:

2. Click Connect and enter your credentials. If the connection was successful, thered box changes to green.

This example uses the sample z/OS Connect EE utility JCL BAQLS2JS to generateservice archive files from existing language structures. In this case, CICS COBOL


application COMMAREA copybooks. The z/OS Connect EE sample JCL<installation_dir>/jcl/baqls2js.jcl is customized for each service and samplesare provided.

The following steps create SAR files for three different services: Inquire single,Inquire catalog, and Place order. If you want to test just one service, you can godirectly to that step and complete the other steps at another time.

Note: BAQLS2JS generates JSON schemas and bind files in addition to the SARfile for the service. The names of the generated files are important because at runtime the bind file and schema names must correspond to the zosConnectServiceserviceName attribute, which is configured in the server.xml in a later step. Thenaming convention requires that the bind file must be called<serviceName>.wsbind, the request schema must be called<serviceName>_request.json, and the response schema must be called<serviceName>_response.json. In each case, <serviceName> is the value that isspecified on the SERVICE-NAME parameter in BAQLS2JS.3. Create a PDS with RECFM=FB LRECL=80 on your z/OS LPAR to store the JCL

you use to create your SAR files. For example, userid.SAR.JCL.

4. In IBM Explorer for z/OS, click Open Perspective and select the z/OSperspective. This perspective provides the views that you need to create theSAR files.

5. Create a SAR file for the Inquire single service.a. Create a member called INQSINGL in your PDS. For example,

<userid>.SAR.JCL. In this example, create this member by using IBMExplorer for z/OS.

b. In the Data Sets view, right-click on your PDS, and click New Data SetMember....

c. In the Member Name field, enter INQSINGL. Ensure that Open Editor ischecked.

d. Click Finish. The new member opens in the editor.e. Download the sample file BAQLS2JS_inquireSingle.txt To download,

right-click the link and select Save Link As....f. Open BAQLS2JS_inquireSingle.txt in a plain text editor. Use cut and paste

to copy the contents of the file into the new member INQSINGL.g. Customize the following values:


v Replace <Install Path> with the fully qualified installation path of z/OSConnect EE.

v Replace <Output Path> with a UNIX System Service path where you wantthe generated SAR, WSBIND file, and JSON schemas to be stored. Forexample, /u/userid/catalogManager.

v Replace <CICSHLQ> with the HLQ of your CICS libraries. This HLQ isused to locate the COBOL copybooks for the CICS Catalog Managerexample application.

v Replace <Java path> with the UNIX System Service path where Java isinstalled.

h. Ensure that the UNIX System Service file paths that are defined forJSON-SCHEMA-REQUEST, JSON-SCHEMA-RESPONSE, WSBIND, and SERVICE-ARCHIVEparameters exist. You can use the z/OS UNIX Files view to check that thepaths are correct.

i. In the Data Sets view, right-click the file INQSINGL and select Submit z/OSJob.

j. In the Console view, click the job ID to open the z/OS Job view.k. In the z/OS Job view, check that the job completed successfully. Click

STDOUT and look for the following message:DFHPI9587I Program "DFHLS2JS" completed SUCCESSFULLY.

6. Create a SAR file for the Inquire catalog service. Repeat step 5 using a newmember called INQCAT and sample file BAQLS2JS_inquireCatalog.txt

7. Create a SAR file for the Place order service. Repeat step 5 using a newmember called ORDER and sample file BAQLS2JS_placeOrder.txt.

8. Transfer the generated SAR files, inquireSingle.sar, inquireCatalog.sar, andplaceOrder.sar to the local file system of the workstation where IBM Explorerfor z/OS is installed. This can be done by using FTP in binary mode. Thesefiles are required in the next step, to create an API which calls those services.

Create an API using z/OS Connect EE API EditorUse the z/OS Connect EE API Editor to create and deploy an API, using the SARfiles you generated in the previous step.

Before you begin

Ensure that the inquireSingle.sar, inquireCatalog.sar, and placeOrder.sar filesthat were generated in the previous step have been transferred, in binary mode, tothe machine where IBM Explorer for z/OS is installed. For more details, see“Generate a service archive from a CICS COBOL copybook” on page 20.

Procedure1. Start IBM Explorer for z/OS and open the z/OS Connect Enterprise Edition

perspective.2. Right click in the project explorer window and select New... > Project. Expand

z/OS Connect Enterprise Edition, select z/OS Connect EE API Project andclick Next.


3. Fill in the sections for the new API project and click Finish.

The z/OS Connect Enterprise Edition API Editor dialog opens.


The following steps create an API path for the inquireSingle service. This isimplemented as an HTTP GET request and demonstrates the mapping of pathparameters, and assign and remove mappings.4. Rename the default Path value to be /items/{itemID} by typing over the

existing value, where {itemID} indicates a path parameter whose value will besubstituted at runtime.

5. Remove the POST, PUT and DELETE methods by clicking on the

at theend of the line. This should leave only the GET method allowed for the path/items/{itemID}.

6. Click Service for the GET method to select the service archive file that definesthe service on this API path that will be called by an HTTP GET. The Select az/OS Connect EE Service dialog opens

7. Click File System and navigate to the location of the inquireSingle.sar file.Select the sar file and click OK. The inquireSingle service now appears in theService dialog.


Click OK. The service is defined to the GET method.

8. Click Mapping for the GET method, then click open both mappings. Therequest and response mappings open in the editor so that you can define themapping between the content of the HTTP API request and the JSON contentpassed to the z/OS Connect Enterprise Edition service.

9. In the request mapping, right click ca_request_id and select Add Assign. Astatic value is assigned to the field in the request JSON schema.

10. Ensure Assign has focus. In the Properties view, click General and set Valueto 01INQS. This is the value required by the CICS Catalog Manager applicationprogram to perform an inquiry on a single catalog item.

11. Check Omit from interface. This excludes this value from the API Swaggerdocument definition of the request body for this path. This value must be setfor the CICS Catalog Manager application, but because it is an internalimplementation value it does not need to be exposed to users of the API.

12. For each of ca_return_code, ca_single_item and ca_response_message, rightclick the value and click Add Remove Transform. This changes the mappingto Remove which excludes these values from the API Swagger documentdefinition of the request body for this path. These values are not required onthe request. They will be populated by the Catalog Manager application andreturned in the response.

13. Connect the path parameter itemID to ca_item_ref_req. This creates a Moveand assigns the value from the path parameter in the HTTP request to the


field in the JSON content passed to the z/OS Connect Enterprise Editionservice.

14. In the response mapping, for each of ca_request_id and ca_item_ref_req,right click the value and click Add Remove Transform. This excludes thesevalues from the API Swagger document definition of the response body forthis path and prevents them being displayed in the API HTTP response body.These values are only required on the request to the CICS application and donot need to be exposed in the response to the API user.

The following steps are for the placeOrder service. This is implemented as anHTTP POST request and demonstrates the mapping of query parameters

15. Select the package.xml tab and click

next to Path to add a new Path.Enter /orders into the path and delete the GET, PUT and DELETE methods.Add the service placeOrder.sar to the path.

16. Click Mapping for the POST method using the placeOrder service and selectopen both mappings. The request and response mappings open in the editor.


17. In the request mapping, right click ca_request_id and select Add AssignTransform A static value is assigned to the field in the request JSON schema.

18. Click the Properties tab, then click Assign. Set Value to 01ORDR. This is thevalue required by the CICS Catalog Manager application program to orderitems from the catalog. Check Omit from interface.

19. Add an Assign to ca_userid and ca_charge_dept. Both these JSON values areassigned the default value of an empty string, so no value needs to bespecified in the Properties tab for this example.

20. Add a Remove for ca_return_code and ca_response_message This excludesthese values from the API Swagger document definition of the request bodyfor this path.

21. In the response mapping, add a Remove for ca_request_id andca_order_request. This excludes these values from the API Swaggerdocument definition of the response body for this path, and prevents thembeing displayed in the API HTTP response body.

The following steps are for the inquireCatalog service. This is implemented as anHTTP GET request.

22. Select the package.xml tab and click

next to Path to add a new path.Enter /items into the path and delete the POST, PUT and DELETE methods.Add the service inquireCatalog.sar to the path.

23. Click Mapping for the GET method using the inquireCatalog service. Selectopen both mappings. The request and response mappings open in the editor.


24. In the request mapping, right click on ca_request_id and select Add AssignTransform This assigns a static value to the field in the request JSON schema.

25. Click the Properties tab, then click Assign. Set Value to 01INQC. This is thevalue required by the CICS Catalog Manager application program to performan inquiry on catalog items. Check Omit from interface. This excludes thisvalue from the API Swagger document definition of the request body for thispath.

26. Add a Remove for ca_return_code, ca_response_message, ca_last_item_ref,ca_item_count and ca_cat_item This excludes these values from the APISwagger document definition of the request body for this path.

27. Right click on Query Parameters and select Add Query Parameter. Fill in thename field with the name that you want to use for the query parameter. Forexample, startItemID. From the drop down menu, select integer for the typeand check Required.

28. Click OK. Drag and link this query parameter to ca_list_start_ref. Thiscreates a Move and assigns the value from the query parameter in the HTTPrequest to the field in the JSON content passed to the z/OS ConnectEnterprise Edition service.

29. In the response mapping, add a Remove for ca_request_id.


In the remaining steps, you export the API as an API package (API archive file)and transfer the archive file to the UNIX System Services directory on the z/OSLPAR where z/OS Connect Enterprise Edition is installed.30. Save all files. Right click catalog in the Project Explorer view. Click z/OS

Connect EE > Export z/OS Connect EE API Package.31. Click Workspace > Browse and navigate to the /catalog folder, to create an

API archive file named catalog.aar in your catalog project. Click OK. z/OSConnect Enterprise Edition V2.0 provides an apideploy tool to deploy the APIarchive file from a location in the USS file system into your z/OS ConnectEnterprise Edition server configuration.

32. Transfer the API archive file. The API archive file must be transferred to aUNIX System Service directory on the z/OS LPAR, so that it can be accessedby the apideploy tool, which deploys the API archive file to a z/OS ConnectEnterprise Edition server. When you want to uninstall the API archive file, theapideploy tool requires that the API archive file must still exist in the sameUSS directory where it was installed, so you must export the file to apermanent UNIX System Service directory:a. Right-click on the API archive file catalog.aar in your catalog project.b. Select Export > General > z/OS UNIX File System.c. Set Destination Directory to a suitable value. For example:

/u/userid/catalogManager.d. Click Finish.

Configuring the z/OS Connect EE server to use WOLAIn this step, you create and configure a z/OS Connect EE server to use theWebSphere Optimized Local Adapter, the z/OS Connect EE API, and services forthe Catalog Manager application.

Before you begin1. To use WOLA, the zosLocalAdapters-1.0 feature must be enabled in your server

configuration.2. You must set the WLP_USER_DIR environment variable to the location where

you want your server instances and user features to be stored. For example:/var/zosconnect.

Procedure1. Create a server by using the following command. You enter this command from

the <installation_dir>/bin directory, for example: /usr/lpp/IBM/zosconnect/v2r0/bin.

zosconnect create catalogManager --template=zosconnect:default


This command creates a server that is called catalogManager by using thedefault z/OS Connect EE template. The default template defines the basicfeatures in your server.xml. You must manually add any other features thatyou need.

2. Customize the server.xml configuration file for your z/OS Connect EE serverto contain these elements:<server description="ZConnect Wola test server">

<featureManager><feature>zosconnect:zosconnect-2.0</feature><feature>zosLocalAdapters-1.0</feature>

</featureManager>

<httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="9080" httpsPort="9443" />

<zosconnect_zosConnectManager requireAuth="false" requireSecure="false"/>

<zosLocalAdapters wolaGroup="CATMGR1" wolaName2="CATMGR2" wolaName3="CATMGR3" />

<connectionFactory id="wolaCF" jndiName="eis/ola">

<properties.ola/></connectionFactory>

<zosconnect_localAdaptersConnectService id="wolaCatalogManager"

registerName="CICSREG"serviceName="DFH0XCMN"connectionFactoryRef="wolaCF"/>

<zosconnect_zosConnectService id="inquireSingleService"requireAuth="false"requireSecure="false"serviceName="inquireSingle"serviceRef="wolaCatalogManager"dataXformRef="xformJSON2Byte" />

<zosconnect_zosConnectService id="placeOrderService"requireAuth="false"requireSecure="false"serviceName="placeOrder"serviceRef="wolaCatalogManager"dataXformRef="xformJSON2Byte" />

<zosconnect_zosConnectService id="inquireCatalogService"requireAuth="false"requireSecure="false"serviceName="inquireCatalog"serviceRef="wolaCatalogManager"dataXformRef="xformJSON2Byte" />

<zosconnect_zosConnectDataXform id="xformJSON2Byte"

bindFileLoc="<Output path>" bindFileSuffix=".wsbind"requestSchemaLoc="<Output path>"responseSchemaLoc="<Output path>"requestSchemaSuffix=".json"responseSchemaSuffix=".json">

</zosconnect_zosConnectDataXform></server>

v The httpEndpoint element attributes httpPort and httpsPort must be uniquewithin your z/OS LPAR

v The zosLocalAdapters element attribute values wolaGroup, wolaName2, andwolaName3 are arbitrary but must match the values that are specified in the

SAF CBIND profile when you configure CICS to use WOLA. Each namecomponent is limited to eight alphanumeric characters with no blank spaces.The names are case-sensitive. If you have mixed case in the server.xml, thenthe external address space or program that seeks to register into the LibertyServer would need to have matching case. Make the values uppercase tosimplify creating the CBIND profile. The three-part name that is used by aLiberty Profile z/OS server instance must be unique on the z/OS LPAR

Note: WOLA requires a three-part name to be used when external addressspaces, such as CICS, register into the Liberty Profile server. The three-partname model is used to retain consistent behavior for when WOLA is used inWebSphere Application Server for z/OS full profile, which uses cell, nameand server constructs.

v The connectionFactory XML defines the WOLA JCA resource adapter that isused for communication outbound from a z/OS Connect EE server to CICS.

v In the localAdaptersConnectService element, check the following attributes:– The registerName attribute is used by CICS for the register name when it

registers with WOLA. This attribute is the RGN value on the BBOCSTART_SRVR RGN command.

– The value for serviceName must match the name CICS is using for theservice name. That is, the target CICS program name.

v The value of the serviceName attribute in the zosConnectService elementmust match the value that is specified for the SERVICE-NAME property whenyou run BAQLS2JS. This value is included in the generated .sar file and wasused by the API Editor to identify the service names that are associated withspecific paths and methods in the API.

v The zosConnectDataXform specifies the extensions and directories that containthe bind file and JSON schemas that are generated for the CICS services bythe BAQLS2JS utility.

Note: The bind file and schema names must correspond to thezosConnectService serviceName. In this example,serviceName="inquireSingle" so the bind file must be calledinquireSingle.wsbind, the request schema must be calledinquireSingle_request.json the response schema must be calledinquireSingle_response.json.

v <Output path> in the zosConnectDataXform element is the UNIX SystemServices directory where you generated the bind file, request and responseschemas for each of the services in the earlier step “Generate a servicearchive from a CICS COBOL copybook” on page 20. For example,/u/userid/catalogManager. You can also choose to configure alternativelocations here, in which case you must copy the generated files to theselocations. The bindFileLoc, requestSchemaLoc, and responseSchemaLoc valuescan all be different paths.

What to do next

The server is configured. In the next step, you will deploy the API.

Deploying an API to the z/OS Connect EE serverDeploy the API archive file to the z/OS Connect EE server.


About this task

You need to deploy your API to make it available.

Note: If you have z/OS Connect EE V2.0.1.0 or later installed, you can deployyour APIs directly from the API Editor. For more information, see “Deploying anAPI in the API Editor” on page 223.

Procedure

Run the apideploy command, as one line, on the z/OS system:

<installation_dir>/bin/apideploy-deploy -a <path_to_aar_file>/<api package name>.aar-p <WLP_USER_DIR>/servers/<server name>/resources/zosconnect/apis

For example,

/usr/lpp/IBM/zosconnect/v2r0/bin/apideploy-deploy -a /u/userid/catalogManager/catalog.aar-p /var/zosconnect/servers/catalogManager/resources/zosconnect/apis

Note:

v The path that is specified on the -p parameter must exist before the command isrun.

v If an API is already deployed, add the -w at the end of the command tooverwrite the API with the new version.

Test the scenarioStart the WOLA connection between the z/OS Connect EE server and the CICSregion, make HTTP calls to confirm that your services and APIs are installedcorrectly, then call the APIs.

About this task

Note: The HTTP GET requests can be made in any browser. The HTTP POSTrequest requires the use of a browser with a REST Client browser plug-in.

Procedure1. Start the angel process started task by typing the command on the operator

console: S BBGZANGL2. Restart the z/OS Connect EE server. To preserve the case of your server name,

you must start the server from the System Command Extension windowwithin SDSF.From SDSF, type / to open the extended console, then enter the command:

S BAQSTRT,PARMS='<serverName> --clean'

a. Check the server's message log file in <WLP_USER_DIR>/servers/{servername}/logs/messages.log. The following messages appear:

CWWKB0103I: Authorized service group LOCALCOM is available.CWWKB0103I: Authorized service group WOLA is available....CWWKB0501I: The WebSphere Optimized Local Adapter channel registered with the Liberty profile server with the following name:


CATMGR1 CATMGR2 CATMGR3...J2CA7001I: Resource adapter wola installed in 0.327 seconds.

Where:v If the LOCALCOM service group is available, then the angel is running

and your Liberty Server ID has READ access to that SERVER profile.v If the WOLA service group is available, then the configuration was

completed successfully.v The CWWKB0501I message is showing the successful use of the WOLA

three part name values you provided in the server.xml file. Thismessage indicates that an external address space might register into theLiberty Profile server, in this instance the z/OS Connect EE server, byusing this three-part name on the BBOA1REG API.

v The J2CA7001I message indicates that the WOLA JCA resource adapteris available.

3. Ensure that the CICS region is started4. Start the TRUE and Link Server task from CICS, and register with WOLA. The

z/OS Connect EE server must be running.a. Open a session with the CICS region and type the following command:

BBOC START_TRUE

The following message indicates success:WOLA TRACE 1: Exit enabled successfully.

b. Type the following command, as one line, to start the link server task andregister to your server:

BBOC START_SRVR RGN=CICSREG DGN=GROUP NDN=NAME2SVN=NAME3 SVC=* MNC=1 MXC=10 TXN=N SEC=N REU=Y

Where GROUP, NAME2, and NAME3 match the values that are specifiedon the zosLocalAdapters element in the server.xml configuration file tocreate the three part name for WOLA. For example:

BBOC START_SRVR RGN=CICSREG DGN=CATMGR1 NDN=CATMGR2SVN=CATMGR3 SVC=* MNC=1 MXC=10 TXN=N SEC=N REU=Y

The following message indicates success:WOLA TRACE 0: Start server completed successfully.

Messages are also written to the CICS region job log BBOOUT.If you get a nonzero return code and reason code, then go to the topicOptimized local adapters for z/OS APIs in the WebSphere Application Serverz/OS documentation. Go to the “Register” section (also known as theBBOA1REG section) and look for the RC and RSN code that is providedthere.

You can now send requests from the z/OS Connect Enterprise Edition server viaWOLA to CICS.5. From a web browser, enter an HTTP GET request to list all the installed z/OS

Connect Enterprise Edition services:http://<host name>:<port>/zosConnect/services


https://www-01.ibm.com/support/knowledgecenter/SS7K4U_8.0.0/com.ibm.websphere.nd.multiplatform.doc/info/ae/ae/cdat_olaapis.html?lang=en

For example:http://companyhost.company.com:9080/zosConnect/services

If your services are working correctly, the following response is received:

{"zosConnectServices": [

{"ServiceName": "inquireSingle","ServiceDescription": "DATA_UNAVAILABLE","ServiceProvider": "WOLA-1.0","ServiceURL": "http://companyhost.company.com:9080/zosConnect/services/inquireSingle"

},{

"ServiceName": "inquireCatalog","ServiceDescription": "DATA_UNAVAILABLE","ServiceProvider": "WOLA-1.0","ServiceURL": "http://companyhost.company.com:9080/zosConnect/services/inquireCatalog"

},{

"ServiceName": "placeOrder","ServiceDescription": "DATA_UNAVAILABLE","ServiceProvider": "WOLA-1.0","ServiceURL": "http://companyhost.company.com:9080/zosConnect/services/placeOrder"

}]

}

6. From a web browser, enter an HTTP GET request to list all the installed z/OSConnect Enterprise Edition APIs:http://<host name>:<port>/zosConnect/apis

For example:http://companyhost.company.com:9080/zosConnect/apis

If your API is installed correctly, the following response is received:

{"apis": [{

"name": "catalog","version": "1.0.0","description": "API for the CICS catalog manager example application","adminUrl": "http://companyhost.company.com:9080/zosConnect/apis/catalog"

}]

}

7. From a web browser, enter an HTTP GET request to view the SWAGGERdocument for the catalog API:http://companyhost.company.com:9080/catalogManager/api-docs

If your API request is successful, the HTTP response contains the API'sSWAGGER document. Notice that the host value is updated to show theserver where the API is deployed, as follows:


{"swagger": "2.0","info": {"description": "","version": "1.0.0","title": "catalog"

},"host": "companyhost.company.com:9080","basePath": "/catalogManager","schemes": ["https","http"

],"consumes": ["application/json"

],"produces": ["application/json"

],"paths": {"/items": {

"get": {...}

},"/items/{itemID}": {"get": {...}

},"/orders": {"post": {

...}

}},"definitions": {...

}}

8. From a web browser, enter an HTTP GET request to call the API to inquire ona single catalog item:http://companyhost.company.com:9080/catalogManager/items/10

Where:v catalogManager is the base path value that is defined in the API definitionv 9080 is the HTTP port the z/OS Connect EE server uses to listen for HTTP

requests.v items is the path that is defined in the API for inquiring on a single catalog

itemv 10 is the runtime value for the path parameter value {itemID}If your API request is successful, the following response is received:


{"DFH0XCMNOperationResponse": {"ca_return_code": 0,"ca_response_message": "RETURNED ITEM: REF =0010","ca_inquire_single": {

"ca_single_item": {"in_sngl_stock": 129,"ca_sngl_description": "Ball Pens Black 24pk","ca_sngl_item_ref": 10,"on_sngl_order": 0,"ca_sngl_cost": "002.90","ca_sngl_department": 10

}}

}}

9. From a web browser, enter an HTTP POST call to call the API to place anorder:

Note: A POST request requires the use of a browser with a REST Clientbrowser plug-in.http://companyhost.company.com:9080/catalogManager/orders

Add an HTTP header: Content-Type: application/json. The Content-Typeinforms the z/OS Connect EE server that the HTTP body data it receivescontains JSON data:Request Body Content:{

"DFH0XCMNOperation": {"ca_order_request":{"ca_item_ref_number":10,"ca_quantity_req":1

}}

}

If your API request is successful, the following response is received:

{"DFH0XCMNOperationResponse": {"ca_return_code": 0,"ca_response_message": "ORDER SUCCESSFULLY PLACED"

}}

10. From a web browser, enter an HTTP GET request to call the API to list theitems in the catalog, starting with the item whose catalog item reference is 10:http://companyhost.company.com:9080/catalogManager/items?startitemID=10

Where ?startitemID=10 is a query parameter whose name is startitemID andvalue is 10.If your API request is successful, the following response is received:


{"DFH0XCMNOperationResponse": {"ca_return_code": 0,"ca_inquire_request": {

"ca_last_item_ref": 150,"ca_item_count": 15,"ca_cat_item": [{

"ca_cost": "002.90","in_stock": 128,"ca_description": "Ball Pens Black 24pk","on_order": 0,"ca_item_ref": 10,"ca_department": 10

},

...,

{"ca_cost": "005.35","in_stock": 36,"ca_description": "Sticky Notes 3x3 Assorted Colors 5pk","on_order": 45,"ca_item_ref": 150,"ca_department": 10

}],"ca_list_start_ref": 10

},"ca_response_message": "+15 ITEMS RETURNED"

}}

11. To unregister the CICS region from WOLA and stop the link server task, typethe following commands from a CICS session:

BBOC STOP_SRVR RGN=CICSREG

Where the RGN value must match the value that is specified when youregistered the CICS region. The following message indicates success:WOLA TRACE 0: Stop server completed successfully.

BBOC STOP_TRUE

The following message indicates success:WOLA TRACE 0: Exit stopped successfully

For more information, see the Liberty Profile z/OS WOLA Quick Start Guideavailable from Techdoc WP101490.

What to do next

You can compare these results with the results you saw when you tested theCatalog Manager application with the BMS interface.

For more information on the BBOC CICS transactions, see WebSphere ApplicationServer transactions BBOC, BBO$, BBO# in the WebSphere Application Server for z/OSdocumentation.


http://www-03.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/WP101490

http://www.ibm.com/support/knowledgecenter/en/SSAW57_liberty/com.ibm.websphere.nd.multiplatform.doc/ae/rdat_cics.html


Develop an API to invoke a CICS service using the CICS serviceprovider

Use this scenario to develop and deploy an API to invoke a CICS service using theCICS service provider

You can then use that API to invoke a service that is provided by the CICS CatalogManager, one of the example applications provided by CICS Transaction Server.

This scenario uses the CICS service provider to connect to an application programthat is running in a CICS region. The z/OS Connect Enterprise Edition server andCICS region must run in the same z/OS LPAR. To enable this connection, youneed to configure SAF resource definitions for CICS and z/OS. These steps aredescribed in the configuration step of this scenario.

This scenario shows you how to use the BAQLS2JS utility to generate a servicearchive from an existing CICS application, and how to use the API Editor to createan API, including mapping of the HTTP request path and query parameters.

PrerequisitesThe following facilities are needed to run this scenario.

Software requirementsv z/OS Connect Enterprise Edition V2.0 installed and zconsetup install

command run successfully.v CICS Transaction Server 4.1 or higher installed and a CICS region running.

Prerequisite tasks

You need to complete the following tasks to provide the infrastructure needed bythe scenario.v Configure a started task to run a z/OS Connect EE server.

To set up the started task, customize the sample JCL <installation_path>/jcl/baqstrt.jcl and add it to your PROCLIB library. Then, enter the SAF commandto associate the name of the started task procedure with a user ID. For example,to define the BAQSTRT procedure name to run under the user ID <userid>, usethe following RACF command:



v Install z/OS Explorer Aqua and the IBM z/OS Connect EE API Editor plug-in.See “Installing z/OS Explorer and the z/OS Connect EE API Editor” on page115. The API Editor plug-in is required to create the API.

v You can install a REST client for your web browser to make testing easier.

Configuring the CICS Catalog Manager example applicationTo run this scenario you will need to install and configure the CICS CatalogManager example application


About this task

This scenario uses the CICS Catalog Manager sample application as an example ofan existing CICS application to be exposed as an API. This application must beinstalled and configured in your target CICS region. If this application is not yetconfigured, follow this procedure. For more information, refer to The CICS catalogmanager example application in the CICS Transaction Server documentation








2. Test that the application has been installed and configured correctly. Follow theinstructions in Running the example application with the BMS interface.

Results

The sample application is now configured on CICS and can be run using the BMSinterface. Follow the remaining steps to access this application from z/OS ConnectEE.

Generate a service archive from a CICS COBOL copybookGenerate a Service Archive (SAR) file that can be used by the API Editor.

About this task

At runtime, z/OS Connect Enterprise Edition APIs start z/OS Connect EnterpriseEdition services. Before you can create an API, you need to generate a ServiceArchive (SAR) file, which provides information about the service, including itsexpected request and response JSON schemas. SAR files for CICS services aregenerated by using the z/OS Connect Enterprise Edition utilities. This task showsyou how to use IBM Explorer for z/OS to create a service archive file by using thesample BAQLS2JS JCL from an existing CICS COBOL application, the CatalogManager example application.

Procedure1. Establish an FTP connection to your z/OS LPAR.

a. In IBM Explorer for z/OS, go to the Host Connections view.b. Under z/OS, select z/OS FTP then click Add.c. Type in your host name, then click Save and Close.

Your connection is listed as shown in the screen image:






2. Click Connect and enter your credentials. If the connection was successful, thered box changes to green.

This example uses the sample z/OS Connect EE utility JCL BAQLS2JS to generateservice archive files from existing language structures. In this case, CICS COBOLapplication COMMAREA copybooks. The z/OS Connect EE sample JCL<installation_dir>/jcl/baqls2js.jcl is customized for each service and samplesare provided.

The following steps create SAR files for three different services: Inquire single,Inquire catalog, and Place order. If you want to test just one service, you can godirectly to that step and complete the other steps at another time.

Note: BAQLS2JS generates JSON schemas and bind files in addition to the SARfile for the service. The names of the generated files are important because at runtime the bind file and schema names must correspond to the zosConnectServiceserviceName attribute, which is configured in the server.xml in a later step. Thenaming convention requires that the bind file must be called<serviceName>.wsbind, the request schema must be called<serviceName>_request.json, and the response schema must be called<serviceName>_response.json. In each case, <serviceName> is the value that isspecified on the SERVICE-NAME parameter in BAQLS2JS.3. Create a PDS with RECFM=FB LRECL=80 on your z/OS LPAR to store the JCL

you use to create your SAR files. For example, userid.SAR.JCL.

4. In IBM Explorer for z/OS, click Open Perspective and select the z/OSperspective. This perspective provides the views that you need to create theSAR files.

5. Create a SAR file for the Inquire single service.


a. Create a member called INQSINGL in your PDS. For example,<userid>.SAR.JCL. In this example, create this member by using IBMExplorer for z/OS.

b. In the Data Sets view, right-click on your PDS, and click New Data SetMember....

c. In the Member Name field, enter INQSINGL. Ensure that Open Editor ischecked.

d. Click Finish. The new member opens in the editor.e. Download the sample file BAQLS2JS_inquireSingle.txt To download,

right-click the link and select Save Link As....f. Open BAQLS2JS_inquireSingle.txt in a plain text editor. Use cut and paste

to copy the contents of the file into the new member INQSINGL.g. Customize the following values:v Replace <Install Path> with the fully qualified installation path of z/OS

Connect EE.v Replace <Output Path> with a UNIX System Service path where you want

the generated SAR, WSBIND file, and JSON schemas to be stored. Forexample, /u/userid/catalogManager.

v Replace <CICSHLQ> with the HLQ of your CICS libraries. This HLQ isused to locate the COBOL copybooks for the CICS Catalog Managerexample application.

v Replace <Java path> with the UNIX System Service path where Java isinstalled.

h. Ensure that the UNIX System Service file paths that are defined forJSON-SCHEMA-REQUEST, JSON-SCHEMA-RESPONSE, WSBIND, and SERVICE-ARCHIVEparameters exist. You can use the z/OS UNIX Files view to check that thepaths are correct.

i. In the Data Sets view, right-click the file INQSINGL and select Submit z/OSJob.

j. In the Console view, click the job ID to open the z/OS Job view.k. In the z/OS Job view, check that the job completed successfully. Click

STDOUT and look for the following message:DFHPI9587I Program "DFHLS2JS" completed SUCCESSFULLY.

6. Create a SAR file for the Inquire catalog service. Repeat step 5 using a newmember called INQCAT and sample file BAQLS2JS_inquireCatalog.txt

7. Create a SAR file for the Place order service. Repeat step 5 using a newmember called ORDER and sample file BAQLS2JS_placeOrder.txt.


8. Transfer the generated SAR files, inquireSingle.sar, inquireCatalog.sar, andplaceOrder.sar to the local file system of the workstation where IBM Explorerfor z/OS is installed. This can be done by using FTP in binary mode. Thesefiles are required in the next step, to create an API which calls those services.

Deploying an API to the z/OS Connect EE serverDeploy the API archive file to the z/OS Connect EE server.

About this task

You need to deploy your API to make it available.

Note: If you have z/OS Connect EE V2.0.1.0 or later installed, you can deployyour APIs directly from the API Editor. For more information, see “Deploying anAPI in the API Editor” on page 223.

Procedure

Run the apideploy command, as one line, on the z/OS system:

<installation_dir>/bin/apideploy-deploy -a <path_to_aar_file>/<api package name>.aar-p <WLP_USER_DIR>/servers/<server name>/resources/zosconnect/apis

For example,

/usr/lpp/IBM/zosconnect/v2r0/bin/apideploy-deploy -a /u/userid/catalogManager/catalog.aar-p /var/zosconnect/servers/catalogManager/resources/zosconnect/apis

Note:

v The path that is specified on the -p parameter must exist before the command isrun.

v If an API is already deployed, add the -w at the end of the command tooverwrite the API with the new version.

Test the scenarioStart the WOLA connection between the z/OS Connect EE server and the CICSregion, make HTTP calls to confirm that your services and APIs are installedcorrectly, then call the APIs.

About this task

Note: The HTTP GET requests can be made in any browser. The HTTP POSTrequest requires the use of a browser with a REST Client browser plug-in.

Procedure1. Start the angel process started task by typing the command on the operator

console: S BBGZANGL2. Restart the z/OS Connect EE server. To preserve the case of your server name,

you must start the server from the System Command Extension windowwithin SDSF.From SDSF, type / to open the extended console, then enter the command:


S BAQSTRT,PARMS='<serverName> --clean'


CWWKB0103I: Authorized service group LOCALCOM is available.CWWKB0103I: Authorized service group WOLA is available....CWWKB0501I: The WebSphere Optimized Local Adapter channel registered with the Liberty profile server with the following name:CATMGR1 CATMGR2 CATMGR3...J2CA7001I: Resource adapter wola installed in 0.327 seconds.




three part name values you provided in the server.xml file. Thismessage indicates that an external address space might register into theLiberty Profile server, in this instance the z/OS Connect EE server, byusing this three-part name on the BBOA1REG API.

v The J2CA7001I message indicates that the WOLA JCA resource adapteris available.


z/OS Connect EE server must be running.a. Open a session with the CICS region and type the following command:

BBOC START_TRUE


b. Type the following command, as one line, to start the link server task andregister to your server:

BBOC START_SRVR RGN=CICSREG DGN=GROUP NDN=NAME2SVN=NAME3 SVC=* MNC=1 MXC=10 TXN=N SEC=N REU=Y

Where GROUP, NAME2, and NAME3 match the values that are specifiedon the zosLocalAdapters element in the server.xml configuration file tocreate the three part name for WOLA. For example:

BBOC START_SRVR RGN=CICSREG DGN=CATMGR1 NDN=CATMGR2SVN=CATMGR3 SVC=* MNC=1 MXC=10 TXN=N SEC=N REU=Y





You can now send requests from the z/OS Connect Enterprise Edition server viaWOLA to CICS.5. From a web browser, enter an HTTP GET request to list all the installed z/OS

Connect Enterprise Edition services:http://<host name>:<port>/zosConnect/services

For example:http://companyhost.company.com:9080/zosConnect/services

If your services are working correctly, the following response is received:

{"zosConnectServices": [

{"ServiceName": "inquireSingle","ServiceDescription": "DATA_UNAVAILABLE","ServiceProvider": "WOLA-1.0","ServiceURL": "http://companyhost.company.com:9080/zosConnect/services/inquireSingle"

},{

"ServiceName": "inquireCatalog","ServiceDescription": "DATA_UNAVAILABLE","ServiceProvider": "WOLA-1.0","ServiceURL": "http://companyhost.company.com:9080/zosConnect/services/inquireCatalog"

},{

"ServiceName": "placeOrder","ServiceDescription": "DATA_UNAVAILABLE","ServiceProvider": "WOLA-1.0","ServiceURL": "http://companyhost.company.com:9080/zosConnect/services/placeOrder"

}]

}




{"apis": [{

"name": "catalog","version": "1.0.0","description": "API for the CICS catalog manager example application","adminUrl": "http://companyhost.company.com:9080/zosConnect/apis/catalog"

}]

}

7. From a web browser, enter an HTTP GET request to view the SWAGGERdocument for the catalog API:http://companyhost.company.com:9080/catalogManager/api-docs

If your API request is successful, the HTTP response contains the API'sSWAGGER document. Notice that the host value is updated to show theserver where the API is deployed, as follows:


{"swagger": "2.0","info": {"description": "","version": "1.0.0","title": "catalog"

},"host": "companyhost.company.com:9080","basePath": "/catalogManager","schemes": ["https","http"

],"consumes": ["application/json"

],"produces": ["application/json"

],"paths": {"/items": {

"get": {...}

},"/items/{itemID}": {"get": {...}

},"/orders": {"post": {

...}

}},"definitions": {...

}}

8. From a web browser, enter an HTTP GET request to call the API to inquire ona single catalog item:http://companyhost.company.com:9080/catalogManager/items/10

Where:v catalogManager is the base path value that is defined in the API definitionv 9080 is the HTTP port the z/OS Connect EE server uses to listen for HTTP


itemv 10 is the runtime value for the path parameter value {itemID}If your API request is successful, the following response is received:


{"DFH0XCMNOperationResponse": {"ca_return_code": 0,"ca_response_message": "RETURNED ITEM: REF =0010","ca_inquire_single": {

"ca_single_item": {"in_sngl_stock": 129,"ca_sngl_description": "Ball Pens Black 24pk","ca_sngl_item_ref": 10,"on_sngl_order": 0,"ca_sngl_cost": "002.90","ca_sngl_department": 10

}}

}}

9. From a web browser, enter an HTTP POST call to call the API to place anorder:

Note: A POST request requires the use of a browser with a REST Clientbrowser plug-in.http://companyhost.company.com:9080/catalogManager/orders

Add an HTTP header: Content-Type: application/json. The Content-Typeinforms the z/OS Connect EE server that the HTTP body data it receivescontains JSON data:Request Body Content:{

"DFH0XCMNOperation": {"ca_order_request":{"ca_item_ref_number":10,"ca_quantity_req":1

}}

}

If your API request is successful, the following response is received:

{"DFH0XCMNOperationResponse": {"ca_return_code": 0,"ca_response_message": "ORDER SUCCESSFULLY PLACED"

}}

10. From a web browser, enter an HTTP GET request to call the API to list theitems in the catalog, starting with the item whose catalog item reference is 10:http://companyhost.company.com:9080/catalogManager/items?startitemID=10

Where ?startitemID=10 is a query parameter whose name is startitemID andvalue is 10.If your API request is successful, the following response is received:


{"DFH0XCMNOperationResponse": {"ca_return_code": 0,"ca_inquire_request": {

"ca_last_item_ref": 150,"ca_item_count": 15,"ca_cat_item": [{

"ca_cost": "002.90","in_stock": 128,"ca_description": "Ball Pens Black 24pk","on_order": 0,"ca_item_ref": 10,"ca_department": 10

},

...,

{"ca_cost": "005.35","in_stock": 36,"ca_description": "Sticky Notes 3x3 Assorted Colors 5pk","on_order": 45,"ca_item_ref": 150,"ca_department": 10

}],"ca_list_start_ref": 10

},"ca_response_message": "+15 ITEMS RETURNED"

}}

11. To unregister the CICS region from WOLA and stop the link server task, typethe following commands from a CICS session:

BBOC STOP_SRVR RGN=CICSREG

Where the RGN value must match the value that is specified when youregistered the CICS region. The following message indicates success:WOLA TRACE 0: Stop server completed successfully.

BBOC STOP_TRUE

The following message indicates success:WOLA TRACE 0: Exit stopped successfully

For more information, see the Liberty Profile z/OS WOLA Quick Start Guideavailable from Techdoc WP101490.

What to do next

You can compare these results with the results you saw when you tested theCatalog Manager application with the BMS interface.

For more information on the BBOC CICS transactions, see WebSphere ApplicationServer transactions BBOC, BBO$, BBO# in the WebSphere Application Server for z/OSdocumentation.





Create an IMS mobile serviceYou can create an IMS mobile service to enable RESTful access to IMS transactionsvia the IMS service provider supplied with z/OS Connect EE.

This scenario involves the use of the IMS Mobile feature (imsmobile-2.0), whichserves as the IMS service provider. The IMS Mobile feature was previouslyincluded in the IMS Enterprise Suite as the IMS Mobile Feature Pack for z/OSConnect EE.

The IMS Mobile feature includes the following functions:v A data transformation module that converts request messages from the JSON

format to the native representation of the input message and then converts theresponse messages to JSON.

v An IMS Connect adapter module that interacts with IMS Connect for IMSTransaction Manager (TM) access.

v A service management and administration interface that is used by IMS Explorerfor Development to provide the user interface for service creation, testing, andmanagement.

v A sample ping service to use as an installation verification program (IVP).

The tool for creating, publishing, and testing services is provided by IMS Explorerfor Development, an Eclipse-based graphical tool for creating, testing, andpublishing services based the data structures in IMS COBOL copybooks or PL/Iincludes. The z/OS Connect EE API Editor provides the tool for defining RESTfulAPIs to act on the resources that are exposed in the services.

The following diagram shows the request and response processing and thecomponents that are involved at run time. When a request comes in, z/OS ConnectEE handles the user access control and the conversion between HTTP and JSONbased on the API packages are deployed. The IMS mobile service provider isinvoked, and the request message is converted from JSON to the nativerepresentation of the input message (for example, bytes array or arrays forsegments in COBOL and PL/I applications). The request then goes through theIMS Connect for access to IMS transactions. These transactions might be accessingIMS DB, DB2, or other external subsystems such as WebSphere MQ or WebSphereOptimized Local Adapters (WOLA). The service definition, request and responsemetadata, interaction profile, and connection profile are stored in the IMS mobileservice registry.


PrerequisitesExamine the operational requirements, considerations and restrictions to assist theplanning and design of your mobile solution.v z/OS Connect EE is properly installed.v The IMS Mobile feature is properly configured. For more information, see

“Using the IMS service provider” on page 129.v IMS Explorer for Development V3.2.1.4 or later is properly installed.

– IMS Explorer for Development (IMS Explorer) can be downloaded from theDownload Eclipse tools page on the mainframe development site athttps://developer.ibm.com/mainframe/products/downloads/. Follow theinstructions on the page for IBM Installation Manager.

– Updates of the IMS Mobile feature might require a newer version of IMSExplorer. Check the Chapter 2, “z/OS Connect EE change history,” on page 7topic for any potential compatibility issues.

RestrictionsThe IMS Mobile feature has restrictions on the type of IMS transactions that aresupported and on data conversion from the high-level languages to JSON.v Only transactions with a single input message and a single output message are

supported, although the message can contain multiple segments. For

Figure 2. The IMS mobile solution process flow and components involved


https://developer.ibm.com/mainframe/products/downloads/

non-response transactions or when IMS encounters an error while processing thetransaction, a GMOBA0920E message is generated that includes the DFSmessage from IMS.

v For COBOL to JSON data conversion restrictions, see COBOL to JSON schemamapping (IMS Explorer).

v For PL/I to JSON data conversion restrictions, see PL/I to JSON schemamapping (IMS Explorer).

Request and response messages for IMS mobile servicesRequest and response messages for IMS mobile services are represented in JSONformat. The schema can be obtained through the getRequestSchema andgetResponseSchema actions.

In general, the JSON schema looks as follows:{

"type": "object","properties": {

"<TopLevelStructureName1>": {"type": "object","properties": {

"<fieldName>":"<fieldValue>",...,

"<fieldNameN>":"<fieldValueN>"}

},...,"<TopLevelStructureNameN>": {

"type": "object","properties": {

"<fieldName>":"<fieldValue>",...,

"<fieldNameN>":"<fieldValueN>"}

}}

}

The following sample request data is based on the IMS phonebook sampleapplication. The request has two input fields: in_cmd and in_name1.{

"INPUT_MSG" : {"IM_CMD":"DISPLAY","IN_NAME1":"DOE"

}}

Based on the input from the request, the following response is returned:{

"OUTPUT_MSG" : {"OUT_MSG":"ENTRY WAS DISPLAYED ","OUT_CMD":"DISPLAY ","OUT_NAME1":"DOE "},"OUT_NAME2":"JOE ","OUT_EXTN":"4081111111","OUT_ZIP":"95141 ","OUT_SEGNO":"0001"}]

}}


When an error occurs, a response message with the error detail is returned inkey-value pair in the following format:{

"status": HTTP status code,"messageCode": Message code,"message": "Message text","details": "Message detail for mobile developer","moreInfo":"URL to the message documentation""response": "Result of the request, if any"

}

Mobile application developers are responsible for checking for returned HTTPstatus codes that are not 200, and process the response based on the error messagecode.

Mobile service creators can use IMS Explorer for Development to choose specificfields in an IMS transaction to expose as part of the input and output servicemetadata and assign default values.

For the input stream format and each possible output stream format, users of themobile application receive the name, data type, and default value, if specified, foreach field. Regardless of data type, the mobile application must send, at run time,a character representation of the field values. This character representation isconverted to the native representation of the input message before the request issent to IMS.

Based on the message interface that is generated by IMS Explorer forDevelopment, a service expects input and output data fields to match the datastructure in the interface.1. On input, JSON name-value pairs are marshalled into bytes arrays. JSON field

names must match the field name from the message interface. The pairs aremarshalled one at a time.

2. On output, the byte array is un-marshalled into JSON name-value pairs. Allfields in the metadata are returned in the response, but you can deselect fieldsin IMS Explorer for Development when you define the service interface to omitthose fields in the response. Output JSON field names match the field namesfrom the metadata.

Tip: Default values from COBOL or PL/I fields are not captured in the messageinterface.

IMS Explorer for Development also provides advanced data conversion options,allowing you to trim leading or trailing white spaces, exclude non-printable controlcharacters, or suppress low values or empty tags from the JSON responsemessages.Related reference:IMS phonebook application descriptionFor more information about the phonebook application, see the tutorial topic.

High-level language and JSON schema mappingThe data mapping function in IMS Explorer for Development communicates withthe data transformation function in IMS Mobile feature to generate JSON schemasfrom high-level language data structures and vice versa.


Each JSON schema element contains the following attributes:v name: Name of the field.v type: JSON data type for the field, such as string, integer, number, or array.v maxLength (for string type): The maximum length allowed for the field.v multipleOf (for numeric type): The decimal value based on the numeric scale for

the field, for example, 0.01.v minOccurs (for array type): The minimal occurrences in the array (COBOL

OCCURS statements).v maxOccurs (for array type): The maximum occurrences in the array (COBOL

OCCURS statements).v minimum* (for numeric type): The recommended minimal value allowed for the

field.v maximum* (for numeric type): The recommended maximum value allowed for

the field.v description: Additional information or remarks entered in the IMS Explorer for

Development about the field.

*: Data type conversion for large numeric data could result in some loss ofaccuracy.

For more information about COBOL-to-JSON and PL/I-to-JSON data mapping, seeand in the IMS Explorer for Development information.

The following JSON schema samples are based on the IMS phonebook application(IVTNO). For input messages:{

"Display":{

"IN_CMD":{

"maxLength": 8,"type": "string"

},"IN_EXTN":{


},"IN_ZIP":{


},"IN_TRCD":{


},"IN_LL":{

"maximum": 32768,"type": "integer","minimum": -32767

},"IN_ZZ":{


},


"IN_NAME1":{


},"IN_NAME2":{


}}

}

For output messages:{

"Display":{

"OUT_MSG":{


},"OUT_ZIP":{


},"OUT_LL":{


},"OUT_ZZ":{


},"OUT_NAME1":{


},"OUT_SEGNO":{


},"OUT_NAME2":{


},"OUT_CMD":{


},"OUT_EXTN":{


}}

}


Related reference:IMS phonebook application description (in the tutorial)For more information about the phonebook application, see the tutorial topic.

IMS service creation workflowUse the IMS Explorer for Development (IMS Explorer) to create and publish thenecessary resources that define an IMS service to the server, including connectionprofiles, interaction profiles, transaction message metadata, and service metadata.

IMS Explorer can be downloaded from the . Follow the instructions on the pagefor IBM Installation Manager.

Creating IMS mobile services generally involves the following steps in IMSExplorer for Development:1. Set up for connection to the z/OS Connect EE server with the appropriate user

name and password.2. Define a connection profile for IMS Connect connection by specifying the IMS

host name, port number, data store name and other properties.3. Define an interaction properties profile. The interaction properties specify how

each service interacts with IMS Connect, such as commit mode and sync level.4. Define the message metadata (the input and output message formats) for the

IMS transaction by importing the COBOL copybook or PL/I source file.5. Define the service to the server by specifying the transaction name, the

interaction properties profile, and the connection profile to use.6. Create a test case to invoke the mobile service to ensure that all the specified

metadata is correct, and that the transaction returns the expected output.

After the service is created and tested, export the service as a SAR file. Import theSAR file into the z/OS Connect EE API Editor to design, develop, and test theREST API for the service.

This scenario is based on the MS phonebook application (IVTNO). The phonebookcopybook is provided.Related information:

Tutorial: Create an IMS mobile serviceThis tutorial takes you through the steps to create a REST service to enable accessto the IMS phonebook application through the JSON/REST protocol.

Learning objectives

You will learn the following concepts and steps to REST-enable your IMSapplications:v The process, the components, and the tool involved in creating an IMS mobile

service.v The access permission that you need to the IMS gateway server and to IMS for

creating a REST service from an IMS application.v What message metadata is, and how to define it from the input and output

messages of an IMS transaction.

Background and workflow


To expose an IMS transaction as a RESTful service, the z/OS Connect EE server(also known as the IMS gateway server) that handles request routing must haveinformation about how to connect to IMS through IMS Connect (the connectionprofile), how to interact with an IMS transaction (the interaction properties profile),what the transaction message contains (message metadata), and the name of theRESTful service. To specify all the required information, you will use IMS Explorerfor Development (IMS Explorer).

This tutorial will step you through the steps to specify and define the requiredinformation:1. Create a connection to the z/OS Connect EE server.2. Define an IMS connection profile for use to connect to IMS.3. Define an IMS interaction properties profile that specifies how to invoke an

IMS transaction.4. Define the message metadata that can be used to convert between the

JavaScript Object Notation (JSON) message format and the bytes array formatof an IMS transaction.

Time required

This tutorial should take approximately 90 minutes to finish. If you explore otherconcepts related to this tutorial, it could take longer to complete.

Figure 3. Information required on the server to enable RESTful access to IMS transactions


Audience

IMS application programmers that are familiar with the IMS transactions to beenabled for RESTful access.

Prerequisites

Use the following checklist to gather the information you need and to ensure youhave the required setup before you begin.v z/OS Connect EE is properly installed, and IMS Mobile feature is properly

installed into z/OS Connect EE. See “Operational requirements” on page 130 formore information.Record the following information for connecting to the z/OS Connect EE server:– Host name: _______________________– Port number: _______________________

v A compatible version of IMS Explorer for Development is downloaded andproperly installed on your workstation.To install IMS Explorer for Development, go to the on the MainframeDevelopment website. Follow the instructions for IBM Installation Manager.

v The user name you can use to access the z/OS Connect EE server. This usermust be set up as an administrative user in order to deploy a service. Obtainthis user ID from your server administrator.Record the user name for the server here: _______________________

v The user name and password you can use to access the backend IMS must beidentified and set up. Obtain this user ID from your IMS system administratoror programmer.Record the following information for connecting to IMS:– Host name (where IMS Connect is running): _______________________– Port number (where IMS Connect is listening): _______________________– User name: _______________________– Password: _______________________

v The IMS phonebook application is set up through the installation verificationprogram (IVP) H216T and H213J.

v Obtain the phonebook copybook (IMSPHBK.cpy) file from your IMS systemadministrator.The phonebook copybook (IMSPHBK.cpy) is required. Although it is includedwith IMS and you can obtain it from your IMS system administrator, you canalso right-click here and select Save Link As (in FireFox) or Save Target As (inMicrosoft Internet Explorer) to download it. Rename the downloaded file with a.cpy extension. Note that this version of the phonebook copybook is modifiedwith different field names so they are easier to understand.

Connect to the z/OS Connect EE serverTo specify all the required information for RESTful access to an IMS transaction inIMS Explorer for Development (IMS Explorer), you must first establish aconnection from IMS Explorer to the server.

About this task

In this first step, we will connect to the server from IMS Explorer.


Note: Starting IMS Explorer V3.2.1.4 and later, some user interface labels havechanged. The term IMS gateway server is replaced by z/OS Connect EE server. TheIMS Gateway Navigator view is renamed to IMS Service Navigator. If you have anolder version of IMS Explorer, update to the latest version to take advantage ofnew and enhanced features and defect fixes.

Procedure1. Switch to the IMS Mobile perspective.

a. From the main menu, select Window > Open Perspective > Other TheSelect Perspective wizard opens.

b. Click IMS Mobile.c. Click OK. The IMS Mobile perspective opens.

2. In the IMS Mobile perspective of IMS Explorer, from the IMS Service Navigatorview, right-click the z/OS Connect EE Servers folder and click Connect to az/OS Connect EE server.

3. In the Create a z/OS Connect EE server connection wizard, enter the followinginformation:

Table 3. IMS gateway server connection information

Field Description

Name Provide a name for the z/OS Connect EE server.

Host name The host name for the location where IMS Mobile is installed andconfigured.

Port number The port number for the location where IMS Mobile is installed andconfigured.

User ID The user ID that has access to the IMS Mobile server.

4. Click OK to establish the connection to the z/OS Connect EE server.5. Expand the z/OS Connect EE Servers folder in the IMS Service Navigator view

to verify that the z/OS Connect EE server that you created is displayed withthe following folders:v IMS Connection profiles

v IMS interaction properties profiles

v Services

6. Expand the z/OS Connect EE Servers folder in the IMS Transaction Navigatorview to verify that the server connection that you created is displayed with theTransactions folder.

Results

You can now proceed to define the required information for your service.

Define an IMS connection profileWhen the server receives a RESTful service request, it first authorizes the user andthen routes the request through the IMS service provider to the appropriate IMSConnect based on a defined connection profile. Connection profiles can be sharedby any number of services.

About this task

In this step, you will create a connection profile for the server to authorizes theuser that is associated with a request.


Procedure1. In the IMS Service Navigator view, expand the server that you created in the

previous step.2. Right-click the IMS Connection profiles folder and click Create an IMS

connection profile.3. In the New IMS Connection Profile wizard, enter the following information:

Table 4. IMS connection profile

Field Description

Name Your IMS connection profile name.

Host The name of the system on which IMS Connect is running.

Port number The port number of the system on which IMS Connect isrunning.

User name The user name to connect to IMS Connect.

Password The password for connection to IMS Connect.

4. Click Finish to deploy the connection definition to the server.

Results

The connection profile shows up under the IMS Connection profiles folder.

Define an IMS interaction properties profileAfter the connection with IMS Connect is established, you need to define how theserver should invoke an IMS transaction.

About this task

You can specify the IMS ID that the transaction will be routed to, the commitmode, and the sync level to use for this interaction by defining an interactionproperties profile. Similar to the connection profiles, the interaction propertiesprofiles can be shared by any number of services.

Procedure1. In the IMS Service Navigator view, expand the server that you created.2. Right-click the IMS interaction properties profiles folder and click Create an

IMS interaction properties profile.3. In the New IMS Interaction Properties Profile wizard, enter the following

information:

Table 5. IMS interaction properties profile

Field Description

Profile name A unique name for your IMS interaction properties profile.

IMS destination name The ID of the IMS system that you want to route to. Thisname should match one of the ID values of theDATASTORE statement in IMS Connect.

You can keep the default values for all other fields.4. Click Finish to deploy the IMS interaction properties definition to the IMS

gateway server.


Results

The interaction properties profile shows up under the IMS interaction propertiesprofiles folder.

You have created a connection profile and an interaction properties profile. Youwill now define the message metadata for the IMS phonebook application(transaction IVTNO).

Define message metadata for the IMS phonebook applicationThe IMS Mobile feature uses message metadata to convert from RESTful serviceinput, which is in JavaScript Object Notation (JSON), to IMS transaction input,which is an array of structured bytes that is defined by the IMS application.

About this task

The COBOL or PL/I copybook structures from your IMS applications define theinput and output messages of the transaction. Import the copybook into yourproject to generate the necessary metadata for the server to complete this datatransformation.

The phonebook application, if you use the IMSPHBK.cpy file that is provided withthis tutorial, has the following data:************* IMS PhoneBook Transaction (IVTNO) Sample *************/

01 IVTNO-INPUT-MSG.02 IN-LL PICTURE S9(3) COMP.02 IN-ZZ PICTURE S9(3) COMP.02 IN-TRANCDE PICTURE X(10).02 IN-COMMAND PICTURE X(8).02 IN-LAST-NAME PICTURE X(10).02 IN-FIRST-NAME PICTURE X(10).02 IN-EXTENSION PICTURE X(10).02 IN-ZIP-CODE PICTURE X(7).

01 IVTNO-OUTPUT-MSG.02 OUT-LL PICTURE S9(3) COMP VALUE +0.02 OUT-ZZ PICTURE S9(3) COMP VALUE +0.02 OUT-MESSAGE PICTURE X(40) VALUE SPACES.02 OUT-COMMAND PIC X(8).02 OUT-LAST-NAME PIC X(10).02 OUT-FIRST-NAME PIC X(10).02 OUT-EXTENSION PIC X(10).02 OUT-ZIP-CODE PIC X(7).02 OUT-SEGNO PICTURE X(4) VALUE SPACES.

Note: If you use the original copy that comes with IMS, the field names aredifferent. For example, IN_NAME1 is last name, and IN_NAME2 is first name.However, the structure is the same.

The phonebook service requires the following input fields:v IN_TRANCODE is a value up to 10 characters.v IN_COMMAND has the following valid values: ADD, DISPLAY, DELETE, and

UPDATE.v IN_LAST_NAME is a value up to 10 characters.v IN_FIRST_NAME is a value up to 10 characters.v IN_EXTENSION is a value up to 10 characters.v IN_ZIP_CODE is a value up to 7 characters.


The expected output for phonebook is OUT_MESSAGE, which contain a messageup to 40 characters indicating success or failure.

In the following steps, you will import the input and output metadata for ourIVTNO transaction from a COBOL copybook called IMSPHBK.cpy to create themessage metadata. The IMSPHBK.cpy file is included with IMS and is provided withthis tutorial for your convenience. Right-click here and select Save Link As (inFireFox) or Save Target As (in Microsoft Internet Explorer) to download it. Renamethe file with a .cpy extension.

Procedure1. In the IMS Transaction Navigator view, expand the server that you created.2. Right-click the Transactions folder and click Create message metadata. The

Create IMS Transaction wizard opens.3. In the Create IMS Transaction wizard, enter a Transaction name (TRANCODE)

value. For example, IVTNO, and click OK.A new tab for IVTNO.trn opens in the IMS Explorer Transaction MessageMetadata Editor.

4. Click Import data structure.5. In the Import wizard, click Browse

6. In the Select File dialog, navigate to the phonebook copybook file IMSPHBK.cpyon your workstation and click Open.

7. Specify the data structure for the input and output messages:a. In the Data structure name list, select IVTNO_INPUT_MSG.b. Ensure that the Message name list has IVTNO - INPUT **IN** selected.c. Ensure that the Segment name list has Segment 1 selected.d. Click Add to Import List to add this message data structure to the Import

list.The input message data structure is defined. Now we will specify the datastructure for the output message.

e. In the Data structure name list, select IVTNO_OUTPUT_MSG.f. In the Message name list, select IVTNO - OUTPUT **OUT**.g. Ensure that the Segment name field has Segment 1 selectedh. Click Add to Import List to add the data structures to the Import list.


8. To complete your import, click Finish.9. Click File > Save to save all of your imported metadata to the server.

Results

In the IMS Explorer Transaction Message Editor, you can expand the elementsunder Input Messages and Output Messages to verify that the COBOL copybookswere properly imported to the respective input and output messages.

Figure 4. Importing input or output message data structures


Define the phonebook service to the serverWith the connection profile, interaction properties profile, and message metadataall defined, you are ready to define a service for the phonebook application.

About this task

To define a service, you specify a name for the service and identify the followinginformation that is associated with this service:v IMS transactionv Interaction properties profilev Connection profilev The input fields and output fields that you want to expose.

Procedure1. In the IMS Service Navigator view, expand the server that you created.2. Right-click the Services folder and click Create an IMS mobile transaction

service.3. In the Service name field, enter a name for the service, such as Phonebook.

Figure 5. Input and output messages defined


4. Click Browse next to the Transaction code field. The Specify TransactionMetadata wizard opens.a. In the Transaction name list, select the transaction code that you defined

earlier from the drop down list, such as IVTNO. The Input message isautomatically populated with a reference to your input message metadata<trancode> – INPUT. The Output message is automatically populated witha reference to your input message metadata <trancode> – OUTPUT

b. Click OK.5. In the Interaction properties list, select the interaction properties profile that

you created in Step 3.6. In the Connecton profile list, select the connection profile that you created in

Step 3.7. In the Transaction code override field, ensure that IVTNO is listed.

This field lets you specify the transaction code to use at run time, overridingthe transaction code for the transaction message formats that are defined for aprogram. This option lets you define one set of transaction message formatsfor a given program, but access the program through a REST service by usingpotentially multiple transaction code values at run time. For this phonebookapplication, the transaction code at run time must be IVTNO.

8. Click Next.9. Expand Segment1 under the <trancode> – INPUT and <trancode> – OUTPUT

sections to show the fields in each section.10. The phonebook service requires most of the fields for input message, except

IN_LL and IN_ZZ.a. IN_LL and IN_ZZ are not selected by default. Ensure that they stay

unselected. These are IMS internal fields.b. For IN_TRANCDE, for the phonebook application, set the default field

value to IVTNO.

Tip: The transaction message metadata you created in the previous stepcan be of any name. However, for this phonebook sample application towork, you must specify a default value of IVTNO for the service.

11. For output message, clear the check boxes for OUT_LL and OUT_ZZ.12. Click Finish.13. Verify that your Services folder now contains your newly created service in a

subfolder.

Results

A folder with the name of your service is now created under the Services folder inthe IMS Service Navigator view.

Test the phonebook serviceYou will use IMS Explorer to create an IMS mobile transaction test case and runthe service.

About this task

For a quick test of a newly created service, you can issue a PUT request in a webbrowser with the following URL:https://zcee_hostname:port/zosConnect/services


You should see your service listed among other services in the response in JSONformat:

{"ServiceName":"Phonebook","ServiceDescription":"","ServiceProvider":"imsmobile-2.0","ServiceURL":"https://myserver.mycom.com:8443/zosConnect/services/Phonebook"}

Next, you want to create a test case to test your phonebook service. Creating andrunning a mobile test case allows you to more effectively debug and refine yourservice definition.

Procedure1. In the IMS Service Navigator view, under the Services folder, right-click the

service you just created, such as Phonebook, and select Create a test case.2. In the Create IMS Transaction Service Test wizard, click New Project, enter a

project name such as PhonebookTest in the Project name field, and click Next.3. In the Server name list, select the server you used for this tutorial.4. In the Service name list, select the service you created for this tutorial.5. In the Testcase name field, enter PhonebookTest and click Finish. The test case

editor opens.6. Enter values for the phonebook service input fields. In this test, we will add a

phonebook entry.a. Double-click the IN_TRANCDE row, enter IVTNO, and click OK.b. Double-click the IN_COMMAND row, enter ADD, and click OK.c. Double-click the IN_LAST_NAME row and enter a unique field value (10

characters or fewer) for the last name, and then click OK.d. Double-click the IN_FIRST_NAME row and enter a field value (10

characters or fewer) for first name, and click OK.e. Double-click the IN_EXTENSION row and enter a field value (10

characters or fewer) for phone extension, and click OK.f. Double-click the IN_ZIP_CODE row and enter a zip code value (7

characters or fewer), and click OK.7. Click File > Save.

To run the test case:8. In Project Explorer view, right-click your test case (the .stc file) and select

Run As > IMS Transaction. The Edit Configurations wizard opens.9. In the Name field, enter a name for the test, such as RunPhonebookTest.


10. In the Server name list, select your server from list.11. In the Project name list, select the name you created for the project, and click

Run. The Run a Test Case Console opens. The top portion shows the inputmessage and data that you will use to make the service request, and thebottom panel is where your output will appear.

12. In the Test case name list, select your test case from the list

13. Click the Run button ( ) to test the service.

Results

When the run completes, the OUT_MESSAGE in the Output Message section ispopulated with a response. Your phonebook service was successfully tested if yousee one of the following messages:v ENTRY WAS ADDEDv ADDITION OF ENTRY HAS FAILED (this message indicates that the

IN_LAST_NAME value you specified already exists)

The following output shows an entry was successfully added for John Doe.

Figure 6. The Edit Configuration wizard


If you received an error about the transaction could not be executed with a DFS064message from IMS, your transaction code is not specified correctly.

Tutorial summary:

You have created a service for the IMS phonebook application and tested theservice.

In the first tutorial, you learned the following:v How to create a service by first defining a connection profile for connection with

IMS Connect, an interaction properties profile that describes how to handleinteractions with the transaction, and the message metadata (input and outputmessage mapping) for the phonebook transaction.

v How to test a service by creating a test case in IMS Explorer.

Develop an API to invoke an IMS serviceUse the z/OS Connect EE API Editor to develop a REST API to invoke an IMSservice.

API creation workflow

The JSON schema of an IMS mobile service is obtained from the service archive(SAR) file, which is generated by IMS Explorer. You then use the z/OS Connect EE

Figure 7. Sample result of a test run


API Editor, to map an HTTP method to a service, assign a value to a field in theservice, remove a field from the request or response message, and more.

After the mapping is done, the API can be deployed to the server and you canimmediately test the API, all from within the API Editor. z/OS Connect EE APARPI62820 (V2.0.1.0) and the z/OS Connect EE API Editor V2.0.1.0 or later arerequired for this function.

PrerequisitesExamine the operational requirements, considerations and restrictions to assist theplanning and design of your mobile solution.v The IMS service must be created, deploying, and running properly.v z/OS Connect EE API Editor is downloaded and properly installed.

– z/OS Connect EE API Editor can be downloaded from the Download Eclipsetools page on the mainframe development site at https://developer.ibm.com/mainframe/products/downloads/. The installation instructions are providedon the site.

– z/OS Connect EE APAR PI62820 (V2.0.1.0) and the z/OS Connect EE APIEditor V2.0.1.0 or later are required.

– Updates of the z/OS Connect EE server might require a newer version of theeditor. Check the Chapter 2, “z/OS Connect EE change history,” on page 7topic for any potential compatibility issues.

API creation workflow for IMS mobile servicesImplementation of an IMS mobile solution involves the use of IMS Explorer forDevelopment (IMS Explorer) to create and publish necessary resources to theserver, including connection profiles, interaction profiles, transaction messagemetadata, and service metadata.

Creating the REST API for an IMS mobile service involves the following steps:1. Use IMS Explorer to generate the service archive (SAR) file that contains the

information that the server needs to install and provide the service.2. Create an API project in z/OS Connect EE API Editor and import the service

archive into the project.3. Create the API.

a. Specify the path, query parameters, and HTTP methods.

IMS Mobilefeature

z/OS Connect EE

IMS Explorer for Development z/OS Connect EE API Editor

API archive(AAR)

Servicearchive(SAR)

Figure 8. Creating a REST API for an IMS mobile service from the service archive file




b. Import the service archive to load the service JSON schema into the project.c. Use the mapping editor in the z/OS Connect EE API Editor to map between

the HTTP request/response messages and the service JSON schema.

After the API is created and saved, you can deploy it to the server from within theeditor and test it in the embedded Swagger UI.

Tutorial: Create a REST API for an IMS mobile serviceYou will create a REST API to interact with the IMS phonebook service.

Learning objectives

You will learn the following concepts and steps to create a REST API for thephonebook service you created in “Tutorial: Create an IMS mobile service” on page54.v The concepts associated with REST API design.v The process, the tool, and the artifacts that you need to create a REST API from

a service on the z/OS Connect EE server.v How to deploy and test an API.

Time required

This tutorial should take approximately 90 minutes to finish. If you explore otherconcepts related to this tutorial, it could take longer to complete.

Audience

An API developer who is familiar with RESTful API design principles.

Prerequisitesv A phonebook service is properly created based on “Tutorial: Create an IMS

mobile service” on page 54.v z/OS Connect EE API Editor is downloaded and properly installed.v You will need the service archive (SAR) file that contains the information the

server needs to install and provide the service. The service archive is generatedin IMS Explorer.

Design the API for the serviceWhen composing the API, first identify the resources that can be acted upon by theservice. Then plan the URI paths, the use of path or query parameters, and anyrequirements for input.

About this task

This API layer provides the ability to use HTTP verbs to imply the actions againsta resource, as well as access to path and query parameters.

For the phonebook service, the resource is the contact record. The actions againstthe contact record are to add, display, update, and delete a contact record.

Procedure1. Identify which fields need to be available to accept input (request).


The following table identifies the fields in the phonebook service that need tobe exposed, hidden, or assigned a value. It also demonstrates the API designthought process.

Table 6. Input fields for the phonebook service

Input field Action Description

IVTNO-INPUT-MSG Hide An "01" level element for the record.

IN-LL Hide Internal to the IMS transaction. No need toexpose this field to the API.

IN-ZZ Hide Internal to the IMS transaction. No need toexpose this field to the API.

IN-TRANCDE Assign The value for this field must be the same asthe defined transaction definition. This valuecan be assigned only at the service layer butnot in the API.

IN-COMMAND Expose The API must pass in this value. The valuesmust be either ADD, DISPLAY, DELETE, orUPDATE.

IN-LAST-NAME Expose The key field for the database. This value mustbe unique. Therefore, this field must beexposed.

IN-FIRST-NAME Expose This field is needed for ADD and UPDATEactions.

IN-EXTENSION Expose Same as for IN-FIRST-NAME.

IN-ZIP-CODE Expose Same as for IN-FIRST-NAME.

2. Identify the fields that need to be available for output (response).The following table identifies the fields that need to be made available in theresponse.

Table 7. Output fields for the phonebook service

Output field Action Description

IVTNO-OUTPUT-MSG Hide An "01" level element for the record.

OUT-LL Hide Internal to the IMS transaction. No need toexpose this field to the API.

OUT-ZZ Hide Internal to the IMS transaction. No need toexpose this field to the API.

OUT-MESSAGE Expose The message that indicates the result of theaction. This field needs to be exposed to theAPI.

OUT-COMMAND Expose This field will be made available to the API tobe exposed to the client application if the APIdevelopers intend to do so. A potential use forthis field is a simple verification of thecommand used to achieve the result. This canbe hidden if you don't see a use case for it.

OUT-LAST-NAME Expose This field will be made available to the API tobe exposed to the end users. For all fouractions, this fields should be displayed for theend users.


Table 7. Output fields for the phonebook service (continued)

Output field Action Description

OUT-FIRST-NAME Expose This field will be made available to the API tobe exposed to the client applications if the APIdevelopers intend to do so. For ADD,UPDATE and DISPLAY, this information canbe useful for end user validation purposes. ForDELETE, this field has less value and can behidden by the API.

OUT-EXTENSION Expose Same as for OUT-FIRST-NAME.

OUT-ZIP-CODE Expose Same as for OUT-FIRST-NAME.

OUT-SEGNO Hide Internal to the IMS transaction. No need toexpose this field to the API.

3. Identify the resource and actions that are allowed on the resource.The resource that is being exposed by this service is the phonebook entry, orcontact record. The goal of the API we are creating is to allow users to add,update, display, and delete a contact record.

Table 8. Goals of the API

Action IN-COMMAND value HTTP Verb

Add a contact ADD POST

Update a contact UPDATE PUT

Display a contact DISPLAY GET

Delete a contact DELETE DELETE

4. Identify URI paths and query parameters.The next step is to plan the URI paths, the use of path or query parameters,and input JSON requirements:

Table 9. URI path planning

Action HTTP verb Path

Add a contact POST /phoneBook/contacts + JSON body

The HTTP verb POST implies the action("add"), so in the API mapping we willassign the value ADD to theIN-COMMAND field. The JSON will carryin the four contact record values: last name,first name, extension and zip code.

Update a contact PUT /phoneBook/contacts/{lastName} + JSONbody

The HTTP verb PUT implies the action("update"), so in the API mapping we willassign the value UPDATE to theIN-COMMAND field. The resource to actupon is specified as a path parameter, whichwill get mapped to the LAST-NAME field.The JSON will carry in the three othercontact record values: first name, extensionand zip code.


Table 9. URI path planning (continued)


Display a contact GET /phoneBook/contacts/{lastName}

The HTTP verb GET implies the action("retrieve" or "display"), so in the APImapping we will assign the value DISPLAYto the IN-COMMAND field. The transactionsupports the display of a single contactrecord, not a range.

Delete a contact DELETE /phoneBook/contacts/{lastName}

The HTTP verb DELETE implies the action("delete"), so in the API mapping we willassign the value DELETE to theIN-COMMAND field. The transactionsupports the delete of a single contactrecord, not a range. Therefore, we use a pathparameter. The API will map this pathparameter value to the last name field.

5. Identify output for each action.The output for each action is as follows:

Table 10. Output for each action

Action Fields to return

Add a contact v OUT-MESSAGE: To indicate success or failure of theaction.

v LAST-NAME, FIRST-NAME, EXTENSION, ZIP-CODE: Toallow for validation of the added contact record.

Update a contact The same as adding a contact.

Display a contact The same as adding a contact.

Delete a contact v OUT-MESSAGE: To indicate success or failure of theaction.

v LAST-NAME: To allow for validation of the deletedrecord.

Results

With the API design identified, you are ready to create the API.

Generate a service archive from an IMS transactionGenerate a Service Archive (SAR) file in IMS Explorer. This file is needed by thez/OS Connect EE API Editor to create an API.

About this task

The SAR file contains the information that is needed by IMS Mobile feature toenable the service as a JSON asset.

Procedure1. Open IMS Explorer.2. Ensure you are in the IMS Mobile perspective.


3. In the IMS Service Navigator view, expand the z/OS Connect EE Servers folderand then the Services folder.

4. Right-click the phonebook service you created in “Tutorial: Create an IMSmobile service” on page 54 and select Export transaction service archive. TheExport Service Archive dialog opens.

5. Select Local file system, and browse to the folder where you want to save theservice archive file.

Results

A <service_name>.sar file is saved in the location you specified.

Create an API projectUse the z/OS Connect EE API Editor to create an API project and define the APIname and base path.

About this task

You can create an API project and define the API in the z/OS Connect EnterpriseEdition perspective.

Procedure1. Open the Eclipse tool (IBM Explorer for z/OS Aqua or IMS Explorer) in which

you installed the z/OS Connect EE API Editor.2. Switch to the z/OS Connect Enterprise Edition perspective.

a. From menu bar, select Window > Open Perspective > Other.b. In the list of perspectives, select z/OS Connect Enterprise Edition and click

OK.

You are now in the z/OS Connect Enterprise Edition perspective, with relatedviews and resources readily available.

3. Create an API project.a. From the menu bar, select File > New > z/OS Connect EE API Project. The

z/OS Connect EE API Project wizard opens.b. Enter the project properties:

Table 11. Input fields for the phonebook servicee

Project property DescriptonSample value tospecify

Project name Unique alphanumeric name for your project.This is the name of the project in Eclipse.

phoneBook

API name The name of your API. This is the name bywhich the z/OS Connect EE server knowsabout this API.

contacts

Base path The unique basePath attribute that specifiesthe root of all the resources in this API. Thispath is used by REST clients in the URI theysend in to invoke the API.

/phonebook

Description Optional field to provide a description ofthis API for documentation purposes.

This is an API formanaging contacts.

c. Click Finish.


Results

The API project is created in the Project Explorer view. The API package.xml fileopens in the API Editor where you can model your API.

Create the APICreate the API by defining the API front end, associating the API with a service,and mapping JSON request and response messages to the input and outputmessages of the IMS transaction as exposed in the service.

About this task

In this step, you will import the service archive file (a .sar file) for the phonebookservice into the API project you created in z/OS Connect EE API Editor, and mapthe input and output messages for each HTTP verb (action).

For the API design, our goal is to create the following APIs for adding, updating,displaying, and deleting a contact record, as defined in “Design the API for theservice” on page 68. The path of the API is /<base_path>/<api_name>, and in thiscase, the path is /phoneBook/contacts

Table 12. URI path planning


Add a contact POST /phoneBook/contacts

Display a contact GET /phoneBook/contacts/{lastName}

Update a contact PUT /phoneBook/contacts/{lastName}

Delete a contact DELETE /phoneBook/contacts/{lastName}

Two paths are needed:v /phoneBook/contacts: This path is needed only by the POST action (ADD).v /phoneBook/contacts/{lastName}: This path is needed by the GET, PUT, and

DELETE methods, and you will need to define last name as a parameter.

Procedure

You will define a /phoneBook/contacts path and an associated POST method:1. In the Project Explorer view, right-click the phonebook folder (or your project

name, if you use a different value), and select z/OS Connect EE > Importz/OS Connect EE Services. The Import z/OS Connect EE Services wizardopens.

2. Click File System to navigate to where the phonebook service archive file isstored. Select the .sar file and click OK.

For the POST verb to add contact information for a given last name, in the nextstep you will:a. Define the path value.b. Map the request message for the action.c. Map the response message for the action.3. In the z/OS Connect EE API Editor where the package.xml is displayed, set

the path to /contacts. The default base path for this API is /phoneBook, so itdoes not need to be included.


For the POST action, we want to ADD a contact record, and therefore:v IN_COMMAND needs to be assigned a value of ADD. This field should be

hidden from end users whenever this API is called.v The other input fields can be left alone with their default mapping. These

fields should be allowed to be exposed to end users for them to specify thevalues.

4. Remove the GET, PUT, and DELETE methods by clicking the remove button (

) next to these methods. You have created the front end of your API.Now the API needs to be connected to the back-end application in IMS.

To associate a service with the API:5. For the POST method, click Service next to the method. The Select a z/OS

Connect EE Service window opens.6. Select the phonebook service archive file you generated in an earlier step and

click OK.7. Save your project by clicking File > Save (or press Ctrl-S).

Now map your API request to fields in the service:8. Click the Mapping button next to the POST method and select Open Request

Mapping. If you have not saved your project or latest changes, a dialog opensto prompt you to save the package.xml file. Click OK to save the changes, andthe request mapping editor opens.

Figure 9. Adding a path for the API


9. Expand the IVTNO_INPUT_MSG section on the left by clicking the expandbutton ( ). The following image shows the expanded IVTNO_INPUT_MSGsection.

a. The right side of the interface (labeled with the letter "a") shows the fieldsthat are exposed by the service for the request.

b. The upper left of the interface (labeled with the letter "b") shows fields thatwill be exposed through the API and made available to the REST clients.By default, it is a one-to-one mapping to the fields that are exposed by theservice unless you change the mapping.

c. The lower left of the interface (labeled with the letter "c") shows the HTTPrequest, which can consist of one or more headers, path parameters, queryparameters, and the request body.

For the POST action, we want to ADD a contact record with the followinggoals:v IN_COMMAND needs to be assigned a value of ADD. This field should be

hidden from end users whenever this API is called.

Figure 10. Request mapping for the POST method

Figure 11. Request mapping for the POST method


v The other input fields can be left alone with their default mapping. Thesefields should be allowed to be exposed to end users for them to specify thevalues.

We will achieve these goals in the next few steps.10. Right-click the IN_COMMAND field in the service definition (section A in

Figure 3, and select Add Assign transform. An Assign box shows up in themiddle.

11. Click the Assign box, and the Transform - Assign properties view opens.12. In the Value field, enter ADD, and leave the Omit from interface checkbox

checked to exclude this value from the Swagger document so it is not exposedin the API.

13. Click File > Save (or press Ctrl-S) to save your mapping.14. Close the request mapping tab.You have defined how the request message should be mapped. You will nowdefine what will be in the response message.15. Click the Mapping button next to the POST method and select Open

Response Mapping.

16. From among the six output fields, we don't need to send OUT_COMMANDback to the user, so we need to remove it by right-clicking OUT_COMMANDand select Add Remove transform.

Figure 12. Assigning a fixed value to the IN_COMMAND field


17. Click File > Save (or press Ctrl-S) to save your mapping.18. Close the response mapping tab.

Results

You have defined the POST method to add a contact record and how the requestand response messages are mapped to the data fields in the service. The next stepis to define a new path that will take last name as a parameter for the GET, PUT,and DELETE methods. You can skip this step and proceed directly to deploy andtest the API if you already understand how the API design and developmentprocess works.

(Optional) Create the API, part 2Define another path and data mapping for the PUT, GET, and DELETE verbs. Youcan skip this step and proceed directly to deploy and test the API if you alreadyunderstand how the API design and development process works.

About this task

In this step, you will define a new path, /phoneBook/contacts/{lastName}, and thedata mapping for the associated PUT, GET, and DELETE verbs.

Table 13. Output for the display and delete actions

ActionHTTPVerb Fields to return

Display a contact GET v IN-COMMAND to be assigned a value of DISPLAY.

v Fields to return:

– OUT-MESSAGE: To indicate success or failure of theaction.

– LAST-NAME, FIRST-NAME, EXTENSION, ZIP-CODE

LAST-NAME, FIRST-NAME, EXTENSION, andZIP-CODE.

Figure 13. Removing a field from the response messasge


Table 13. Output for the display and delete actions (continued)

ActionHTTPVerb Fields to return

Update a contact PUT v IN-COMMAND to be assigned a value of UPDATE.

v Fields to return:


– LAST-NAME, FIRST-NAME, EXTENSION, ZIP-CODE:To allow for validation of the updated contact record.

Delete a contact DELETE v IN-COMMAND to be assigned a value of DELETE.

v Fields to return:


– LAST-NAME: To allow for validation of the deletedrecord.

Procedure

To display, update, or delete a contact record for a given last name, define the pathvalue and the map the request and response message for the action:1. In the z/OS Connect EE API Editor where the package.xml is displayed, add a

path by clicking the Add a new path button ( ) next to the “Path” label.

2. Enter the API path and the path parameter, lastName, enclosed in curlybrackets. In this case, it is /contacts/{lastName}

3. Remove the POST method by clicking the remove button ( ) next to themethod.

The GET method For the GET method (querying a contact record by last name),map the data structure between the service JSON schema and the HTTP requestand response messages.

Figure 14. Adding another path for the API


4. For the GET method, click Service next to the method, select the phonebookservice archive file, and click OK.

5. Click File > Save or press Ctrl-S to save the service association.6. Click Mapping next to the GET method and select Open Request Mapping.

7. Right-click the IN_COMMAND field in the service definition on the right, andselect Add Assign transform. An Assign box shows up in the middle.

8. Click the Assign box, and the Transform - Assign properties view opens.9. For the Value field, enter DISPLAY.

10. Because only the last name is needed for the request and the other fields arenot needed, remove those fields so they are hidden from the client.a. Hold down the Ctrl key to select multiple fields: IN_EXTENSION,

IN_FIRST_NAME, and IN_ZIP_CODE.b. Right-click and select Add Remove transform.

The last step is to map the path parameter lastName from the HTTP Requestsection to the IN_LAST_NAME field.

Tip: You can right-click the field to undo an action, or right-click the addedaction button to delete the action.

11. Click and drag the lastName path parameter field in the HTTP Request sectionto the IN_LAST_NAME field on the right.

Figure 15. Removing unneeded fields from the requests


No JSON body is sent in with this request. All the information needed todisplay a contact record is carried in on the URI with the path parameter.

12. Click File > Save (Ctrl-S) to save your request mapping.13. Close the request mapping tab.

The next step is to map the response. For the given last name, we want toreturn all fields except the OUT_COMMAND field, so we need to remove thisfield from the response.

14. Click Mapping next to the GET method and select Open Response Mapping.15. Right-click OUT_COMMAND on the right, and select Add Remove

transform.

16. Click File > Save (Ctrl-S) to save your response mapping and close theresponse tab.

Figure 16. Mapping the lastName path parameter to the IN_LAST_NAME field

Figure 17. Removing the OUT_COMMAND field from the response


The PUT method For the PUT method (updating a record), the request andresponse mapping is similar to the GET method. The key tasks are as follows:v Assign a service that is associated with this method.v Assign a static value to the IN_COMMAND field. The command to update a

record in the phonebook application is UPDATE, so set the static value toUPDATE.

v The lastName path parameter is the key and its value needs to be moved to theIN_LAST_NAME field.

v The IN_FIRST_NAME, IN_EXTENSION and IN_ZIP_CODE fields need to beexposed in the JSON body for this request for users to update.

17. Map the request for the PUT method so the mapping looks as follows:

18. Save your changes.19. Close the request tab.

Next map the response message. All fields should be returned to allow usersto validate their updates.

20. Map the response for the PUT method as follows:

21. Save your changes and close the response tab.

Figure 18. Request mapping for the PUT method

Figure 19. Response mapping for the PUT method


Tip: With this mapping design, if only the extension for a specified last nameis provided in the request message, the first name and zip code fields will beupdated as blank. Ensuring that field values are not incorrectly wiped outwould be the responsibility of the mobile application developer.

The DELETE method For the DELETE method (deleting a record), the keymapping tasks are as follows:v Assign the service that is associated with this method and savev Assign a static value to the IN_COMMAND field. In this case, the command to

delete a record in the phonebook application is DELETE, so set the value toDELETE.

v The lastName path parameter is the key and its value needs to be moved to theIN_LAST_NAME field.

v No fields need to be exposed in the request, so IN_EXTENSION,IN_FIRST_NAME, and IN_ZIP_CODE should be removed.

22. Map the request for the DELETE method so the mapping looks as follows:

23. Save your changes and close the request tab.Next map the response message. For a delete operation, all we are interestedin is whether the action succeeded. This information is indicated inOUT_MESSAGE. We can remove all fields, except OUT_MESSAGE, should beremoved.

24. Map the response for the DELETE request as follows:

Figure 20. Request mapping for the DELETE method


25. Save your changes and close the response tab.

Results

The API is now completed.

Deploy the APIDeploy the API directly from z/OS Connect EE API Editor by first creating aconnection to the server.

About this task

In this step, you will first create a connection to the z/OS Connect EE and thendeploy the API to the server.

Tip: Starting from this step, you must have z/OS Connect EE V2.0.1.0 (APARPI62820) and z/OS Connect EE API Editor V2.0.1.0 or later.

Procedure1. In the Host Connections view, click Add and select z/OS Connect Enterprise

Edition.2. Specify the following information for your environment:

Table 14. Adding a server connection

Field Description

Name A descriptive name for the server connection.

Host name The name or the IP address of the server.

Port number The port number.

Select the Secure connection (TLS/SSL) checkbox for secureconnections.

3. Click Save and Connect to save the definition and connect to the server. Youwill be prompted to either specify an existing credential to use, or create acredential at this time.

4. After you select an existing credential or create a new one, click OK to use thecredential to connect. The defined host connection shows up in the z/OS

Figure 21. Response mapping for the DELETE method


Connect EE Servers view. Deployed API packages are listed under the APIsfolder.

To deploy your API:5. In the Project Explorer view, right-click your API project and select z/OS

Connect EE > Deploy API to z/OS Connect EE Server.6. In the Deploy API window, select the server to which to deploy the API.7. Click OK. Deployment result is reported. A deployed API is automatically

started unless specified otherwise in the z/OS Connect EE preferences window.

Results

Your API is deployed and ready to be tested.

Test the APIYou can test your API directly from z/OS Connect EE API Editor by using the "Tryit out!" function in Swagger UI that is embedded in the editor.

About this task

In this step, you will test the deployed API in Swagger UI. For each operation, youcan provide values for the exposed fields (as parameters) to test the API andexamine the associated request URL, request headers, response body, responsecode, and response headers.

Procedure

To test your API:1. In the z/OS Connect EE Servers view under the APIs folder, double-click your

API. The API is opened in the Swagger UI.2. Click List Operations to see available operations in the API.

3. Test adding a contact record by clicking POST.a. Click the Example Value box to copy the request message format into your

phonebook POST request.b. Specify the last name, first name, zip code, and extension.

Figure 22. Operations in the API


c. Click Try it out!. Information about the request URL, request headers,response body, response code, and response headers are provided. Theresponse body contains the output message. The OUT_MESSAGE wouldcontain one of the following messages:v ENTRY WAS ADDEDv ADDITION OF ENTRY HAS FAILED (this message indicates that the

IN_LAST_NAME value you specified already exists)4. Proceed to test other methods and examine the results.

Results

You have created, deployed, and tested the API.

Tutorial summary:

You have completed the tutorial for creating and deploying an API for an IMSmobile service.

You learned the following:v The concepts associated with REST API design.v The process, the tool, and the artifacts that you need to create a REST API from

a service on the z/OS Connect EE server.v How to deploy and test an API.

Configure an HA environment that uses the WOLA service providerUsing this scenario, you can configure a highly available z/OS Connect EEenvironment that uses the WOLA service provider to connect to CICS TransactionServer.

This scenario uses two z/OS Connect EE servers with shared configuration, APIpackages, WSBind files, and JSON schemas, and uses TCP/IP port sharing todistribute requests across the servers.

This scenario uses the API and services that were developed in the scenario“Develop an API to invoke a CICS service via WOLA” on page 17 to start the

Figure 23. Operations in the API


CICS Catalog Manager, a sample application provided by CICS Transaction Server.A server template is provided which creates a server that is preconfigured with theAPI and services for this scenario. This template includes the API package andservice artifacts.

Note: For more information about the concepts of high availability and the optionsyou can choose, see Chapter 7, “High availability,” on page 167.

This scenario shows you how to configure a simple z/OS Connect EE HAenvironment for a single z/OS LPAR. The configured environment has thefollowing characteristics:v Two z/OS Connect EE servers with workload that is distributed to them using

TCP/IP port sharing with WLM.v Two CICS Transaction Server regions.v Each z/OS Connect EE server is configured to use WOLA to connect to a single

CICS Transaction Server region.v Server configuration files, API packages, WSBind files, and JSON schemas are

shared between the two z/OS Connect EE servers to maintain a consistentconfiguration between servers.

To simplify setting up and testing the HA environment the following configurationchoices are used, which are not common for a production environment:v Polling of the server configuration file is enabled. Polling allows the servers to

automatically pick up configuration changes as the scenario progresses, withoutthe need to restart the server or invoke the FileNotificationMbean. Inproduction, it is more common to disable polling to avoid unnecessary CPUusage when monitoring a typically static file.

v HTTPS is not used, and HTTP examples are used throughout the scenario. Thisscenario is focused on the specific HA configuration, rather than security, sousing only HTTP avoids the need to create and configure certificates to secureconnections. If HTTPS is required in your environment, then you can follow thesame steps, but you must enable, configure, and share the HTTPS port andconfigure the client application for HTTPS when you test this scenario.

This scenario uses the following values:


Description Value

z/OS LPAR host name companyhost.company.com

z/OS Connect server 1 server name haserver1


z/OS Connect server Started Task procedurename

BAQSTRT

z/OS Connect server 1 Started Task jobname

ZCHA1

z/OS Connect server 2 Started Task jobname

ZCHA2

z/OS Connect servers shared HTTP port 11111

PrerequisitesThese requirements are needed to run this scenario.


Before you create a high availability environment, you must first create thesupporting infrastructure. This includes a single z/OS Connect EE server that usesWOLA to connect to CICS as shown in Figure 1. When this configuration iscomplete, you can then create the high availability environment.

Software requirementsv z/OS Connect Enterprise Edition installed and zconsetup install command runv CICS Transaction Server 4.2 or later installed and two running CICS regions.

Prerequisite tasks

You need to complete the following tasks to provide the infrastructure that isneeded by the scenario.1. Install z/OS Connect EE. For more information, see Chapter 5, “Installation

information,” on page 111.2. Configure a started task to run a z/OS Connect EE server.

To set up the started task, customize the sample JCL <installation_path>/jcl/baqstrt.jcl and add it to your PROCLIB library. Then, enter the SAFcommand to associate the name of the started task procedure with a user ID.For example, to define the BAQSTRT procedure name to run under the user ID<userid>, use the following RACF command:



3. Configure the Liberty angel process as described in “Configuring the Libertyangel process and z/OS authorized services” on page 185. The angel process isrequired by WOLA to access z/OS authorized services.

4. In the following tasks, you configure your initial environment for a single z/OSConnect EE server to connect to a single CICS region using WOLA.

Configuring the CICS Catalog Manager example applicationTo run this scenario, you need to install and configure the CICS “Catalog Managerexample application”.

Figure 24. A single server environment


About this task

This scenario uses the CICS Catalog Manager sample application as an example ofan existing CICS application to be exposed as an API. This application must beinstalled and configured in both your target CICS regions. If this application is notyet configured, follow this procedure. For more information, see The CICS catalogmanager example application in the CICS Transaction Server documentation.








2. Test that the application is installed and configured correctly. Follow theinstructions in Running the example application with the BMS interface.

Results

The sample application is now configured on CICS and can be run by using theBMS interface. Follow the remaining steps to access this application from z/OSConnect EE.

Configuring CICS to use WOLAConfigure the example CICS application and configure both CICS and SAF to useWOLA.

Before you begin

Complete the tasks in “Prerequisites” on page 86 and “Configuring the CICSCatalog Manager example application” on page 87.

About this task

Configure CICS to use WebSphere Optimized Local Adapters (WOLA). WOLA isthe service provider that allows z/OS Connect EE requests to interact with z/OSassets.

Procedure

Follow the instructions in “Configuring CICS to use WebSphere optimized localadapters (WOLA)” on page 124. This scenario uses the following values:







Parameter Region 1 Region 2

Group ZC1DGN ZC2DGN

Name 2 ZC1NDN ZC2NDN

Name 3 ZC1SVN ZC2SVN

When you define the SAF CBIND profile, use the same values. For example, if youare using RACF, choose one of these options:v To use explicit definitions, enter the following commands:

RDEF CBIND BBG.WOLA.ZC1DGN.ZC1NDN.ZC1SVN UACC(NONE)PERMIT BBG.WOLA.ZC1DGN.ZC1NDN.ZC1SVN CLASS(CBIND) ACCESS(READ) ID(CICSID)RDEF CBIND BBG.WOLA.ZC2DGN.ZC2NDN.ZC2SVN UACC(NONE)PERMIT BBG.WOLA.ZC2DGN.ZC2NDN.ZC1SVN CLASS(CBIND) ACCESS(READ) ID(CICSID)

v To use wildcards, and create only a single definition, enter the followingcommands:

RDEF CBIND BBG.WOLA.* UACC(NONE)PERMIT BBG.WOLA.* CLASS(CBIND) ACCESS(READ) ID(CICSID)

v Use your own values. If you choose this option, ensure that you use the samevalues in the corresponding steps later in the scenario. You must create a uniquedefinition for each server.

Creating the initial serverCreate a z/OS Connect EE server from a template and configure CICS to useWOLA.

About this task

You create an initial z/OS Connect EE server, and then copy the configuration tocreate multiple servers for an HA environment.

Procedure1. Change to the <installation_dir>/bin directory. For example,

/usr/lpp/IBM/zosconnect/v2r0/bin.2. Enter the following command.

zosconnect create haserver1 --template=zosconnect:sampleWolaCatalogManager

This command creates a server that is named haserver1 by using thesampleWolaCatalogManager template. This template creates a server with an APIand three services that are configured to call the catalog manager CICSapplication that uses WOLA. The server is created in the <WLP_USER_DIR>/servers directory.

3. Start the z/OS Connect EE server. To preserve the case of your server name,you must start the server from the System Command Extension window withinSDSF.From SDSF, type / to open the extended console, then enter the command:

S BAQSTRT,JOBNAME=ZCHA1,PARMS=’haserver1 –clean’



CWWKB0103I: Authorized service group LOCALCOM is available.CWWKB0103I: Authorized service group WOLA is available....CWWKB0501I: The WebSphere Optimized Local Adapter channel registered with the Liberty profile server with the following name:ZC1DGN ZC1NDN ZC1SVN...J2CA7001I: Resource adapter wola installed in 0.327 seconds.




three part name values you provided in the server.xml file. This messageindicates that an external address space might register into the LibertyProfile server by using this three-part name on the BBOA1REG API.

v The J2CA7001I message indicates that the WOLA JCA resource adapter isavailable.


z/OS Connect Enterprise Edition server must be running.a. Open a session with the CICS region and type the following command:

BBOC START_TRUE


b. Type the following command as one line to start the link server task andregister to your server:

BBOC START_SRVR RGN=CICSREG DGN=ZC1DGN NDN=ZC1NDN SVN=ZC1SVN SVC=* TXN=N REU=Y








{"apis": [

{"name": "catalog","version": "1.0.0","description": "API for the CICS catalog manager example application","adminUrl": "http://companyhost.company.com:9080/zosConnect/apis/catalog"

}]

}

7. From a web browser, enter an HTTP GET request to call the API to inquire on asingle catalog item:http://companyhost.company.com:9080/catalogManager/items/10

Wherev catalogManager is the base path value that is defined in the API definitionv 9080 is the HTTP port the z/OS Connect EE server uses to listen for HTTP


itemv 10 is the runtime value for the path parameter value {itemID}.If your API request is successful, the following response is received:

{"DFH0XCMNOperationResponse": {

"ca_return_code": 0,"ca_response_message": "RETURNED ITEM: REF =0010","ca_inquire_single": {"ca_single_item": {

"in_sngl_stock": 129,"ca_sngl_description": "Ball Pens Black 24pk","ca_sngl_item_ref": 10,"on_sngl_order": 0,"ca_sngl_cost": "002.90","ca_sngl_department": 10

}}

}}

What to do next

The prerequisites are complete. You can now begin creating your HA environment.

Setting up HA for the first serverModify an existing server to prepare it for a HA environment.

In this step, you modify the configuration of the existing z/OS Connect EE serverin preparation to add the second server. You must make the followingmodifications:v Create a shared TCP/IP port.v Split the server configuration file into content that can be shared between

servers and that which is server-specific.v Move the API and service artifacts to a shared location.

Setting up TCP/IP port sharingSet up port sharing so the z/OS Connect EE servers in the HA environment canlisten on the same port.


Procedure1. Choose an unreserved port number to be used for the servers' HTTP listeners.

This scenario uses port 11111 as an example, but it can be changed if it isalready in use in your environment. To display ports that are currently reservedon a single TCP/IP stack, use one of the following methods:v Enter the following SDSF command, where procname is the name of the

TCP/IP stack:

/D TCPIP,<procname>,N,PORTL

v Enter the UNIX System Services command:

netstat –o

2. Configure the shared ports in z/OS to use SHAREPORTWLM.a. In the TCP/IP profile for the z/OS LPAR, add or update an existing PORT

statement to add an entry for the HTTP port the server is listening on. Inthis scenario, port 11111 was chosen, with started task job names that startwith “ZCHA” and the SHAREPORTWLM option to allow WLM to managethe incoming workload. The shared port definition in the TCP/IP portprofile is as follows.PORT11111 TCP ZCHA* SHAREPORTWLM

b. Enable the shared port definitions. Enter the SDSF command

VARY TCPIP,<procname>,OBEYFILE,<datasetname>

For further instructions see the description of the VARY TCPIP,,OBEYFILEcommand in the z/OS Communications Server: IP System Administrator'sCommands documentation.

3. Confirm that the shared port is active. To display ports that are currentlyreserved on a single TCPIP stack, use one of the following methods.v Enter the following SDSF command, where procname is the name of the

TCP/IP stack:



netstat –o

The output includes the port number with a FLAGS value of DASW:

PORT# PROT USER FLAGS RANGE SAF NAME11111 TCP ZCHA* DASW

SW indicates that the port is shared and that the port uses WLM server-specificrecommendations.

4. Update the existing httpEndpoint element in server.xml to use the shared port.For example,<httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="11111" httpsPort="-1" />

Creating a shared configuration fileServers in an HA environment share common elements of the configuration file.


http://www.ibm.com/support/knowledgecenter/SSLTBW_2.2.0/com.ibm.zos.v2r2.halu101/varyp1b.htm#varyp1b

About this task

To ensure that both servers in the HA environment can handle the same workload,some elements from the server.xml file for each server are shared from a commonconfiguration file. Configuration elements that are unique to a server are defined ina separate server.xml file.

Procedure1. Create directories under /var/zosconnect to store the shared configuration file.

For example, run the following command from the /var/zosconnect directory.

mkdir –p shared/config

2. Move the current server.xml file that is used by haserver1 to the sharedconfiguration directory and rename it to haserver.xml. For example, run thefollowing command as a single line:

mv /var/zosconnect/servers/haserver1/server.xml/var/zosconnect/shared/config/haserver.xml

3. Create a file named server.xml for haserver1 in the /var/zosconnect/servers/haserver1 directory with the following elements:<?xml version="1.0" encoding="UTF-8"?><server description="z/OS Connect EE HA server1">

<include location="${shared.config.dir}/haserver.xml"/></server>

This configuration file includes the shared haserver.xml by using the Libertyproperty ${shared.config.dir} to reference the directory that contains the sharedconfiguration files. This property points to the directory WLP_USER_DIR/shared/config.

4. Move configuration elements that are unique for each server to the specificserver server.xml file. For this scenario, the only element that must be uniqueis the three-part WOLA group name, which identifies the Liberty server forWOLA connections. Remove the zosLocalAdapters element from/var/zosconnect/shared/config/haserver.xml and add it to/var/zosconnect/haserver1/server.xml.<zosLocalAdapters wolaGroup="ZC1DGN" wolaName2="ZC1NDN" wolaName3="ZC1SVN" />

Setting up shared resourcesMove the API and service artifacts to a shared location so they can be accessed byboth servers.

About this task

To ensure that workload distribution can route requests to any of the z/OSConnect EE servers that are available in a port shared group, the servers musthave the same APIs and services available. For more information, see “Sharingserver configuration” on page 170.

Procedure1. Create directories under /var/zosconnect to store the API package, WSBind

files, and JSON schemas.Run the following command from the /var/zosconnect/shared directory:

mkdir –p resources/zosconnect/apis resources/zosconnect/services

2. Move your API .aar files to /var/zosconnect/shared/resources/zosconnect/apis

Enter the following command on a single line:

mv /var/zosconnect/servers/haserver1/resources/zosconnect/apis/*.aar/var/zosconnect/shared/resources/zosconnect/apis

3. Move your WSBind files and JSON schemas to /var/zosconnect/shared/resources/services

Enter the following commands, on single lines:

mv /var/zosconnect/servers/haserver1/resources/zosconnect/services/*.wsbind/var/zosconnect/shared/resources/zosconnect/services

mv /var/zosconnect/servers/haserver1/resources/zosconnect/services/*.json/var/zosconnect/shared/resources/zosconnect/services

4. In /var/zosconnect/shared/config/haserver.xml, update thezosconnect_zosConnectDataXform element to point to the new services artifactlocation. Change the bindFileLoc, requestSchemaLoc, and responseSchemaLocattributes to ${shared.resource.dir}/zosconnect/services. For example,<zosconnect_zosConnectDataXform id="xformJSON2Byte"

bindFileLoc="${shared.resource.dir}/zosconnect/services"bindFileSuffix=".wsbind"requestSchemaLoc="${shared.resource.dir}/zosconnect/services"responseSchemaLoc="${shared.resource.dir}/zosconnect/services"requestSchemaSuffix=".json" responseSchemaSuffix=".json"/>

5. Update the zosconnect_zosConnectAPIs element to configure the shared APIlocation ${shared.resource.dir}/zosconnect/apis. For example,<zosconnect_zosConnectAPIs

location="${shared.resource.dir}/zosconnect/apis" updateTrigger="polled" />

6. Restart the server for the new API location to take effect. From SDSF enter thefollowing command to stop the server,

/P ZCHA1

From SDSF, type / to open the extended console, then enter the command:

S BAQSTRT,JOBNAME=ZCHA1,PARMS=’haserver1 –clean’

Results

The HA environment is now set up for the first server.

Adding a second serverAdd a second server to the HA environment.

Procedure1. Run the zosconnect create command to create the second server. The

configuration from the first server is copied across for the second server in alater step so no template is required now. Run the following command fromthe <installation_dir>/bin directory. For example, /usr/lpp/IBM/zosconnect/v2r0/bin.

zosconnect create haserver2


2. Replace the default Liberty server.xml file with the server.xml file fromhaserver1. Run the following command:

cp /var/zosconnect/servers/haserver1/server.xml /var/zosconnect/servers/haserver2

3. Update the second server configuration in /var/zosconnect/servers/haserver2/server.xml so that the three-part WOLA group name is unique foreach z/OS Connect EE server in the LPAR. Change the following attributes ofthe zosLocalAdapters element:<zosLocalAdapters wolaGroup="ZC2DGN" wolaName2="ZC2NDN" wolaName3="ZC2SVN" />


S BAQSTRT,JOBNAME=ZCHA2,parms='haserver2 --clean'

a. Check the server's message log file in <WLP_USER_DIR>/servers/{servername}/logs/messages.log. The following messages appear:CWWKB0103I: Authorized service group LOCALCOM is available.CWWKB0103I: Authorized service group WOLA is available....CWWKB0501I: The WebSphere Optimized Local Adapter channel registered with the Libertyprofile server with the following name: ZC2DGN ZC2NDN ZC2SVN...J2CA7001I: Resource adapter wola installed in 0.327 seconds.




three part name values you provided in the server.xml file. This messageindicates that an external address space might register into the LibertyProfile server by using this three-part name on the BBOA1REG API.


5. Ensure that the second CICS region is started6. Start the TRUE and Link Server task from CICS, and register with WOLA. The

z/OS Connect Enterprise Edition server must be running.a. Open a session with the second CICS region and type the following

command:

BBOC START_TRUE


b. Type the following command as one line, to start the link server task andregister to your server:

BBOC START_SRVR RGN=CICSREG DGN=ZC2DGN NDN=ZC2NDN SVN=ZC2SVN SVC=* TXN=N REU=Y

The following message indicates success:

WOLA TRACE 0: Start server completed successfully.


Testing the scenarioTest the HA configuration and validate that it is distributing work across bothservers.

About this task

To confirm that the HTTP requests are distributed to both z/OS Connect EEservers in turn, the usage count of the Catalog Manager program DFH0XCMN ineach region is checked. Therefore, this count is checked before and after eachrequest to determine which CICS region and which z/OS Connect EE serverprocessed the request.

You can test this scenario from both a web browser and the command line toolcurl. curl is an open source command line tool and library for transferring datawith URL syntax. It is supported on many operating systems. For moreinformation about curl, see the website https://curl.haxx.se/.

Note: Persistent HTTP connections from a client can result in multiple requeststhat are sent to the same server, rather than being distributed across the HAenvironment. Persistent connections are a good practice, as it improvesperformance by not creating a new connection for every request, but it can falselyindicate that workload is not being distributed correctly by TCP/IP port sharing.To prevent a web browser from using the same connection, you can use a privatebrowsing mode, common in most modern browsers, for the second connection.

Procedure1. Log on to a CICS terminal for each CICS region and check the initial usage

count of the Catalog Manager program DFH0XCMN in each region. Make anote of the values to confirm in later steps that the count was incremented.Enter the following command on each CICS region:

CEMT I PROG(DFH0XCMN)

The use field indicates how many times the program was run.

2. Send an HTTP GET request to call the API and get item 10 from the catalog.v If you are using a web browser, enter an HTTP GET request to

http://companyhost.company.com:11111/catalogManager/items/10

v If you are using curl, enter the command:

curl -G http://companyhost.company.com:11111/catalogManager/items/10



https://curl.haxx.se/

In both cases, the expected response is the same.

{"DFH0XCMNOperationResponse":{"ca_return_code":0,"ca_response_message":"RETURNED ITEM:REF=0010","ca_inquire_single":{"ca_single_item":{"ca_sngl_item_ref":10,"in_sngl_stock":132,"ca_sngl_description":"Ball Pens Black 24pk","ca_sngl_cost":"002.90","ca_sngl_department":10,"on_sngl_order":0}}}}

3. On both CICS regions, check that the usage count was incremented by 1 in oneregion only.

4. Send a second HTTP GET request to call the API and get item 10 from thecatalog.v If you are using a web browser, open a private browsing window to establish

a new HTTP connection. In the second private window, issue an HTTP GETrequest to http://companyhost.company.com:11111/catalogManager/items/10

v If you are using curl, the connection is not persistent, so enter the samecommand from step 2:curl -G http://companyhost.company.com:11111/catalogManager/items/10



5. Check that the usage count was incremented by 1 on the other CICS region.

Results

Your HA environment is now set up. You can add more servers by repeating thesteps in “Adding a second server” on page 94

Further capabilities of the HA scenarioWhen you have completed the HA scenario, you can try these tasks to makeyourself more familiar with the value and capabilities of High Availability.

Adding an APIYou can use the shared API location directory and configuration files to deploy anew API and associated configuration to all servers in the HA environment.

Before you begin

Clear the SMF data sets. The method that you use depends on how your SMF datasets are configured. If unsure, contact your system programmer.

About this task

To demonstrate the advantages of sharing a configuration between servers in a HAenvironment, this task shows you how to add an API to the shared API location,update server.xml to configure an interceptor for the new API, and check thatboth servers picked up the changes. The server.xml configuration file is updatedfirst to ensure that the interceptor is configured when the API starts. The new APIis called catalogBrowser and is a cut down version of the catalog API, with onlythe operations to get the list of items and query individual items. This methodsimplifies the steps so the existing services and CICS programs can be reused.

The audit interceptor is used to write an SMF 123 subtype 1 record each time thecatalogBrowser API is called, but not for the catalog API.


Procedure1. Configure an audit interceptor by adding zosconnect_auditInterceptor and

zosconnect_zosConnectInterceptors elements to the shared configuration file/var/zosconnect/shared/config/haserver.xml. For example,<zosconnect_zosConnectInterceptors

id="auditInterceptorList"interceptorRef="auditInterceptor" />

<zosconnect_auditInterceptorid="auditInterceptor"/>

2. Update the zosconnect_zosConnectAPIs element in the shared configuration file/var/zosconnect/shared/config/haserver.xml to configure the auditinterceptor for the catalogBrowser API. For example,<zosconnect_zosConnectAPIs

location="${shared.resource.dir}/zosconnect/apis"updateTrigger="polled"><zosConnectAPI name="catalogBrowser"

interceptorsRef="auditInterceptorList" /></zosconnect_zosConnectAPIs>

3. Copy the catalogBrowser API package from <installation_path>/samples/scenarios/haWola/catalogBrowser.aar to the shared API location directory/var/zosconnect/shared/resources/zosconnect/apis. Enter the followingcommand on one line. Replace <installation_path> with the fully qualifiedinstallation path of z/OS Connect EE.

cp <installation_path>/samples/scenarios/haWola/catalogBrowser.aar/var/zosconnect/shared/resources/zosconnect/apis

4. Check the message log file for each server in /var/zosconnect/servers/<serverName>/logs/messages.log for the following messages:

CWWKG0016I: Starting server configuration update.CWWKG0028A: Processing included configuration resource: /var/zosconnect/shared/config/haserver.xmlBAQR7008W: z/OS Connect API catalogBrowser could not be installed.CWWKG0017I: The server configuration was successfully updated in 0.137 seconds.BAQR7000I: z/OS Connect API package catalogBrowser installed successfully.

The BAQR7008W warning message occurred because the API was not deployedto the API location, but was added to the server configuration file.The BAQR7000I information message indicates that the API was successfullyinstalled after it was deployed to the API location.

5. Send an HTTP GET request to call the catalog API and get item 10 from thecatalog.v If you are using a web browser, enter an HTTP GET request to the catalog

API:

http://companyhost.company.com:11111/catalogManager/items/10


curl -G http://companyhost.company.com:11111/catalogManager/items/10



6. The audit interceptor is not configured for the catalog API, so check that noSMF 123 subtype 1 records were written:


a. Obtain the SMF data. The method that you use depends on your SMFconfiguration. If unsure, contact your system programmer. Informationabout using the z/OS IFASMFDP program to dump the SMF data to a fileis described in Running the SMF data set dump program. You can alsoconfigure your JCL to select only the SMF 123 subtype 1 records.

b. Use ERBSCAN against the SMF data to check that no SMF 123 subtype 1records exist.

7. Send an HTTP GET request to call the catalogBrowser API and get item 10from the catalog.v If you are using a web browser, enter an HTTP GET request to

http://companyhost.company.com:11111/catalogBrowser/items/10


curl -G http://companyhost.company.com:11111/catalogBrowser/items/10



8. Send a second HTTP GET request to call the catalogBrowser API and get item10 from the catalog.v If you are using a web browser, open a private browsing window to establish

a new HTTP connection. In the second private window, issue an HTTP GETrequest to

http://companyhost.company.com:11111/catalogBrowser/items/10

v If you are using curl, the connection is not persistent, so enter the samecommand from step 7:

curl -G http://companyhost.company.com:11111/catalogBrowseer/items/10



9. The audit interceptor is configured for the catalogBrowser API, so check thatSMF 123 subtype 1 records were written and that calls were made to both z/OSConnect EE servers. Two HTTP GET requests were issued so look for two SMF123 subtype 1 records, one to each server.a. Obtain the SMF data a second time.b. Use ERBSCAN to check the dumped SMF file for the two SMF 123 subtype

1 records.c. To determine which z/OS Connect EE server each request went to, format

the server identification section of the SMF 123 subtype 1 records. Use thez/OS ICETOOL utility to view the SMF data. Sample JCL to run this utilitycan be found in <installation_path>/jcl/baqs123.jcl.

d. The JOBNAME in the formatted output indicates which z/OS Connect EEserver received the request.


http://www.ibm.com/support/knowledgecenter/SSLTBW_2.2.0/com.ibm.zos.v2r2.ieag200/rundump.htm

Adding a second httpEndpointYou can define an additional httpEndpoint to allow the RESTful administrationinterface to be used to target operation requests at a specific server.

About this task

Use these instructions to configure an additional httpEndpoint and then performoperations on APIs in one server by using the RESTful administration interface.

Note: For the purposes of this scenario, an HTTP only example is used to focus onthe specific HA configuration, rather than security. For information about usingSSL to restrict access to this additional httpEndpoint, see “Management of z/OSConnect EE APIs and services in an HA environment” on page 173.

z/OS Connect EE provides a RESTful administration interface, which can be usedto list installed APIs, details of those APIs and perform operations such as startingor stopping APIs. This interface uses the HTTP or HTTPS ports that are defined onan httpEndpoint element in the z/OS Connect EE server's configuration file. Formore information, see “Using the RESTful administration interface” on page 235.

In the highly available environment that is configured in this scenario, only asingle HTTP endpoint that is shared by the z/OS Connect EE servers is configured.Administration or operation requests cannot be targeted at a specific server unlessyou configure a second httpEndpoint element in each server's specificconfiguration file to specify an additional HTTP port value that is unique for eachserver.



Description Value

z/OS Connect EE server 1 operations port 19080

z/OS Connect EE server 2 operations port 29080

Procedure1. Update the server-specific configuration files to add the additional

httpEndpoint.a. Add the following entry to the first server's configuration file

/var/zosconnect/servers/haserver1/server.xml:<httpEndpoint id="operationsHttpEndpoint"

host="*"httpPort="19080"httpsPort="-1" />

b. Add the following entry to the second server's configuration file/var/zosconnect/servers/haserver2/server.xml:<httpEndpoint id="operationsHttpEndpoint"

host="*"httpPort="29080"httpsPort="-1" />

The RESTful administration interface is used to verify that the operationrequests complete successfully to a specific server.

In the following steps, the HTTP GET requests can be made in any browser. TheHTTP PUT request requires the use of a browser with a REST Client browserplug-in.2. From a web browser, enter an HTTP GET request to display details of the

catalog API in server haserver1.http://companyhost.company.com:19080/zosConnect/apis/catalog

If your request is successful, the HTTP response contains details of the catalogAPI in server haserver1, as follows:

{"name": "catalog","version": "1.0.0","description": "","status": "Started","apiUrl": "http://companyhost.company.com:19080/catalogManager","documentation": {

"swagger": "http://companyhost.company.com:19080/catalogManager/api-docs"}

}

Notice that the status value is “Started”.3. From a web browser, enter an HTTP GET request to display details of the

catalog API in server haserver2. Enter the following request:http://companyhost.company.com:29080/zosConnect/apis/catalog

If your request is successful, the HTTP response contains details of the catalogAPI in server haserver2. The output is the same as the output from step 1,except for the port value in the apiUrl and swagger values because both serversshare an API location directory with the same API installed.

4. From a web browser, enter an HTTP PUT request to stop the catalog API inserver haserver1. Enter the following request:http://companyhost.company.com:19080/zosConnect/apis?status=stopped

If your request is successful, the HTTP response contains the details of thecatalog API in haserver1 after the stop request is performed:

{"name": "catalog","version": "1.0.0","description": "","status": "Stopped","apiUrl": "http://companyhost.company.com:19080/catalogManager","documentation": {

"swagger": "http://companyhost.company.com:19080/catalogManager/api-docs"}

}

Notice that the status value is “Stopped”.5. Repeat step 2 to display details of the catalog API in server haserver2.

If your request is successful, the HTTP response contains details of the catalogAPI in server haserver2. The status is still “Started” because the API is onlystopped in server haserver1.

6. Flow two requests to get item 10 from the catalog.http://companyhost.company.com:11111/catalogManager/items/10

The instructions for how to flow two requests are described in the scenario,Configure an HA environment that uses the WOLA server provider, topic “Testingthe scenario” on page 96.The request to haserver2 where the API is running still works.The request to haserver1 where the API is stopped fails with the error message


BAQR7023E: The API is stopped.

7. From a web browser, enter an HTTP PUT request to start the catalog API inserver haserver1:http://companyhost.company.com:19080/zosConnect/apis?status=started

If your request is successful, the HTTP response contains the details of thecatalog API in haserver1 after the start request is performed, as follows:

{"name": "catalog","version": "1.0.0","description": "","status": "Started","apiUrl": "http://companyhost.company.com:19080/catalogManager","documentation": {"swagger": "http://companyhost.company.com:19080/catalogManager/api-docs"

}}

Notice that the status value is “Started”.8. Repeat step 6 to send two more requests to the catalog API.

This time both requests complete successfully because the API is started in bothservers.

Configure an HA environment that uses the IMS service providerUsing this scenario, you can configure a highly available z/OS Connect EEenvironment that uses the IMS service provider (also known as the IMS Mobilefeature) to connect to IMS.

This scenario uses two z/OS Connect EE servers with shared configurations anduses TCP/IP port sharing to distribute requests across the servers.

Note: For more information about the concepts of high availability and theoptions, you can choose see Chapter 7, “High availability,” on page 167.

In a sample configuration, the environment has the following characteristics:v Two z/OS Connect EE servers with workload that is distributed to them using

TCP/IP port sharing with WLM.v Two IMS regions.v Each z/OS Connect EE server is configured to use the IMS service provider.v Server configuration files and API packages are shared between the two z/OS

Connect EE servers to maintain a consistent configuration between servers.


Polling of the server configuration file is enabled. Polling allows the servers toautomatically pick up configuration changes as the scenario progresses, withoutthe need to restart the server or invoke the FileNotificationMbean. In production,it is more common to disable polling to avoid unnecessary CPU usage whenmonitoring a typically static file.

This scenario shows you how to configure a simple z/OS Connect EE HAenvironment for a single z/OS LPAR so they can share the service requestprocessing and the IMS service registry. The focus here is the HA configuration ofthe z/OS connect EE server. On the IMS side, a single IMS connection profile withone IMS host name, port, and data store can talk to multiple IMS Connectinstances and IMS systems, depending on the HA setup in your IMS environment,such as through the use of Sysplex Distributor.



Description Value

z/OS LPAR host name companyhost.company.com



z/OS Connect servers shared HTTP port 11111

PrerequisitesThese requirements are needed to run this scenario.

Before you create a high availability environment, you must first create thesupporting infrastructure. This includes a single z/OS Connect EE server that usesthe IMS service provider (also known as the IMS Mobile feature) to connect to IMSas shown in Figure 1. When this configuration is complete, you can then create thehigh availability environment.

z/OS Connect EE

IMS service

provider

z/OS Connect EE

IMS service

provider

IMSConnect

IMSConnect

IMS

Shared

files

IMS

Sysplex

distributor

Port

sharing

LPAR

Figure 25. A sample configuration of a highly available server environment that uses the IMS service provider


Prerequisite tasks

You must complete the following tasks to provide the infrastructure that is neededby the scenario.1. Create the initial server with the IMS service provider configured. Follow the

steps in “Configuring for the IMS service provider” on page 133 to set up aserver and the required IMS mobile service registry, including thepost-installation step that points you to the security configuration that isrequired on the server and on IMS.

2. Create a service by following the steps in “Tutorial: Create an IMS mobileservice” on page 54. After you complete the tutorial, a phonebook service iscreated, deployed, and tested.

3. Create an API for the phonebook service by following the steps in “Tutorial:Create a REST API for an IMS mobile service” on page 68. After you completethe tutorial, a REST API for accessing the phonebook service is created,deployed, and tested.

Setting up HA for the first serverModify an existing server to prepare it for a HA environment.

In this step, you modify the configuration of the existing z/OS Connect EE serverin preparation to add the second server. You must make the followingmodifications:v Create a shared TCP/IP port.v Split the server configuration file into content that can be shared between

servers and that which is server-specific.v Move the API and service artifacts to a shared location.

Setting up TCP/IP port sharingSet up port sharing so the z/OS Connect EE servers in the HA environment canlisten on the same port.

Procedure1. Choose an unreserved port number to be used for the servers' HTTP listeners.

This scenario uses port 11111 as an example, but it can be changed if it isalready in use in your environment. To display ports that are currently reservedon a single TCP/IP stack, use one of the following methods:

HTTP

z/OS Connect EE

IMS service

provider

IMSConnect

IMS

LPAR

Figure 26. Configuration of a single server to connect to IMS


v Enter the following SDSF command, where procname is the name of theTCP/IP stack:



netstat –o

2. Configure the shared ports in z/OS to use SHAREPORTWLM.a. In the TCP/IP profile for the z/OS LPAR, add or update an existing PORT

statement to add an entry for the HTTP port the server is listening on. Inthis scenario, port 11111 was chosen, with started task job names that startwith “ZCHA” and the SHAREPORTWLM option to allow WLM to managethe incoming workload. The shared port definition in the TCP/IP portprofile is as follows.PORT11111 TCP ZCHA* SHAREPORTWLM

b. Enable the shared port definitions. Enter the SDSF command

VARY TCPIP,<procname>,OBEYFILE,<datasetname>

For further instructions see the description of the VARY TCPIP,,OBEYFILEcommand in the z/OS Communications Server: IP System Administrator'sCommands documentation.

3. Confirm that the shared port is active. To display ports that are currentlyreserved on a single TCPIP stack, use one of the following methods.v Enter the following SDSF command, where procname is the name of the

TCP/IP stack:



netstat –o

The output includes the port number with a FLAGS value of DASW:

PORT# PROT USER FLAGS RANGE SAF NAME11111 TCP ZCHA* DASW

SW indicates that the port is shared and that the port uses WLM server-specificrecommendations.

4. Update the existing httpEndpoint element in server.xml to use the shared port.For example,<httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="11111" httpsPort="-1" />

Creating a shared configuration fileServers in an HA environment share common elements of the configuration file.

About this task

To ensure that both servers in the HA environment can handle the same workload,some elements from the server.xml file for each server are shared from a commonconfiguration file. Configuration elements that are unique to a server are defined ina separate server.xml file.


http://www.ibm.com/support/knowledgecenter/SSLTBW_2.2.0/com.ibm.zos.v2r2.halu101/varyp1b.htm#varyp1b

Procedure1. Ensure the server is stopped. For more information about starting and stopping

the server, see “Starting and stopping z/OS Connect EE” on page 189.2. Create directories under <WLP_USER_DIR> to store the shared configuration file.

For example, if the default directory is used, run the following command fromthe /var/zosconnect directory.

mkdir –p shared/config

3. Move the current server.xml file that is used by haserver1 to the sharedconfiguration directory and rename it to haserver.xml. For example, assumingthe default directory /var/zosconnect is used, run the following command:

mv <WLP_USER_DIR>/servers/<SERVER_NAME>/server.xml<WLP_USER_DIR>/zosconnect/shared/config/<HA_SERVER_NAME>.xml

For example: mv /var/zosconnect/servers/haserver1/server.xml/var/zosconnect/shared/config/haserver.xml

4. Open the haserver.xml file and locate the following <include> statements.<include location="/<WLP_USER_DIR>/servers/<SERVER_NAME>/resources/imsmobile-config/interactions/ims-interactions.xml" optional="true"/><include location="/<WLP_USER_DIR>/servers/<SERVER_NAME>/resources/imsmobile-config/connections/ims-connections.xml" optional="true"/><include location="/<WLP_USER_DIR>/servers/<SERVER_NAME>/resources/imsmobile-config/services/ims-services.xml" optional="true"/><include location="/<WLP_USER_DIR>/servers/<SERVER_NAME>/ims-admin-services.xml" optional="true"/>

Take one of the following actions:v Remove these <include> statements, unless you want to preserve specific

layout of the XML file.v If you want to preserve specific layout of the XML file, change the path to

the shared location:<include location="/<WLP_USER_DIR>/shared/resources/imsmobile-config/interactions/ims-interactions.xml" optional="true"/><include location="/<WLP_USER_DIR>/shared/resources/imsmobile-config/connections/ims-connections.xml" optional="true"/><include location="/<WLP_USER_DIR>/shared/resources/imsmobile-config/services/ims-services.xml" optional="true"/><include location="/<WLP_USER_DIR>/shared/config/ims-admin-services.xml" optional="true"/>

Save your changes.5. Create a file named server.xml for haserver1 in the /<WLP_USER_DIR>/servers/

haserver1 directory with the following elements:<?xml version="1.0" encoding="UTF-8"?><server description="z/OS Connect EE HA server1">

<include location="${shared.config.dir}/haserver.xml"/></server>

This configuration file includes the shared haserver.xml by using the Libertyproperty ${shared.config.dir} to reference the directory that contains the sharedconfiguration files. This property points to the directory WLP_USER_DIR/shared/config.

Setting up shared resourcesMove the API and service artifacts to a shared location so they can be accessed byboth servers.

About this task

To ensure that workload distribution can route requests to any of the z/OSConnect EE servers that are available in a port shared group, the servers musthave the same APIs and services available. For more information, see “Sharingserver configuration” on page 170.


Procedure1. Create directories under <WLP_USER_DIR> to store the API package. The default

for <WLP_USER_DIR> is /var/zosconnect.Run the following command from the /<WLP_USER_DIR>/shared directory:

mkdir –p resources/zosconnect/apis

2. Move your API .aar files to /<WLP_USER_DIR>/shared/resources/zosconnect/apis

Enter the following command on a single line, and replace <WLP_USER_DIR> withthe fully qualified path in your environment.

mv /<WLP_USER_DIR>/servers/haserver1/resources/zosconnect/apis/*.aar/<WLP_USER_DIR>/shared/resources/zosconnect/apis

For example, if <WLP_USER_DIR> is /var/zosconnect, the command would be asfollows:

mv /var/zosconnect/servers/haserver1/resources/zosconnect/apis/*.aar/var/zosconnect/shared/resources/zosconnect/apis

3. Add a zosconnect_zosConnectAPIs element in haserver.xml to configure theshared API location ${shared.resource.dir}/zosconnect/apis. For example,<zosconnect_zosConnectAPIs

location="${shared.resource.dir}/zosconnect/apis" />

4. Move the IMS service registry to /<WLP_USER_DIR>/shared/resourcesEnter the following commands on a single line, replacing <WLP_USER_DIR> withthe actual fully qualified path:

mv -iR /<WLP_USER_DIR>/servers/haserver1/resources/imsmobile-config/<WLP_USER_DIR>/shared/resources

For example, if <WLP_USER_DIR> is left as the default of /var/zosconnect, thecommand would look as follows:

mv -iR /var/zosconnect/servers/haserver1/resources/imsmobile-config/var/zosconnect/shared/resources

Results

The HA environment is now set up for the first server.

Adding a second serverAdd a second server to the HA environment.

Procedure1. Run the zosconnect create command to create the second server. The

configuration from the first server is copied across for the second server in alater step so no template is required now. Run the following command fromthe <installation_dir>/bin directory. For example, /usr/lpp/IBM/zosconnect/v2r0/bin.

zosconnect create haserver2

2. Replace the default Liberty server.xml file with the server.xml file fromhaserver1. Run the following command:


cp /var/zosconnect/servers/haserver1/server.xml/var/zosconnect/servers/haserver2


S BAQSTRT,JOBNAME=ZCHA2,parms='haserver2 --clean'

a. Check the server's message log file in <WLP_USER_DIR>/servers/{servername}/logs/messages.log. The following message appears:GMOIG7777I: The IMS Mobile feature initialized successfully.

v If the LOCALCOM service group is available, then the angel is runningand your Liberty Server ID has READ access to that SERVER profile.

4. Ensure that the second IMS region is started

Testing the scenarioTest the HA configuration and validate that it is distributing work across bothservers.

About this task

You can test this scenario from a web browser, a REST client, the Swagger UI inz/OS Connect EE API Editor, or the command line tool curl. curl is an opensource command line tool and library for transferring data with URL syntax. It issupported on many operating systems. For more information about curl, see thewebsite https://curl.haxx.se/.

For this step, you need a REST client and curl to avoid potential persistentconnection to the same server.

Procedure1. Log on to an IMS terminal for each IMS system and check the usage count of

the IVTNO transaction in each region by entering the following command.

/DISPLAY TRAN IVTNO

The QCNT field indicates how many times the program was run. Make a noteof the value to confirm in a later step that the count was incremented.

2. Send an HTTP POST request to call the API to add a phonebook entry from aREST client. For example, to add an entry for John Smith with the followinginformation:v Last name (the key): Smithv First name: Johnv Zip code: 55555v Extension: 555-5555

From a REST client, send an HTTP POST request to http://companyhost.company.com:11111/phoneBook/contacts/Smith?firstName=John&zipcode=55555&extension=555-55555

3. Send a second HTTP POST request to call the API by using curl. For example,to add an entry for Joe White with the following information:v Last name (the key): Whitev First name: Joe


https://curl.haxx.se/

v Zip code: 11111v Extension: 111-1111Enter the command:

curl http://companyhost.company.com:11111/phoneBook/contacts/White?firstName=Joe&zipcode=11111&extension=111-11111

4. Log on to an IMS terminal for each IMS system and check the usage count ofthe IVTNO transaction in each region.

/DISPLAY TRAN IVTNO

The QCNT field indicates how many times the program was run. Compare thisnumber with the earlier number.

Note: Depending on your Sysplex Distributor setup and how the workload isdistributed between the two servers, your test result might vary. If the systemis distributing work in a round-robin fashion, the two requests would go todifferent servers and to different IMS systems.

Results

Your HA environment is now set up. You can add more servers by repeating thesteps in “Adding a second server” on page 94


Chapter 5. Installation information

Refer to this section when you are ready to install z/OS Connect EnterpriseEdition.

z/OS Connect Enterprise Edition V2.0 (program number 5655-CEE) is available toorder using standard IBM ordering systems for z/OS products, such as IBM Shopz.z/OS Connect EE is shipped using CBPDO or other customized offerings, on 3590tape.

RequirementsYour system must meet these hardware and software requirements to install andrun z/OS Connect EE.

Support requirements

Minimum required service levels are listed where appropriate. If a specific level isnot listed, support is provided for the General Availability (GA) release of theproduct. Service levels later than those listed are also supported, if the productprovides upward compatibility between service releases.

Hardware requirements

z/OS Connect EE runs on any hardware that supports the chosen operatingsystem.

Software requirements

z/OS Connect EE requires IBM z/OS V1.13 or V2.1 or later, and one of thefollowing SDKs:1. IBM 64-bit SDK for z/OS, Java Technology Edition V7.1.02. IBM 64-bit SDK for z/OS, Java Technology Edition V8.0.0

z/OS Connect EE API Editor, the Eclipse-based workstation tool for creating APIs,requires one of the following products:1. IBM Explorer for z/OS Aqua V3.02. IBM CICS Explorer V5.33. IBM IMS Explorer for Development V3.2.1 or later

For the most up-to-date information of the specified operating environments forz/OS Connect EE, go to the IBM Software Product Compatibility reports, athttp://www.ibm.com/software/reports/compatibility/clarity/index.jsp

Service requirements

If you use z/OS Connect EE V2.0.3.0 or V2.0.4.0 with IMS Mobile Feature Pack,you must apply the PTF for IMS APAR PI67597. The IMS mobile feature isintegrated in z/OS Connect EE starting V2.0.5.0 (APAR PI70432).

If you use z/OS Connect EE V2.0.3.0 or higher embedded in CICS TS V5, youmust apply the PTFs for one of the following CICS APARs.


https://www.ibm.com/software/shopzseries/ShopzSeries_public.wss

http://www.ibm.com/software/reports/compatibility/clarity/index.jsp

v For CICS TS V5.2, apply the PTFs for APAR PI64748.v For CICS TS V5.3, apply the PTFs for APAR PI64749.

Installing z/OS Connect EEYou must first install z/OS Connect EE, and then you perform the post installationtasks.

About this task

The SMP/E installation process puts the product code onto your system.

Procedure1. Follow the instructions in the Program Directory to install z/OS Connect EE

using SMP/E.

Note:

v By default, the product code is installed in /usr/lpp/IBM/zosconnect/v2r0/bin.

v You can set the WLP_USER_DIR environment variable to the location whereyou want your server instances to be stored. If you do not setWLP_USER_DIR, the default value /var/zosconnect is used.If you change the WLP_USER_DIR environment variable to a differentlocation, new servers are stored in the new location. The servers in the oldlocation still exist, but can be used only when you change WLP_USER_DIRback to that location again.

v If you are planning to set up an HA environment, you need to customizeWLP_USER_DIR, so consider this requirement when you plan yourinstallation.

2. Apply the latest maintenance to update the product.

Results

z/OS Connect EE is installed.

What to do next

Perform the post installation steps in “Creating the z/OS Connect EE shareddirectory” and “Setting up the product extensions directory” on page 113 beforeyou attempt to start a server.

Creating the z/OS Connect EE shared directoryUse this information to create the directories that are required by the z/OSConnect EE servers.

About this task

The shared directory is used as a dedicated file system by all z/OS Connect EEserver instances on the same LPAR. z/OS Connect EE uses /var/zosconnect as theshared directory of every release-specific product extension.

You must complete the following steps before you create and start your first z/OSConnect EE server instance:


https://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss?CTY=US&FNC=SRX&PBL=GI13-3384

Procedure1. Create the zosconnect mount point in the z/OS UNIX file system:

/var/zosconnect.2. Set up file system security to enable z/OS Connect EE server instances to

access the /var/zosconnect shared directory.a. Change the owner of the directories in /var/zosconnect to the user ID that

is administering z/OS Connect EE.b. Change the group ownership of the directories in /var/zosconnect to a

group that all the z/OS Connect EE server user IDs belong to.c. Give the owner of the directories read, write, and execute permissions, and

give the group read, write, and execute permissions. For example,rwxrwx---.

3. Optional: Use UNIX System Services access control list (ACL) entries to addgroup or owner permissions for multiple administrators or groups. When theACL is complete, activate the FSSEC resource class and use the setfaclcommand.

Setting up the product extensions directoryThe final step in the installation of z/OS Connect EE, is to run the zconsetup scriptto create the product extensions directory.

Before you begin

To use the zconsetup script, you must be a z/OS Connect EE administrator withsufficient authority.

About this task

A product extension is a structured directory on disk that stores Liberty features.Each product extension must be configured by a properties file and stored underthe product extensions directory so that the extension can be detected by serverruntimes. For more information, see Liberty product extension

The zconsetup utility must be used once per LPAR because /var is not a sharedfile system. You cannot configure the specific path for the z/OS Connect EEproduct extensions. However, you can share your z/OS Connect EE configurationacross LPARs by mounting a shared zFS as /var/zosconnect on each LPAR.

Procedure1. Go to the <installation_path>/bin directory.2. Issue the following command to run the zconsetup script:

zconsetup install

Results

The script makes the following changes to the system:v Creates the release-specific product extensions directory in the /var/zosconnect

directory, for example,

/var/zosconnect/v2r0/extensions

v Creates a symbolic link of the extensions directory in the product z/OS UNIXinstallation path. For example,

Chapter 5. Installing 113

http://www.ibm.com/support/knowledgecenter/en/SSEQTP_liberty/com.ibm.websphere.wlp.nd.multiplatform.doc/ae/cwlp_prod_ext.html

/usr/lpp/IBM/zosconnect/v2r0/wlp/etc/extensions

Note: This needs to be done only once if /usr/lpp is shared in a sysplexconfiguration.

v Installs the z/OS Connect EE product extension properties file in the productextensions directory.

The following table shows the directory structure and contents of a typicalinstallation:

Table 19. Directory paths and contents

Path Contents

/usr/lpp/IBM/zosconnect/v2r0/bin Product code

/usr/lpp/IBM/zosconnect/v2r0/runtime/lib/

zosconnect feature files

/usr/lpp/IBM/zosconnect/v2r0/wlp/etc/extensions

Symlink to /var/zosconnect/v2r0/extensions

/var/zosconnect/v2r0/extensions Product extension properties files containingthe absolute path to the service provider.

Installing the z/OS Connect EE Build ToolkitInstall the z/OS Connect EE Build Toolkit to create Service archive (SAR) files.

About this task

Two methods are provided, a command line interface (CLI) and a SoftwareDevelopment Kit (SDK). For more information, read the Javadoc included in thezconbt.zip file or the Build Toolkit SPI in the Reference section. You can also findexamples in GitHub.

Note: This task shows you how to install and use the build toolkit on a PCrunning Microsoft Windows. You can also run the build toolkit on z/OS, but youstill need to unpack the files on your PC first. See the readme.txt file for moreinformation.

Procedure1. On your local Windows machine, extract the zconbt.zip file onto the local file

system.2. If you plan to use the SDK, ensure that the following .jar files from the lib

directory are on the class path.v com.ibm.zosconnect.buildtoolkit.jar

v com.ibm.ws.zos.connect.sar.jar

v jackson-annotations-2.4.2.jar

v jackson-core-2.4.2.jar

v jackson-databind-2.4.2.jar

v jackson-dataformat-yaml-2.4.2.jar

3. Ensure that the plugin.properties file is in the same directory as thecom.ibm.zosconnect.buildtoolkit.jar file.


Updating z/OS Connect EEYou should update to the latest level of z/OS Connect EE, by applying the latestmaintenance.

Before you apply maintenance, shut down all instances of z/OS Connect EE.

Note: All files in the <WLP_USER_DIR>/servers directory are preserved when youapply maintenance.

Maintenance considerations for z/OS Connect EE embedded inCICS

Because z/OS Connect EE can run stand-alone or within Liberty that is embeddedin CICS, the two environments must be described uniquely. You can run bothenvironments concurrently, but they are not mutually exclusive, so care is neededwhen you apply maintenance to the WebSphere Liberty Profile (WLP) clientlibraries that contain the BBOA* modules.

For more information, see Keeping CICS TS 5.3 and z/OS Connect EE 2.0maintenance in sync.

Installing z/OS Explorer and the z/OS Connect EE API EditorTo design and create APIs you need to use the z/OS Connect EE API Editor whichis provided as a plug-in for IBM Explorer for z/OS Aqua 3.0.

Before you begin

If you already have IBM Explorer for z/OS Aqua 3.0 installed, you should stillfollow this procedure, but in step 4, select only the z/OS Connect EE API Editorplug-in.

About this task

In this task, you download and install IBM Explorer for z/OS Aqua. You can theninstall the z/OS Connect EE API Editor plug-in to define and deploy an API.

Procedure1. In your browser, go to the mainframe development tools downloads page at

https://developer.ibm.com/mainframe/downloads/You can choose either IBM Installation Manager (IBM IM) or Eclipse p2. In thisexample, we will use IM.2. Follow the IBM IM path and the instructions on the page to choose your

installation option and add the repository URL to your Installation Manager.

Important: Follow the path for Aqua 3.0 (Eclipse 4.4 Luna) on the downloadsite.


https://developer.ibm.com/answers/questions/337637/how-to-keep-cics-ts-53-and-zosconnect-v2r0-mainten.html#answer-337664

https://developer.ibm.com/answers/questions/337637/how-to-keep-cics-ts-53-and-zosconnect-v2r0-mainten.html#answer-337664

https://developer.ibm.com/mainframe/downloads/

3. On the main IM screen, click Install.4. On the Install Packages dialog, select IBM Explorer for z/OS, if not already

installed, and IBM z/OS Connect EE API Editor. Click Next.5. Follow the on screen instructions to download and install the selected

packages.6. When the installation has completed, close Installation Manager.

Updating z/OS Explorer and the z/OS Connect EE API EditorBe aware of these considerations when planning to update z/OS Explorer and thez/OS Connect EE API Editor.

Updating z/OS ExplorerIf you want to update z/OS Explorer, you should do so before starting thez/OS Connect EE V2 update.

Installing the new API Editor into EclipseYou can install the new API Editor into Eclipse while projects are still inflight. However, you should export your projects before beginning theupdate.

Migrating from z/OS Connect V1Follow these steps to migrate your API deployments to z/OS Connect EnterpriseEdition V2.0.

To migrate an existing configuration based on z/OS Connect V1 to z/OS ConnectEnterprise Edition V2.0, you must make the following updates to your server.xmlfile:1. In the Feature Manager section, replace <feature>zosconnect-1.0</feature> or

<feature>zosconnect-1.2</feature> with:<feature>zosconnect:zosconnect-2.0</feature>

2. Prefix all z/OS Connect configuration elements for services, interceptors,DataXForm and the z/OS Connect manager with zosconnect_. For example:<zosConnectService id='example' name='example' serviceRef='exampleService'/>


becomes<zosconnect_zosConnectService id='example' name='example' serviceRef='exampleService'/>


Chapter 6. Configuring

Use this section to configure the different elements of z/OS Connect EE.

Note: All configuration settings for the server are contained in the server.xml file.To change the configuration, you need authority to edit this file.

Creating a z/OS Connect Enterprise Edition ServerUse the zosconnect command to create a z/OS Connect EE server.

Before you begin

To use the zosconnect command, you must be a z/OS Connect EE administratorwith access to the OMVS shell.

Before you create a z/OS Connect EE server, ensure that the shared directory isavailable. For more information, see “Creating the z/OS Connect EE shareddirectory” on page 112.

About this task

This task shows you how to use the default template to create a z/OS Connect EEserver. Templates are a Liberty feature that you can use when you create a server.Other service providers can supply their own templates to enable a quicker startwith their functions. For more information, see Creating Liberty servers fromcustom configurations in the WebSphere Application Server Liberty documentation.

Note: The file permissions on the server are controlled by the umask of the userthat created the server.

Procedure1. Set the WLP_USER_DIR environment variable to the location where you want

your server instances and user features to be stored. For example,/var/zosconnect.You can specify WLP_USER_DIR environment variable in the shellenvironment. This variable must be an absolute path.

2. Run the zosconnect command with the create option. Use the followingsyntax:zosconnect create <server name> --template=<template name>

For example, to create a server by using the default z/OS Connect EE template,type the command:zosconnect create myserver --template=zosconnect:default

Note:

v Add the same WLP_USER_DIR environment variable to the started taskprocedure://STDENV *

WLP_USER_DIR=/any/user/directory


http://www.ibm.com/support/knowledgecenter/SSAW57_liberty/com.ibm.websphere.wlp.nd.doc/ae/twlp_server_customconfig.html

http://www.ibm.com/support/knowledgecenter/SSAW57_liberty/com.ibm.websphere.wlp.nd.doc/ae/twlp_server_customconfig.html

For more information about the started task procedure, see “Starting andstopping z/OS Connect EE” on page 189.

v You can specify JVM options to be used on startup by placing the file<name>.options in the <WLP_USER_DIR>/servers directory and adding thefollowing to the started task procedure://STDENV DD PATH’<WLP_USER_DIR>/servers/<name>.options’

where <name>.options is the name of the file in the <WLP_USER_DIR>/serversdirectory. For more information about JVM options, see Customizing theLiberty environment in the WebSphere Application Server Libertydocumentation.

Results

A z/OS Connect EE server is created in the <WLP_USER_DIR>/servers directory witha server.xml configuration file that defines the z/OS Connect EE feature and thedefault location of the API packages. The shared resources and the serverdefinitions are also located in this directory when servers are running.

The following table shows the directory structure and contents when a server iscreated:

Table 20. Directory paths and contents

Path Contents

<WLP_USER_DIR>/servers Server instances. One subdirectory perserver instance, each created by using thecreate option of the zosconnect command.

<WLP_USER_DIR>/extension The location where user features areinstalled.

The configuration is shown in Figure 1.

Figure 27. Configuration used in this example.


https://www.ibm.com/support/knowledgecenter/SSEQTP_liberty/com.ibm.websphere.wlp.zseries.doc/ae/twlp_admin_customvars.html

https://www.ibm.com/support/knowledgecenter/SSEQTP_liberty/com.ibm.websphere.wlp.zseries.doc/ae/twlp_admin_customvars.html

Configuring servicesz/OS Connect EE service definitions provide the mechanism for reaching z/OSapplication assets using REST calls. To enable a service, you must add a servicedefinition to the Liberty server.xml configuration file. Services require thezosConnect-2.0 feature to be configured in server.xml.

About this task

z/OS Connect EE services are defined by the zosConnectService configurationelement. This element contains attribute definitions that might have globallydefined counterparts. Attributes can be defined globally through thezosConnectManager element. These attributes, if defined, apply to all services. Ifboth global and service level attributes are configured, the values defined at thezosConnectService level are used.

A service provider is supplied with z/OS Connect EE that enables HTTP requeststo interact with z/OS assets through WebSphere® Optimized Local Adapters(WOLA). For more information, see “Using the WOLA service provider” on page122.

z/OS Connect EE also provides a service implementation that allows HTTPrequests to contact remote REST endpoints. For more information, see“Configuring the z/OS Connect EE REST client service” on page 145.

Note: If your service is called as part of an API call, then the interceptors andsecurity configuration included with the API will override the configurationincluded in the service.

Procedure1. Add a zosConnectService configuration element for each service in your

server.xml configuration.You must configure the serviceRef and serviceName attributes, other attributesare optional. The serviceRef element points to the service providerconfiguration element. The serviceName attribute identifies the service to z/OSConnect EE and is also used as part of the URL for z/OS Connect EE requeststhat are targeted to a specific service. The service name must be unique.The following excerpt from a server.xml file shows a sample definition for az/OS Connect EE service called recordOpsCreate:<zosconnect_zosConnectService id="zcs1"serviceName="recordOpsCreate"serviceRef="{id of service provider}"/>

For more information on each attribute, see “Configuration elements” on page283 in the Reference section.

2. Optional: Add the zosConnectManager configuration element to the server.xmlfile.This element is a singleton in the server.xml configuration and it containsglobal values that apply to all z/OS Connect EE services that are defined forthe server. The element can contain the names of z/OS Connect EE interceptorsor data transformation provider configuration elements that apply to allservices in the server.The following example describes a zosConnectManager configuration elementthat defines an operations group name of Operator1 under the item

Chapter 6. Configuring 121

globalOperationsGroup. This is the name of the security (SAF or LDAP) groupthat the requesting client user ID needs to be in before z/OS Connect EEoperations requests are permitted, such as action=start|stop|status. Thisgroup applies to all services in the z/OS Connect EE configurations. The itemglobalDataxformRef defines the element name where z/OS Connect EE willfind a data transformation provider. Supplying the globalDataxformRef in thezosConnectManager element means this is the transformation providerimplementation for all services in the configuration that do not already havetheir own data transformation element reference. The itemglobalInterceptorsRef is the name of the element in the configuration thatdescribes the set of z/OS Connect EE interceptors that apply to all services inthe configuration.<zosconnect_zosConnectManagerglobalOperationsGroup="Operator1"globalDataxformRef="XformJSON2Byte"globalInterceptorsRef="GlobalInterceptors"/>

For more information on each attribute, see “Configuration elements” on page283 in the Reference section.

Using the WOLA service providerFollow these steps to use the WOLA service provider supplied with z/OS ConnectEE.

Before you begin

The WebSphere Optimized Local Adapter (WOLA) service provider requires thatboth the zosconnect:zosconnect-2.0 and the zosLocalAdapters-1.0 features areconfigured. The WOLA service provider is included with z/OS Connect EE anduses the WOLA function provided with the Liberty profile. The WOLA serviceprovider can be used by both CICS and Batch.

About this task

z/OS Connect EE provides a service implementation that allows z/OS Connect EErequests to interact with z/OS assets through WOLA. The service is automaticallyenabled when both zosconnect:zosconnect-2.0 and the zosLocalAdapters-1.0features are configured. Instances of this service can be defined through thezosconnect_localAdaptersConnectService configuration element.

Procedure

For a service to use the WOLA service provider, the service definition requires azosconnect_localAdaptersConnectService configuration element in the server.xmlfile. The minimum configuration consists of the target WOLA Connection Factoryname, Register name (RGN), and Service name. Configuration of z/OS Connect EEfollows the Liberty profile conventions by only requiring the minimum parametersto be specified.For more information about all the supported attributes, see“zosconnect_localAdaptersConnectService” on page 302 in the Reference section.The only supported authentication mechanism on a WOLA connection factory iscontainer managed authentication. The authentication credentials are defined usingan authData element that is referenced on the containerAuthDataRef attribute ofthe connectionFactory element.WOLA uses a three part name to uniquely identify the WOLA server. This name is


derived from the wolaGroup, wolaName2 and wolaName3 attribute values on the localadapter's configuration element zosLocalAdapters, and must be unique per serverin the same z/OS LPAR.The following code snippet is an example of configuring the WOLA serviceprovider:<zosconnect_zosConnectService id="zcs1"serviceName="recordOpsCreate"serviceRef="wolaOpsCreate"/>

<authData id="cauth1" user="user1" password="{xor}LDo8Ki02KyY="/><connectionFactory id="wolaCF" jndiName="eis/ola"containerAuthDataRef="cauth1" ><properties.ola/></connectionFactory>

<zosLocalAdapters wolaGroup="LIBERTY" wolaName2="LIBERTY"wolaName3="LIBERTY" />

<zosconnect_localAdaptersConnectService id="wolaOpsCreate"registerName="BATCH01"serviceName="COBLPGM1"connectionFactoryRef="wolaCF"/>

The z/OS Connect EE service implementation that allows z/OS Connect EErequests to interact with z/OS assets through WOLA might require a datatransformer. If a data transformer is configured, globally or at the service level,input and output payloads are converted using the configured data transformer. Ifa data transformer is not configured, and the request contains a JSON payload, theservice assumes that the backend program will handle the data conversion. Theservice converts the JSON payload to a byte array using the encoding specified inthe request header or the default JSON encoding of UTF-8. Similarly, if the assetreturns a payload and no data transformer is configured, the WOLA serviceimplementation expects to receive a JSON payload in byte array form, which isconverted to a JSON response payload following the same encoding rules used fortransforming a JSON request payload to a byte array.The WOLA service provider implementation allows for a number of other WOLAconnection factory attributes to be specified in itszosconnect_localAdaptersConnectService configuration element.You can specify the way for a WOLA CICS Link Server to propagate data to targetCICS application programs by using the useCICSContainer attribute in thelocalAdaptersConnectService element. When the useCICSContainer attribute is setto false, the payload is passed to the target CICS application program by using aCOMMAREA; otherwise, the payload is passed to the target CICS applicationprogram by using CICS containers.The following options are supported to flow payloads to CICS applicationprograms:v Use a COMMAREA.v Use a channel name of IBM-WAS-ADAPTER to flow a single payload container.v Use a channel name of your choice to flow a single payload container with the

HTTP context containers. The context containers pass information about theHTTP request to the CICS application program. See Table 1 for moreinformation.

Table 21. HTTP context container names and descriptions

Name Description

ZCONReqURL Contains the URL of the HTTP request. Forexample, if an invokeURI definition of/banking/deposit and a query parametercountry=USA are used, the URL ishttps//localhost: port/banking/deposit?country=USA.

ZCONReqQParms Contains the query parameters of the HTTPrequest. For example, if a request URL ishttps//localhost:port//banking/deposit?country=USA, the query parameter iscountry=USA.

ZCONReqMethod Contains the method of the HTTP request,for example, GET.

ZCONHTTPHeaders Contains a JSON-formatted set of HTTPheader name and value pairs that isconfigured by using thelinkTaskChanCtxContHttpHeaders attributeunder thezosconnect_localAdaptersConnectServiceelement.

Configuring CICS to use WebSphere optimized local adapters(WOLA)

z/OS Connect Enterprise Edition includes a WOLA service provider, which usesWOLA to communicate with CICS programs.

About this task

WOLA is provided as part of the Liberty profile that is included in the z/OSConnect Enterprise Edition installation. To configure CICS to use WOLA, copy theWOLA modules from the z/OS Connect Enterprise Edition installation directory toa load library that is referenced in the DFHRPL DD concatenation of the CICSregion startup JCL. Next, define WOLA CSD definitions to your CICS region and aSAF profile to control which external user IDs can use WOLA to register to thez/OS Connect EE server.

Note: The Liberty feature that is included in both CICS TS and z/OS Connect EE,includes the BBOA* WOLA modules, but the versions of these modules arepotentially different. Always upload the modules that are included with z/OSConnect EE as these modules are tested to ensure compatibility.

Procedure1. Allocate a PDSE, for example called LIBERTY.WOLA.LOAD, with the following

values:


2. Open a Telnet or ssh session to your z/OS system UNIX System Services:a. Change to the z/OS Connect Enterprise Edition <installation_path>/wlp/

clients/zos directory that contains the WOLA modules. For example,/usr/lpp/IBM/zosconnect/v2r0/wlp/clients/zos.

b. Enter the following command to copy the modules from the UNIX SystemServices file system to the PDSE you allocated in previous step:

cp -Xv ./* "//'data.set'"

Where "//'data.set'" is the location of the target PDSE. For example,

cp -Xv ./* "//'LIBERTY.WOLA.LOAD'"

c. Check the contents of the PDSE to ensure that all the modules were copiedsuccessfully.

3. Edit your CICS region JCL start procedure to add the PDSE containing theWOLA modules. For example, add LIBERTY.WOLA.LOAD, to the DFHRPL DDconcatenation.

4. Define the WOLA resources, transactions, and TD queue to the CICS regionDFHCSD. The CSD definition that is required for the Liberty profile WOLAmodules is provided on a GitHub website.a. In a web browser, open the URL https://github.com/WASdev/sample.wola

and click the file CSDUPDAT.jclsamp to open the file. Click the Raw toremove the line numbers.

b. Copy the contents of the file CSDUPDAT.jclsamp into a new file calledCSDUPDAT on your workstation.

c. Upload file CSDUPDAT in ASCII to a PDS (record format FB, record length 80)on your z/OS system.

d. Customize the CSDUPDAT JCL member STEPLIB and DFHCSD DD cards foryour CICS installation.

e. Review and modify the ADD statement at the end of the file to conformwith your CICS installation standards for GROUPs and LISTs.

f. Run the job and check that it completes with RC=0.g. If you want the CSD GROUP(BBOACSD) to be installed when CICS starts,

add its LIST to the CICS region startup JCL GRPLIST SIT parameter.


https://github.com/WASdev/sample.wola

5. Set up the Liberty message catalog in the CICS regionThe optimized local adapter programs issue messages from a message catalogthat is provided with Liberty. For the programs to issue messages, theNLSPATH environment variable in the CICS region must point to the directorythat contains the message catalog. This directory is wlp/lib/native/zos/s390x/nls/%N.cat, where wlp is the directory in which the Liberty server is installed.To set the environment variable, use the Language Environment® ENVAR option,which you can set by editing the CEEROPT CSECT that the CICS region uses.After you edit the CSECT, you can build, compile, link, and copy the CSECTinto the DFHRPL data set. For more information about other ways to setLanguage Environment options, see the documentation for your version ofCICS.

Note: Methods for setting Language Environment options that involve editingthe application source code or relinking the application are not supportedbecause the optimized local adapter programs cannot be recompiled orrelinked.The following example shows a CEEROPT CSECT that defines the NLSPATHenvironment variable for a Liberty server that is installed in /u/MSTONE1/wlp.The definition spans two lines and includes a continuation character, X, incolumn 72.

CEEROPT CSECTCEEROPT AMODE ANYCEEROPT RMODE ANY******************************************************************* Utility: CEEROPT* Purpose: Set default LE runtime options for CICS region.******************************************************************

CEEXOPT ENVAR=((’NLSPATH=/u/MSTONE1/wlp/lib/native/zos/s390x/nlXs/%N.cat’),OVR)

END

6. Define the SAF CBIND profile to allow remote clients (for example, CICS) toregister with WOLA. In these examples, RACF commands are used.a. Enter the command:

RDEF CBIND BBG.WOLA.group.name2.name3 UACC(NONE)

Where group, name2, and name3 match the values that are specified on thezosLocalAdapters element in the server.xml configuration file to create thethree-part name for WOLA. For example,

RDEF CBIND BBG.WOLA.LIBERTY1.LIBERTY2.LIBERTY3 UACC(NONE)

Note:

v You can use a wildcard in the profile to make it more generic. Forexample, the CBIND profile BBG.WOLA.* would apply to any three-partname you use in Liberty.

v CBIND profiles are stored in uppercase. Specify uppercase values in yourserver.xml zosLocalAdapters element because lowercase characters inyour three-part name cause a mismatch when the CBIND authority ischecked.

b. Grant the CICS region user ID (for example, cics_id) READ access to theCBIND profile


PERMIT BBG.WOLA.group.name2.name3 CLASS(CBIND) ACCESS(READ) ID(cics_id)

For example,

PERMIT BBG.WOLA.LIBERTY1.LIBERTY2.LIBERTY3 CLASS(CBIND) ACCESS(READ) ID(CICSID)SETROPTS RACLIST(CBIND) REFRESH

7. Start the CICS region to ensure that the WOLA definitions are installedsuccessfully.a. Ensure that CSD GROUP(BBOACSD) defined in step 4 is installed (install

manually now if it is not included in a List in the GRPLIST SIT parameter).b. Confirm that the WOLA support was added, by checking the MSGUSR job

log output for the following messages:

Resource definition for BBOACLNK has been added.Resource definition for BBOACNTL has been added.Resource definition for BBOACSRV has been added.Resource definition for BBOATRUE has been added.TRANSACTION definition entry for BBO$ has been added.TRANSACTION definition entry for BBO# has been added.TRANSACTION definition entry for BBOC has been added.

8. Stop the CICS regionYou will need to restart CICS after the z/OS Connect EE server is configuredand started.

What to do next

More advanced configuration options are also available, such as:v Enabling the WOLA Task Related User Exit (TRUE) to start during CICS region

startup.v Configuring the Link Server Task to start by using either INITPARM or a

sequential terminal.

These options are similar to the actions required when WOLA is used inWebSphere Application Server for z/OS. For more information, see the FullFunction WebSphere Application Server z/OS WOLA Quick Start Guide also availablefrom Techdoc WP101490.

Registering CICS with the WebSphere optimized local adapter(WOLA)

To use the z/OS Connect Enterprise Edition WOLA service provider to connect toCICS, you must first configure both your z/OS Connect EE server and your CICSregion. You must then use a CICS transaction to register the CICS region as a clientof the WOLA running in the z/OS Connect EE server.

Before you begin

The following tasks must be completed:1. Configure the SAF definitions required to permit your z/OS Connect EE server

the authority to access the z/OS authorized services required by WOLA.Instructions for RACF are documented in “Configuring the Liberty angelprocess and z/OS authorized services” on page 185.

2. Configure your z/OS Connect EE server to use the WOLA service provider.Follow the instructions in “Using the WOLA service provider” on page 122.



3. Configure your CICS region to use WOLA. Follow the instructions in“Configuring CICS to use WebSphere optimized local adapters (WOLA)” onpage 124.

About this task

In this task, you run a CICS transaction to start the WOLA Task Related User Exit(TRUE) and the Link Server task. This registers the CICS region as a client of theWOLA running in the z/OS Connect EE server.

Procedure1. Ensure that the angel process is running. If it is not running, start it by issuing

the following command on the z/OS operator console:

S BBGZANGL

Note: The angel process must be running before a z/OS Connect EE Serverthat is configured to use WOLA is started, because the server connects to theangel process to access the z/OS authorized services.

2. Start the z/OS Connect EE server. Check the server's message log file in<WLP_USER_DIR>/servers/<serverName>/logs/messages.log. The followingmessages indicate that the server was started successfully:

CWWKB0103I: Authorized service group LOCALCOM is available.CWWKB0103I: Authorized service group WOLA is available....CWWKB0501I: The WebSphere Optimized Local Adapter channel registered with the Liberty profile server using the following name: <GROUP> <NAME2> <NAME3>J2CA7001I: Resource adapter ola installed in 0.327 seconds.

. where:v <GROUP>, <NAME2>, and <NAME3> must match the wolaGroup, wolaName2

and wolaName3 attribute values specified on the zosLocalAdapters element inserver.xml.

v The availability of the LOCALCOM service group is a key indicator that theangel process is running and your Liberty Server ID has READ access to thatserver profile.

v The availability of the WOLA service group is another key indicator that theconfiguration was completed successfully.

v Message CWWKB0501I shows the successful use of the WOLA three-partname values you provided in the server.xml file. This message indicates thatan external address space might register into the Liberty Profile server, inthis instance the z/OS Connect EE server, by using this three-part name onthe BBOA1REG API.


3. Ensure that the CICS region is started.4. Start the WOLA TRUE and Link Server task from CICS, and register with

WOLA.a. Enter the following command on the command line of the CICS region:

BBOC START_TRUE

The following message indicates success:


WOLA TRACE 1: Exit enabled successfully.

b. Enter the following command to start the link server task and register toyour server:

BBOC START_SRVR RGN=<registerName> DGN=<GROUP> NDN=<NAME2>SVN=<NAME3> SVC=*SEC=N REU=Y


Messages are also written to the CICS region job log BBOOUT.If you get a non zero return code and reason code, then go to the topicOptimized local adapters for z/OS APIs in the WebSphere Application Serverz/OS documentation. Search on the string cdat_olaapis. Open the link andgo to the Register section, also known as the BBOA1REG section and look forthe RC and RSN codes.

Results

You can now send requests from the z/OS Connect EE server via WOLA to CICS.

What to do next

To unregister the CICS region from WOLA and stop the Link Server task, open aterminal session with the CICS region and issue the following command:

BBOC STOP_SRVR RGN=<registerName>

where:v <registerName> must match the registerName attribute value specified on the

localAdaptersConnectService element in server.xml.

The following message indicates that the server was stopped:

WOLA TRACE 0: Stop server completed successfully.

To stop the WOLA TRUE, issue the following command:

BBOC STOP_TRUE

The following message indicates that the exit was stopped:

WOLA TRACE 0: Exit disabled Successfully

Using the IMS service providerYou can create a service to enable RESTful access to IMS transactions through theIMS service provider.


https://www-01.ibm.com/support/knowledgecenter/SS7K4U_8.0.0/com.ibm.websphere.nd.multiplatform.doc/info/ae/ae/cdat_olaapis.html

The solution involves the use of the IMS Mobile feature (imsmobile-2.0), whichserves as the IMS service provider. The IMS Mobile feature was previouslyincluded in the IMS Enterprise Suite as the IMS Mobile Feature Pack for z/OSConnect EE.

Important: V2.0.5.0 (APAR PI70432) or later is required for the embedded IMSservice provider.

Configuration scenarios

Identify your scenario and follow the corresponding steps.

Table 22. Configuration scenarios

Scenario Steps

You are setting up the server touse the IMS service provider thefirst time.

1. Check the “Operational requirements.”

2. Review the “IMS service security process flow.”Determine if basic or SAF registry must be configuredon the server for the initial setup. Identify if RACF isturned on in IMS Connect and if an IMS technical ID,technical group, and technical password need to beconfigured.

3. Follow the steps in “Configuring for the IMS serviceprovider” on page 133.

You are upgrading from IMSMobile Feature Pack for z/OSConnect EE in IMS EnterpriseSuite

Follow the steps in “Upgrading from the IMS MobileFeature Pack in IMS Enterprise Suite” on page 136.

Operational requirementsExamine the operational requirements to assist the planning and setup of your IMSmobile solution.v IMS Connect is required. The IMS service provider provides access to IMS

transactions through the IMS Transaction Manager with IMS Connect being theTCP/IP gateway. The transactions can then access IMS DB, DB2, and otherexternal subsystems. See “IMS service security process flow” for moreinformation about user authentication and authorization from z/OS Connect EEto IMS.

v IMS Explorer for Development V3.2.1.4 or later is required for creating,publishing, and testing the services. Subsequent updates of IMS Mobile featuremight require a newer version of IMS Explorer.

v The z/OS Connect EE API Editor is required for creating APIs for IMS services.

IMS service security process flowFor a secure setup, the z/OS Connect EE server must be configured with SAF orLDAP registry authentication. For SAF, the server must be configured with the SAFAuthorization element. An access control list (ACL) must be configured to protectIMS mobile service registry.

The following diagram describes the user authentication and authorization process.


1. The client, such as IMS Explorer for Development, IBM MobileFirst PlatformFoundation (previously known as IBM Worklight), or other web applications,initiates an HTTPS call to IBM z/OS Connect Enterprise Edition.

2. z/OS Connect EE is configured with SSL client authentication and fallback tobasic authentication.

3. The client (a mobile server such as IBM MobileFirst Platform Foundation or aweb client) sends to z/OS Connect EE server a client certificate. All clientsmust send a basic authentication credential. The user ID and password in thecredential must be registered in the basic registry or SAF registry on theserver.Note that the IMS Explorer for Development does not send in the clientcertificate. A valid administrative user ID (registered in the RACF or LDAPuser registry) with read/write privileges to the IMS Mobile feature installationdirectory (the value specified for the imsmobile.install.dir variable in theserver.xml file) must be specified in IMS Explorer for Development when youuse the provided wizard to create and publish a mobile service. With this userID properly configured, IMS Explorer for Development is considered a trustedclient.

4. The server verifies the client certificate with the previously imported clientcertificate that is stored in the sever truststore or keyring. If the clientcertificate is missing, the server applies basic authentication against the userregistry that was configured (SAF or LDAP).

5. The client begins transmitting data over a secure connection.

Figure 28. The IMS mobile solution security process flow and components involved


6. For a service request, z/OS Connect EE server authenticates the usercredential. Then the server authorizes the user by using a SAF call to validatethat the group names in the service configuration matches one of the groupnames associated with the user ID in the request subject.

Important:

The user ID is determined based on the following rules:v If a user name and a password are specified in IMS Explorer for

Development when the connection profile is created, the user name and thepassword are used for SAF authentication with IMS Connect.

v If no user name is specified in the connection profile:– The password that is specified in the connection profile is ignored.– The user ID is extracted from the request subject. z/OS Connect

Enterprise Edition must be configured with SAF registry authentication.The IMS service provider retrieves the user ID from the request subject.If the user ID is longer than 8 bytes, the use ID must be properlymapped to a RACF ID.

Note: z/OS Connect Enterprise Edition V2.0.10 or later is required. Inolder versions, the user ID must be 8 bytes or less.

For more information about , see the RACMAP command for mappingbetween a RACF ID and one or more distributed userIDs.https://www.ibm.com/support/knowledgecenter/SSLTBW_2.2.0/com.ibm.zos.v2r2.icha400/racmap.htm.

– If authentication is disabled on z/OS Connect EE, the IMS serviceprovider retrieves the user ID from the technical ID, an IMS mobileglobal element that is specified during initial installation and setup. TheIMS technical password is the SAF password for the user.

– If the technical ID is left blank, the IMS service provider uses the z/OSConnect EE started job user ID. The IMS technical password, if specified,is the SAF password for the user.

v The IMS technical groupname, if specified, is the SAF groupname.7. After authentication and authorization, z/OS Connect EE passes the request to

the IMS Mobile feature for transforming the data from JSON to bytes. Ifauthentication and authorization fail, an error is returned to the client.

8. The IMS Mobile feature transforms the incoming request from JSON to bytes.9. The IMS Mobile feature initiates a request to send the input bytes array and

SAF information to IMS Connect. The HWSJAVA0 user exit on IMS Connect isused to manage the messages. The request triggers SSL handshake via AT-TLS,if it is configured, to protect the communication between z/OS Connect EEserver and IMS Connect.

10. IMS Connect flows the request with the SAF user ID, password, and IMSgroupname to IMS. IMS might perform additional authorization, dependingon the setting. IMS transaction runs. IMS returns response (bytes) to IMSConnect.

11. IMS Connect returns response (bytes) to the IMS Mobile feature.12. The IMS Mobile feature transforms the response from bytes to JSON.13. The response is returned to the client.Related concepts:


https://www.ibm.com/support/knowledgecenter/SSLTBW_2.2.0/com.ibm.zos.v2r2.icha400/racmap.htm


“Security configuration for the IMS mobile solution” on page 140You must configure the z/OS Connect EE server and the back-end IMS to ensuresecure communications.Related information:

Configuring for the IMS service providerTo set up a new server to use the IMS service provider, use the provided templateto set up the required configuration, including the IMS mobile service registry. Ifyou have already set up a server (such as with the WOLA service provider), oryou have specific layout requirements for the XML file, manually configure theserver.xml file.

Before you begin

Important: If you are upgrading from IMS Mobile Feature Pack for z/OS ConnectEE in IMS Enterprise Suite, following the steps in “Upgrading from the IMSMobile Feature Pack in IMS Enterprise Suite” on page 136 instead.

For a new installation or if you are using the IMS service provider the first time,take the following prerequisite steps:1. Install or upgrade to V2.0.5.0 (APAR PI70432) or later. Follow the steps in the

holdcard text.2. The product extensions directory and the required imsmobile.properties file

must be created by using the zconsetup install utility script. Ensure that theproduct extensions directory exists and the required imsmobile.properties fileis added by following the steps in “Setting up the product extensionsdirectory” on page 113.

About this task

Use the provided template to set up a server that is configured to use the IMSservice provider. Instructions are also provided for manual configuration of theserver.xml file. Manual configuration might be the approach to take for thefollowing scenarios:v You already have other service providers set up and working, and now need to

add the IMS service provider.v You want to preserve specific layout of the server.xml.

Procedure

For a new server setup, start with step 1. If you already have a server set up to useother service providers, start with step 3.1. To configure and set up the IMS service provider, run the zosconnect command

with the create option and specify the imsmobile template.zosconnect create <server name> --template=imsmobile:imsDefault

For a default installation directory, the IMS service provider is set up under the/usr/lpp/IBM/zosconnect/v2r0/imsmobile directory.

2. Proceed to step 4.3. If you already have an existing server, manually update the server.xml file to

use the imsmobile-2.0 feature by adding the following configurationinformation in the <featureManager> section:


<featureManager>. . .

<feature>imsmobile:imsmobile-2.0</feature></featureManager>

4. Configure security. Security must be enabled in order to use the IMS Explorerfor Development to create, deploy, and test IMS services. Uncomment therelated tags and provide the appropriate values.a. Uncomment the following tags for SSL and failover to basic authentication:







Use the Liberty server securityUtility command (securityUtility encodeuserID) to generate the encoded password. This utility is located in the<installation_path>/wlp/bin directory.For example, the uncommented security configuration might look asfollows:

<ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore"trustStoreRef="defaultTrustStore" clientAuthentication="false" />

<keyStore id="defaultKeyStore" password="{xor}PjMzbiw7KjE="/>

<keyStore id="defaultTrustStore" password="{xor}PjMzbiw7KjE="/>

<webAppSecurity allowFailOverToBasicAuth="true"/>

b. Configure your SAF registry or basic registry by uncommenting the relatedsections in the server.xml file.For more information about SAF or basic registry configuration, see“Configuring security for z/OS Connect EE” on page 180.

5. Save your changes.You can now start the server and verify if you can use the IMS service provider.6. Start the server.

Starting the server is usually done by running a started task based on thesample JCL <install_location>/jcl/baqstrt.jcl. For information aboutstarting the server, see “Starting and stopping z/OS Connect EE” on page 189.A GMOIG7777I message is issued in the console and logged in themessages.log file in <WLP_USER_DIR>/servers/{servername}/logs, indicatingthat the feature is initialized successfully.

7. Verify that the IMS service provider is configured properly by invoking the IMSPingService service that comes with the IMS Mobile feature. In your RESTclient or Java™ application, use the HTTP PUT method to invoke the providedIMSPingService service:https://hostname:port/zosConnect/services/IMSPingService?action=invoke

Results

You would receive the following response:{

message: "The ping request to the z/OS Connect EE server through the IMS serviceprovider was successful."}

What to do next

To test and verify communications to IMS, you can use the IMS PingService serviceby providing additional parameters. For more information, see “Verifying servercommunication with IMS.”

To start creating a service and an API, see the information in the following IMSscenarios. Each scenario includes a tutorial with detailed steps.v “Create an IMS mobile service ” on page 48v “Develop an API to invoke an IMS service ” on page 66

Verifying server communication with IMSUse the IMSPingService to verify that the IMS service provider can communicatewith IMS Connect by specifying the hostname, port number, and IMS data storename.

About this task

The IMSPingService service is included as part of the IMS Mobile feature that youcan use to check if the IMS service provider is configured correctly. This servicecan also be used to verify that the IMS service provider can communicate with IMSConnect.

Procedure

In your REST client or Java application, use the HTTP PUT method to invoke theprovided IMSPingService service, and specify host name, the port number, and theIMS data store name.https://hostname:port/zosConnect/services/IMSPingService?action=invoke&HOSTNAME=my.ims.host.com&PORT=9999&DATASTORE=IMS1

The HOSTNAME, PORT, and DATASTORE parameters must be in all uppercaseletters, and all three parameters must be specified. If one of the requiredparameters is missing or the parameter names are misspelled, the parameters areignored, and the request is treated as a ping request to the z/OS Connect EEserver. When these parameters are provided correctly, this service issues a /DISPLAYOTMA command to verify that the IMS service provider on the z/OS Connect EEserver can access the IMS host system.


Results

You would receive the following response:

{..."message": "The ping request for the IMS system \"HOSTNAME: 9.30.112.170, PORT: 9999,

DATASTORE: IMS1, RACF ID: admuser\" through z/OS Connect EE and the IMS service providerwas successful."

...}

Upgrading from the IMS Mobile Feature Pack in IMSEnterprise Suite

If you are upgrading from z/OS Connect EE V2.0.4 or earlier and IMS MobileFeature Pack for z/OS Connect EE in IMS Enterprise Suite, modify theimsmobile.properties file manually.

Before you begin

Stop your current server. Ensure that all server processes are stopped.

Procedure1. Apply APAR PI70432 (V2.0.5.0). Ensure that you follow the steps in the APAR

holdcard.2. Modify the imsmobile.properties file in the <WLP_USER_DIR>/v2r0/extensions

directory (default is /var/zosconnect/v2r0/extensions) by setting the value forthe com.ibm.websphere.productInstall property to imsmobile/wlp-ext asfollows:com.ibm.websphere.productInstall=imsmobile/wlp-ext

3. Save your changes.You can now start the server and verify if you can use the IMS service provider.4. Start the server.

Starting the server is usually done by running a started task based on thesample JCL <install_location>/jcl/baqstrt.jcl. For information aboutstarting the server, see “Starting and stopping z/OS Connect EE” on page 189.In the console or the messages.log file in <WLP_USER_DIR>/servers/{servername}/logs, the following message appears:

GMOIG7777I: The IMS Mobile feature initialized successfully.

5. Verify that the IMS service provider is configured properly by invoking the IMSPingService service that comes with the IMS Mobile feature. In your RESTclient or Java application, use the HTTP PUT method to invoke the providedIMSPingService service:https://hostname:port/zosConnect/services/IMSPingService?action=invoke

You would receive the following response:

{message: "The ping request to the z/OS Connect EE server through the IMS service

provider was successful."}


Results

All your existing services and APIs remain untouched. You can proceed to test oneof your services and APIs.

What to do next

Optionally, you can remove the old IMS Mobile Feature Pack installation files toclean up your file system and to reduce confusion.

(Optional) Removing IMS Mobile Feature Pack installation filesThe old IMS Mobile Feature Pack installation files are no longer needed. You canremove them to reduce potential confusion and to clean up your file system.

Before you begin

Ensure that you follow the steps in “Upgrading from the IMS Mobile Feature Packin IMS Enterprise Suite” on page 136 to properly configure the server to use theIMS service provider.

Procedure1. Remove the .esa file for IMS Mobile Feature Pack if you downloaded it or

obtained it through Shopz as part of IMS Enterprise Suite.2. Remove the installed IMS Mobile feature files. This location is specified in the

imsmobile.install.dir variable in the server.xml file. The default is/usr/lpp/ims/imses/V3R2/imsmobile/wlp-ext

3. If a dedicated filesystem was allocated for this mount point, that filesystem canbe deleted from the system because it is no longer used to store the IMS Mobilefeature files.

4. Open the server.xml file and remove the following imsmobile.install.dir variabletag, which is no longer needed.<variable name="imsmobile.install.dir" value="<path_to_ims_mobile_feature_pack_install_dir>"/>

5. Save your changes.

Results

The old IMS Mobile Feature Pack installation files are now cleaned up.

IMS mobile service definitionAn IMS mobile service is created, published, and managed through IMS Explorer forDevelopment. A service is started when it is published.

A started service can be invoked, stopped, and restarted by using REST calls. Youcan also use IMS Explorer for Development to stop and restart a service, or test aservice by invoking it.

A published IMS mobile service is a RESTful service with associated back-endconnections, interaction properties, and a transaction message pair based on theservice metadata. The service metadata object contains metadata that describes theinput and output data formats of the related IMS application. An IMS mobileservice loads service metadata for request and response data transformation. Theservice communicates with one or more connection endpoints as defined in theconnection profiles based on the interactions that are stored in the interactionproperties profile.


IMS Explorer for Development provides the tooling for generating the servicemetadata files from the COBOL copybook or PL/I structure of the IMS application.You can also use IMS Explorer for Development to define the connection propertiesand interaction properties. Based on the service metadata, IMS Mobile featuretransforms the RESTful request and response between JSON and bytes that arerecognized by the back-end IMS COBOL or PL/I application.

A RESTful IMS mobile service has the following elements:

ConnectionAn IMS Connect connection profile contains parameters that are specifiedthrough IMS Explorer for Development, such as a connection profile name,the host name, port number, data store name, and connection timeoutvalue.

Interaction propertiesFor each service communicating with IMS Connect, a set of interactionproperties can be specified, including interaction profile name, commitmode, sync level, and whether the response data includes LLLL.

MetadataA pair of references to metadata that describes the transaction's input andoutput message formats.

Service interfaceAn overlay of transaction metadata to:v Specify a user-friendly service field name.v Select the fields to be included in the service definition.v Provide remarks for each field with possible information on the input

values.v Specify default values for fields.

All this service definition information is stored in the IMS mobile service registry.Related concepts:“IMS mobile service registry, in-memory cache, and administrative services” onpage 139The IMS mobile service registry is the authoritative source of information for serviceresources such as connection profiles, interaction profiles, service metadata, andtransaction message metadata. When a service is first invoked or queried, relatedservice resources are stored in the in-memory cache to improve the performance ofsubsequent requests.“Request and response messages for IMS mobile services” on page 50Request and response messages for IMS mobile services are represented in JSONformat. The schema can be obtained through the getRequestSchema andgetResponseSchema actions.Related reference:“High-level language and JSON schema mapping” on page 51The data mapping function in IMS Explorer for Development communicates withthe data transformation function in IMS Mobile feature to generate JSON schemasfrom high-level language data structures and vice versa.Related information:


IMS mobile service registry, in-memory cache, andadministrative services

The IMS mobile service registry is the authoritative source of information for serviceresources such as connection profiles, interaction profiles, service metadata, andtransaction message metadata. When a service is first invoked or queried, relatedservice resources are stored in the in-memory cache to improve the performance ofsubsequent requests.

When you define a connection profile or an interaction profile, or create a mobileservice by using the IMS Explorer for Development, the information is stored inthe IMS mobile service registry. When a service is first invoked or queried, itsresource information is loaded into the in-memory cache and stays there until theIMS gateway server shuts down. Storing the service information in the cachereduces access latency and shortens server response time.

You can dump the cache into the server log or clear the cache by using IMSExplorer for Development. These functions could be used for troubleshooting.

IMS mobile service registry

The service registry is installed into the location that is defined in the server.xmlfile during initial installation. It is defined in the imsServiceRegistryHome attributein the <imsmobile_imsserviceManager> element.

The service registry default location is a resources/ directory under the serverdirectory (the <WLP_USER_DIR>/servers/<serverName> directory, with a typicallocation of /var/zosconnect/servers/<server_name>). To customize the location,you must specify an absolute path, for example, <imsmobile_imsServiceManagerimsServiceRegistryHome="/usr/lpp/imsmobile/resources"/>.

The service registry directory contains a subdirectory imsmobile-config/ thatcontains the service registry artifacts with the following sub-directories:

Table 23. IMS mobile service registry structure

Directory Description

connections/ This directory contains the ims-connections.xml file thatstores the connection profile information, such as theprofile name and the associated host name, port number,and connection timeout values.

interactions/ This directory contains the ims-interactions.xml file thatstores the interaction properties information, such as theinteraction profile name, the associated commit mode, andwhether the response data includes LLLL.

services/ This directory contains the ims-services.xml file thatdefines all the services and their interfaces. Service inputinterface (serviceName_SII.xml) and output interface(serviceName_SOI.xml) for each service are stored in theinterfaces/ subdirectory.

tran_messages/ This directory contains the input and output messageformats for transactions. Each transaction has its owndirectory that contains the tran_name - INPUT.xml andtran_name - OUTPUT.xml files.


Store the services definitions in a source control management system for versioningcontrol and for service promotion enablement.

IMS mobile administrative services

IMS mobile administrative services are responsible for managing the creation,reading, updating and deletion of IMS mobile service registry artifacts. Theims-admin-services.xml file is the service configuration file that containsinformation about these services. These are z/OS Connect EE services and can bemanaged through the z/OS Connect EE service configuration options. This file islocated in the same directory as server.xml.Related tasks:“Deploying an IMS service to a different target server” on page 144A service is automatically deployed when you create or edit a service by using IMSExplorer for Development. After a service is tested in one environment (such as adevelopment environment), to deploy the service to a different target server (suchas a production server), copy the service definition and interfaces files from theIMS mobile service registry to the target server.“Clearing or examining the IMS service in-memory cache” on page 268To help troubleshoot issues, you can clear the cache or dump the content in thecache into the server log by using the IMS Explorer for Development withoutrestarting the z/OS Connect EE server.

Security configuration for the IMS mobile solutionYou must configure the z/OS Connect EE server and the back-end IMS to ensuresecure communications.

Examine the “IMS service security process flow” on page 130 topic to gain anunderstanding of how user authentication and authorization are handled, and howthe user ID and password for each service request are determined.

Table 24. Required security configurations

Area Configuration task

z/OS Connect EEserver

See “Configuring security for z/OS Connect EE” on page 180 andrelated security configuration topics for details.

IMS services For service-level security, you can set the authority level of a user in the<ims_service_registry_home>/services/ims-services.xml file. Thefollowing example sets, for the phonebook service, the administratorauthority for users in ADMINGRP1 and the Invoke authority for usersin USERGRP1.

<zosconnect_zosConnectService id="phonebook"invokeURI="/imsmobile/services/phonebook"runGlobalInterceptors="true"adminGroup="ADMINGRP1"invokeGroup="USERGRP1"serviceDescription="" serviceName="phonebook"serviceRef="phonebook"/>

See “Overview of z/OS Connect EE security” on page 177 for moreinformation.


Table 24. Required security configurations (continued)

Area Configuration task

IMS serviceprovider

If authentication is disabled on the z/OS Connect EE server, the IMSservice provider retrieves the user from the technical ID that you canspecify in server.xml. In addition, you can specify the technical groupand technical password in an <imsmobile_imsserviceManager>) elementin the server.xml file:

<imsmobile_imsServiceManagerimsServiceRegistryHome="/usr/lpp/imsmobile/resources"imsTechnicalGroup="IMSGROUP"imsTechnicalID="IMSUSER"imsTechnicalPassword="encoded_password"/>

v The IMS technical ID and IMS technical group name must beproperly configured in SAF (or RACF) on the IMS host system.

v The IMS technical password is optional. This global technicalpassword is used if RACF® security is turned on in IMS™ Connect(RACF=Y) but a user ID is not specified in the connection profile.

Use the Liberty server securityUtility command (securityUtilityencode userID) to generate the encoded password. Copy the encodedpassword into the server.xml file for the imsTechnicalPasswordattribute. See “Configuring the global IMS technical password” on page142 for more information.

IMS Connect The user ID and the associated password for each request are passed toIMS Connect for authentication and authorization. If RACF is turned onin IMS Connect, the user ID and the password must be properlyconfigured in RACF on the IMS host system.

The IMS Connect HWSJAVA0 exit routine manages the messages forthe IMS mobile solution and can be used to perform custom securitychecking.

IMS Explorer forDevelopment

To connect to an z/OS Connect EE server to begin creating and editingmessage metadata and specifying the interaction properties, you mustfirst provide a user ID and password along with the host name or IPaddress and the port number. The user ID and password must be setup as an administrative user on the z/OS Connect EE server with readand write permission to the directory where the IMS Mobile featureand the IMS service registry is located.

If RACF is turned on in IMS Connect, when you create a connectionprofile for your IMS mobile service, specify a user ID and a passwordfor RACF authentication. You can create multiple connection profilesfor each server instance, with each connection profile associated with auser ID and password.

For more information about how the user ID is determined when auser ID is not specified in the connection profile, see “Authenticationby IMS Connect” on page 143.

Client applications All client requests must provide basic authentication credentials in theheader. The user ID and password in the credential must be registeredin the basic registry or SAF registry on the server.

Important:

v Use of z/OS Communications Server Application Transparent Transport LayerSecurity (AT-TLS) SSL protection to secure the communication between the z/OSConnect EE server and IMS Connect is recommended.


v Optionally, you can turn on IMS security (/SECURE OTMA) for authorization that isbased on RACF user ID in the request subject and the associated group name.

Enhancing security through these options are recommended. However, If you turnon IMS security, and you are using the basic user registry for user authentication inz/OS Connect EE server, you must use RACF ID as the user ID in your basic userregistry in order for IMS OTMA to authorize the user.

Configuring AT-TLS for IMS Connect and OTMA

Setting up AT-TLS SSL for IMS ConnectFor more information about setting up AT-TLS for IMS Connect, see the IMS 14IMS Connect information.

/SECURE OTMA commandFor more information about setting up IMS security, see the IMS 14 IMSCommands information.

Configuring the global IMS technical passwordIf RACF security is turned on in IMS Connect (RACF=Y), configure a global IMStechnical password per z/OS Connect EE server instance.

Before you begin

Examine the “IMS service security process flow” on page 130 topic to gain anunderstanding of how user authentication and authorization are handled.

About this task

The IMS technical password is optional. If the connection profile is created with auser ID and a password defined, that user ID and the password are used for SAFauthentication in IMS Connect. If a user ID is not specified in the connectionprofile, this technical password is sent to IMS Connect as part of the request withthe request user ID. The user ID might be the ID that issues the request, the IMStechnical ID, or the ID that started the server, depending on your setup.

When IMS Connect RACF security is turned on, a RACF password is required forthe user ID that is associated with the mobile service request. This RACF passwordis specified in this IMS technical password. Only one IMS technical password canbe specified per z/OS Connect EE server instance. This password must be set upin RACF for the user ID or IDs that are associated with the mobile servicerequests.

Procedure

To configure the IMS technical password, modify (uncomment) theimsTechnicalPassword attribute and specify the password in the <imsmobile>element in the server.xml file. Possible approaches to update the server.xml fileinclude:v Use WebSphere Application Server Liberty Profile Developer Tools to configure

the password and then transfer the file to the server by using FTP.v Use the securityUtility command (securityUtility encode userID) to

generate the encrypted password to copy into the server.xml file for theimsTechnicalPassword attribute. This utility is located in the<installation_path>/wlp/bin directory.


http://www.ibm.com/support/knowledgecenter/SSEPH2_14.1.0/com.ibm.ims14.doc.sdg/ims_odb_ssl_setup.htm

http://www-01.ibm.com/support/knowledgecenter/SSEPH2_14.1.0/com.ibm.ims14.doc.cr/imscmds/ims_secure.htm

Results

The updated <imsmobile_imsServiceManager> element in the server.xml file mightlook as follows:<imsmobile_imsServiceManager imsServiceRegistryHome="./resources"

imsTechnicalGroup="SYS1" imsTechnicalID="IMSGUEST"imsTechnicalPassword="{xor}PjMzbiw7KjE=" >

Authentication by IMS ConnectFor authentication with IMS Connect, a user ID and a password can be specified inthe IMS Explorer for Development when you create a connection profile.

The user ID is determined based on the following rules:v If a user name and a password are specified in IMS Explorer for Development

when the connection profile is created, the user name and the password are usedfor SAF authentication with IMS Connect.

v If no user name is specified in the connection profile:– The password that is specified in the connection profile is ignored.– The user ID is extracted from the request subject. z/OS Connect Enterprise

Edition must be configured with SAF registry authentication. The IMS serviceprovider retrieves the user ID from the request subject. If the user ID is longerthan 8 bytes, the use ID must be properly mapped to a RACF ID.

Note: z/OS Connect Enterprise Edition V2.0.10 or later is required. In olderversions, the user ID must be 8 bytes or less.

For more information about , see the RACMAP command for mappingbetween a RACF ID and one or more distributed user IDs.https://www.ibm.com/support/knowledgecenter/SSLTBW_2.2.0/com.ibm.zos.v2r2.icha400/racmap.htm.

– If authentication is disabled on z/OS Connect EE, the IMS service providerretrieves the user ID from the technical ID, an IMS mobile global element thatis specified during initial installation and setup. The IMS technical passwordis the SAF password for the user.

– If the technical ID is left blank, the IMS service provider uses the z/OSConnect EE started job user ID. The IMS technical password, if specified, isthe SAF password for the user.

v The IMS technical groupname, if specified, is the SAF groupname.

If RACF is turned on in IMS Connect, you must specify a user name and apassword when you create a connection profile in IMS Explorer for Development.You can create multiple connection profiles per server instance, each with its userID and password. If no user ID is specified in the connection profile, ensure anIMS technical ID and a technical password are specified. This IMS technicalpassword is used as the password for RACF authentication.

If RACF is turned off in IMS Connect, you can either specify a user name and apassword in the connection profile (all services using the connection profile wouldshare the same user name for IMS authorization), or leave the user name in theconnection profile blank, in which case the user ID coming from the z/OS ConnectEE server would be used for IMS authorization.





Deploying an IMS service to a different target serverA service is automatically deployed when you create or edit a service by using IMSExplorer for Development. After a service is tested in one environment (such as adevelopment environment), to deploy the service to a different target server (suchas a production server), copy the service definition and interfaces files from theIMS mobile service registry to the target server.

About this task

Important: This step assumes the related connection profiles and interactionproperties profiles are already created on the target server.

Procedure1. Obtain the following files from the development server or your source control

management system. These files are located in the IMS mobile service registryin the imsmobile-config/ directory.v services/

– ims-services.xml

– interfaces/serviceName_SII.xml

– interfaces/serviceName_SOI.xml

v tran_messages/tranName/

– tranName-INPUT.xml

– tranName-OUTPUT.xml

2. For each service to deploy on the target server, you need the service interfacesfiles and transaction input and output message format files in the same locationin the IMS mobile service registry on the target server.a. Copy the following files into the service registry on the target server. Ensure

the same directory structure is preserved.v Put the service interfaces files in the services/ directory.

– interfaces/serviceName_SII.xml

– interfaces/serviceName_SOI.xml

v Put the transaction message format files in the tran_messages/tranName/directory.– tranName-INPUT.xml

– tranName-OUTPUT.xml

b. Copy the service definitions in the ims-services.xml file to the same file onthe target server. Each service has an associated<zosconnect_zosConnectService ..> element and a <imsmobile_imsZService...> element:<zosconnect_zosConnectService id="CBLTMBCSService" ... serviceRef="CBLTMBCSService"/><imsmobile_imsZService ... id="CBLTMBCSService"

Copy these two set of tags into the ims-services.xml file on the targetserver.

Tip: Any new or changed service definitions are appended to the end ofthe ims-services.xml file.

3. If your updateTrigger attribute of the config element in server.xml is set tombean, restart the server. The default setting is polled, and the server will pickup the new services without a restart.


Example

For sample scripts that demonstrate how to deploy services, see Sample shellscripts for deploying IMS mobile services to a different target server.

Using other service providersUsing the service providers that are supplied with other products.

Both WOLA and IMS service providers are included with z/OS Connect EE. Youcan also write your own service provider or you can use one that is supplied withthe SoR to plug into the framework. The following list provides references to thedocumentation for other products that supply their own service providers.

IBM MQ for z/OS Service Provider for z/OS ConnectThe IBM MQ service provider allows REST aware applications to interactwith z/OS assets that are use IBM MQ for z/OS queues and topics. Theapplication can be written without the need to code for asynchronousmessaging.

Configuring the z/OS Connect EE REST client serviceThe z/OS Connect EE REST Client support enables z/OS Connect EE users toroute requests to remote REST applications through z/OS Connect EE, takingadvantage of the existing interceptor infrastructure.

About this task

This function is available when you configure z/OS Connect EE. The z/OSConnect EE REST Client service is a z/OS Connect EE service SPI implementation.Requests can use the following methods to invoke this service:1. Use the ?action=invoke query parameter mechanism as follows:

https://hostName:port/zosConnect/services/serviceY?action=invoke whereserviceY is the service name that is associated with the configuredzosConnectServiceRestClient element.

2. Use the zosConnectService attribute definition that is called invokeURI. Youcan use this attribute to define a custom URI that is associated with a servicename and any of the following HTTP verbs: GET, POST, PUT, DELETE; forexample:

<zosconnect_zosConnectService serviceName="serviceY" serviceRef="restClientServiceY" invokeURI="/my/custom/uri" />

3. Use an API to invoke the service.

An example of a service invocation for the defined service is: https://host:port/my/custom/uri (HTTP verb: GET/POST/PUT/DELETE).

z/OS Connect EE understands the association between the invokeURI attribute andthe serviceName attribute defined in the example. z/OS Connect EE calls theinvoke method on the implementation of the z/OS Connect EE associated service(restClientServiceY).

For more information on the capability and flexibility that the invokeURI attributeoffers, see “zosconnect_zosConnectService” on page 318 in the Reference section.


https://www-304.ibm.com/support/docview.wss?uid=swg27048355

https://www-304.ibm.com/support/docview.wss?uid=swg27048355

https://www.ibm.com/support/knowledgecenter/SSFKSJ_9.0.0/com.ibm.mq.adm.doc/q127330_.htm

Procedure1. Configure the zosConnectServiceRestClient element and associate it with a

zosConnectService element. You should use thezosconnect_zosConnectServiceRestClientConnection element to configure theHTTP endpoint information independently of the Service definition. Thismethod allows you to deploy the same SAR file into multiple environmentswhich might need to connect to different backend systems.

<featureManager><feature>zosconnect:zosconnect-2.0</feature>

</featureManager>

<zosconnect_zosConnectInterceptors interceptorRef="auth,audit,fileSystemLogger" id="globalInterceptorList1"/><fileSystemloggerInterceptor id="fileSystemLogger" logName="service1Log_%SERVERNAME%"sequence="1"/><authorizationInterceptor id="auth" sequence="2"/><auditInterceptor id="audit" sequence="3"/>

<zosconnect_zosConnectManager

globalAdminGroup="ADMIN"globalOperationsGroup="OPS"globalInvokeGroup="INVOKE"globalInterceptorsRef="globalInterceptorList1" />

<zosconnect_zosConnectServiceserviceName="serviceY"serviceRef="restClientServiceY"invokeURI="/my/custom/uri" />

<zosconnect_zosConnectServiceRestClientid="restClientServiceY"connectionRef="restClientConnectionY"uri="/remote/endpoint"httpMethod="DELETE" />

<zosconnect_zosConnectServiceRestClientConnectionid="restClientConnectionY"connectionTimeout="30s"host="remoteHostName"port="8800"receiveTimeout="60s" />

In the example, requests that target the serviceY service are routed to theremote host and port that is configured under the associatedrestClientServiceY service and that uses the configured URI and DELETEHTTP method. The JSON payload is automatically sent with the remoterequest. The host name and port number attributes are specified in theassoicated zosConnectServiceRestClientConnection element. If you do notspecify the uri or httpMethod attributes, the values that are used are the onesfrom the original client request that is targeting the serviceY service. Theexample also shows that because interceptors are configured to run globally,every request that targets the serviceY service is logged, authorized, andaudited before it is routed to the remote endpoint. The interceptors also log andaudit the responses on the return from the remote endpoint. Because aninvokeURI attribute is configured for the serviceY service, the requester canstart the implementation of the serviceY invoke method by using the followingURL: https://host:port/my/custom/uri and using either the GET, POST, PUT, orDELETE HTTP methods. In this case, because the serviceY service refers to aninstance of the z/OS Connect REST client service, the invoke() method on thisinstance is called. For more information about available configuration attributesand default values, see “Configuration elements” on page 283 in the Referencesection.

Alternatively, you can define the connection information directly in thezosConnectServiceRestClient element and associate it with azosConnectService element, but using this method means that the same SARfile cannot be deployed into multiple environments.

<featureManager><feature>zosconnect:zosconnect-2.0</feature>

</featureManager>

<zosconnect_zosConnectInterceptors interceptorRef="auth,audit,fileSystemLogger" id="globalInterceptorList1"/><fileSystemloggerInterceptor id="fileSystemLogger" logName="service1Log_%SERVERNAME%"sequence="1"/><authorizationInterceptor id="auth" sequence="2"/><auditInterceptor id="audit" sequence="3"/>

<zosconnect_zosConnectManager

globalAdminGroup="ADMIN"globalOperationsGroup="OPS"globalInvokeGroup="INVOKE"

globalInterceptorsRef="globalInterceptorList1"/>

<zosconnect_zosConnectServiceserviceName="serviceY"serviceRef="restClientServiceY"invokeURI="/my/custom/uri" />

<zosconnect_zosConnectServiceRestClientid="restClientServiceY"host="remoteHostName"port="8800"uri="/remote/endpoint"httpMethod="DELETE" />

2. Optional: Configure basic authentication. Add the appSecurity-2.0 feature tothe server.xml file.<featureManager>

<feature>zosconnect:zosconnect-2.0</feature><feature>appSecurity-2.0</feature>

</featureManager>

<zosconnect_zosConnectServiceRestClientBasicAuthid="fredBasicAuth"userName="Fred"password="{xor}OS06Oy8oOw=="/>

<zosconnect_zosConnectServiceRestClientid="restClientServiceY"host="remoteHostName"port="8800"uri="/remote/endpoint"httpMethod="POST"basicAuthRef="fredBasicAuth" />

<zosconnect_zosConnectServiceserviceName="serviceY"serviceRef="restClientServiceY" />

The configuration enables the user name and password that is configured forthe zosConnectServiceRestClientBasicAuth element to be propagated when therequest to the remote REST application endpoint is made.

3. Optional: Configure certificate authentication. Add the appSecurity-2.0 featureto the server.xml file.The example shows how to configure the client keystore and client truststoreand associate them with the zosConnectServiceRestClient configuration.

<featureManager><feature>zosconnect:zosconnect-2.0</feature><feature>appSecurity-2.0</feature>

</featureManager>

<keyStore id="clientKeyStore" password="zosConnect"location="${server.config.dir}/resources/security/clientKey.jks" />

<keyStore id="clientTrustStore" password="zosConnect"location="${server.config.dir}/resources/security/clientTrust.jks" />

<ssl id="sslCertificates" keyStoreRef="clientKeyStore" trustStoreRef="clientTrustStore"/>

<zosconnect_zosConnectServiceRestClientid="restClientServiceY"connectionRef="restClientConnectionY"uri="/remote/endpoint"httpMethod="PUT" />

<zosconnect_zosConnectServiceRestClientConnectionid="restClientConnectionY"basicAuthRef="fredBasicAuth"connectionTimeout="30s"host="remoteHostName"port="8800"receiveTimeout="60s"sslCertsRef="sslCertificates" />

<zosconnect_zosConnectService serviceName="serviceY" serviceRef="restClientServiceY" />

Configuring interceptorsz/OS Connect EE provides a framework that enables interceptors, or methods, towork with operations such as service invoke, status, start, or stop. Interceptors areOSGi services that implement the com.ibm.zosconnect.spi.Interceptor ServiceProvider Interface (SPI) that is provided by z/OS Connect EE.

About this task

You can use interceptors for many purposes. z/OS Connect EE does not knowwhat an interceptor is used for. For example, an interceptor might be written toperform some infrastructure setup that is based on the message payload before therequest is processed. z/OS Connect EE provides a copy of the input requestpayload to all interceptors.

z/OS Connect EE provides the zosconnect_zosConnectService configurationelement that enables the administrator to configure a set of attributes that apply toa particular service. One of these attributes is interceptorsRef, which points to aconfiguration element that lists one or more interceptors to run for a specificservice.

This task describes how to define a z/OS Connect EE interceptor and a list ofinterceptors, and also explains how to associate the interceptors with one or moreservices in the configuration for a server. This task also includes a description ofhow to enable the z/OS Connect EE, provided audit and authorization interceptorsfor services.

If defined, interceptors are called in a specific order:1. Global interceptor pre-invoke methods2. User interceptor pre-invoke methods


3. API is invoked4. User interceptor post-invoke methods5. Global interceptor post-invoke methods

Within each category, the sequence attribute determines the order in which theinterceptors run. For pre-invoke methods, the lowest number runs first. Forpost-invoke methods, the lowest number runs last. If the sequence numbers are thesame, there is no set order. If the sequence is not defined (or incorrectly defined),these interceptors run their pre-invoke methods after all other interceptors of thesame type, and their post-invoke methods before all other interceptors of the sametype. For more information, see Interface Interceptor.

Procedure1. Update the <zosconnect_zosConnectService> element for each service in your

server.xml configuration for which you want to enable an interceptor or list ofinterceptors for.<zosconnect_zosConnectService id="zcs1"serviceName="recordOpsCreate"serviceRef="wolaOpsCreateService"interceptorsRef="opsCreateInterceptorList"/>

2. Create the associated <zosconnect_zosConnectInterceptors> element.<usr_userInterceptorOne id="userI1" sequence="1"/><usr_userInterceptorTwo id="userI2" sequence="2"/>

<zosconnect_zosConnectInterceptors id="opsCreateInterceptorList" interceptorRef="userI1, userI2"/>

The name of the interceptor list in this example is opsCreateInterceptorList.Two interceptors are referred to here, userI1 and userI2. Interceptorimplementations use the Liberty SPI extensions. These interceptors must definetheir metatypes to the z/OS Connect EE profile server and create animplementation of the com.ibm.zosconnect.spi.Interceptor class. In thisexample, an implementation of this class is created with a metatype thatdefines the elements usr_userInterceptorOne and usr_userInterceptorTwo. Thename of the configuration element where the list of interceptors is provided iscalled interceptorsRef. It is not a required attribute.

3. Optional: Create a global interceptor list and enable it in the<zosconnect_zosConnectManager> element. The globalInterceptorsRef item isthe name of the element in the configuration that describes the set of z/OSConnect EE interceptors that apply to all of the services in the configuration.

<zosconnect_zosConnectManager globalInterceptorsRef="globalInterceptors"/>

<usr_userInterceptorOne id="userI1" sequence="1"/><usr_userInterceptorTwo id="userI2" sequence="2"/><zosconnect_zosConnectInterceptors id="globalInterceptors" interceptorRef="userI1, userI2"/>

4. Optional: Enable the z/OS Connect EE-provided audit, authorization, orlogging interceptors for a service or set of services. The z/OS ConnectEE-supplied audit interceptor implements thecom.ibm.zosconnect.spi.Interceptor SPI to store audit or tracking informationin the z/OS System Management Facility (SMF) data sets. The authorizationinterceptor gives the ability to verify that the current authenticated user has theauthority to perform the requested action. Examples of actions that are checkedinclude service action=invoke, start, or stop. You enable these interceptors

for one or more services in the z/OS Connect EE server configuration. Thefollowing example shows how to enable both the audit and authorizationinterceptors for a single service:

<zosconnect_zosConnectService id="zcs1"serviceName="recordOpsCreate"serviceRef="wolaOpsCreateService"interceptorsRef="opsCreateInterceptorList1"/>

<zosconnect_authorizationInterceptor id="authInterceptor1" sequence="1"/><zosconnect_auditInterceptor id="auditInterceptor1" sequence="2"/>

<zosconnect_zosConnectInterceptors id="opsCreateInterceptorList1" interceptorRef="auditInterceptor1, authInterceptor1"/>

Configuring the file system logger interceptorThe file system logger interceptor enables z/OS Connect EE users to log requestinformation in a file.

About this task

This function is available when you configure z/OS Connect EE.

Table 25. Descriptions of the entries that are in the generated log file

Entry Description

DateTime The date and time that is calculated by the loggerinterceptor before the service invocation

ThreadID The ID of the thread under which the service request isbeing processed

UserName The user name for which the request is being processed

RequestID The request tracking ID that is generated by z/OSConnect EE

RemoteAddress The Internet Protocol (IP) address of the client whooriginated the request or last proxy that sent the request

LocalAddress The Internet Protocol (IP) address of the interface onwhich the request was received

MessageType Identifies whether the payload is from a request or aresponse

MessageSize The character size of the payload

MessageData A request or response payload

*****************************************************************************ServerName: com.ibm.zosconnect.interceptor.logger.fs*****************************************************************************DateTime:2015-07-19_12-14-02 | ThreadId:47 | UserName:Fred | RequestID:0000000000000001000000000000000000000000000000 |RemoteAddress:127.0.0.1 | LocalAddress:127.0.0.1MessageType:REQUESTMessageSize:27MessageData:{"payload":"HELLO_SERVICE"}

DateTime:2015-07-19_12-14-02 | ThreadId:47 | UserName:Fred | RequestID:0000000000000001000000000000000000000000000000 |RemoteAddress:127.0.0.1 | LocalAddress:127.0.0.1MessageType:RESPONSEMessageSize:26MessageData:{"payload":"HELLO_CALLER"}

The file system logger interceptor is configured via azosconnect_fileSystemloggerInterceptor entry in server.xml. This entry has thefollowing attributes:

Table 26. . Descriptions of the entries that are in the zosconnect_fileSystemloggerInterceptor

Attribute name Data type Default value Description

bufferSize int 8192 Buffer size setting to beused when thebufferLogging attribute isset to true.

bufferedLogging boolean false Indicates whether entries tothe log is buffered beforethey are written to the logfile.

encoding string UTF-8 Encoding used whenwriting to the log file.

id string A unique configuration ID.

logName string Log file name pattern usedfor payload logging.

logOption RESPONSEREQUESTALL

ALL Log option that controlswhat is logged.

RESPONSEIndicates that onlyresponse data islogged.

REQUESTIndicates that onlyrequest data islogged.

ALL Indicates that bothrequest andresponse data arelogged.

logPath string File system location inwhich the file log iscreated. If the environmentvariable ${server.output.dir}is configured, its value isused by default.

maxPayloadSize int 524288 Maximum payload size inbytes allowed to be writtento the log file.

rollOffLogPolicy SIZEDURATION

SIZE Indicates that log fileshould be rolled off basedon size or duration.

SIZE Indicates that thelog file should beroll off based onsize.

DURATION%rollOffLogPolicy.duration

rollOffLogPolicyDuration int 1440 Roll off policy duration inminutes.


Table 26. (continued). Descriptions of the entries that are in the zosconnect_fileSystemloggerInterceptor


rollOffLogPolicySize int 52428800 Roll off policy size in bytes.

sequence int

(Minimum: 0 Maximum:2147483647)

0 Sequence in which theinterceptor is processedwith respect to others.

Procedure1. Configure the zosconnect_fileSystemloggerInterceptor element globally.

<zosconnect_fileSystemloggerInterceptor id="globalFileSystemLogger" logName="globalLog_%SERVERNAME%"/><zosconnect_zosConnectInterceptors id="globalInterceptorList" interceptorRef="globalFileSystemLogger" /><zosconnect_zosConnectManager globalInterceptorsRef="globalInterceptorList"/>

In the example, all z/OS Connect EE service requests are logged in a file calledglobalLog_myServer1_yyyy-MM-dd_HH_mm_ss_SSS.log, where myServer1 is thename of the server. The only required configuration element is the logNameattribute definition. The configuration element accepts a %SERVERNAME% stringthat is replaced with the name of the server when the log is created. Thedefault log file location is ${server.output.dir}/logs/zosConnect. For moreinformation about available configuration attributes and default values, see“Configuration elements” on page 283 in the Reference section.You can also configure the fileSystemloggerInterceptor element for specificservices.

<zosconnect_fileSystemloggerInterceptor id="serviceYFileSystemLogger"logName="service1Log"logPath="/zosConnect/logs"logOption="RESPONSE"maxPayloadSize="30720"/>

<zosconnect_zosConnectInterceptors id="serviceYInterceptorList" interceptorRef="serviceYFileSystemLogger" /><zosconnect_zosConnectService serviceName="serviceY" serviceRef="serviceY" interceptorsRef="serviceYInterceptorList"/><usr_myService id="serviceY"/>

In the example, information is logged in a file called service1Log_yyyy-MM-dd_HH_mm_ss_SSS.log which is located in the path /zosConnect/logs. The logpath is a fully qualified path. Only response data is logged for all incomingrequests that target serviceY. The maximum JSON payload is configured to be30,720 characters, so any JSON response payload that is greater than 30,720characters is truncated to the configured maximum payload size.

2. Optional: Configure the bufferedLogging and the bufferSize attributedefinitions to enable buffered logging. The default buffer size is 8 kilobytes. Allrecords in the buffer are flushed to the disk when the buffer becomes full.Using buffered logging is appropriate when performance is a concern andwhen it is acceptable for a possible loss of records from the buffer during afailure condition.<zosconnect_fileSystemloggerInterceptor id="globalFileSystemLogger"

logName="globalLog_%SERVERNAME%"bufferedLogging="true"bufferSize="16384"/>

3. Optional: Configure the rollOffLogPolicy attribute. This policy states when anew file is created based on when the active log file reaches the specified ordefault file size of 50 megabytes, or when the specified or default time of 24hours expires since the active log file was created. In the following example, anew file is created when the file reaches 16 kilobytes in size. The namingschema is the same: globalLog_myServer1_yyyy-MM-dd_HH_mm_ss_SSS.log. Thedifference between the newly created log files is the time stamp that is usedwhen the new file is created:


<zosconnect_fileSystemloggerInterceptor id="globalFileSystemLogger"logName="globalLog_%SERVERNAME%"rollOffLogPolicy="SIZE"rollOffLogPolicySize="16384"/>

Auditing and trackingTo audit and track requests, you can use the audit interceptor included with z/OSConnect EE, or live statistics for z/OS Connect EE services.

Audit Interceptor

You can use a RESTful interface to retrieve live statistics data for z/OS Connect EEservice requests. For example, to obtain the feature start time, total number ofservice requests and the distribution of requests.

You can enable the interceptor in z/OS Connect EE on a single or group of z/OSConnect EE services. The z/OS Connect EE audit interceptor records requestactivity to the SMF data store on z/OS operating systems. SMF type 123, subtype 1records are generated.

Note: For z/OS Connect EE to write to SMF, the user ID under which z/OSConnect EE runs, must have READ access to the RACF BPX.SMF profile of theFACILITY class. An example of the required command syntax is shown here:PERMIT BPX.SMF CLASS(FACILITY) ACCESS(READ) ID(USERID)

For more information, see Defining z/OS UNIX users to RACF in the z/OS UNIXSystem Services Planning documentation.

The SMF type 123 subtype 1 record contains the following information insequence:1. Standard SMF header2. SMF type 123 subtype 1 header extension3. Triplet #1 for the server identification section4. Triplet #2 for the user data section5. Server identification section (one instance)6. User data sections (multiple instances)

Triplet #1 and Triplet #2 each consist of an ordered set of three 2-byte values,representing: offset, length, number. If you dump your SMF data set to a raw file,you can use the sample JCL found in <installation_path>/jcl/baqs123.jcl toformat the SMF 123 subtype 1 records. The JCL uses the z/OS ICETOOL utilityand formats each of the following sections.

Standard SMF headerThe standard SMF header that is used by z/OS Connect EE is a StandardSMF Record Header for Records with Subtypes.

Note: The first 4 bytes of the standard SMF header, the record descriptorword (RDW), contains the fields SMFxLEN and SMFxSEG. The SMFoffload utility, IFASMFDP, strips the RDW from each record so, offsets forthe subsequent header fields must be adjusted.

SMF type 123 subtype 1 header extensionThe SMF type 123, subtype 1, header extension is defined in Table 1:


https://www.ibm.com/support/knowledgecenter/SSLTBW_2.2.0/com.ibm.zos.v2r2.bpxb200/secuid.htm

Table 27. SMF 123 subtype 1 header extension.

Offset Length Data type. Data

0 4 Binary Subtype version number.

4 4 Binary Number of triplets.

8 4 Binary Index of this record.

12 4 Binary Total number of records.

16 8 EBCDIC Record continuation token.

Note: SMF 123 subtype 1 records are typically non-spanning. In this case,the value of index is 0 (zero), total records is 1 (one), and the recordscontinuation token is 8 bytes of nulls.

The SMF type 123 subtype 1 header for SMF records is followed by twotriplets. The first triplet points to the server identification section. Only oneserver identification section is allowed. The second triplet points to theuser data section, which can have multiple instances.

Triplet #1 for the server identification sectionTriplet #1 describes the server identification section that is detailed in Table2. The server data section consists of the following parameters: (values indecimal).

Table 28. Server data section parameters.


0 4 Binary Version of SMF record.

4 8 Character System name.

12 8 Character Sysplex name.

20 8 Character Job ID (jsabjbid).

28 8 Character Job name (jsabjbnm).

36 8 Binary SToken (assbstkn).

44 36 N/A Reserved.

Triplet #2 for the user data section

Triplet #2 describes the user data sections that are detailed in Tables 3 and4. The user data section consists of the following parameters (values indecimal):

Table 29. User data section parameters.


0 4 Binary Version.

4 4 Binary Type

8 4 Binary Length of data (user data sections are 2KB, this field indicates how much of that isused).

12 N/A Data (See Table 4).

For z/OS Connect EE, the value of the user data type field is 66(hexadecimal) or 102 (decimal). The data contains the followingparameters:


Table 30. User data section parameters.


0 4 Binary Version.

4 8 Store Clock(STCK).

Arrival date and time.

12 8 Store Clock(STCK).

Completion date and time.

20 64 Character Target URI (EBCDIC, right padded withblanks).

84 4 Binary Request payload length in bytes.

88 64 Character API or Service name (EBCDIC, rightpadded with blanks).

152 8 Character Method (EBCDIC).

160 4 Binary Response payload length in bytes.

164 64 Character User name (EBCDIC, right padded withblanks).

228 23 Binary Request ID (bytes, right padded withzeros).

251 1 Boundary padding (zero).

252 64 Character Service grouping name (EBCDIC,right-padded with blanks).

316 8 Character Mapped user name (EBCDIC, right-paddedwith blanks).

Retrieving live statistic data

Feature start time, total number of service requests and the distribution of requestsare available by using this operational capability. Valid authenticated clients areable to use a HTTP GET for one of the following URIs to retrieve statistics about thez/OS Connect EE server:v Get statistics for a single service. For example, to get statistics for the HelloWorld

service:https://<hostname:port>/zosConnect/services/HelloWorld?action=getStatistics

v Get statistics for all services in the server:https://<hostname:port>/zosConnect/operations/getStatistics

v Get statistics for all services under a single service provider by specifying theprovider="<service provider name>" query parameter. For example, to retrievestatistics for all services that are associated with the provider name of WOLA-1.0use the following URLhttps://<hostname:port>/zosConnect/operations/getStatistics?provider=WOLA-1.0"

v The response data is returned in JSON object format.

Configuring the audit interceptorYou can use the audit interceptor included with z/OS Connect EE, to audit andtrack requests. The interceptor records data to the z/OS SMF data store.

About this task

You can enable the audit interceptor on a single or group of z/OS Connect EEservices.


Procedure

Enable the audit interceptor supplied with z/OS Connect EE for a service or set ofservices. The audit interceptor implements thecom.ibm.zosconnect.spi.Interceptor SPI to store auditing and trackinginformation in the audit interceptor supplied with z/OS System ManagementFacility (SMF) data sets. The following is an example that shows how to enable theaudit interceptor for a single service:

<zosconnect_auditInterceptor id="auditInterceptor" sequence="1"/>

<zosconnect_zosConnectInterceptors id="interceptorList1" interceptorRef="auditInterceptor"/>

<zosconnect_zosConnectService id="zcs1" serviceName="recordOpsCreate" serviceRef="wolaOpsCreateService"interceptorsRef="interceptorList1"/>

You can use the sequence parameter to control the sequence in which theinterceptors are called. For more information, see “zosconnect_auditInterceptor” onpage 301 in the Reference section of this documentation.

Configuring API specific interceptorsThe z/OS Connect EE administrator can configure a user-defined set ofinterceptors for an API.

The zosConnectAPI element represents a single API definition that is madeavailable at runtime by the server associated with a given server.xml configurationfile.

The zosConnectAPI element accepts an interceptorsRef element, which can beused by the z/OS Connect EE administrator to configure the API with auser-defined set of interceptors. These interceptors are invoked whenever a requestis matched to that API for invocation (pre-invoke), and before the result is returnedto the caller (post-invoke). For example:<zosconnect_zosConnectAPIs location="">

<zosConnectAPI name="Health" interceptorsRef="medstaffInterceptorList" /><zosConnectAPI name="Foo" interceptorsRef="adminInterceptorList" /><zosConnectAPI name="Bar" interceptorsRef="patientInterceptorList" />

</zosconnect_zosConnectAPIs>

This example implies the existence of three zosConnectInterceptor definitions,located in server.xml:<zosconnect_zosConnectInterceptors id="medstaffInterceptorList" interceptorRef=".....<zosconnect_zosConnectInterceptors id="adminInterceptorList" interceptorRef=".....<zosconnect_zosConnectInterceptors id="patientInterceptorList" interceptorRef=".....

For more information, see Defining interceptors.

Excluding specific APIs from the Global interceptors

The runGlobalInterceptors element accepts values true or false, and defaults totrue. You can use this element to exclude individual APIs from a configured globalinterceptor. For example, the following configuration would exclude the HealthAPI from any global interceptor definition:

<zosconnect_zosConnectAPIs location=""><zosConnectAPI name="Health" interceptorsRef="medstaffInterceptorList" runGlobalInterceptors="false" /><zosConnectAPI name="Foo" interceptorsRef="adminInterceptorList" /><zosConnectAPI name="Bar" interceptorsRef="patientInterceptorList" />

</zosconnect_zosConnectAPIs>

Configuring Data TransformersIBM z/OS Connect EE provides the ability to optionally transform request andresponse payloads that are used for calling a business asset on z/OS operatingsystems. You can create message payload transformers to satisfy specific needs byimplementing the com.ibm.zosconnect.spi.DataXform Service Provider Interface(SPI), which is included with z/OS Connect EE.

About this task

z/OS Connect EE provides an implementation that requires the request andresponse message format be JSON. This product supports the conversion of therequest to a byte array, which can be mapped by a native language COBOL, PL/I,or C structure. This language structure of the target program, or copy book,includes a description of the in and out parameters. The language structure isused by a supplied utility to generate a binding file and JSON request andresponse schema files. The bind file that is generated by this utility is used byz/OS Connect EE to complete the data conversion to and from JSON and nativedata formats as requests arrive and responses are returned. You can retrieve theJSON schemas for the request and response message with a RESTful API call thatis provided by z/OS Connect EE.

z/OS Connect EE provides the zosConnectService configuration element thatenables the administrator to configure a set of attributes that apply to a particularservice. One of these attributes is dataXformRef, which points to a datatransformation configuration that is to be used for a specific service. This taskdescribes how the data transformer supplied with z/OS Connect EE is used.

Note:

1. In the examples shown in steps 1 & 2, the serviceName and bindFileSuffixmust match the bindfile found in bindFileLoc. For example:recordOpsCreate.wsbind resides in /u/bindfiles.

2. The request and response schema file names must match the serviceNamespecified in the zosConnectService element with _request or _responseappended. The values, including the file type, must match therequestSchemaSuffix or responseSchemaSuffix respectively. For example:recordOpsCreate_request.json and recordOpsCreate_response.json. These filesmust reside in /u/json.

Procedure1. Update the zosConnectService element for each service in your server.xml

configuration for which you want to enable the data transformation suppliedby z/OS Connect EE.<zosconnect_zosConnectService id="zcs1"serviceName="recordOpsCreate"serviceRef="wolaOpsCreateService"dataXformRef="xformJSON2byte"/>

2. Create the associated zosConnectDataXform element.

<zosconnect_zosConnectDataXform id="xformJSON2byte"

bindFileLoc="/u/bindfiles" bindFileSuffix=".wsbind"requestSchemaLoc="/u/json" responseSchemaLoc="/u/json"requestSchemaSuffix=".json" responseSchemaSuffix=".json"/>

3. Optional: Configure a data transformer that applies to all services. Set theglobaDataXformRef of the zosConnectManager element to the configured datatransformer's ID that is intended for global use. If both global and service datatransformers are defined and requests come in for a service with a configureddata transformer, z/OS Connect EE will use the data transformer configuredspecifically for the service.<zosconnect_zosConnectManager globalDataXformRef="globalDataXform"/>

<zosconnect_zosConnectDataXform id="globalDataXform"

bindFileLoc="/u/bindfiles" bindFileSuffix=".wsbind"requestSchemaLoc="/u/json" responseSchemaLoc="/u/json"requestSchemaSuffix=".json" responseSchemaSuffix=".json"/>

Creating bind and schema filesz/OS Connect EE provides the ability to optionally transform request and responsepayloads that are used for calling a business asset on z/OS operating systems.z/OS Connect EE supplies two new utilities called BAQLS2JS and BAQJS2LS.

Before you begin

Before you create your binding and schema files, make sure that your setupcomplies with these conditions:v Your high-level language data structures must meet the following criteria:

– The data structures must be defined separately from the source program. Forexample, in a COBOL copybook.

– If your PL/I or COBOL application program uses different data structures forinput and output, the data structures must be defined in two differentmembers in a partitioned data set. If the same structure is used for input andoutput, the structure must be defined in a single member.

– For C and C++, your data structures can be in the same member in apartitioned data set.

v The language structures must be available in a partitioned data set.v You must define to Open Multiple Virtual Storage (OMVS) the user ID that

BAQLS2JS or BAQJS2LS uses to run.v The user ID must have read permission to z/OS UNIX and PDS libraries, and

write permission to the directories that are specified on the LOGFILE, WSBIND,and JSON-SCHEMA-REQUEST and JSON-SCHEMA-RESPONSE output parameters.

v The user ID must have a sufficiently large storage allocation to run Java. You canuse any supported version of Java. The BAQLS2JS and BAQJS2LS utilities use theJava version that is specified by JAVA_HOME in BAQLS2JS.jcl and BAQJS2LS.jcl.Otherwise, the ID uses the Java version specified on the PATH statement.

About this task

The BAQLS2JS utility reads a COBOL copybook, PLI structure, or C structure fileand generates a binding file and JSON schema files. The BAQJS2LS utility reads aJSON schema and generates the corresponding binding file and language structurefile. The utilities are similar to the existing DFHLS2JS and DFHJS2LS tools, which arepart of the CICS Transaction Server Mobile Extensions feature pack.

Procedure1. Copy the BAQLS2JS.jcl or BAQJS2LS.jcl procedure to a writeable directory or

dataset2. Use the BAQLS2JS procedure to generate a z/OS Connect EE service binding file

from a language structure. You will need to provide JCL to invoke the BAQLS2JSprocedure with the input parameters. Refer to the BAQLS2JS referencedocumentation for information on the input parameters and an example job tohelp you use the procedure. When you submit the BAQLS2JS procedure, theutility generates the service binding file to the location that you specified withthe WSBIND parameter. The generated JSON schemas are placed in the locationthat you specified with the JSON-SCHEMA-REQUEST and JSON-SCHEMA-RESPONSEparameters. For more information, see “Conversion for z/OS ConnectEnterprise Edition data transformation” on page 250.

Note: In order to generate a service archive file, SERVICE-ARCHIVE andSERVICE-NAME must be specified in BAQLS2JS.

3. Review the generated JSON schema. These schemas are used to define theinput and output data formats for interacting with the z/OS Connect EEservice. The application developer must use these schemas when creating anapplication to call the service and pass the JSON request payload.

Note: Changing the generated schema invalidates the generated binding file atWSBIND. If you want to change the schema, for example, to rename the fieldswithin the schema, you must use BAQJS2LS to generate a new binding file, anda new set of language structures. The application program must be re-compiledto use the new language structures.

Configuring SARsYou can add the zosconnect_services element to server.xml and configure whereservice archive packages for the REST Client service provider are stored.

You copy a SAR file into a directory where it can be accessed during APIdevelopment. The definition of the service must be added to the server.xmlconfiguration file before it can be used.

Important: This feature is supported for the REST Client service provider only.

The zosconnect_services element in the configuration file defines the z/OSConnect EE services to be deployed. For example,<zosconnect_services location="/var/zosconnect/services" updateTrigger="polled" pollingRate="100ms"><service name="AddCustomer" /><service name="InquireCustomer" /><service name="UpdateCustomer" /></zosconnect_services>

The server.xml configuration file can contain the following elements:

zosconnect_services

v Only one zosconnect_services element is allowed.v The location parameter is optional and specifies where the SAR

packages are deployed. If it is not defined, then the${server.config.dir}/resources/zosconnect/services directory is usedas the SAR package installation directory. When the server is started, allthe SAR packages are deployed in the server.


v The updateTrigger parameter is optional and controls when z/OSConnect EE is notified about changes in the services directory. Thedefault value of the updateTrigger parameter is disabled. For moreinformation, see “zosconnect_services” on page 306 in the Referencesection.

service

v One or more service elements can be contained in thezosconnect_services element.

v Supports other optional attributes that, for example, can be used todefine authentication, authorization, or interceptors specific to a service.For more information, see “Configuration elements” on page 283.

v The attributes adminGroup, invokeGroup, operationsGroup, readerGroup,requireAuth, and requireSecure are available to specify authenticationand authorization for a service. For more information, see Chapter 8,“Securing,” on page 177.

v The attributes interceptorsRef and runGlobalInterceptors are availableto specify interceptors for a service. For more information, see“Configuring API specific interceptors” on page 156.

property

v One or more property elements can be contained in the serviceelement.

v Defines optional properties for the service provider.v Properties can only be defined by editing the server.xml file.v Properties remain in the configuration file after the SAR file is moved or

deleted.Related concepts:Chapter 12, “Administering SARs,” on page 231Use this information to learn how to manage your service archives.

Configuring APIsHow to add the zosconnect_zosConnectAPIs element to server.xml and configurewhere API packages are stored.

Note: For information about deploying APIs with the Administration Interface, seeChapter 13, “Administering APIs,” on page 233.

A new element is added to server.xml, which defines the z/OS Connect EE APIsare to be deployed and, optionally, the APIs that are expected to be deployed. Forexample,<zosconnect_zosConnectAPIs location="/var/zosconnect/apis" updateTrigger="polled"><zosConnectAPI name="Health" /><zosConnectAPI name="Inventory" /><zosConnectAPI name="Ordering" /></zosconnect_zosConnectAPIs>

The server.xml configuration file can contain the following elements:

zosconnect_zosConnectAPIs

v Only one zosconnect_zosConnectAPIs element is allowed.v The location parameter is optional and specifies where the API

packages are deployed. If it is not defined, then the${server.config.dir}/resources/zosconnect/apis directory is used as


the API package installation directory. When the server is started, all theAPI packages in the location directory are deployed in the server.

Note: The server does not create the API package installation directory.If the directory does not exist, then APIs cannot be dynamicallydeployed by the API Editor or RESTful administration interface. Eitherchange the location to a directory that exists and restart the server, orcreate the required directories.

v The updateTrigger parameter is optional and controls when z/OSConnect EE is notified about changes in the apis directory. The apisdirectory is specified on the location parameter. For more information,see “Configuration elements” on page 283.

v You can use the nested zosConnectAPI elements to specify the APIs thatare expected to be in the location directory. If a defined API is not foundin the location directory, then a message is written to the log. If an APIpackage is invalid, then the API fails to load and an error is written tothe log.

Note: The zosconnect_zosConnectAPIs element cannot be changed whilethe server is running; its value is set when the server is started.

zosConnectAPI

v One or more zosConnectAPI elements can be contained in thezosconnect_zosConnectAPIs element.

v Supports other optional attributes that, for example, can be used todefine authentication, authorization, or interceptors specific to an API.For more information, see “Configuration elements” on page 283.

v The attributes adminGroup, invokeGroup, operationsGroup, readerGroup,requireAuth, and requireSecure are available to specify authenticationand authorization for an API. For more information, see Chapter 8,“Securing,” on page 177.

v The attributes interceptorsRef and runGlobalInterceptors are availableto specify interceptors for an API. For more information, see“Configuring API specific interceptors” on page 156.

Note: The zosConnectAPI element can be dynamically updated while theserver is running, provided the server is enabled for dynamicconfiguration. For more information about enabling the server for dynamicconfiguration, see Administering Liberty in the WebSphere Application ServerLiberty documentation.

Related information:Chapter 13, “Administering APIs,” on page 233Use this information to learn how to manage your APIs.

Configuring Cross-Origin Resource Sharing on a z/OS ConnectEnterprise Edition Server

z/OS Connect EE supports Cross-Origin Resource Sharing (CORS).

CORS is a mechanism that allows a resource to be requested from a differentdomain than the one from which the resource originated. Usually, clientapplications that support CORS send a preflight request before some certain


http://www.ibm.com/support/knowledgecenter/SSEQTP_liberty/com.ibm.websphere.wlp.nd.multiplatform.doc/ae/twlp_admin.html

cross-domain requests are sent. z/OS Connect EE servers are enabled to answerpreflight requests by using different methods depending on the different versionsof z/OS Connect EE.v If you are using z/OS Connect EE V2.0.2 or earlier, enable CORS and CORS

preflight checks by upgrading z/OS Connect EE to the latest version.v If you are using z/OS Connect EE V2.0.3, you do not need to manually enable

CORS preflight checks because z/OS Connect EE V2.0.3 is enhanced to supportthis function.

v For the latest version of z/OS Connect EE, CORS and CORS preflight checks areenabled by using the Liberty CORS function. When a server is created, a corselement is automatically added to the server.xml. The cors element defines theCORS settings for the URL being setup in the domain. The following excerptfrom the server.xml shows a sample definition of CORS element:<cors id="defaultCORSConfig"

domain="/"allowedOrigins="*"allowedMethods="GET, POST, PUT, DELETE, OPTIONS"allowedHeaders="Origin, Content-Type, Authorization"allowCredentials="true"maxAge="3600" />

For more information about customizing the cors element, see the topicConfiguring Cross-Origin Resource Sharing on a Liberty Server in the WebSphereApplication Server for z/OS Liberty Knowledge Center

Server configuration updates on demandA running z/OS Connect EE server uses information from various files that arestored in UNIX System Services.v Server configuration files.v Data transformation files, if any of your z/OS Connect EE services use

DataXForms.

If you need to modify, create or delete these files while the server is running, youcan use any one of these methods:1. Polling the files at regular intervals to check whether any changes were made

and update the server with the detected changes. Continuous polling uses CPUresources. This method can be useful in a development or test environment.

2. Disable dynamic updates. This method requires the server to be restarted topick up any changes.

3. Using an MBean to trigger an update on demand from the current file content.This method can be useful in a production environment.

The update mechanism is specified on the following server configuration elements:v Updates to the server configuration files are controlled by the config

configuration element. For more information, see Configuration Management(config) in the Reference section.

v Updates to data transformation files are controlled by thezosconnect_zosConnectDataXform configuration element. For more information,see “zosconnect_zosConnectDataXform” on page 312 in the Reference section.

v Updates to APIs are controlled by the zosconnect_zosConnectAPIs configurationelement. For more information, see “zosconnect_zosConnectAPIs” on page 309in the Reference section.


https://www.ibm.com/support/knowledgecenter/SS7K4U_liberty/com.ibm.websphere.wlp.zseries.doc/ae/twlp_webcontainer_cors_config.html

Using an MBean to trigger updatesAn MBean called the FileNotificationMBean is provided, which can be called totrigger an update of a running server.

The MBean can make the following updates to the server:v Use new, modified, or deleted configuration files.v Use new, modified, or deleted data transformation files.v Use new, modified, or deleted API archive files.

MBeans are invoked by using a Java Management Extensions (JMX) connector. Twosupported JMX connectors are available:v The local connector is enabled through the Liberty feature localConnector-1.0.

Access through the local connector is protected by the policy that isimplemented by the SDK in use. The client must run on the same host as theserver, and under the same user ID.

v The REST connector is enabled through the Liberty feature restConnector-1.0.Remote access through the REST connector is protected by a single administratorrole. In addition, SSL is required to keep the communication confidential.

You must configure the JMX connectors as described in the topics Configuringlocal JMX connection to Liberty or Configuring secure JMX connection to Libertyin the WebSphere Application Server documentation.

Note: If you intend to use the REST connector with SAF authentication, thefollowing steps are required.v Instead of following the link to the topic Map to the administrator role for Liberty,

see the alternative topic Mapping the administrator role for Liberty on z/OS.v Define the following RACF definitions (or equivalent definitions for your SAF

provider).RDEFINE APPL <SAF_profilePrefix> UACC(NONE) SETROPTS CLASSACT(APPL)PERMIT <SAF_profilePrefix> CLASS(APPL) ACCESS(READ) ID(<id>)

Where <id> is the user or group name of the SAF user ID you are grantingadministrator authority to, and <SAF_profilePrefix> is value of the profilePrefixattribute specified on the server configuration file element safCredentials. Thedefault profilePrefix value is BBGZDFLT.For more information, see Liberty: Accessing z/OS security resources usingWZSSAD in the WebSphere Application Server documentation.

MBeans can be called from java based client applications. For example, a Javaprogram, Jython script, or a REST API.

Invoking the FileNotificationMBean from a java programJavadoc for the FileNotificationMBean is provided in the file <installation_dir>/wlp/dev/api/ibm/javadoc/com.ibm.websphere.appserver.api.basics_1.2-javadoc.zip.

The following java code snippet provides an example of using the REST connectorto invoke the FileNotificationMBean method notifyFileChanges. This exampleupdates the running server configuration with changes that are made to either oftwo server configuration files: /var/zosconnect/servers/serverName/server.xmland /var/zosconnect/servers/serverName/includedConfig.xml.


http://www.ibm.com/support/knowledgecenter/en/SS7K4U_8.5.5/com.ibm.websphere.wlp.nd.doc/ae/twlp_admin_localconnector.html

http://www.ibm.com/support/knowledgecenter/en/SS7K4U_8.5.5/com.ibm.websphere.wlp.nd.doc/ae/twlp_admin_localconnector.html

http://www.ibm.com/support/knowledgecenter/en/SS7K4U_8.5.5/com.ibm.websphere.wlp.nd.doc/ae/twlp_admin_restconnector.html

http://www.ibm.com/support/knowledgecenter/en/SS7K4U_liberty/com.ibm.websphere.wlp.zseries.doc/ae/twlp_sec_mapadmin_zos.html

http://www.ibm.com/support/knowledgecenter/SS7K4U_8.5.5/com.ibm.websphere.wlp.zseries.doc/ae/rwlp_config_safCredentials.html

http://www.ibm.com/support/knowledgecenter/en/SS7K4U_liberty/com.ibm.websphere.wlp.zseries.doc/ae/rwlp_WZSSAD_zos.html

http://www.ibm.com/support/knowledgecenter/en/SS7K4U_liberty/com.ibm.websphere.wlp.zseries.doc/ae/rwlp_WZSSAD_zos.html

/** z/OS Connect server hostname */private final static String hostname = "companyhost.company.com";/** z/OS Connect server HTTPS port */private final static String httpsPort = "9443";/** z/OS Connect server administration role user */private final static String adminUserid = "adminUser";/** z/OS Connect server administration role user’s password */private final static String adminPassword = "adminPswd";/** Truststore containing z/OS Connect server’s public certificate */private final static String trustStoreLocation = "/mydir/trust.jks";/** Truststore password */private final static String trustStorePassword = "truststorePswd";/** Absolute paths of configuration files to monitor */private final static String configFilePath1 = "/var/zosconnect/servers/serverName/server.xml";private final static String configFilePath2 = "/var/zosconnect/servers/serverName/includedConfig.xml";

/** FileNotificationMBean name */private final static String MBEAN_FILE_NOTIFICATION = "WebSphere:service=com.ibm.ws.kernel.filemonitor.FileNotificationMBean";/** FileNotificationMBean method notifyFileChanges signature */private final static String[] MBEAN_FILE_NOTIFICATION_NOTIFYFILECHANGES_SIGNATURE = new String[] {

Collection.class.getName(),Collection.class.getName(),Collection.class.getName() };

/** JMX service URL*/private static String jmxServiceURL = "service:jmx:rest://" + hostname + ":" + httpsPort + "/IBMJMXConnectorREST";...public void invokeFileNotificationMBean() {...

// Get secure remote JMX MBean server connectionSystem.setProperty("javax.net.ssl.trustStore", trustStoreLocation);System.setProperty("javax.net.ssl.trustStorePassword", trustStorePassword);HashMap<String, Object> environment = new HashMap<String, Object>();environment.put("jmx.remote.protocol.provider.pkgs", "com.ibm.ws.jmx.connector.client");environment.put("com.ibm.ws.jmx.connector.client.disableURLHostnameVerification", Boolean.TRUE);environment.put(JMXConnector.CREDENTIALS, new String[] { adminUserid , adminPassword });JMXServiceURL url = new JMXServiceURL(jmxServiceURL);JMXConnector jmxConnector = JMXConnectorFactory.newJMXConnector(url, environment);jmxConnector.connect();MBeanServerConnection mbsc = jmxConnector.getMBeanServerConnection();

// Invoke FileNotificationMBeanObjectName fileMonitorMBeanName = new ObjectName(MBEAN_FILE_NOTIFICATION);if (mbsc.isRegistered(fileMonitorMBeanName)) {

// Create a list of absolute paths of each file to be checkedList<String> modifiedFilePaths = new ArrayList<String>();modifiedFilePaths.add(configFilePath1);modifiedFilePaths.add(configFilePath2);

// Set MBean method notifyFileChanges parameters (createdFiles, modifiedFiles, deletedFiles)Object[] params = new Object[] { null, modifiedFilePaths, null };

// Invoke FileNotificationMBean method notifyFileChangesmbsc.invoke(fileMonitorMBeanName, "notifyFileChanges", params,

MBEAN_FILE_NOTIFICATION_NOTIFYFILECHANGES_SIGNATURE);}else {

System.err.println("MBean invoke request failed " + MBEAN_FILE_NOTIFICATION + " is not registered.");}...

}

Note: The client-side REST connector, which is provided in wlp/clients/restConnector.jar, must be in the class path that is used to compile and run ajava application that invokes an MBean.


Invoking FileNotificationMBean from the REST APIMBeans can also be invoked by using a REST interface.

This method is described in the WASdev article Accessing Liberty’s JMX RESTAPIs. As described in that article, if the JMX Connector is installed, you can gethelp on the syntax that is required to invoke an MBean by making an HTTP GETcall to http://<hostname>:<port>/IBMJMXConnectorREST and selecting the MBeanoperation invocation and JSON grammar for POJO options from the menu.

The following instructions provide an example of using the REST API to invokethe FileNotificationMBean method notifyFileChanges. This example updates therunning server configuration with changes that are made to either of two serverconfiguration files: /var/zosconnect/servers/serverName/server.xml and/var/zosconnect/servers/serverName/includedConfig.xml.

Issue an HTTP POST request to http://<hostname>:<port>/IBMJMXConnectorREST/mbeans/WebSphere%3Aservice%3Dcom.ibm.ws.kernel.filemonitor.FileNotificationMBean/operations/notifyFileChanges with a HTTP header : Content-Type application/json and arequest JSON payload as in the following sample.

{"params":[

{"value" : [""],"type" : {"className":"java.util.ArrayList","items":["java.lang.String"]}

},{

"value" : ["/var/zosconnect/servers/serverName/server.xml","/var/zosconnect/servers/serverName/includedConfig.xml"],"type" : {"className":"java.util.ArrayList","items":["java.lang.String","java.lang.String"]}

},{

"value" : [""],"type" : {"className":"java.util.ArrayList","items":["java.lang.String"]}

}],"signature":[

"java.util.Collection","java.util.Collection","java.util.Collection"

]}

The FileTransferMBeanThe FileTransferMBean can be used to transfer your API archive files from aremote system to the z/OS Connect EE API location directory.

The FileTransferMBean contains methods that you can use to download, upload,or delete files on the z/OS Connect EE server instance. This MBean is available aspart of the restConnector-1.0 feature. Javadoc is provided in the file<installation_dir>/wlp/dev/api/ibm/javadoc/com.ibm.websphere.appserver.api.restConnector_1.1-javadoc.zip.

Note: To use this MBean, you must also define the remoteFileAccess serverconfiguration element attributes readDir and writeDir to define the directories towhich the restConnector within that server is authorized to read to and writefrom.

For more information about this element, see Remote File Access(remoteFileAccess) in the WebSphere Application Server documentation. For moreinformation about using this MBean, see the WASdev article Using File Service andFile Transfer MBeans with Liberty.


https://developer.ibm.com/wasdev/docs/accessing-libertys-jmx-rest-apis/

https://developer.ibm.com/wasdev/docs/accessing-libertys-jmx-rest-apis/

https://www.ibm.com/support/knowledgecenter/en/SS7K4U_liberty/com.ibm.websphere.wlp.zseries.doc/ae/rwlp_config_remoteFileAccess.html

https://www.ibm.com/support/knowledgecenter/en/SS7K4U_liberty/com.ibm.websphere.wlp.zseries.doc/ae/rwlp_config_remoteFileAccess.html

https://developer.ibm.com/wasdev/docs/using-file-service-and-file-transfer-mbeans-with-liberty/

https://developer.ibm.com/wasdev/docs/using-file-service-and-file-transfer-mbeans-with-liberty/

Chapter 7. High availability

The key concepts of a high availability (HA) environment and how they can beimplemented with z/OS Connect EE.

This information is aimed at architects and z/OS system programmers who needto implement a z/OS Connect EE HA environment. Implementation requires z/OSsystem programming skills, such as the use of TCP/IP workload balancingsoftware and creation of zFS file systems.

By implementing a high availability solution, you can minimize the impact ondaily operations of the failure of one or more components within the overallsystem. You can use various IBM or third-party products with z/OS Connect EE tobuild such a system. You have a number of options available so that you canchoose a solution that suits the needs of your organization. The solution might bejust two z/OS Connect EE servers that run in a single LPAR. Or you can design amore complex parallel sysplex solution with many z/OS Connect EE servers thatare spread across multiple LPARs.

It is also necessary to plan for variations in workloads, especially increasedworkloads, when it might be necessary to increase the capacity of the system. Thesystem must respond in a predictable way to workload variation to meet SLAs. Forz/OS Connect EE, scalability can be achieved by manually increasing the numberof servers.

High availability can be achieved with z/OS Connect EE by the workloaddistribution of HTTP and HTTPS API and service requests from clients acrossseveral servers with shared configuration. For more information, see “Workloaddistribution” and “Sharing server configuration” on page 170. To ensure thatworkload distribution can route requests to any configured z/OS Connect EEserver, the servers must be maintained as clones of each other. That is, the servershave the same configuration with the same z/OS Connect APIs and servicesdeployed.

Workload distributionA z/OS Connect EE HA environment can take advantage of TCP/IP loadbalancing technologies.

Requests to invoke APIs and services in z/OS Connect EE servers are made byusing HTTP, which means that an HA environment can use known TCP/IP loadbalancing technologies to distribute connections from clients across multipleservers.v TCP/IP port sharing can be used to load balance requests across multiple z/OS

Connect EE servers in the same z/OS LPAR.v Sysplex Distributor can be used to distribute requests across multiple z/OS

Connect EE servers in a Parallel Sysplex®. Used with TCP/IP port sharingwithin each LPAR.

By configuring the httpEndpoint in the server configuration file of multiple z/OSConnect EE servers to listen on the same shared TCP/IP port, clients can sendrequests to a single hostname and port and allow the TCP/IP load balancingtechnologies to distribute the request to one of the available servers. z/OS Connect


EE APIs and services have no persistent state and do not use HTTP sessions, so noaffinities exist between client applications and z/OS Connect EE servers,simplifying both workload distribution and the retry of failed requests.

TCP/IP port sharingThe TCP/IP port sharing component of the z/OS TCP/IP Communicationssubsystem allows multiple listeners to listen on the same combination of port andIP address.

Port sharing can be configured to distribute HTTP requests across multiple z/OSConnect EE servers in a single LPAR.

Shared ports are defined by the PORT statement in the TCP/IP profile. A sharedport definition reserves a specific port number to be shared by specific z/OSaddress space job names. Two options of the PORT statement control port sharing:

SHAREPORTRequests are distributed by a weighted round-robin distribution methodbased on the Servers' accept Efficiency Fractions (SEFs) of the listeners thatshare the port.

SHAREPORTWLMRequests are distributed based on WLM server-specific recommendations,which are modified by the SEF values for each listener. Load balancing canbe more efficient if you consider the status that is provided by dynamicfeedback from the z/OS Workload Manager (WLM).

When you configure port sharing for z/OS Connect EE, define shared ports forany ports that receive HTTP or HTTPS requests to invoke APIs or services. Forexample, the port values specified on the httpEndpoint element withid="defaultHttpEndpoint" in your server's configuration file. For multiple z/OSConnect EE server address spaces to share a port, their job names must start withthe same characters. It is the common portion of the job name that must bespecified on the PORT definition. For example, to uniquely identify two servers:1. Use the baqstrt.jcl started task procedure provided in /usr/lpp/zosconnect/

<version>/jcl.2. Specify the JOBNAME parameters as JOBNAME=ZCHA1 and

JOBNAME=ZCHA2. The common portion of the job name in this instance is"ZCHA".

Note: Use the JOBNAME parameter rather than an identifier for started tasks. SeeStarting a system task from a console in the z/OS MVS™ System Commandsdocumentation. If you choose to use identifiers, be aware that it is the commonportion of the identifier value that is used as the job name in the shared portdefinition.Related information:

Considerations for multiple servers sharing a TCP portin the z/OS Communications Server IP Configuration Guide.

TCP/IP profile (PROFILE.TCPIP) and configuration statementsin the z/OS Communications Server: IP Configuration Reference documentation.

PORT statementin the z/OS Communications Server: IP Configuration Reference documentation.


https://www.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.ieag100/skp1.htm

https://www.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.halz002/ip_multi_srvrs_share_tcp_port.htm

https://www.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.halz001/pro.htm

https://www.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.halz001/portstatement.htm

Sysplex distributorSysplex Distributor is the strategic IBM solution for connection workload balancingacross an IBM Parallel Sysplex.

Sysplex Distributor is a component of IBM z®/OS Communications Server andprovides TCP/IP load balancing across multiple LPARs. It can be combined withTCP/IP port sharing. Sysplex distributor is a combination of the high availabilityfeatures of distributed DVIPA and the workload optimization capabilities of WLM.The TCP/IP stacks can be configured to request workload information from WLM,enabling the distributing stack to forward those connections that are based on theworkload of each of the target stacks. The WLM workload information is based ona comparison of available general CPU capacity for each target system.

z/OS Connect EE is a Java based product, so it can use System z® IntegratedInformation Processor (zIIP) capacity. You can configure the TCP/IP stacks toconsider the available zIIP CPU capacity. You can also configure WLM-basedforwarding based on server-specific workload.Related information:

Configuring distributed DVIPAs — sysplex distributorin the z/OS Communications Server documentation.

Workload distribution between z/OS Connect EE servers andservice provider SORs

Workload distribution depends on a number of factors.

Whether you can distribute work between z/OS Connect EE servers and a serviceprovider system of record (SOR) depends on the service provider you are usingand the type of connection that is configured to the z/OS subsystem used for theSOR. If the service provider uses TCP/IP, then TCP/IP port sharing and or Sysplexdistributor might be appropriate.

The WOLA service provider has some restrictions:v Connections to SORs must be local within the same LPAR.v A single service can be connected to only one SOR. Currently, no options are

available to allow workload balancing or failover to an alternative SOR forWOLA connections from a Liberty profile-based server.

WLM ClassificationClassify HTTP traffic to improve workload distribution.

You can classify HTTP traffic in a z/OS Connect EE server so that it can bemanaged by z/OS workload management (WLM) along with other work in thesystem by enabling Liberty feature zosWlm-1.0. This identifies work byclassification rules and pass that into z/OS WLM for mapping to service classesand reporting classes. Different URIs can have different priority and performancecriteria. Classification of HTTP requests is based on host, port, method, andresource and is configured in the server configuration file.

A WLM enclave is associated with the thread that the request is dispatched on. Itis also associated with a WLM Service Class. A WLM Service Class is assigned tothe WLM enclave by WLM, based on rules that you define in the WLMconfiguration. The WLM Service Class indicates the WLM goals for each class ofclient work, for example, 95% complete in 1 second or less. The WLM Service

Chapter 7. High availability 169

https://www.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.halz002/vipa_sys_dist.htm

Class also indicates the importance of the goals relative to other work on thesystem. WLM uses information that is provided by the Liberty server duringclassification to assign a WLM Service Class.

In a high availability environment, you can specify the same value on the WLMNative Enclave Manager Configuration element for all your servers. For example,<zosWorkloadManager collectionName="<value>" />

This method allows the servers to use the same collection name in WLM, insteadof the default collection name, which is the server name for each server.Related information:

Enabling workload management for Liberty on z/OSin the WebSphere Application Server for z/OS documentation.

Sharing server configurationWorkload distribution across a group of servers that use a shared port requires thatthe same configuration is maintained across all servers.

To ensure that workload distribution can route requests to any of the availablez/OS Connect EE servers that use a shared port, the servers must have the sameAPIs and services available.

Note: Some minor systematic variations might exist. For example, in a solutionthat uses WOLA, where each z/OS Connect EE server is configured to use adifferent CICS region.

To avoid the need to manually edit multiple z/OS Connect EE server configurationfiles with the same content each time an update is required, you can share aconfiguration file between the z/OS Connect EE servers. Sharing a configurationfile simplifies administration and maintenance because only a single file needs tobe updated and ensures that all servers are using the same configuration. To use ashared a configuration file between servers, you must consider the followingaspects:v The mechanisms that allow server configuration to be split into multiple files.v Which configuration elements can be shared and which elements must be

server-specific.v Where to store the shared configuration file.

The following topics describe how to set up a shared configuration.

Splitting server configuration informationConfiguration elements that are common to all z/OS Connect EE servers can beincluded from a shared configuration file.

Each server must have a valid Liberty server configuration file that is calledserver.xml in its server configuration directory ${server.config.dir}. Thefollowing mechanisms can be used to split a server configuration file intoserver-specific content and content that is common to multiple servers:v Use include elements in server configuration files to include additional server

configuration files, in the format: <include location="pathname/filename"/>. Forexample, each server's configuration file might contain only those entries that


http://www.ibm.com/support/knowledgecenter/en/SS7K4U_liberty/com.ibm.websphere.wlp.zseries.doc/ae/twlp_wlmclassification.html

are specific to that server and specify an element to include anotherconfiguration file whose content is common to all servers.When you use include elements, be aware of the Liberty profile configurationelement merging rules. See Liberty:Configuration element merging rules in theWebSphere Application Server for z/OS documentation. Specify each element'sattribute in only one of the configuration files to ensure that only one valuetakes effect. For more information, see Using include elements in configurationfiles in the WebSphere Application Server for z/OS documentation.

v Use properties in server configuration files to enable an otherwise server-specificelement to be contained in the common server configuration file. Properties foreach server are defined in a file that is called bootstrap.properties in the serverconfiguration directory ${server.config.dir}. The properties are defined in theformat of name=value pairs that are written one line per property. For example,propertyName=propertyValue. Server configuration files can reference theseproperties by using the syntax: ${propertyName}.For example, for two servers to specify unique three part names for WOLA, theconfiguration file contains the following statements.– server1 has a bootstrap.properties file with the following content:

- wola_dgn=ZC1DGN- wola_ndn=ZC1NDN- wola_svn=ZC1SVN

– server2 has a bootstrap.properties file with the following content:- wola_dgn=ZC2DGN- wola_ndn=ZC2NDN- wola_svn=ZC2SVN

A shared configuration file might then specify the element by using theseproperties:<zosLocalAdapters wolaGroup="${wola_dgn}" wolaName2="${wola_ndn}" wolaName3="${wola_svn]" />

Note: If you update the bootstrap.properties file, you must restart the serverfor the changes to take effect. For more information, see Using variables inconfiguration files in the WebSphere Application Server for z/OS documentation.

Server-specific configuration elementsWhether configuration elements are common or server specific depends on yourenvironment, APIs, and service providers.

When you use the WOLA service provider, the three part name is derived from thewolaGroup, wolaName2, and wolaName3 attribute values on the local adapter'sconfiguration element zosLocalAdapters. This three part name must be unique foreach server in the same z/OS LPAR.

Location of shared configuration filesA shared configuration file must be stored in a location that can be read by allservers.

It is good practice to use the Liberty profile's shared directory structure. Theshared.config.dir property specifies the location <WLP_USER_DIR>/shared/config.You can use this property name within your server configuration file. By defaultthe value of WLP_USER_DIR is /var/zosconnect, so this location might not besuitable if you want to use shared zFS in a Parallel Sysplex, because the /varmount point cannot be shared. However, you can customize the value of the


http://www.ibm.com/support/knowledgecenter/SS7K4U_liberty/com.ibm.websphere.wlp.zseries.doc/ae/cwlp_confg_element_merging_rule.html

http://www.ibm.com/support/knowledgecenter/SS7K4U_liberty/com.ibm.websphere.wlp.zseries.doc/ae/twlp_setup_includes.html

http://www.ibm.com/support/knowledgecenter/SS7K4U_liberty/com.ibm.websphere.wlp.zseries.doc/ae/twlp_setup_includes.html

http://www.ibm.com/support/knowledgecenter/SS7K4U_liberty/com.ibm.websphere.wlp.zseries.doc/ae/twlp_setup_vars.html

http://www.ibm.com/support/knowledgecenter/SS7K4U_liberty/com.ibm.websphere.wlp.zseries.doc/ae/twlp_setup_vars.html

WLP_USER_DIR environment variable before you install z/OS Connect EE. Formore information, see “Installing z/OS Connect EE” on page 112.

In a single LPAR, a UNIX System Services directory that is not in the${server.config.dir} directory structure can be used so that it is not nested in thedirectory structure of a single server.

In a Parallel Sysplex, you can mount a shared zFS to share a single configurationfile between multiple servers. For more information about using shared zFS in aParallel Sysplex, see z/OS File System overview. You can further improve theresilience of these file systems by using RAID arrays and DASD mirroringtechnologies. Alternatively, you can share configuration files only among theservers in each LPAR and maintain separate physical copies of the file on eachLPAR. These files must be kept in sync manually.Related information:

Customizing the Liberty environmentin the WebSphere Application Server for z/OS

Liberty:Directory locations and propertiesin the WebSphere Application Server for z/OS

Maintenance of API and service deploymentsWorkload distribution requires z/OS Connect EE servers to be kept in sync.

To enable workload distribution across a group of servers, the servers must havethe same APIs and services deployed. Any changes to those APIs or services mustbe reflected across all the servers that participate in the shared workload.

APIs are deployed to a location directory that is specified by the location attributeof the zosconnect_zosConnectAPIs element. By default, this attribute contains theserver-specific directory ${server.config/dir}/resources/zosconnect/apis.Storing the API archive files in a single directory that is shared by all serversensures that the same versions of all APIs are available in all servers.

Files that are associated with Services can also be stored in UNIX System Servicesdirectories, depending on the service provider they use. For example, the WOLAservice provider uses the supplied DataXForm to transform JSON payload to bytes.This service requires WSbind files and JSON schema files whose locations arespecified to the zosconnect_zosConnectDataXform server configuration element.Choosing to store all the service files in directories that are shared by all theservers ensures that the same versions of all services are available in all servers.

Deciding where to store the API and service files.

The API location directory and any directories that contain service files must bestored in a location that all servers have read and write access to.

It is good practice to use of the Liberty profile's shared directory structure. Theshared.resource.dir property specifies the location $WLP_USER_DIR/shared/resources. You can use this property name within your server configuration file.You can choose to create nested subdirectories within this directory that areappropriate for your APIs and service artifact files.


http://www.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.ioea700/ioea7d001998602.htm

http://www.ibm.com/support/knowledgecenter/en/SS7K4U_liberty/com.ibm.websphere.wlp.zseries.doc/ae/twlp_admin_customvars.html

http://www.ibm.com/support/knowledgecenter/en/SS7K4U_liberty/com.ibm.websphere.wlp.zseries.doc/ae/rwlp_dirs.html

For more information about storing shared files, see “Location of sharedconfiguration files” on page 171.

Administration and Operation Tasks in an HA environmentIn an HA environment, administration and operation tasks require furtherconsiderations.

Stopping and starting z/OS Connect EE servers in an HAenvironment

There are some things you must consider when stopping or starting a z/OSConnect EE server

When a server is shutdown, the order of events causes the z/OS Connect EE APIsand services to become unavailable while the HTTP and HTTPS ports are stillenabled. This can result in the client application receiving HTTP response code 404(Not Found).

To avoid this situation, you can disable the HTTP ports before shutting down theserver by setting the enabled attribute on the httpEndpoint configuration element tofalse. As soon as the endpoint is disabled, TCP/IP port sharing will no longerroute work to that server, until the httpEndpoint is re-enabled.

Note: If the httpEndpoint element is defined in a shared configuration file, youwill need to override the attribute definition to specify the enabled attributeuniquely in each server, so that you can control the value per server. For example,add the following entry to the server.xml files used by each server.

<httpEndpoint id="defaultHttpEndpoint" enabled="true" />

When a server is started, its HTTP ports may be enabled before all the z/OSConnect EE APIs and services are started. In a HA environment, with an activeworkload, requests could be distributed to the starting server before it is fullyinitialized. A similar approach could be used to start the server with thehttpEndpoint initially disabled and then update the configuration to enable it oncethe server startup has completed.

Management of z/OS Connect EE APIs and services in an HAenvironment

Considerations for querying, starting, stopping, deploying, updating, andundeploying APIs and services in an HA environment

z/OS Connect EE provides an administration interface for services, and a RESTfuladministration interface for APIs. See “The z/OS Connect EE administrationinterface” on page 245 and “Using the RESTful administration interface” on page235. These administration interfaces connect to the HTTP or HTTPS port of a z/OSConnect EE server and provide various functions such as:v Listing currently deployed APIs and services and retrieving details of an

individual API or service.v Stopping and starting individual APIs or services.v Deploying, updating, or undeploying an API.

In an HA environment, HTTP, and HTTPS requests are targeted at a single hostname and port but are then distributed across multiple servers when those serversuse TCP/IP port sharing, Sysplex Distributor or both. Routing of an administrationrequest cannot be guaranteed. Therefore, in an HA environment, administration, oroperation actions through HTTP administration interfaces cannot be targeted ateither a specific server or to all of the servers.

Querying APIs and services

If all the servers in a high availability group are configured with the same APIsand services, then a shared HTTP or HTTPS port can still be used to retrievedetails of currently deployed APIs and services, because any server can return thesame information. However, it is not possible to determine the API and servicestatus on any particular server. In that case, a second httpEndpoint can beconfigured as described below.

Starting and stopping APIs and services

To start or stop an individual API or service and to retrieve definitive deploymentand status information from individual servers in an HA environment, configure asecond httpEndpoint element in server.xml to specify an additional HTTP andHTTPS port pair for each server. These ports must be unique for each server andnot shared. They are used only for the RESTful Administration interfaceadministration and operation requests. Requests to invoke APIs and servicescontinue to use the shared ports so that those requests are distributed across theservers.

For example, add the following entry into each server's server.xml file:<httpEndpoint id="operationsHttpEndpoint" host="*" httpPort="<unique_http_port>" httpsPort="<unique_https_port>" />

Note:

1. In a production environment, you might restrict this administration endpoint torequire SSL. By default, an httpEndpoint server configuration element uses theserver's default SSL configuration, an ssl element with id=defaultSSLConfig.However, if you want to use different SSL certificates to protect requests overthis administration endpoint, you can associate this endpoint with a differentSSL configuration. For more information, see the Configuring an httpEndpointto use an SSL configuration other than the default.

2. Requests received on either httpEndpoint are authenticated against the samez/OS Connect EE roles that are defined in your configured security repository.For more information, see “Overview of z/OS Connect EE security” on page177.

Deploying APIs

If the RESTful Administration interface is used to deploy, update, or undeployAPIs to a location directory that is shared by multiple servers then the time atwhich the change to the API takes effect in each server is unpredictable. This isbecause the server that the administration request is distributed to immediatelyimplements the change to the API in its runtime and the API archive file isupdated in the location directory. However, the other servers reflect the change tothe API only when they refresh their API information, as specified by theupdateTrigger attribute specified on zosconnect_zosConnectAPIs serverconfiguration element. For more information, see “zosconnect_zosConnectAPIs” onpage 309.


http://www.ibm.com/support/knowledgecenter/SS7K4U_8.5.5/com.ibm.websphere.wlp.zseries.doc/ae/twlp_sec_ssl_endpoint.html

http://www.ibm.com/support/knowledgecenter/SS7K4U_8.5.5/com.ibm.websphere.wlp.zseries.doc/ae/twlp_sec_ssl_endpoint.html

A better alternative in an HA environment is to deploy or update APIs by copyingor FTPing the archive files in binary mode to a single location directory that isshared by all servers. Similarly, an API archive file can be deleted from the locationdirectory so that new, updated, or deleted APIs are reflected on all servers at thesame time. The change to the API archive file again takes effect in the runningservers based on the updateTrigger attribute that is specified onzosconnect_zosConnectAPIs server configuration element.

When run in production, an mbean trigger is preferable to a polled trigger forperformance reasons.

Deploying services

To deploy, update, or undeploy services in an HA environment, use the standardLiberty functions appropriate for your service provider.

Updates to the server configuration file can be made to the common sharedconfiguration file and take effect dependent on the updateTrigger attribute that isspecified on the config server configuration element. For more information, seeConfiguration Management (config) in the Reference section.

If your z/OS Connect EE services use DataXForms, then creation, modification, ordeletion of the data transformation files in the UNIX System Services directory canbe updated based on the updateTrigger attribute that is specified on thezosconnect_zosConnectDataXform server configuration element. For moreinformation, see “zosconnect_zosConnectDataXform” on page 312.

Note: If you specify the updateTrigger attribute value of mbean on any of theapplicable server configuration elements, then you must also configure your serverto use the Java Management Extensions (JMX) connector, for more information see“Using an MBean to trigger updates” on page 163.


Chapter 8. Securing

Connections to the server can be secured through user authority roles. Access toapplications can be configured at different levels. For z/OS Connect EE to usez/OS authorized services, the Liberty angel process must be configured.

Overview of z/OS Connect EE securityz/OS Connect EE provides user authority roles and the ability to configure SSLconnections, so that you can secure access to your server.

Levels of user authority

You can set the authority level of a user to perform actions on APIs and servicesaccording to the security credentials provided with requests.

Note: A user must be a member of a global admin group to be able to see all theresources by using the URI ../zosConnect/(services | apis). If a user is amember of a specific resource, then that user has authorization only to that specificresource and must use the URI ../zosConnect/(services | apis)/(<serviceName> | <apiName>).

z/OS Connect EE supports four levels of authority:

AdministratorFor a user with Administrator authority, all z/OS Connect EE actions areallowed, including all Operator, Invoke, and Reader actions.

OperatorA user with Operator authority is able to request all z/OS Connect EEoperations and actions except for invoke. These actions include deploying,updating, querying and deleting APIs, querying services and requestingaction=start, stop, status, getRequestSchema, getResponseSchema andgetStatistics for services.

InvokeA user with Invoke authority is able to request action=invoke for theservice or use the invokeURI parameter on the z/OS Connect EE servicedefinition. Such users can also invoke APIs. Permission for Invoke does notprovide access to z/OS Connect EE operations.

ReaderA user with Reader authority is able to read the Swagger document, accessand import the API, read a list of all APIs and services, and get detailedinformation. A user with Reader authority is not authorized to requestactions that are permitted for users with Operator or Invoke authority.

z/OS Connect EE supplies an authorization interceptor that implements thecom.ibm.zosconnect.spi.Interceptor SPI, and supports both SAF and LDAP. Thisinterceptor uses the getGroupsforUser() security API internally to determine whichgroups the current user is in, and then compares these groups to the groupsprovided in the API definition, service definition, or global definition. Theauthorization interceptor can be enabled using either the globalInterceptorsRefattribute on the zosConnectManager element or, for a specific API or service, theinterceptorsRef attribute on the zosConnectAPI or zosConnectService element.


Any zosConnectAPI or zosConnectService element which does not specifyrunGlobalInterceptors="false" will run all of the global interceptors in additionto any it specifies.

When the z/OS Connect EE supplied authorization interceptor is enabled, theRACF or LDAP user registry group names that are associated with users can alsobe associated with any of the groups that are mentioned previously at the global,API, or service definition levels. At the global level, they can be defined under thezosConnectManager configuration element. The attributes that are defined at thislevel include: globalAdminGroup, globalOperationsGroup, globalInvokeGroup, andglobalReaderGroup. If configured, they apply to all configured APIs and services. Ifmore granularity is needed, the groups can also be configured at the API or servicelevel under the zosConnectAPI or zosConnectService configuration element. Theattributes that are defined at that level are: adminGroup, operationsGroup,invokeGroup, and readerGroup. These values, if specified, override the values thatare defined globally.

When an authorization interceptor is defined at the global level, authorizationchecks are done once for all services. When you use /zosConnect/operations/getStatistics request for more than one service and service discovery, the usergets information on all services that are registered with z/OS Connect EE when thefollowing conditions exist:v The user passes the authorization checkv No other conditions prevent service information from being returned

When an authorization interceptor is defined at the global level, and a user ineither the globalAdminGroup or globalOperationsGroup requests /zòsConnect/apisto get a list of APIs, the returned list contains all installed APIs, regardless of thegroups specified on the zosConnectAPI element.

If the authorization interceptor is placed in an API level definition, either explicitlyusing the interceptorsRef attribute, or implicitly using therunGlobalInterceptors="true" attribute, access to information for that API islimited to users that are in the groups specified on that API definition.

For example:

A user in the adminGroup on the zosConnectAPI element, or, if omitted, in theglobalAdminGroup on the zosConnectManager element is authorized to:v Perform all the actions described below for operationsGroup and invokeGroup.

A user in the operationsGroup on the zosConnectAPI element, or, if omitted, in theglobalOperationsGroup on the zosConnectManager element is authorized to:v Get details of that APIv Get the Swagger document for that APIv Deploy an APIv Update an APIv Delete an API

A user in the invokeGroup on the zosConnectAPI element, or, if omitted, in theglobalInvokeGroup on the zosConnectManager element is authorized to:v Invoke the API


A user in the readerGroup on the zosConnectAPI element, or, if omitted, in theglobalReaderGroup on the zosConnectManager element is authorized to:v Read the Swagger document.v Access and import the API.v Read a list of all APIs and services.v Get detailed information on APIs and services.

If the authorization interceptor is placed in a service level definition, access toinformation for those services are limited to users that are in that servicedefinition.

For example, given the following configuration with the authorization interceptordefined at the service level:

User "USR1" is in groups: ADMINS1, ADMINS2

User "USR2" is in groups: OPERATS1

User "USR3" is in groups: ADMINS2, OPERATS1

z/OS Connect EE configuration:<zosconnect_zosConnectManager globalAdminGroup="ADMINS1"globalOperationsGroup="OPERATS1"/>

Service 1:<zosconnect_zosConnectService adminGroup="ADMINS2"operationsGroup="OPERATS2"interceptorsRef="interceptorList1"/>

Service 2:<zosconnect_zosConnectService operationsGroup="OPERATS2"interceptorsRef="interceptorList1"/>

Service 3:<zosconnect_zosConnectService adminGroup="ADMINS1"interceptorsRef="interceptorList1"/>

Where interceptorList1 is defined as follows:<zosconnect_zosConnectInterceptors id="interceptorList1"interceptorRef="zosConnectAuthorizationInterceptor"/>

<zosconnect_authorizationInterceptorid="zosConnectAuthorizationInterceptor"/>

Given the previous service/group configuration and user/group allocation, thefollowing table is what each user can see if a discovery request is issued:

service1 service2 service3

USR1 X X X

USR2 -- -- X

USR3 X -- X

Chapter 8. Securing 179

Requesting SSL and Authentication

You can secure communications between a client and the z/OS Connect EE serverusing the Secure Sockets Layer (SSL) protocol.

In the server.xml configuration file, the zosConnectManager, zosConnectAPI andzosConnectService elements all support the following attributes:

requireSecureRequires that requests are sent over HTTPS. This is a boolean value, thedefault value is true.

requireAuthRequires that users specify security credentials in order to be authenticatedwhen calling the URI. This is a boolean value. The default value is true.

The value specified on the zosConnectManager element applies to all configuredAPIs and services, unless an individual zosConnectAPI or zosConnectServiceelement explicitly specifies a different value. For example, both of the followingserver.xml entries are equivalent and indicate that requests must be sent overHTTPS, and that users must specify security credentials. The first example uses thedefault values:<zosconnect_zosConnectManager />

The second example explicitly specifies the attributes:<zosconnect_zosConnectManager requireSecure="true" requireAuth="true" />

The following server.xml entry indicates that requests to service testService canbe sent over HTTP, and that user security credentials are not required:<zosconnect_zosConnectService id="testService" serviceName="testService"serviceRef="refTestService" invokeUri="/test"requireSecure="false" requireAuth="false" />

With z/OS Connect EE API Editor V2.0.4.5 or later, you can set up clientauthentication in the API Editor to establish connections to the server, and use theseparate user ID for authorization based on the defined security role.Related tasks:“Configuring client certificates for server connections” on page 217Generate a client certificate and configure the Eclipse preferences to send in thecertificate from the API Editor to the z/OS Connect EE server. On the server side,import the client certificate into the server truststore and disable failover to basicauthentication.

Configuring security for z/OS Connect EEThe z/OS Connect EE application can be accessed by authenticated users that arealso authorized under the zosConnectAccess role. You can configure groupauthorization at the global, API, or service definition level. Group authorization issupported for basic, SAF, and LDAP user registries.

By default, the z/OS Connect EE application requires users to be authenticated.Authentication is controlled by the requireAuth attribute on thezosconnect_zosConnectManager, zosConnectAPI, and zosconnect_zosConnectServiceelements of the server.xml configuration file. The default value is true. Setting thisvalue to false removes the requirement for users to be authenticated.


Note: A user must be a member of a global admin group to be able to see all theresources by using the URI ../zosConnect/(services | apis). If a user is amember of a specific resource, then that user has authorization only to that specificresource and must use the URI - ../zosConnect/(services | apis)/(<serviceName> | <apiName>).

By default, the z/OS Connect EE application requires an SSL connection from theclient. It also defaults to client authentication. The SSL connection is controlled bythe requireSecure attribute on the zosconnect_zosConnectManager, zosConnectAPI,and zosconnect_zosConnectService elements of the server.xml configuration file.The default value is true. However, this value can be set to false to remove therequirement for an SSL connection. If SSL is enabled, you can also use basicauthentication instead of client authentication.

If authentication and authorization are enabled, the security features must beenabled, and users must be defined in a user registry and authorized under thezosConnectAccess role. The steps that are required to configure thezosConnectAccess role depends on your chosen user registry.

Note: At least one user registry must be defined even if authentication andauthorization are not enabled

If SSL is enabled, the SSL feature must be selected and SSL keystores andtruststores must be configured.

z/OS Connect EE supports both SSL and user authentication by using the supportthat is provided in the Liberty profile.

For instructions on configuring a z/OS Connect EE server to provide securecommunications between a client and the server that uses SSL, see the Libertyprofile topic Securing communications with Liberty

For instructions on configuring a z/OS Connect EE server to use a (Basic, LDAP orSAF) user registry to authenticate a user and determine their level of authorization,see the Liberty profile topic Configuring a user registry in Liberty.

You can use System Authorization Facility (SAF), for example, by using RACF tosecure your z/OS Connect EE server. To use SAF, or to take advantage of otherz/OS authorized services such as Workload Manager (WLM), Resource Recoveryservices (RRS), or SVCDUMP, you must set up a Liberty angel process and grantaccess for your Liberty profile server to use these services. For more information,see Enabling z/OS authorized services on Liberty for z/OS in the WebSphereApplication Server for z/OS documentation.

The following tasks describe how to configure a z/OS Connect EE server to requirebasic authentication and an SSL connection, that use either basic or SAF userregistries.

Configuring security with a basic user registryConfigure group authorization at the global, API, or service definition level byusing a basic user registry. Group authorization is also supported for SAF andLDAP user registries.


http://www.ibm.com/support/knowledgecenter/en/SS7K4U_liberty/com.ibm.websphere.wlp.zseries.doc/ae/twlp_sec_comm.html

http://www.ibm.com/support/knowledgecenter/en/SS7K4U_liberty/com.ibm.websphere.wlp.zseries.doc/ae/twlp_sec_registries.html

http://www.ibm.com/support/knowledgecenter/SS7K4U_liberty/com.ibm.websphere.wlp.zseries.doc/ae/twlp_config_security_zos.html

About this task

In this task, you configure a z/OS Connect EE server to require basic userauthentication and an SSL connection, by using a basic user registry.

To set up client certificate authentication, see the documentation on configuringyour web application and server for client certificate authentication in the Libertyprofile.

Procedure1. Set up SSL and user authentication to access the z/OS Connect EE application.

Sample 1. Basic user registry configuration.<featureManager><feature>zosconnect:zosconnect-2.0</feature><feature>ssl-1.0</feature><feature>appSecurity-2.0</feature></featureManager>

<ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" trustStoreRef="defaultTrustStore" clientAuthentication="false" />

<keyStore id="defaultKeyStore" password="zosconnect"/>

<keyStore id="defaultTrustStore" password="zosconnect"/>

<webAppSecurity allowFailOverToBasicAuth="true"/>

<basicRegistry id="basic1" realm="zosConnect"><user name="Fred" password="fredpwd"/></basicRegistry>

2. Set up user authorization to access the z/OS Connect EE application byassigning users the zosConnectAccess role.Sample 2. Authorization configuration with a basic user registry.<authorization-roles id="zos.connect.access.roles"><security-role name="zosConnectAccess"><user name="Fred"/></security-role>

</authorization-roles>

3. Optional: Define authorization groups for use with the authorizationinterceptor for z/OS Connect EE. If required, define additional users andgroups in the basic user registry definition you created in step 1. For example,add user Fred to the OPERATS1 group:Sample 3. Group definition with a basic user registry.<basicRegistry id="basic1" realm="zosConnect"><user name="Fred" password="fredpwd"/><group name="OPERATS1"><member name="Fred" /></group>

</basicRegistry>

The OPERATS1 group can then be used when you define authorization groups tobe used by the authorization interceptor for z/OS Connect EE. For example:

<zosconnect_authorizationInterceptor id="authInterceptor1" sequence="1"/>

<zosconnect_zosConnectInterceptors id="InterceptorList" interceptorRef="authInterceptor1"/>

Then define the interceptor list and the OPERATS1 group at the appropriatescope. For example:

<zosconnect_zosConnectManager globalOperationsGroup="OPERATS1" globalInterceptorsRef="InterceptorList"/>

or<zosConnectAPI name="api1" operationsGroup="OPERATS1" interceptorsRef="InterceptorList"/>

or<zosconnect_zosConnectService serviceRef="service1" operationsGroup="OPERATS1" interceptorsRef="InterceptorList"/>

Configuring security with SAF registriesConfigure group authorization at the global, API, or service definition level byusing SAF registries. Group authorization is also supported for basic user andLDAP user registries.

About this task

In this task, you configure a z/OS Connect EE server to require basicauthentication and an SSL connection, for a SAF user registry.

To set up client certificate authentication, see the documentation on configuringyour web application and server for client certificate authentication in the Libertyprofile.

Procedure1. Set up SSL and user authentication to access the z/OS Connect EE application.

Sample 1. SAF registry configuration.<featureManager><feature>zosconnect:zosconnect-2.0</feature><feature>ssl-1.0</feature><feature>appSecurity-2.0</feature><feature>zosSecurity-1.0</feature>

</featureManager>


<keyStore id="defaultKeyStore" password="zosconnect"/>


<webAppSecurity allowFailOverToBasicAuth="true"

<safRegistry id="saf" realm="zosConnect"/>

Create RACF definitions. For more details, follow the instructions in the Libertydocumentation Accessing z/OS security resources using WZSSAD. The value ofthe profilePrefix attribute is specified on the server configuration file element


https://www.ibm.com/support/knowledgecenter/SSEQTP_liberty/com.ibm.websphere.wlp.zseries.doc/ae/rwlp_WZSSAD_zos.html

safCredentials. The default value is BBGZDFLT. In this example, a value ofMYPROFIL is used, but you need to substitute your own value.

# Define the APPL class based on the default security prefix called MYPROFIL.RDEFINE APPL MYPROFIL UACC(NONE)

# Activate the APPL class.SETROPTS CLASSACT(APPL)

# For FRED to be authenticated by the server, assign FRED READ access to the APPLID in the APPL class.PERMIT MYPROFIL ID(FRED) ACCESS(READ) CLASS(APPL)

# The unauthenticated user ID (i.e. WSGUEST by default) requires READ access to the APPLID in the APPL classPERMIT MYPROFIL CLASS(APPL) ACCESS(READ) ID(unauthenticatedUserId)

# Grant the server permission to make authentication calls.RDEFINE SERVER BBG.SECPFX.MYPROFIL UACC(NONE)PERMIT BBG.SECPFX.MYPROFIL ID(serverId) ACCESS(READ) CLASS(SERVER)

Note: The server needs to have permission to use the SAFCRED authorizedservice routines. See “Configuring the Liberty angel process and z/OSauthorized services” on page 185.

2. Set up user authorization to access the z/OS Connect EE application byassigning users the zosConnectAccess role.a. Update the configuration file to add the safAuthorization element. For

example,Sample2. Authorization configuration using SAF/RACF.

<featureManager><feature>zosconnect:zosconnect-2.0</feature><feature>ssl-1.0</feature><feature>appSecurity-2.0</feature><feature>zosSecurity-1.0</feature></featureManager>


<keyStore id="defaultKeyStore" password="Liberty"/>


<webAppSecurity allowFailOverToBasicAuth="true"

<safRegistry id="saf" realm="zosConnect"/><safAuthorization id="saf2" />

b. Create RACF definitions.Enter the following commands to assign FRED the zosConnectAccess role:RDEFINE EJBROLE MYPROFIL.zos.connect.access.roles.zosConnectAccessUACC(NONE)PERMIT MYPROFIL.zos.connect.access.roles.zosConnectAccessCLASS(EJBROLE) ID(FRED) ACCESS(READ)

The value of the profilePrefix attribute is specified on the serverconfiguration file element safCredentials. The default value is BBGZDFLT.In this example, a value of MYPROFIL is used, but you need to substituteyour own value.

3. (Optional) Define authorization groups for use with the authorizationinterceptor for z/OS Connect EE. If required, define more users and groups inthe in the SAF registry. For example, to add user Fred to the OPERATS1 group:Sample 3. RACF Group definition for use with SAF.

ADDGROUP OPERATS1 OMVS(GID(xxx)) OWNER(xxxx)

# Add user FRED under the OPERATS1 groupADDUSER FRED DFLTGRP(OPERATS1) OMVS(UID(xxx) HOME(/xxxx) PROGRAM(/bin/sh)) NAME(’USER FRED’) NOPASSWORDALTUSER FRED PASSWORD(xxxxxxx) NOEXPIRED

# Connect user Fred to the OPERATS1 groupCONNECT FRED GROUP(OPERATS1)

The OPERATS1 group can then be used when defining authorization groups to beused by the authorization interceptor for z/OS Connect EE. For example:<zosconnect_authorizationInterceptor id="authInterceptor1" sequence="1"/>

<zosconnect_zosConnectInterceptors id="InterceptorList" interceptorRef="authInterceptor1"/>

Then define the interceptor list and the OPERATS1 group at the appropriatescope. For example:

<zosconnect_zosConnectManager globalOperationsGroup="OPERATS1" globalInterceptorsRef="InterceptorList"/>

or<zosConnectAPI name="api1" operationsGroup="OPERATS1" interceptorsRef="InterceptorList"/>

or<zosconnect_zosConnectService serviceRef="service1" operationsGroup="OPERATS1" interceptorsRef="InterceptorList"/>

Configuring the Liberty angel process and z/OS authorized servicesYou need to configure the Liberty angel process so that z/OS Connect EnterpriseEdition can use z/OS authorized services.

About this task

To use z/OS authorized services such as WebSphere Optimized Local Adapters(WOLA), System Authorization Facility (SAF), Workload Manager (WLM), resourcerecovery services (RRS), or SVCDUMP, you must set up a Liberty angel processand grant access for your z/OS Connect EE server to use these services. TheLiberty profile angel process must be run as a started task, but is lightweight, hasno configuration or TCP ports, and consumes almost no CPU when running.

To create the angel process started task you must customize the sample JCL andcreate SAF definitions to associate the started task with a userid and permit yourz/OS Connect EE server to use the z/OS authorized services. The followingexamples use RACF commands.

Note: Each LPAR can have only one angel process. Ensure that the angel processis running at the latest installed level of Liberty on the LPAR. If a Liberty serverinstance that is embedded in z/OS Connect EE server connects to an angel processthat is running at an earlier service level, some features of the server might not beavailable.

Procedure1. Create the JCL start procedure for the angel process.

a. Open a Telnet or ssh session to your z/OS system UNIX System Services.b. Copy the sample JCL from z/OS Connect EE installation directory to your

z/OS PROCLIB:cp <installation_dir>/wlp/templates/zos/procs/bbgzangl.jcl "//’<PROCLIB>(BBGZANGL)’"

For example:cp /usr/lpp/IBM/zosconnect/v2r0/wlp/templates/zos/procs/bbgzangl.jcl "//’USER.PROCLIB(BBGZANGL)’"

c. Customize the sample JCL by updating the SET ROOT value to your z/OSConnect EE installation directory. For example:SET ROOT=’/usr/lpp/IBM/zosconnect/v2r0/wlp’

In the following steps, work with your security administrator to create thenecessary authorizations and artifacts for the angel process to run as a started taskand to permit your z/OS Connect EE server to use z/OS authorized services.2. Started tasks must be associated with a userid. If you do not have a suitable

userid, use the following commands to create a new userid and group. Forexample: to define a userid called angel_id in a group called admin_group, yoursecurity administrator needs to enter the following commands:

ADDGROUP admin_group OMVS(GID(gid))ADDUSER angel_id DFLTGRP(admin_group) OMVS(UID(uid)HOME(/u/angel_id) PROGRAM(/bin/sh)) NAME('Liberty angel')

NOPASSWORD NOOIDCARD

3. Grant the required SAF authorization to associate the userid with the startedtask. For example:

RDEF STARTED BBGZANGL.* UACC(NONE) STDATA(USER(angel_id)GROUP(admin_group) PRIVILEGED(NO) TRUSTED(NO)

TRACE(YES)SETROPTS RACLIST(STARTED) REFRESH

4. Create a set of SAF SERVER profiles to grant your z/OS Connect EE serverauthority to use the required z/OS authorized services.a. Define the following SAF SERVER profiles, if they do not already exist.

Grant your z/OS Connect EE server userid READ access to each, by issuingthe following commands where server_id is the userid used to run the z/OSConnect EE server started taskAlternatively, you may choose to permit access at a group level, in whichcase replace server_id with the name of the group. The userid used to runthe z/OS Connect EE server started task must be connected to this group:

Note: To use WebSphere Optimized Local Adapters (WOLA) you need todefine and permit access to the SERVER profiles for: BBG.ANGEL,BBG.AUTHMOD.BBGZSAFM, BBG.AUTHMOD.BBGZSAFM.LOCALCOM,BBG.AUTHMOD.BBGZSAFM.WOLA, BBG.AUTHMOD.BBGZSCFM andBBG.AUTHMOD.BBGZSCFM.WOLA.v SERVER profile for the angel process to allow server access to the angel

process:

RDEF SERVER BBG.ANGEL UACC(NONE)PERMIT BBG.ANGEL CLASS(SERVER) ACCESS(READ) ID(server_id)


v SERVER profile for the authorized module BBGZSAFM to allow serveraccess to z/OS Authorized services:

RDEF BBG.AUTHMOD.BBGZSAFM UACC(NONE)PERMIT BBG.AUTHMOD.BBGZSAFM CLASS(SERVER)ACCESS(READ) ID(server_id)

v SERVER profiles for the optimized local adapter authorized service:

RDEF SERVER BBG.AUTHMOD.BBGZSAFM.LOCALCOM UACC(NONE)PERMIT BBG.AUTHMOD.BBGZSAFM.LOCALCOM CLASS(SERVER)

ACCESS(READ) ID(server_id)RDEF SERVER BBG.AUTHMOD.BBGZSAFM.WOLA UACC(NONE)PERMIT BBG.AUTHMOD.BBGZSAFM.WOLA CLASS(SERVER)

ACCESS(READ) ID(server_id)

v SERVER profile for the authorized client module BBGZSCFM:

RDEF SERVER BBG.AUTHMOD.BBGZSCFM UACC(NONE)PERMIT BBG.AUTHMOD.BBGZSCFM CLASS(SERVER)ACCESS(READ) ID(server_id)

v SERVER profiles for optimized local adapter authorized client service:

RDEF SERVER BBG.AUTHMOD.BBGZSCFM.WOLA UACC(NONE)PERMIT BBG.AUTHMOD.BBGZSCFM.WOLA CLASS(SERVER)ACCESS(READ) ID(server_id)

v SERVER profile for WLM services (ZOSWLM):

RDEF SERVER BBG.AUTHMOD.BBGZSAFM.ZOSWLM UACC(NONE)PERMIT BBG.AUTHMOD.BBGZSAFM.ZOSWLM CLASS(SERVER)ACCESS(READ) ID(server_id)

v SERVER profile for RRS transaction services (TXRRS)

RDEF RDEF SERVER BBG.AUTHMOD.BBGZSAFM.TXRRS UACC(NONE)PERMIT PERMIT BBG.AUTHMOD.BBGZSAFM.TXRRS CLASS(SERVER)ACCESS(READ) ID(server_id)

v SERVER profile for SVCDUMP services (ZOSDUMP)

RDEF SERVER BBG.AUTHMOD.BBGZSAFM.ZOSDUMP UACC(NONE)PERMIT BBG.AUTHMOD.BBGZSAFM.ZOSDUMP CLASS(SERVER)ACCESS(READ) ID(server_id)

v SERVER profile for IFAUSAGE services (PRODMGR)

RDEF SERVER BBG.AUTHMOD.BBGZSAFM.PRODMGR UACC(NONE)PERMIT BBG.AUTHMOD.BBGZSAFM.PRODMGR CLASS(SERVER)ACCESS(READ) ID(server_id)

v SERVER profile for SAF authorized user registry services and SAFauthorization services (SAFCRED)

RDEF SERVER BBG.AUTHMOD.BBGZSAFM.SAFCRED UACC(NONE)PERMIT BBG.AUTHMOD.BBGZSAFM.SAFCRED CLASS(SERVER)ACCESS(READ) ID(server_id)

b. Refresh to activate the definitions:

SETROPTS RACLIST(SERVER) REFRESH


5. Start the angel process as a started task: From the z/OS operator console, issuethe following command:

S BBGZANGL

You should see the following log messages to indicate that the angel processstarted successfully:

IRR812I PROFILE BBGZANGL.* (G) IN THE STARTED CLASS WAS USEDTO START BBGZANGL WITH JOBNAME BBGZANGL.$HASP100 BBGZANGL ON STCINRDRIEF695I START BBGZANGL WITH JOBNAME BBGZANGL IS ASSIGNED TOUSER angel_id, GROUP admin_group$HASP373 BBGZANGL STARTEDCWWKB0056I INITIALIZATION COMPLETE FOR ANGEL

Note: You should leave the angel process running for any z/OS Connect EEserver that requires access using z/OS authorized services. To stop the angelprocess, enter the following command at the z/OS operator console:

P BBGZANGL


Chapter 9. Operating

Operating z/OS Connect EE

Starting and stopping z/OS Connect EEUse these commands to start and stop your z/OS Connect EE server.

Use a started procedure to run your z/OS Connect EE server.

Setting up a started task to run z/OS Connect EE servers

A single instance of the started task JCL can be used to start multiple z/OSConnect EE servers because the server name is passed as a parameter on the startcommand. You might require multiple copies of the started task JCL, if your z/OSConnect EE servers require different settings, for example: JVM_OPTIONS.

To set up the started task, customize the sample JCL <installation_path>/jcl/baqstrt.jcl and add it to your PROCLIB library. Then, enter the SAF command toassociate the name of the started task procedure with a user ID. For example, todefine the BAQSTRT procedure name to run under the user ID <userid>, use thefollowing RACF command:


If you use a non-IBM External Security Manager and receive aCHECK_PROC_OWNER error message when you start z/OS Connect EE as astarted task, check that you have correctly defined the location where the serverinstances are stored. Define the location in the HOME parameter of the OMVSsegment of the started task user ID.

Starting a z/OS Connect EE server

To start the server started procedure, enter the following command:

/S BAQSTRT,PARMS='<serverName> --clean'

Note: You must use the System Command Extension window within SDSF topreserve the case of your server name. From SDSF, enter / to open the SystemCommand Extension window, then enter the START command.

Stopping a z/OS Connect EE server

To stop the server started procedure, enter the following command:/P <JOB NAME>

System AutomationSystem Automation of z/OS software usually involves trapping messages issued tothe z/OS console and performing actions in response to those messages. Forexample, to confirm a z/OS Connect EE server has started or shutdownsuccessfully.


Specifying z/OS Connect EE messages to be written to z/OSoperator console

By default, z/OS Connect EE logs all messages to the UNIX System Services filemessages.log, and only a subset of these messages are written to the z/OS console.However, the server configuration file element zosLogging can be used to specifyadditional server messages to be logged to the z/OS console. For more informationabout the zosLogging server configuration element, see z/OS Logging (zosLogging)in the WebSphere Application Server documentation.

For example, you might find the following messages useful:

BAQR7000I: z/OS Connect API package apiName installed successfully.This message indicates that an API was installed successfully.

SRVE0250I: Web Module z/OS Connect has been bound to default_host.CWWKT0016I: Web application available (default_host): http://hostname:port/

These messages indicate that a z/OS Connect EE server has completedstart up successfully.

CWWKE1101I: Server quiesce complete.Indicates that a z/OS Connect EE server has completed shutdownsuccessfully

To log these messages to the z/OS console, specify the following in the serverconfiguration element:<zosLogging enableLogToMVS="true" wtoMessage="BAQR7000I,SRVE0250I,CWWKT0016I,CWWKE1101I"/>

When the z/OS Connect EE server is started with a deployed API, the followingmessages are written to the z/OS console:

N 4000000 MVxx yyddd hh:mm:ss.sss JOBnnnnn nnnnnnnn +CWWKE0001I: The server serverName has been launched.N 4000000 MVxx yyddd hh:mm:ss.sss JOBnnnnn nnnnnnnn +BAQR7000I: z/OS Connect API package apiName installed successfully.N 4000000 MVxx yyddd hh:mm:ss.sss JOBnnnnn nnnnnnnn +CWWKF0011I: The server serverName is ready to run a smarter planet.N 4000000 MVxx yyddd hh:mm:ss.sss JOBnnnnn nnnnnnnn +SRVE0250I: Web Module z/OS Connect has been bound to default_host.M 4000000 MVxx yyddd hh:mm:ss.sss JOBnnnnn nnnnnnnn +CWWKT0016I: Web application available (default_host):E 870 nnnnnnnn http://hostname:port/

When the z/OS Connect EE server is stopped, the following messages are writtento the z/OS console:

N 4000000 MVxx yyddd hh:mm:ss.sss JOBnnnnn nnnnnnnn +CWWKB0001I: Stop command received for server serverName.N 4000000 MVxx yyddd hh:mm:ss.sss JOBnnnnn nnnnnnnn +CWWKE1101I: Server quiesce complete.

Note: This function cannot be used to log the following shutdown messages,because they occur too late in the shutdown processing:CWWKB0111I: IBM Corp product z/OS Connect version vv.rr.mm successfully deregistered from z/OS.CWWKE0036I: The server serverName stopped after m minutes, s.sss seconds.

Using IBM Tivoli® System Automation for z/OS with z/OSConnect EE

IBM Tivoli System Automation for z/OS can be used to trap and respond to z/OSconsole messages issued by z/OS Connect EE servers to keep them highlyavailable.

IBM Tivoli System Automation for z/OS V5.3 APAR OA49939 supports a simplesetup for automating and monitoring the angel and z/OS Connect EE servers. Thissetup uses a pre-defined z/OS Connect EE configuration that is provided by the*IBMCOMP add-on policy, similar to sample solutions for products like IMS, CICS,


http://www.ibm.com/support/knowledgecenter/SS7K4U_liberty/com.ibm.websphere.wlp.zseries.doc/ae/rwlp_config_zosLogging.html

http://www-01.ibm.com/support/docview.wss?crawler=1&uid=swg1OA49939

DB2 and others. For more information see the developerWorks® article APAROA49939 - Easy Automation of zOS Connect EE and Using SA z/OS SamplePolicies in the IBM Tivoli System Automation for z/OS, Version 3.5 Knowledge Centerdocumentation.

Note: The support added by APAR OA49939 does not automatically use theadditional WTO messages, but you can use the instructions above to produce theWTO messages and manually include these in your policy.

With IBM System Automation for z/OS V3.5 APAR OA51440, which will beavailable by January 2017, messages CWWKB0001I, CWWKF0011I, CWWKT0016Iand CWWKE1101I will be used to automate and monitor z/OS Connect EE. Thisautomation also uses a pre-defined z/OS Connect EE configuration that isprovided by the *IBMCOMP add-on policy.

Chapter 9. Operating 191

https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/Tivoli%20System%20Automation/page/APAR%20OA49939%20-%20Easy%20Automation%20of%20zOS%20Connect%20EE%20V2

https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/Tivoli%20System%20Automation/page/APAR%20OA49939%20-%20Easy%20Automation%20of%20zOS%20Connect%20EE%20V2

http://www.ibm.com/support/knowledgecenter/SSWRCJ_3.5.0/com.ibm.safos.doc_3.5/Using_SA_zOS_Sample_Policies.html

http://www.ibm.com/support/knowledgecenter/SSWRCJ_3.5.0/com.ibm.safos.doc_3.5/Using_SA_zOS_Sample_Policies.html

https://www-304.ibm.com/support/entdocview.wss?uid=swg1OA51440&myns=swgtiv&mynp=OCSSWRCJ&mync=R&cm_sp=swgtiv-_-OCSSWRCJ-_-R

Chapter 10. Building a Service Archive (SAR) by using theBuild Toolkit

You can use either the command line interface or the SDK to build your SAR filefor the REST client and for IMS services.

A Service archive (SAR) file contains the information that is needed by a z/OSConnect EE service provider to install and provide the service, and to enable theservice as a JSON asset. You create a SAR file, then import it into the z/OSConnect EE API tooling that represents a REST client service.

You can create the SAR file from your IDE with the Build toolkit SDK or from thecommand line with the zconbt command. In each case, you need to set theproperties for the SAR file you are generating.Related reference:“zconbt command syntax” on page 329

Building a SAR for the REST clientYou can use either the command line interface or the SDK to build your SAR filefor the REST client.

To use the build toolkit to build your SAR file, the following properties must bedefined.

Table 31. Mandatory properties

Property Importance Description

provider Required Must be set to rest to build a SARfile for the REST client serviceprovider.

name Required The name of the service.Note: The name must match theserviceName attribute in thezosconnect_zosConnectServiceelement in the server.xml file.

version Required The version of the service.

The following properties are available for the REST client service provider:

Table 32. Properties for the REST client service provider



Table 32. Properties for the REST client service provider (continued)

connectionRef Required The name of the connection detailsdefined in the z/OS Connect EEconfiguration for connecting to theremote service. If not defined, then avalidzosconnect_zosConnectServiceRestClientorzosconnect_zosConnectServiceRestClientConnectionelement must be defined in theserver.xml file.

description Optional The description of the service. Thisname must match the serviceNameattribute in thezosconnect_zosConnectServiceelement in the server.xml file.

requestSchemaFile Required The JSON schema file that definesthe request object for this service.Note: If you do not specify anabsolute path, then the Build Toolkituses a relative path from thedirectory in which the zconbtcommand is run.

responseSchemaFile Required The JSON schema file that definesthe response object for this service.Note: If you do not specify anabsolute path, then the Build Toolkituses a relative path from thedirectory in which the zconbtcommand is run.

verb Optional The HTTP verb that is used to callthe service. If this verb is omitted,then the verb that is used to invokethe service is used.

uri Required The resource that this serviceexposes. It must not contain the hostname or port.

You can now use the build toolkit to create the SAR file. See the following topicswith samples:v “Building a SAR from the command line” on page 198v “Building a SAR with the z/OS Connect EE Build Toolkit SDK” on page 199Related reference:“zconbt command syntax” on page 329

Building a SAR for the IMS service providerWith a z/OS Connect EE connection, you can download IMS service definition filesfrom IMS Explorer for Development to your service project in the workspace. Theproject can be consumed by the build toolkit later to generate the SAR offlinewithout having to connect to a server.


For more information about downloading IMS service definitions, seeDownloading IMS service definitions (in IMS Explorer for Developmentinformation).




provider Required Must be set to imssp to build a SAR file for the IMS service provider.

name Required The name of the service.

version Optional The version of the service.

The following properties are required for the IMS service provider.

Table 34. Required properties for the IMS service provider run time


imsServiceProjectLocation Required The Eclipse workspace or a source control management folder thatcontains all the downloaded service projects from IMS Explorer.

imsTransactionRegistryLocationRequired The subfolder under the Eclipse workspace or a source controlmanagement folder that contains all the transaction messagemetadata.

imsConnectionRef Optional (seenote)

Name of the connection profile to use at service invocation.Note: This property is optional during SAR file generation, but if itis not specified, errors occur when the generated SAR file is used atrun time. Always specify this property when you use the buildtoolkit to generate the SAR files for IMS services.

imsInteractionRef Optional (seenote)

Name of the interaction properties profile to use at serviceinvocation.Note: This property is optional during SAR file generation, but if itis not specified, errors occur when the generated SAR file is used atrun time. Always specify this property when you use the buildtoolkit to generate the SAR files for IMS services.

The following properties are optional for the IMS service provider.

Table 35. Optional properties for the IMS service provider

Attribute Importance Description

imsTranCodeOverride Optional Overrides the transaction code that the service invokes at runtime.

imsDatastoreOverride Optional Overrides the IMS datastore name that specifies the IMSsubsystem against which to invoke the service.

Input-only properties:

initializeInputFields Optional Initializes fields in the input data structure according to theirtype if a default is not specified for the field and either thefield is omitted from the input interface or the field isincluded but the respective JSON tag is not received at runtime. By default, fields are not initialized unless specifiedotherwise in IMS Explorer.

enforceMinArrayOccurrence Optional Enforces the minimum number of array occurrence in theinput data structure as defined in the copybook. The defaultis true unless specified otherwise in IMS Explorer.

Chapter 10. Building a Service Archive (SAR) by using the Build Toolkit 195

http://www.ibm.com/support/knowledgecenter/SS9NWR_3.2.0/com.ibm.ims.explorer32.doc/wb_download_services.htm

Table 35. Optional properties for the IMS service provider (continued)

Attribute Importance Description

Output-only properties:

trimOutputLeadingWhitespace Optional Trims the leading whitespace from JSON property values inthe output messages. By default, leading whitespace is nottrimmed, unless specified otherwise in IMS Explorer.

trimOutputTrailingWhitespace Optional Trims trailing whitespace from JSON property values inoutput messages. By default, trailing whitespace is trimmed,unless specified otherwise in IMS Explorer.

escapeOutputControlCharacters Optional Escapes non-printable control characters, such as tokens orcontrol blocks, in JSON property values as \uNNNN fornecessary internal processing, instead of removing them. Bydefault, control characters are omitted, not escaped, unlessspecified otherwise in IMS Explorer.

omitOutputFieldsByValue Optional Omits the JSON name-value pair for a non-numeric fieldfrom the JSON output message when the data for the field iscomposed of the same byte value repeated throughout, suchas all 0x00 or all 0xFF. By default, this option is not selected,unless specified otherwise in IMS Explorer.

omitOutputFieldsByValueByte Optional Specifies the hexadecimal value that all bytes in anon-numeric field must contain to be omitted. The defaultvalue is 00, unless specified otherwise in IMS Explorer.

omitOutputEmptyTags Optional Omits JSON tags that contain an empty string ("tag":"")from JSON output messages after whitespace and controlcharacters are processed. By default, empty tags are notomitted, unless specified otherwise in IMS Explorer.

The default values are already set in IMS Explorer, and you can modify them inIMS Explorer when you create or edit an IMS mobile transaction service orthrough the IMS mobile preferences for advanced data conversion options. Thesevalues are stored with the downloaded service definitions.

Important:

v If these properties are not specified during SAR generation using the buildtoolkit, the values that were specified in IMS Explorer are used at run time.

v If these properties are specified during SAR generation using the build toolkit,they override the values that were specified in IMS Explorer.

This behavior allows you to more easily generate a SAR file for different testing orproduction environments without having to modify the service definitions.

You can now use the build toolkit to create the SAR file. See the following topicswith samples:v “Building a SAR from the command line” on page 198v “Building a SAR with the z/OS Connect EE Build Toolkit SDK” on page 199Related reference:“zconbt command syntax” on page 329

Building a SAR for the WOLA service providerYou can use the build toolkit to build a SAR file for the CICS service provider.


The SAR contains equivalent function to a SAR built using the BAQLS2JS utility. Formore information about the BAQLS2JS utility, see “Conversion for z/OS ConnectEnterprise Edition data transformation” on page 250. The WSBind file is includedin the SAR file.




provider Required Must be set to wola.

name Required The name of the service. For example, inquireSingle.

version Required The version of the service.

channelName Required The CICS channel name to use for delivering messages and receivingpayloads using CICS containers.

connectionRef Required The name of the configured connection factory element to be used. Thiselement contains the JNDI name of the WOLA resource adapter connectionfactory.

connectionWaitTimeout Required The number of seconds to wait for an external address space applicationthat matches the registration name to issue a WOLA Receive Request orHost Service API and become active. Set this parameter to 0 to disabletimeout.

contextEncoding Required The encoding of the data in all context containers that are sent to thedestination program.

httpHeaders Required The HTTP header name or list of comma-separated and case-sensitiveHTTP header names that are passed to the destination program.

program Required The name of the program to invoke in the remote system.

register Required The name of the WOLA target register.

requestContainerName Required The name of the request container.

requestContainerType Required The type of the request container, CHAR or BIT.

responseContainerName Required The name of the response container.

responseContainerType Required The type of the response container, CHAR or BIT,

tranId Required The name of the WOLA CICS Link Server link invocation task transactionID.

The following properties are available for the WOLA service provider when usedwith DataXForm.

Table 37. Other properties for the WOLA service provider using DataXForm


ccsid Optional The CCSID that is used at run timeto encode character data. Forexample, 037.

charVarying Optional Defines how variable-length characterdata is mapped. Valid values areno|null|collapse|binary.

dataTruncation Optional Controls if variable length data istolerated in a fixed-length fieldstructure. Valid values arefalse|true. The default is false.


Table 37. Other properties for the WOLA service provider using DataXForm (continued)

dateTime Optional Specifies if potential ABSTIME fieldsin the high-level language structureare mapped as timestamps. Validvalues are unused|packed15. Thedefault is unused

language Required The language of the target program.Valid values are COBOL|C|PLI-ENTERPRISE|PLI-OTHER.

requestStructure Required The relative or absolute path to thefile that contains the languagestructure for the request.

responseStructure Required The relative or absolute path to thefile containing the language structurefor the response.

truncateNullArrays Optional Specifies how structured arrays areprocessed. Valid values arefalse|true. The default is false.

truncateNullArraysValue Optional Specifies which values are treated asempty for truncateNullArraysprocessing. Valid values arenull|space|zero. The default is null.

The following properties are available for the WOLA service provider when usedfor migration.

Table 38. Properties for the WOLA service provider when used for migration


bindFile Required The relative or absolute path to thebind file.

requestSchema Required The relative or absolute path to theJSON schema for the request.

responseSchema Required The relative or absolute path to theJSON schema for the response.

The following properties are available for the WOLA service provider when usedwithout DataXForm.

Table 39. Properties for the WOLA service provider when without DataXForm


requestSchema Required The relative or absolute path to theJSON schema for the request.

responseSchema Required The relative or absolute path to theJSON schema for the response.

Related reference:“zconbt command syntax” on page 329

Building a SAR from the command lineEnter the zconbt command on the command line to build your Service archive file.


Before you begin

Ensure that the z/OS Connect EE Build Toolkit is installed. For more information,see “Installing the z/OS Connect EE Build Toolkit” on page 114.

About this task

Follow these steps to use the z/OS Connect EE Build Toolkit to create a SAR file.To learn more about the Build Toolkit, see “The z/OS Connect EE Build Toolkit”on page 5.

Procedure1. Create the properties files with the properties you need for the SAR.

For example, for the REST client:provider=restname=exampleversion=1.0description=An example REST client servicerequestSchemaFile=request.jsonresponseSchemaFile=response.jsonverb=POSTuri=/resource/itemconnectionRef=conn

A description of the properties is provided in “Building a SAR for the RESTclient” on page 193.For the IMS service provider:

provider=imsspname=service1version=1.0description=My first IMS serviceimsServiceProjectLocation=C:/myEclipse/workspaceimsTransactionRegistryLocation=C:/myEclipse/workspace/MyzCEETransimsConnectionRef=NewConnRefimsInteractionRef=NewInteracRef

A description of the properties is provided in “Building a SAR for the IMSservice provider” on page 194.

Note: If you are running on Microsoft Windows, use either a double backslash\\ or a forward slash character / in the path name.

2. Enter the zconbt command. For example:

zconbt -p=service1.properties -f=./service1.sar

3. If any errors occur, make the necessary corrections and repeat the procedure.4. You can now import the SAR file so it can be used by the API.Related reference:“zconbt command syntax” on page 329

Building a SAR with the z/OS Connect EE Build Toolkit SDKUse the Build Toolkit SDK to build your Service archive file.


Before you beginv Ensure that the z/OS Connect EE Build Toolkit is installed. For more

information, see “Installing the z/OS Connect EE Build Toolkit” on page 114.v Ensure that the plug-in classes are located in a directory in the class path.

About this task

Follow these steps to use the z/OS Connect EE build toolkit SDK to create a SARfile. To learn more about the build toolkit, see “The z/OS Connect EE BuildToolkit” on page 5.

Procedure1. In your IDE, create a Map<String, String> object to contain the properties

required to build the SAR.2. Create a SARGenerator object passing in the Map created in Step 1. If any

properties are invalid, an InvalidPropertyException occurs. The error messagecontains the property in error and the reason.

3. Save the SAR file. Call the save() method and pass the filename. For example4. You can now import the SAR file so it can be used by the API.

Example

Example 1: The REST client:Map<String, String> properties = new HashMap<String, String>();

properties.put("name", "example");properties.put("provider", "rest");properties.put("version", "1.0");properties.put("description", "An example REST client service");properties.put("requestSchemaFile", "request.json");properties.put("responseSchemaFile", "response.json");properties.put("verb", "POST");properties.put("uri", "/resource/item");properties.put("connectionRef", "conn");

SARGenerator sarGenerator = new SARGenerator(properties);sarGenerator.save("/example/ouput/dir/file.sar");

Example 2: The IMS service provider:Map<String, String> properties = new HashMap<String, String>();

properties.put("name", "service1");properties.put("provider", "imssp");properties.put("version", "1.0");properties.put("description", "My first IMS service");properties.put("imsServiceProjectLocation", "C:/myEclipse/workspace");properties.put("imsTransactionRegistryLocation", "C:/myEclipse/workspace/MyzCEETrans");properties.put("imsConnectionRef", "NewConnRef");properties.put("imsInteractionRef", "NewInteracRef");

SARGenerator sarGenerator = new SARGenerator(properties);sarGenerator.save("C:/IMSMobile/output/service1.sar");


Chapter 11. Designing and building APIs in the API Editor

z/OS Connect EE provides an Eclipse-based API editor for you to define APIs foryour z/OS Connect EE services.

When you are in the z/OS Connect Enterprise Edition perspective in the Eclipseenvironment, you can do the following work:v Create, edit, delete, deploy, and export an API project in the Project Explorer

view.v Browse, start, stop, and remove deployed APIs on connected servers in the z/OS

Connect EE Servers view.v Examine and test the operations of an API in Swagger UI that is included in the

API Editor.

See the following resources for step-by-step examples of creating and deployingAPIs:v “Develop an API to invoke a CICS service via WOLA” on page 17v “Develop an API to invoke an IMS service ” on page 66v YouTube video: https://www.youtube.com/watch?v=HjE8wdvX3I0

&feature=youtu.be.

RESTful web services and API designThe primary focus of RESTful web service design is to identify the z/OS assetsthat need to be exposed, determine the HTTP methods that you want to supportfor those assets, and then map the resource identifiers and methods to those assets.

The methods that are defined by the HTTP specification provide a uniforminterface for interacting with resources on the web. All web browsers, servers, andapplications understand this uniform interface and the semantics of each operation.They can connect to one another and exchange information by using this uniforminterface regardless of platforms or technology differences.

After the resources that need to be exposed for the service are determined, the nextstep is to design a REST API. This API is the user interface to the consumers of theAPI. The consumers of the API might be application developers who need to buildRESTful clients to access the services, or an integration developer who publishesyour APIs in IBM API Connect.

A REST API describes a set of resources and a set of methods that can be called onthose resources. The methods in a REST API can be called from any HTTP client,including client-side JavaScript code that is running in a web browser. The RESTAPI has a base path, which is similar to a context root. All resources in a REST APIare defined relative to its base path. The base path can be used to provide isolationbetween different REST APIs. The HTTP client uses a path relative to the base paththat identifies the resource in the REST API that the client is accessing. The pathsto a resource can be hierarchical, and a well-designed path structure can help aconsumer of a REST API understand the resources that are available within thatREST API. The following table lists some example resources for a patient databasein the REST API:




Table 40. Example resources

Resource Description

/patients All of the patients in the database

/patients/12345 Patient #12345

/patients/12345/orders All prescription orders for patient #12345

/patients/12345/orders/67890 Prescription order #67890 for patient #12345

Each resource in the REST API has a set of methods that can be called by an HTTPclient. The following table lists example methods for the resource /patients/12345:

Table 41. Example operations

HTTP Method Description

GET Retrieve the patient details from the database.

PUT Update the patient details in the database.

DELETE Delete the patient from the database.

To update information for that patient, the HTTP client would make an HTTP PUTrequest to /patients/12345.

With a uniform interface for communication, application developers can focus onthe resources rather than the methods. They can create their applications withouthaving to deal with a complex system or learn the intricacies of new interfaces.They can also freely change their applications while the communication methodsthat connect to these resources remain stable.

Each path and method combination in a REST API can also have a set ofparameters that can be used by the HTTP client to pass arguments. Each parametermust be defined in the definitions for the REST API. Each parameter has a uniquename and type. Several types of parameters are supported by REST APIs in z/OSConnect EE:

Path parametersCan be used to identify a particular resource. The value of the parameter ispassed in by the HTTP client as a variable part of the URL, and the valueof the parameter is extracted from the path for use in the operation. Pathparameters are denoted by using the syntax {paramName} in the path to theresource. For example, the patient ID can be passed in as a path parameternamed patientID:

/patients/{patientID}

Query parametersThe value of a query parameter is passed in by the HTTP client as akey-value pair in the query string at the end of the URL. As an example,query parameters can be used to pass in a minimum and maximumnumber of results to be returned by a particular call:

/patients?min=5&max=20

Header parametersThe HTTP client can pass header parameters by adding them as HTTPheaders in the HTTP request. As an example, a header parameter might beused to pass in a unique identifier that identifies the HTTP client that iscalling the API:


Api-Client-Id: fffe2c5d-42d5-7428-5f5f-abc34ab7f555

To assist you with the design and development of this API, z/OS Connect EEprovides a graphical editor, the z/OS Connect EE API Editor.

Designing RESTful APIsThe way that you design APIs can have a significant impact on their adoption.This section lists considerations for API design in general, and principles foreffective RESTful implementation in particular.

Think “consumer”

APIs don't exist in isolation. Modern APIs are the way in which the capabilities ofservices are shared with others. When implemented correctly, APIs that are usedinside your organization can enforce consistency and promote efficient reuse.Public APIs that are used outside your organization can expand the reach of yourbusiness, by allowing developers to extend the services that you provide.Ease-of-use for consumers is vital for the adoption of the API.

Consumers are developers. They could be developers in your own organization, ora mix of internal and third-party developers. These developers expect APIs thatmake it quick for them to deliver: quick to learn, easy to use, and aimed at theiruse cases. Using the API must be faster and more expedient than coding analternative solution. A successful API encourages developers to use it and to shareit with other developers.

An API designer of any API must decide on the following functional requirements:v What function needs to be exposed, and how.v Models an API that supports the needs of the user and follows RESTful

principles.

A properly designed API appeals to the user, is easy to understand and implement.

Thinking of an API as a business product helps to differentiate it from traditionalapplication programming interfaces. A traditional application programminginterface represents a piece of software that you have built and deployed. Amodern API represents a package of capabilities that is both attractive to a userand independent of any specific piece of back-end software. The API is designedfrom the perspective of the intended user. Before you develop one, you mustunderstand:v Who is the user? You might have one clear target user for the API or a mix of

users. If you have a mix of users, you must understand each of them.v What do they want? Instead of focusing on what the API can do, that is, its

functions and capabilities, think about the ways in which it might be used.v How can you make those use cases as easy as possible? Think about:

StabilityHow can you minimize disruption for the consumer when you changethe API?

FlexibilityAlthough you can't exhaustively cover every possibility, how can youbuild in some flexibility for the consumer? A simple example is allowingeither uppercase or lower-case input.

Chapter 11. Designing and building APIs in the API Editor 203

ConsistencyWhat standards can you set for your API so that consumers know whatto expect?

DocumentationWhat documentation can you provide, and how do you make this asstraightforward to use as possible?

Think “resources”

Traditional services focused on methods, such as "createAccount" or"updateAccount". Designing RESTful services means that you have to thinkdifferently: you focus on resources. For example, a resource could be "Account",then the standard HTTP methods are used to operate on that resource. Thesemethods act as verbs for the nouns of the resources.

The verbs POST, GET, PUT, and DELETE are already defined. Try to handle alloperations with a combination of these verbs and the resources. The more bespokeverbs that you define, the less generalized your interface becomes.

Design the URIs

From the standpoint of client applications addressing resources, the URIsdetermine how intuitive the REST Web service is and whether the service will beused in ways that the designers can anticipate. REST Web service URIs should beintuitive to the point where they are easy to guess. Think of a URI as a kind ofself-documenting interface that requires little, if any, explanation or reference for adeveloper to understand what it points to and to derive related resources. To thisend, the structure of a URI should be straightforward, predictable, and easilyunderstood.

One way to achieve this level of usability is to define directory structure-like URIs.This type of URI is hierarchical, rooted at a single path, and branching from it aresub-paths that expose the service's main areas. According to this definition, a URIis not merely a slash-delimited string, but rather a tree with subordinate andsuperordinate branches connected at nodes. For example, in a discussion threadingservice that gathers a range of topics, you might define a structured set of URIslike this:http://www.myservice.org/discussion/topics/{topic}

The root, /discussion, has a /topics node beneath it. Underneath that there are aseries of topic names, such as technology and so on, each of which points to adiscussion thread. Within this structure, it's easy to pull up discussion threads justby typing something after /topics/.

In some cases, the path to a resource lends itself especially well to a directory-likestructure. Take resources organized by date, for instance, which are a very goodmatch for using a hierarchical syntax. This example is intuitive because it is basedon rules: http://www.myservice.org/discussion/2008/12/10/{topic}. The firstpath fragment is a four-digit year, the second path fragment is a two-digit day, andthe third fragment is a two-digit month. This is the level of simplicity we're after.Humans and machines can easily generate structured URIs like this because theyare based on rules. Filling in the path parts in the slots of a syntax makes themgood because there is a definite pattern from which to compose them:http://www.myservice.org/discussion/{year}/{day}/{month}/{topic}


Some additional guidelines while thinking about URI structure for a RESTful Webservice are:v Hide the server-side scripting technology file extensions (.jsp, .php, .asp), if any,

so you can convert to another scripting language without changing the URIs.v Keep everything lowercase.v Substitute spaces with either hyphens or underscoresv Avoid query strings as much as you can.v Instead of using the 404 Not Found code if the request URI is for a partial path,

always provide a default page or resource as a response.v URIs should also be static so that when the resource changes or the

implementation of the service changes, the link stays the same. This allowsbookmarking. It's also important that the relationship between resources that isencoded in the URIs remains independent of the way the relationships arerepresented where they are stored.

Apply HTTP methods explicitly

One of the key characteristics of a RESTful Web service is the explicit use of HTTPmethods in a way that follows the protocol as defined by RFC 2616. HTTP GET,for instance, is defined as a data-producing method that's intended to be used by aclient application to retrieve a resource, to fetch data from a Web server, or toexecute a query with the expectation that the Web server will look for and respondwith a set of matching resources.

REST asks developers to use HTTP methods explicitly and in a way that'sconsistent with the protocol definition. This basic REST design principle establishesa one-to-one mapping between create, read, update, and delete (CRUD) operationsand HTTP methods. According to this mapping:v To create a resource on the server, use POST.v To retrieve a resource, use GET.v To change the state of a resource or to update it, use PUT.v To remove or delete a resource, use DELETE.

An unfortunate design flaw inherent in many Web APIs is in the use of HTTPmethods for unintended purposes. The request URI in an HTTP GET request, forexample, usually identifies one specific resource. Or the query string in a requestURI includes a set of parameters that defines the search criteria used by the serverto find a set of matching resources. At least this is how the HTTP/1.1 RFCdescribes GET. But there are many cases of unattractive Web APIs that use HTTPGET to trigger something transactional on the server: for instance, to add recordsto a database. In these cases the GET request URI is not used properly or at leastnot used RESTfully. If the Web API uses GET to invoke remote procedures, it lookslike this: GET /adduser?name=Robert HTTP/1.1

It's not a very attractive design because this Web method supports a state-changingoperation over HTTP GET. Put another way, this HTTP GET request has sideeffects. If successfully processed, the result of the request is to add a new user: inthis example, Robert, to the underlying data store. The problem here is mainlysemantic. Web servers are designed to respond to HTTP GET requests by retrievingresources that match the path (or the query criteria) in the request URI and returnthese or a representation in a response, not to add a record to a database. From the


standpoint of the intended use of the protocol method then, and from thestandpoint of HTTP/1.1-compliant Web servers, using GET in this way isinconsistent.

Beyond the semantics, the other problem with GET is that to trigger the deletion,modification, or addition of a record in a database, or to change server-side state insome way, invites Web caching tools (crawlers) and search engines to makeserver-side changes unintentionally simply by crawling a link. A simple way toovercome this common problem is to move the parameter names and values onthe request URI into XML tags. The resulting tags, an XML representation of theentity to create, may be sent in the body of an HTTP POST whose request URI isthe intended parent of the entity:Before:GET /adduser?name=Robert HTTP/1.1

After:POST /users HTTP/1.1Host: myserverContent-Type: application/xml<user><name>Robert</name></user>

This method is exemplary of a RESTful request: proper use of HTTP POST andinclusion of the payload in the body of the request. On the receiving end, therequest may be processed by adding the resource contained in the body as asubordinate of the resource identified in the request URI; in this case the newresource should be added as a child of /users. This containment relationshipbetween the new entity and its parent, as specified in the POST request, isanalogous to the way a file is subordinate to its parent directory. The client sets upthe relationship between the entity and its parent and defines the new entity's URIin the POST request.

A client application may then get a representation of the resource using the newURI, noting that at least logically the resource is located under /users:HTTP GET request GET /users/Robert HTTP/1.1Host: myserverAccept: application/xml

Using GET in this way is explicit because GET is for data retrieval only. GET is anoperation that should be free of side effects, a property also known asidempotence. A similar refactoring of a Web method also needs to be applied incases where an update operation is supported over HTTP GET:GET /updateuser?name=Robert&newname=Bob HTTP/1.1

This changes the name attribute (or property) of the resource. Query strings aren'ta bad thing (they're good for implementing filter specifications, for example) butthe query-string-as-method-signature pattern that is used in this simple examplecan break down when used for more complex operations. Because your goal is tomake explicit use of HTTP methods, a more RESTful approach is to send an HTTPPUT request to update the resource, instead of HTTP GET, for the same reasonsstated earlier.PUT /users/Robert HTTP/1.1Host: myserverContent-Type: application/xml

<?xml version="1.0"?><user><name>Bob</name></user>


Using PUT to replace the original resource provides a much cleaner interface that'sconsistent with REST's principles and with the definition of HTTP methods. ThePUT request in this example is explicit in the sense that it points at the resource tobe updated by identifying it in the request URI and in the sense that it transfers anew representation of the resource from client to server in the body of a PUTrequest instead of transferring the resource attributes as a loose set of parameternames and values on the request URI. This also has the effect of renaming theresource from Robert to Bob, and in doing so changes its URI to /users/Bob. In aREST Web service, subsequent requests for the resource using the old URI wouldgenerate a standard 404 Not Found error.

Another consideration is handling large result sets. A standard approach is to useexplicit pagination: the GET returns a limited number of objects when it is invokedagainst a set (irrespective of whether it is filtered), and include a link to the next“page” or “batch” that can be requested. The size of a page can be included on theGET, for example as a query string parameter) and, if there is a danger ofreturning too many, it should be set to default if the caller forgets to set it.

As a general design principle, it helps to follow REST guidelines for using HTTPmethods explicitly by using nouns in URIs instead of verbs. In a RESTful Webservice, the verbs POST, GET, PUT, and DELETE are already defined by theprotocol. And ideally, to keep the interface generalized and to allow clients to beexplicit about the operations they invoke, the Web service should not define moreverbs or remote procedures, such as /adduser or /updateuser. This general designprinciple also applies to the body of an HTTP request, which is intended to beused to transfer resource state, not to carry the name of a remote method orremote procedure to be invoked.

Be stateless

REST Web services need to scale to meet increasingly high performance demands.Clusters of servers with load-balancing and failover capabilities, proxies, andgateways are typically arranged in a way that forms a service topology, whichallows requests to be forwarded from one server to the other as needed to decreasethe overall response time of a Web service call. Using intermediary servers toimprove scale requires REST Web service clients to send complete, independentrequests; that is, to send requests that include all data needed to be fulfilled so thatthe components in the intermediary servers may forward, route, and load-balancewithout any state being held locally in between requests.

A complete, independent request doesn't require the server, while processing therequest, to retrieve any kind of application context or state. A REST Web serviceapplication (or client) includes within the HTTP headers and body of a request allof the parameters, context, and data needed by the server-side component togenerate a response. Statelessness in this sense improves Web service performanceand simplifies the design and implementation of server-side components becausethe absence of state on the server removes the need to synchronize session datawith an external application.

Figure 1 illustrates a stateful service from which an application may request thenext page in a multi-page result set, assuming that the service keeps track of wherethe application leaves off while navigating the set. In this stateful design, theservice increments and stores a previousPage variable somewhere to be able torespond to requests for next.


Stateful services like this get complicated. In a Java Platform, Enterprise Edition(Java EE) environment stateful services require a lot of up-front consideration toefficiently store and enable the synchronization of session data across a cluster ofJava EE containers. In this type of environment, there's a problem familiar toservlet/JavaServer Pages (JSP) and Enterprise JavaBeans (EJB) developers whooften struggle to find the root causes of java.io.NotSerializableException duringsession replication. Whether it's thrown by the servlet container duringHttpSession replication or thrown by the EJB container during stateful EJBreplication, it's a problem that can cost developers days in trying to pinpoint theone object that doesn't implement the Serializable interface in a sometimes complexgraph of objects that constitute the server's state. In addition, sessionsynchronization adds overhead, which impacts server performance.

Stateless server-side components, on the other hand, are less complicated to design,write, and distribute across load-balanced servers. A stateless service not onlyperforms better, it shifts most of the responsibility of maintaining state to the clientapplication. In a RESTful Web service, the server is responsible for generatingresponses and for providing an interface that enables the client to maintainapplication state on its own. For example, in the request for a multi-page result set,the client should include the actual page number to retrieve instead of simplyasking for next.

A stateless Web service generates a response that links to the next page number inthe set and lets the client do what it needs to in order to keep this value around.This aspect of RESTful Web service design can be broken down into two sets ofresponsibilities as a high-level separation that clarifies just how a stateless servicecan be maintained:

Server

Figure 29. . Diagram showing stateful design

Figure 30. . Diagram showing stateless design


v Generates responses that include links to other resources to allowapplications to navigate between related resources. This type of responseembeds links. Similarly, if the request is for a parent or containerresource, then a typical RESTful response might also include links to theparent's children or subordinate resources so that these remainconnected.

v Generates responses that indicate whether they are cacheable or not toimprove performance by reducing the number of requests for duplicateresources, and by eliminating some requests entirely. The server doesthis by including a Cache-Control and Last-Modified (a date value)HTTP response header.

Client application

v Uses the Cache-Control response header to determine whether to cachethe resource (make a local copy of it) or not. The client also reads theLast-Modified response header and sends back the date value in anIf-Modified-Since header to ask the server if the resource has changed.This is called Conditional GET, and the two headers go hand-in-hand inthat the server's response is a standard 304 code (Not Modified) andomits the actual resource requested if it has not changed since that time.A 304 HTTP response code means the client can safely use a cached,local copy of the resource representation as the most up-to-date, in effectbypassing subsequent GET requests until the resource changes.

v Sends complete requests that can be serviced independently of otherrequests. This requires the client to make full use of HTTP headers asspecified by the Web service interface and to send completerepresentations of resources in the request body. The client sendsrequests that make very few assumptions about prior requests, theexistence of a session on the server, the server's ability to add context toa request, or about application state that is kept in between requests.

This collaboration between client application and service is essential to beingstateless in a RESTful Web service. It improves performance by saving bandwidthand minimizing server-side application state.

Transfer XML, JSON, or both?

A resource representation typically reflects the current state of a resource, and itsattributes, at the time a client application requests it. Resource representations inthis sense are mere snapshots in time. This could be a thing as simple as arepresentation of a record in a database that consists of a mapping betweencolumn names and XML tags, where the element values in the XML contain therow values. Or, if the system has a data model, then according to this definition aresource representation is a snapshot of the attributes of one of the things in yoursystem's data model. These are the things you want your REST Web service toserve up. The last set of constraints that goes into a RESTful Web service designhas to do with the format of the data that the application and service exchange inthe request/response payload or in the HTTP body. This is where it really pays tokeep things simple, human-readable, and connected. The objects in your datamodel are usually related in some way, and the relationships between data modelobjects (resources) should be reflected in the way they are represented for transferto a client application. In the discussion threading service, an example of connectedresource representations might include a root discussion topic and its attributes,and embed links to the responses given to that topic.


And last, to give client applications the ability to request a specific content typethat's best suited for them, construct your service so that it makes use of thebuilt-in HTTP Accept header, where the value of the header is a MIME type. Somecommon MIME types used by RESTful services are shown in Table 1:

Table 42. Common MIME types used by RESTful services

MIME-Type Content-Type

JSON application/json

XML application/xml

XHTML application/xhtml+xml

This allows the service to be used by a variety of clients written in differentlanguages running on different platforms and devices. Using MIME types and theHTTP Accept header is a mechanism known as content negotiation, which letsclients choose which data format is right for them and minimizes data couplingbetween the service and the applications that use it.

z/OS Connect EE API Editor for defining your APIsThe z/OS Connect EE API Editor helps you create an API package that describesthe configuration of the API and the HTTP methods on the resources that can becalled.

For each path and method combination, you can select an existing z/OS ConnectEE service and specify optional HTTP-to-JSON mappings. The mapping is basedon a service archive (SAR) file, a compressed collection of files that represent all theinformation that is needed by a z/OS Connect EE service provider to install andprovide the service, and to enable the service as a JSON asset. The service archivefile is generated by the related tool for each of the z/OS Connect EE serviceproviders. For example, for IMS, use IMS Enterprise Suite Explorer forDevelopment. For CICS access through the WebSphere Optimized Local Adapters(WOLA), use the BAQLS2JS and BAQJS2LS utilities.

With the service archive, you can map an HTTP method to a field in the service, orassign a value to a field in the service, by using the z/OS Connect EE API Editor.After the mapping is complete, you export the API project into an API package inthe form of an API archive file.

The following diagram shows the API creation process.


API package and API archive (AAR)

A z/OS Connect EE API package is generated as an API archive (AAR) file, acompressed collection of files with the following structure:v package.xml, which describes the API and its implementation.v An api/ directory that contains all the HTTP-to-JSON mapping information.v An api-docs/ directory that holds the API documentation, including the

Swagger document, swagger.json.v A services/ directory that contains services that were imported in the z/OS

Connect EE API project.

The generated Swagger document in the API package is the REST API equivalentof a WSDL document for a SOAP-based web service.

Defining your API in z/OS Connect EE API Editor

With the API Editor, you can complete the following REST API development tasks:v Define an API by specifying a name, some description, the base path, and a

version number. The base path is the root of all resources that are associatedwith this API. The base path can contain a variable.

v Add or remove one or more paths (relative paths). For each path:– You can specify a path parameter in the path, which is indicated with curly

braces ({}), such as:/myPath/{myVariable}

– You can add and remove HTTP methods.– You can reorder methods.– Each method can be associated with:

- A z/OS Connect EE service- One or more query parameters- One or more headers

– For each method, you can specify the following actions:

Figure 31. API creation process in z/OS Connect EE


- Assign a static value to a field.- Assign a value to a field from the header, path parameter, or query

parameter.- Remove a field.

After the HTTP-to-JSON mapping is defined, you can deploy the API to the z/OSConnect EE server, or export the project as an API archive file for deployment byusing the apideploy command.

You can also deploy the API directly from the API Editor. Right click the API, thenclick z/OS Connect EE > Deploy API to z/OS Connect EE Server.

Testing, starting, and stopping an API

After an API is deployed, you can single-click the API in the z/OS Connect EEServers view to examine its properties. You can further use the provided SwaggerUI to examine and test the operations in the API by double-clicking the API in thez/OS Connect EE Servers view. You can also start or stop a deployed API, orremove an API from the server, all from within the API Editor:

Related concepts:“RESTful web services and API design” on page 201The primary focus of RESTful web service design is to identify the z/OS assetsthat need to be exposed, determine the HTTP methods that you want to supportfor those assets, and then map the resource identifiers and methods to those assets.


Related information:

What is Swagger?

Swagger RESTful API documentation specification

Tips for using the API Editor for HTTP-to-JSON mappingYou can use the common keyboard and mouse-click actions for your API designneeds when you map HTTP request and response to the JSON schema of theservice.

Use the keyboard and the mouse for HTTP to JSON mapping:v Drag-and-drop to map data from the HTTP header, path parameter, or query

parameters to fields in the service.v Right-click to access menus for actions applicable to the selected elements, such

as adding/editing a query parameter, assigning a value to a field, or undo atransform action.

v Use the Control or Shift key to select multiple fields.

The basics

When you open the request mapping, you see the HTTP request on one side andthe fields in the service on the other. As an API developer, your primary interest isto map the information from the HTTP request, typically in the header or aparameter to appropriate fields in the service.

If you open the response mapping, you see fields in the service on the left and theHTTP response on the right. As an API developer, your primary interest is todetermine what information from the service to send back to the body in the HTTPresponse. Often times you would remove some fields from the response and sendback only needed information.

Transform actions

Designing your API is achieved mostly through the data transform actions:v Move: Moves data from the HTTP header, path parameter, or query parameters

to appropriate fields in the service.v Remove: Hides a field in the service. This action is often used in the response

mapping so unnecessary fields are not available to the API for the HTTPresponse.

v Assign: Assigns a static value to a field in the service.

To move data from the HTTP request to appropriate fields in the service, moveyour mouse over the element in the HTTP request and drag.

You can also easily add an HTTP header or a query parameter through theright-click menu.


http://swagger.io/?cm_mc_uid=42071323141114436327967&cm_mc_sid_50200000=1444322404

https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md

If you make a mistake, you can undo or delete your transform action byright-clicking the action and select Delete from the menu.

Selecting multiple fields

To select multiple fields for the same action, you have several options:v Select a block of fields by selecting the first field, holding down the Shift key,

and clicking the Up or Down arrow to extend the selection.v Select a block of fields by drawing a box around the fields with your mouse.

v Select multiple fields that are not next to one another by selecting the first field,holding down the Control key, and clicking the other fields that you want toselect.

Figure 32. The right-click menu

Figure 33. Selecting a block of fields by drawing a box


Handling the null type in JSON schemaSwagger 2.0 does not support the null type because Swagger supports only asubset of JSON schema.

If a service that is imported into the API contains nullable fields, as shown in thefollowing example with "type": ["null", "string"], the first supported type (inthis example, "string") is used, and only the Remove transform is allowed in themapping editor.{

"type": "object","properties": {"location": {

"type": ["null","string"

],"maxLength": 16

}},"required": ["LOCATION"

]}

Because Swagger 2.0 does not support the null type, nullable fields areindistinguishable from non-nullable fields in the Swagger document. When nulltypes are sent to the z/OS Connect EE server, they are passed through in the bodyand not represented in the Swagger document.

Setting preferences for the API EditorYou can specify your preferences for default behaviors for host connections, APIdeployment, and logging in the preferences window.

Figure 34. Selecting a block of fields by drawing a box


To set your preferences, from the menu bar, click Window > Preferences > z/OSConnect EE.

The API deployment and connection preferences apply to APIs that you will bedeploying, updating, or removing, or new connections that you will be creating. Bydefault, APIs are started upon deployment and stopped upon update.

You can override these default settings when you are creating individual hostconnections or deploying individual APIs.

Connecting to a z/OS Connect EE serverCreate a host connection to the z/OS Connect EE server to view, deploy, start, orstop an API.

Before you begin

Switch to the z/OS Connect Enterprise Edition perspective.

About this task

In the Host Connections view, you can add connections to z/OS Connect EEservers and credentials to store your user IDs and passwords.

Tip: If you don't see the Host Connections view, from the menu bar, click Window> Manage Connections to open the Host Connections view.

Procedure1. In the Host Connections view, click Add and select z/OS Connect Enterprise

Edition.2. Specify the following information:

Table 43. Adding a server connection

Field Description

Name A descriptive name for the server connection.

Host name The name or the IP address of the server.

Port number The port number.

Select the Secure connection (TLS/SSL) checkbox for secureconnections.

Connection timeout The amount of time in milliseconds the API Editor will wait fora successful connection to be established with the z/OSConnect EE server before timing out. The default is 30 secondsunless specified otherwise in the z/OS Connect EE preferenceswindow. A value of 0 indicates to wait forever.

Read timeout The amount of time in milliseconds the API editor will readresponse data from the z/OS Connect EE server before timingout. The default is 30 seconds unless specified otherwise in thez/OS Connect EE preferences window. A value of 0 indicates towait forever.

Tip: You can change the default connection timeout and read timeout values.From the main menu bar, click Window > Preference > z/OS Connect EE, andspecify your default timeout values.


3. Click Save and Connect to save the definition and connect to the server. Youwill be prompted to either specify an existing credential to use, or create acredential at this time. To add a credential, click Add in the Credentials section.See Defining connection credentials in IBM Explorer for z/OS documentation.

Note: If client authentication is enabled on the server, this user credential isused for authorization. A trusted client certificate must be configured for userauthentication by selecting Window > Preferences > Explorer > Certificatemanagement. For more information, see “Configuring client certificates forserver connections.” This feature requires V2.0.4.5 or later of the API Editor.

4. After you select an existing credential or create a new one, click OK to use thecredential to connect.

Results

The defined host connection shows up in the z/OS Connect EE Servers view.Deployed API packages are listed under the APIs folder.Related concepts:“Setting preferences for the API Editor” on page 215You can specify your preferences for default behaviors for host connections, APIdeployment, and logging in the preferences window.

Configuring client certificates for server connectionsGenerate a client certificate and configure the Eclipse preferences to send in thecertificate from the API Editor to the z/OS Connect EE server. On the server side,import the client certificate into the server truststore and disable failover to basicauthentication.

Before you begin

Note:

v Support for client certificate configuration requires API Editor V2.0.4.5 or later.v The embedded Swagger UI supports only basic authentication. Client

authentication is not supported.

If SSL is enabled on the z/OS Connect EE server (requireSecure attribute inserver.xml is set to true), and a trusted client certificate is not sent in forauthentication, upon connection to the server, you get an "HTTP 403 Forbidden"error.

To connect to the server from the API Editor, generate a client certificate first andimport it into the truststore on the server.1. Generate your client certificate.

This certificate is sent to the server for authentication. Use a tool such asKeytool to create a keystore and then export the client certificate from thekeystore. The following example shows the keytool command to create akeystore called myclient.keystore.ks:keytool -genkey -alias myclient.keystore -dname"CN=API editor client Keystore, OU=IBM Systems z, O=IBM, C=US"-keyalg RSA -keypass mypassword -storepass mypassword-keystore <path_to>/myclient.keystore.ks


https://www.ibm.com/support/knowledgecenter/SSBDYH_3.0.1/com.ibm.zexpl.ug.zosexplorer.doc/topics/tasks/task_configure_credentials.html

Then export the client certificate (myclient.keystore.cer) from the clientkeystore:keytool -export -alias myclient.keystore -storepass mypassword-file <path_to>/myclient.keystore.cer -keystore <path_to>/myclient.keystore.ks

2. Transfer the client certificate to a location accessible to the z/OS Connect EEserver.

3. On the z/OS Connect EE server, import the client certificate into the servertruststore.The following example shows the keytool command to import the clientcertificate into the server truststore.keytool -import -v -trustclientcerts -alias apieditor.client-file myclient.keystore.cer -keystore "<path_to>\server.truststore.ks"-keypass mypassword -storepass mypassword

4. Modify the server.xml file to ensure the following information is specified.v Ensure the allowFailOverToBasicAuth attribute of the webAppSecurity tag is

set to false.<webAppSecurity allowFailOverToBasicAuth="false"/>

Note: When you create an IMS service in IMS Explorer, theallowFailOverToBasicAuth attribute must be set to true. If clientauthentication is required by the server, change this attribute to false whenyou are designing and testing your APIs.

v The location and the password for the server truststore is specified.For more information, see Configuring your web application and server forclient certificate authentication (WebSphere Application Server for z/OSLiberty).

Procedure

Configure the API Editor with the client certificate.1. Open the Preferences window by clicking Window > Preferences on the main

menu.2. Expand Explorer and click Certificate management.3. In the Keystore details section, next to the File name field, enter the full path

and name of the file where the certificates are saved. You can also clickBrowse to navigate to the client key, select the client key, and click Open.

4. In the Pass phrase field, enter the password for this keystore.5. In the Store type field, select the correct store type.6. If you are using a smart card, select Use Windows cryptography services for

the Windows operating system, which uses the standard Windowscryptography mechanism. To use a PKCS11 driver (mandatory on Mac OS andLinux operating systems), select Use PKCS11 driver and specify the driverpath and PIN.

7. If you are instructed by your network administrator, select the correct protocolfor your organization in the Secure socket protocol field.

8. Click Apply and OK to save your settings and close the window.9. Add a new credential for the client certificate for host connections.

a. Click Window > Manage Connections to open the Host Connections view.b. Click Add in the Credentials section and select Certificate from Keystore.c. Specify the user ID that is associated with the certificate.


https://www.ibm.com/support/knowledgecenter/en/SS7K4U_liberty/com.ibm.websphere.wlp.zseries.doc/ae/twlp_sec_clientcert.html

d. Choose the appropriate certificate from the list and click OK.10. Select your z/OS Connect Enterprise Edition connection in the Connections

section, right-click, and select Set Credentials.11. Select the credential you just defined, and click Connect.

Results

The client certificate is used for server connection authentication, allowing theserver to use the user ID that is specified for the host connection for authorizationbased on the defined security role.Related tasks:“Connecting to a z/OS Connect EE server” on page 216Create a host connection to the z/OS Connect EE server to view, deploy, start, orstop an API.Related information:

Defining connection credentials (IBM Explorer for z/OS)For more information about defining connection credentials, see IBM Explorer forz/OS documentation.

Creating a REST APICreate a REST API for your z/OS Connect EE services by exporting your serviceas a service archive (SAR). Import the service archive into your z/OS Connect EEAPI project in the editor to model and define your API.

Generating a service archiveYou must first generate service archive (SAR) files from z/OS Connect EE servicesfor which you want to create APIs.

About this task

A SAR file contains the information that is needed by a z/OS Connect EE serviceprovider to install and provide the service, and to enable the service as a JSONasset. Service archives are required for service interface mapping that uses thez/OS Connect EE API Editor to map HTTP headers, path parameters, and queryparameters with fields in the JSON schema of a z/OS Connect EE service.

Procedure1. Generate the service archive (SAR) file for your service by using the Build

Toolkit. For more information about the Build Toolkit, see Chapter 10, “Buildinga Service Archive (SAR) by using the Build Toolkit,” on page 193. Alternatively,you can export your z/OS Connect EE services as service archive (SAR) files inthe supported tool for each of the z/OS Connect EE service providers.v For CICS access through WOLA, use the BAQLS2JS and BAQJS2LS utilities

with the SERVICE-ARCHIVE and SERVICE-NAME parameters specified.v For IMS, use IMS Explorer (in IMS Enterprise Suite V3.2).

2. In z/OS Connect EE, import your SAR files in a project in the Project Explorerview. You will import the SAR files into your API project. You will map pathand methods to the services that the SAR files contain.

What to do next

Create an API project.


https://www.ibm.com/support/knowledgecenter/SSBDYH_3.0.1/com.ibm.zexpl.ug.zosexplorer.doc/topics/tasks/task_configure_credentials.html

http://www.ibm.com/support/knowledgecenter/SS9NWR_3.2.0/com.ibm.ims.explorer32.doc/wb_export_sar.htm

Creating an API projectYou can create a project by opening the z/OS Connect EE API Project wizard whenyou are in the z/OS Connect Enterprise Edition perspective.

Before you begin

Switch to the z/OS Connect Enterprise Edition perspective.1. From the main menu, select Window > Open Perspective > Other. The Select

Perspective wizard opens.2. Select z/OS Connect Enterprise Edition.

Procedure

To create a new z/OS Connect EE API project in the z/OS Connect EnterpriseEdition perspective:1. From the main menu bar, click File > New > z/OS Connect EE API Project.2. In the z/OS Connect EE API Project wizard, enter the project properties, and

click Finish to create the project.

Project property Description

Project name Unique alphanumeric name for your project.

API name The name of your API. If the API namematches an existing service name, the APItakes precedence over the service when therequest is connected through IBM APIConnect.

Base path The unique basePath attribute that specifiesthe root of all the resources in this API.

v If the same basePath is specified indifferent API packages, then the first isinstalled successfully and all others fail.

v If the API base path overlaps with theinvokeURI of a service, the API is invokedrather than the service.

Description Description for your API.

The API project is created in the Project Explorer view. The API package.xmlfile opens in the API Editor where you can model your API.

3. Import your service archive (SAR) files. Right-click an API project and clickz/OS Connect EE > Import z/OS Connect EE Services.

What to do next

Model your API.

Modeling an API with the API EditorYou can model your API by adding paths, creating methods, and associating themethods with related z/OS Connect EE services.

Before you beginv Generate a service archive.v Create an API project.


Procedure1. In the Project Explorer view, open the package.xml file located in your API

project. The z/OS Connect EE API Editor opens.2. In the z/OS Connect EE API Editor, specify a Path. You can add a URI path

parameter with curly brackets. For example, the following path uses patID as apath parameter:/Patient/{patID}

You can add paths by selecting the

icon next to Path.

Tip: When you save your changes (Ctrl + S), package.xml is updated, and thechanges are reflected in swagger.json.

3. Add methods.

You can add methods by selecting the

icon next to Methods.

HTTP method Description

POST Adds a new instance of the specifiedresource.

GET Retrieves details about the specified resource.

PUT Updates information for the specifiedresource.

DELETE Deletes information for the specifiedresource.

4. Assign a service to a method by clicking Service, then select a z/OS ConnectEE service or import one from your Workspace or File System.

Tip: If a service is changed after the API is created, upon re-importing thechanged service, the impact of the changes is analyzed and reported. For moreinformation, see “Re-importing changed services” on page 225.

What to do next

Define HTTP-to-JSON mapping.

Defining HTTP-to-JSON mappingThe next step in modeling your API is to map HTTP headers, path parameters,and query parameters with fields in the JSON schema of a z/OS Connect EEservice. The JSON schema is the metadata that is used to communicate with theservice.

Procedure1. In the Project Explorer view, open the package.xml file that is in your API

project. The z/OS Connect EE API Editor opens.2. In the z/OS Connect EE API Editor, click Mapping on a method to map fields

in the JSON schema of the service, and then select Open Request mapping(HTTP request) or Open Response mapping (HTTP response). The mappingeditor opens.

3. Create HTTP headers and query parameters.v To create an HTTP header, right-click HTTP Headers > Add HTTP Header.


v To create a query parameter, right-click Query Parameters > Add QueryParameter.

4. Map HTTP headers, path parameters, and query parameters with the serviceJSON schema by dragging the header or parameter to a field in the JSONschema.

5. Assign any static values or remove any unnecessary field from the serviceJSON schema.

Mapping actions Description

Assign Assigns a static value to a field in the serviceJSON schema for the HTTP request or HTTPresponse.

Remove Hides the value from the HTTP request orHTTP response.

Task Allows adding a description and detaileddocumentation for communication purposes.

Note: With V2.0.1.1 of the editor or later, path and query parameters inherit theminimum, maximum, minLength, maxLength, exclusiveMinimum, andexclusiveMaximum properties of the service field to which they are mapped.To use the Assign mapping action:a. Right-click the field to be assigned and select Add Assign transform.b. Select the Assign box to open the Properties view.c. In the General tab of the Properties view, type the required value into the

Value field.d. Optionally, add a description in the Documentation tab.

Unmapped fields in the request JSON schema remain unchanged and get theirvalues from the body of the HTTP request.

Example

In the following example, a healthcare service provider is developing an API toallow their patients to look up their registration information based on their patientID.

In the mapping editor, an API developer created and mapped the following HTTPheader, path parameter, and query parameters for the GET HTTP method:

HTTP header: X_TrackingIDEnables the service caller to provide the routing information(CA_ROUTING_CODE) for a patient with the HTTP header variable calledX_TrackingID.

Path parameter: patIDEnables the service caller to set the value for CA_PATIENT_ID as theprovided patID value.

Query parameter: userIDEnables the service caller to set the value for CA_USERID as the provideduserID value.

Query parameter: zipCodeEnables the service caller to set the value for CA_POST_CODE as theprovided zipCode value.


What to do next

Deploy an API.

Deploying an API in the API EditorAfter you define your API, you can deploy the API directly to your z/OS ConnectEE server from the API Editor.

Before you begin

By default, deployed APIs are automatically started. You can change this behaviorby configuring the z/OS Connect EE preferences:1. From the main menu bar, click Windows > Preferences.2. In the Preferences wizard, select z/OS Connect EE.3. Make your changes and click Apply and then OK.

Make any final edits to the Swagger document. For example, you might want toadd security and authentication requirements. Manual changes to the Swaggerdocument in the API editor are preserved when saved. To edit the Swaggerdocument by using your preferred JSON editor, the location of the Swaggerdocument can be found by right-clicking the api-docs/ folder of your API projectin the Project Explorer view and selecting Properties. The location of the Swaggerdocument is displayed in the Location field.

Ensure that you are connected to the server. For more information, see“Connecting to a z/OS Connect EE server” on page 216.

About this task

You can deploy an API directly from the package editor by clicking the Deploy

API to z/OS Connect EE Server button ( ) in the corner.

An example mapping configuration for the HTTP request and request JSON schema.


You can also deploy the API from Project Explorer view, or by using the apideploycommand on the server.

Procedure

To deploy the API from the Project Explorer view:1. In the Project Explorer view, select one or more API projects and right-click to

select z/OS Connect EE > Deploy API to z/OS Connect EE Server.2. In the Deploy API window, select the server to which to deploy the APIs.3. If an API of the same name exists and you want to overwrite it, select the

Update existing APIs check box.4. Click OK.

Alternatively, if you need to deploy the API by using the apideploy commandon the server:a. Right-click the API project and click z/OS Connect EE > Export z/OS

Connect EE API Archive to save the API as an API archive (AAR) file to alocation of your choice.

b. Transfer the API archive file in binary mode to a file system that the APIDeployment utility can access.

c. In an OMVS shell, issue the apideploy -deploy command. For moreinformation, see .

Results

Deployment result is reported. Errors that occur during the deployment arerecorded in the Problems view. A deployed API is automatically started unlessspecified otherwise in the z/OS Connect EE preferences window.

Tips:

v To see the newly deployed APIs on the server, in the z/OS Connect EE Serversview, right-click the server, and select Refresh.

v As a software source code management best practice, save a copy of the APIproject in your source control management system.

What to do next

Examine and test the API directly within the API Editor.Related concepts:“Setting preferences for the API Editor” on page 215You can specify your preferences for default behaviors for host connections, APIdeployment, and logging in the preferences window.Related tasks:“Generating an API archive” on page 225To deploy the API by using the API Deployment utility (apideploy -deploycommand), you need to export your API project into an API archive (AAR) file.

Editing an existing APITo edit an existing API in the editor, double-click the package.xml file in yourproject folder in the Project Explorer view. To edit the request mapping or responsemapping for a method, double-click the request.map or response.map file for themethod in the /api folder of your project.


Re-importing changed servicesIf a service is modified after an API is created, when it is re-imported into theproject, the impact of the changes is analyzed. The impact is reported, andmapping problems are recorded in the Problems view.

About this task

You can re-import one or more services in one of two ways:v Click Service next to a method.v Right-click the API project in the Project Explorer and click z/OS Connect EE >

Import z/OS Connect EE Services.

Important: All APIs in the project that are associated with the re-imported servicesare impacted.

In the impact analysis dialog that is displayed, examine the impact. If the impacton the existing mappings is as expected, click OK to re-import the services.

The impacts are reported in the following categories:

Errors An existing mapping is broken. A broken mapping occurs when a fieldthat was involved in an explicit Move or Assign transform is removed orrenamed in the changed service. The broken mapping is highlighted in themapping editor when you open the request or response mapping.

WarningsA warning is a result of one of the following conditions:v A field that was not explicitly involved in any Move or Assign transform

but was implicitly passed through the request or response body is nolonger available in the changed service.

v The data type of a field is changed.v A new field is added.

Mapping issues are recorded in the Eclipse built-in Problems view to assistproblem resolution.

Generating an API archiveTo deploy the API by using the API Deployment utility (apideploy -deploycommand), you need to export your API project into an API archive (AAR) file.

Before you begin

Make any final edits to the Swagger document. For example, you might want toadd security and authentication requirements. Manual changes to the Swaggerdocument are preserved when saved.

Procedure1. In the Project Explorer view, right-click an API project and click z/OS Connect

EE > Export z/OS Connect EE API Archive.2. Specify the location where you want to save this API archive file.


Results

The API package is saved as a .aar file.

What to do next1. Transfer the file in binary mode to the host system where the API Deployment

utility on the z/OS Connect EE server can access.2. On the server, issue the apideploy -deploy command to deploy the API.Related information:

Examining, testing, starting and stopping an APIYou can examine, test, start, and stop an API in the z/OS Connect EE Servers view.

Before you begin

Switch to the z/OS Connect Enterprise Edition perspective.

Ensure that you are connected to the server. For more information, see“Connecting to a z/OS Connect EE server” on page 216.

About this task

The z/OS Connect EE Servers view in the z/OS Connect Enterprise Editionperspective provides a list of defined host connections and the APIs that aredeployed on the servers.

Procedure1. In the z/OS Connect EE Servers view, ensure that the server is connected. If the

server is not connected, right-click the server and select Connect.2. Expand the server and the APIs folder to see all APIs that are deployed to the

server.3. For each API, you can examine its status, description, and documentation. You

can also start, stop, or remove it.v To examine the status, version number, api URL, description, and

documentation of an API, click the API to see the information in theProperties view.

v To examine and test the operations in the API in Swagger UI, double-clickthe API or right-click the API and select Open in Swagger UI.

Important: Before using the "Try it out!" button in Swagger UI, if your z/OSConnect EE server connection is secure (SSL/TLS), install and trust theserver's certificate by using Certificate Manager (Start > Run and selectcertmgr.msc) in Windows, or by using Keychain Access in MacOS. BecauseSwagger UI runs on a workstation rather than the server where the API ishosted, cross-origin resource sharing (CORS) must be enabled on the server,and the client (Swagger UI) must accept the self-signed certificate. For moreinformation about CORS and related configuration, see “Installing andtrusting a self-signed certificate for Swagger UI” on page 227.

Tips:


– You can disable the prompt about a valid TLS certificate is required. Fromthe main menu bar, click Window > Preference > z/OS Connect EE, andspecify your choice.

– If you prefer to open the Swagger UI outside of the editor in an externalbrowser, configure your Eclipse preferences by selecting Window >Preference > General > Web Browser, and specify your browser of choice.

v To temporarily stop further requests through the API, right-click the API andselect Stop API.

v To restart the API, right-click and select Start API.v To remove an API, the API must be stopped first. After an API is stopped,

right-click and select Remove API.

Tip: You can set the preferences to automatically stop an API upon removalor to automatically start an API upon deployment in the z/OS Connect EEpreferences window.

Related concepts:“Setting preferences for the API Editor” on page 215You can specify your preferences for default behaviors for host connections, APIdeployment, and logging in the preferences window.

Installing and trusting a self-signed certificate for Swagger UITo use the embedded Swagger UI, because it runs on a workstation rather than theserver where the API is hosted, cross-origin resource sharing (CORS) must beenabled on the server, and the client (Swagger UI) must accept the self-signedcertificate.

Before you begin

For more information about enabling CORS on the z/OS Connect EE server, see“Configuring Cross-Origin Resource Sharing on a z/OS Connect Enterprise EditionServer” on page 161.

About this task

Swagger UI does not provide diagnostics when the "Try It Out!" function fails dueto a CORS issue. CORS is enforced by the browser and Swagger UI does not havethe visibility to the interaction between the browser and the resource (server).

When you use Swagger UI in the API Editor to invoke an API over a secureconnection, if the API is hosted on a server with a self-signed or invalid certificate,you would encounter one of the following issues:v The browser prompts you whether to accept or decline the self-signed or invalid

certificate. If you accept, the request is sent to the server. If you decline, therequest is not sent and Swagger UI indicates that no response is received. Youare prompted again after restarting the browser.

v The browser does not prompt you at all, the request is not sent to the server,and Swagger UI indicates that no response is received.

By default, when you open Swagger UI from within the API Editor, the Eclipseinternal web browser is used. Installing the certificate into your external webbrowsers might not suffice. Installing and trusting the certificate at the operatingsystem level is the best way


Procedure

To install and trust a self-signed certificate, export the server certificate from theserver and import it to the workstation where the API Editor is running:1. On the z/OS Connect EE server, export the server certificate.v If the z/OS Connect EE server is using a SAF key ring:

a. On the server, generate a Certificate Authority (CA) root certificate. Forexample:RACDCERT CERTAUTH GENCERT SUBJECTSDN(CN(’ZCEE Sample CA’) O(’MYCOM’) OU(’MYORG’)) SIZE(1024)WITHLABEL(’ZCEE-Sample-Certification’) TRUSTNOTAFTER(DATE(2021/12/31)

b. On the server, create a server certificate, signed by the CA. For example:RACDCERT ID (ZOSCONN) GENCERT SUBJECTSDN(CN(’zceeserver.mycom.com’)O(’MYCOM’) OU(’MYORG’)) SIZE(1024)SIGNWITH (CERTAUTH LABEL(’ZCEE’)) WITHLABEL(’ZCEE-Server’) NOTAFTER(DATE(2021/12/31))

c. Create a RACF key ring.RACDCERT ADDRING(ZCEE.KEYRING.wsc) ID(ZOSCONN)

d. Connect the server certificate to the key ring.RACDCERT ID(ZOSCONN) CONNECT (RING(ZCEE.KEYRING.wsc) LABEL(’ZCEE-Cert’) CERTAUTH)RACDCERT ID(ZOSCONN) CONNECT (RING(ZCEE.KEYRING.wsc)LABEL(’ZCEE-Server’) DEFAULT

e. Update the server configuration in server.xml to point to the newlycreated key ring.<ssl id="defaultSSLConfig" keyStoreRef="racfKeyStore"sslProtocol="SSL_TLS"serverKeyAlias="ZCEE-Server" />

f. Export the certificate and save it to the USS file system. For example:RACDCERT CERTAUTH EXPORT(LABEL(’ZCEE-Cert’))DSN(’ZCONN.CERT.LIBCERT’) FORMAT(CERTDER) PASSWORD(’password’)OPUT ’ZCONN.CERT.LIBCERT’ ’/u/acrand/zcee/zcee.certAuth.cer’ BINARYCONVERT(NO)RACDCERT ID(ZOSCONN) EXPORT(LABEL(’ZCEE-Server’)) DSN(’ZCONN.CERT.SERVER.P12’) FORMAT(PKCS12DER)PASSWORD(’password’)OPUT ’ZCONN.CERT.SERVER.P12’ ’/u/devuser1/zcee/zcee.server.p12’BINARY CONVERT(NO)

v If the z/OS Connect EE server is using a keystore:a. Locate the keystore for your z/OS Connect EE server. The default

location of the keystore is /var/zosconnect/servers/serverName/resources/security/keys.jks

b. Extract your server certificate from its keystore. Use the Java keytool toextract the certificate into a file named testserver.cer. Note that thevalues of the parameters might differ for your configuration.keytool -export -alias default -file testserver.cer-keystore keys.jks -storepass zosConnect -storetype jks

The message "Certificate stored in file testserver.cer" is displayed.2. On your workstation, complete the certification configuration steps for your

operation system.v For Windows, take the following steps to configure the certificates.

a. Open a command prompt or PowerShell, type certmgr.msc, and pressEnter.

b. Right-click Trusted Root Certification Authorities and select All Tasks >Import.

c. Click Next when the Certificate Import Wizard appears.


d. On the "File to Import" page, specify the testserver.cer certificate file(created in Step 2).

e. Click Next to advance to the Certificate Store page.f. Verify that Place all certificates in the following store and Trust Root

Certification Authorities are both selected.g. Click Next, and after confirming the details of the import, click Finish.h. When prompted if you want to continue given that the certificate cannot

be verified (because it is self-signed), click Yes.i. Restart the API Editor and any web browsers that might be running.

v For MacOS, take the following steps to configure the certificates.a. Open the Keychain Access application.b. Select System in the Keychains view.c. Select Certificates in the Category view.d. Select File > Import items.e. Specify the testserver.cer certificate file (created in Step 2). You might

be prompted for your user name and password to allow modification ofthe system keychain.The certificate is now displayed in the list, with the CN value of thecertificate as its name (for example, testserver.example.org).

f. Double-click the certificate to update its settings.g. In the Trust section of the displayed dialog, for the When using this

certificate field, select Always Trust and close the dialog. You might beprompted for your user name and password to allow modification of thecertificate settings.

h. Restart the API Editor and any web browsers that might be running.Related information:“Configuring Cross-Origin Resource Sharing on a z/OS Connect Enterprise EditionServer” on page 161z/OS Connect EE supports Cross-Origin Resource Sharing (CORS).

Developing applications with Swagger documentsThe Swagger document that is generated by the z/OS Connect EE API Editor canbe examined and exposed in various ways.

A range of third-party tools are available for you to use with Swagger documents.

Swagger UIWith Swagger UI, you can visualize and test a REST API that is definedwith Swagger from any web browser. The built-in testing functions let yougraphically explore the APIs, test the APIs, and inspect the results. Formore information, see GitHub: Swagger UI.

Swagger CodegenWith Swagger Codegen, you can generate a Software Development Kit(SDK) in various languages, including Java, Objective-C, PHP, and Python,from a Swagger document for a REST API. You can use the resulting SDKto test the API in real time with a generated sample server implementationbefore you fully implement the API. For more information, see GitHub:Swagger Code Generator.

The editor.swagger.io site, for example, provides Swagger Editor, Swagger UI, andSwagger Codegen.


https://github.com/swagger-api/swagger-ui

https://github.com/swagger-api/swagger-codegen

https://github.com/swagger-api/swagger-codegen

http://editor.swagger.io/

Documenting your API using SwaggerWhen you have created your API, you can expose the API documentation to users.

You can provide this documentation with Swagger. For more information, seeIntroduction to Swagger. For details in the Swagger specification, see SwaggerRESTful API Documentation Specification.

A RESTful administration interface for an API is available on the URI/<apiBasePath>/api-docs and returns the Swagger document for the API, which istypically generated using the z/OS Connect EE tooling. API Swagger documentsare only returned if the API has been correctly initialized:

HTTP methodGET

URI /<apiBasePath>/api-docs

Note: The only allowed methods for the URI are GET and OPTIONS.

Return bodyReturns the Swagger document as a JSON string with an HTTP status codeof 200 OK.

The host and port values are added to the returned Swagger document,and override a host entry specified in the Swagger document on disk. Thehost name and port are derived from the request string.

Errors For any call using a HTTP method other than GET and OPTIONS, a HTTPstatus code of 405 Method Not Allowed is returned.

If the <apiBasePath> does not exist or cannot be accessed, a HTTP statuscode of 404 Not Found is returned.

For more information, see Swagger RESTful API Documentation Specification.


http://swagger.io/

http://swagger.io/specification/



Chapter 12. Administering SARs

Use this information to learn how to manage your service archives.

Service archives (SARs) are deployed to a z/OS Connect EE server by copyingthem to a location which is defined in the server.xml configuration file.

Note: Only SAR files that are created by the build toolkit for the REST Clientservice provider are suitable for SAR deployment.

Automated SAR managementDeploy and undeploy your service archives automatically when you add orremove them from the services folder.

You can configure z/OS Connect EE to deploy a service archive automaticallywhen you copy your SAR file to the location where your services archives arestored. For example, resources/zosconnect/services.

When you remove the SAR file from the folder, the service is automaticallyundeployed.

The service location is monitored for changes to the SARs. You can control howand when z/OS Connect EE reacts to these changes by setting the updateTriggerand pollingRate attributes of the zosconnect_services element of the server.xmlconfiguration file. The default value for pollingRate is 5000 mSecs. For moreinformation, see “zosconnect_services” on page 306.

Note: Service definitions remain in the server.xml configuration file after youdelete or uninstall a SAR file.

When you copy a SAR file to the SAR folder, ensure that the service name isunique within the folder. For example, if test1.sar exists in the folder andcontains a service named test, then it must be removed before you copytest2.sar, which also contains a service named test. If both files are present whenz/OS Connect EE starts, the service that is deployed is that of the first file that isread. When the other file is read, an error message is returned that the service isalready deployed.

To update a service, replace the SAR file in the SAR folder. The file must have thesame name. If the updateTrigger and pollingRate attributes of thezosconnect_services element are set, the service is installed automatically whenthe folder is polled.

If you copy a SAR to the directory where a service of the same name is alreadyconfigured, the new service will not be installed. When the server is restarted, thenew service might install first, but this is unpredictable.

Overriding SAR propertiesControl the properties of a SAR when you deploy it.


When you deploy a SAR that was supplied by a Service Provider, certainproperties can be overridden.

Properties are specified as nested elements inside a service element. For example:<service name="myService" requireAuth="true" requireSecure="true" runGlobalInterceptors="false">

<property name="name1" value="value1"/><property name=’name2’ value=’value2’ />.....<property name=’namex’ value=’valuex’ />

</service>

You must manually edit properties in the server.xml configuration file.

If the SAR file is deleted or moved, the properties remain in the configuration fileand must be manually removed.


Chapter 13. Administering APIs

Use this information to learn how to manage your APIs.

APIs can be deployed to a z/OS Connect EE server using the API deploymentutility, the API Editor, or the RESTful administration API. The API Editor orRESTful administration interface can also be used to get information on the APIsthat have been deployed and to stop an API from accepting requests.

Automated API managementDeploy and undeploy your APIs automatically when you add or remove themfrom the API folder.

You can configure z/OS Connect EE to deploy an API automatically when youcopy your AAR file to the location where your APIs are stored. For example,resources/zosconnect/apis.

When you remove the API from the folder, it is automatically undeployed.

The API location is monitored for changes to the API. You can control how andwhen z/OS Connect EE reacts to these changes by setting the updateTrigger andpollingRate attributes of the zosconnect_zosConnectAPIs element of theconfiguration file server.xml. The default value for pollingRate is 5000 mSecs. Formore information, see “zosconnect_zosConnectAPIs” on page 309.

Note: API definitions remain in the server.xml configuration file after you deleteor uninstall an API. This situation causes a warning message to be written to thelog until the API is reinstalled.

When you copy an AAR file to the API folder, ensure that the API name is uniquewithin the folder. For example, if test1.aar exists in the folder and contains theAPI test, then it must be removed before you copy test2.aar, which also containsan API named test. If both files are present when z/OS Connect EE starts, one ofthe APIs is deployed. When the other file is read, an error message is returned thatthe API is already deployed.

To update an API, replace the AAR file in the API folder. The file must have thesame name. If the updateTrigger and pollingRate attributes of thezosconnect_zosConnectAPIs element are set, the API is installed automaticallywhen the folder is polled.

Using the API Deployment utilityUse this information to learn how to deploy, secure, and maintain your APIs.

Securing access to APIs

Before deploying an API, ensure that the underlying service is available. Calling anAPI might fail if the called URI is not defined in the API, or if there is an error inthe underlying service. The failure will follow the standard HTTP rules.Related tasks:


“Deploying an API”You must deploy an API to make it available to users.“Undeploying an API” on page 235When you undeploy an API, you remove it from the system and make itunavailable to users.Related reference:“apideploy command syntax” on page 328Deploy or undeploy APIs

Deploying an APIYou must deploy an API to make it available to users.

Before you begin

Note:

v To issue the API Deployment utility commands, you must be a z/OS ConnectEE server administrator with access to the OMVS shell.

v You can also deploy an API directly from the z/OS Connect EE API Editor. Seeinstructions in “Deploying an API in the API Editor” on page 223.

Follow these instructions to deploy an API using the API Deployment utilityv The API archive file must already reside on a UNIX System Services file system

on the same z/OS LPAR where z/OS Connect EE is installed.v When transferring the API archive file to the file system, use binary mode.v After the API archive file is transferred, ensure that the owner of the file has

read and write permission (a minimum of 644 by using the UNIX SystemServices chmod command).

v You must be a z/OS Connect EE server administrator to issue the APIDeployment utility commands.

v The API deployment directory must already exist. The user that issues the APIDeployment utility must have the permission to write to the API deploymentdirectory.

v The apideploy command is a supplied z/OS UNIX command, so theadministrator must have access to the OMVS shell to use the command.

Procedure1. Go to the <installation_path>/bin directory.2. Issue the following command:

apideploy –deploy –a <path_to_apiPackage.aar> –p <path_to_api_location>

Specify the relative or absolute path to the API archive file (-a) and to the APIdeployment location (-p). For example,

apideploy –deploy –a ./myApi/goodHealth.aar -p <WLP_USER_DIR>/servers/<serverName>/resources/zosconnect/apis

Results

The API that is defined in the API archive file is saved to the z/OS Connect EEserver directory. A directory that is based on the API name is created in the APIdeployment directory.


What to do next

Depending on the configuration of your server, you might need to restart theserver before the server is ready to process HTTP requests for the related z/OSConnect EE services from a REST client.Related reference:“apideploy command syntax” on page 328Deploy or undeploy APIs

Undeploying an APIWhen you undeploy an API, you remove it from the system and make itunavailable to users.

Before you begin

Follow these instructions to undeploy an API using the API Deployment utility.

Note:

1. To issue the API Deployment utility commands, you must be a z/OS ConnectEE server administrator with access to the OMVS shell.

2. You can also undeploy an API directly from the z/OS Connect EE API Editor.In the z/OS Connect EE Servers view in the editor, right-click the API andselect Stop API to stop the API first. Then right-click the API and selectRemove API.

Procedure1. Go to the <installation_path>/bin directory.2. Issue the following command:

apideploy –undeploy –a <path_to_apiPackage.aar> –p <path_to_deploy_location>

Specify the relative or absolute path to the API archive file (-a) and to the APIdeployment location (-p). For example,

apideploy –undeploy –a ./myApi/goodHealth.aar -p <WLP_USER_DIR>/servers/<serverName>/resources/zosconnect/apis

.

Results

The API that is defined in the API archive file is undeployed. The directory withthe name of the API is removed from the API deployment directory.

What to do next

Depending on the configuration of your server, you might need to restart theserver for the changes to take effect.Related reference:“apideploy command syntax” on page 328Deploy or undeploy APIs

Using the RESTful administration interfaceThe administration interface for APIs is available in paths under /zosConnect/apisand provides meta-data for the APIs.

Chapter 13. Administering APIs 235

A Swagger document describing the RESTful administration interface for z/OSConnect EE is available on the URI /zosConnect/api-docs.

Notes for all callsv All successful calls return HTTP status code 200 unless otherwise specified.v URLs returned by any of the calls contain the protocol, server, and port from the

request.v Any call using a HTTP method with a URI not mentioned in these topics will

return an error 405 Method Not Allowed.v If an error occurs while processing a request, an appropriate HTTP status code

and the following JSON will be returned:{

"errorMessage": "{message}","errorDetails": "{details}"

}

Note: errorDetails is optional and will only be returned for some errorscenarios.

GET a list of APIsYou can use the HTTP method GET to obtain a list of the z/OS Connect EE APIsinstalled in the runtime.

HTTP methodGET

URI /zosConnect/apis

DescriptionGets a list of the z/OS Connect EE APIs installed in the runtime, includingsome basic information and a URL for more detailed information. APIs areincluded in the list whether they are started or stopped.

SecurityUsers with Administrator, Operator or Reader authority can get a list ofAPIs; users with Invoke authority cannot.

Note: A user must be a member of a global group to be able to see all theresources. For more information about user authorization, see “Overviewof z/OS Connect EE security” on page 177.

Return body{

"apis":[{"name":"{name}","version":"{version}","description":"{API description}","adminUrl":"http(s)://{host}:{port}/zosConnect/apis/{name}"

},... repeats

]}

where adminUrl contains the URL where you can get more details for thespecific API. For more information, see “GET details of an API” on page237.


Example body{

"apis":[{"name":"HospitalAPI","version":"1.0","description":"API for Hospital app","adminUrl":"http://localhost:9080/zosConnect/apis/HospitalAPI"

}]

}

GET details of an APIYou can use the HTTP method GET to obtain information about a specific z/OSConnect EE API.

HTTP methodGET

URI /zosConnect/apis/{APIname}

DescriptionGets the details of the requested z/OS Connect EE API.

SecurityUsers with Administrator, Operator or Reader authority can get details ofan API; users with Invoke authority cannot.

Return body{

"name":"{name}","version":"{version}","description":"{API description}","status": "Started|Stopped","apiUrl":"http(s)://{host}:{port}/{basePath}""documentation": {

"swagger":"http(s)://{host}:{port}/{basePath}/api-docs"}

}

where:v apiUrl is the URL you use to invoke the API.v swagger contains the URL where the Swagger document for the API can

be obtained. For more details see “Documenting your API usingSwagger” on page 230

Example body{

"name":"HospitalAPI","version":"1.0.0","description":"API for Hospital app","status": "Started","apiUrl":"http://localhost:9080/hospital","documentation": {

"swagger":"http://localhost:9080/hospital/api-docs"}

}

Errors The following error can occur:404 Not foundThe API was not found.


GET a Service Archive (SAR)You can use the HTTP method GET to retrieve a service archive for a specificservice.

Note: This function is supported only by IMS

HTTP methodGET

URI /zosConnect/services/{serviceName}?action=getArchive

DescriptionGets a service archive file, which is used to create a z/OS Connect EE API.

SecurityUsers with Administrator, Operator or Reader authority can get an archive,users with Invoke authority cannot.

Return bodyReturns the service archive file, with the Content-Type for the response setto application/zip.

Errors The following error can occur::204 No contentThe Service provider returned null to signal it does not intend to support creating service archives in the runtime.

Deploying an APIYou must deploy your API to make it available for use.

You can use the HTTP method POST to deploy a z/OS Connect EE API.

HTTP methodPOST

URI /zosConnect/apis

DescriptionDeploys an API into z/OS Connect EE.

SecurityUsers with Administrator or Operator authority can deploy an API, userswith Invoke or Reader authority cannot.

Request bodyThe API package file. The Content-Type for the request is application/zip.

Response body{

"name": "{name}","version": "{version}","description": "{API description}","status": "{Started|Stopped}","apiUrl": "http(s)://{host}:{port}/{basePath}","documentation": {"swagger":"http(s)://{host}:{port}/{basePath}/api-docs"

}}

Example response body{

"name": "testHealthApi2","version": "1.0.0""description": "Health API","status": "Started",


"apiUrl": "http://192.168.99.100:9080/testHealthApi2","documentation": {

"swagger": "http://192.168.99.100:9080/testHealthApi2/api-docs"}

}

Errors The following errors can occur:400 Bad requestInvalid or missing API package

409 ConflictPackage conflicts with the existing z/OS Connect configuration

415 Unsupported media typeContent-Type is not application/zip

500 Internal Server ErrorServer issue, may require administrator intervention.

Setting the initial status of a new API

When you deploy a new API, the default initial status is set to Started. You canoptionally set the initial status to Stopped by appending a query string to theHTTP POST method:

HTTP methodPOST

URI/zosConnect/apis?status=stopped

DescriptionDeploys a new API into z/OS Connect EE and sets the status to Stopped.When an API is stopped, requests invoking the API will fail.Administration requests to /zosConnect/apis/{apiName} will still functionas normal and the API will appear in the list returned by a GET request to/zosConnect/apis. To start the API after it has been deployed, see “Changethe status of an API” on page 241

SecurityUsers with Administrator or Operator authority can set the initial status ofan API, users with Invoke or Reader authority cannot.

Request bodyAPI package to be deployed.

Example request

To deploy an API and set the initial status to stopped:/zosConnect/apis?status=stopped

Response body{

"name": "{name}","version": "{version}","description": "{API description}","status": "{Started|Stopped}","apiUrl": "http(s)://{host}:{port}/{basePath}""documentation": {

"swagger":"http(s)://{host}:{port}/{basePath}/api-docs"}

}

Errors The following error can occur:


400 Bad requestUnknown status specified

Update an APIYou can use the HTTP method PUT to update a z/OS Connect EE API.

Note:

By default, an API will have the status started. However, it can be set to a specificinitial status by appending a query string to the URI with a status. For example:/zosConnect/apis/{apiName}?status=stopped

HTTP methodPUT

URI /zosConnect/apis/{apiName}

DescriptionUpdates the named API in z/OS Connect EE using the new API packagefile.

Note:

1. The API needs to be stopped before updating.2. The package being updated needs to be for the same API.

SecurityUsers with Administrator or Operator authority can update an API, userswith Invoke or Reader authority cannot.

Request bodyThe API package file. The content type for the request is application/zip.

Response bodyThis function returns the Location header pointing to protocol://server:port/basePath

{"name": "{name}","version": "{version}","description": "{API description}","status": "Started|Stopped","apiUrl": "http(s)://{host}:{port}/{basePath}""documentation": {"swagger":"http(s)://{host}:{port}/{basePath}/api-docs"

}

where:v apiUrl is the URL you use to invoke the API.v swagger contains the URL where the swagger document for the API can

be obtained. For more details see “Documenting your API usingSwagger” on page 230

Example response body{

"name": "HospitalAPI","version": "1.0.0","description": "API for Hospital app","status": "Started","apiUrl": "http://localhost:9080/hospital",


"documentation": {"swagger":"http://localhost:9080/hospital/api-docs"

}}

Errors The following errors can occur:400 Bad requestInvalid or missing API package

409 ConflictA z/OS Connect API must be stopped before it can be updated.

415 Unsupported Media TypeContent-Type is not application/zip:


503 Service UnavailableA z/OS Connect API must complete all outstanding requests before it can be updated.

Change the status of an APIA query string option can be used to set the status of an API. If the API package, isnot usable, the operation fails.

Note: When an API is stopped, the API will not invoke interceptors for newrequests, and returns the following message:

503 Service Unavailable

The error response body contains:{ "errorMessage": "The API has been stopped" }

Note: The status of an API can be either started, or stopped. You can change thestatus with the HTTP PUT method.

HTTP methodPUT

URI /zosConnect/apis/{apiName}?status=started|stopped

DescriptionStarts or stops the existing API. When an API is stopped, new requests willfail but existing requests will be allowed to complete. Administrationrequests to /zosConnect/apis/{apiName} will still function normally andthe API will appear in the list returned by the /zosConnect/apis request.

SecurityUsers with Administrator or Operator authority can change the status ofan API, users with Invoke or Reader authority cannot.

Request bodyTo change the status of an API, the request body should have no content. Ifan API package is in the request body then the request is to update theAPI and set the initial status after the update. For more information, see“Update an API” on page 240.

Example requestTo change the status of the API called apiName to started:/zosConnect/apis/apiName?status=started


Response body{

"name": "{name}","version": "{version}","description": "{API description}","status": "Started|Stopped","apiUrl": "http(s)://{host}:{port}/{basePath}","documentation": {"swagger":"http(s)://{host}:{port}/{basePath}/api-docs"

}}

Note: Responses from GET requests, such as GET /zosConnect/apis/{apiName}?status=started, include the status property. For example:{

"name": "API name","version": "version","description": "API description","status": "Started|Stopped","apiUrl": "API base path","documentation": {"swagger": "API Swagger document location"}

}

Errors400 Bad requestUnknown status specified

Delete an APIYou can use the HTTP method DELETE to delete a z/OS Connect EE API.

HTTP methodDELETE

URI /zosConnect/apis/{apiName}

DescriptionUninstalls the named API from z/OS Connect EE, and deletes the APIpackage from the file system. An API must be in stopped state to bedeleted.

SecurityUsers with Administrator or Operator authority can delete an API, userswith Invoke or Reader authority cannot.

Return body{

"name":"{API name}"}

Example body{

"name":"HospitalAPI"}

Errors The following errors can occur:409 ConflictA z/OS Connect API must be stopped before it can be deleted.



503 Service UnavailableA z/OS Connect API must complete all outstanding requests before it can be deleted.


Chapter 14. Client application development

When z/OS Connect EE is successfully installed, you can create the artifacts thatare needed for client applications to access your z/OS services.Related concepts:Auditing and trackingTo audit and track requests, you can use the audit interceptor included with z/OSConnect EE, or live statistics for z/OS Connect EE services.

The z/OS Connect EE administration interfacez/OS Connect EE provides a set of APIs that you can use to discover services,check service status, start or stop services, get statistics, and complete otheroperations.

You can use the z/OS Connect EE administration interface from any client that isrunning in a web, mobile, or cloud environment.

The following examples demonstrate some of the calls that can be made by usingthe administration interface.1. Discover services in the z/OS Connect EE configuration by using a HTTP GET

request. For example,https://host:port/zosConnect/services

The following sample shows the JSON payload that is returned:{

zosConnectServices: [{

ServiceName: "recordOpsCreate"ServiceDescription: "Creates a new record"ServiceProvider: "SAMPLE-1.0"ServiceURL: "https://host:port/zosConnect/services/recordOpsCreate"

},{

ServiceName: "recordOpsDelete"ServiceDescription: "Deletes an existing record"ServiceProvider: "SAMPLE-1.0"ServiceURL: "https://host:port/zosConnect/services/recordOpsDelete"

}]

}

2. Retrieve configuration data for a service.https://host:port/zosConnect/services/recordOpsCreate

The output is returned in two parts: the first part contains the z/OS ConnectEE configuration parameters and the second part has the configuration that isreturned by the service provider implementation. The following sample showsthe JSON payload that is returned:{

zosConnect: {serviceName: "recordOpsCreate"serviceDescription: "Creates a new record"serviceProvider: "SAMPLE-1.0"serviceURL: "https://host:port/zosConnect/services/recordOpsCreate"serviceInvokeURL: "https://host:port/zosConnect/services/recordOpsCreate?action=invoke"dataXformProvider: "jsonByte-1.0"


},recordOpsCreate: {targetProgram: "CREATREC"timeout: "300ms"

}}

3. Retrieve service status.https://host:port/zosConnect/services/recordOpsCreate?action=status


zosConnect:{serviceName: "recordOpsCreate"serviceDescription: "Creates a new record"serviceProvider: "SAMPLE-1.0"serviceURL: "https://host:port/zosConnect/services/recordOpsCreate"serviceInvokeURL: "https://host:port/zosConnect/services/recordOpsCreate?action=invoke"dataXformProvider: "jsonByte-1.0"serviceStatus: "Started"

}}

4. Retrieve request schema.https://host:port/zosConnect/services/recordOpsCreate?action=getRequestSchema

The following sample shows the JSON payload that is returned:{<Request schema as returned by the data configured data transformer>}

Note: If you use the getRequestSchema call to find JSON schema files,zosconnect_zosConnectDataXform automatically appends _request to theservice name.

5. Retrieve response schema.https://host:port/zosConnect/services/recordOpsCreate?action=getResponseSchema

The following sample shows the JSON payload that is returned:{<Response schema as returned by the data configured data transformer>}

Note: If you use the getResponseSchema call to find JSON schema files,zosconnect_zosConnectDataXform automatically appends _response to theservice name.

6. Retrieve statistics.Statistics include z/OS Connect EE data for a service such asInvokeRequestCount, and a TimeOfRegistrationWithZosConnect, along withany other statistics returned by the service provider by using thegetStatistics() SPI implementation in the provider. Statistics for a particularservice can be retrieved through a /zosConnect/operation or an action=request call. /zosConnect/operations requests offer more flexibility becausethe product can retrieve statistics for all services. If the authorizationinterceptor is enabled, then the product returns statistics for only thoseservices that the user can request. See the documentation about z/OS Connectsecurity for more details.The following sample shows an HTTP GET request that usesaction=getStatistics to return statistics:https://host:port/zosConnect/services/recordOpsCreate?action=getStatistics

The following sample shows the JSON payload that is returned:


{recordOpsCreate:{ServiceProvider: "SAMPLE-1.0"InvokeRequestCount: 100TimeOfRegistrationWithZosConnect: "<yyyy-mm-dd hh:mm:ss:mmm tzn>"ServiceStatistics:{

.. <JSON name value pairs showing statistical information about the service returned.>}

}}

where yyyy-mm-dd is the date, hh:mm:ss:mmm time and tzn is the time zone. Forexample: 2015-11-13 17:28:28:589 GMT.

7. Retrieving statistics for a service can also be accomplished by using the URI inthe administration interface.The information that is returned includes statistics for all services that thecurrent user can request. The following sample shows a HTTP GET request thatuses /zosConnect/operation/getStatistics:https://host:port/zosConnect/operations/getStatistics

The following sample shows the JSON payload that is returned:{zosConnectStatistics:

[{

recordOpsCreate:{

ServiceProvider: "SAMPLE-1.0"InvokeRequestCount: 100TimeOfRegistrationWithZosConnect: "<yyyy-mm-dd hh:mm:ss:mmm tzn>"ServiceStatistics:{


}},{

recordOpsDelete:{

ServiceProvider: "SAMPLE-1.0"InvokeRequestCount: 100TimeOfRegistrationWithZosConnect: "<yyyy-mm-dd hh:mm:ss:mmm tzn>"ServiceStatistics:{


}}

]}

If no services are registered with z/OS Connect EE, the output resembles thefollowing example:{zosConnectStatistics:[]}

8. Retrieve statistics for all services that are defined for a specific serviceprovider by using the URI in the administration interface.Sample HTTP GET request:https://host:port/zosConnect/operations/getStatistics?provider=SAMPLE-1.0

Chapter 14. Client application development 247

Sample format/output.{

recordOpsCreate:{ServiceProvider: "SAMPLE-1.0"InvokeRequestCount: 100TimeOfRegistrationWithZosConnect: "<yyyy-mm-dd hh:mm:ss:mmm tzn>"ServiceStatistics:{.. <JSON name value pairs showing statistical information about the service returned.>

}}

}

9. Retrieve statistics for a single service by using the URI in the administrationinterface. This operation is equivalent to specifying action=getStatistics ona service. HTTP GET request on:https://host:port/zosConnect/operations/getStatistics?service=recordOpsCreate


recordOpsCreate:{ServiceProvider: "SAMPLE-1.0"InvokeRequestCount: 100TimeOfRegistrationWithZosConnect: "<yyyy-mm-dd hh:mm:ss:mmm tzn>"ServiceStatistics:{.. <JSON name value pairs showing statistical information about the service returned.>}

}}

10. Stop z/OS Connect EE services by using an HTTP POST or PUT request withaction=stop, or start the services by using HTTP POST or PUT with theaction=start query string.Stop and start actions do not require a payload. If one is provided, it isignored. A user can retrieve the status of a z/OS Connect EE service by usingHTTP GET on the service name with the action=status query string toretrieve the service status. If the authorization interceptor provided by z/OSConnect EE is enabled, the user that is requesting the status change must bein the operator or administrator group that is required for the service. Foreach, the Service Provider SPI is called by z/OS Connect EE to notify it thatthese actions were requested. The method names that are in the SPI for theseactions are stop(), start(), and status().

Note: z/OS Connect EE does not persist any state that is related to the serviceand instead delegates this state to the service provider.The service provider can send responses other than stop or start. z/OSConnect EE allows for a custom status to be returned.Stop a service by using HTTP POST or PUT:https://host:port/zosConnect/services/recordOpsCreate?action=stop


zosConnect:{serviceName: "recordOpsCreate"serviceDescription: "Creates a new record"serviceProvider: "SAMPLE-1.0"serviceURL: "https://host:port/zosConnect/services/recordOpsCreate"serviceInvokeURL: "https://host:port/zosConnect/services/recordOpsCreate?action=invoke"


dataXformProvider: "jsonByte-1.0"serviceStatus: "Stopped"

}}

11. Start a service sample by using HTTP POST or PUT:https://host:port/zosConnect/services/recordOpsCreate?action=start


zosConnect:{serviceName: "recordOpsCreate"serviceDescription: "Creates a new record"serviceProvider: "SAMPLE-1.0"serviceURL: "https://host:port/zosConnect/services/recordOpsCreate"serviceInvokeURL: "https://host:port/zosConnect/services/recordOpsCreate?action=invoke"dataXformProvider: "jsonByte-1.0"serviceStatus: "Started"

}}

12. Invoke services by using the z/OS Connect EE query string: action=invoke,which runs the invoke() method of the Service Provider SPI implementation.The sample in this step runs the invoke method for the service that is namedrecordOpsCreate and passes a JSON object payload in the request body.The z/OS Connect EE invoke method supports an input payload in JSONobject form for this request. In the code example, it is assumed that z/OSConnect EE looked up the Service Provider and identified a service referencefor the service called SAMPLE-1.0. A data transformation reference is containedin the z/OS Connect EE service definition with a provider calledjsonByte-1.0. When the invoke method of the service provider gets controland calls the getBytes() method, the data transformation implementation getscontrol and converts the request payload from JSON to a byte array andreturns it to the service provider.If the invoke action request has a URL that contains query parameters, thenthese parameters, and other HTTP request information, are passed to theservice provider by using thecom.ibm.zosconnect.spi.HttpZosConnectRequestSPI interface that is provided by z/OS Connect EE. Interceptors that areprocessed for actions or operations also receive HTTP request informationthrough the same object.Another invocation style that is supported by z/OS Connect EE provides ameans to define a user-defined URI as the invokeURI in the z/OS Connectservice definition. With this style, the HTTP request does not have to containzosConnect/services and can instead be a user-defined string.When this style is employed, z/OS Connect EE supports use of other HTTPmethods, such as GET, PUT, POST, and DELETE. Requests arriving with thisURI, regardless of the HTTP method that is employed, pass through z/OSConnect EE interceptors and are passed to the invoke() method of the serviceprovider.Sample that uses HTTP POST or PUT:https://host:port/zosConnect/services/recordOpsCreate?action=invoke{<JSON object passed in for the service invocation>}

The following sample shows the JSON payload that is returned:{<JSON object returned from the service invocation>}


Conversion for z/OS Connect Enterprise Edition data transformationYou can use the BAQLS2JS and BAQJS2LS utilities to generate the necessary z/OSConnect Enterprise Edition artifacts to facilitate data conversion with the z/OSConnect Enterprise Edition data transformation provider.

The BAQLS2JS and BAQJS2LS utilities are provided for use with the supplied serviceprovider for CICS WOLA.

Note: z/OS Connect EE supports JSON integer values in the range -2⌂63 through2⌂63 - 1. Any language structures that you use as input to the BAQLS2JS utility,which generates JSON schemas with "type":"integer" and values below -2⌂63 orvalues above 2⌂63 - 1 are not supported. For example,v For C, do not exceed long long. Unsigned long long is not supported.v For COBOL, do not exceed PIC S9(18) COMP-5 or PIC S9(18) DISPLAY.v For Enterprise PL/I, do not exceed SIGNED FIXED BINARY(63). UNSIGNED FIXED

BINARY(64) is not supported.

If you are using existing JSON schemas as input to BAQJS2LS, ensure that anyinteger values do not exceed these limits.

For more information about the language structure to JSON mappings and JSONto language structure mappings, see High-level language and JSON schemamapping in the CICS TS Knowledge Center documentation.

BAQLS2JS: High-level language to binding and schema fileconversion for z/OS Connect Enterprise Edition datatransformation

The BAQLS2JS Job Control Language procedure generates a JavaScript ObjectNotation (JSON) schema and bind files from a high-level data structure. The filesthat are generated are used by the z/OS Connect Enterprise Edition datatransformation process.

Note: If you are generating a WSBind file and JSON schemas to use the z/OSConnect EE data transformation feature, then you must use the naming conventionthat is required by the zosConnectDataXform element in the server.xml file. Thenames of the request and response schemas must be of the format that is shown inthe following example. The suffixes _request and _response are mandatory. Thefollowing example uses this naming convention:

SERVICE-ARCHIVE={servicearchive_dir}/{servicearchive}SERVICE-NAME={serviceName}WSBIND={wsbind_dir}/{serviceName}.wsbindJSON-SCHEMA-REQUEST={json_schema_dir}/{serviceName}_request.jsonJSON-SCHEMA-RESPONSE={json_schema_dir}/{serviceName}_response.json

wherev {serviceName} must match the value that is specified on the serviceName attribute

of the associated zosConnectService element when you configure server.xml fileto use the DataXform.

v {servicearchive_dir>} is the UNIX System Services directory in which the servicearchive file is created

v {wsbind_dir} is the UNIX System Services directory in which the wsbind file iscreated.


https://www.ibm.com/support/knowledgecenter/SSGMCP_5.3.0/com.ibm.cics.ts.applicationprogramming.doc/datamapping/dfhws_hlljsonmapping.html

https://www.ibm.com/support/knowledgecenter/SSGMCP_5.3.0/com.ibm.cics.ts.applicationprogramming.doc/datamapping/dfhws_hlljsonmapping.html

v {json_schema_dir} is the UNIX System Services directory in which the JSONrequest and response schemas are created.

For example:<zosconnect_zosConnectService id="inquireCatalogService"

serviceName="<serviceName>"serviceRef="wolaCatalogManager"dataXformRef="xformJSON2Byte" />

<zosconnect_zosConnectDataXform id="xformJSON2Byte"

bindFileLoc="<wsbind_dir>"bindFileSuffix=".wsbind"requestSchemaLoc="<json_schema_dir>"responseSchemaLoc="<json_schema_dir>"requestSchemaSuffix=".json"responseSchemaSuffix=".json">

</zosconnect_zosConnectDataXform>

Job control statements for BAQLS2JS

JOB Starts the job.

EXEC Specifies the procedure name (BPXBATCH).

Input Parameters

BAQLS2JS runs a version of the CICS JSON assistant utility program DFHLS2JS. Forinput parameter descriptions, see the DFHLS2JS reference documentation . Wherethe documentation refers to DFHLS2JS, use BAQLS2JS.

Two additional input parameters can be used to create a service archive for z/OSConnect Enterprise Edition:

SERVICE-ARCHIVEThe fully qualified z/OS UNIX name of the service archive file. DFHLS2JScreates the file, but not the directory structure, if it does not exist.

SERVICE-NAMEThe name of the z/OS Connect Enterprise Edition service that is describedby the service archive. This name is specified by the SERVICE-ARCHIVEparameter. If you develop APIs from the generated service archive files, theAPI Editor uses the value that is specified on the SERVICE-NAME parameteras the service name associated with a specific API path and method.

The following input parameters are valid for BAQLS2JS. The value that is specifiedfor the PGMNAME parameter is used in the generated JSON schema.


http://www.ibm.com/support/knowledgecenter/SSGMCP_5.3.0/com.ibm.cics.ts.webservices.doc/reference/dfhws_ls2js.html

►► PDSLIB=valuePDSCP=value

REQMEM(data-value) RESPMEM(data-value)REQUEST-CHANNEL=value

RESPONSE-CHANNEL=value

►

► LANG=COBOLLANG=PLI-ENTERPRISELANG=PLI-OTHERLANG=CLANG=CPP STRUCTURE=( , )

request response

►

►

PGMINT=CHANNELCONTID=value

PGMNAME=valueTRANSACTION=name USERID=id URI=value PGMINT=COMMAREA

►

►MAPPING-LEVEL=1.0MAPPING-LEVEL=1.1

CHAR-VARYING=NOMAPPING-LEVEL=1.2MAPPING-LEVEL=2.0 CHAR-VARYING=NULLMAPPING-LEVEL=2.1MAPPING-LEVEL=2.2 CHAR-VARYING=COLLAPSE

DATETIME=UNUSED DATA-TRUNCATION=DISABLED CHAR-VARYING=BINARYMAPPING-LEVEL=3.0

DATETIME=PACKED15 DATA-TRUNCATION=ENABLEDMAPPING-LEVEL=4.0 Advanced data mapping (mapping level 4.0 and higher)MAPPING-LEVEL=4.1 Advanced data mapping (mapping level 4.1 and higher)

►

►MINIMUM-RUNTIME-LEVEL=MINIMUM

MINIMUM-RUNTIME-LEVEL=CURRENTMINIMUM-RUNTIME-LEVEL=1.0MINIMUM-RUNTIME-LEVEL=1.1MINIMUM-RUNTIME-LEVEL=1.2MINIMUM-RUNTIME-LEVEL=2.0MINIMUM-RUNTIME-LEVEL=2.1MINIMUM-RUNTIME-LEVEL=2.2MINIMUM-RUNTIME-LEVEL=3.0MINIMUM-RUNTIME-LEVEL=4.0MINIMUM-RUNTIME-LEVEL=4.1

DATA-SCREENING=ENABLED

DATA-SCREENING=DISABLED►

►HTTPPROXY= domain name :port number HTTPPROXY-USERNAME=value HTTPPROXY-PASSWORD=value

IP addressCCSID=value

SYNCONRETURN=NO

SYNCONRETURN=YES►

►TRUNCATE-NULL-ARRAYS=DISABLED

TRUNCATE-NULL-ARRAYS=ENABLED

TRUNCATE-NULL-ARRAY-VALUES=NULL

TRUNCATE-NULL-ARRAY-VALUES=SPACETRUNCATE-NULL-ARRAY-VALUES=ZERO

WSBIND=value JSON-SCHEMA-REQUEST=value JSON-SCHEMA-RESPONSE=value ►

► LOGFILE=value ►◄

The following is sample JCL to run the BAQLS2JS tool. You can find this sample inthe <Install Path>/jcl directory./BAQLS2JS.jcl for the JCL template://BAQLS2JS JOB (0),MSGCLASS=X,CLASS=A,NOTIFY=&SYSUID,REGION=500M//ASSIST EXEC PGM=BPXBATCH//STDPARM DD *PGM /usr/lpp/IBM/zosconnect/v2r0/bin/baqls2jsLOGFILE=/u/userid/BAQLS2JS.logLANG=COBOLMAPPING-LEVEL=4.0PDSLIB=//PROJECT.COBOLREQMEM=REQLSRESPMEM=RESPLSJSON-SCHEMA-REQUEST=/u/userid/schema/inquireCatalog_request.jsonJSON-SCHEMA-RESPONSE=u/userid/schema/inquireCatalog_response.jsonWSBIND=/u/userid/wsbind/inquireCatalog.wsbind


PGMNAME=DFH0XCMNPGMINT=COMMAREA/*//STDOUT DD SYSOUT=*//STDERR DD SYSOUT=*//STDENV DD *JAVA_HOME=/java/java71_64//

BAQJS2LS: JSON schema to high-level language conversion forz/OS Connect Enterprise Edition data transformation

The BAQJS2LS JCL procedure generates a high-level language data structure andbinding file from a JSON schema. The files that are generated are used by thez/OS Connect Enterprise Edition data transformation process.

The value that is specified for the PGMNAME parameter is used in the name of thegenerated high-level language structure.

Note:

1. If you use the WSBind file to call CICS via an API, then JSON-SCHEMA-REQUESTand JSON-SCHEMA-RESPONSE must use schemas that specify only a singleproperty at the top level of the JSON format described.

2. If you are generating a WSBind file and JSON schemas for use in a z/OSConnect Enterprise Edition DataXform, then you must use a namingconvention that is expected by the zosConnectDataXform element in theserver.xml file. Specify the following values for the BAQJS2LS parameters:SERVICE-NAME={serviceName}WSBIND={wsbind_dir}/{serviceName}.wsbindJSON-SCHEMA-REQUEST={json_schema_dir}/{serviceName}_request.jsonJSON-SCHEMA-RESPONSE={json_schema_dir}/{serviceName}_response.json

wherev {serviceName} must match the value that is specified on the serviceName

attribute of the associated zosConnectService element when you configureserver.xml file to use the DataXform

v {wsbind_dir} is the UNIX System Services directory in which the wsbind file iscreated.

v {json_schema_dir} is the UNIX System Service directory in which the JSONrequest and response schemas are stored.

Job control statements for BAQJS2LS

JOB Starts the job.

EXEC Specifies the procedure name (BPXBATCH).

Input parameters for BAQJS2LS

BAQJS2LS runs a version of the CICS JSON assistant utility program DFHJS2LS. Forinput parameter descriptions, see the DFHJS2LS reference documentation . Wherethe documentation refers to DFHJS2LS, use BAQJS2LS.

Two additional input parameters can be used to create a service archive for z/OSConnect Enterprise Edition:


http://www-01.ibm.com/support/knowledgecenter/SSGMCP_5.3.0/com.ibm.cics.ts.webservices.doc/reference/dfhws_js2ls.html

SERVICE-ARCHIVEThe fully qualified z/OS UNIX name of the service archive file. DFHJS2LScreates the file, but not the directory structure, if it does not exist.

SERVICE-NAMEThe name of the z/OS Connect Enterprise Edition service that is describedby the service archive. This archive is specified by the SERVICE-ARCHIVEparameter. If you develop APIs from the generated service archive files, theAPI Editor uses this value as the service name associated with a specificAPI path and method.

The following input parameters are valid for BAQJS2LS. The value that is specifiedfor the PGMNAME parameter is used in the name of the generated high-level languagestructure.

►► PDSLIB=valuePDSCP=value

REQMEM(data-value) RESPMEM(data-value) ►

► LANG=COBOLLANG=PLI-ENTERPRISELANG=PLI-OTHERLANG=CLANG=CPP STRUCTURE=( , )

request response

►

►PGMINT=CHANNEL

CONTID=valuePGMNAME=value

URI=value PGMINT=COMMAREA TRANSACTION=name USERID=id

►

►MAPPING-LEVEL=1.0MAPPING-LEVEL=1.1MAPPING-LEVEL=1.2 Advanced data mapping (mapping level 1.2 and higher)MAPPING-LEVEL=2.0MAPPING-LEVEL=2.1 Advanced data mapping (mapping level 2.1 and higher)MAPPING-LEVEL=2.2 Advanced data mapping (mapping level 2.2 and higher)

DATETIME=PACKED15 DATA-TRUNCATION=DISABLEDMAPPING-LEVEL=3.0 Advanced data mapping (mapping level 3.0 and higher)

DATETIME=STRING DATA-TRUNCATION=ENABLEDCHAR-OCCURS=STRING CHAR-USAGE=NATIONAL

MAPPING-LEVEL=4.0 Advanced data mapping (mapping level 4.0 and higher)MAPPING-LEVEL=4.1 Advanced data mapping (mapping level 4.1 and higher) CHAR-OCCURS=ARRAY CHAR-USAGE=DBCS

►

►SAME-AS-MAPPING-LEVEL

MAPPING-OVERRIDES=UNDERSCORES-AS-HYPHENSLESS-DUP-NAMES

MINIMUM-RUNTIME-LEVEL=MINIMUM

MINIMUM-RUNTIME-LEVEL=1.0MINIMUM-RUNTIME-LEVEL=1.1MINIMUM-RUNTIME-LEVEL=1.2MINIMUM-RUNTIME-LEVEL=2.0MINIMUM-RUNTIME-LEVEL=2.1 Advanced data mapping (runtime level 2.1 and higher)MINIMUM-RUNTIME-LEVEL=2.2 Advanced data mapping (runtime level 2.2 and higher)MINIMUM-RUNTIME-LEVEL=3.0 Advanced data mapping (runtime level 3.0 and higher)MINIMUM-RUNTIME-LEVEL=4.0 Advanced data mapping (runtime level 4.0 and higher)MINIMUM-RUNTIME-LEVEL=4.1 Advanced data mapping (runtime level 4.1 and higher)MINIMUM-RUNTIME-LEVEL=CURRENT

►

►DATA-SCREENING=ENABLED

DATA-SCREENING=DISABLED HTTPPROXY= domain name :port number HTTPPROXY-USERNAME=value HTTPPROXY-PASSWORD=valueIP address

►

► JSON-SCHEMA-REQUEST=value JSON-SCHEMA-RESPONSE=valueCCSID=value NAME-TRUNCATION=value

LOGFILE=value ►

►TRUNCATE-NULL-ARRAYS=DISABLED

TRUNCATE-NULL-ARRAYS=ENABLED

TRUNCATE-NULL-ARRAY-VALUES=NULL

TRUNCATE-NULL-ARRAY-VALUES=SPACETRUNCATE-NULL-ARRAY-VALUES=ZERO

WSBIND=valueWIDE-COMP3=NO

WIDE-COMP3=YES►◄


Advanced data mapping (mapping level 1.2 and higher):

CHAR-VARYING=NOCHAR-VARYING=NULLCHAR-VARYING=YES

CHAR-VARYING-LIMIT=32767

CHAR-VARYING-LIMIT=value

CHAR-MULTIPLIER=1

CHAR-MULTIPLIER=value►

►DEFAULT-CHAR-MAXLENGTH=255

DEFAULT-CHAR-MAXLENGTH=value

Advanced data mapping (mapping level 2.1 and higher):

INLINE-MAXOCCURS-LIMIT=1

INLINE-MAXOCCURS-LIMIT=value

Use this sample JCL to run the BAQJS2LS tool. You can find this sample in the<Install Path>/jcl directory./BAQJS2LS.jcl for the JCL template://BAQJS2LS JOB (0),MSGCLASS=X,CLASS=A,NOTIFY=&SYSUID,REGION=500M//ASSIST EXEC PGM=BPXBATCH//STDPARM DD *PGM /usr/lpp/IBM/zosconnect/v2r0/bin/baqjs2lsLOGFILE=/u/userid/BAQJS2LS.logLANG=COBOLMAPPING-LEVEL=4.0PDSLIB=//PROJECT.COBOLREQMEM=REQLSRESPMEM=RESPLSJSON-SCHEMA-REQUEST=/u/userid/schema/inquireCatalog_request.jsonJSON-SCHEMA-RESPONSE=u/userid/schema/inquireCatalog_response.jsonWSBIND=/u/userid/wsbind/inquireCatalog.wsbindPGMNAME=DFH0XCMNPGMINT=COMMAREA/*//STDOUT DD SYSOUT=*//STDERR DD SYSOUT=*//STDENV DD *JAVA_HOME=/java/java71_64//

Return codes

If the running utility program issues a non-zero return code, look in the jobSTDOUT and STDERR for messages about the cause of the problem. If no warningor error messages are found in STDOUT or STDERR, look for security-relatedmessages in the system log of the LPAR. Fix the problem and rerun the utilityprogram until a zero return code is obtained. Do not use artifacts that aregenerated with a non-zero return code.


Related concepts:z/OS Connect EE API Editor for defining your APIsThe z/OS Connect EE API Editor helps you create an API package that describesthe configuration of the API and the HTTP methods on the resources that can becalled.

Interacting with COBOL and TSO/ISPFUsing WOLA in z/OS Connect EE to allow a REST application to access z/OSCOBOL and z/OS TSO/ISPF applications.

Consider these requirements when you create a REST client that uses z/OSConnect EE to access Batch applications.

Essential requirements

For a REST client to access z/OS, COBOL, and z/OS TSO/ISPF, certain functionsmust be provided, as shown in Figure 2:

1. Hosting of HTTP listen ports.

Figure 35. A REST client uses z/OS Connect EE to access Batch applications.

Figure 36. Functions required for a REST client to access COBOL and TSO/ISPF


2. Provide REST handling capabilities.3. A bridge between the REST handler and COBOL or TSO/ISPF.4. Bridge program must be able to link to and start the target programs.5. Properly structured target programs. For example,v TSO/ISPF functions must have good separation of the 3270 presentation

layer from the business logic.v Data requirements for COBOL must be understood.

You can use z/OS Connect EE and WOLA to provide these functions. Only 5WOLA APIs are used.

BBOA1REGThe first step to using WOLA is to register to z/OS Connect EE to createthe cross-memory WOLA link.

BBOA1SRVHost a service. This service holds program control until a request isreceived. Output parameters include the connection handle, length of therequest and address of the request. The TSO/ISPF function or COBOLmodule is started.

BBOA1SRPSend a response back to z/OS Connect EE.

BBOA1CNRRelease the connection that was given to BBOA1SRV and return it to thepool. Return control to BBOA1SRV and listen on the HTTP port for thenext request.

BBOA1URGUnregister the connection to WOLA.

Program structure

A typical program would function as shown in Figure 3.


1. BBOA1REG is called to create the connection between z/OS Connect EE andWOLA. The HTTP port is then monitored for an incoming request.

2. The REST client sends a request. For example,http://<host>:<port>/myService

3. Request is mapped to the service definition in the z/OS Connect EEconfiguration file server.xml:<zosConnectService id="MyService"

invokeURI="/myService"serviceName="MyService"serviceRef="wolaSvc" />

4. The service definition maps to xml that defines the WOLA information and theservice to be started:

Figure 37. Typical program uses z/OS Connect EE to connect to TSO/ISPF


<localAdaptersConnectService id="wolaSvc"registerName="WOLAREG"serviceName="ServiceName"connectionFactoryRef="wolaCF" />

5. The service name that is called by z/OS Connect EE maps to the service namehosted by BBOA1SRV. The request flows across WOLA, and the BBO1SRV APIactivates and your program processes request:MOVE ’ServiceName’ TO SRV-service-name

CALL ’BBOA1SRV’ USINGregister-name,SRV-service-name,SRV-service-name-length,SRV-rqst-area-addr,SRV-rqst-area-length,connect-handle,wait-time,rc,rsn,rv

In this example, service-name is your BBOA1SRV service name.

Managing workload

Processing of requests occurs relatively quickly through z/OS Connect EE, WOLA,and the COBOL bridge program. Any delay is likely to be in the TSO/ISPFfunctions or COBOL module. COBOL is single threaded, so if the requests arrivefaster than they can be serviced, a queue forms. This queue is managed in themulti-threaded environment of Liberty and z/OS Connect EE.

The workload can be managed in three ways:1. Use z/OS Connect EE to spread the requests across multiple WOLA bridges as

shown in Figure 4:


2. Use WOLA into CICS and take advantage of the multi-threaded model of theWOLA link server task.

Note: You need to design the load-sharing interface between CICS and theTSO/ISPF functions or COBOL modules.

3. Write a bridge program in C/C++ to take advantage of the multi-threadedcapabilities.

Figure 38. Use z/OS Connect EE to spread requests across multiple WOLA bridges.

Figure 39. Location of the load-sharing interface that you must design


The model that uses z/OS Connect EE with BBOA1SRV is designed for relativelyfast completion times on the backend program. If your objective is to start along-running backend COBOL program, consider submitting it as a JOB throughthe z/OSMF interface.

You can find more examples of using WOLA in Techdoc WP101490 - WebSpherez/OS Optimized Local Adapters. An example implementation of WOLA BATCHfor z/OS Connect EE is provided on Github. The example includes COBOL sourcefiles, JCL to create a SAR file, a matching z/OS Connect EE API Editor projectarchive for import, and z/OS Connect EE runtime configuration.

Error responsesIf the useJsonErrorResponses attribute is set on the zosConnectManagerconfiguration element, all error responses from the z/OS Connect EE runtime arereturned in JSON format.

For more information on the attribute, see “zosconnect_zosConnectManager” onpage 316 in the Reference section. If the attribute is not set, or set to false, theerror responses are a mixture of JSON and plain text, depending on the error caseencountered.

If an error occurs while processing a request, an appropriate HTTP status code andthe following JSON will be returned:{

"errorMessage": "{message}","errorDetails": "{details}"

}

Note:

v errorDetails is optional and will only be returned for some error scenarios.v Service providers may use a proprietary error response format, so the format

described above cannot be guaranteed when invoking an API or service.

For example:

A GET request to /zosConnect/services/doesNotExist, would return a HTTPstatus code of 404 and JSON body:

{"errorMessage": "BAQR0403W: Service doesNotExist specified under URL

http://server:1234/zosConnect/services/doesNotExist is not available."}

A POST request to /zosConnect/services/myService with Content-Type set toapplication/json but an invalid body of: notJson would return a HTTP statuscode of 400 Bad Request and a JSON body:

{"errorMessage": "BAQR0417W: The request payload under request URL http://192.168.59.103:9080/zosConnect/services/myService could not be parsed.A JSON object format payload is expected. Error: Unexpected identifier ’notjson’ on line 1, column 7."

}




https://github.com/zosconnect/zosconnect-sample-wola-batch

Chapter 15. Extending z/OS Connect EE

Creating a z/OS Connect EE service providerz/OS Connect EE provides the com.ibm.zosconnect.spi.Service SPI that supportsthe creation of service providers that you can use to process requests arriving viaz/OS Connect EE.

About this task

For more information about the com.ibm.zosconnect.spi.Service SPI, see InterfaceService class.

z/OS Connect EE service providers can be written and delivered by anycomponent to plug into the framework. Both WOLA and IMS service providers areincluded with z/OS Connect EE.

Service providers from third party products can be deployed with z/OS ConnectEE. These service providers must supply a properties file describing the productfeatures and install the properties file into the z/OS Connect Product feature directory.For more information, see “Setting up the product extensions directory” on page113.

A service provider implemented for z/OS Connect EE is an OSGi service thatconnects and interacts with z/OS Connect EE through the OSGi framework.

Procedure1. Create a service provider that implements the z/OS Connect EE

com.ibm.zosconnect.spi.Service SPI.2. Edit the service metatype configuration so that it specifies the following

attribute definition:<OCD id="user.service.ID" ibm:alias="userServiceAlias" name="userServiceName"description="zOSConnect User ServiceProvider" ibm:objectClass="com.ibm.zosconnect.serviceType">

where the ibm:objectClass attribute indicates that this object is a type serviceprovider.Java API documentation for the z/OS Connect EE SPIs can be found in thez/OS Connect EE SPI reference, and as a separate file at <installation_path>/doc/javadoc.zip.The Java API documentation for each Liberty profile SPI can be found in theLiberty product documentation and is also available in a separate .zip file inone of the javadoc directories of the <installation_path>/wlp/dev directory.

Creating a z/OS Connect EE service at run timeTo process incoming requests, you can create a z/OS Connect EE service at runtime by using the com.ibm.zosconnect.spi.ServiceController serviceprogramming interface (SPI).

About this task

You can dynamically create a z/OS Connect EE service provider at run time basedon the configuration that is stored in an external repository.


Procedure1. Create a service provider that implements the z/OS Connect EE

com.ibm.zosconnect.spi.ServiceController SPI.2. At run time, register the service with the OSGi framework that is using the the

registerService method on the BundleContext attribute.Dictionary<String, Object> dynamicServiceProps = new Hashtable<String, Object>();dynamicServiceProps.put(ServiceControllerConstants.SERVICE_NAME, "myNewService");dynamicServiceProps.put(ServiceControllerConstants.INVOKE_URI, new String[] { "/u/my/url1",

"/u/myurl2", "/u/my/url3*" });ServiceRegistration<ServiceController> dynamicServiceReg =

bundleContext.registerService(com.ibm.zosconnect.spi.ServiceController.class, newMyServiceController(), dynamicServiceProps);

Note: The Java API documentation for each Liberty profile SPI can be found inthe Liberty product documentation and is also available in a separate .zip filein one of the javadoc directories of the <installation_path>/wlp/dev directory.

Creating a z/OS Connect EE interceptorUse the z/OS Connect EE SPI to create interceptor preInvoke and postInvokeimplementations that manage service requests such as invoke, status, start, andstop.

About this task

For more information about the SPI, see z/OS Connect SPI in the Reference section.

Interceptors are OSGi services that implement thecom.ibm.zosconnect.spi.Interceptor SPI provided by z/OS Connect EE. Severalinterceptors are provided.

For more information on interceptors, see “Interceptors” on page 3.

You can use interceptors for various purposes. z/OS Connect EE has noknowledge of the uses of interceptors. For example, an interceptor might bewritten to do some infrastructure set up that is based on the message payloadbefore the request is processed. z/OS Connect EE provides a copy of the inputrequest payload to all interceptors.

An interceptor implemented for z/OS Connect EE is an OSGi service that connectsand interacts with z/OS Connect EE through the OSGi framework.

Procedure1. The interceptor must implement the z/OS Connect EE

com.ibm.zosconnect.spi.Interceptor SPI.2. Edit the service metatype configuration so that it specifies the following

attribute definition:<OCD id="user.interceptor.ID" ibm:alias="userInterceptorAlias" name="userInterceptorName"description="zOSConnect User Interceptor" ibm:objectClass="com.ibm.zosconnect.interceptorType">

where the ibm:objectClass attribute indicates that this object is a typeinterceptor.Java API documentation for the z/OS Connect EE SPIs can be found in thez/OS Connect EE SPI reference, and as a separate file at <installation_path>/doc/javadoc.zip.


The Java API documentation for each Liberty profile SPI can be found in theLiberty product documentation and is also available in a separate .zip file inone of the javadoc directories of the <installation_path>/wlp/dev directory.

Creating a z/OS Connect EE data transformerYou can use the z/OS Connect EE SPI to create a custom data transformer. Datatransformers are OSGi services that implement thecom.ibm.zosconnect.spi.DataXform SPI that is provided by z/OS Connect EE.

About this task

z/OS Connect EE data transformers are written and delivered by any componentto plug into the framework. A data transformer is included with z/OS Connect EEand provides both to and from JSON byte arrays that are consumable by COBOL,PL/I, and C programs on z/OS.

A data transformer that is implemented for z/OS Connect EE is an OSGi servicethat connects and interacts with z/OS Connect EE through the OSGi framework.

Procedure1. Implement the z/OS Connect EE com.ibm.zosconnect.spi.DataXform SPI in the

service.2. Edit the metatype configuration so that it specifies the following attributes. This

definition should be entered on one line:<OCD id="user.DataTransform.ID" ibm:alias="userDataTransformAlias" name="userDataTransformName"description="zOSConnect User DataTransform" ibm:objectClass="com.ibm.zosconnect.dataXformType">

where the ibm:objectClass attribute indicates that this object is a typedataTransform.Java API documentation for the z/OS Connect EE SPIs can be found in thez/OS Connect EE SPI reference, and as a separate file at <installation_path>/doc/javadoc.zip.The Java API documentation for each Liberty profile SPI can be found in theLiberty product documentation and is also available in a separate .zip file inone of the javadoc directories of the <installation_path>/wlp/dev directory.As an implementation of a z/OS Connect Enterprise Edition programminginterface, Liberty profile API and SPI features can be used.

Using the DataxFormExt interfaceYou can use the methods provided by the com.ibm.zosconnect.spi.DataXformExtSPI to obtain information about the encoding of the data transformer.

When you create a data transformer, you implement the z/OS Connect EEcom.ibm.zosconnect.spi.DataXform SPI in the service. You can also use themethods in the com.ibm.zosconnect.spi.DataXformExt SPI to return informationabout the encoding.

For more information on using the DataxFormExt interface, see InterfaceDataxFormExt.

The getEncoding() method

When you invoke the service configured to use a DataXform which implements thegetEncoding() method of the DataXform interface, the service will check the value

Chapter 15. Extending z/OS Connect EE 265

of the Service.IBM_ZOS_CONNECT_ENCODING key in the requestStateMap.


Chapter 16. Resolving problems

Use this section to find solutions to problems that might occur.

Information about common problems can be found on the IBM developerWorkswebsite dW Answers. https://developer.ibm.com/answers/topics/zosconnect/.

The information is tagged with “zosconnect”.

Note: Version information for z/OS Connect EE can be found in messageBAQR0000I in the <WLP_USER_DIR>/servers/{servername}/logs/messages.log file..

Enabling z/OS Connect EE server traceThis section describes how to enable the z/OS Connect EE server trace when youare asked to do so by IBM service.

The following trace component specifications are available:v z/OS Connect: zosConnect=allv z/OS Connect REST Client:

zosConnectServiceRestClient=all:com.ibm.ws.jaxrs20.client=all

v z/OS Connect FS Logger interceptor: zosConnectInterceptorLoggerFS=allv WOLA Service Provider: zosConnectLocalAdapters=allv WOLA: zosLocalAdapters=allv IMS Service Provider:

– com.ibm.ims.*=all

– com.ibm.j2ca.RAIMSTM=all (for IMS connection issues)

You can enable trace with either of the following methods:1. Specifying the server.xml configuration logging element. Separate multiple

trace specifications with colons (":"). For example:<logging traceSpecification="zosConnect=all:zosConnectLocalAdapters=all"/>

or<logging traceSpecification="zosConnect=all:com.ibm.ims.*=all:com.ibm.j2ca.RAIMSTM=all"/>

2. Create a file called bootstrap.properties in the {server.config.dir} directory, withcontent specifying the com.ibm.ws.logging.trace.specification property. Forexample:

com.ibm.ws.logging.trace.specification=*=info:zosConnect=all:zosConnectLocalAdapters=all

For this method, you must restart the server for the changes to take effect.

In each case, the trace will be written to a trace.log file in the${server.config.dir}/logs directory by default.

For more information about setting up trace in a Liberty server, see the TechnoteSetting up trace and getting a full dump in the WebSphere Application Server V8.5Liberty profile, or the topic Liberty: Logging and Trace in the WebSphere ApplicationServer Liberty Knowledge Center.


https://developer.ibm.com/answers/topics/zosconnect/

http://www-01.ibm.com/support/docview.wss?uid=swg21596714

http://www-01.ibm.com/support/docview.wss?uid=swg21596714

http://www.ibm.com/support/knowledgecenter/SSEQTP_liberty/com.ibm.websphere.wlp.nd.multiplatform.doc/ae/rwlp_logging.html

Clearing or examining the IMS service in-memory cacheTo help troubleshoot issues, you can clear the cache or dump the content in thecache into the server log by using the IMS Explorer for Development withoutrestarting the z/OS Connect EE server.

About this task

Clearing the cache cleans up what is stored in the cache. The service definitioninformation is reloaded into the cache when a service is invoked or queried.

Dumping the cache to the log allows you to examine the log file fortroubleshooting. The cache itself is not touched.

Procedure

In the IMS Service Navigator in IMS Explorer for Development, right-click one ofthe following items and select the corresponding option from the context menu:v An z/OS Connect EE server nodev One of four entity type folders (IMS Connection profiles, Interaction properties

profiles, Services, and Transaction messages) under a server node.Related concepts:“IMS mobile service registry, in-memory cache, and administrative services” onpage 139The IMS mobile service registry is the authoritative source of information for serviceresources such as connection profiles, interaction profiles, service metadata, andtransaction message metadata. When a service is first invoked or queried, relatedservice resources are stored in the in-memory cache to improve the performance ofsubsequent requests.Related information:“Enabling z/OS Connect EE server trace” on page 267This section describes how to enable the z/OS Connect EE server trace when youare asked to do so by IBM service.

Contacting IBM Software SupportIBM Software Support provides assistance with product defects.

Before contacting IBM Software Support, your company must have an active IBMsoftware maintenance contract, and you must be authorized to submit problems toIBM.

Follow the steps in this topic to contact IBM Software Support:1. Determine the business impact of your problem.2. Describe your problem and gather background information.3. Submit your problem to IBM Software Support using the IBM Support Portal.

Determine the business impact of your problem

When you report a problem to IBM, you will be asked to supply a severity level.Therefore, you need to understand and assess the business impact of the problemyou are reporting. Use the following criteria:


https://www-947.ibm.com/account/userservices/jsp/login.jsp?persistPage=true&page=/support/entry/myportal/support

Severity Impact Characteristic

1 Critical You are unable to use the program, resulting in a criticalimpact on operations. This condition requires animmediate solution.

2 Significant The program is usable but is severely limited.

3 Moderate The program is usable with less significant features (notcritical to operations) unavailable.

4 Minimal The problem causes little impact on operations, or areasonable circumvention to the problem has beenimplemented.

Describe your problem and gather background information

When explaining a problem to IBM, be as specific as possible. Include all relevantbackground information so that IBM Software Support specialists can help yousolve the problem efficiently. To save time, know the answers to these questions:v What software versions were you running when the problem occurred?v Do you have logs, traces, and messages that are related to the problem

symptoms? IBM Software Support is likely to ask for this information.v Can the problem be recreated? If so, what steps led to the failure?v Have any changes been made to the system? For example, hardware, operating

system, networking software, and so on.v Are you currently using a workaround for this problem? If so, you may be

asked to explain it when you report the problem.

To find out what information and files you will need to supply when opening aproblem management record (PMR), see z/OS Connect EE MustGather.

Submit your problem to IBM Software Support

You can submit your problem in one of two ways:v Online: Go to the Submit and track problems page on the IBM Software Support

site. Enter your information into the appropriate problem submission tool.v By phone: For the phone number to call in your country, go to the contacts page

of the IBM Software Support Handbook on the Web and click the name of yourgeographic region.

If the problem you submit is for a software defect or for missing or inaccuratedocumentation, IBM Software Support will create an Authorized Program AnalysisReport (APAR). The APAR describes the problem in detail. Whenever possible,IBM Software Support will provide a workaround for you to implement until theAPAR is resolved and a fix is delivered.

IBM publishes resolved APARs on the IBM product support Web pages daily, sothat other users who experience the same problem can benefit from the sameresolutions.

Chapter 16. Resolving problems 269

Chapter 17. Messages

z/OS Connect EE messages are grouped into these categories:

IMS service provider (IMS Mobile feature) messagesError messages for the IMS Mobile feature have the prefix GMO. Some errormessages could surface in IMS Explorer for Development.

GMOBA messagesGMOBA messages are related to communications with IMS Connect through thebuilt-in backend adapter.

GMOBA0108E The IMS gateway server is unable toestablish a connection with IMSConnect: Failed to connect to host[host_name],port [port_number].[java_exception]

Explanation: A connection with IMS Connect couldnot be established, most likely due to incorrectconnection property specification, a network issue, orthe unavailability of the host system. java_exceptionindicates the reason for the failure to connect.

System action: An HTTP 500 status code is returned.

Programmer response: Examine the java_exception todetermine the reason for the failure to connect to thehost. Some possible values for java_exception aredescribed in the following table.

Table 44. Java exceptions for GMOBA0108E

Exception Description

java.net.UnknownHostException:hostname The host name that you

specified when you configuredthe connection profile isinvalid. Check that theconfiguration is still valid. Youmight need to use the fullyqualified path for the hostname or the IP address.

Table 44. Java exceptions forGMOBA0108E (continued)


java.net.ConnectException:Connection refused Some possible reasons for the

exception are:

v The port number is invalid.Ensure that you are using avalid port number for theIMS Connect that isindicated by host_name.

v The specified port isstopped. Check the status ofthe port by using the IMSConnect VIEWHWScommand. If the port statusis NOT ACTIVE, the port isstopped. To start the port,use the IMS ConnectOPENPORT dddd command,where dddd is the specifiedport number.

v IMS Connect on thespecified host is notrunning. Start IMS Connecton the host system.

v TCP/IP was restartedwithout either canceling andrestarting IMS Connect, orissuing STOPPORT followedby OPENPORT on the host.




java.net.SocketException:connect (code=10051) Some possible reasons for the

exception are:

v The system with thespecified host name isunreachable on the InternetProtocol network. Verify thatthe host system is accessiblefrom the Internet Protocolnetwork by issuing the pingcommand to the specifiedhost system. Enter the pingcommand on the system onwhich the z/OS Connect EEserver is running. StartTCP/IP on the host, if it isnot started.

v TCP/IP was restarted butthe status of the port that isused by the application wasNOT ACTIVE. To correctthis situation, take one ofthe following actions:

– Use the IMS Connectcommand OPENPORT dddd,where dddd is the portnumber, to activate theport.

– Restart IMS Connect.

GMOBA0109E The interaction requests could not beprocessed. Error_details.

Explanation: An error occurred when the interactionrequests were being processed by IMS Connect orOTMA.


Programmer response: Examine the IMS Connectreturn and reason codes and the OTMA sense codes todetermine the appropriate corrective action.

The return_code, reason_code, and sense_code are reportedin decimal. For example, if you receive an OTMA sensecode of 27, the hexadecimal value is 1B, or 001B. Usethe hexadecimal value when you look up the IMSConnect and OTMA return code, reason code, andsense code in IMS messages and code information.

For OTMA, a reason code of 0 indicates that the sensecode does not have an associated reason code.


OTMA codes

GMOBA0110E A problem occurred duringtransaction processing.[server_error_detail].

Explanation: An error occurred when IMS Connecttried to process the requested transaction.


Programmer response: Examine the server_error_detail.Traffic from the z/OS Connect EE server to IMS has aGMP prefix for the client ID. Use the client ID to helpanalyze the trace data from the different componentsthat are involved. If a Java exception are reported, usethe information to determine the reason for the failure.Some possible values for the Java exception aredescribed in the following table.

Table 45. Java exceptions for GMOBA0110E

Java exceptions Description

java.io.EOFExceptionSome possible reasons for theexception are:

v The timeout value that is specifiedin the IMS Connect configurationmember is exceeded before IMSConnect receives a response fromIMS. Exceeding a timeout valuetypically occurs when a region isnot available in IMS to run the IMStransaction that processes the clientrequest. If so, ensure that anappropriate region is started andavailable to process the request.Exceeding a timeout value can alsooccur if the IMS applicationprogram that is associated with thetransaction is stopped. If so, use theIMS type-2 UPDATE PGMNAME(pgm_name) START(SCHD)command or type-1 /START PROGRAMcommand to start the IMSapplication program.

v A Java client tries to use apreviously active client (forexample, a connection from thepool) for which an IMS ConnectSTOPCLNT command has beenissued.

GMOBA0109E • GMOBA0110E



Java exceptions Description

java.net.SocketException:Connectionreset by peer:socket writeerror

Some possible reasons for theexception are:

v A Java client attempts to use aconnection for which theunderlying socket is no longerconnected to IMS Connect. Thesocket connection might be lost ifIMS Connect is recycled, but theapplication server is not. After IMSConnect is restarted, theconnections that were formerlysuccessfully connected to IMSConnect are still in the connectionpool. As clients attempt to reuseeach of these connections, theexceptionjava.net.SocketException isthrown, and the connection object isremoved from the connection pool.

v TCP/IP on the host is comingdown.

GMOBA0113E Unable to instantiate aConnectionFactory instanceinstance_name.

Explanation: The IMS service provider cannot create aconnection to connect to IMS. The connection profilemight be corrupted.


Programmer response: Recreate the connection profile.

GMOCR messagesGMOCR messages are related to connection resources.

GMOCR0004E The specified connection profilename conn_profile_name cannot be locatedin the registry.

Explanation: Most likely the specified connectionprofile name is not entered correctly. Profile names arecase-sensitive. Allowed characters are A-Z, a-z, 0-9, and“-” (hyphen) , “.” (period), “_” (underscore), and “~”(tilde).


Programmer response: Check that the connectionprofile name is specified correctly.

GMOCR0008E A connection named conn_profile_namealready exists in the connection registry.

Explanation: The specified connection profile namealready exists in the registry.

System action: No action was taken by the system. AnHTTP 409 status code is returned.

Programmer response: Specify a different connectionname.

GMOCR0021E The creation or change to the {0}configuration element {1} was notprocessed by the server.

Explanation: The configuration element might be

connection, service, or interaction properties related.The server was not able to process the configurationchanges in a reasonable amount of time. The servermight be busy due to heavy workload.


Programmer response: Stop and start the server toprocess the configuration changes.

GMOCR0201I The connection profile with nameconn_profile_name was successfullycreated.

Explanation: This is an informational message.


Programmer response: No action is required.

GMOCR0202I The connection profile with nameconn_profile_name was successfullydeleted.




GMOBA0113E • GMOCR0202I

Chapter 17. Messages 273

GMOCR0203I The connection profile with nameconn_profile_name was successfullyupdated.




GMOCR0213I No connection profiles exist in theregistry.

Explanation: This is an informational response toqueries for available connection profiles in the registry.



GMOIG messagesGMOIG messages are general server communication-related messages.

GMOIG0004E The entity entity_name was not foundin the entity_type registry.

Explanation: The specified entity name does not existin the registry for the identified entity type.

System action: An HTTP 404 error is returned.

Programmer response: Specify a valid name and tryagain.

GMOIG0008E The entity_name name was empty.

Explanation: The required entity name was notspecified.

System action: No action was taken by the system. AnHTTP 400 status code is returned.

Programmer response: Specify a name and resubmitthe request.

GMOIG0100E An internal server error occurred.

Explanation: This error message was returned onlywhen all likely error cases were exhausted.


Programmer response: Check the trace output forpossible causes. Restart the server. If the problempersists, contact IBM Software Support and provide thetrace output.

GMOIG0102E The data store could not beinitialized.

Explanation: The data store might be corrupted or thedata store location was modified.


Programmer response: The data store might becorrupted or the data store location was modified.

GMOIG0108I The resource_type in the cache wassuccessfully logged in lengthmilliseconds.

Explanation: This is an informational message thatinformation stored in the cache for the resource_type islogged. The resource type might be connection profiles,

interaction properties profiles, services, or transactionmessages.



Related tasks:

“Clearing or examining the IMS service in-memorycache” on page 268To help troubleshoot issues, you can clear the cache ordump the content in the cache into the server log byusing the IMS Explorer for Development withoutrestarting the z/OS Connect EE server.

GMOIG0109I All resource types in the cache weresuccessfully logged in lengthmilliseconds.

Explanation: This is an informational message thatinformation stored in the cache for all resource types islogged.



Related tasks:


GMOIG0110I The resource_type in the cache wassuccessfully cleared in lengthmilliseconds.

Explanation: This is an informational message thatinformation stored in the cache for the resource_type iscleared. The resource type might be connection profiles,interaction properties profiles, services, or transactionmessages.



Related tasks:

GMOCR0203I • GMOIG0110I



GMOIG0111I All resource types in the cache weresuccessfully cleared in lengthmilliseconds.

Explanation: This is an informational message thatinformation stored in the cache for all resource types iscleared.



Related tasks:


GMOIG0112E Deletion of the transaction directory{0} failed.

Explanation: The operation to delete a transactionfailed, most likely due to a permission issue.


Programmer response: Ensure that the serveradministrator has the permission to the transactiondirectory in the service registry.

GMOIG0113E Deletion of the transaction messagefile {0} failed.

Explanation: The operation to delete a transactionmessage file failed, most likely due to a permissionissue.


Programmer response: Ensure that the serveradministrator has the permission to the transactionmessages files in the service registry.

GMOIG0114E Input payload is missing.

Explanation: The JSON payload is missing. Anoutmost, top-level element that matches level 01 of theCOBOL data structure is required. For example, if theinput copybook has the following structure:

01 IVTNO-INPUT-MSG.02 IN-LL PICTURE S9(3) COMP.02 IN-ZZ PICTURE S9(3) COMP.02 IN-TRANCDE PICTURE X(10).. . .

The outmost element for the input message must beIVTNO-INPUT-MSG:

{"IVTNO-INPUT-MSG": {

"IN_TRANCDE": "IVTNO",. . .

}}


Programmer response: Ensure that the input messagehas an outmost element that matches level 01 of theCOBOL input data structure and the XML iswell-formed.

GMOIG0115E Unsupported media type.

Explanation: The request is attempting to invoke aservice by using an unsupported media type. Thesupport media type is application/json.


GMOIG0300W Information in the cache cannot belogged. Logging must be enabled firstby adding the com.ibm.ims.gatewaypackage to the logging element inserver.xml.

Explanation: Logging must be enabled in order todump the information in the cache to the log.

System action: An HTTP 412 status code is returned.No action was taken by the system.

Programmer response: Enable logging and tracking byadding the com.ibm.ims.* package to the server.xmlfile. Specify the trace file name, maximum file size,maximum number of files, trace format, and trace level.


“Enabling z/OS Connect EE server trace” on page 267This section describes how to enable the z/OS ConnectEE server trace when you are asked to do so by IBMservice.

GMOIG7777I IMS service provider (build_timestamp)for z/OS Connect Enterprise Editioninitialized successfully.

Explanation: This is an informational message thatindicates the server is up and running with the IMSservice provider properly initialized.


GMOIG7787I The IMS Mobile feature wasdeactivated successfully.



GMOIG0111I • GMOIG7787I


GMOIG7788I IMS Mobile service registry wassuccessfully migrated. Total numbersmigrated: {0} interaction properties, {1}connections , {2} transaction messages,{3} services.

Explanation: This is an informational message toreport the completion of service migration as a result ofserver restart after IMS Mobile feature was updated.


GMOIG7797I The ping request to the z/OS ConnectEE server through the IMS serviceprovider was successful.

Explanation: This is an informational message thatindicates the IMS service provider is configuredproperly on the z/OS Connect EE server.


GMOIG7798I The ping request to the IMS system"IMS_connection_detail" through z/OSConnect EE and the IMS serviceprovider was successful.

Explanation: This is an informational message thatindicates the IMS service provider is configuredproperly on the z/OS Connect EE server, and the IMShost system is configured properly for communicationwith the IMS service provider.


GMOIG7799E The ping request to the IMS system"IMS_connection_detail" through z/OSConnect EE and the IMS serviceprovider did not succeed.

Explanation: Most likely the IMS system is not yet setup to process the request from the IMS serviceprovider.


Programmer response: Ensure that you have thepermission to write to the database.

GMOIG8888E The service service_name could not beupdated in the registry.

Explanation: The specified service could not beupdated, most likely due to a permission issue.


Programmer response: Ensure that IMS and IMSConnect is configured properly and up and running toprocess requests. If RACF is turned on in IMS Connect,the user ID for each request must be configured inRACF on the IMS system. For more information aboutrequired configuration, see “Security configuration forthe IMS mobile solution” on page 140.

GMOMW messagesGMOMW messages are related to conversion of transaction message bytes to JSONor JSON to transaction message bytes.

GMOMW0005E A data type conversion erroroccurred while the leaf field field_nameof transaction message message_id wasconverted: Error_details.

Explanation: See the error details for moreinformation about why the data type conversionoccurred. Most likely the data type does not match theschema, overflows, is too long, is out of range, or isuninitialized.


Programmer response: Use the getRequestSchema orgetResponseSchema action to get the correct dataschema.

GMOMW0006E The byte array was exhausted whilethe leaf field field_name of transactionmessage message_id was read andprocessed.

Explanation: Most likely the data type does not matchthe schema, overflows, is too long, or is out of range.



GMOMW0007E The field field_name of transactionmessage message_id is not a composite.

Explanation: The named field was expected to be acomposite.



GMOMW0008E The field field_name of transactionmessage message_id is not a composite.

Explanation: The named field was expected to be acomposite.


Programmer response: Use the getRequestSchema or

GMOIG7788I • GMOMW0008E


getResponseSchema action to get the correct dataschema.

GMOMW0009E The field field_name of transactionmessage message_id is not a leaf.

Explanation: The named field was expected to be aleaf.



GMOMW0010E The field field_name of transactionmessage message_id is not a leaf array.

Explanation: The named field was expected to be aleaf array.



GMOMW0011E The maximum of number_of_entriesentries for the leaf array field_name oftransaction message message_id wasexceeded.

Explanation: The number of the entries for the leafarray exceeds what was expected.



GMOMW0012E The maximum of number_of_entriesentries for the composite array field_nameof transaction message message_id wasexceeded.

Explanation: The number of the entries for thecomposite array exceeds what was expected.



GMOMW0013E Leaf field field_name with theoccurrence count of array array_name oftransaction message message_id cannot beupdated: error_details

Explanation: Examine the error details for moreinformation about the error. Most likely the data type

of the leaf field is not an integer or not compatible withinteger.


Programmer response: Verify that the data type of theleaf field is compatible with integer and try again.

GMOMW0014E An error occurred when leaf fieldfield_name was read to obtain theoccurrence count of array array_name oftransaction message message_id:error_details

Explanation: Examine the error details for moreinformation about the error. Most likely the data typeof the leaf field array count is not an integer or notcompatible with integer.


Programmer response: Verify that the data type of thearray count is compatible with integer and try again.

GMOMW0015E A mismatch exists between thetransaction message and the interface ofthe service.

Explanation: Anytime a data structure is changed inthe transaction editor you must delete and re-create theservice.


Programmer response: Drop and re-create the serviceto cause a new matching interface to be created.

GMOMW0016E A minimum of {0} entries for thecomposite array {1} of transactionmessage {2} is expected, but only {3}entries were found.

Explanation: The minimum number of entries definedfor a composite field is not met.


Programmer response: Use the getJSONschema actionto get the correct data schema.

GMOMW0017E A minimum of {0} entries for theleaf array {1} of transaction message {2}is expected, but only {3} entries werefound.

Explanation: The minimum number of entries definedfor a leaf field is not met.


Programmer response: Use the getJSONschema actionto get the correct data schema.

GMOMW0009E • GMOMW0017E


GMOPR messagesGMOPR messages are related to properties resources.

GMOPR0002E A duplicate profile named profile_namewas found in the properties registry.

Explanation: The request cannot be executed becausea profile of the same name already exists.

System action: The request cannot be executed. AnHTTP 409 error is returned.

Programmer response: Specify a different profilename.

GMOPR0004E No property with the profile name ofname was found in the registry.

Explanation: The specified profile name was notfound in the registry.


Programmer response: Ensure that the profile name isspecified correctly. Profile names are case-sensitive.

GMOPR0020E The profile name is invalid.

Explanation: Profile names are case-sensitive. Allowedcharacters are A-Z, a-z, 0-9, and "-", ".", "_", and "~".

System action: An HTTP 400 bad request error isreturned.

Programmer response: Ensure that the profile name isspecified correctly.

GMOPR0201I The property_name property wassuccessfully created




GMOPR0202I The property_name property wassuccessfully updated.




GMOPR0203I The property_name property wassuccessfully deleted.




GMOPR0213I No property profiles exist in theregistry.

Explanation: This is an informational response toqueries for available property profiles in the registry.



GMOPR0002E • GMOPR0213I


GMOSR messagesGMOSR messages are related to service resources.

GMOSR0002E Duplicate services were found in theregistry with service name name.

Explanation: The specified service name alreadyexists.

System action: No system action was taken. An HTTP409 status code is returned.

Programmer response: Specify a different servicename.

GMOSR0004E The service_name service was notfound in the registry.

Explanation: The specified service name does not existin the registry.


Programmer response: Specify a valid service name.

GMOSR0005E The service could not be createdbecause the referenced resource_typenamed resource_name was not found inthe registry.

Explanation: The specified name for the identifiedresource type is not valid.


Programmer response: Specify a valid name for theidentified resource type.

GMOSR0011E The service type is not supported.Only service with TRAN service type issupported. Update the service definitionand try again.

Explanation: A value other than TRAN for the servicetype was specified.


Programmer response: Update the service definitionand try again.

GMOSR0012E The service service_name could not beinvoked because it is not started.

Explanation: A service must be started before it can beinvoked.

System action: An HTTP 412 status code(precondition failed) is returned.

Programmer response: Start the service by issuing thestart action first before invoking the service.

GMOSR0201I Service service_name was successfullycreated.


System action: The named service was created, and anHTTP 201 status code is returned.


GMOSR0202I Service service_name was successfullyupdated.




GMOSR0203I Service service_name was successfullydeleted.




GMOSR0204I Service service_name was successfullystarted.




GMOSR0205I Service service_name was successfullystopped.




GMOSR0213I No services exist in the registry.

Explanation: This is an informational response toqueries for available services in the registry.

System action: An HTTP 404 not found status code isreturned.


GMOSR0002E • GMOSR0213I


GMOTM messagesGMOTM messages are related to transaction management.

GMOTM0001E An error occurred while accessing thetransaction message table.

Explanation: The transaction message information inthe registry is not accessible.


Programmer response: Check the trace for possiblecauses. Restart the server, check that the connection isproperly configured, and retry the operation. If theproblem persists, contact IBM Software Support andprovide the trace output.

GMOTM0002E A transaction with transaction codetran_code and message name message_idalready exists in the registry.

Explanation: An entity for the identified transactioncould not be created in the registry because it alreadyexists.



GMOTM0004E The transaction code tran_code withmessage name message_id was not found.

Explanation: The transaction with the identifiedtransaction code and message name does not exist inthe registry.



GMOTM0011E More than one transaction messagewith transaction code tran_code andmessage name message_id exists.

Explanation: The transaction with the identifiedtransaction code and message name already exists inthe registry.



GMOTM0015E No messages exist with transactioncode tran_code and directionmessage_direction.

Explanation: The transaction with the identifiedtransaction code in the input (message_direction=0) oroutput (message_direction=1) message does not exist.


Programmer response: Check that the transactioncode is specified correctly in the interaction properties.

GMOTM0021E The transaction code tran_code wasnot valid.

Explanation: The transaction code cannot be null,empty, or longer than eight characters.


Programmer response: Specify a valid transactioncode. A valid transaction code contains no more thaneight characters.

GMOTM0022E The message namemessage_id was notvalid.

Explanation: The message name cannot be null orempty.


Programmer response: Specify a valid message name.

GMOTM0201I The transaction message withtransaction code tran_code and messagename message_name was successfullycreated.



GMOTM0203I The transaction message withtransaction code tran_code and messagename message_name was successfullydeleted.



GMOTM0213I No transaction messages exist in theregistry.

Explanation: This message is a response to queries foravailable transaction messages in the service registry.

GMOTM0001E • GMOTM0213I




GMOTM0214I No transaction codes exist in theregistry.

Explanation: This message is a response to queries foravailable transactions in the service registry.



GMOTM0221I The transaction message withtransaction code tran_code and messagename message_name was successfullyupdated.



GMOTM0214I • GMOTM0221I


Chapter 18. Reference

This section contains descriptions of the server.xml elements and Javadoc for thez/OS Connect EE SPI. Use this information in your development, to extend z/OSConnect EE.

Configuration elementsYou can use the following elements in your server.xml file to configure z/OSConnect EE:v administrator-role

– group– user

v authCachev authenticationv authorization-roles

– security-role- group- special-subject- user

v basicRegistry– group

- member– user

v classloadingv “config” on page 288v “connectionFactory” on page 289v “connectionManager” on page 290v “containerAuthData” on page 292v jaasLoginContextEntryv jaasLoginModule

– library- file- fileset- folder

– optionsv library

– file– fileset– folder

v ltpav quickStartSecurityv “recoveryAuthData” on page 299v trustAssociation


– interceptors- libraryv filev filesetv folder

- propertiesv zosconnect_auditInterceptorv zosconnect_authorizationInterceptorv “zosconnect_localAdaptersConnectService” on page 302v “zosconnect_services” on page 306

– service- property

v zosconnect_zosConnectAPIsv zosconnect_zosConnectDataXformv zosconnect_zosConnectfileSystemloggerInterceptorv zosconnect_zosConnectInterceptorsv zosconnect_zosConnectManager

– globalInterceptorsRefv zosconnect_zosConnectService

– interceptorsRefv zosconnect_zosConnectServiceRestClient

– basicAuthv zosconnect_zosConnectServiceRestClientConnection

– basicAuthv zosconnect_zosConnectServiceRestClientBasicAuthv “zosLocalAdapters (WOLA)” on page 327

administrator-role A collection of users or groups assigned the server administrator role.

Sub elements

administrator-role > groupDescription: Group assigned a role.

Required: false

Data type: string

administrator-role > userDescription: User assigned a role.

Required: false

Data type: string

authCache Controls the operation of the authentication cache.


allowBasicAuthLookup boolean true Allow lookup by user IDand hashed password.



initialSize integer

Minimum: 1

50 Initial number of entriessupported by theauthentication cache.

maxSize integer

Minimum: 1

25000 Maximum number ofentries supported by theauthentication cache.

timeout A period of time withmillisecond precision

600s Amount of time after whichan entry in the cache willbe removed. Specify apositive integer followed bya unit of time, which can behours (h), minutes (m),seconds (s), or milliseconds(ms). For example, specify500 milliseconds as 500ms.You can include multiplevalues in a single entry. Forexample, 1s500ms isequivalent to 1.5 seconds.

authentication Controls the built-in authentication service configuration.


allowHashtableLoginWithIdOnlyboolean false Allow an application tologin with just an identityin the hashtable properties.Use this option only whenyou have applications thatrequire this and have othermeans to validate theidentity.

cacheEnabled boolean true Enables the authenticationcache.

authorization-roles A collection of role names and mappings of the roles to users, groups, orspecial subjects



Sub elements

authorization-roles > security-roleDescription: A unique configuration ID.

Required: false



name string Role name.

Chapter 18. Reference 285

authorization-roles > security-role > groupDescription: A unique configuration ID.

Required: false


access-id string A group access ID in thegeneral formgroup:realmName/groupUniqueId. A valuewill be generated if one isnot specified.


name string Name of a group that hasthe security role.

authorization-roles > security-role > special-subjectDescription: A unique configuration ID.

Required: false



type v EVERYONE

vALL_AUTHENTICATED_USERS

One of the followingspecial subject types:ALL_AUTHENTICATED_USERS,EVERYONE.

EVERYONEAll users for everyrequest, even if therequest was notauthenticated.

ALL_AUTHENTICATED_USERSAll authenticatedusers.

authorization-roles > security-role > userDescription: A unique configuration ID.

Required: false


access-id string A user access ID in thegeneral formuser:realmName/userUniqueId. A value willbe generated if one is notspecified.


name string Name of a user who hasthe security role.

basicRegistry A simple XML-based user registry.




ignoreCaseForAuthentication boolean false Allow case-insensitive username authentication.

realm string BasicRegistry The realm name representsthe user registry.

Sub elements

basicRegistry > groupDescription: A unique configuration ID.

Required: false



name string Name of a group in a BasicUser Registry.

basicRegistry > group > memberDescription: A unique configuration ID.

Required: false



name string Name of a user in a BasicUser Registry group.

basicRegistry > userDescription: A unique configuration ID.

Required: false



name string Name of a user in a BasicUser Registry.

password One way hashable, orreversably encodedpassword (string)

Password of a user in aBasic User Registry. Thevalue can be stored in cleartext or encoded form. It isrecommended that youencode the password. To doso, use the securityUtilitytool with the encodeoption.

classloading Global classloading



useJarUrls boolean false Whether to use jar: orwsjar: URLs for referencingfiles in archives

config Defines how the server processes configuration information


monitorInterval A period of time withmillisecond precision

500ms Rate at which the serverchecks for configurationupdates. Specify a positiveinteger followed by a unitof time, which can be hours(h), minutes (m), seconds(s), or milliseconds (ms).For example, specify 500milliseconds as 500ms. Youcan include multiple valuesin a single entry. Forexample, 1s500ms isequivalent to 1.5 seconds.

onError v IGNORE

v FAIL

v WARN

WARN Action to take after aincurring a configurationerror.

IGNOREServer will notissue any warningand errormessages when itincurs aconfiguration error.

FAIL Server will issue awarning or errormessage on thefirst erroroccurrence andthen stop theserver.

WARN Server will issuewarning and errormessages when itdetects aconfiguration error.



updatetrigger v mbean

v polled

v disabled

polled Configuration updatemethod or trigger.

mbean Server will onlyupdate theconfigurationwhen prompted bytheFileNotificationMbean.TheFileNotificationMbeanis typically calledby an externalprogram such asan integrateddevelopmentenvironment or amanagementapplication.

If you specify thisvalue, you mustalso configureyour server to usethe JavaManagementExtensions (JMX)connector. Formore information,see “Using anMBean to triggerupdates” on page163.

polled Server will scanfor changes at thepolling interval onall theconfiguration filesand update theruntimeconfiguration withthe changesdetected.

disabledDisables all updatemonitoring.Configurationchanges will notbe applied whilethe server isrunning.

connectionFactoryConnection factory reference.



connectionManagerRef A reference to top levelconnectionManager element(string).

Connection manager for aconnection factory.

containerAuthDataRef A reference to top levelauthData element (string).

Default authentication datafor container managedauthentication that applieswhen bindings do notspecify anauthentication-alias for aresource reference withres-auth=CONTAINER.


jndiName string JNDI name for a resource.

recoveryAuthDataRef A reference to top levelauthData element (string).

Authentication data fortransaction recovery.

connectionManagerConnection manager for a connection factory.


agedTimeout A period of time withsecond precision

-1 Amount of time before aphysical connection can bediscarded by poolmaintenance. A value of -1disables this timeout.Specify a positive integerfollowed by a unit of time,which can be hours (h),minutes (m), or seconds (s).For example, specify 30seconds as 30s. You caninclude multiple values in asingle entry. For example,1m30s is equivalent to 90seconds.

connectionTimeout A period of time withsecond precision

30s Amount of time after whicha connection request timesout. A value of -1 disablesthis timeout. Specify apositive integer followed bya unit of time, which can behours (h), minutes (m), orseconds (s). For example,specify 30 seconds as 30s.You can include multiplevalues in a single entry. Forexample, 1m30s isequivalent to 90 seconds.

maxConnectionsPerThread integer Minimum: 0 Limits the number of openconnections on each thread.



maxIdleTime A period of time withsecond precision

30m Amount of time after whichan unused or idleconnection can bediscarded during poolmaintenance, if doing sodoes not reduce the poolbelow the minimum size. Avalue of -1 disables thistimeout. Specify a positiveinteger followed by a unitof time, which can be hours(h), minutes (m), or seconds(s). For example, specify 30seconds as 30s. You caninclude multiple values in asingle entry. For example,1m30s is equivalent to 90seconds.

maxPoolSize integer Minimum: 0 50 Maximum number ofphysical connections for apool. A value of 0 meansunlimited.

minPoolSize integer Minimum: 0 Minimum number ofphysical connections tomaintain in the pool. Thepool is not pre-populated.Aged timeout can overridethe minimum.

numConnectionsPerThreadLocalinteger Minimum: 0 Caches the specifiednumber of connections foreach thread.



purgePolicy ValidateAllConnections |FailingConnectionOnly |EntirePool

EntirePool Specifies which connectionsto destroy when a staleconnection is detected in apool.

ValidateAllConnectionsWhen a staleconnection isdetected,connections aretested and thosefound to be badare closed.

FailingConnectionOnlyWhen a staleconnection isdetected, only theconnection whichwas found to bebad is closed.

EntirePoolWhen a staleconnection isdetected, allconnections in thepool are markedstale, and when nolonger in use, areclosed.

reapTime A period of time withsecond precision

3m Amount of time betweenruns of the poolmaintenance thread. Avalue of -1 disables poolmaintenance. Specify apositive integer followed bya unit of time, which can behours (h), minutes (m), orseconds (s). For example,specify 30 seconds as 30s.You can include multiplevalues in a single entry. Forexample, 1m30s isequivalent to 90 seconds.

containerAuthDataDefault authentication data for container managed authentication thatapplies when bindings do not specify an authentication-alias for a resourcereference with res-auth=CONTAINER.



password Reversably encodedpassword (string)

Password of the user to usewhen connecting to the EIS.The value can be stored inclear text or encoded form.It is recommended that youencode the password. To doso, use the securityUtilitytool with the encodeoption.

user string Name of the user to usewhen connecting to the EIS.

jaasLoginContextEntry The JAAS login context entry configuration.



loginModuleRef List of references to toplevel jaasLoginModuleelements (comma-separatedstring).

hashtable,userNameAndPassword,certificate,token

A reference to the ID of aJAAS login module.

name string Name of a JAASconfiguration entry.

jaasLoginModule A login module in the JAAS configuration.


className string Fully-qualified packagename of the JAAS loginmodule class.



controlFlag v SUFFICIENT

v REQUISITE

v REQUIRED

v OPTIONAL

REQUIRED The login module's controlflag. Valid values areREQUIRED, REQUISITE,SUFFICIENT, andOPTIONAL.

SUFFICIENTThis LoginModuleis SUFFICIENT asper the JAASspecification. TheLoginModule isnot required tosucceed. Ifauthentication issuccessful, nootherLoginModules willbe called andcontrol is returnedto the caller.

REQUISITEThis LoginModuleis REQUISITE asper the JAASspecification. TheLoginModule isrequired tosucceed. Ifauthenticationfails, no otherLoginModules willbe called andcontrol is returnedto the caller.

REQUIREDThis LoginModuleis REQUIRED asper the JAASspecification. TheLoginModule isrequired tosucceed.

OPTIONALThis LoginModuleis OPTIONAL asper the JAASspecification. TheLoginModule isnot required tosucceed.


libraryRef A reference to top levellibrary element (string).

A reference to the ID of theshared libraryconfiguration.

Sub elements


jaasLoginModule > libraryDescription: A reference to the ID of the shared library configuration.

Required: false


apiTypeVisibility string spec,ibm-api,api The types of API packagethis library's class loaderwill be able to see, as acomma-separated list ofany combination of thefollowing: spec, ibm-api,api, third-party.

description string Description of sharedlibrary for administrators

filesetRef List of references to toplevel fileset elements(comma-separated string).

Id of referenced Fileset

name string Name of shared library foradministrators

jaasLoginModule > library > fileDescription: Id of referenced File

Required: false



name Path to a file Fully qualified filename

jaasLoginModule > library > filesetDescription: Id of referenced Fileset

Required: false


caseSensitive boolean true Boolean to indicate whetheror not the search should becase sensitive (default:true).

dir Path to a directory ${server.config.dir} The base directory to searchfor files.

excludes string The comma or spaceseparated list of file namepatterns to exclude fromthe search results, bydefault no files areexcluded.


includes string * The comma or spaceseparated list of file namepatterns to include in thesearch results (default: *).



scanInterval A period of time withmillisecond precision

0 Scanning interval to checkthe fileset for changes as along with a time unit suffixh-hour, m-minute, s-second,ms-millisecond (e.g. 2ms or5s). Disabled(scanInterval=0) by default.Specify a positive integerfollowed by a unit of time,which can be hours (h),minutes (m), seconds (s), ormilliseconds (ms). Forexample, specify 500milliseconds as 500ms. Youcan include multiple valuesin a single entry. Forexample, 1s500ms isequivalent to 1.5 seconds.

jaasLoginModule > library > folderDescription: Id of referenced folder

Required: false


dir Path to a directory Directory or folder to beincluded in the libraryclasspath for locatingresource files


jaasLoginModule > optionsDescription: A collection of JAAS Login module options

Required: false

library Shared Library









Sub elements

library > fileDescription: Id of referenced File

Required: false




library > filesetDescription: Id of referenced Fileset

Required: false









library > folderDescription: Id of referenced folder

Required: false





ltpa Lightweight Third Party Authentication (LTPA) token configuration.


expiration A period of time withminute precision

120m Amount of time after whicha token expires in minutes.Specify a positive integerfollowed by a unit of time,which can be hours (h) orminutes (m). For example,specify 30 minutes as 30m.You can include multiplevalues in a single entry. Forexample, 1h30m isequivalent to 90 minutes.

keysFileName Path to a file ${server.output.dir}/resources/security/ltpa.keys

Path of the file containingthe token keys.

keysPassword Reversably encodedpassword (string)

{xor}CDo9Hgw= Password for the tokenkeys. The value can bestored in clear text orencoded form. It isrecommended to encodethe password, use thesecurityUtility tool with theencode option.

monitorInterval A period of time withmillisecond precision

0ms Rate at which the serverchecks for updates to theLTPA token keys file.Specify a positive integerfollowed by a unit of time,which can be hours (h),minutes (m), seconds (s), ormilliseconds (ms). Forexample, specify 500milliseconds as 500ms. Youcan include multiple valuesin a single entry. Forexample, 1s500ms isequivalent to 1.5 seconds.

quickStartSecurity Simple administrative security configuration.


userName string Single user defined as partof the quick start securityconfiguration. This user isgranted the Administratorrole.



userPassword Reversably encodedpassword (string)

Password for the singleuser defined as part of thequick start securityconfiguration. It isrecommended that youencode this password. Todo so, use thesecurityUtility tool with theencode option.

recoveryAuthDataAuthentication data for transaction recovery.



Password of the user to usewhen connecting to the EIS.The value can be stored inclear text or encoded form.It is recommended that youencode the password. To doso, use the securityUtilitytool with the encodeoption.

user string Name of the user to usewhen connecting to the EIS.

trustAssociation Controls the operation of the trust association interceptor (TAI).


failOverToAppAuthType boolean false Allow an interceptor to fallback to the applicationauthentication mechanism.


invokeForUnprotectedURI boolean false Controls whether the TAI isinvoked for an unprotectedURI.

Sub elements

trustAssociation > interceptorsDescription: A unique configuration ID.

Required: false


className string Fully-qualified packagename of the interceptorclass.

enabled boolean true Enables or disables theinterceptor.


invokeAfterSSO boolean true Invoke an interceptor aftersingle sign-on (SSO).



invokeBeforeSSO boolean false Invoke an interceptorbefore single sign-on (SSO).

libraryRef A reference to top levellibrary element (string).

A reference to the ID of theshared libraryconfiguration.

trustAssociation > interceptors > libraryDescription: A reference to the ID of the shared libraryconfiguration.

Required: false







trustAssociation > interceptors > library > fileDescription: Id of referenced File

Required: false




trustAssociation > interceptors > library > filesetDescription: Id of referenced Fileset

Required: false











trustAssociation > interceptors > library > folderDescription: Id of referenced folder

Required: false




trustAssociation > interceptors > propertiesDescription: Collection of properties for the interceptor.

Required: false

zosconnect_auditInterceptorDefines the audit interceptor for z/OS Connect EE to allow request data tobe logged using System Management Facility (SMF) 123 subtype 1 recordson z/OS.





sequence integer

Minimum: 0

Maximum: 2147483647

0 The sequence in which thisinterceptor should beprocessed with respect toother configuredinterceptors implementingthecom.ibm.wsspi.zos.connect.InterceptorService Provider Interface(SPI) for z/OS Connect EE.

zosconnect_authorizationInterceptorDefines a z/OS Connect EE authorization interceptor.



sequence integer

Minimum: 0

Maximum: 2147483647

0 The sequence in which thisinterceptor should beprocessed with respect toother configuredinterceptors implementingz/OS Connect'scom.ibm.wsspi.zos.connect.InterceptorService Provider Interface(SPI).

zosconnect_localAdaptersConnectServiceRepresents a WOLA service:

The following table lists the attributes that are applicable to bothCOMMAREA and channel payloads.


connectionFactoryRef string Reference to the configuredconnection factory elementcontaining the JNDI nameof the WOLA resourceadapter connection factoryto be used.

connectionWaitTimeout integer

Minimum: 0

Maximum: 2147483647

Number of seconds to waitfor an external addressspace application thatmatches the registrationname to issue a WOLAReceive Request or HostService API and becomeactive.




serviceName string Name of the WOLA targetservice. This service namemust match the name anexternal address spaceapplication is using for theservice name on a WOLAReceive Request or HostService API call, or theprogram name used forSVC with a WOLA CICSLink Server.

registerName string Name of the WOLA targetregister. This name mustmatch the name an externaladdress space application isusing for the register nameon a WOLA Register APIcall, or the name used forRegister Name with aWOLA CICS Link Server.

linkTaskTranID string When using the WOLACICS Link Server, specifiesthe name of the WOLACICS Link Server linkinvocation task transactionID.

useCICSContainer boolean false When using the WOLACICS Link Server, definesthe mechanism to use fordata propagation. When setto true, the payload ispassed to the target CICSapplication program usingCICS containers. When setto false (default), thepayload is passed the targetCICS application programusing a COMMAREA. Seethe tables below for adescription of theadditional attributesrequired for channelpayloads.

useGenericError boolean true When enabled, all errorcases from the service willreturn a HTTP status codeof 500 Internal Server Error.This option is retained forcompatibility with previousversions of z/OS ConnectEE.

There are two different methods of specifying the channel and containerattributes. These methods are mutually exclusive:v Method 1: Use a channel name of IBM-WAS-ADAPTER to flow a single

payload container. Specify the following attributes:



linkTaskReqContID string When using the WOLACICS Link Server and thelinkTaskRspContID anduseCICSContainer (true)attributes are alsoconfigured, specifies thename of the request, orinput, container. Thedefault CICS channel nameis IBM-WAS-ADAPTER.The container name mustnot include blankcharacters.

linkTaskReqContType integer

Minimum: 0

0 When using the WOLACICS Link Server and thelinkTaskReqContID anduseCICSContainer (true)attributes are alsoconfigured, specifies thetype of the requestcontainer (0=CHAR,1=BIT). The default CICSchannel name isIBM-WAS-ADAPTER.

linkTaskRspContID string When using the WOLACICS Link Server and thelinkTaskReqContID anduseCICSContainer (true)attributes are alsoconfigured, specifies thename of the response, oroutput container. Thecontainer name must notinclude blank characters.

linkTaskRspContType integer

Minimum: 0

0 When using the WOLACICS Link Server and thelinkTaskRspContID anduseCICSContainer (true)attributes are alsoconfigured, specifies thetype of response container(0=CHAR, 1=BIT).

v Method 2: Use a channel name of your choice to flow a single payloadcontainer with the HTTP context containers. Specify the followingattributes:



linkTaskChanID string When using the WOLACICS Link Server and theuseCICSContainer (true)attribute is also configured,specifies the CICS channelname to use for deliveringmessages and receivingpayloads using CICScontainers. The channelname must not includeblank characters.

linkTaskChanType integer

Minimum: 0

0 When using the WOLACICS Link Server and thelinkTaskChanID anduseCICSContainer (true)attributes are alsoconfigured, specifies thetype of the CICS containers(0=CHAR, 1=BIT) that areto be associated with theconfigured channel ID.When set to 0(default), theencoding of the characterdata in the input/outputcontainers areexpected/returned in ASCII(CCSID 819) and the data isconverted to or fromEBCDIC (cp037)before/after it is sentto/from the destinationprogram. Use the BIT typeto avoid data type andencoding expectations.

linkTaskChanReqContID string ZCONReqData When using the CICS LinkServer and when thelinkTaskChanID anduseCICSContainer (true)attributes are alsoconfigured, specifies thename of the requestcontainer. The containername must not includeblank characters.

linkTaskChanRespContID string ZCONRespData When using the CICS LinkServer and when thelinkTaskChanID anduseCICSContainer (true)attributes are alsoconfigured, specifies thename of the responsecontainer. The containername must not includeblank characters.



linkTaskChanCtxContEncodingstring cp819 When using the CICS LinkServer and when thelinkTaskChanID anduseCICSContainer (true)attributes are alsoconfigured, specifies theencoding of the data in allcontext containers that aresent to the destinationprogram.

linkTaskChanCtxContHttpHeadersstring When using the CICS LinkServer and thelinkTaskChanID anduseCICSContainer (true)attributes are alsoconfigured, specifies theHTTP header name or listof comma-separated andcase-sensitive HTTP headernames that are passed tothe destination programusing the context containerwith the name ofZCONHTTPHeaders. Theinformation contained inthis context container is inJSON format:{httpHeaders:{"header1":"header1Value",...,"header-n":"headerValue-n"}}. Ifthe request containsmultiple headers with thesame name, the value thatis used is the one for thefirst header in the request.

zosconnect_servicesDefines the directory where service packages are stored.


location string Path to a directory locationwhere SAR packages arestored.

pollingRate long (A period of time withmillisecond precision)

5s Controls how often theserver polls the servicesdirectory. Specify a positiveinteger followed by a unitof time, which can be hours(h), minutes (m), seconds(s), or milliseconds (ms).For example, specify 500milliseconds as 500ms. Youcan include multiple valuesin a single entry. Forexample, 1s500ms isequivalent to 1.5 seconds.



updateTrigger string disabled Controls when the runtimeis notified about changes inthe services directory.Acceptable values aredisabled, polled or mbean.The default value isdisabled.

disabledUpdates to thefiles in thedirectory are notacted upon by theruntime.

polled The server willperiodically checkfor changes to thedirectory contents.

mbean The server willcheck for changeswhen thenotifyFileChangesmethod is invokedon theFileNotificationMBean.


service A list of service elements. The serviceName elementsdefine the resources in theSAR package.

Sub elements

zosconnect_services > serviceDescription: Defines the resources in the SAR package.

Required: true


name string The name of the service.

requireSecure boolean true Require that requests aresent over HTTPS.

requireAuth boolean true Require that users specifysecurity credentials in orderto call the URI.



runGlobalInterceptors boolean true Indicates whether globalinterceptors should run forrequests that are associatedwith this service. Globalinterceptors are listed inglobalInterceptorsRef inthezosconnect_zosConnectManagerelement. By default, z/OSConnect EE processes allglobal and serviceendpoint-specificinterceptors. If therunGlobalInterceptors isset to false, z/OS ConnectEE processes only the set ofinterceptors that are listedin the interceptorsRefattribute.

interceptorsRef string Reference name thatidentifies the set ofconfigured interceptors thatare associated with thisservice.Note: If the service iscalled by an API, then onlythe interceptors configuredfor that API are processed.Interceptors defined for theservice are ignored.

adminGroup string Administrative group namethat is associated with thisservice. A user must be amember of this securitygroup to be able to useadministrative functions. IfglobalAdminGroup is alsodefined under elementzosconnect_zosConnectManager,then the value definedunder adminGroup is used.

invokeGroup string Invoke group name that isassociated with this service.A user must be a memberof this security group to beable to invoke the API. IfglobalInvokeGroup is alsodefined under elementzosconnect_zosConnectManager,then the value definedunder invokeGroup is used.



operationsGroup string Operations group namethat is associated with thisservice. A user must be amember of this securitygroup to be able to performoperations such as startingor stopping this service. IfglobalOperationsGroup isalso defined under elementzosconnect_zosConnectManager,then the value definedunder operationsGroup isused.

readerGroup string Reader group name that isassociated with this service.A user must be a memberof this security group to beable to get informationabout this service includingthe Swaggerdocumentation. IfglobalReaderGroup is alsodefined under elementzosconnect_zosConnectManager,then the value definedunder readerGroup is used.

property A list of property elements. The property elementsdefine the overrideproperties for the SARpackage.

zosconnect_services > service > propertyDescription: Optional properties for the service provider.

Required: false


name string The name of the property

value string The value of the property

zosconnect_zosConnectAPIsDefines the directory where API packages are stored.


location string Path to a directory locationwhere API packages arestored.



pollingRate long (A period of time withmillisecond precision)

5s Controls how often theserver polls the apisdirectory. Specify a positiveinteger followed by a unitof time, which can be hours(h), minutes (m), seconds(s), or milliseconds (ms).For example, specify 500milliseconds as 500ms. Youcan include multiple valuesin a single entry. Forexample, 1s500ms isequivalent to 1.5 seconds.

updateTrigger string disabled Controls when the runtimeis notified about changes inthe apis directory.Acceptable values aredisabled, polled or mbean.

disabledUpdates to thefiles in thedirectory are notacted upon by theruntime.

polled The server willperiodically checkfor changes to thedirectory contents.

mbean The server willcheck for changeswhen thenotifyFileChangesmethod is invokedon theFileNotificationMBean.


zosConnectAPI A list of zosConnectAPIelements.

The zosConnectAPIelements define theresources in the APIpackage.

Sub elements


zosconnect_zosConnectAPIs > zosConnectAPIDescription: Defines the resources in the API package.

Required: true


name string A name of the API.


requireAuth boolean true Require that users specifysecurity credentials in orderto call the URI.

runGlobalInterceptors boolean true Indicates whether globalinterceptors should run forrequests that are associatedwith this API. Globalinterceptors are listed inglobalInterceptorsRef inthezosconnect_zosConnectManagerelement. By default, z/OSConnect EE processes allglobal and serviceendpoint-specificinterceptors. If therunGlobalInterceptors isset to false, z/OS ConnectEE processes only the set ofinterceptors that are listedin the interceptorsRefattribute.

interceptorsRef string Reference name thatidentifies the set ofconfigured interceptors thatare associated with thisAPI.Note: If a service is calledby the API, then only theinterceptors configured forthe API are processed.Interceptors defined for theservice are ignored.

adminGroup string Administrative group namethat is associated with thisAPI. A user must be amember of this securitygroup to be able to useadministrative functions. IfglobalAdminGroup is alsodefined under elementzosconnect_zosConnectManager,then the value definedunder adminGroup is used.



invokeGroup string Invoke group name that isassociated with this API. Auser must be a member ofthis security group to beable to invoke the API. IfglobalInvokeGroup is alsodefined under elementzosconnect_zosConnectManager,then the value definedunder invokeGroup is used.

operationsGroup string Operations group namethat is associated with thisAPI. A user must be amember of this securitygroup to be able to performoperations such as startingor stopping this API. IfglobalOperationsGroup isalso defined under elementzosconnect_zosConnectManager,then the value definedunder operationsGroup isused.

readerGroup string Reader group name that isassociated with this API. Auser must be a member ofthis security group to beable to get informationabout this API includingthe Swaggerdocumentation. IfglobalReaderGroup is alsodefined under elementzosconnect_zosConnectManager,then the value definedunder readerGroup is used.

zosconnect_zosConnectDataXformDefines a z/OS Connect EE data transformer.


bindFileLoc string File system path where thebind files are located.

bindFileSuffix string Suffix name that isassociated with the bindfiles.




pollingRate A period of time withmillisecond precision

2s Rate at which the serverchecks for updates to datatransformation-related filessuch as bind or schemafiles. Specify a positiveinteger followed by a unitof time, which can be hours(h), minutes (m), seconds(s), or milliseconds (ms).For example, specify 500milliseconds as 500ms. Youcan include multiple valuesin a single entry. Forexample, 1s500ms isequivalent to 1.5 seconds.

requestSchemaLoc string File system path where therequest schema files arelocated.

requestSchemaSuffix string Suffix name that isassociated with the requestschema files.

responseSchemaLoc string File system path where theresponse schema files arelocated.

responseSchemaSuffix string Suffix name that isassociated with theresponse schema files.



updateTrigger v mbean

v polled

v disabled

polled Update trigger for datatransformation files such asbind and schema files.

mbean Server reloads datatransformationfiles whenprompted by anMBean called byan externalprogram such asan integrateddevelopmentenvironment or amanagementapplication.


polled Server scans forchanges at thepolling intervaland reload anyfiles that havedetectable changes.

disabledDisables all updatemonitoring. Datatransformation filechanges are not beapplied while theserver is running.

zosconnect_zosConnectfileSystemloggerInterceptorDefines a z/OS Connect EE File System logger interceptor.


bufferSize integer 8192 Buffer size in bytes to beused when thebufferLogging attribute isset to true.

bufferedLogging boolean false Indicates whether entries tothe log are buffered beforethey are written to the logfile.



encoding string UTF-8 Encoding that is used whenwritting to the log file.


logName string Log file name pattern thatis used for payload logging.

logOption v RESPONSE

v REQUEST

v ALL

ALL Log option that controlswhat is logged.

RESPONSEIndicates that onlyresponse data islogged.

REQUESTIndicates that onlyrequest data islogged.

ALL Indicates that bothrequest andresponse data arelogged.

logPath string File system location inwhich the file log iscreated. If the environmentvariable ${server.output.dir}is configured, its value isused by default.

maxPayloadSize integer 524288 Maximum payload size incharacters that are allowedto be written to the log file.

rollOffLogPolicy v SIZE

v DURATION

SIZE Indicates that log file isrolled off based on size orduration.

SIZE Indicates that thelog file is roll-offbased on the sizeof the log.

DURATIONIndicates that theroll-off log policyis based on theelapsed time sincethe active log filewas created.

rollOffLogPolicyDuration integer 1440 Roll off policy duration inminutes.

rollOffLogPolicySize integer 52428800 Roll off policy size in bytes.

sequence integer

Minimum: 0

Maximum: 2147483647

0 Sequence in which theinterceptor is processedwith respect to others.


zosconnect_zosConnectInterceptorsBundles 1 to N interceptors.



interceptorRef List of references to toplevel auditInterceptorelements (comma-separatedstring).

The identifier of one ormore interceptors.

zosconnect_zosConnectManagerDefines global configuration settings for z/OS Connect EE.



asyncRequestTimeout A period of time withmillisecond precision

Timeout value that isassociated with all serviceendpoints when processingasynchronous work. Itspecifies the time inmilliseconds in whichrequests have to complete.This timeout valueoverrides the webcontainer'sasyncTimeoutDefaultattribute value. If neitherasyncRequestTimeout norasyncTimeoutDefault areconfigured, the timeoutused is theasyncTimeoutDefaultattribute default value (i.e.30 seconds). IfasyncRequestTimeout isnot configured, but theasyncTimeoutDefaultattribute is, the valuedefined inasyncTimeoutDefault isused. A timeout may occurat any time duringprocessing of the requestz/OS Connect EE. Therequest might still be activeafter the timeout is detectedand a response is sent tothe client. Specify a positiveinteger followed by a unitof time, which can be hours(h), minutes (m), seconds(s), or milliseconds (ms).For example, specify 500milliseconds as 500ms. Youcan include multiple valuesin a single entry. Forexample, 1s500ms isequivalent to 1.5 seconds.



globalAdminGroup string Administrative group namethat is associated with allAPIs and service endpoints.A user must be a memberof this group forpermission to performadministrative functions.

globalDataXformRef A reference to top levelzosconnect_zosConnectDataXformelement (string).

Reference name thatidentifies the datatransformation handler thatis associated with allservice endpoints.

globalInvokeGroup string Invoke group name that isassociated with all APIsand service endpoints. Auser must be a member ofthis group to havepermission to make invokecalls.

globalOperationsGroup string Operations group namethat is associated with allAPIs and service endpoints.A user must be a memberof this group to havepermission to performoperations such as start,stop, or status.

globalReaderGroup string Reader group name that isassociated with all APIsand service endpoints. Auser must be a member ofthis group to havepermission to performactions such as listing andgetting details of APIs andservices, including the APISwagger documentation.

operationMode v SYNC

v ASYNC

ASYNC Specifies the mode inwhich z/OS Connect EErequests will be processed.

SYNC Synchronous modeof operation

ASYNCAsynchronousmode of operation

preserveJsonObjectPayloadOrderboolean false When enabled, the order ofentries in a JSON objectpayload is preserved.



preserveJsonPayloadCharFormatboolean false Indicates if the characters inthe JSON payload shouldflow unchanged throughz/OS Connect EE duringrequest handling such asAPI invocation, serviceinvocation and schemaretrievals. When set tofalse, UTF-8 encodedcharacters might beconverted to theirrespective escaped Unicoderepresentation. For thisattribute to take effect, theattribute definitionsetUTF8ResponseEncodingmust be set to true.

requireAuth boolean true Require that users specifysecurity credentials forpermission to call the URI.


useJsonErrorResponses boolean false When enabled, errorresponses from the serverare in JSON format.

setUTF8ResponseEncoding boolean false Indicates whether thecharacter encoding in theHTTP response is set toUTF-8.

Sub elements

zosconnect_zosConnectManager > globalInterceptorsRefDescription: Reference name that identifies the set of configuredinterceptors that is associated with all APIs and services. If services donot require global interceptors association, the runGlobalInterceptorsattribute of the zosconnect_zosConnectService element can be set tofalse. If APIs do not require global interceptors association, therunGlobalInterceptors attribute of the zosConnectAPI element can beset to false.

Note: If a service is called by an API, then only the inteceptorsconfigured for the API are processed. Interceptors defined for theservice are ignored.

Required: false

Data type: tokenType

zosconnect_zosConnectServiceDefines the configuration settings for a service endpoint.



adminGroup string Administrative group namethat is associated with aservice endpoint. It is thename of the security groupthat the user needs to be inbefore administrativefunctions are permitted. If itis configured along with itsglobal counterpart,globalAdminGroup definedunder elementzosconnect_zosConnectManager,the value defined underadminGroup is used.

dataXformRef A reference to top levelzosconnect_zosConnectDataXformelement (string).

Reference name thatidentifies the datatransformation handler thatis associated with a serviceendpoint. If configuredalong with its global datatransformation handlercounterpart(globalDataXformRefdefined under elementzosconnect_zosConnectManager),the data transformerdefined for the serviceendpoint is used.


invokeGroup string Invoke group name that isassociated with a serviceendpoint. It contains thename of the security groupthat the user needs to be inbefore invoke calls arepermitted. If it is configuredalong with its globalcounterpart,globalInvokeGroup definedunder elementzosconnect_zosConnectManager,the value defined underinvokeGroup is used.



invokeURI string URI or list ofcomma-separated URIs toassociate with a serviceendpoint. InvokeURIs canend with a wildcardcharacter in the form/a/b/* or x/y* togenerically match a serviceendpoint invocation.Specifying multiplewildcard characters (i.e./a/b/**) or wildcardcharacters in the middle ofthe requestURI (i.e. /a/*/c)is not supported. If serviceendpoints with configuredinvokeURIs using thewildcard character areassociated with overlappinginvokeURIs, the serviceendpoint associated withthe most specific invokeURIis matched. For instance, ifa service endpoint requestis issued with the following:https://host:port/a/b/cgoing to a server with thefollowing configuration:service1 ->invokeURI="/a/b/c/*" andservice2 ->invokeURI="/a/b/*", z/OSConnect EE will match therequest to service1.Configured invokeURIentries must start with the/ character. The use of aninvokeURI is equivalent toa service request where theaction=invoke queryparameter is specified.

operationsGroup string Operations group name thatis associated with a serviceendpoint. A user must be amember of this group to beable to perform operationssuch as start, stop, or status.If it is configured alongwith its global counterpart,globalOperationsGroupdefined under elementzosconnect_zosConnectManager,the value that is definedunder operationsGroup isused.



readerGroup string Reader group name that isassociated with this API. Auser must be a member ofthis security group to beable to get informationabout this API including theSwagger documentation. IfglobalReaderGroup is alsodefined under elementzosconnect_zosConnectManager,then the value definedunder readerGroup is used.

requireAuth boolean true Require that users specifysecurity credentials to callthe URI.


runGlobalInterceptors boolean true Indicates whether globalinterceptors run for requeststhat are associated with aservice endpoint. By defaultz/OS Connect EE processesall global and serviceendpoint-specificinterceptors .



serviceAsyncRequestTimeout A period of time withmillisecond precision

Timeout value that isassociated with a serviceendpoint when processingasynchronous work. Itspecifies the time inmilliseconds in whichrequests must complete.This timeout valueoverrides the webcontainer'sasyncTimeoutDefaultattribute value. If neitherasyncRequestTimeout norasyncTimeoutDefault areconfigured, the timeoutused is theasyncTimeoutDefaultattribute default value (i.e.30 seconds). IfasyncRequestTimeout is notconfigured, but theasyncTimeoutDefaultattribute is, theasyncTimeoutDefault'sconfigured value is used. Ifconfigured along with itsglobal counterpart:asyncRequestTimeoutdefined under elementzosconnect_zosConnectManager,the value defined underserviceAsyncRequestTimeoutis used. A timeout mayoccur at any time duringz/OS Connect's processingof the request. The requestmay still be active after thetimeout is detected and aresponse is sent to theclient. Specify a positiveinteger followed by a unitof time, which can be hours(h), minutes (m), seconds(s), or milliseconds (ms).For example, specify 500milliseconds as 500ms. Youcan include multiple valuesin a single entry. Forexample, 1s500ms isequivalent to 1.5 seconds.

serviceDescription string Description that isassociated with a serviceendpoint.

serviceGroupingName string Name that can be used togroup or associate a set ofservice endpoints together.



serviceName string Name that is associatedwith a service endpoint.This name identifies aservice endpoint to a client.

serviceRef A reference to top levellocalAdaptersConnectServiceelement (string).

Reference name thatidentifies the serviceendpoint that is registeredwith z/OS Connect.

Sub elements

zosconnect_zosConnectService > interceptorsRefDescription: Reference name that identifies the set of configuredinterceptors that is associated with a service endpoint. If it isconfigured along with its global interceptors counterpart(globalInterceptorsRef defined under thezosconnect_zosConnectManager element), z/OS Connect EE processesboth sets of interceptors. If the runGlobalInterceptors attribute for theservice endpoint is set to false, z/OS connect will only process the setof interceptors configured for the service endpoint.

Required: false

Data type: tokenType

zosconnect_zosConnectServiceRestClientAllows requests to be routed from z/OS Connect EE to a remote RESTendpoint.


basicAuthRef A reference to top levelzosconnect_zosConnectServiceRestClientBasicAuthelement (string).

Reference name thatidentifies the basicauthentication data to beused for connecting to aremote REST endpoint.

connectionRef A reference to top levelzosconnect_zosConnectServiceRestClientConnectionelement (string)

If set, then the connectionwill be made using theattributes of thezosconnect_zosConnectServiceRestClientConnectionelement. If not set, or thezosconnect_zosConnectServiceRestClientConnectionelement does not exist, thenthe values from thezosconnect_zosConnectServiceRestClientelement will be used.



connectionTimeout A period of time withmillisecond precision

30s The connection timeoutspecifies the amount oftime that the client willattempt to establish aconnection to the remoteendpoint before it timesout. If the timeout value isset to 0, the client willattempt to open aconnection indefinitely.Specify a positive integerfollowed by a unit of time,which can be hours (h),minutes (m), seconds (s), ormilliseconds (ms). Forexample, specify 500milliseconds as 500ms. Youcan include multiple valuesin a single entry. Forexample, 1s500ms isequivalent to 1.5 seconds.

host string IP address, domain nameserver (DNS) host namewith domain name suffix,or just the DNS host name,used to route the request.

httpMethod string Name of the HTTP methodto be used when routingHTTP requests. If nomethod is specified, themethod used is the one inthe original request.


port string Port used for routing HTTPor HTTPS requests.

receiveTimeout A period of time withmillisecond precision

60s The receive timeoutspecifies the amount oftime that the client willwait for a response fromthe remote endpoint beforeit times out. If the timeoutvalue is set to 0, the clientwill wait for a responseindefinitely. Specify apositive integer followed bya unit of time, which can behours (h), minutes (m),seconds (s), or milliseconds(ms). For example, specify500 milliseconds as 500ms.You can include multiplevalues in a single entry. Forexample, 1s500ms isequivalent to 1.5 seconds.



sslCertsRef string An SSL repertoire with anID, a defined keystore, andtruststore.

uri string URI that identifies theresource to contact whenrouting HTTP requests. Ifno URI is specifiedeverything after the portnumber from the originalrequest is used.

Sub elements

zosconnect_zosConnectServiceRestClient > basicAuthDescription: Reference name that identifies the basic authenticationdata to be used for connecting to a remote REST endpoint.

Required: false



Password of the user underwhich the request will berouted. The value can bestored in clear text orencoded. It isrecommended that thepassword be encoded. Todo so, use thesecurityUtility shipped withWebSphere Liberty profile.

userName string Name of the user underwhich the request will berouted.

zosconnect_zosConnectServiceRestClientConnectionAllows requests to be routed from z/OS Connect EE to a remote RESTendpoint.


basicAuthRef A reference to top levelzosconnect_zosConnectServiceRestClientBasicAuthelement (string).

Reference name thatidentifies the basicauthentication data to beused for connecting to aremote REST endpoint.



connectionTimeout A period of time withmillisecond precision

30s The connection timeoutspecifies the amount oftime that the client willattempt to establish aconnection to the remoteendpoint before it timesout. If the timeout value isset to 0, the client willattempt to open aconnection indefinitely.Specify a positive integerfollowed by a unit of time,which can be hours (h),minutes (m), seconds (s), ormilliseconds (ms). Forexample, specify 500milliseconds as 500ms. Youcan include multiple valuesin a single entry. Forexample, 1s500ms isequivalent to 1.5 seconds.

host string IP address, domain nameserver (DNS) host namewith domain name suffix,or just the DNS host name,used to route the request.


port string Port used for routing HTTPor HTTPS requests.

receiveTimeout A period of time withmillisecond precision

60s The receive timeoutspecifies the amount oftime that the client willwait for a response fromthe remote endpoint beforeit times out. If the timeoutvalue is set to 0, the clientwill wait for a responseindefinitely. Specify apositive integer followed bya unit of time, which can behours (h), minutes (m),seconds (s), or milliseconds(ms). For example, specify500 milliseconds as 500ms.You can include multiplevalues in a single entry. Forexample, 1s500ms isequivalent to 1.5 seconds.

sslCertsRef string An SSL repertoire with anID, a defined keystore, andtruststore.

Sub elements

zosconnect_zosConnectServiceRestClientConnection > basicAuthDescription: Reference name that identifies the basic authenticationdata to be used for connecting to a remote REST endpoint.


Required: false





zosconnect_zosConnectServiceRestClientBasicAuthBasic authentication data for connecting to a remote REST endpoint.






zosLocalAdapters (WOLA)

WebSphere Optimized Local Adapters.


useCicsTaskUserId boolean false If security is enabled in theWOLA client, this settingcontrols which user ID ispropagated to this z/OSConnect EE server when aWOLA request is sent fromthe client to the server. Ifyou enable this setting, theuser ID of the task thatmakes the request ispropagated. If you do notenable this setting, the userID of the client addressspace is propagated. Thissetting is applicable only toCICS clients.



wolaGroup string The WOLA group name isthe first part of the 3-partWOLA name. The namecannot contain lowercaseletters.

wolaName2 string The 2nd part of the 3-partWOLA name. The namecannot contain lowercaseletters.

wolaName3 string The 3rd part of the 3-partWOLA name. The namecannot contain lowercaseletters.

Command referenceSyntax of the z/OS Connect EE commands.

apideploy command syntaxDeploy or undeploy APIs

Syntax

apideploy -deploy -a <path to api archiveFile> -p <path to apiDeploy location> -w

apideploy -undeploy -a <path to api archiveFile> -p <path to apiDeploy location>

Parameters

-deploySpecifies the API deployment task.

-undeploySpecifies the API undeployment task.

-a Specifies the relative or absolute path to the API archive file. The archive filehas a file type of .aar. The path cannot include parentheses and soft links arenot supported.

-p Specifies the relative or absolute path to the API deployment location for theserver. For example, <WLP_USER_DIR>/servers/<serverName>/resources/zosconnect/apis. The path cannot include parentheses and soft links are notsupported.

-w If specified, the API replaces the API, if it is already deployed, with the newversion. The API identifier is the API name that is specified in the z/OSConnect EE API Editor when you create the API.

Examples

The following example deploys the API that is defined in the goodhealth.aar fileby specifying an absolute path to the .aar file and an absolute path to the APIdeployment directory.apideploy -deploy -a /usr/lpp/myAPIs/goodhealth.aar-p <WLP_USER_DIR>/servers/<serverName>/resources/zosconnect/apis


The following example redeploys an API by specifying the -w parameter:apideploy -deploy -a /usr/lpp/myAPIs/goodhealth.aar-p <WLP_USER_DIR>/servers/<serverName>/resources/zosconnect/apis -w

The following example undeploys the API that is defined in the goodhealth.aarfile by specifying an absolute path to the .aar file and an absolute path to the APIdeployment directory.apideploy -undeploy -a /usr/lpp/myAPIs/goodhealth.aar-p <WLP_USER_DIR>/servers/<serverName>/resources/zosconnect/apis

zconbt command syntax

Syntax

zconbt properties=<filename>.properties file=<filename>.sar verbose help

Parameter usage

-p | --propertiesSpecifies the name of the properties file that is used to create the servicearchive file.

-f | --fileSpecifies the path and file name of the service archive file. The file type is.sar.

-v | --verboseReturns more information when the utility is running.

-h | --helpReturns list of available options that the user can enter.

Example

The following example command uses the values in the health.properties file tocreate the service archive.

zconbt -p=health.properties -f=./health.sar

zosconnect command syntax

Syntax

zosconnect create <server name> --template=<template name>

Parameters

createSpecifies that a z/OS Connect EE server is created.

--templateThe name of the template to be used to create the server. The default iszosconnect:default.

--cleanRemoves all persistent cached information that is related to the specified serverinstance.


Example

zosconnect create myserver --template=zosconnect:default

zconsetup command syntax

Syntax

zconsetup install

Parameters

installSpecifies that the product extension directories be created.

Example

zconsetup install


Notices

This information was developed for products and services offered in the US. Thismaterial might be available from IBM in other languages. However, you may berequired to own a copy of the product or product version in that language in orderto access it.

IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property rights maybe used instead. However, it is the user's responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle Drive, MD-NC119Armonk, NY 10504-1785United States of America

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan Ltd.19-21, Nihonbashi-Hakozakicho, Chuo-kuTokyo 103-8510, Japan

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESSFOR A PARTICULAR PURPOSE. Some jurisdictions do not allow disclaimer ofexpress or implied warranties in certain transactions, therefore this statement maynot apply to you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM websites are provided forconvenience only and do not in any manner serve as an endorsement of thosewebsites. The materials at those websites are not part of the materials for this IBMproduct and use of those websites is at your own risk.


IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.

Licensees of this program who want to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact

IBM Director of LicensingIBM CorporationNorth Castle Drive, MD-NC119Armonk, NY 10504-1785US

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Programming License Agreement, or any equivalent agreementbetween us.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to actual people or business enterprises is entirelycoincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrate programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operatingplatform for which the sample programs are written. These examples have notbeen thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs. The sampleprograms are provided "AS IS", without warranty of any kind. IBM shall not beliable for any damages arising out of your use of the sample programs.

Trademarks

IBM, the IBM logo, and ibm.com are trademarks or registered trademarks ofInternational Business Machines Corp., registered in many jurisdictions worldwide.Other product and service names might be trademarks of IBM or other companies.A current list of IBM trademarks is available on the web at “Copyright andtrademark information” at www.ibm.com/legal/copytrade.shtml.


http://www.ibm.com/legal/us/en/copytrade.shtml

Terms and conditions for product documentation

Permissions for the use of these publications are granted subject to the followingterms and conditions.

ApplicabilityThese terms and conditions are in addition to any terms of use for the IBMwebsite.

Personal useYou may reproduce these publications for your personal, noncommercialuse provided that all proprietary notices are preserved. You may notdistribute, display or make derivative work of these publications, or anyportion thereof, without the express consent of IBM.

Commercial useYou may reproduce, distribute and display these publications solely withinyour enterprise provided that all proprietary notices are preserved. Youmay not make derivative works of these publications, or reproduce,distribute or display these publications or any portion thereof outside yourenterprise, without the express consent of IBM.

Rights Except as expressly granted in this permission, no other permissions,licenses or rights are granted, either express or implied, to the publicationsor any information, data, software or other intellectual property containedtherein.

IBM reserves the right to withdraw the permissions granted hereinwhenever, in its discretion, the use of the publications is detrimental to itsinterest or, as determined by IBM, the instructions are not being properlyfollowed.

You may not download, export or re-export this information except in fullcompliance with all applicable laws and regulations, including all UnitedStates export laws and regulations.

IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESEPUBLICATIONS. THE PUBLICATIONS ARE PROVIDED "AS-IS" ANDWITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED ORIMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIESOF MERCHANTABILITY, NON-INFRINGEMENT, AND FITNESS FOR APARTICULAR PURPOSE.

IBM online privacy statement

IBM Software products, including software as a service solutions, (“SoftwareOfferings”) may use cookies or other technologies to collect product usageinformation, to help improve the end user experience, to tailor interactions withthe end user or for other purposes. In many cases no personally identifiableinformation is collected by the Software Offerings. Some of our Software Offeringscan help enable you to collect personally identifiable information. If this SoftwareOffering uses cookies to collect personally identifiable information, specificinformation about this offering’s use of cookies is set forth below.

For more information about the use of various technologies, including cookies, forthese purposes, see IBM’s Privacy Policy at www.ibm.com/privacy and IBM’sOnline Privacy Statement at www.ibm.com/privacy/details the section entitledCookies, Web Beacons and Other Technologies and the IBM Software Products and

Notices 333

Software-as-a-Service Privacy Statement at www.ibm.com/software/info/product-privacy.


Glossary

This glossary defines the terms and abbreviations used in z/OS Connect EE and inthe knowledge centers.

# A B C D E F G H I J K L M N O P Q R S T U V W XY Z

#

${server.config.dir}See server.config.dir

A

AAR See API Archive.

Angel The Liberty angel process is a started task which you configure to allowz/OS Connect EE to use z/OS authorized services.

APAR See Authorized program analysis report.

API See application programming interface.

API ArchiveA file of type .aar containing an API project that can be deployed intoz/OS Connect EE

API ConsumerAn application that calls a RESTful API to access valuable content, data orresources.

API ProviderAn application that is exposed using a RESTful API.

application programming interface (API)A functional interface that allows an application program that is written ina high-level language to use specific data or functions of the operatingsystem or another program.

Authorized Program Analysis Report (APAR)A request for correction of a defect in a current release of an IBM-suppliedprogram.

TOP

B

bind fileSee WSBind

business logicThe part of a distributed application that is concerned with the applicationlogic rather than the user interface of the application. Compare withpresentation logic.

TOP


C

CA See certificate authority.

CCSIDCoded Character Set Identifier. A 16-bit number that includes a specific setof encoding scheme identifiers, character set identifiers, code pageidentifiers, and other information that uniquely identifies the codedgraphic-character representation.

certificate authority (CA)In computer security, an organization that issues certificates. The certificateauthority authenticates the certificate owner's identity and the services thatthe owner is authorized to use. It issues new certificates and revokescertificates from users who are no longer authorized to use them.

class In object-oriented programming, a model or template that can beinstantiated to create objects with a common definition and therefore,common properties, operations, and behavior. An object is an instance of aclass.

CLASSPATHIn the execution environment, an environment variable keyword thatspecifies the directories in which to look for class and resource files.

code pageAn assignment of hexadecimal identifiers (code points) to graphiccharacters. Within a given code page, a code point can have only onemeaning.

configuration fileA file that specifies the characteristics of a program, system device, serveror network.

connectionIn data communication, an association established between functional unitsfor conveying information.

In Open Systems Interconnection architecture, an association established bya given layer between two or more entities of the next higher layer for thepurpose of data transfer.

In TCP/IP, the path between two protocol application that providesreliable data stream delivery service.

In Internet, a connection extends from a TCP application on one system toa TCP application on another system.

TOP

D

DBCS See double-byte character set.

deprecatedPertaining to an entity, such as a programming element or feature, that issupported but no longer recommended, and that might become obsolete.

digital certificateAn electronic document used to identify an individual, server, company, orsome other entity, and to associate a public key with the entity. A digitalcertificate is issued by a certificate authority and is digitally signed by thatauthority.


digital signatureInformation that is encrypted with an entity's private key and is appendedto a message to assure the recipient of the authenticity and integrity of themessage. The digital signature proves that the message was signed by theentity that owns, or has access to, the private key or shared secretsymmetric key.

distributed applicationAn application for which the component application programs aredistributed between two or more interconnected processors.

distributed identityUser identity information that originates from a remote system. Thedistributed identity is created in one system and is passed to one or moreother systems over a network. See also distinguished name and realm name.

distributed processingThe processing of different parts of the same application in differentsystems, on one or more processors.

domainIn the Internet, a part of a naming hierarchy in which the domain nameconsists of a sequence of names (labels) separated by periods (dots).

domain nameIn TCP/IP, a name of a host system in a network.

domain name serverIn TCP/IP, a server program that supplies name-to-address translation bymapping domain names to IP addresses. Synonymous with name server.

dotted decimal notationThe syntactical representation for a 32-bit integer that consists of four 8-bitnumbers written in base 10 with periods (dots) separating them. It is usedto represent IP addresses.

double-byte character set (DBCS)A set of characters in which each character is represented by 2 bytes.Languages such as Japanese, Chinese and Korean, which contain moresymbols than can be represented by 256 code points, require double-bytecharacter sets. Because each character requires 2 bytes, the typing, display,and printing of DBCS characters requires hardware and programs thatsupport DBCS. Contrast with single-byte character set.

TOP

E

EBCDICSee extended binary-coded decimal interchange code.

encryptionThe process of transforming data into an unintelligible form in such a waythat the original data can be obtained only by using a decryption process.

Enterprise Information System (EIS)The applications that comprise an enterprise's existing system for handlingcompany-wide information. An enterprise information system offers awell-defined set of services that are exposed as local or remote interfaces orboth.

Glossary 337

environment variableA variable that specifies the operating environment for a process. Forexample, environment variables can describe the home directory, thecommand search path, the terminal in use, and the current time zone.

extended binary-coded decimal interchange code (EBCDIC)A coded character set of 256 8-bit characters developed for therepresentation of textual data.

TOP

F

firewallA configuration of software that prevents unauthorized traffic between atrusted network and an untrusted network.

TOP

H

host A computer that is connected to a network (such as the Internet or an SNAnetwork) and provides an access point to that network. The host can beany system; it does not have to be a mainframe.

host addressAn IP address that is used to identify a host on a network.

host IDIn TCP/IP, that part of the IP address that defines the host on the network.The length of the host ID depends on the type of network or network class(A, B, or C).

host nameIn the Internet suite of protocols, the name given to a computer.Sometimes, host name is used to mean the fully qualified domain name;other times, it is used to mean the most specific subname of a fullyqualified domain name. For example, if mycomputer.city.company.com isthe fully qualified domain name, either of the following can be consideredthe host name: mycomputer.city.company.com, mycomputer.

hover helpInformation that can be viewed by holding a mouse pointer over an itemsuch as an icon in the user interface.

Hypertext Transfer Protocol (HTTP)In the Internet suite of protocols, the protocol that is used to transfer anddisplay hypertext and XML documents.

Hypertext Transfer Protocol Secure (HTTPS)A TCP/IP protocol that is used by World Wide Web servers and Webbrowsers to transfer and display hypermedia documents securely acrossthe Internet.

TOP

I

<installation_path>This term is used in file paths to represent the directory where youinstalled the product.


InterceptorInterceptors are used to capture and manipulate a z/OS Connect EErequest so you can control z/OS Connect EE operations, service providercalls and APIs.

Internet Architecture BoardThe technical body that oversees the development of the internet suite ofprotocols known as TCP/IP.

Internet Protocol (IP)In TCP/IP, a protocol that routes data from its source to its destination inan Internet environment.

interoperabilityThe capability to communicate, run programs, or transfer data amongvarious functional units in a way that requires the user to have little or noknowledge of the unique characteristics of those units.

IP Internet Protocol.

IP addressA unique address for a device or logical unit on a network that uses the IPstandard.

TOP

J

Java An object-oriented programming language for portable interpretive codethat supports interaction among remote objects.

Java Development Kit (JDK)The name of the software development kit that Oracle provided for theJava platform.

Java Native Interface (JNI)A programming interface that allows Java code running in a Java virtualmachine to work with functions that are written in other programminglanguages.

Java Runtime Environment (JRE)A subset of the Java Software Development Kit (SDK) that supports theexecution, but not the development, of Java applications. The JREcomprises the Java Virtual Machine (JVM), the core classes, and supportingfiles.

Java Secure Socket Extension (JSSE)A Java package that enables secure Internet communications. It implementsa Java version of the Secure Sockets Layer (SSL) and Transport LayerSecurity (TSL) protocols and supports data encryption, serverauthentication, message integrity, and optionally client authentication.

Java virtual machine (JVM)A software implementation of a processor that runs compiled Java code(applets and applications).

JavaScript Object Notation (JSON)A lightweight data-interchange format that is based on the object-literalnotation of JavaScript. JSON is programming-language neutral but usesconventions from languages that include C, C++, C#, Java, JavaScript, Perl,Python.

Glossary 339

JDK See Java development kit.

JNI See Java Native Interface.

JRE See Java Runtime Environment.

JSON See JavaScript Object Notation (JSON).

JSON SchemaA JavaScript Object Notation (JSON) document that describes the structureand constrains the contents of other JSON documents.

JSON web serviceA web service that accepts and produces JSON payloads.

JSSE See Java Secure Socket Extension.

JVM See Java Virtual Machine.

TOP

K

KeystoreIn the JSSE protocol, a file that contains public keys, private keys, trustedroots, and certificates.

TOP

L

TOP

M

methodIn object-oriented programming, an operation that an object can perform.An object can have many methods.

TOP

N

name serverIn TCP/IP, synonym for Domain Name Server. In Internetcommunications, a host that translates symbolic names assigned tonetworks and hosts into IP addresses.

TOP

O

object In object-oriented programming, a concrete realization of a class thatconsists of data and the operations associated with that data.

object-oriented (OO)Describing a computer system or programming language that supportsobjects.

OO See object-oriented.


OSGi A specification that describes a modular system and a service platform forthe Java programming language that implements a complete and dynamiccomponent model.

TOP

P

PING In Internet communications, a program used in TCP/IP networks to testthe ability to reach destinations by sending the destinations an InternetControl Message Protocol (ICMP) echo request and waiting for a reply.

port An endpoint for communication between devices, generally referring to alogical connection. A 16-bit number identifying a particular TransmissionControl Protocol (TCP) or User Datagram Protocol (UDP) resource within agiven TCP/IP node.

port sharingA way of load balancing TCP/IP connections across a group of serversrunning in the same z/OS image.

presentation logicThe part of a distributed application that is concerned with the userinterface of the application. Compare with business logic.

TOP

Q

Query stringsQuery strings are used in the statistical data API. A query string is aninput parameter, specifying the statistical data to be retrieved.

TOP

R

RACF See Resource Access Control Facility.

Resource Access Control Facility (RACF)An IBM licensed program that provides access control by identifying usersto the system; verifying users of the system; authorizing access to protectedresources; logging detected unauthorized attempts to enter the system; andlogging detected accesses to protected resources.

resource group IDA resource group ID is a logical grouping of resources, grouped forstatistical purposes. A resource group ID is associated with a number ofresource group statistics, each identified by a statistic ID.

resource IDA resource ID refers to a specific resource. Information about the resourceis included in resource-specific statistics. Each statistic is identified by astatistic ID.

RESTfulPertaining to applications and services that conform to RepresentationalState Transfer (REST) constraints. REST is the pattern that is mostcommonly used for web requests today that run over the HTTP protocol.The REST protocol relies solely on the HTTP GET/PUT/POST/DELETEmethods.

Glossary 341

RESTful serviceAn implementation of a RESTful service must provide the following:v Explicit use of HTTPv Stateless functionalityv Displays directory structure like URIsv Support Transfer XML, JavaScript Object Notation (JSON), or both

IBM z/OS Connect EE provides a set of RESTful services that offerdiscovery and linkage from external cloud, mobile, and web environmentsto business assets on z/OS systems.

Result setA result set is a set of data calculated or recorded by a statistical APIfunction.

TOP

S

SAR See Service Archive.

SBCS See single-byte character set.

Secure Sockets Layer (SSL)A security protocol that provides communication privacy. SSL enablesclient/server applications to communicate in a way that is designed toprevent eavesdropping, tampering, and message forgery. SSL applies onlyto internet protocols, and is not applicable to SNA.

server.config.dirA Liberty property that identifies the server configuration directory. Thisrefers to the <WLP_USER_DIR>/servers/<serverName> directory.

serviceUsed by an API to implement a method, such as GET, PUT, POST orDELETE for a specific service provider. Information about the service iscontained in a service archive (SAR) file and includes information aboutthe request and response JSON schemas required by the service.

service archive (SAR)A file that contains the information needed by a z/OS Connect EE serviceprovider to install and provide the service and to enable the service as aJSON asset.

single-byte character set (SBCS)A character set in which each character is represented by 1 byte. Contrastwith double-byte character set.

SMF The z/OS System Management Facility (SMF) collects and records systemand job-related information that your z/OS installation can use forreporting, billing, analysis, profiling, and maintaining system security.CICS TG for z/OS writes statistical data to SMF.

socket A network communication concept, typically representing a point ofconnection between a client and a server. A TCP/IP socket will normallycombine a host name or IP address, and a port number.

SoE See Systems of Engagement.

SoR See Systems of Record.

SSL See Secure Sockets Layer.


subnetAn interconnected, but independent segment of a network that is identifiedby its Internet Protocol (IP) address.

subnet addressIn Internet communications, an extension to the basic IP addressing schemewhere a portion of the host address is interpreted as the local networkaddress.

Systems of EngagementDescribing a system which acts as a service requester. This term hasreplaced the term client when describing how different systems areclassified in the cloud environment. IBM z/OS Connect EE provides thetools that are needed to transform requests from SoE environments toapplications that are running on SoR servers on the z/OS operatingsystem.

Systems of RecordDescribing a system which acts as a service provider. This term hasreplaced the term server when describing how different systems areclassified in the cloud environment. IBM z/OS Connect EE provides thetools that are needed to transform requests from SoE environments toapplications that are running on SoR servers on the z/OS operatingsystem.

TOP

T

TCP/IPSee Transmission Control Protocol/Internet Protocol.

TCP/IP load balancingThe ability to distribute TCP/IP connections across target servers.

thread A stream of computer instructions that is in control of a process. In someoperating systems, a thread is the smallest unit of operation in a process.Several threads can run concurrently, performing different jobs.

timeoutA time interval that is allotted for an event to occur or complete beforeoperation is interrupted.

trace A record of the processing of a computer program. It exhibits thesequences in which the instructions were processed.

Transmission Control Protocol/Internet Protocol (TCP/IP)An industry-standard, nonproprietary set of communications protocols thatprovide reliable end-to-end connections between applications overinterconnected networks of different types.

TOP

U

Uniform Resource Locator (URL)A sequence of characters that represent information resources on acomputer or in a network such as the Internet. This sequence of charactersincludes (a) the abbreviated name of the protocol used to access theinformation resource and (b) the information used by the protocol to locatethe information resource.

Glossary 343

URL See Uniform Resource Locator.

user registryThe location where the distinguished name of a user is defined andauthenticated. See also distinguished name.

TOP

V

version stringA character string containing version information about the statistical dataAPI.

TOP

W

Web browserA software program that sends requests to a Web server and displays theinformation that the server returns.

Web serverA software program that responds to information requests generated byWeb browsers.

Websphere Optimized Local Adapter (WOLA)WOLA is used to allow z/OS Connect EE requests to interact with z/OSassets.

WLP_USER_DIRThis environment variable can be used to specify an alternative location for${wlp.user.dir}. This variable must be an absolute path. If this variable isspecified, the runtime environment looks for shared resources and serverdefinitions in the specified directory. The ${server.config.dir} isequivalent to ${wlp.user.dir}/servers/serverName. If this environmentvariable is not specified, ${wlp.user.dir} is set to ${wlp.install.dir}/usr.

WSBind fileA Web service bind file is a resource that describes the specifics of the Webservice.

TOP


Index

AAbend codes 271ACL 140

IMS service provider 130add API 97add endpoint 100administering 233Administration 173Advantages and benefits 1, 236angel process 140API 156, 159, 160, 233, 236, 237, 238,

240, 241, 242API archive (AAR) 201, 229API editor

preferences 216usage tips 213

API Editormodeling 220service import 225

API interceptor 156API management 173API package

creating 219, 220Customizing 221definition 201deploying 223, 234editing 225editor 210examining 226exporting 225overview 210removing 226starting 226stopping 226testing 226undeploying 235workflow 4

apideploy 328auditing 155Auditing 153authentication 140, 142

IMS service provider 130authorization 140, 142

IMS service provider 130automation 190

Bbasic registry 182bind 158bind files 158build toolkit 5, 114, 199, 200

Ccatalog manager 18, 19, 88charge-back

IMS service provider 130client 245client certificates 217

client service 145concepts 3configuration 93, 170, 171configure CICS 18, 88configure WOLA 19, 88configuring 180, 182, 183

IMS Mobile feature 133IMS service provider 133

Configuring 119connection profiles 143considerations

IMS service provider 49, 67contacting IBM Software Support 268Conversion 250CORS 161

CORS 227CORS preflight check 161create 119create api 22, 32, 42create server 119creating service 263Creating service provider 263

Ddata conversion

IMS service provider 52data transformation 250data transformer 263, 265deploying 233deploying API 159, 160development 245

Ffirst server 91

GGET 236, 237, 238, 240, 241, 242glossary of terms and abbreviations 335GMOBA messages 271GMOCR messages 273GMOIG messages 274GMOMW messages 276GMOPR messages 278GMOSR messages 279GMOTM messages 280

HHA 85, 89, 91, 92, 93, 94, 96, 167, 168,

169, 170, 171, 173HA scenario 97, 100

IMS service provider 103WOLA service provider 87

high availabiility 170high availability 85, 91, 92, 93, 94, 96,

167, 168, 169, 171, 173

HTTP mapping 213, 221

Iimplementation workflow

IMS Mobile solution 54, 67IMS administrative services 139IMS in-memory cache 139IMS Mobile feature

API 66configuration 133connection endpoints 137connection profiles 137IMS communication verification 135IMS gateway server 48interaction profiles 137interaction properties 137migration cleanup 137overview 48, 130prioritized connection endpoints 137service definition 137service metadata 137upgrading 136

IMS Mobile solutionimplementation workflow 54, 67

IMS service cache 48, 130clearing 268dumping to log 268examining 268

IMS service providerAPI 66configuration 133connection endpoints 137connection profiles 137considerations 49, 67IMS communication verification 135IMS gateway server 48in-memory cache 268interaction profiles 137interaction properties 137migration cleanup 137overview 48, 130prerequisites 67prioritized connection endpoints 137restrictions 49, 130service definition 137service metadata 137upgrading 136

IMS service registrydefinition 139

IMS service registry cacheaccessing 139dumping to log 139refreshing 139

IMS technical ID 140IMS technical password 140installation 114

API editor 115installing 111, 112interceptor 150, 156, 263


JJSON schema

IMS service provider 50JSON schema mapping

IMS service provider 52

Llog records

IMS service provider 130logger 150

Mmanagement 173mapping editor 213messages

IMS service provider 271Messages 271Migrating 116

Nnew features 7Null type 215

Ooperating 189operation 173Overview 1, 7, 236

Pport sharing 92, 168preferences 216Prerequisites 18, 87, 103Problem analysis 267problem determination 268

trace 267Product extensions 113Product overview 1, 236

RRACF 142RACF groupname 140RACF setting

IMS service provider 130request messages

IMS service provider 50Resolving problems 267response messages

IMS service provider 50REST 145REST APIs

building 201design 201design workflow 4requirements 4

RESTful servicesdesign 201overview 201

restrictionsIMS service provider 49, 67

SSAF 140, 142SAF registry 183SAR 193, 197, 219, 238

IMS service provider 195scenario 17, 18, 19, 20, 22, 29, 32, 39, 42,

88, 89, 93, 94, 96, 124, 127, 185scenario 1 18, 19, 88Scenarios 17schema 158schema files 158second server 94security 177, 233

configuration 140, 142IMS process flow 130technical password 142

Security 180, 182, 183server connection 216, 217service 263service archive 219, 238Service archive 193, 197

IMS service provider 195service archive (SAR) 201, 229service provider 85service registry

IMS Mobile feature 48, 130services 121, 122

deployingIMS services 144

promotingIMS services 144

Setup 113shared configuration 93shared resources 93SMP/E 112SMPE 112starting 189status 241stopping 189supported hardware 111supported software 111Swagger 229sysplex distributor 169

TTCP/IP 92, 168tcpip 92TCPIP 168technical ID 142technical password 142test 32, 42testing 96tracking 155Tracking 153transformation 250transformer 265troubleshooting

IMS service provider 271Troubleshooting 267

Uundeploy 235updating 115, 116updating API editor 116upgrading 115

IMS Mobile feature 136IMS service provider 136

user authentication 143

Vversion 1 116

WWebSphere optimized local

adapters 124, 127whats new 7wlm 167, 169WOLA 85, 124, 127workload 167

Zzconbt 329zconsetup 330zosconnect 329


z/O S C o nn e ct E n t e rp r i s e E di ti o n IBM€¦ · z/O S C o nn e ct E n t e rp r i s e E...

Documents

Transcript of z/O S C o nn e ct E n t e rp r i s e E di ti o n IBM€¦ · z/O S C o nn e ct E n t e rp r i s e E...