IBM. z/os Connect Enterprise Edition. z/os Connect Enterprise Edition. Version 2 Release 0

Transcription

1 z/os Connect Enterprise Edition IBM z/os Connect Enterprise Edition Version 2 Release 0

2

3 z/os Connect Enterprise Edition IBM z/os Connect Enterprise Edition Version 2 Release 0

4 Note Before 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 and modifications until otherwise indicated in new editions. Copyright IBM Corporation 2015, US Goernment Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents Chapter 1. What is IBM z/os Connect Enterprise Edition? z/os Connect EE concepts API design and workflow The z/os Connect EE Build Toolkit Chapter 2. z/os Connect EE change history Chapter 3. Sources of information Chapter 4. Scenarios Deelop an API to inoke a CICS serice ia WOLA 17 Prerequisites Configuring the CICS Catalog Manager example application Configuring CICS to use WOLA Generate a serice archie from a CICS COBOL copybook Create an API using z/os Connect EE API Editor Configuring the z/os Connect EE serer to use WOLA Deploying an API to the z/os Connect EE serer 31 Test the scenario Deelop an API to inoke a CICS serice using the CICS serice proider Prerequisites Configuring the CICS Catalog Manager example application Generate a serice archie from a CICS COBOL copybook Deploying an API to the z/os Connect EE serer 42 Test the scenario Create an IMS mobile serice Prerequisites Restrictions Request and response messages for IMS mobile serices High-leel language and JSON schema mapping 51 IMS serice creation workflow Tutorial: Create an IMS mobile serice Deelop an API to inoke an IMS serice Prerequisites API creation workflow for IMS mobile serices 67 Tutorial: Create a REST API for an IMS mobile serice Configure an HA enironment that uses the WOLA serice proider Prerequisites Setting up HA for the first serer Adding a second serer Testing the scenario Further capabilities of the HA scenario Configure an HA enironment that uses the IMS serice proider Prerequisites Setting up HA for the first serer Adding a second serer Testing the scenario Chapter 5. Installation information Requirements Installing z/os Connect EE Creating the z/os Connect EE shared directory 112 Setting up the product extensions directory Installing the z/os Connect EE Build Toolkit Updating z/os Connect EE Installing z/os Explorer and the z/os Connect EE API Editor Updating z/os Explorer and the z/os Connect EE API Editor Migrating from z/os Connect V Chapter 6. Configuring Creating a z/os Connect Enterprise Edition Serer 119 Configuring serices Using the WOLA serice proider Configuring CICS to use WebSphere optimized local adapters (WOLA) Registering CICS with the WebSphere optimized local adapter (WOLA) Using the IMS serice proider Operational requirements IMS serice security process flow Configuring for the IMS serice proider Verifying serer communication with IMS Upgrading from the IMS Mobile Feature Pack in IMS Enterprise Suite IMS mobile serice definition IMS mobile serice registry, in-memory cache, and administratie serices Security configuration for the IMS mobile solution Deploying an IMS serice to a different target serer Using other serice proiders Configuring the z/os Connect EE REST client serice Configuring interceptors Configuring the file system logger interceptor 150 Auditing and tracking Configuring API specific interceptors Configuring Data Transformers Creating bind and schema files Configuring SARs Configuring APIs Configuring Cross-Origin Resource Sharing on a z/os Connect Enterprise Edition Serer Copyright IBM Corp. 2015, 2017 iii

6 Serer configuration updates on demand Using an MBean to trigger updates Inoking the FileNotificationMBean from a jaa program Inoking FileNotificationMBean from the REST API The FileTransferMBean Chapter 7. High aailability Workload distribution TCP/IP port sharing Sysplex distributor Workload distribution between z/os Connect EE serers and serice proider SORs WLM Classification Sharing serer configuration Splitting serer configuration information Serer-specific configuration elements Location of shared configuration files Maintenance of API and serice deployments Administration and Operation Tasks in an HA enironment Stopping and starting z/os Connect EE serers in an HA enironment Management of z/os Connect EE APIs and serices in an HA enironment Chapter 8. Securing Oeriew of z/os Connect EE security Configuring security for z/os Connect EE Configuring security with a basic user registry 181 Configuring security with SAF registries Configuring the Liberty angel process and z/os authorized serices Chapter 9. Operating Starting and stopping z/os Connect EE System Automation Chapter 10. Building a Serice Archie (SAR) by using the Build Toolkit Building a SAR for the REST client Building a SAR for the IMS serice proider Building a SAR for the WOLA serice proider 196 Building a SAR from the command line Building a SAR with the z/os Connect EE Build Toolkit SDK Chapter 11. Designing and building APIs in the API Editor RESTful web serices and API design Designing RESTful APIs z/os Connect EE API Editor for defining your APIs Tips for using the API Editor for HTTP-to-JSON mapping Handling the null type in JSON schema Setting preferences for the API Editor Connecting to a z/os Connect EE serer Configuring client certificates for serer connections Creating a REST API Generating a serice archie Creating an API project Modeling an API with the API Editor Defining HTTP-to-JSON mapping Deploying an API in the API Editor Editing an existing API Re-importing changed serices Generating an API archie Examining, testing, starting and stopping an API 226 Installing and trusting a self-signed certificate for Swagger UI Deeloping applications with Swagger documents 229 Documenting your API using Swagger Chapter 12. Administering SARs Automated SAR management Oerriding SAR properties Chapter 13. Administering APIs Automated API management Using the API Deployment utility Deploying an API Undeploying an API Using the RESTful administration interface GET a list of APIs GET details of an API GET a Serice Archie (SAR) Deploying an API Update an API Change the status of an API Delete an API Chapter 14. Client application deelopment The z/os Connect EE administration interface Conersion for z/os Connect Enterprise Edition data transformation Interacting with COBOL and TSO/ISPF Error responses Chapter 15. Extending z/os Connect EE Creating a z/os Connect EE serice proider Creating a z/os Connect EE serice at run time 263 Creating a z/os Connect EE interceptor Creating a z/os Connect EE data transformer Using the DataxFormExt interface Chapter 16. Resoling problems Enabling z/os Connect EE serer trace Clearing or examining the IMS serice in-memory cache Contacting IBM Software Support i z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

7 Chapter 17. Messages IMS serice proider (IMS Mobile feature) messages GMOBA messages GMOCR messages GMOIG messages GMOMW messages GMOPR messages GMOSR messages GMOTM messages Chapter 18. Reference Configuration elements Command reference apideploy command syntax zconbt command syntax zosconnect command syntax zconsetup command syntax Notices Glossary Index Contents

8 i z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

9 Chapter 1. What is IBM z/os Connect Enterprise Edition? IBM z/os Connect Enterprise Edition proides a framework that enables z/os based programs and data to participate fully in the new API economy for mobile and cloud applications. IBM z/os Connect Enterprise Edition V2.0 proides access to z/os subsystems, such as CICS, IMS, WebSphere MQ, DB2, and Batch, that use RESTful APIs with JSON formatted messages. The framework proides concurrent access, through a common interface, to multiple z/os subsystems. z/os Connect EE can help to delier benefits for an enterprise in two ways. It proides an intuitie workstation-based tool, the z/os Connect EE API Editor, that enables a deeloper, with or without z/os skills, to create RESTful APIs from traditional z/os based assets. The core business assets that run on z/os can easily be adapted to the latest mobile and cloud communication techniques and message protocol formats. Mobile and cloud application deelopers, inside or outside the enterprise, can incorporate z/os data and transactions into their applications without the need to understand z/os subsystems. The z/os resources appear as any other RESTful API. Cloud and mobile applications reshape the way enterprises and systems interact. RESTful APIs that use JSON message formats are the predominant standards for new application deelopment. z/os subsystems participate in these new application deelopment standards so that application deelopers can use z/os based serices and data for deelopment of new applications. The following diagram shows how z/os Connect EE connects mobile and cloud applications with z/os assets: z/os LPAR Application user z/os Connect EE z/os Address Space API Serice Serice Proider 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,

10 Benefits of using z/os Connect EE Using z/os Connect EE has the following benefits: Proides a standard framework to support serice proiders that you can write yourself, or can be supplied with the System of Record (SoR). The serice proider forwards requests to the SoR. Proides a unified, extensible approach for discoery and inocation of RESTful APIs and serices for z/os based business assets, opening up these assets to cloud and mobile-based Systems of Engagement (SoE) enironments. Proides functions that are based on Liberty serer technology. It is lightweight and easily configurable, proides z/os differentiation with System Authorization Facility (SAF) security, and z/os Workload Manager (WLM) integration. WLM integration means different URIs can hae arying leels of priority and performance criteria. Note: Do not attempt to run your own applications in the same Liberty serer where z/os Connect EE is running. Such usage is not supported. Proides security for indiidual or groups of z/os Connect EE APIs and serices with SAF security. Only specified users or groups hae access to specified serices. Can uniformly track requests from cloud, mobile, and web enironments by using z/os System Management Facility (SMF) serices. This tracking means that z/os customers can use their existing processes for auditing and chargeback for requests from these enironments. Can automatically conert the request payload from JSON form on input to binary form. The binary form is consumable by z/os applications such as COBOL, PL/I, and C. For the response from the z/os application, the output can be conerted 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 RESTful API. These RESTful API definitions, which are created by the supplied z/os Connect EE API Editor, include Swagger 2.0 standard descriptions. The descriptions instruct other application deelopers how to use the API. z/os assets appear to mobile and cloud deelopers as any other system that proides RESTful API serices. An enterprise API catalog can be populated with z/os Connect EE-hosted APIs alongside any other proider and can be used in the same way. This API package deployment can be done manually or it can be automated by extending an existing enterprise change control process. The associated deployment capabilities proide an enterprise with the ability to meet the demands of the fast-paced API economy. z/os Connect EE includes a significant new mapping capability that is used before the transformation from JSON messages to the required format of the z/os subsystems. This mapping capability adds a powerful abstraction layer between the API consumer and the underlying z/os assets and allows inline manipulation of requests, such as the mapping of HTTP headers, pass-through, redaction, or defaulting of JSON fields. The API mapping functions improe the productiity of the z/os deeloper in the creation of RESTful APIs. 2 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

11 z/os Connect EE concepts Understand the terms used in z/os Connect EE before you get started with z/os Connect EE. Serice proiders A z/os Connect EE serice proider forwards requests to a System of Record (SoR). You can write your own serice proider or you can use one that is supplied with the SoR to plug into the framework. Both WOLA and IMS serice proiders are included with z/os Connect EE. Serice proiders must implement the com.ibm.zosconnect.spi.serice SPI. The WOLA serice proider can be used by both CICS and Batch. Interceptors z/os Connect EE interceptors proide you with the ability to execute some logic around a request so you can control operations, serice proider calls, and APIs. Interceptors are written and deliered by any component to plug into the framework. The framework allows for any number of qualities of serice to be injected around the inocation of a serice. For more information on using the interceptors see Configuring interceptors on page 148. z/os Connect EE proides three interceptors: 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 as start, stop, and inoke. For instructions on using the audit interceptor see Auditing and tracking on page 153. An authorization interceptor that allows users belonging to certain groups (administration, operator, inoke) to perform certain requests. The interceptor proides z/os, SAF and LDAP authorization checks for operations such as start, stop, and inoke. For instructions on using the authorization interceptor see Configuring security for z/os Connect EE on page 180. A file system logger interceptor, which enables users to log request information in a system file. For instructions on using the file system logger interceptor see Configuring the file system logger interceptor on page 150. Data transformation proiders z/os Connect EE proides the ability to optionally transform request and response payloads that are used for calling a business asset on operating systems.. Data transformers are written and deliered by any component to plug into the framework. A data transformer is included with z/os Connect EE: com.ibm.zosconnect.xform.serice. It proides JSON to and from byte arrays that are 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 proides the ability to optionally do a conersion of the request 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

12 Payload transformers can be created to satisfy specific needs by implementing the required DataXform SPI proided by z/os Connect EE. Payload conersion is enabled by adding a reference in the configuration to a data transformation implementation. z/os Connect EE proides an implementation that requires that the request and response message format be JSON. It supports the conersion of the request to a byte array, which can be mapped by a COBOL, PLI, or C structure. The target program's structure, or copybook (description of its parameters in/out) is used to generate a binding file and JSON schema files by using a utility that is proided with z/os Connect EE. The bind file that is generated by this utility is used by z/os Connect EE to do the data conersion between JSON and natie data formats as requests arrie and responses are returned. The JSON schemas for the request and response message can be retrieed with a proided REST API call. Process types on z/os For the Liberty runtime enironment on the z/os platform, there are two types of process: the serer process and the angel process. Note: API design and workflow There can only be a single instance of the angel process running on an LPAR. If you hae multiple products installed which require the angel process, then to ensure you hae the latest function, you must run the angel process with the highest leel of Liberty profile code that is shipped with any of those products. For more information, see Process types on z/os in the WebSphere Application Serer documentation. Before you plan to create your APIs for a serice, consider some design issues and requirements to ensure a smooth workflow. Examine the following general workflow and gather the requirements for resources that need to be exposed. 1. Generate a serice archie. Depending on the z/os subsystem, use the related tool to generate the serice archie. For example, for IMS, use IMS Enterprise Suite Explorer for Deelopment. For CICS access through the WebSphere Optimized Local Adapters (WOLA), use the BAQLS2JS and BAQJS2LS utilities. Determine the resources that need to be exposed in the API. Expose all fields 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 an oeriew of the API Editor, see the Using the API editor in IBM z/os Connect EE article on deeloperworks. A Swagger document is generated, along with the HTTP-to-JSON mapping and other API- and serice-related information. If necessary, edit the generated Swagger document in the editor. Do so before you export your API project into an API archie. 3. Deploy the API to a connected serer. You can deploy the API directly from within the editor by right-clicking the API project and selecting the corresponding menu item. 4 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

13 You can also deploy the API by using the apideploy -deploy command. With this approach, you export the API project as an API archie (AAR) file. 4. As a software source code management best practice, sae a copy of the API project 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 Toolkit The Build Toolkit is used by third-party endors, serice proiders, and users to generate SAR files that are needed to enable APIs to connect to back end applications. The Build Toolkit is supplied in a compressed file called zconbt.zip that you can download from the product installation directory. When you install a z/os Connect EE serer instance, you automatically hae access to the zconbt.zip file. The compressed file contains both the command line interface (CLI) and Software Deelopment Kit (SDK) ersions of zconbt. A readme file that contains instructions on how to use zconbt is included in the package. File structure of zconbt.zip The following directories are contained in the compressed file: bin lib Contains utility files that are used by zconbt. Contains the Jaa classes. plugins Includes REST, and IMS as standard and extensible to third-parties. doc Contains the Jaadoc files. Running the Build Toolkit The following example illustrates the syntax of the zconbt command as written on the command line: zconbt -p <properties filename> -f <output filename> In this example, <properties filename> is the name of the properties file that contains the configuration of the serice. <output filename> is the path and file name of the archie file that is created and must hae a file type of.sar. When you run this command, a return message indicates if the archie file was built successfully. Related concepts: Chapter 10, Building a Serice Archie (SAR) by using the Build Toolkit, on page 193 You can use either the command line interface or the SDK to build your SAR file for the REST client and for IMS serices. Related tasks: Installing the z/os Connect EE Build Toolkit on page 114 Install the z/os Connect EE Build Toolkit to create Serice archie (SAR) files. Chapter 1. What is IBM z/os Connect Enterprise Edition? 5

14 6 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

15 Chapter 2. z/os Connect EE change history Table 1. Enhancements and fixes Maintenance leel October 2017 V APAR PI86221 August 2017 API Editor V July 2017 Use this information to discoer the enhancements in each refresh of IBM z/os Connect Enterprise Edition. Enhancements and fixes Enhancements The ersion of Liberty that is embedded in z/os Connect EE is upgraded to V Fixes The mapping function was unable to distinguish between identically-named JSON objects that hae different full paths (that is, different parent objects), and incorrectly rendered the same contents in the mapping editor. This issue is addressed. Copyright IBM Corp. 2015,

16 Table 1. Enhancements and fixes (continued) Maintenance leel Serer code update V APARs: PI72646 PI73237 PI81092 PI81379 PI82085 PI82792 April 2017 Enhancements and fixes Enhancements When no user ID is specified in the IMS connection profile, the IMS serice proider would extract the user ID from the request subject for authentication with IMS Connect. Preiously, the user ID cannot be more than 8 bytes. This restriction is now lifted, allowing a user ID longer than 8 bytes to be passed to IMS Connect, proided that the user ID is properly mapped to a RACF ID. For more information about how the user ID is determined, see Authentication by IMS Connect on page 143. More informatie status codes are proided to allow client applications to distinguish serer errors from errors caused by bad input data, and take the appropriate actions. This feature is controlled by a new option usegenericerror which is set to true by default to presere the current behaior. For more information, see zosconnect_localadaptersconnectserice on page 302 in the Reference section. Fixes The GMOBA0110E message, The transaction could not be executed, could be misleading. For CM0 (commit-then-send) transactions, the transaction is already executed before the timeout occurs. The message is changed to "A problem occurred during transaction processing, " followed by additional error details, for arious possible error scenarios. For more information, see GMOBA0110E on page 272. The client ID that the IMS serice proider generates for requests from z/os Connect EE no longer has a GMP prefix, but a generic HWS prefix for all IMS Connect messages. The GMP prefix is needed to help distinguish z/os Connect EE requests coming into IMS Connect from other sources. The GMP prefix is now added back to the client ID. Timeout alues set in IMS Explorer for Deelopment did not appear to be reflected correctly in the IMS serice proider during run time. The "Transaction execution timeout" label in IMS Explorer for Deelopment V is changed to "IMS Connect socket timeout" to more clearly indicate that the alue is used to determine the time the socket should remain open to wait for a reply from IMS Connect. The label now is consistent with the IMS serice proider runtime behaior. Inoking an IMS serice generates a null pointer exception when the credential passed in is not alid. This issue is addressed. In addition, when security is disabled, you no longer hae to pass in a credential. Stopping an IMS serice resulted in an IMSGatewayException error, stating that "the creation or change to the <sericename> configuration element SERVICE was not processed by the serer." This issue is addressed. The limitation on the API GET request is remoed. A alue longer than 10 digits can now be used. Code has been changed to correct an ERROR 400 BAQR7018E THE HTTP REQUEST IS MISSING PARAMETER when using a mixed case HTTP header name and alue. Using a alue longer than 10 digits on an API GET request caused error message BAQR7019E to be returned. This restriction is remoed. 8 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

17 Table 1. Enhancements and fixes (continued) Maintenance leel Serer code update V (APAR PI77278) Serer code update V (APAR PI79272) API Editor V March 2017 API Editor V February 2017 Enhancements and fixes Enhancements Serices for the REST Client serice proider can now be deployed to a z/os Connect EE serer by copying the serice archie file (SAR) to a drop-in folder in the same way as you deploy AAR files. z/os Connect EE dynamically reacts to changes made to SAR files in the serices directory. SAR files can be copied to the location directory specified on the zosconnect_serices element of the serer.xml configuration 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 serice proider are suitable for SAR deployment. You can now iew the z/os Connect EE documentation in PDF format. You can also download a copy of the PDF directly from this IBM Knowledge Center for use within your organization. If you choose to download, check the online documentation regularly to ensure that you always hae the latest PDF. See. Fixes After installing or upgrading to 2.0.8, IMS users can create connection profiles in IMS Explorer but cannot retriee or edit them. Serices cannot be inoked and a null pointer exception is thrown at run time. This issue is addressed. When tracing is turned on for internal debugging, the IMS serice proider log trace contains duplicate entries resulting in a performance degradation. This issue is addressed. Enhancements The ersion of Liberty that is embedded in z/os Connect EE is upgraded to V z/os Connect EE supports the optional screening of application data alues that are inconsistent with the language structure. Instead of returning an error to the application, the inalid alue is replaced by a default alue suitable for that field. This enhancement is controlled by the DATA-SCREENING parameter of the BAQLS2JS, and BAQJS2LS utilities. For more information, see Conersion for z/os Connect Enterprise Edition data transformation on page 250. Enhancements The Swagger UI in the API editor is updated to V This updated ersion proides JSON field alidation in a web form. When testing the API, instead of modifying the alues enclosed in double quotes in XML format, you can now enter the alue for each input field in a web form. The alue is alidated based on the defined data type, length (for strings), or allowed alues. Description of the field, if defined, is also shown in the web form. 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 serer for serer access authentication. The client certificate is specified in the Eclipse preferences, in the Keystore details section under Explorer > Certificate management. With client authentication, the separate user ID that is added for a host connection can be used for authorization based on the defined security role. For more information, see Configuring client certificates for serer connections on page 217. Fixes When path segments, path parameters, or operation IDs are modified in the API Editor, in some cases, the underlying HTTP methods would reert to the base request JSON schema of the assigned serice in the generated Swagger document despite the presence of existing mappings. This issue is addressed. Chapter 2. z/os Connect Enterprise Edition change history 9

18 Table 1. Enhancements and fixes (continued) Maintenance leel API Editor V January 2017 API Editor V December 2016 Serer code update V (APAR PI73978) Serer code update V (APAR PI72673) API Editor V October 2016 Enhancements and fixes Fixes The API editor is updated to detect inalid characters in the serice name when a serice is imported, and to ensure characters that are alid in a URI are supported. Valid characters for serice names are alphanumeric characters (A-Z, a-z, and 0-9) and the following special characters: -._~:/?#[]@!$& ()*+,;= Enhancements You can now add detailed documentation in the mapping editor for serice fields that are not inoled in any data mapping actions. Preiously, to add any documentation to a field, the field must be inoled in a moe, assign, or remoe transform. You can now choose Add Task transform, and then add any description or documentation as needed. Fixes This release addresses the issue where, after the mapping editor is reopened, saed mapping information is lost for a Moe transform that was added by dragging from the target (on the right) to the source (on the left). Fixes User customizations in the ims-serices.xml file, such as specification of user authority roles, are now presered after an IMS serice definition is updated by using the IMS Explorer for Deelopment. The IMS serice proider GMOIG7777I initialization message upon serer startup is modified. The old name IMS Mobile feature in the message text is changed to IMS serice proider, followed by the build number. z/os Connect EE supports the optional optimization of payload sizes by aoiding the return of empty tags in the JSON response payload, when the COBOL field is NULL, ZERO, character SPACES or a mix of these alues. This enhancement is enabled by setting the MAPPING-LEVEL=4.1, TRUNCATE-NULL-ARRAYS and TRUNCATE-NULL-ARRAY-VALUES parameters of the BAQLS2JS utility. For more information, see Conersion for z/os Connect Enterprise Edition data transformation on page 250. Enhancements The ersion of Liberty that is embedded in z/os Connect EE is upgraded to V A new topic in the Operating section of the documentation explains how to use system automation tools with z/os Connect EE. Fixes Preiously, if a serice that was not inoled in any mapping was changed and re-imported into the API project, it was not included in the impact analysis. The analysis compared only serices that hae explicit mappings to an HTTP header, path parameter, or query parameter. The impact analysis now includes these serices and reports new and remoed fields. The generated Swagger document for the GET method no longer includes the HTTP body if all serice fields are mapped. 10 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

19 Table 1. Enhancements and fixes (continued) Maintenance leel Serer code update V (APAR PI70432) Serer code update V (APAR PI69668) API Editor V2.0.4 September 2016 API Editor V API Editor V Enhancements and fixes Enhancements The IMS Mobile feature is now included in z/os Connect EE as the IMS serice proider. The IMS Mobile feature was preiously a component in the IMS Enterprise Suite as the IMS Mobile Feature Pack for z/os Connect EE. Two new scenarios are proided to demonstrate how to create an IMS serice (also known as an IMS mobile serice) and how to deelop an API to inoke an IMS serice. A new scenario is proided to demonstrate how to use z/os Connect EE in a High Aailability enironment for RESTful access to IMS transactions through the IMS serice proider. Enhancements A new chapter describes how you can use z/os Connect EE in a High Aailability enironment. The chapter explains the concepts and components of HA and the adantages and disadantages. Drop-ins support is now proided for APIs. This allows z/os Connect EE to dynamically react to changes to AAR files in the apis directory. AAR files can be dropped into the location directory specified on the zosconnect_zosconnectapis element. The updatetrigger attribute of this element should be set to polled or mbean. For more information, see Configuring APIs on page 160. UTF-8 encoding is now supported in JSON payloads for APIs. A more detailed description of MBeans shows how they can be used to update serer configurations on demand. An extension of the HA scenario is proided to demonstrate how to deploy an API and how to add a second httpendpoint in a High Aailability enironment. You can now build Serice Archie (SAR) files for the REST client using either the command line interface or the SDK in the Build Toolkit. The description of the zosconnect_localadaptersconnectserice element has been enhanced to explain the attributes applicable to using COMMAREA and channel payloads on the WOLA serice. Enhancements If a serice 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 into errors, warnings, and other issues. If you choose to continue with the import, broken mappings are highlighted in the mapping editor. For more information, see Re-importing changed serices on page 225. Enhancements In an Assign transform, the assigned alue is now alidated against the constraints of the target field, such as the data type, the minimum or maximum length for strings, or the minimum and maximum alue for numeric fields. Fixes For compatibility with the Swagger Editor, minimum and maximum constraints for numeric fields in generated Swagger documents no longer use the scientific E notation. Enhancements When a serice (SAR) is re-imported into an API project, existing mappings are no longer cleared. The API editor now preseres existing mappings by updating all the mapping files that reference the serice. If a field that a transform action refers to is no longer in the serice interface, the broken mapping is highlighted in the mapping editor. Chapter 2. z/os Connect Enterprise Edition change history 11

20 Table 1. Enhancements and fixes (continued) Maintenance leel August 2016 Serer code update V (APAR PI66869) July 2016 Serer code update V (APAR PI64587) API Editor V Enhancements and fixes Enhancements The ersion of Liberty that is embedded in z/os Connect EE is upgraded to V z/os Connect EE is enhanced so that you can set the WLP_USER_DIR enironment ariable to define the location of your serer instances and user features. Enhancements A new attribute, usejsonerrorresponses is proided for the zosconnectmanager configuration element. When set, all error responses are returned in JSON format. For more information, see zosconnect_zosconnectmanager on page 316 in the Reference section. You can now authenticate users when they test your APIs in the API Editor or in a web-based application. Enhancements A Deploy API to z/os Connect EE Serer button is added to facilitate deployment of the API directly from the API package editor: June 2016 Serer code update V (APAR PI62820) Usability of relatie path specification is enhanced: Path alidation occurs only when the user attempts to sae, the path text field loses focus, or there are outstanding errors in the editor. The editor no longer alidates and displays errors as the user starts typing. A closing curly bracket ("}") is automatically inserted when the user types an opening curly bracket ("{"). Path and query parameters now inherit the minimum, maximum, minlength, maxlength, exclusieminimum, and exclusiemaximum properties of the serice field to which they are mapped. Enhancements Deploy an API project using the RESTful administration interface or the API Deployment utility. Browse, start, stop, and remoe deployed APIs on connected z/os Connect EE serers using the RESTful administration interface. Examine and test the operations of an API in Swagger UI. The DataxForm SPI is extended with a new interface DataxFormExt. This SPI has a getencoding() method, which can be used to obtain encoding information when using data transformation. UTF-8 encoding is now supported in JSON payloads for Serices. A new role, Reader can be assigned, allowing the user to read the Swagger document, access and import APIs, read a list of all APIs and serices, and get detailed information. 12 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

21 Table 1. Enhancements and fixes (continued) Maintenance leel API Editor V Enhancements and fixes Enhancements The following new features in this release require z/os Connect EE serer V (APAR PI62820) or later. Connect to z/os Connect EE serers in the Host Connections iew. Deploy an API project directly from the editor in the Project Explorer iew. Browse, start, stop, and remoe deployed APIs on connected serers directly in the editor in the z/os Connect EE Serers iew. Examine and test the operations of an API in Swagger UI that is included in the API editor. Important: Before using the "Try it out!" button in Swagger UI, take the following action: April 2016 Serer code update V (APAR PI63420) If your z/os Connect EE serer connection is secure (SSL/TLS), install and trust the serer's certificate by using Certificate Manager (Start > Run and select certmgr.msc) in Windows, or by using Keychain Access in MacOS. Enhancements The authentication process is enhanced to always use the authenticated user on the request subject. Added new attribute definition that is called preserejsonobjectpayloadorder, which can be set under the zosconnectmanager element and applies to all configured serices. When set, z/os Connect EE preseres the order of JSON objects that are contained in the payloads. Added support to WebSphere Optimized local adapters for use with CICS Transaction Serer V5.3. Properties files can now be read from product extensions on z/os. Added function to reestablish the link between the CICS link serer and the Liberty serer instance, when the Liberty serer is restarted. The ersion of Liberty that is embedded in z/os Connect EE is upgraded to V Fixes Modify WOLA connection close processing to ensure completion when Liberty serer is canceled. Naming conentions for the BBO transaction TS Queue name creation to aoid conflict with the TS queue Names for BBO# transactions. Chapter 2. z/os Connect Enterprise Edition change history 13

22 Table 1. Enhancements and fixes (continued) Maintenance leel API Editor V Enhancements and fixes Enhancements Multi-select for the Assign and Remoe mapping actions is now supported. When an Assign mapping is added, the Properties iew is brought forward and the newly created mapping is automatically selected for edits. Fixes A pop-up warning message is added when you try to export an API package to an API archie file name that exists, and the.aar file extension for an API archie is now enforced when you export an API package. A pop-up message is added to surface the underlying exception when you try to export an API package to an existing API archie file that is locked and cannot be oerridden. A warning message is added to inform you that existing mappings would be lost when you try to change serice assignment for a method with existing HTTP-to-JSON mappings. The mapping editor no longer shows the actions for adding data transforms on items that already hae a mapping. 14 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

23 Chapter 3. Sources of information The IBM Knowledge Center is the primary source of information about z/os Connect Enterprise Edition, but there are other documents that you might find useful. IBM Knowledge Center content The content of this IBM Knowledge Center is also aailable in these formats: As a download. You can use a locally hosted IBM Knowledge Center with z/os Connect Enterprise Edition product documentation for access oer your organization's intranet or offline access on your workstation. You can install the locally hosted IBM Knowledge Center on Windows and Linux. For more information, see As a PDF from the PDF library. Translated into the following national languages. Brazilian Portuguese, Czech, French, German, Hungarian, Japanese, Korean, Polish, Romanian, Russian, and Simplified Chinese. Other sources of information Configuring z/os Connect EE inside CICS Transaction Serer. deeloper.ibm.com/mainframe/2017/03/22/configuring-zos-connect-ee-insidecics-transaction-serer/ This article describes a working example of how to configure z/os Connect EE inside CICS Transaction Serer 5.3. Securing APIs with z/os Connect EE. docs/securing-apis/securing-apis-with-zos-connect-ee/ This article describes arious aspects of securing APIs with z/os Connect EE. Copyright IBM Corp. 2015,

24 16 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

25 Chapter 4. Scenarios Follow the steps in these scenarios to learn how to perform tasks such as deeloping and deploying APIs. You can find an example of creating and deploying APIs on YouTube: Deelop an API to inoke a CICS serice ia WOLA Use this scenario to deelop and deploy an API to inoke a CICS serice ia WOLA. You can then use that API to inoke a serice that is proided by the CICS Catalog Manager, one of the example applications included with CICS Transaction Serer. This scenario uses the WOLA serice proider that is proided with z/os Connect Enterprise Edition to connect to an application program that is running in a CICS region. WOLA connections require the Liberty angel process, the z/os Connect Enterprise Edition serer and CICS region to run in the same z/os LPAR. To enable this connection, you need to configure SAF resource definitions for CICS and 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 serice archie from an existing CICS application, and how to use the API Editor to create an API, including mapping of the HTTP request path and query parameters. It also proides instructions on how to configure a z/os Connect Enterprise Edition serer to use WOLA to connect to a CICS region. The following diagram shows the topology that is used in this scenario: z/os Connect EE Liberty Serer zosconnect feature CICS BBOC control transaction API request HTTP port HTTP to JSON mapping API Serice DataXform WOLA serice proider BBO# inocation task transaction WOLA BBO$ Link Serer Task Catalog Manager Programs WOLA WOLA TRUE angel process DFHRPL WOLA modules Prerequisites These are the prerequisites used to run this scenario. Copyright IBM Corp. 2015,

26 Software requirements z/os Connect Enterprise Edition V2.0 installed and zconsetup install command run CICS Transaction Serer 4.1 or higher installed and a CICS region running. Prerequisite tasks You need to complete the following tasks to proide the infrastructure needed by the scenario. Configure a started task to run a z/os Connect EE serer. 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 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: 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 EE serers on page 189. Configure the Liberty angel process as described in Configuring the Liberty angel process and z/os authorized serices on page 185. The angel process is required by WOLA to access z/os authorized serices. 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 page 115. The API Editor plug-in is required to create the API. Configuring the CICS Catalog Manager example application To run this scenario you will need to install and configure the CICS Catalog Manager example application. About this task This scenario uses the CICS Catalog Manager sample application as an example of an existing CICS application to be exposed as an API. This application must be installed and configured in your target CICS region. If this application is not yet configured, follow this procedure. For more information, refer to The CICS catalog manager example application in the CICS Transaction Serer documentation Procedure 1. Install and configure the CICS Catalog Manager example application. Follow the steps in Installing and setting up the base application. For the configuration step, enter the transaction ECFG on a CICS terminal to start the configuration application. Update the following alues to use a VSAM Datastore and the stubbed ersion of the Order Dispatcher: 18 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

27 CONFIGURE CICS EXAMPLE CATALOG APPLICATION Datastore Type ==> VSAM Outbound WebSerice? ==> NO Catalog Manager ==> DFH0XCMN Data Store Stub ==> Data Store VSAM ==> DFH0XVDS Order Dispatch Stub ==> DFH0XSOD Order Dispatch WebSerice ==> Stock Manager ==> DFH0XSSM VSAM File Name ==> EXMPCAT Serer Address and Port ==> Outbound WebSerice URI ==> STUB VSAM YES NO 2. Test that the application has been installed and configured correctly. Follow the instructions in Running the example application with the BMS interface. Results The sample application is now configured on CICS and can be run using the BMS interface. Follow the remaining steps to access this application from z/os Connect EE. Configuring CICS to use WOLA In this step, you configure the example CICS application and configure both CICS and SAF to use WOLA. About this task Configure CICS to use WebSphere Optimized Local Adapters (WOLA). WOLA is the serice proider that allows z/os Connect EE requests to interact with z/os assets. Procedure Follow the instructions in Configuring CICS to use WebSphere optimized local adapters (WOLA) on page 124. This scenario uses the following alues: Table 2. Values used in this scenario Parameter Group Name 2 Name 3 Region CATMGR1 CATMGR2 CATMGR3 When you define the SAF CBIND profile, use the same alues. For example, if you are using RACF, choose one of these options: 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) To use wildcards, and create only a single definition, enter the following commands: RDEF CBIND BBG.WOLA.* UACC(NONE) PERMIT BBG.WOLA.* CLASS(CBIND) ACCESS(READ) ID(CICSID) Chapter 4. Scenarios 19

28 Use your own alues. If you choose this option, ensure that you use the same alues in the corresponding steps later in the scenario. You must create a unique definition for each serer. Generate a serice archie from a CICS COBOL copybook Generate a Serice Archie (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 Enterprise Edition serices. Before you can create an API, you need to generate a Serice Archie (SAR) file, which proides information about the serice, including its expected request and response JSON schemas. SAR files for CICS serices are generated by using the z/os Connect Enterprise Edition utilities. This task shows you how to use IBM Explorer for z/os to create a serice archie file by using the sample BAQLS2JS JCL from an existing CICS COBOL application, the Catalog Manager example application. Procedure 1. Establish an FTP connection to your z/os LPAR. a. In IBM Explorer for z/os, go to the Host Connections iew. b. Under z/os, select z/os FTP then click Add. c. Type in your host name, then click Sae and Close. Your connection is listed as shown in the screen image: 2. Click Connect and enter your credentials. If the connection was successful, the red box changes to green. This example uses the sample z/os Connect EE utility JCL BAQLS2JS to generate serice archie files from existing language structures. In this case, CICS COBOL 20 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

29 application COMMAREA copybooks. The z/os Connect EE sample JCL <installation_dir>/jcl/baqls2js.jcl is customized for each serice and samples are proided. The following steps create SAR files for three different serices: Inquire single, Inquire catalog, and Place order. If you want to test just one serice, you can go directly to that step and complete the other steps at another time. Note: BAQLS2JS generates JSON schemas and bind files in addition to the SAR file for the serice. The names of the generated files are important because at run time the bind file and schema names must correspond to the zosconnectserice sericename attribute, which is configured in the serer.xml in a later step. The naming conention requires that the bind file must be called <sericename>.wsbind, the request schema must be called <sericename>_request.json, and the response schema must be called <sericename>_response.json. In each case, <sericename> is the alue that is specified 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 Perspectie and select the z/os perspectie. This perspectie proides the iews that you need to create the SAR files. 5. Create a SAR file for the Inquire single serice. a. Create a member called INQSINGL in your PDS. For example, <userid>.sar.jcl. In this example, create this member by using IBM Explorer for z/os. b. In the Data Sets iew, right-click on your PDS, and click New Data Set Member... c. In the Member Name field, enter INQSINGL. Ensure that Open Editor is checked. 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 Sae 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 alues: Chapter 4. Scenarios 21

30 Replace <Install Path> with the fully qualified installation path of z/os Connect EE. Replace <Output Path> with a UNIX System Serice path where you want the generated SAR, WSBIND file, and JSON schemas to be stored. For example, /u/userid/catalogmanager. Replace <CICSHLQ> with the HLQ of your CICS libraries. This HLQ is used to locate the COBOL copybooks for the CICS Catalog Manager example application. Replace <Jaa path> with the UNIX System Serice path where Jaa is installed. h. Ensure that the UNIX System Serice file paths that are defined for JSON-SCHEMA-REQUEST, JSON-SCHEMA-RESPONSE, WSBIND, and SERVICE-ARCHIVE parameters exist. You can use the z/os UNIX Files iew to check that the paths are correct. i. In the Data Sets iew, right-click the file INQSINGL and select Submit z/os Job. j. In the Console iew, click the job ID to open the z/os Job iew. k. In the z/os Job iew, 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 serice. Repeat step 5 using a new member called INQCAT and sample file BAQLS2JS_inquireCatalog.txt 7. Create a SAR file for the Place order serice. Repeat step 5 using a new member called ORDER and sample file BAQLS2JS_placeOrder.txt. 8. Transfer the generated SAR files, inquiresingle.sar, inquirecatalog.sar, and placeorder.sar to the local file system of the workstation where IBM Explorer for z/os is installed. This can be done by using FTP in binary mode. These files are required in the next step, to create an API which calls those serices. Create an API using z/os Connect EE API Editor Use the z/os Connect EE API Editor to create and deploy an API, using the SAR files you generated in the preious step. Before you begin Ensure that the inquiresingle.sar, inquirecatalog.sar, and placeorder.sar files that were generated in the preious step hae been transferred, in binary mode, to the machine where IBM Explorer for z/os is installed. For more details, see Generate a serice archie from a CICS COBOL copybook on page 20. Procedure 1. Start IBM Explorer for z/os and open the z/os Connect Enterprise Edition perspectie. 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 and click Next. 22 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

31 3. Fill in the sections for the new API project and click Finish. The z/os Connect Enterprise Edition API Editor dialog opens. Chapter 4. Scenarios 23

32 The following steps create an API path for the inquiresingle serice. This is implemented as an HTTP GET request and demonstrates the mapping of path parameters, and assign and remoe mappings. 4. Rename the default Path alue to be /items/{itemid} by typing oer the existing alue, where {itemid} indicates a path parameter whose alue will be substituted at runtime. 5. Remoe the POST, PUT and DELETE methods by clicking on the at the end of the line. This should leae only the GET method allowed for the path /items/{itemid}. 6. Click Serice for the GET method to select the serice archie file that defines the serice on this API path that will be called by an HTTP GET. The Select a z/os Connect EE Serice dialog opens 7. Click File System and naigate to the location of the inquiresingle.sar file. Select the sar file and click OK. The inquiresingle serice now appears in the Serice dialog. 24 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

33 Click OK. The serice is defined to the GET method. 8. Click Mapping for the GET method, then click open both mappings. The request and response mappings open in the editor so that you can define the mapping between the content of the HTTP API request and the JSON content passed to the z/os Connect Enterprise Edition serice. 9. In the request mapping, right click ca_request_id and select Add Assign. A static alue is assigned to the field in the request JSON schema. 10. Ensure Assign has focus. In the Properties iew, click General and set Value to 01INQS. This is the alue required by the CICS Catalog Manager application program to perform an inquiry on a single catalog item. 11. Check Omit from interface. This excludes this alue from the API Swagger document definition of the request body for this path. This alue must be set for the CICS Catalog Manager application, but because it is an internal implementation alue 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, right click the alue and click Add Remoe Transform. This changes the mapping to Remoe which excludes these alues from the API Swagger document definition of the request body for this path. These alues are not required on the request. They will be populated by the Catalog Manager application and returned in the response. 13. Connect the path parameter itemid to ca_item_ref_req. This creates a Moe and assigns the alue from the path parameter in the HTTP request to the Chapter 4. Scenarios 25

34 field in the JSON content passed to the z/os Connect Enterprise Edition serice. 14. In the response mapping, for each of ca_request_id and ca_item_ref_req, right click the alue and click Add Remoe Transform. This excludes these alues from the API Swagger document definition of the response body for this path and preents them being displayed in the API HTTP response body. These alues are only required on the request to the CICS application and do not need to be exposed in the response to the API user. The following steps are for the placeorder serice. This is implemented as an HTTP 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 serice placeorder.sar to the path. 16. Click Mapping for the POST method using the placeorder serice and select open both mappings. The request and response mappings open in the editor. 26 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

35 17. In the request mapping, right click ca_request_id and select Add Assign Transform A static alue is assigned to the field in the request JSON schema. 18. Click the Properties tab, then click Assign. Set Value to 01ORDR. This is the alue required by the CICS Catalog Manager application program to order items from the catalog. Check Omit from interface. 19. Add an Assign to ca_userid and ca_charge_dept. Both these JSON alues are assigned the default alue of an empty string, so no alue needs to be specified in the Properties tab for this example. 20. Add a Remoe for ca_return_code and ca_response_message This excludes these alues from the API Swagger document definition of the request body for this path. 21. In the response mapping, add a Remoe for ca_request_id and ca_order_request. This excludes these alues from the API Swagger document definition of the response body for this path, and preents them being displayed in the API HTTP response body. The following steps are for the inquirecatalog serice. This is implemented as an HTTP 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 serice inquirecatalog.sar to the path. 23. Click Mapping for the GET method using the inquirecatalog serice. Select open both mappings. The request and response mappings open in the editor. Chapter 4. Scenarios 27

36 24. In the request mapping, right click on ca_request_id and select Add Assign Transform This assigns a static alue to the field in the request JSON schema. 25. Click the Properties tab, then click Assign. Set Value to 01INQC. This is the alue required by the CICS Catalog Manager application program to perform an inquiry on catalog items. Check Omit from interface. This excludes this alue from the API Swagger document definition of the request body for this path. 26. Add a Remoe for ca_return_code, ca_response_message, ca_last_item_ref, ca_item_count and ca_cat_item This excludes these alues from the API Swagger document definition of the request body for this path. 27. Right click on Query Parameters and select Add Query Parameter. Fill in the name field with the name that you want to use for the query parameter. For example, startitemid. From the drop down menu, select integer for the type and check Required. 28. Click OK. Drag and link this query parameter to ca_list_start_ref. This creates a Moe and assigns the alue from the query parameter in the HTTP request to the field in the JSON content passed to the z/os Connect Enterprise Edition serice. 29. In the response mapping, add a Remoe for ca_request_id. 28 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

37 In the remaining steps, you export the API as an API package (API archie file) and transfer the archie file to the UNIX System Serices directory on the z/os LPAR where z/os Connect Enterprise Edition is installed. 30. Sae all files. Right click catalog in the Project Explorer iew. Click z/os Connect EE > Export z/os Connect EE API Package. 31. Click Workspace > Browse and naigate to the /catalog folder, to create an API archie file named catalog.aar in your catalog project. Click OK. z/os Connect Enterprise Edition V2.0 proides an apideploy tool to deploy the API archie file from a location in the USS file system into your z/os Connect Enterprise Edition serer configuration. 32. Transfer the API archie file. The API archie file must be transferred to a UNIX System Serice directory on the z/os LPAR, so that it can be accessed by the apideploy tool, which deploys the API archie file to a z/os Connect Enterprise Edition serer. When you want to uninstall the API archie file, the apideploy tool requires that the API archie file must still exist in the same USS directory where it was installed, so you must export the file to a permanent UNIX System Serice directory: a. Right-click on the API archie file catalog.aar in your catalog project. b. Select Export > General > z/os UNIX File System. c. Set Destination Directory to a suitable alue. For example: /u/userid/catalogmanager. d. Click Finish. Configuring the z/os Connect EE serer to use WOLA In this step, you create and configure a z/os Connect EE serer to use the WebSphere Optimized Local Adapter, the z/os Connect EE API, and serices for the Catalog Manager application. Before you begin 1. To use WOLA, the zoslocaladapters-1.0 feature must be enabled in your serer configuration. 2. You must set the WLP_USER_DIR enironment ariable to the location where you want your serer instances and user features to be stored. For example: /ar/zosconnect. Procedure 1. Create a serer by using the following command. You enter this command from the <installation_dir>/bin directory, for example: /usr/lpp/ibm/zosconnect/ 2r0/bin. zosconnect create catalogmanager --template=zosconnect:default Chapter 4. Scenarios 29

38 This command creates a serer that is called catalogmanager by using the default z/os Connect EE template. The default template defines the basic features in your serer.xml. You must manually add any other features that you need. 2. Customize the serer.xml configuration file for your z/os Connect EE serer to contain these elements: <serer description="zconnect Wola test serer"> <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"/> <!-- Local adapters config --> <zoslocaladapters wolagroup="catmgr1" wolaname2="catmgr2" wolaname3="catmgr3" /> <!-- Local adapters connection factory definition --> <connectionfactory id="wolacf" jndiname="eis/ola"> <properties.ola/> </connectionfactory> <!-- WOLA Connect serice and z/os Connect serice definitions --> <zosconnect_localadaptersconnectserice id="wolacatalogmanager" registername="cicsreg" sericename="dfh0xcmn" connectionfactoryref="wolacf"/> <zosconnect_zosconnectserice id="inquiresingleserice" requireauth="false" requiresecure="false" sericename="inquiresingle" sericeref="wolacatalogmanager" dataxformref="xformjson2byte" /> <zosconnect_zosconnectserice id="placeorderserice" requireauth="false" requiresecure="false" sericename="placeorder" sericeref="wolacatalogmanager" dataxformref="xformjson2byte" /> <zosconnect_zosconnectserice id="inquirecatalogserice" requireauth="false" requiresecure="false" sericename="inquirecatalog" sericeref="wolacatalogmanager" dataxformref="xformjson2byte" /> <!-- z/os Connect data transformation proider --> <zosconnect_zosconnectdataxform id="xformjson2byte" bindfileloc="<output path>" bindfilesuffix=".wsbind" requestschemaloc="<output path>" responseschemaloc="<output path>" requestschemasuffix=".json" responseschemasuffix=".json"> </zosconnect_zosconnectdataxform> </serer> The httpendpoint element attributes httpport and httpsport must be unique within your z/os LPAR The zoslocaladapters element attribute alues wolagroup, wolaname2, and wolaname3 are arbitrary but must match the alues that are specified in the 30 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

39 SAF CBIND profile when you configure CICS to use WOLA. Each name component is limited to eight alphanumeric characters with no blank spaces. The names are case-sensitie. If you hae mixed case in the serer.xml, then the external address space or program that seeks to register into the Liberty Serer would need to hae matching case. Make the alues uppercase to simplify creating the CBIND profile. The three-part name that is used by a Liberty Profile z/os serer instance must be unique on the z/os LPAR Note: WOLA requires a three-part name to be used when external address spaces, such as CICS, register into the Liberty Profile serer. The three-part name model is used to retain consistent behaior for when WOLA is used in WebSphere Application Serer for z/os full profile, which uses cell, name and serer constructs. The connectionfactory XML defines the WOLA JCA resource adapter that is used for communication outbound from a z/os Connect EE serer to CICS. In the localadaptersconnectserice 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 alue on the BBOC START_SRVR RGN command. The alue for sericename must match the name CICS is using for the serice name. That is, the target CICS program name. The alue of the sericename attribute in the zosconnectserice element must match the alue that is specified for the SERVICE-NAME property when you run BAQLS2JS. This alue is included in the generated.sar file and was used by the API Editor to identify the serice names that are associated with specific paths and methods in the API. The zosconnectdataxform specifies the extensions and directories that contain the bind file and JSON schemas that are generated for the CICS serices by the BAQLS2JS utility. Note: The bind file and schema names must correspond to the zosconnectserice sericename. In this example, sericename="inquiresingle" so the bind file must be called inquiresingle.wsbind, the request schema must be called inquiresingle_request.json the response schema must be called inquiresingle_response.json. <Output path> in the zosconnectdataxform element is the UNIX System Serices directory where you generated the bind file, request and response schemas for each of the serices in the earlier step Generate a serice archie from a CICS COBOL copybook on page 20. For example, /u/userid/catalogmanager. You can also choose to configure alternatie locations here, in which case you must copy the generated files to these locations. The bindfileloc, requestschemaloc, and responseschemaloc alues can all be different paths. What to do next The serer is configured. In the next step, you will deploy the API. Deploying an API to the z/os Connect EE serer Deploy the API archie file to the z/os Connect EE serer. Chapter 4. Scenarios 31

40 About this task You need to deploy your API to make it aailable. Note: If you hae z/os Connect EE V or later installed, you can deploy your APIs directly from the API Editor. For more information, see Deploying an API 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>/serers/<serer name>/resources/zosconnect/apis For example, /usr/lpp/ibm/zosconnect/2r0/bin/apideploy -deploy -a /u/userid/catalogmanager/catalog.aar -p /ar/zosconnect/serers/catalogmanager/resources/zosconnect/apis Note: The path that is specified on the -p parameter must exist before the command is run. If an API is already deployed, add the -w at the end of the command to oerwrite the API with the new ersion. Test the scenario Start the WOLA connection between the z/os Connect EE serer and the CICS region, make HTTP calls to confirm that your serices and APIs are installed correctly, then call the APIs. About this task Note: The HTTP GET requests can be made in any browser. The HTTP POST request requires the use of a browser with a REST Client browser plug-in. Procedure 1. Start the angel process started task by typing the command on the operator console: S BBGZANGL 2. Restart the z/os Connect EE serer. To presere the case of your serer name, you must start the serer from the System Command Extension window within SDSF. From SDSF, type / to open the extended console, then enter the command: S BAQSTRT,PARMS='<sererName> --clean' a. Check the serer's message log file in <WLP_USER_DIR>/serers/ {serername}/logs/messages.log. The following messages appear: CWWKB0103I: Authorized serice group LOCALCOM is aailable. CWWKB0103I: Authorized serice group WOLA is aailable.... CWWKB0501I: The WebSphere Optimized Local Adapter channel registered with the Liberty profile serer with the following nam 32 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

41 CATMGR1 CATMGR2 CATMGR3... J2CA7001I: Resource adapter wola installed in seconds. Where: If the LOCALCOM serice group is aailable, then the angel is running and your Liberty Serer ID has READ access to that SERVER profile. If the WOLA serice group is aailable, then the configuration was completed successfully. The CWWKB0501I message is showing the successful use of the WOLA three part name alues you proided in the serer.xml file. This message indicates that an external address space might register into the Liberty Profile serer, in this instance the z/os Connect EE serer, by using this three-part name on the BBOA1REG API. The J2CA7001I message indicates that the WOLA JCA resource adapter is aailable. 3. Ensure that the CICS region is started 4. Start the TRUE and Link Serer task from CICS, and register with WOLA. The z/os Connect EE serer 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 serer task and register to your serer: BBOC START_SRVR RGN=CICSREG DGN=GROUP NDN=NAME2 SVN=NAME3 SVC=* MNC=1 MXC=10 TXN=N SEC=N REU=Y Where GROUP, NAME2, and NAME3 match the alues that are specified on the zoslocaladapters element in the serer.xml configuration file to create the three part name for WOLA. For example: BBOC START_SRVR RGN=CICSREG DGN=CATMGR1 NDN=CATMGR2 SVN=CATMGR3 SVC=* MNC=1 MXC=10 TXN=N SEC=N REU=Y The following message indicates success: WOLA TRACE 0: Start serer 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 topic Optimized local adapters for z/os APIs in the WebSphere Application Serer z/os documentation. Go to the Register section (also known as the BBOA1REG section) and look for the RC and RSN code that is proided there. You can now send requests from the z/os Connect Enterprise Edition serer ia WOLA to CICS. 5. From a web browser, enter an HTTP GET request to list all the installed z/os Connect Enterprise Edition serices: name>:<port>/zosconnect/serices Chapter 4. Scenarios 33

42 For example: If your serices are working correctly, the following response is receied: { "zosconnectserices": [ { "SericeName": "inquiresingle", "SericeDescription": "DATA_UNAVAILABLE", "SericeProider": "WOLA-1.0", "SericeURL": " }, { "SericeName": "inquirecatalog", "SericeDescription": "DATA_UNAVAILABLE", "SericeProider": "WOLA-1.0", "SericeURL": " }, { "SericeName": "placeorder", "SericeDescription": "DATA_UNAVAILABLE", "SericeProider": "WOLA-1.0", "SericeURL": " } ] } 6. From a web browser, enter an HTTP GET request to list all the installed z/os Connect Enterprise Edition APIs: name>:<port>/zosconnect/apis For example: If your API is installed correctly, the following response is receied: { "apis": [ { "name": "catalog", "ersion": "1.0.0", "description": "API for the CICS catalog manager example application", "adminurl": " } ] } 7. From a web browser, enter an HTTP GET request to iew the SWAGGER document for the catalog API: If your API request is successful, the HTTP response contains the API's SWAGGER document. Notice that the host alue is updated to show the serer where the API is deployed, as follows: 34 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

43 { "swagger": "2.0", "info": { "description": "", "ersion": "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 on a single catalog item: Where: catalogmanager is the base path alue that is defined in the API definition 9080 is the HTTP port the z/os Connect EE serer uses to listen for HTTP requests. items is the path that is defined in the API for inquiring on a single catalog item 10 is the runtime alue for the path parameter alue {itemid} If your API request is successful, the following response is receied: Chapter 4. Scenarios 35

44 { "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 an order: Note: A POST request requires the use of a browser with a REST Client browser plug-in. Add an HTTP header: Content-Type: application/json. The Content-Type informs the z/os Connect EE serer that the HTTP body data it receies contains 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 receied: { "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 the items in the catalog, starting with the item whose catalog item reference is 10: Where?startitemID=10 is a query parameter whose name is startitemid and alue is 10. If your API request is successful, the following response is receied: 36 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

45 { "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 serer task, type the following commands from a CICS session: BBOC STOP_SRVR RGN=CICSREG Where the RGN alue must match the alue that is specified when you registered the CICS region. The following message indicates success: WOLA TRACE 0: Stop serer 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 Guide aailable from Techdoc WP What to do next You can compare these results with the results you saw when you tested the Catalog Manager application with the BMS interface. For more information on the BBOC CICS transactions, see WebSphere Application Serer transactions BBOC, BBO$, BBO# in the WebSphere Application Serer for z/os documentation. Chapter 4. Scenarios 37

46 Deelop an API to inoke a CICS serice using the CICS serice proider Use this scenario to deelop and deploy an API to inoke a CICS serice using the CICS serice proider You can then use that API to inoke a serice that is proided by the CICS Catalog Manager, one of the example applications proided by CICS Transaction Serer. This scenario uses the CICS serice proider to connect to an application program that is running in a CICS region. The z/os Connect Enterprise Edition serer and CICS region must run in the same z/os LPAR. To enable this connection, you need to configure SAF resource definitions for CICS and 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 serice archie from an existing CICS application, and how to use the API Editor to create an API, including mapping of the HTTP request path and query parameters. Prerequisites The following facilities are needed to run this scenario. Software requirements z/os Connect Enterprise Edition V2.0 installed and zconsetup install command run successfully. CICS Transaction Serer 4.1 or higher installed and a CICS region running. Prerequisite tasks You need to complete the following tasks to proide the infrastructure needed by the scenario. Configure a started task to run a z/os Connect EE serer. 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 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: 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 EE serers on page 189. 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 page 115. The API Editor plug-in is required to create the API. You can install a REST client for your web browser to make testing easier. Configuring the CICS Catalog Manager example application To run this scenario you will need to install and configure the CICS Catalog Manager example application 38 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

47 About this task This scenario uses the CICS Catalog Manager sample application as an example of an existing CICS application to be exposed as an API. This application must be installed and configured in your target CICS region. If this application is not yet configured, follow this procedure. For more information, refer to The CICS catalog manager example application in the CICS Transaction Serer documentation Procedure 1. Install and configure the CICS Catalog Manager example application. Follow the steps in Installing and setting up the base application. For the configuration step, enter the transaction ECFG on a CICS terminal to start the configuration application. Update the following alues to use a VSAM Datastore and the stubbed ersion of the Order Dispatcher: CONFIGURE CICS EXAMPLE CATALOG APPLICATION Datastore Type ==> VSAM Outbound WebSerice? ==> NO Catalog Manager ==> DFH0XCMN Data Store Stub ==> Data Store VSAM ==> DFH0XVDS Order Dispatch Stub ==> DFH0XSOD Order Dispatch WebSerice ==> Stock Manager ==> DFH0XSSM VSAM File Name ==> EXMPCAT Serer Address and Port ==> Outbound WebSerice URI ==> STUB VSAM YES NO 2. Test that the application has been installed and configured correctly. Follow the instructions in Running the example application with the BMS interface. Results The sample application is now configured on CICS and can be run using the BMS interface. Follow the remaining steps to access this application from z/os Connect EE. Generate a serice archie from a CICS COBOL copybook Generate a Serice Archie (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 Enterprise Edition serices. Before you can create an API, you need to generate a Serice Archie (SAR) file, which proides information about the serice, including its expected request and response JSON schemas. SAR files for CICS serices are generated by using the z/os Connect Enterprise Edition utilities. This task shows you how to use IBM Explorer for z/os to create a serice archie file by using the sample BAQLS2JS JCL from an existing CICS COBOL application, the Catalog Manager example application. Procedure 1. Establish an FTP connection to your z/os LPAR. a. In IBM Explorer for z/os, go to the Host Connections iew. b. Under z/os, select z/os FTP then click Add. c. Type in your host name, then click Sae and Close. Your connection is listed as shown in the screen image: Chapter 4. Scenarios 39

48 2. Click Connect and enter your credentials. If the connection was successful, the red box changes to green. This example uses the sample z/os Connect EE utility JCL BAQLS2JS to generate serice archie 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 serice and samples are proided. The following steps create SAR files for three different serices: Inquire single, Inquire catalog, and Place order. If you want to test just one serice, you can go directly to that step and complete the other steps at another time. Note: BAQLS2JS generates JSON schemas and bind files in addition to the SAR file for the serice. The names of the generated files are important because at run time the bind file and schema names must correspond to the zosconnectserice sericename attribute, which is configured in the serer.xml in a later step. The naming conention requires that the bind file must be called <sericename>.wsbind, the request schema must be called <sericename>_request.json, and the response schema must be called <sericename>_response.json. In each case, <sericename> is the alue that is specified 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 Perspectie and select the z/os perspectie. This perspectie proides the iews that you need to create the SAR files. 5. Create a SAR file for the Inquire single serice. 40 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

49 a. Create a member called INQSINGL in your PDS. For example, <userid>.sar.jcl. In this example, create this member by using IBM Explorer for z/os. b. In the Data Sets iew, right-click on your PDS, and click New Data Set Member... c. In the Member Name field, enter INQSINGL. Ensure that Open Editor is checked. 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 Sae 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 alues: Replace <Install Path> with the fully qualified installation path of z/os Connect EE. Replace <Output Path> with a UNIX System Serice path where you want the generated SAR, WSBIND file, and JSON schemas to be stored. For example, /u/userid/catalogmanager. Replace <CICSHLQ> with the HLQ of your CICS libraries. This HLQ is used to locate the COBOL copybooks for the CICS Catalog Manager example application. Replace <Jaa path> with the UNIX System Serice path where Jaa is installed. h. Ensure that the UNIX System Serice file paths that are defined for JSON-SCHEMA-REQUEST, JSON-SCHEMA-RESPONSE, WSBIND, and SERVICE-ARCHIVE parameters exist. You can use the z/os UNIX Files iew to check that the paths are correct. i. In the Data Sets iew, right-click the file INQSINGL and select Submit z/os Job. j. In the Console iew, click the job ID to open the z/os Job iew. k. In the z/os Job iew, 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 serice. Repeat step 5 using a new member called INQCAT and sample file BAQLS2JS_inquireCatalog.txt 7. Create a SAR file for the Place order serice. Repeat step 5 using a new member called ORDER and sample file BAQLS2JS_placeOrder.txt. Chapter 4. Scenarios 41

50 8. Transfer the generated SAR files, inquiresingle.sar, inquirecatalog.sar, and placeorder.sar to the local file system of the workstation where IBM Explorer for z/os is installed. This can be done by using FTP in binary mode. These files are required in the next step, to create an API which calls those serices. Deploying an API to the z/os Connect EE serer Deploy the API archie file to the z/os Connect EE serer. About this task You need to deploy your API to make it aailable. Note: If you hae z/os Connect EE V or later installed, you can deploy your APIs directly from the API Editor. For more information, see Deploying an API 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>/serers/<serer name>/resources/zosconnect/apis For example, /usr/lpp/ibm/zosconnect/2r0/bin/apideploy -deploy -a /u/userid/catalogmanager/catalog.aar -p /ar/zosconnect/serers/catalogmanager/resources/zosconnect/apis Note: The path that is specified on the -p parameter must exist before the command is run. If an API is already deployed, add the -w at the end of the command to oerwrite the API with the new ersion. Test the scenario Start the WOLA connection between the z/os Connect EE serer and the CICS region, make HTTP calls to confirm that your serices and APIs are installed correctly, then call the APIs. About this task Note: The HTTP GET requests can be made in any browser. The HTTP POST request requires the use of a browser with a REST Client browser plug-in. Procedure 1. Start the angel process started task by typing the command on the operator console: S BBGZANGL 2. Restart the z/os Connect EE serer. To presere the case of your serer name, you must start the serer from the System Command Extension window within SDSF. From SDSF, type / to open the extended console, then enter the command: 42 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

51 S BAQSTRT,PARMS='<sererName> --clean' a. Check the serer's message log file in <WLP_USER_DIR>/serers/ {serername}/logs/messages.log. The following messages appear: CWWKB0103I: Authorized serice group LOCALCOM is aailable. CWWKB0103I: Authorized serice group WOLA is aailable.... CWWKB0501I: The WebSphere Optimized Local Adapter channel registered with the Liberty profile serer with the following n CATMGR1 CATMGR2 CATMGR3... J2CA7001I: Resource adapter wola installed in seconds. Where: If the LOCALCOM serice group is aailable, then the angel is running and your Liberty Serer ID has READ access to that SERVER profile. If the WOLA serice group is aailable, then the configuration was completed successfully. The CWWKB0501I message is showing the successful use of the WOLA three part name alues you proided in the serer.xml file. This message indicates that an external address space might register into the Liberty Profile serer, in this instance the z/os Connect EE serer, by using this three-part name on the BBOA1REG API. The J2CA7001I message indicates that the WOLA JCA resource adapter is aailable. 3. Ensure that the CICS region is started 4. Start the TRUE and Link Serer task from CICS, and register with WOLA. The z/os Connect EE serer 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 serer task and register to your serer: BBOC START_SRVR RGN=CICSREG DGN=GROUP NDN=NAME2 SVN=NAME3 SVC=* MNC=1 MXC=10 TXN=N SEC=N REU=Y Where GROUP, NAME2, and NAME3 match the alues that are specified on the zoslocaladapters element in the serer.xml configuration file to create the three part name for WOLA. For example: BBOC START_SRVR RGN=CICSREG DGN=CATMGR1 NDN=CATMGR2 SVN=CATMGR3 SVC=* MNC=1 MXC=10 TXN=N SEC=N REU=Y The following message indicates success: WOLA TRACE 0: Start serer 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 topic Optimized local adapters for z/os APIs in the WebSphere Application Serer z/os documentation. Go to the Register section (also known as the BBOA1REG section) and look for the RC and RSN code that is proided there. Chapter 4. Scenarios 43

52 You can now send requests from the z/os Connect Enterprise Edition serer ia WOLA to CICS. 5. From a web browser, enter an HTTP GET request to list all the installed z/os Connect Enterprise Edition serices: name>:<port>/zosconnect/serices For example: If your serices are working correctly, the following response is receied: { "zosconnectserices": [ { "SericeName": "inquiresingle", "SericeDescription": "DATA_UNAVAILABLE", "SericeProider": "WOLA-1.0", "SericeURL": " }, { "SericeName": "inquirecatalog", "SericeDescription": "DATA_UNAVAILABLE", "SericeProider": "WOLA-1.0", "SericeURL": " }, { "SericeName": "placeorder", "SericeDescription": "DATA_UNAVAILABLE", "SericeProider": "WOLA-1.0", "SericeURL": " } ] } 6. From a web browser, enter an HTTP GET request to list all the installed z/os Connect Enterprise Edition APIs: name>:<port>/zosconnect/apis For example: If your API is installed correctly, the following response is receied: { "apis": [ { "name": "catalog", "ersion": "1.0.0", "description": "API for the CICS catalog manager example application", "adminurl": " } ] } 7. From a web browser, enter an HTTP GET request to iew the SWAGGER document for the catalog API: If your API request is successful, the HTTP response contains the API's SWAGGER document. Notice that the host alue is updated to show the serer where the API is deployed, as follows: 44 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

53 { "swagger": "2.0", "info": { "description": "", "ersion": "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 on a single catalog item: Where: catalogmanager is the base path alue that is defined in the API definition 9080 is the HTTP port the z/os Connect EE serer uses to listen for HTTP requests. items is the path that is defined in the API for inquiring on a single catalog item 10 is the runtime alue for the path parameter alue {itemid} If your API request is successful, the following response is receied: Chapter 4. Scenarios 45

54 { "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 an order: Note: A POST request requires the use of a browser with a REST Client browser plug-in. Add an HTTP header: Content-Type: application/json. The Content-Type informs the z/os Connect EE serer that the HTTP body data it receies contains 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 receied: { "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 the items in the catalog, starting with the item whose catalog item reference is 10: Where?startitemID=10 is a query parameter whose name is startitemid and alue is 10. If your API request is successful, the following response is receied: 46 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

55 { "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 serer task, type the following commands from a CICS session: BBOC STOP_SRVR RGN=CICSREG Where the RGN alue must match the alue that is specified when you registered the CICS region. The following message indicates success: WOLA TRACE 0: Stop serer 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 Guide aailable from Techdoc WP What to do next You can compare these results with the results you saw when you tested the Catalog Manager application with the BMS interface. For more information on the BBOC CICS transactions, see WebSphere Application Serer transactions BBOC, BBO$, BBO# in the WebSphere Application Serer for z/os documentation. Chapter 4. Scenarios 47

56 Create an IMS mobile serice You can create an IMS mobile serice to enable RESTful access to IMS transactions ia the IMS serice proider supplied with z/os Connect EE. This scenario inoles the use of the IMS Mobile feature (imsmobile-2.0), which seres as the IMS serice proider. The IMS Mobile feature was preiously included in the IMS Enterprise Suite as the IMS Mobile Feature Pack for z/os Connect EE. The IMS Mobile feature includes the following functions: A data transformation module that conerts request messages from the JSON format to the natie representation of the input message and then conerts the response messages to JSON. An IMS Connect adapter module that interacts with IMS Connect for IMS Transaction Manager (TM) access. A serice management and administration interface that is used by IMS Explorer for Deelopment to proide the user interface for serice creation, testing, and management. A sample ping serice to use as an installation erification program (IVP). The tool for creating, publishing, and testing serices is proided by IMS Explorer for Deelopment, an Eclipse-based graphical tool for creating, testing, and publishing serices based the data structures in IMS COBOL copybooks or PL/I includes. The z/os Connect EE API Editor proides the tool for defining RESTful APIs to act on the resources that are exposed in the serices. The following diagram shows the request and response processing and the components that are inoled at run time. When a request comes in, z/os Connect EE handles the user access control and the conersion between HTTP and JSON based on the API packages are deployed. The IMS mobile serice proider is inoked, and the request message is conerted from JSON to the natie representation of the input message (for example, bytes array or arrays for segments in COBOL and PL/I applications). The request then goes through the IMS Connect for access to IMS transactions. These transactions might be accessing IMS DB, DB2, or other external subsystems such as WebSphere MQ or WebSphere Optimized Local Adapters (WOLA). The serice definition, request and response metadata, interaction profile, and connection profile are stored in the IMS mobile serice registry. 48 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

57 Figure 2. The IMS mobile solution process flow and components inoled Prerequisites Examine the operational requirements, considerations and restrictions to assist the planning and design of your mobile solution. z/os Connect EE is properly installed. The IMS Mobile feature is properly configured. For more information, see Using the IMS serice proider on page 129. IMS Explorer for Deelopment V or later is properly installed. IMS Explorer for Deelopment (IMS Explorer) can be downloaded from the Download Eclipse tools page on the mainframe deelopment site at Follow the instructions on the page for IBM Installation Manager. Updates of the IMS Mobile feature might require a newer ersion of IMS Explorer. Check the Chapter 2, z/os Connect EE change history, on page 7 topic for any potential compatibility issues. Restrictions The IMS Mobile feature has restrictions on the type of IMS transactions that are supported and on data conersion from the high-leel languages to JSON. Only transactions with a single input message and a single output message are supported, although the message can contain multiple segments. For Chapter 4. Scenarios 49

58 non-response transactions or when IMS encounters an error while processing the transaction, a GMOBA0920E message is generated that includes the DFS message from IMS. For COBOL to JSON data conersion restrictions, see COBOL to JSON schema mapping (IMS Explorer). For PL/I to JSON data conersion restrictions, see PL/I to JSON schema mapping (IMS Explorer). Request and response messages for IMS mobile serices Request and response messages for IMS mobile serices are represented in JSON format. The schema can be obtained through the getrequestschema and getresponseschema actions. In general, the JSON schema looks as follows: { } "type": "object", "properties": { "<TopLeelStructureName1>": { "type": "object", "properties": { "<fieldname>":"<fieldvalue>",..., "<fieldnamen>":"<fieldvaluen>" } },..., "<TopLeelStructureNameN>": { "type": "object", "properties": { "<fieldname>":"<fieldvalue>",..., "<fieldnamen>":"<fieldvaluen>" } } } The following sample request data is based on the IMS phonebook sample application. 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":" ", "OUT_ZIP":"95141 ", "OUT_SEGNO":"0001"}] } } 50 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

59 When an error occurs, a response message with the error detail is returned in key-alue pair in the following format: { } "status": HTTP status code, "messagecode": Message code, "message": "Message text", "details": "Message detail for mobile deeloper", "moreinfo":"url to the message documentation" "response": "Result of the request, if any" Mobile application deelopers are responsible for checking for returned HTTP status codes that are not 200, and process the response based on the error message code. Mobile serice creators can use IMS Explorer for Deelopment to choose specific fields in an IMS transaction to expose as part of the input and output serice metadata and assign default alues. For the input stream format and each possible output stream format, users of the mobile application receie the name, data type, and default alue, if specified, for each field. Regardless of data type, the mobile application must send, at run time, a character representation of the field alues. This character representation is conerted to the natie representation of the input message before the request is sent to IMS. Based on the message interface that is generated by IMS Explorer for Deelopment, a serice expects input and output data fields to match the data structure in the interface. 1. On input, JSON name-alue pairs are marshalled into bytes arrays. JSON field names must match the field name from the message interface. The pairs are marshalled one at a time. 2. On output, the byte array is un-marshalled into JSON name-alue pairs. All fields in the metadata are returned in the response, but you can deselect fields in IMS Explorer for Deelopment when you define the serice interface to omit those fields in the response. Output JSON field names match the field names from the metadata. Tip: Default alues from COBOL or PL/I fields are not captured in the message interface. IMS Explorer for Deelopment also proides adanced data conersion options, allowing you to trim leading or trailing white spaces, exclude non-printable control characters, or suppress low alues or empty tags from the JSON response messages. Related reference: IMS phonebook application description For more information about the phonebook application, see the tutorial topic. High-leel language and JSON schema mapping The data mapping function in IMS Explorer for Deelopment communicates with the data transformation function in IMS Mobile feature to generate JSON schemas from high-leel language data structures and ice ersa. Chapter 4. Scenarios 51

60 Each JSON schema element contains the following attributes: name: Name of the field. type: JSON data type for the field, such as string, integer, number, or array. maxlength (for string type): The maximum length allowed for the field. multipleof (for numeric type): The decimal alue based on the numeric scale for the field, for example, minoccurs (for array type): The minimal occurrences in the array (COBOL OCCURS statements). maxoccurs (for array type): The maximum occurrences in the array (COBOL OCCURS statements). minimum* (for numeric type): The recommended minimal alue allowed for the field. maximum* (for numeric type): The recommended maximum alue allowed for the field. description: Additional information or remarks entered in the IMS Explorer for Deelopment about the field. *: Data type conersion for large numeric data could result in some loss of accuracy. For more information about COBOL-to-JSON and PL/I-to-JSON data mapping, see and in the IMS Explorer for Deelopment 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": { "maxlength": 10, "type": "string" }, "IN_ZIP": { "maxlength": 7, "type": "string" }, "IN_TRCD": { "maxlength": 10, "type": "string" }, "IN_LL": { "maximum": 32768, "type": "integer", "minimum": }, "IN_ZZ": { "maximum": 32768, "type": "integer", "minimum": }, 52 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

61 } } "IN_NAME1": { "maxlength": 10, "type": "string" }, "IN_NAME2": { "maxlength": 10, "type": "string" } For output messages: { } "Display": { "OUT_MSG": { "maxlength": 40, "type": "string" }, "OUT_ZIP": { "maxlength": 7, "type": "string" }, "OUT_LL": { "maximum": 32768, "type": "integer", "minimum": }, "OUT_ZZ": { "maximum": 32768, "type": "integer", "minimum": }, "OUT_NAME1": { "maxlength": 10, "type": "string" }, "OUT_SEGNO": { "maxlength": 4, "type": "string" }, "OUT_NAME2": { "maxlength": 10, "type": "string" }, "OUT_CMD": { "maxlength": 8, "type": "string" }, "OUT_EXTN": { "maxlength": 10, "type": "string" } } Chapter 4. Scenarios 53

62 Related reference: IMS phonebook application description (in the tutorial) For more information about the phonebook application, see the tutorial topic. IMS serice creation workflow Use the IMS Explorer for Deelopment (IMS Explorer) to create and publish the necessary resources that define an IMS serice to the serer, including connection profiles, interaction profiles, transaction message metadata, and serice metadata. IMS Explorer can be downloaded from the. Follow the instructions on the page for IBM Installation Manager. Creating IMS mobile serices generally inoles the following steps in IMS Explorer for Deelopment: 1. Set up for connection to the z/os Connect EE serer 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 serice interacts with IMS Connect, such as commit mode and sync leel. 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 serice to the serer by specifying the transaction name, the interaction properties profile, and the connection profile to use. 6. Create a test case to inoke the mobile serice to ensure that all the specified metadata is correct, and that the transaction returns the expected output. After the serice is created and tested, export the serice as a SAR file. Import the SAR file into the z/os Connect EE API Editor to design, deelop, and test the REST API for the serice. This scenario is based on the MS phonebook application (IVTNO). The phonebook copybook is proided. Related information: Tutorial: Create an IMS mobile serice This tutorial takes you through the steps to create a REST serice to enable access to the IMS phonebook application through the JSON/REST protocol. Learning objecties You will learn the following concepts and steps to REST-enable your IMS applications: The process, the components, and the tool inoled in creating an IMS mobile serice. The access permission that you need to the IMS gateway serer and to IMS for creating a REST serice from an IMS application. What message metadata is, and how to define it from the input and output messages of an IMS transaction. Background and workflow 54 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

63 To expose an IMS transaction as a RESTful serice, the z/os Connect EE serer (also known as the IMS gateway serer) that handles request routing must hae information about how to connect to IMS through IMS Connect (the connection profile), how to interact with an IMS transaction (the interaction properties profile), what the transaction message contains (message metadata), and the name of the RESTful serice. To specify all the required information, you will use IMS Explorer for Deelopment (IMS Explorer). Figure 3. Information required on the serer to enable RESTful access to IMS transactions This tutorial will step you through the steps to specify and define the required information: 1. Create a connection to the z/os Connect EE serer. 2. Define an IMS connection profile for use to connect to IMS. 3. Define an IMS interaction properties profile that specifies how to inoke an IMS transaction. 4. Define the message metadata that can be used to conert between the JaaScript Object Notation (JSON) message format and the bytes array format of an IMS transaction. Time required This tutorial should take approximately 90 minutes to finish. If you explore other concepts related to this tutorial, it could take longer to complete. Chapter 4. Scenarios 55

64 Audience IMS application programmers that are familiar with the IMS transactions to be enabled for RESTful access. Prerequisites Use the following checklist to gather the information you need and to ensure you hae the required setup before you begin. 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 for more information. Record the following information for connecting to the z/os Connect EE serer: Host name: Port number: A compatible ersion of IMS Explorer for Deelopment is downloaded and properly installed on your workstation. To install IMS Explorer for Deelopment, go to the on the Mainframe Deelopment website. Follow the instructions for IBM Installation Manager. The user name you can use to access the z/os Connect EE serer. This user must be set up as an administratie user in order to deploy a serice. Obtain this user ID from your serer administrator. Record the user name for the serer here: The user name and password you can use to access the backend IMS must be identified and set up. Obtain this user ID from your IMS system administrator or 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: The IMS phonebook application is set up through the installation erification program (IVP) H216T and H213J. Obtain the phonebook copybook (IMSPHBK.cpy) file from your IMS system administrator. The phonebook copybook (IMSPHBK.cpy) is required. Although it is included with IMS and you can obtain it from your IMS system administrator, you can also right-click here and select Sae Link As (in FireFox) or Sae Target As (in Microsoft Internet Explorer) to download it. Rename the downloaded file with a.cpy extension. Note that this ersion of the phonebook copybook is modified with different field names so they are easier to understand. Connect to the z/os Connect EE serer To specify all the required information for RESTful access to an IMS transaction in IMS Explorer for Deelopment (IMS Explorer), you must first establish a connection from IMS Explorer to the serer. About this task In this first step, we will connect to the serer from IMS Explorer. 56 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

65 Note: Starting IMS Explorer V and later, some user interface labels hae changed. The term IMS gateway serer is replaced by z/os Connect EE serer. The IMS Gateway Naigator iew is renamed to IMS Serice Naigator. If you hae an older ersion of IMS Explorer, update to the latest ersion to take adantage of new and enhanced features and defect fixes. Procedure 1. Switch to the IMS Mobile perspectie. a. From the main menu, select Window > Open Perspectie > Other The Select Perspectie wizard opens. b. Click IMS Mobile. c. Click OK. The IMS Mobile perspectie opens. 2. In the IMS Mobile perspectie of IMS Explorer, from the IMS Serice Naigator iew, right-click the z/os Connect EE Serers folder and click Connect to a z/os Connect EE serer. 3. In the Create a z/os Connect EE serer connection wizard, enter the following information: Table 3. IMS gateway serer connection information Field Name Host name Port number User ID Description Proide a name for the z/os Connect EE serer. The host name for the location where IMS Mobile is installed and configured. The port number for the location where IMS Mobile is installed and configured. The user ID that has access to the IMS Mobile serer. 4. Click OK to establish the connection to the z/os Connect EE serer. 5. Expand the z/os Connect EE Serers folder in the IMS Serice Naigator iew to erify that the z/os Connect EE serer that you created is displayed with the following folders: IMS Connection profiles IMS interaction properties profiles Serices 6. Expand the z/os Connect EE Serers folder in the IMS Transaction Naigator iew to erify that the serer connection that you created is displayed with the Transactions folder. Results You can now proceed to define the required information for your serice. Define an IMS connection profile When the serer receies a RESTful serice request, it first authorizes the user and then routes the request through the IMS serice proider to the appropriate IMS Connect based on a defined connection profile. Connection profiles can be shared by any number of serices. About this task In this step, you will create a connection profile for the serer to authorizes the user that is associated with a request. Chapter 4. Scenarios 57

66 Procedure 1. In the IMS Serice Naigator iew, expand the serer that you created in the preious 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 Name Host Port number User name Password Description Your IMS connection profile name. The name of the system on which IMS Connect is running. The port number of the system on which IMS Connect is running. The user name to connect to IMS Connect. The password for connection to IMS Connect. 4. Click Finish to deploy the connection definition to the serer. Results The connection profile shows up under the IMS Connection profiles folder. Define an IMS interaction properties profile After the connection with IMS Connect is established, you need to define how the serer should inoke an IMS transaction. About this task You can specify the IMS ID that the transaction will be routed to, the commit mode, and the sync leel to use for this interaction by defining an interaction properties profile. Similar to the connection profiles, the interaction properties profiles can be shared by any number of serices. Procedure 1. In the IMS Serice Naigator iew, expand the serer 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 Profile name IMS destination name Description A unique name for your IMS interaction properties profile. The ID of the IMS system that you want to route to. This name should match one of the ID alues of the DATASTORE statement in IMS Connect. You can keep the default alues for all other fields. 4. Click Finish to deploy the IMS interaction properties definition to the IMS gateway serer. 58 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

67 Results The interaction properties profile shows up under the IMS interaction properties profiles folder. You hae created a connection profile and an interaction properties profile. You will now define the message metadata for the IMS phonebook application (transaction IVTNO). Define message metadata for the IMS phonebook application The IMS Mobile feature uses message metadata to conert from RESTful serice input, which is in JaaScript 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 the input and output messages of the transaction. Import the copybook into your project to generate the necessary metadata for the serer to complete this data transformation. The phonebook application, if you use the IMSPHBK.cpy file that is proided with this 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 OUT-ZZ PICTURE S9(3) COMP VALUE 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 are different. For example, IN_NAME1 is last name, and IN_NAME2 is first name. Howeer, the structure is the same. The phonebook serice requires the following input fields: IN_TRANCODE is a alue up to 10 characters. IN_COMMAND has the following alid alues: ADD, DISPLAY, DELETE, and UPDATE. IN_LAST_NAME is a alue up to 10 characters. IN_FIRST_NAME is a alue up to 10 characters. IN_EXTENSION is a alue up to 10 characters. IN_ZIP_CODE is a alue up to 7 characters. Chapter 4. Scenarios 59

68 The expected output for phonebook is OUT_MESSAGE, which contain a message up to 40 characters indicating success or failure. In the following steps, you will import the input and output metadata for our IVTNO transaction from a COBOL copybook called IMSPHBK.cpy to create the message metadata. The IMSPHBK.cpy file is included with IMS and is proided with this tutorial for your conenience. Right-click here and select Sae Link As (in FireFox) or Sae Target As (in Microsoft Internet Explorer) to download it. Rename the file with a.cpy extension. Procedure 1. In the IMS Transaction Naigator iew, expand the serer 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) alue. For example, IVTNO, and click OK. A new tab for IVTNO.trn opens in the IMS Explorer Transaction Message Metadata Editor. 4. Click Import data structure. 5. In the Import wizard, click Browse 6. In the Select File dialog, naigate to the phonebook copybook file IMSPHBK.cpy on 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 data structure 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 selected h. Click Add to Import List to add the data structures to the Import list. 60 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

69 Figure 4. Importing input or output message data structures 8. To complete your import, click Finish. 9. Click File > Sae to sae all of your imported metadata to the serer. Results In the IMS Explorer Transaction Message Editor, you can expand the elements under Input Messages and Output Messages to erify that the COBOL copybooks were properly imported to the respectie input and output messages. Chapter 4. Scenarios 61

70 Figure 5. Input and output messages defined Define the phonebook serice to the serer With the connection profile, interaction properties profile, and message metadata all defined, you are ready to define a serice for the phonebook application. About this task To define a serice, you specify a name for the serice and identify the following information that is associated with this serice: IMS transaction Interaction properties profile Connection profile The input fields and output fields that you want to expose. Procedure 1. In the IMS Serice Naigator iew, expand the serer that you created. 2. Right-click the Serices folder and click Create an IMS mobile transaction serice. 3. In the Serice name field, enter a name for the serice, such as Phonebook. 62 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

71 4. Click Browse next to the Transaction code field. The Specify Transaction Metadata 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 is automatically populated with a reference to your input message metadata <trancode> INPUT. The Output message is automatically populated with a 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 In the Connecton profile list, select the connection profile that you created in Step In the Transaction code oerride field, ensure that IVTNO is listed. This field lets you specify the transaction code to use at run time, oerriding the transaction code for the transaction message formats that are defined for a program. This option lets you define one set of transaction message formats for a gien program, but access the program through a REST serice by using potentially multiple transaction code alues at run time. For this phonebook application, 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 serice 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 alue to IVTNO. Tip: The transaction message metadata you created in the preious step can be of any name. Howeer, for this phonebook sample application to work, you must specify a default alue of IVTNO for the serice. 11. For output message, clear the check boxes for OUT_LL and OUT_ZZ. 12. Click Finish. 13. Verify that your Serices folder now contains your newly created serice in a subfolder. Results A folder with the name of your serice is now created under the Serices folder in the IMS Serice Naigator iew. Test the phonebook serice You will use IMS Explorer to create an IMS mobile transaction test case and run the serice. About this task For a quick test of a newly created serice, you can issue a PUT request in a web browser with the following URL: Chapter 4. Scenarios 63

72 You should see your serice listed among other serices in the response in JSON format: {"SericeName":"Phonebook","SericeDescription":"","SericeProider":"imsmobile-2.0", "SericeURL":" Next, you want to create a test case to test your phonebook serice. Creating and running a mobile test case allows you to more effectiely debug and refine your serice definition. Procedure 1. In the IMS Serice Naigator iew, under the Serices folder, right-click the serice you just created, such as Phonebook, and select Create a test case. 2. In the Create IMS Transaction Serice Test wizard, click New Project, enter a project name such as PhonebookTest in the Project name field, and click Next. 3. In the Serer name list, select the serer you used for this tutorial. 4. In the Serice name list, select the serice you created for this tutorial. 5. In the Testcase name field, enter PhonebookTest and click Finish. The test case editor opens. 6. Enter alues for the phonebook serice 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 alue (10 characters or fewer) for the last name, and then click OK. d. Double-click the IN_FIRST_NAME row and enter a field alue (10 characters or fewer) for first name, and click OK. e. Double-click the IN_EXTENSION row and enter a field alue (10 characters or fewer) for phone extension, and click OK. f. Double-click the IN_ZIP_CODE row and enter a zip code alue (7 characters or fewer), and click OK. 7. Click File > Sae. To run the test case: 8. In Project Explorer iew, 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. 64 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

73 Figure 6. The Edit Configuration wizard 10. In the Serer name list, select your serer 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 input message and data that you will use to make the serice request, and the bottom 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 serice. Results When the run completes, the OUT_MESSAGE in the Output Message section is populated with a response. Your phonebook serice was successfully tested if you see one of the following messages: ENTRY WAS ADDED ADDITION OF ENTRY HAS FAILED (this message indicates that the IN_LAST_NAME alue you specified already exists) The following output shows an entry was successfully added for John Doe. Chapter 4. Scenarios 65

74 Figure 7. Sample result of a test run If you receied an error about the transaction could not be executed with a DFS064 message from IMS, your transaction code is not specified correctly. Tutorial summary: You hae created a serice for the IMS phonebook application and tested the serice. In the first tutorial, you learned the following: How to create a serice by first defining a connection profile for connection with IMS Connect, an interaction properties profile that describes how to handle interactions with the transaction, and the message metadata (input and output message mapping) for the phonebook transaction. How to test a serice by creating a test case in IMS Explorer. Deelop an API to inoke an IMS serice Use the z/os Connect EE API Editor to deelop a REST API to inoke an IMS serice. API creation workflow The JSON schema of an IMS mobile serice is obtained from the serice archie (SAR) file, which is generated by IMS Explorer. You then use the z/os Connect EE 66 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

75 API Editor, to map an HTTP method to a serice, assign a alue to a field in the serice, remoe a field from the request or response message, and more. After the mapping is done, the API can be deployed to the serer and you can immediately test the API, all from within the API Editor. z/os Connect EE APAR PI62820 (V ) and the z/os Connect EE API Editor V or later are required for this function. IMS Explorer for Deelopment z/os Connect EE API Editor Serice archie (SAR) API archie (AAR) z/os Connect EE IMS Mobile feature Figure 8. Creating a REST API for an IMS mobile serice from the serice archie file Prerequisites Examine the operational requirements, considerations and restrictions to assist the planning and design of your mobile solution. The IMS serice must be created, deploying, and running properly. z/os Connect EE API Editor is downloaded and properly installed. z/os Connect EE API Editor can be downloaded from the Download Eclipse tools page on the mainframe deelopment site at mainframe/products/downloads/. The installation instructions are proided on the site. z/os Connect EE APAR PI62820 (V ) and the z/os Connect EE API Editor V or later are required. Updates of the z/os Connect EE serer might require a newer ersion of the editor. Check the Chapter 2, z/os Connect EE change history, on page 7 topic for any potential compatibility issues. API creation workflow for IMS mobile serices Implementation of an IMS mobile solution inoles the use of IMS Explorer for Deelopment (IMS Explorer) to create and publish necessary resources to the serer, including connection profiles, interaction profiles, transaction message metadata, and serice metadata. Creating the REST API for an IMS mobile serice inoles the following steps: 1. Use IMS Explorer to generate the serice archie (SAR) file that contains the information that the serer needs to install and proide the serice. 2. Create an API project in z/os Connect EE API Editor and import the serice archie into the project. 3. Create the API. a. Specify the path, query parameters, and HTTP methods. Chapter 4. Scenarios 67

76 b. Import the serice archie to load the serice 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 serice JSON schema. After the API is created and saed, you can deploy it to the serer from within the editor and test it in the embedded Swagger UI. Tutorial: Create a REST API for an IMS mobile serice You will create a REST API to interact with the IMS phonebook serice. Learning objecties You will learn the following concepts and steps to create a REST API for the phonebook serice you created in Tutorial: Create an IMS mobile serice on page 54. The concepts associated with REST API design. The process, the tool, and the artifacts that you need to create a REST API from a serice on the z/os Connect EE serer. How to deploy and test an API. Time required This tutorial should take approximately 90 minutes to finish. If you explore other concepts related to this tutorial, it could take longer to complete. Audience An API deeloper who is familiar with RESTful API design principles. Prerequisites A phonebook serice is properly created based on Tutorial: Create an IMS mobile serice on page 54. z/os Connect EE API Editor is downloaded and properly installed. You will need the serice archie (SAR) file that contains the information the serer needs to install and proide the serice. The serice archie is generated in IMS Explorer. Design the API for the serice When composing the API, first identify the resources that can be acted upon by the serice. Then plan the URI paths, the use of path or query parameters, and any requirements for input. About this task This API layer proides the ability to use HTTP erbs to imply the actions against a resource, as well as access to path and query parameters. For the phonebook serice, the resource is the contact record. The actions against the contact record are to add, display, update, and delete a contact record. Procedure 1. Identify which fields need to be aailable to accept input (request). 68 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

77 The following table identifies the fields in the phonebook serice that need to be exposed, hidden, or assigned a alue. It also demonstrates the API design thought process. Table 6. Input fields for the phonebook serice Input field Action Description IVTNO-INPUT-MSG Hide An "01" leel element for the record. IN-LL Hide Internal to the IMS transaction. No need to expose this field to the API. IN-ZZ Hide Internal to the IMS transaction. No need to expose this field to the API. IN-TRANCDE Assign The alue for this field must be the same as the defined transaction definition. This alue can be assigned only at the serice layer but not in the API. IN-COMMAND Expose The API must pass in this alue. The alues must be either ADD, DISPLAY, DELETE, or UPDATE. IN-LAST-NAME Expose The key field for the database. This alue must be unique. Therefore, this field must be exposed. IN-FIRST-NAME Expose This field is needed for ADD and UPDATE actions. 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 aailable for output (response). The following table identifies the fields that need to be made aailable in the response. Table 7. Output fields for the phonebook serice Output field Action Description IVTNO-OUTPUT-MSG Hide An "01" leel element for the record. OUT-LL Hide Internal to the IMS transaction. No need to expose this field to the API. OUT-ZZ Hide Internal to the IMS transaction. No need to expose this field to the API. OUT-MESSAGE Expose The message that indicates the result of the action. This field needs to be exposed to the API. OUT-COMMAND Expose This field will be made aailable to the API to be exposed to the client application if the API deelopers intend to do so. A potential use for this field is a simple erification of the command used to achiee the result. This can be hidden if you don't see a use case for it. OUT-LAST-NAME Expose This field will be made aailable to the API to be exposed to the end users. For all four actions, this fields should be displayed for the end users. Chapter 4. Scenarios 69

78 Table 7. Output fields for the phonebook serice (continued) Output field Action Description OUT-FIRST-NAME Expose This field will be made aailable to the API to be exposed to the client applications if the API deelopers intend to do so. For ADD, UPDATE and DISPLAY, this information can be useful for end user alidation purposes. For DELETE, this field has less alue and can be hidden 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 to expose 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 serice is the phonebook entry, or contact 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 alue 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 erb Path Add a contact POST /phonebook/contacts + JSON body The HTTP erb POST implies the action ("add"), so in the API mapping we will assign the alue ADD to the IN-COMMAND field. The JSON will carry in the four contact record alues: last name, first name, extension and zip code. Update a contact PUT /phonebook/contacts/{lastname} + JSON body The HTTP erb PUT implies the action ("update"), so in the API mapping we will assign the alue UPDATE to the IN-COMMAND field. The resource to act upon is specified as a path parameter, which will get mapped to the LAST-NAME field. The JSON will carry in the three other contact record alues: first name, extension and zip code. 70 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

79 Table 9. URI path planning (continued) Action HTTP erb Path Display a contact GET /phonebook/contacts/{lastname} The HTTP erb GET implies the action ("retriee" or "display"), so in the API mapping we will assign the alue DISPLAY to the IN-COMMAND field. The transaction supports the display of a single contact record, not a range. Delete a contact DELETE /phonebook/contacts/{lastname} The HTTP erb DELETE implies the action ("delete"), so in the API mapping we will assign the alue DELETE to the IN-COMMAND field. The transaction supports the delete of a single contact record, not a range. Therefore, we use a path parameter. The API will map this path parameter alue 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 Add a contact Update a contact Display a contact Delete a contact Fields to return OUT-MESSAGE: To indicate success or failure of the action. LAST-NAME, FIRST-NAME, EXTENSION, ZIP-CODE: To allow for alidation of the added contact record. The same as adding a contact. The same as adding a contact. OUT-MESSAGE: To indicate success or failure of the action. LAST-NAME: To allow for alidation of the deleted record. Results With the API design identified, you are ready to create the API. Generate a serice archie from an IMS transaction Generate a Serice Archie (SAR) file in IMS Explorer. This file is needed by the z/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 to enable the serice as a JSON asset. Procedure 1. Open IMS Explorer. 2. Ensure you are in the IMS Mobile perspectie. Chapter 4. Scenarios 71

80 3. In the IMS Serice Naigator iew, expand the z/os Connect EE Serers folder and then the Serices folder. 4. Right-click the phonebook serice you created in Tutorial: Create an IMS mobile serice on page 54 and select Export transaction serice archie. The Export Serice Archie dialog opens. 5. Select Local file system, and browse to the folder where you want to sae the serice archie file. Results A <serice_name>.sar file is saed in the location you specified. Create an API project Use the z/os Connect EE API Editor to create an API project and define the API name and base path. About this task You can create an API project and define the API in the z/os Connect Enterprise Edition perspectie. Procedure 1. 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 perspectie. a. From menu bar, select Window > Open Perspectie > Other. b. In the list of perspecties, select z/os Connect Enterprise Edition and click OK. You are now in the z/os Connect Enterprise Edition perspectie, with related iews and resources readily aailable. 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 sericee Project property Project name API name Base path Description Descripton Unique alphanumeric name for your project. This is the name of the project in Eclipse. The name of your API. This is the name by which the z/os Connect EE serer knows about this API. The unique basepath attribute that specifies the root of all the resources in this API. This path is used by REST clients in the URI they send in to inoke the API. Optional field to proide a description of this API for documentation purposes. Sample alue to specify phonebook contacts /phonebook This is an API for managing contacts. c. Click Finish. 72 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

81 Results The API project is created in the Project Explorer iew. The API package.xml file opens in the API Editor where you can model your API. Create the API Create the API by defining the API front end, associating the API with a serice, and mapping JSON request and response messages to the input and output messages of the IMS transaction as exposed in the serice. About this task In this step, you will import the serice archie file (a.sar file) for the phonebook serice into the API project you created in z/os Connect EE API Editor, and map the input and output messages for each HTTP erb (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 the serice on page 68. The path of the API is /<base_path>/<api_name>, and in this case, the path is /phonebook/contacts Table 12. URI path planning Action HTTP erb Path 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: /phonebook/contacts: This path is needed only by the POST action (ADD). /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 iew, right-click the phonebook folder (or your project name, if you use a different alue), and select z/os Connect EE > Import z/os Connect EE Serices. The Import z/os Connect EE Serices wizard opens. 2. Click File System to naigate to where the phonebook serice archie file is stored. Select the.sar file and click OK. For the POST erb to add contact information for a gien last name, in the next step you will: a. Define the path alue. 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 it does not need to be included. Chapter 4. Scenarios 73

82 Figure 9. Adding a path for the API For the POST action, we want to ADD a contact record, and therefore: IN_COMMAND needs to be assigned a alue of ADD. This field should be hidden from end users wheneer this API is called. 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 the alues. 4. Remoe the GET, PUT, and DELETE methods by clicking the remoe button ( ) next to these methods. You hae created the front end of your API. Now the API needs to be connected to the back-end application in IMS. To associate a serice with the API: 5. For the POST method, click Serice next to the method. The Select a z/os Connect EE Serice window opens. 6. Select the phonebook serice archie file you generated in an earlier step and click OK. 7. Sae your project by clicking File > Sae (or press Ctrl-S). Now map your API request to fields in the serice: 8. Click the Mapping button next to the POST method and select Open Request Mapping. If you hae not saed your project or latest changes, a dialog opens to prompt you to sae the package.xml file. Click OK to sae the changes, and the request mapping editor opens. 74 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

83 Figure 10. Request mapping for the POST method 9. Expand the IVTNO_INPUT_MSG section on the left by clicking the expand button ( ). The following image shows the expanded IVTNO_INPUT_MSG section. Figure 11. Request mapping for the POST method a. The right side of the interface (labeled with the letter "a") shows the fields that are exposed by the serice for the request. b. The upper left of the interface (labeled with the letter "b") shows fields that will be exposed through the API and made aailable to the REST clients. By default, it is a one-to-one mapping to the fields that are exposed by the serice unless you change the mapping. c. The lower left of the interface (labeled with the letter "c") shows the HTTP request, which can consist of one or more headers, path parameters, query parameters, and the request body. For the POST action, we want to ADD a contact record with the following goals: IN_COMMAND needs to be assigned a alue of ADD. This field should be hidden from end users wheneer this API is called. Chapter 4. Scenarios 75

84 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 the alues. We will achiee these goals in the next few steps. 10. Right-click the IN_COMMAND field in the serice definition (section A in Figure 3, and select Add Assign transform. An Assign box shows up in the middle. 11. Click the Assign box, and the Transform - Assign properties iew opens. 12. In the Value field, enter ADD, and leae the Omit from interface checkbox checked to exclude this alue from the Swagger document so it is not exposed in the API. Figure 12. Assigning a fixed alue to the IN_COMMAND field 13. Click File > Sae (or press Ctrl-S) to sae your mapping. 14. Close the request mapping tab. You hae defined how the request message should be mapped. You will now define 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_COMMAND back to the user, so we need to remoe it by right-clicking OUT_COMMAND and select Add Remoe transform. 76 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

85 Figure 13. Remoing a field from the response messasge 17. Click File > Sae (or press Ctrl-S) to sae your mapping. 18. Close the response mapping tab. Results You hae defined the POST method to add a contact record and how the request and response messages are mapped to the data fields in the serice. The next step is 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 and test the API if you already understand how the API design and deelopment process works. (Optional) Create the API, part 2 Define another path and data mapping for the PUT, GET, and DELETE erbs. You can skip this step and proceed directly to deploy and test the API if you already understand how the API design and deelopment process works. About this task In this step, you will define a new path, /phonebook/contacts/{lastname}, and the data mapping for the associated PUT, GET, and DELETE erbs. Table 13. Output for the display and delete actions Action HTTP Verb Fields to return Display a contact GET IN-COMMAND to be assigned a alue of DISPLAY. Fields to return: OUT-MESSAGE: To indicate success or failure of the action. LAST-NAME, FIRST-NAME, EXTENSION, ZIP-CODE LAST-NAME, FIRST-NAME, EXTENSION, and ZIP-CODE. Chapter 4. Scenarios 77

86 Table 13. Output for the display and delete actions (continued) Action HTTP Verb Fields to return Update a contact PUT IN-COMMAND to be assigned a alue of UPDATE. Fields to return: OUT-MESSAGE: To indicate success or failure of the action. LAST-NAME, FIRST-NAME, EXTENSION, ZIP-CODE: To allow for alidation of the updated contact record. Delete a contact DELETE IN-COMMAND to be assigned a alue of DELETE. Fields to return: OUT-MESSAGE: To indicate success or failure of the action. LAST-NAME: To allow for alidation of the deleted record. Procedure To display, update, or delete a contact record for a gien last name, define the path alue 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. Figure 14. Adding another path for the API 2. Enter the API path and the path parameter, lastname, enclosed in curly brackets. In this case, it is /contacts/{lastname} 3. Remoe the POST method by clicking the remoe button ( ) next to the method. The GET method For the GET method (querying a contact record by last name), map the data structure between the serice JSON schema and the HTTP request and response messages. 78 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

87 4. For the GET method, click Serice next to the method, select the phonebook serice archie file, and click OK. 5. Click File > Sae or press Ctrl-S to sae the serice association. 6. Click Mapping next to the GET method and select Open Request Mapping. 7. Right-click the IN_COMMAND field in the serice definition on the right, and select Add Assign transform. An Assign box shows up in the middle. 8. Click the Assign box, and the Transform - Assign properties iew opens. 9. For the Value field, enter DISPLAY. 10. Because only the last name is needed for the request and the other fields are not needed, remoe 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 Remoe transform. Figure 15. Remoing unneeded fields from the requests The last step is to map the path parameter lastname from the HTTP Request section to the IN_LAST_NAME field. Tip: You can right-click the field to undo an action, or right-click the added action button to delete the action. 11. Click and drag the lastname path parameter field in the HTTP Request section to the IN_LAST_NAME field on the right. Chapter 4. Scenarios 79

88 Figure 16. Mapping the lastname path parameter to the IN_LAST_NAME field No JSON body is sent in with this request. All the information needed to display a contact record is carried in on the URI with the path parameter. 12. Click File > Sae (Ctrl-S) to sae your request mapping. 13. Close the request mapping tab. The next step is to map the response. For the gien last name, we want to return all fields except the OUT_COMMAND field, so we need to remoe this field 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 Remoe transform. Figure 17. Remoing the OUT_COMMAND field from the response 16. Click File > Sae (Ctrl-S) to sae your response mapping and close the response tab. 80 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

89 The PUT method For the PUT method (updating a record), the request and response mapping is similar to the GET method. The key tasks are as follows: Assign a serice that is associated with this method. Assign a static alue to the IN_COMMAND field. The command to update a record in the phonebook application is UPDATE, so set the static alue to UPDATE. The lastname path parameter is the key and its alue needs to be moed to the IN_LAST_NAME field. The IN_FIRST_NAME, IN_EXTENSION and IN_ZIP_CODE fields need to be exposed 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: Figure 18. Request mapping for the PUT method 18. Sae your changes. 19. Close the request tab. Next map the response message. All fields should be returned to allow users to alidate their updates. 20. Map the response for the PUT method as follows: Figure 19. Response mapping for the PUT method 21. Sae your changes and close the response tab. Chapter 4. Scenarios 81

90 Tip: With this mapping design, if only the extension for a specified last name is proided in the request message, the first name and zip code fields will be updated as blank. Ensuring that field alues are not incorrectly wiped out would be the responsibility of the mobile application deeloper. The DELETE method For the DELETE method (deleting a record), the key mapping tasks are as follows: Assign the serice that is associated with this method and sae Assign a static alue to the IN_COMMAND field. In this case, the command to delete a record in the phonebook application is DELETE, so set the alue to DELETE. The lastname path parameter is the key and its alue needs to be moed to the IN_LAST_NAME field. No fields need to be exposed in the request, so IN_EXTENSION, IN_FIRST_NAME, and IN_ZIP_CODE should be remoed. 22. Map the request for the DELETE method so the mapping looks as follows: Figure 20. Request mapping for the DELETE method 23. Sae your changes and close the request tab. Next map the response message. For a delete operation, all we are interested in is whether the action succeeded. This information is indicated in OUT_MESSAGE. We can remoe all fields, except OUT_MESSAGE, should be remoed. 24. Map the response for the DELETE request as follows: 82 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

91 Figure 21. Response mapping for the DELETE method 25. Sae your changes and close the response tab. Results The API is now completed. Deploy the API Deploy the API directly from z/os Connect EE API Editor by first creating a connection to the serer. About this task In this step, you will first create a connection to the z/os Connect EE and then deploy the API to the serer. Tip: Starting from this step, you must hae z/os Connect EE V (APAR PI62820) and z/os Connect EE API Editor V or later. Procedure 1. In the Host Connections iew, click Add and select z/os Connect Enterprise Edition. 2. Specify the following information for your enironment: Table 14. Adding a serer connection Field Name Host name Port number Description A descriptie name for the serer connection. The name or the IP address of the serer. The port number. Select the Secure connection (TLS/SSL) checkbox for secure connections. 3. Click Sae and Connect to sae the definition and connect to the serer. You will be prompted to either specify an existing credential to use, or create a credential at this time. 4. After you select an existing credential or create a new one, click OK to use the credential to connect. The defined host connection shows up in the z/os Chapter 4. Scenarios 83

92 Connect EE Serers iew. Deployed API packages are listed under the APIs folder. To deploy your API: 5. In the Project Explorer iew, right-click your API project and select z/os Connect EE > Deploy API to z/os Connect EE Serer. 6. In the Deploy API window, select the serer 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 API You can test your API directly from z/os Connect EE API Editor by using the "Try it 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, you can proide alues for the exposed fields (as parameters) to test the API and examine the associated request URL, request headers, response body, response code, and response headers. Procedure To test your API: 1. In the z/os Connect EE Serers iew under the APIs folder, double-click your API. The API is opened in the Swagger UI. 2. Click List Operations to see aailable operations in the API. Figure 22. 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. 84 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

93 Figure 23. Operations in the API c. Click Try it out!. Information about the request URL, request headers, response body, response code, and response headers are proided. The response body contains the output message. The OUT_MESSAGE would contain one of the following messages: ENTRY WAS ADDED ADDITION OF ENTRY HAS FAILED (this message indicates that the IN_LAST_NAME alue you specified already exists) 4. Proceed to test other methods and examine the results. Results You hae created, deployed, and tested the API. Tutorial summary: You hae completed the tutorial for creating and deploying an API for an IMS mobile serice. You learned the following: The concepts associated with REST API design. The process, the tool, and the artifacts that you need to create a REST API from a serice on the z/os Connect EE serer. How to deploy and test an API. Configure an HA enironment that uses the WOLA serice proider Using this scenario, you can configure a highly aailable z/os Connect EE enironment that uses the WOLA serice proider to connect to CICS Transaction Serer. This scenario uses two z/os Connect EE serers with shared configuration, API packages, WSBind files, and JSON schemas, and uses TCP/IP port sharing to distribute requests across the serers. This scenario uses the API and serices that were deeloped in the scenario Deelop an API to inoke a CICS serice ia WOLA on page 17 to start the Chapter 4. Scenarios 85

94 CICS Catalog Manager, a sample application proided by CICS Transaction Serer. A serer template is proided which creates a serer that is preconfigured with the API and serices for this scenario. This template includes the API package and serice artifacts. Note: For more information about the concepts of high aailability and the options you can choose, see Chapter 7, High aailability, on page 167. This scenario shows you how to configure a simple z/os Connect EE HA enironment for a single z/os LPAR. The configured enironment has the following characteristics: Two z/os Connect EE serers with workload that is distributed to them using TCP/IP port sharing with WLM. Two CICS Transaction Serer regions. Each z/os Connect EE serer is configured to use WOLA to connect to a single CICS Transaction Serer region. Serer configuration files, API packages, WSBind files, and JSON schemas are shared between the two z/os Connect EE serers to maintain a consistent configuration between serers. To simplify setting up and testing the HA enironment the following configuration choices are used, which are not common for a production enironment: Polling of the serer configuration file is enabled. Polling allows the serers to automatically pick up configuration changes as the scenario progresses, without the need to restart the serer or inoke the FileNotificationMbean. In production, it is more common to disable polling to aoid unnecessary CPU usage when monitoring a typically static file. HTTPS is not used, and HTTP examples are used throughout the scenario. This scenario is focused on the specific HA configuration, rather than security, so using only HTTP aoids the need to create and configure certificates to secure connections. If HTTPS is required in your enironment, then you can follow the same steps, but you must enable, configure, and share the HTTPS port and configure the client application for HTTPS when you test this scenario. This scenario uses the following alues: Table 15. Values used in this scenario Description z/os LPAR host name z/os Connect serer 1 serer name z/os Connect serer 2 serer name z/os Connect serer Started Task procedure name z/os Connect serer 1 Started Task job name z/os Connect serer 2 Started Task job name Value companyhost.company.com haserer1 haserer2 BAQSTRT ZCHA1 ZCHA2 z/os Connect serers shared HTTP port Prerequisites These requirements are needed to run this scenario. 86 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

95 Before you create a high aailability enironment, you must first create the supporting infrastructure. This includes a single z/os Connect EE serer that uses WOLA to connect to CICS as shown in Figure 1. When this configuration is complete, you can then create the high aailability enironment. Figure 24. A single serer enironment Software requirements z/os Connect Enterprise Edition installed and zconsetup install command run CICS Transaction Serer 4.2 or later installed and two running CICS regions. Prerequisite tasks You need to complete the following tasks to proide the infrastructure that is needed by the scenario. 1. Install z/os Connect EE. For more information, see Chapter 5, Installation information, on page Configure a started task to run a z/os Connect EE serer. 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 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: 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 EE serers on page Configure the Liberty angel process as described in Configuring the Liberty angel process and z/os authorized serices on page 185. The angel process is required by WOLA to access z/os authorized serices. 4. In the following tasks, you configure your initial enironment for a single z/os Connect EE serer to connect to a single CICS region using WOLA. Configuring the CICS Catalog Manager example application To run this scenario, you need to install and configure the CICS Catalog Manager example application. Chapter 4. Scenarios 87

96 About this task This scenario uses the CICS Catalog Manager sample application as an example of an existing CICS application to be exposed as an API. This application must be installed and configured in both your target CICS regions. If this application is not yet configured, follow this procedure. For more information, see The CICS catalog manager example application in the CICS Transaction Serer documentation. Procedure 1. Install and configure the CICS Catalog Manager example application. Follow the steps in Installing and setting up the base application. For the configuration step, enter the transaction ECFG on a CICS terminal to start the configuration application. Update the following alues to use a VSAM Datastore and the stubbed ersion of the Order Dispatcher: CONFIGURE CICS EXAMPLE CATALOG APPLICATION Datastore Type ==> VSAM Outbound WebSerice? ==> NO Catalog Manager ==> DFH0XCMN Data Store Stub ==> Data Store VSAM ==> DFH0XVDS Order Dispatch Stub ==> DFH0XSOD Order Dispatch WebSerice ==> Stock Manager ==> DFH0XSSM VSAM File Name ==> EXMPCAT Serer Address and Port ==> Outbound WebSerice URI ==> STUB VSAM YES NO 2. Test that the application is installed and configured correctly. Follow the instructions in Running the example application with the BMS interface. Results The sample application is now configured on CICS and can be run by using the BMS interface. Follow the remaining steps to access this application from z/os Connect EE. Configuring CICS to use WOLA Configure the example CICS application and configure both CICS and SAF to use WOLA. Before you begin Complete the tasks in Prerequisites on page 86 and Configuring the CICS Catalog Manager example application on page 87. About this task Configure CICS to use WebSphere Optimized Local Adapters (WOLA). WOLA is the serice proider that allows z/os Connect EE requests to interact with z/os assets. Procedure Follow the instructions in Configuring CICS to use WebSphere optimized local adapters (WOLA) on page 124. This scenario uses the following alues: 88 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

97 Table 16. Values used in this scenario 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 alues. For example, if you are using RACF, choose one of these options: 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) To use wildcards, and create only a single definition, enter the following commands: RDEF CBIND BBG.WOLA.* UACC(NONE) PERMIT BBG.WOLA.* CLASS(CBIND) ACCESS(READ) ID(CICSID) Use your own alues. If you choose this option, ensure that you use the same alues in the corresponding steps later in the scenario. You must create a unique definition for each serer. Creating the initial serer Create a z/os Connect EE serer from a template and configure CICS to use WOLA. About this task You create an initial z/os Connect EE serer, and then copy the configuration to create multiple serers for an HA enironment. Procedure 1. Change to the <installation_dir>/bin directory. For example, /usr/lpp/ibm/zosconnect/2r0/bin. 2. Enter the following command. zosconnect create haserer1 --template=zosconnect:samplewolacatalogmanager This command creates a serer that is named haserer1 by using the samplewolacatalogmanager template. This template creates a serer with an API and three serices that are configured to call the catalog manager CICS application that uses WOLA. The serer is created in the <WLP_USER_DIR>/ serers directory. 3. Start the z/os Connect EE serer. To presere the case of your serer name, you must start the serer from the System Command Extension window within SDSF. From SDSF, type / to open the extended console, then enter the command: S BAQSTRT,JOBNAME=ZCHA1,PARMS= haserer1 clean a. Check the serer's message log file in <WLP_USER_DIR>/serers/ {serername}/logs/messages.log. The following messages appear: Chapter 4. Scenarios 89

98 CWWKB0103I: Authorized serice group LOCALCOM is aailable. CWWKB0103I: Authorized serice group WOLA is aailable.... CWWKB0501I: The WebSphere Optimized Local Adapter channel registered with the Liberty profile serer with the following nam ZC1DGN ZC1NDN ZC1SVN... J2CA7001I: Resource adapter wola installed in seconds. Where: If the LOCALCOM serice group is aailable, then the angel is running and your Liberty Serer ID has READ access to that SERVER profile. If the WOLA serice group is aailable, then the configuration was completed successfully. The CWWKB0501I message is showing the successful use of the WOLA three part name alues you proided in the serer.xml file. This message indicates that an external address space might register into the Liberty Profile serer by using this three-part name on the BBOA1REG API. The J2CA7001I message indicates that the WOLA JCA resource adapter is aailable. 4. Ensure that the CICS region is started 5. Start the TRUE and Link Serer task from CICS, and register with WOLA. The z/os Connect Enterprise Edition serer 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 serer task and register to your serer: BBOC START_SRVR RGN=CICSREG DGN=ZC1DGN NDN=ZC1NDN SVN=ZC1SVN SVC=* TXN=N REU=Y The following message indicates success: WOLA TRACE 0: Start serer 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 topic Optimized local adapters for z/os APIs in the WebSphere Application Serer z/os documentation. Go to the Register section (also known as the BBOA1REG section) and look for the RC and RSN code that is proided there. 6. From a web browser, enter an HTTP GET request to list all the installed z/os Connect Enterprise Edition APIs: name>:<port>/zosconnect/apis For example: If your API is installed correctly, the following response is receied: 90 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

99 { "apis": [ { "name": "catalog", "ersion": "1.0.0", "description": "API for the CICS catalog manager example application", "adminurl": " } ] } 7. From a web browser, enter an HTTP GET request to call the API to inquire on a single catalog item: Where catalogmanager is the base path alue that is defined in the API definition 9080 is the HTTP port the z/os Connect EE serer uses to listen for HTTP requests. items is the path that is defined in the API for inquiring on a single catalog item 10 is the runtime alue for the path parameter alue {itemid}. If your API request is successful, the following response is receied: { "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 enironment. Setting up HA for the first serer Modify an existing serer to prepare it for a HA enironment. In this step, you modify the configuration of the existing z/os Connect EE serer in preparation to add the second serer. You must make the following modifications: Create a shared TCP/IP port. Split the serer configuration file into content that can be shared between serers and that which is serer-specific. Moe the API and serice artifacts to a shared location. Setting up TCP/IP port sharing Set up port sharing so the z/os Connect EE serers in the HA enironment can listen on the same port. Chapter 4. Scenarios 91

100 Procedure 1. Choose an unresered port number to be used for the serers' HTTP listeners. This scenario uses port as an example, but it can be changed if it is already in use in your enironment. To display ports that are currently resered on a single TCP/IP stack, use one of the following methods: Enter the following SDSF command, where procname is the name of the TCP/IP stack: /D TCPIP,<procname>,N,PORTL Enter the UNIX System Serices 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 serer is listening on. In this scenario, port was chosen, with started task job names that start with ZCHA and the SHAREPORTWLM option to allow WLM to manage the incoming workload. The shared port definition in the TCP/IP port profile is as follows. PORT 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,,OBEYFILE command in the z/os Communications Serer: IP System Administrator's Commands documentation. 3. Confirm that the shared port is actie. To display ports that are currently resered on a single TCPIP stack, use one of the following methods. Enter the following SDSF command, where procname is the name of the TCP/IP stack: /D TCPIP,<procname>,N,PORTL Enter the UNIX System Serices command: netstat o The output includes the port number with a FLAGS alue of DASW: PORT# PROT USER FLAGS RANGE SAF NAME TCP ZCHA* DASW SW indicates that the port is shared and that the port uses WLM serer-specific recommendations. 4. Update the existing httpendpoint element in serer.xml to use the shared port. For example, <httpendpoint id="defaulthttpendpoint" host="*" httpport="11111" httpsport="-1" /> Creating a shared configuration file Serers in an HA enironment share common elements of the configuration file. 92 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

101 About this task To ensure that both serers in the HA enironment can handle the same workload, some elements from the serer.xml file for each serer are shared from a common configuration file. Configuration elements that are unique to a serer are defined in a separate serer.xml file. Procedure 1. Create directories under /ar/zosconnect to store the shared configuration file. For example, run the following command from the /ar/zosconnect directory. mkdir p shared/config 2. Moe the current serer.xml file that is used by haserer1 to the shared configuration directory and rename it to haserer.xml. For example, run the following command as a single line: m /ar/zosconnect/serers/haserer1/serer.xml /ar/zosconnect/shared/config/haserer.xml 3. Create a file named serer.xml for haserer1 in the /ar/zosconnect/serers/ haserer1 directory with the following elements: <?xml ersion="1.0" encoding="utf-8"?> <serer description="z/os Connect EE HA serer1"> <include location="${shared.config.dir}/haserer.xml"/> </serer> This configuration file includes the shared haserer.xml by using the Liberty property ${shared.config.dir} to reference the directory that contains the shared configuration files. This property points to the directory WLP_USER_DIR/shared/ config. 4. Moe configuration elements that are unique for each serer to the specific serer serer.xml file. For this scenario, the only element that must be unique is the three-part WOLA group name, which identifies the Liberty serer for WOLA connections. Remoe the zoslocaladapters element from /ar/zosconnect/shared/config/haserer.xml and add it to /ar/zosconnect/haserer1/serer.xml. <!-- Local adapters config --> <zoslocaladapters wolagroup="zc1dgn" wolaname2="zc1ndn" wolaname3="zc1svn" /> Setting up shared resources Moe the API and serice artifacts to a shared location so they can be accessed by both serers. About this task To ensure that workload distribution can route requests to any of the z/os Connect EE serers that are aailable in a port shared group, the serers must hae the same APIs and serices aailable. For more information, see Sharing serer configuration on page 170. Procedure 1. Create directories under /ar/zosconnect to store the API package, WSBind files, and JSON schemas. Run the following command from the /ar/zosconnect/shared directory: mkdir p resources/zosconnect/apis resources/zosconnect/serices Chapter 4. Scenarios 93

102 2. Moe your API.aar files to /ar/zosconnect/shared/resources/zosconnect/ apis Enter the following command on a single line: m /ar/zosconnect/serers/haserer1/resources/zosconnect/apis/*.aar /ar/zosconnect/shared/resources/zosconnect/apis 3. Moe your WSBind files and JSON schemas to /ar/zosconnect/shared/ resources/serices Enter the following commands, on single lines: m /ar/zosconnect/serers/haserer1/resources/zosconnect/serices/*.wsbind /ar/zosconnect/shared/resources/zosconnect/serices m /ar/zosconnect/serers/haserer1/resources/zosconnect/serices/*.json /ar/zosconnect/shared/resources/zosconnect/serices 4. In /ar/zosconnect/shared/config/haserer.xml, update the zosconnect_zosconnectdataxform element to point to the new serices artifact location. Change the bindfileloc, requestschemaloc, and responseschemaloc attributes to ${shared.resource.dir}/zosconnect/serices. For example, <zosconnect_zosconnectdataxform id="xformjson2byte" bindfileloc="${shared.resource.dir}/zosconnect/serices" bindfilesuffix=".wsbind" requestschemaloc="${shared.resource.dir}/zosconnect/serices" responseschemaloc="${shared.resource.dir}/zosconnect/serices" requestschemasuffix=".json" responseschemasuffix=".json"/> 5. Update the zosconnect_zosconnectapis element to configure the shared API location ${shared.resource.dir}/zosconnect/apis. For example, <zosconnect_zosconnectapis location="${shared.resource.dir}/zosconnect/apis" updatetrigger="polled" /> 6. Restart the serer for the new API location to take effect. From SDSF enter the following command to stop the serer, /P ZCHA1 From SDSF, type / to open the extended console, then enter the command: S BAQSTRT,JOBNAME=ZCHA1,PARMS= haserer1 clean Results The HA enironment is now set up for the first serer. Adding a second serer Add a second serer to the HA enironment. Procedure 1. Run the zosconnect create command to create the second serer. The configuration from the first serer is copied across for the second serer in a later step so no template is required now. Run the following command from the <installation_dir>/bin directory. For example, /usr/lpp/ibm/zosconnect/ 2r0/bin. zosconnect create haserer2 94 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

103 2. Replace the default Liberty serer.xml file with the serer.xml file from haserer1. Run the following command: cp /ar/zosconnect/serers/haserer1/serer.xml /ar/zosconnect/serers/haserer2 3. Update the second serer configuration in /ar/zosconnect/serers/ haserer2/serer.xml so that the three-part WOLA group name is unique for each z/os Connect EE serer in the LPAR. Change the following attributes of the zoslocaladapters element: <!-- Local adapters config --> <zoslocaladapters wolagroup="zc2dgn" wolaname2="zc2ndn" wolaname3="zc2svn" /> 4. Start the z/os Connect EE serer. To presere the case of your serer name, you must start the serer from the System Command Extension window within SDSF. From SDSF, type / to open the extended console, then enter the command: S BAQSTRT,JOBNAME=ZCHA2,parms='haserer2 --clean' a. Check the serer's message log file in <WLP_USER_DIR>/serers/ {serername}/logs/messages.log. The following messages appear: CWWKB0103I: Authorized serice group LOCALCOM is aailable. CWWKB0103I: Authorized serice group WOLA is aailable.... CWWKB0501I: The WebSphere Optimized Local Adapter channel registered with the Liberty profile serer with the following name: ZC2DGN ZC2NDN ZC2SVN... J2CA7001I: Resource adapter wola installed in seconds. Where: If the LOCALCOM serice group is aailable, then the angel is running and your Liberty Serer ID has READ access to that SERVER profile. If the WOLA serice group is aailable, then the configuration was completed successfully. The CWWKB0501I message is showing the successful use of the WOLA three part name alues you proided in the serer.xml file. This message indicates that an external address space might register into the Liberty Profile serer by using this three-part name on the BBOA1REG API. The J2CA7001I message indicates that the WOLA JCA resource adapter is aailable. 5. Ensure that the second CICS region is started 6. Start the TRUE and Link Serer task from CICS, and register with WOLA. The z/os Connect Enterprise Edition serer must be running. a. Open a session with the second 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 serer task and register to your serer: BBOC START_SRVR RGN=CICSREG DGN=ZC2DGN NDN=ZC2NDN SVN=ZC2SVN SVC=* TXN=N REU=Y The following message indicates success: Chapter 4. Scenarios 95

104 WOLA TRACE 0: Start serer 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 topic Optimized local adapters for z/os APIs in the WebSphere Application Serer z/os documentation. Go to the Register section (also known as the BBOA1REG section) and look for the RC and RSN code that is proided there. Testing the scenario Test the HA configuration and alidate that it is distributing work across both serers. About this task To confirm that the HTTP requests are distributed to both z/os Connect EE serers in turn, the usage count of the Catalog Manager program DFH0XCMN in each region is checked. Therefore, this count is checked before and after each request to determine which CICS region and which z/os Connect EE serer processed the request. You can test this scenario from both a web browser and the command line tool curl. curl is an open source command line tool and library for transferring data with URL syntax. It is supported on many operating systems. For more information about curl, see the website Note: Persistent HTTP connections from a client can result in multiple requests that are sent to the same serer, rather than being distributed across the HA enironment. Persistent connections are a good practice, as it improes performance by not creating a new connection for eery request, but it can falsely indicate that workload is not being distributed correctly by TCP/IP port sharing. To preent a web browser from using the same connection, you can use a priate browsing mode, common in most modern browsers, for the second connection. Procedure 1. 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 a note of the alues 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. If you are using a web browser, enter an HTTP GET request to If you are using curl, enter the command: curl -G 96 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

105 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":13 2,"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 one region only. 4. Send a second HTTP GET request to call the API and get item 10 from the catalog. If you are using a web browser, open a priate browsing window to establish a new HTTP connection. In the second priate window, issue an HTTP GET request to If you are using curl, the connection is not persistent, so enter the same command from step 2: curl -G 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":13 2,"ca_sngl_description":"Ball Pens Black 24pk","ca_sngl_cost":"002.90","ca_sngl_department":10,"on_sngl_order":0}}}} 5. Check that the usage count was incremented by 1 on the other CICS region. Results Your HA enironment is now set up. You can add more serers by repeating the steps in Adding a second serer on page 94 Further capabilities of the HA scenario When you hae completed the HA scenario, you can try these tasks to make yourself more familiar with the alue and capabilities of High Aailability. Adding an API You can use the shared API location directory and configuration files to deploy a new API and associated configuration to all serers in the HA enironment. Before you begin Clear the SMF data sets. The method that you use depends on how your SMF data sets are configured. If unsure, contact your system programmer. About this task To demonstrate the adantages of sharing a configuration between serers in a HA enironment, this task shows you how to add an API to the shared API location, update serer.xml to configure an interceptor for the new API, and check that both serers picked up the changes. The serer.xml configuration file is updated first to ensure that the interceptor is configured when the API starts. The new API is called catalogbrowser and is a cut down ersion of the catalog API, with only the operations to get the list of items and query indiidual items. This method simplifies the steps so the existing serices and CICS programs can be reused. The audit interceptor is used to write an SMF 123 subtype 1 record each time the catalogbrowser API is called, but not for the catalog API. Chapter 4. Scenarios 97

106 Procedure 1. Configure an audit interceptor by adding zosconnect_auditinterceptor and zosconnect_zosconnectinterceptors elements to the shared configuration file /ar/zosconnect/shared/config/haserer.xml. For example, <zosconnect_zosconnectinterceptors id="auditinterceptorlist" interceptorref="auditinterceptor" /> <zosconnect_auditinterceptor id="auditinterceptor"/> 2. Update the zosconnect_zosconnectapis element in the shared configuration file /ar/zosconnect/shared/config/haserer.xml to configure the audit interceptor 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 /ar/zosconnect/shared/resources/zosconnect/apis. Enter the following command on one line. Replace <installation_path> with the fully qualified installation path of z/os Connect EE. cp <installation_path>/samples/scenarios/hawola/catalogbrowser.aar /ar/zosconnect/shared/resources/zosconnect/apis 4. Check the message log file for each serer in /ar/zosconnect/serers/ <serername>/logs/messages.log for the following messages: CWWKG0016I: Starting serer configuration update. CWWKG0028A: Processing included configuration resource: /ar/zosconnect/shared/config/haserer.xml BAQR7008W: z/os Connect API catalogbrowser could not be installed. CWWKG0017I: The serer configuration was successfully updated in seconds. BAQR7000I: z/os Connect API package catalogbrowser installed successfully. The BAQR7008W warning message occurred because the API was not deployed to the API location, but was added to the serer configuration file. The BAQR7000I information message indicates that the API was successfully installed after it was deployed to the API location. 5. Send an HTTP GET request to call the catalog API and get item 10 from the catalog. If you are using a web browser, enter an HTTP GET request to the catalog API: If you are using curl, enter the command: curl -G 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":13 2,"ca_sngl_description":"Ball Pens Black 24pk","ca_sngl_cost":"002.90","ca_sngl_department":10,"on_sngl_order":0}}}} 6. The audit interceptor is not configured for the catalog API, so check that no SMF 123 subtype 1 records were written: 98 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

107 a. Obtain the SMF data. The method that you use depends on your SMF configuration. If unsure, contact your system programmer. Information about using the z/os IFASMFDP program to dump the SMF data to a file is described in Running the SMF data set dump program. You can also configure 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 1 records exist. 7. Send an HTTP GET request to call the catalogbrowser API and get item 10 from the catalog. If you are using a web browser, enter an HTTP GET request to If you are using curl, enter the command: curl -G 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":13 2,"ca_sngl_description":"Ball Pens Black 24pk","ca_sngl_cost":"002.90","ca_sngl_department":10,"on_sngl_order":0}}}} 8. Send a second HTTP GET request to call the catalogbrowser API and get item 10 from the catalog. If you are using a web browser, open a priate browsing window to establish a new HTTP connection. In the second priate window, issue an HTTP GET request to If you are using curl, the connection is not persistent, so enter the same command from step 7: curl -G 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":13 2,"ca_sngl_description":"Ball Pens Black 24pk","ca_sngl_cost":"002.90","ca_sngl_department":10,"on_sngl_order":0}}}} 9. The audit interceptor is configured for the catalogbrowser API, so check that SMF 123 subtype 1 records were written and that calls were made to both z/os Connect EE serers. Two HTTP GET requests were issued so look for two SMF 123 subtype 1 records, one to each serer. 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 serer each request went to, format the serer identification section of the SMF 123 subtype 1 records. Use the z/os ICETOOL utility to iew the SMF data. Sample JCL to run this utility can be found in <installation_path>/jcl/baqs123.jcl. d. The JOBNAME in the formatted output indicates which z/os Connect EE serer receied the request. Chapter 4. Scenarios 99

108 Adding a second httpendpoint You can define an additional httpendpoint to allow the RESTful administration interface to be used to target operation requests at a specific serer. About this task Use these instructions to configure an additional httpendpoint and then perform operations on APIs in one serer by using the RESTful administration interface. Note: For the purposes of this scenario, an HTTP only example is used to focus on the specific HA configuration, rather than security. For information about using SSL to restrict access to this additional httpendpoint, see Management of z/os Connect EE APIs and serices in an HA enironment on page 173. z/os Connect EE proides a RESTful administration interface, which can be used to list installed APIs, details of those APIs and perform operations such as starting or stopping APIs. This interface uses the HTTP or HTTPS ports that are defined on an httpendpoint element in the z/os Connect EE serer's configuration file. For more information, see Using the RESTful administration interface on page 235. In the highly aailable enironment that is configured in this scenario, only a single HTTP endpoint that is shared by the z/os Connect EE serers is configured. Administration or operation requests cannot be targeted at a specific serer unless you configure a second httpendpoint element in each serer's specific configuration file to specify an additional HTTP port alue that is unique for each serer. This scenario uses the following alues: Table 17. Values used in this scenario Description Value z/os Connect EE serer 1 operations port z/os Connect EE serer 2 operations port Procedure 1. Update the serer-specific configuration files to add the additional httpendpoint. a. Add the following entry to the first serer's configuration file /ar/zosconnect/serers/haserer1/serer.xml: <!-- httpendpoint for RESTful administration interface on a per serer basis --> <httpendpoint id="operationshttpendpoint" host="*" httpport="19080" httpsport="-1" /> b. Add the following entry to the second serer's configuration file /ar/zosconnect/serers/haserer2/serer.xml: <!-- httpendpoint for RESTful administration interface on a per serer basis --> <httpendpoint id="operationshttpendpoint" host="*" httpport="29080" httpsport="-1" /> The RESTful administration interface is used to erify that the operation requests complete successfully to a specific serer. 100 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

109 In the following steps, the HTTP GET requests can be made in any browser. The HTTP PUT request requires the use of a browser with a REST Client browser plug-in. 2. From a web browser, enter an HTTP GET request to display details of the catalog API in serer haserer1. If your request is successful, the HTTP response contains details of the catalog API in serer haserer1, as follows: { "name": "catalog", "ersion": "1.0.0", "description": "", "status": "Started", "apiurl": " "documentation": { "swagger": " } } Notice that the status alue is Started. 3. From a web browser, enter an HTTP GET request to display details of the catalog API in serer haserer2. Enter the following request: If your request is successful, the HTTP response contains details of the catalog API in serer haserer2. The output is the same as the output from step 1, except for the port alue in the apiurl and swagger alues because both serers share an API location directory with the same API installed. 4. From a web browser, enter an HTTP PUT request to stop the catalog API in serer haserer1. Enter the following request: If your request is successful, the HTTP response contains the details of the catalog API in haserer1 after the stop request is performed: { "name": "catalog", "ersion": "1.0.0", "description": "", "status": "Stopped", "apiurl": " "documentation": { "swagger": " } } Notice that the status alue is Stopped. 5. Repeat step 2 to display details of the catalog API in serer haserer2. If your request is successful, the HTTP response contains details of the catalog API in serer haserer2. The status is still Started because the API is only stopped in serer haserer1. 6. Flow two requests to get item 10 from the catalog. The instructions for how to flow two requests are described in the scenario, Configure an HA enironment that uses the WOLA serer proider, topic Testing the scenario on page 96. The request to haserer2 where the API is running still works. The request to haserer1 where the API is stopped fails with the error message Chapter 4. Scenarios 101

110 BAQR7023E: The API is stopped. 7. From a web browser, enter an HTTP PUT request to start the catalog API in serer haserer1: If your request is successful, the HTTP response contains the details of the catalog API in haserer1 after the start request is performed, as follows: { "name": "catalog", "ersion": "1.0.0", "description": "", "status": "Started", "apiurl": " "documentation": { "swagger": " } } Notice that the status alue 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 both serers. Configure an HA enironment that uses the IMS serice proider Using this scenario, you can configure a highly aailable z/os Connect EE enironment that uses the IMS serice proider (also known as the IMS Mobile feature) to connect to IMS. This scenario uses two z/os Connect EE serers with shared configurations and uses TCP/IP port sharing to distribute requests across the serers. Note: For more information about the concepts of high aailability and the options, you can choose see Chapter 7, High aailability, on page 167. In a sample configuration, the enironment has the following characteristics: Two z/os Connect EE serers with workload that is distributed to them using TCP/IP port sharing with WLM. Two IMS regions. Each z/os Connect EE serer is configured to use the IMS serice proider. Serer configuration files and API packages are shared between the two z/os Connect EE serers to maintain a consistent configuration between serers. 102 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

111 LPAR z/os Connect EE Sysplex distributor Port sharing IMS serice proider z/os Connect EE Shared files IMS Connect IMS IMS serice proider IMS Connect IMS Figure 25. A sample configuration of a highly aailable serer enironment that uses the IMS serice proider Polling of the serer configuration file is enabled. Polling allows the serers to automatically pick up configuration changes as the scenario progresses, without the need to restart the serer or inoke the FileNotificationMbean. In production, it is more common to disable polling to aoid unnecessary CPU usage when monitoring a typically static file. This scenario shows you how to configure a simple z/os Connect EE HA enironment for a single z/os LPAR so they can share the serice request processing and the IMS serice registry. The focus here is the HA configuration of the z/os connect EE serer. On the IMS side, a single IMS connection profile with one IMS host name, port, and data store can talk to multiple IMS Connect instances and IMS systems, depending on the HA setup in your IMS enironment, such as through the use of Sysplex Distributor. This scenario uses the following alues: Table 18. Values used in this scenario Description z/os LPAR host name z/os Connect serer 1 serer name z/os Connect serer 2 serer name Value companyhost.company.com haserer1 haserer2 z/os Connect serers shared HTTP port Prerequisites These requirements are needed to run this scenario. Before you create a high aailability enironment, you must first create the supporting infrastructure. This includes a single z/os Connect EE serer that uses the IMS serice proider (also known as the IMS Mobile feature) to connect to IMS as shown in Figure 1. When this configuration is complete, you can then create the high aailability enironment. Chapter 4. Scenarios 103

112 LPAR HTTP z/os Connect EE IMS serice proider IMS Connect IMS Figure 26. Configuration of a single serer to connect to IMS Prerequisite tasks You must complete the following tasks to proide the infrastructure that is needed by the scenario. 1. Create the initial serer with the IMS serice proider configured. Follow the steps in Configuring for the IMS serice proider on page 133 to set up a serer and the required IMS mobile serice registry, including the post-installation step that points you to the security configuration that is required on the serer and on IMS. 2. Create a serice by following the steps in Tutorial: Create an IMS mobile serice on page 54. After you complete the tutorial, a phonebook serice is created, deployed, and tested. 3. Create an API for the phonebook serice by following the steps in Tutorial: Create a REST API for an IMS mobile serice on page 68. After you complete the tutorial, a REST API for accessing the phonebook serice is created, deployed, and tested. Setting up HA for the first serer Modify an existing serer to prepare it for a HA enironment. In this step, you modify the configuration of the existing z/os Connect EE serer in preparation to add the second serer. You must make the following modifications: Create a shared TCP/IP port. Split the serer configuration file into content that can be shared between serers and that which is serer-specific. Moe the API and serice artifacts to a shared location. Setting up TCP/IP port sharing Set up port sharing so the z/os Connect EE serers in the HA enironment can listen on the same port. Procedure 1. Choose an unresered port number to be used for the serers' HTTP listeners. This scenario uses port as an example, but it can be changed if it is already in use in your enironment. To display ports that are currently resered on a single TCP/IP stack, use one of the following methods: 104 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

113 Enter the following SDSF command, where procname is the name of the TCP/IP stack: /D TCPIP,<procname>,N,PORTL Enter the UNIX System Serices 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 serer is listening on. In this scenario, port was chosen, with started task job names that start with ZCHA and the SHAREPORTWLM option to allow WLM to manage the incoming workload. The shared port definition in the TCP/IP port profile is as follows. PORT 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,,OBEYFILE command in the z/os Communications Serer: IP System Administrator's Commands documentation. 3. Confirm that the shared port is actie. To display ports that are currently resered on a single TCPIP stack, use one of the following methods. Enter the following SDSF command, where procname is the name of the TCP/IP stack: /D TCPIP,<procname>,N,PORTL Enter the UNIX System Serices command: netstat o The output includes the port number with a FLAGS alue of DASW: PORT# PROT USER FLAGS RANGE SAF NAME TCP ZCHA* DASW SW indicates that the port is shared and that the port uses WLM serer-specific recommendations. 4. Update the existing httpendpoint element in serer.xml to use the shared port. For example, <httpendpoint id="defaulthttpendpoint" host="*" httpport="11111" httpsport="-1" /> Creating a shared configuration file Serers in an HA enironment share common elements of the configuration file. About this task To ensure that both serers in the HA enironment can handle the same workload, some elements from the serer.xml file for each serer are shared from a common configuration file. Configuration elements that are unique to a serer are defined in a separate serer.xml file. Chapter 4. Scenarios 105

114 Procedure 1. Ensure the serer is stopped. For more information about starting and stopping the serer, see Starting and stopping z/os Connect EE on page Create directories under <WLP_USER_DIR> to store the shared configuration file. For example, if the default directory is used, run the following command from the /ar/zosconnect directory. mkdir p shared/config 3. Moe the current serer.xml file that is used by haserer1 to the shared configuration directory and rename it to haserer.xml. For example, assuming the default directory /ar/zosconnect is used, run the following command: m <WLP_USER_DIR>/serers/<SERVER_NAME>/serer.xml <WLP_USER_DIR>/zosconnect/shared/config/<HA_SERVER_NAME>.xml For example: m /ar/zosconnect/serers/haserer1/serer.xml /ar/zosconnect/shared/config/haserer.xml 4. Open the haserer.xml file and locate the following <include> statements. <include location="/<wlp_user_dir>/serers/<server_name>/resources/imsmobile-config/interactions/ims-interactions.xml" optional="true"/> <include location="/<wlp_user_dir>/serers/<server_name>/resources/imsmobile-config/connections/ims-connections.xml" optional="true"/> <include location="/<wlp_user_dir>/serers/<server_name>/resources/imsmobile-config/serices/ims-serices.xml" optional="true"/> <include location="/<wlp_user_dir>/serers/<server_name>/ims-admin-serices.xml" optional="true"/> Take one of the following actions: Remoe these <include> statements, unless you want to presere specific layout of the XML file. If you want to presere 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/serices/ims-serices.xml" optional="true"/> <include location="/<wlp_user_dir>/shared/config/ims-admin-serices.xml" optional="true"/> Sae your changes. 5. Create a file named serer.xml for haserer1 in the /<WLP_USER_DIR>/serers/ haserer1 directory with the following elements: <?xml ersion="1.0" encoding="utf-8"?> <serer description="z/os Connect EE HA serer1"> <include location="${shared.config.dir}/haserer.xml"/> </serer> This configuration file includes the shared haserer.xml by using the Liberty property ${shared.config.dir} to reference the directory that contains the shared configuration files. This property points to the directory WLP_USER_DIR/shared/ config. Setting up shared resources Moe the API and serice artifacts to a shared location so they can be accessed by both serers. About this task To ensure that workload distribution can route requests to any of the z/os Connect EE serers that are aailable in a port shared group, the serers must hae the same APIs and serices aailable. For more information, see Sharing serer configuration on page z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

115 Procedure 1. Create directories under <WLP_USER_DIR> to store the API package. The default for <WLP_USER_DIR> is /ar/zosconnect. Run the following command from the /<WLP_USER_DIR>/shared directory: mkdir p resources/zosconnect/apis 2. Moe 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> with the fully qualified path in your enironment. m /<WLP_USER_DIR>/serers/haserer1/resources/zosconnect/apis/*.aar /<WLP_USER_DIR>/shared/resources/zosconnect/apis For example, if <WLP_USER_DIR> is /ar/zosconnect, the command would be as follows: m /ar/zosconnect/serers/haserer1/resources/zosconnect/apis/*.aar /ar/zosconnect/shared/resources/zosconnect/apis 3. Add a zosconnect_zosconnectapis element in haserer.xml to configure the shared API location ${shared.resource.dir}/zosconnect/apis. For example, <zosconnect_zosconnectapis location="${shared.resource.dir}/zosconnect/apis" /> 4. Moe the IMS serice registry to /<WLP_USER_DIR>/shared/resources Enter the following commands on a single line, replacing <WLP_USER_DIR> with the actual fully qualified path: m -ir /<WLP_USER_DIR>/serers/haserer1/resources/imsmobile-config /<WLP_USER_DIR>/shared/resources For example, if <WLP_USER_DIR> is left as the default of /ar/zosconnect, the command would look as follows: m -ir /ar/zosconnect/serers/haserer1/resources/imsmobile-config /ar/zosconnect/shared/resources Results The HA enironment is now set up for the first serer. Adding a second serer Add a second serer to the HA enironment. Procedure 1. Run the zosconnect create command to create the second serer. The configuration from the first serer is copied across for the second serer in a later step so no template is required now. Run the following command from the <installation_dir>/bin directory. For example, /usr/lpp/ibm/zosconnect/ 2r0/bin. zosconnect create haserer2 2. Replace the default Liberty serer.xml file with the serer.xml file from haserer1. Run the following command: Chapter 4. Scenarios 107

116 cp /ar/zosconnect/serers/haserer1/serer.xml /ar/zosconnect/serers/haserer2 3. Start the z/os Connect EE serer. To presere the case of your serer name, you must start the serer from the System Command Extension window within SDSF. From SDSF, type / to open the extended console, then enter the command: S BAQSTRT,JOBNAME=ZCHA2,parms='haserer2 --clean' a. Check the serer's message log file in <WLP_USER_DIR>/serers/ {serername}/logs/messages.log. The following message appears: GMOIG7777I: The IMS Mobile feature initialized successfully. If the LOCALCOM serice group is aailable, then the angel is running and your Liberty Serer ID has READ access to that SERVER profile. 4. Ensure that the second IMS region is started Testing the scenario Test the HA configuration and alidate that it is distributing work across both serers. About this task You can test this scenario from a web browser, a REST client, the Swagger UI in z/os Connect EE API Editor, or the command line tool curl. curl is an open source command line tool and library for transferring data with URL syntax. It is supported on many operating systems. For more information about curl, see the website For this step, you need a REST client and curl to aoid potential persistent connection to the same serer. Procedure 1. 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 note of the alue 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 a REST client. For example, to add an entry for John Smith with the following information: Last name (the key): Smith First name: John Zip code: Extension: From a REST client, send an HTTP POST request to companyhost.company.com:11111/phonebook/contacts/smith?firstname=john &zipcode=55555&extension= 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: Last name (the key): White First name: Joe 108 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

117 Zip code: Extension: Enter the command: curl 4. Log on to an IMS terminal for each IMS system and check the usage count of the IVTNO transaction in each region. /DISPLAY TRAN IVTNO The QCNT field indicates how many times the program was run. Compare this number with the earlier number. Note: Depending on your Sysplex Distributor setup and how the workload is distributed between the two serers, your test result might ary. If the system is distributing work in a round-robin fashion, the two requests would go to different serers and to different IMS systems. Results Your HA enironment is now set up. You can add more serers by repeating the steps in Adding a second serer on page 94 Chapter 4. Scenarios 109

118 110 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

119 Chapter 5. Installation information Requirements Refer to this section when you are ready to install z/os Connect Enterprise Edition. z/os Connect Enterprise Edition V2.0 (program number 5655-CEE) is aailable to order 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 3590 tape. Your system must meet these hardware and software requirements to install and run z/os Connect EE. Support requirements Minimum required serice leels are listed where appropriate. If a specific leel is not listed, support is proided for the General Aailability (GA) release of the product. Serice leels later than those listed are also supported, if the product proides upward compatibility between serice releases. Hardware requirements z/os Connect EE runs on any hardware that supports the chosen operating system. Software requirements z/os Connect EE requires IBM z/os V1.13 or V2.1 or later, and one of the following SDKs: 1. IBM 64-bit SDK for z/os, Jaa Technology Edition V IBM 64-bit SDK for z/os, Jaa 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 V IBM CICS Explorer V IBM IMS Explorer for Deelopment V3.2.1 or later For the most up-to-date information of the specified operating enironments for z/os Connect EE, go to the IBM Software Product Compatibility reports, at Serice requirements If you use z/os Connect EE V or V with IMS Mobile Feature Pack, you must apply the PTF for IMS APAR PI The IMS mobile feature is integrated in z/os Connect EE starting V (APAR PI70432). If you use z/os Connect EE V or higher embedded in CICS TS V5, you must apply the PTFs for one of the following CICS APARs. Copyright IBM Corp. 2015,

120 Installing z/os Connect EE For CICS TS V5.2, apply the PTFs for APAR PI For CICS TS V5.3, apply the PTFs for APAR PI You must first install z/os Connect EE, and then you perform the post installation tasks. About this task The SMP/E installation process puts the product code onto your system. Procedure 1. Follow the instructions in the Program Directory to install z/os Connect EE using SMP/E. Note: By default, the product code is installed in /usr/lpp/ibm/zosconnect/2r0/ bin. You can set the WLP_USER_DIR enironment ariable to the location where you want your serer instances to be stored. If you do not set WLP_USER_DIR, the default alue /ar/zosconnect is used. If you change the WLP_USER_DIR enironment ariable to a different location, new serers are stored in the new location. The serers in the old location still exist, but can be used only when you change WLP_USER_DIR back to that location again. If you are planning to set up an HA enironment, you need to customize WLP_USER_DIR, so consider this requirement when you plan your installation. 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 shared directory and Setting up the product extensions directory on page 113 before you attempt to start a serer. Creating the z/os Connect EE shared directory Use this information to create the directories that are required by the z/os Connect EE serers. About this task The shared directory is used as a dedicated file system by all z/os Connect EE serer instances on the same LPAR. z/os Connect EE uses /ar/zosconnect as the shared directory of eery release-specific product extension. You must complete the following steps before you create and start your first z/os Connect EE serer instance: 112 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

121 Procedure 1. Create the zosconnect mount point in the z/os UNIX file system: /ar/zosconnect. 2. Set up file system security to enable z/os Connect EE serer instances to access the /ar/zosconnect shared directory. a. Change the owner of the directories in /ar/zosconnect to the user ID that is administering z/os Connect EE. b. Change the group ownership of the directories in /ar/zosconnect to a group that all the z/os Connect EE serer user IDs belong to. c. Gie the owner of the directories read, write, and execute permissions, and gie the group read, write, and execute permissions. For example, rwxrwx Optional: Use UNIX System Serices access control list (ACL) entries to add group or owner permissions for multiple administrators or groups. When the ACL is complete, actiate the FSSEC resource class and use the setfacl command. Setting up the product extensions directory The final step in the installation of z/os Connect EE, is to run the zconsetup script to create the product extensions directory. Before you begin To use the zconsetup script, you must be a z/os Connect EE administrator with sufficient 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 under the product extensions directory so that the extension can be detected by serer runtimes. For more information, see Liberty product extension The zconsetup utility must be used once per LPAR because /ar is not a shared file system. You cannot configure the specific path for the z/os Connect EE product extensions. Howeer, you can share your z/os Connect EE configuration across LPARs by mounting a shared zfs as /ar/zosconnect on each LPAR. Procedure 1. 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: Creates the release-specific product extensions directory in the /ar/zosconnect directory, for example, /ar/zosconnect/2r0/extensions Creates a symbolic link of the extensions directory in the product z/os UNIX installation path. For example, Chapter 5. Installing 113

122 /usr/lpp/ibm/zosconnect/2r0/wlp/etc/extensions Note: This needs to be done only once if /usr/lpp is shared in a sysplex configuration. Installs the z/os Connect EE product extension properties file in the product extensions directory. The following table shows the directory structure and contents of a typical installation: Table 19. Directory paths and contents Path /usr/lpp/ibm/zosconnect/2r0/bin /usr/lpp/ibm/zosconnect/2r0/runtime/ lib/ /usr/lpp/ibm/zosconnect/2r0/wlp/etc/ extensions /ar/zosconnect/2r0/extensions Contents Product code zosconnect feature files Symlink to /ar/zosconnect/2r0/ extensions Product extension properties files containing the absolute path to the serice proider. Installing the z/os Connect EE Build Toolkit Install the z/os Connect EE Build Toolkit to create Serice archie (SAR) files. About this task Two methods are proided, a command line interface (CLI) and a Software Deelopment Kit (SDK). For more information, read the Jaadoc included in the zconbt.zip file or the Build Toolkit SPI in the Reference section. You can also find examples in GitHub. Note: This task shows you how to install and use the build toolkit on a PC running Microsoft Windows. You can also run the build toolkit on z/os, but you still need to unpack the files on your PC first. See the readme.txt file for more information. Procedure 1. 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. com.ibm.zosconnect.buildtoolkit.jar com.ibm.ws.zos.connect.sar.jar jackson-annotations jar jackson-core jar jackson-databind jar jackson-dataformat-yaml jar 3. Ensure that the plugin.properties file is in the same directory as the com.ibm.zosconnect.buildtoolkit.jar file. 114 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

123 Updating z/os Connect EE You should update to the latest leel of z/os Connect EE, by applying the latest maintenance. Before you apply maintenance, shut down all instances of z/os Connect EE. Note: All files in the <WLP_USER_DIR>/serers directory are presered when you apply maintenance. Maintenance considerations for z/os Connect EE embedded in CICS Because z/os Connect EE can run stand-alone or within Liberty that is embedded in CICS, the two enironments must be described uniquely. You can run both enironments concurrently, but they are not mutually exclusie, so care is needed when you apply maintenance to the WebSphere Liberty Profile (WLP) client libraries that contain the BBOA* modules. For more information, see Keeping CICS TS 5.3 and z/os Connect EE 2.0 maintenance in sync. Installing z/os Explorer and the z/os Connect EE API Editor To design and create APIs you need to use the z/os Connect EE API Editor which is proided as a plug-in for IBM Explorer for z/os Aqua 3.0. Before you begin If you already hae IBM Explorer for z/os Aqua 3.0 installed, you should still follow this procedure, but in step 4, select only the z/os Connect EE API Editor plug-in. About this task In this task, you download and install IBM Explorer for z/os Aqua. You can then install the z/os Connect EE API Editor plug-in to define and deploy an API. Procedure 1. In your browser, go to the mainframe deelopment tools downloads page at You can choose either IBM Installation Manager (IBM IM) or Eclipse p2. In this example, 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 download site. Chapter 5. Installing 115

124 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 Editor Be aware of these considerations when planning to update z/os Explorer and the z/os Connect EE API Editor. Updating z/os Explorer If you want to update z/os Explorer, you should do so before starting the z/os Connect EE V2 update. Installing the new API Editor into Eclipse You can install the new API Editor into Eclipse while projects are still in flight. Howeer, you should export your projects before beginning the update. Migrating from z/os Connect V1 Follow these steps to migrate your API deployments to z/os Connect Enterprise Edition V2.0. To migrate an existing configuration based on z/os Connect V1 to z/os Connect Enterprise Edition V2.0, you must make the following updates to your serer.xml file: 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 serices, interceptors, DataXForm and the z/os Connect manager with zosconnect_. For example: <zosconnectserice id='example' name='example' sericeref='exampleserice'/> 116 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

125 becomes <zosconnect_zosconnectserice id='example' name='example' sericeref='exampleserice'/> Chapter 5. Installing 117

126 118 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

127 Chapter 6. Configuring Use this section to configure the different elements of z/os Connect EE. Note: All configuration settings for the serer are contained in the serer.xml file. To change the configuration, you need authority to edit this file. Creating a z/os Connect Enterprise Edition Serer Use the zosconnect command to create a z/os Connect EE serer. Before you begin To use the zosconnect command, you must be a z/os Connect EE administrator with access to the OMVS shell. Before you create a z/os Connect EE serer, ensure that the shared directory is aailable. For more information, see Creating the z/os Connect EE shared directory on page 112. About this task This task shows you how to use the default template to create a z/os Connect EE serer. Templates are a Liberty feature that you can use when you create a serer. Other serice proiders can supply their own templates to enable a quicker start with their functions. For more information, see Creating Liberty serers from custom configurations in the WebSphere Application Serer Liberty documentation. Note: The file permissions on the serer are controlled by the umask of the user that created the serer. Procedure 1. Set the WLP_USER_DIR enironment ariable to the location where you want your serer instances and user features to be stored. For example, /ar/zosconnect. You can specify WLP_USER_DIR enironment ariable in the shell enironment. This ariable must be an absolute path. 2. Run the zosconnect command with the create option. Use the following syntax: zosconnect create <serer name> --template=<template name> For example, to create a serer by using the default z/os Connect EE template, type the command: zosconnect create myserer --template=zosconnect:default Note: Add the same WLP_USER_DIR enironment ariable to the started task procedure: //STDENV * WLP_USER_DIR=/any/user/directory Copyright IBM Corp. 2015,

128 For more information about the started task procedure, see Starting and stopping z/os Connect EE on page 189. You can specify JVM options to be used on startup by placing the file <name>.options in the <WLP_USER_DIR>/serers directory and adding the following to the started task procedure: //STDENV DD PATH <WLP_USER_DIR>/serers/<name>.options Results where <name>.options is the name of the file in the <WLP_USER_DIR>/serers directory. For more information about JVM options, see Customizing the Liberty enironment in the WebSphere Application Serer Liberty documentation. A z/os Connect EE serer is created in the <WLP_USER_DIR>/serers directory with a serer.xml configuration file that defines the z/os Connect EE feature and the default location of the API packages. The shared resources and the serer definitions are also located in this directory when serers are running. The following table shows the directory structure and contents when a serer is created: Table 20. Directory paths and contents Path <WLP_USER_DIR>/serers <WLP_USER_DIR>/extension Contents Serer instances. One subdirectory per serer instance, each created by using the create option of the zosconnect command. The location where user features are installed. The configuration is shown in Figure 1. Figure 27. Configuration used in this example. 120 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

129 Configuring serices z/os Connect EE serice definitions proide the mechanism for reaching z/os application assets using REST calls. To enable a serice, you must add a serice definition to the Liberty serer.xml configuration file. Serices require the zosconnect-2.0 feature to be configured in serer.xml. About this task z/os Connect EE serices are defined by the zosconnectserice configuration element. This element contains attribute definitions that might hae globally defined counterparts. Attributes can be defined globally through the zosconnectmanager element. These attributes, if defined, apply to all serices. If both global and serice leel attributes are configured, the alues defined at the zosconnectserice leel are used. A serice proider is supplied with z/os Connect EE that enables HTTP requests to interact with z/os assets through WebSphere Optimized Local Adapters (WOLA). For more information, see Using the WOLA serice proider on page 122. z/os Connect EE also proides a serice implementation that allows HTTP requests to contact remote REST endpoints. For more information, see Configuring the z/os Connect EE REST client serice on page 145. Note: If your serice is called as part of an API call, then the interceptors and security configuration included with the API will oerride the configuration included in the serice. Procedure 1. Add a zosconnectserice configuration element for each serice in your serer.xml configuration. You must configure the sericeref and sericename attributes, other attributes are optional. The sericeref element points to the serice proider configuration element. The sericename attribute identifies the serice to z/os Connect EE and is also used as part of the URL for z/os Connect EE requests that are targeted to a specific serice. The serice name must be unique. The following excerpt from a serer.xml file shows a sample definition for a z/os Connect EE serice called recordopscreate: <!-- z/os Connect serice definitions --> <zosconnect_zosconnectserice id="zcs1" sericename="recordopscreate" sericeref="{id of serice proider}"/> For more information on each attribute, see Configuration elements on page 283 in the Reference section. 2. Optional: Add the zosconnectmanager configuration element to the serer.xml file. This element is a singleton in the serer.xml configuration and it contains global alues that apply to all z/os Connect EE serices that are defined for the serer. The element can contain the names of z/os Connect EE interceptors or data transformation proider configuration elements that apply to all serices in the serer. The following example describes a zosconnectmanager configuration element that defines an operations group name of Operator1 under the item Chapter 6. Configuring 121

130 globaloperationsgroup. This is the name of the security (SAF or LDAP) group that the requesting client user ID needs to be in before z/os Connect EE operations requests are permitted, such as action=start stop status. This group applies to all serices in the z/os Connect EE configurations. The item globaldataxformref defines the element name where z/os Connect EE will find a data transformation proider. Supplying the globaldataxformref in the zosconnectmanager element means this is the transformation proider implementation for all serices in the configuration that do not already hae their own data transformation element reference. The item globalinterceptorsref is the name of the element in the configuration that describes the set of z/os Connect EE interceptors that apply to all serices in the configuration. <zosconnect_zosconnectmanager globaloperationsgroup="operator1" globaldataxformref="xformjson2byte" globalinterceptorsref="globalinterceptors"/> Using the WOLA serice proider For more information on each attribute, see Configuration elements on page 283 in the Reference section. Follow these steps to use the WOLA serice proider supplied with z/os Connect EE. Before you begin The WebSphere Optimized Local Adapter (WOLA) serice proider requires that both the zosconnect:zosconnect-2.0 and the zoslocaladapters-1.0 features are configured. The WOLA serice proider is included with z/os Connect EE and uses the WOLA function proided with the Liberty profile. The WOLA serice proider can be used by both CICS and Batch. About this task z/os Connect EE proides a serice implementation that allows z/os Connect EE requests to interact with z/os assets through WOLA. The serice is automatically enabled when both zosconnect:zosconnect-2.0 and the zoslocaladapters-1.0 features are configured. Instances of this serice can be defined through the zosconnect_localadaptersconnectserice configuration element. Procedure For a serice to use the WOLA serice proider, the serice definition requires a zosconnect_localadaptersconnectserice configuration element in the serer.xml file. The minimum configuration consists of the target WOLA Connection Factory name, Register name (RGN), and Serice name. Configuration of z/os Connect EE follows the Liberty profile conentions by only requiring the minimum parameters to be specified. For more information about all the supported attributes, see zosconnect_localadaptersconnectserice on page 302 in the Reference section. The only supported authentication mechanism on a WOLA connection factory is container managed authentication. The authentication credentials are defined using an authdata element that is referenced on the containerauthdataref attribute of the connectionfactory element. WOLA uses a three part name to uniquely identify the WOLA serer. This name is 122 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

131 deried from the wolagroup, wolaname2 and wolaname3 attribute alues on the local adapter's configuration element zoslocaladapters, and must be unique per serer in the same z/os LPAR. The following code snippet is an example of configuring the WOLA serice proider: <!-- z/os Connect serice definitions --> <zosconnect_zosconnectserice id="zcs1" sericename="recordopscreate" sericeref="wolaopscreate"/> <!-- Local adapters connection factory definition --> <authdata id="cauth1" user="user1" password="{xor}ldo8ki02kyy="/> <connectionfactory id="wolacf" jndiname="eis/ola" containerauthdataref="cauth1" > <properties.ola/> </connectionfactory> <!-- Local adapters config --> <zoslocaladapters wolagroup="liberty" wolaname2="liberty" wolaname3="liberty" /> <!-- WOLA Connect serice and z/os Connect serice definitions --> <zosconnect_localadaptersconnectserice id="wolaopscreate" registername="batch01" sericename="coblpgm1" connectionfactoryref="wolacf"/> The z/os Connect EE serice implementation that allows z/os Connect EE requests to interact with z/os assets through WOLA might require a data transformer. If a data transformer is configured, globally or at the serice leel, input and output payloads are conerted using the configured data transformer. If a data transformer is not configured, and the request contains a JSON payload, the serice assumes that the backend program will handle the data conersion. The serice conerts the JSON payload to a byte array using the encoding specified in the request header or the default JSON encoding of UTF-8. Similarly, if the asset returns a payload and no data transformer is configured, the WOLA serice implementation expects to receie a JSON payload in byte array form, which is conerted to a JSON response payload following the same encoding rules used for transforming a JSON request payload to a byte array. The WOLA serice proider implementation allows for a number of other WOLA connection factory attributes to be specified in its zosconnect_localadaptersconnectserice configuration element. You can specify the way for a WOLA CICS Link Serer to propagate data to target CICS application programs by using the usecicscontainer attribute in the localadaptersconnectserice element. When the usecicscontainer attribute is set to false, the payload is passed to the target CICS application program by using a COMMAREA; otherwise, the payload is passed to the target CICS application program by using CICS containers. The following options are supported to flow payloads to CICS application programs: Use a COMMAREA. Use a channel name of IBM-WAS-ADAPTER to flow a single payload container. Use a channel name of your choice to flow a single payload container with the HTTP context containers. The context containers pass information about the HTTP request to the CICS application program. See Table 1 for more information. Chapter 6. Configuring 123

132 Table 21. HTTP context container names and descriptions Name ZCONReqURL ZCONReqQParms ZCONReqMethod ZCONHTTPHeaders Description Contains the URL of the HTTP request. For example, if an inokeuri definition of /banking/deposit and a query parameter country=usa are used, the URL is https//localhost: port/banking/ deposit?country=usa. Contains the query parameters of the HTTP request. For example, if a request URL is https//localhost:port//banking/ deposit?country=usa, the query parameter is country=usa. Contains the method of the HTTP request, for example, GET. Contains a JSON-formatted set of HTTP header name and alue pairs that is configured by using the linktaskchanctxconthttpheaders attribute under the zosconnect_localadaptersconnectserice element. Configuring CICS to use WebSphere optimized local adapters (WOLA) z/os Connect Enterprise Edition includes a WOLA serice proider, which uses WOLA to communicate with CICS programs. About this task WOLA is proided as part of the Liberty profile that is included in the z/os Connect Enterprise Edition installation. To configure CICS to use WOLA, copy the WOLA modules from the z/os Connect Enterprise Edition installation directory to a load library that is referenced in the DFHRPL DD concatenation of the CICS region startup JCL. Next, define WOLA CSD definitions to your CICS region and a SAF profile to control which external user IDs can use WOLA to register to the z/os Connect EE serer. Note: The Liberty feature that is included in both CICS TS and z/os Connect EE, includes the BBOA* WOLA modules, but the ersions of these modules are potentially different. Always upload the modules that are included with z/os Connect EE as these modules are tested to ensure compatibility. Procedure 1. Allocate a PDSE, for example called LIBERTY.WOLA.LOAD, with the following alues: 124 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

133 2. Open a Telnet or ssh session to your z/os system UNIX System Serices: 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/2r0/wlp/clients/zos. b. Enter the following command to copy the modules from the UNIX System Serices file system to the PDSE you allocated in preious step: cp -X./* "//'data.set'" Where "//'data.set'" is the location of the target PDSE. For example, cp -X./* "//'LIBERTY.WOLA.LOAD'" c. Check the contents of the PDSE to ensure that all the modules were copied successfully. 3. Edit your CICS region JCL start procedure to add the PDSE containing the WOLA modules. For example, add LIBERTY.WOLA.LOAD, to the DFHRPL DD concatenation. 4. Define the WOLA resources, transactions, and TD queue to the CICS region DFHCSD. The CSD definition that is required for the Liberty profile WOLA modules is proided on a GitHub website. a. In a web browser, open the URL and click the file CSDUPDAT.jclsamp to open the file. Click the Raw to remoe the line numbers. b. Copy the contents of the file CSDUPDAT.jclsamp into a new file called CSDUPDAT 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 for your CICS installation. e. Reiew and modify the ADD statement at the end of the file to conform with 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. Chapter 6. Configuring 125

134 5. Set up the Liberty message catalog in the CICS region The optimized local adapter programs issue messages from a message catalog that is proided with Liberty. For the programs to issue messages, the NLSPATH enironment ariable in the CICS region must point to the directory that contains the message catalog. This directory is wlp/lib/natie/zos/s390x/ nls/%n.cat, where wlp is the directory in which the Liberty serer is installed. To set the enironment ariable, use the Language Enironment 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 CSECT into the DFHRPL data set. For more information about other ways to set Language Enironment options, see the documentation for your ersion of CICS. Note: Methods for setting Language Enironment options that inole editing the application source code or relinking the application are not supported because the optimized local adapter programs cannot be recompiled or relinked. The following example shows a CEEROPT CSECT that defines the NLSPATH enironment ariable for a Liberty serer that is installed in /u/mstone1/wlp. The definition spans two lines and includes a continuation character, X, in column 72. CEEROPT CSECT CEEROPT AMODE ANY CEEROPT RMODE ANY ***************************************************************** * * Utility: CEEROPT * Purpose: Set default LE runtime options for CICS region. * ***************************************************************** CEEXOPT ENVAR=(( NLSPATH=/u/MSTONE1/wlp/lib/natie/zos/s390x/nlX s/%n.cat ),OVR) END 6. Define the SAF CBIND profile to allow remote clients (for example, CICS) to register 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 alues that are specified on the zoslocaladapters element in the serer.xml configuration file to create the three-part name for WOLA. For example, RDEF CBIND BBG.WOLA.LIBERTY1.LIBERTY2.LIBERTY3 UACC(NONE) Note: You can use a wildcard in the profile to make it more generic. For example, the CBIND profile BBG.WOLA.* would apply to any three-part name you use in Liberty. CBIND profiles are stored in uppercase. Specify uppercase alues in your serer.xml zoslocaladapters element because lowercase characters in your three-part name cause a mismatch when the CBIND authority is checked. b. Grant the CICS region user ID (for example, cics_id) READ access to the CBIND profile 126 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

135 PERMIT BBG.WOLA.group.name2.name3 CLASS(CBIND) ACCESS(READ) ID(cics_id) For example, PERMIT BBG.WOLA.LIBERTY1.LIBERTY2.LIBERTY3 SETROPTS RACLIST(CBIND) REFRESH 7. Start the CICS region to ensure that the WOLA definitions are installed successfully. CLASS(CBIND) ACCESS(READ) ID(CICSID) 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 region You will need to restart CICS after the z/os Connect EE serer is configured and started. What to do next More adanced configuration options are also aailable, such as: Enabling the WOLA Task Related User Exit (TRUE) to start during CICS region startup. Configuring the Link Serer Task to start by using either INITPARM or a sequential terminal. These options are similar to the actions required when WOLA is used in WebSphere Application Serer for z/os. For more information, see the Full Function WebSphere Application Serer z/os WOLA Quick Start Guide also aailable from Techdoc WP Registering CICS with the WebSphere optimized local adapter (WOLA) To use the z/os Connect Enterprise Edition WOLA serice proider to connect to CICS, you must first configure both your z/os Connect EE serer and your CICS region. You must then use a CICS transaction to register the CICS region as a client of the WOLA running in the z/os Connect EE serer. Before you begin The following tasks must be completed: 1. Configure the SAF definitions required to permit your z/os Connect EE serer the authority to access the z/os authorized serices required by WOLA. Instructions for RACF are documented in Configuring the Liberty angel process and z/os authorized serices on page Configure your z/os Connect EE serer to use the WOLA serice proider. Follow the instructions in Using the WOLA serice proider on page 122. Chapter 6. Configuring 127

136 3. Configure your CICS region to use WOLA. Follow the instructions in Configuring CICS to use WebSphere optimized local adapters (WOLA) on page 124. About this task In this task, you run a CICS transaction to start the WOLA Task Related User Exit (TRUE) and the Link Serer task. This registers the CICS region as a client of the WOLA running in the z/os Connect EE serer. Procedure 1. 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 Serer that is configured to use WOLA is started, because the serer connects to the angel process to access the z/os authorized serices. 2. Start the z/os Connect EE serer. Check the serer's message log file in <WLP_USER_DIR>/serers/<sererName>/logs/messages.log. The following messages indicate that the serer was started successfully: CWWKB0103I: Authorized serice group LOCALCOM is aailable. CWWKB0103I: Authorized serice group WOLA is aailable... CWWKB0501I: The WebSphere Optimized Local Adapter channel registered with the Liberty profile serer using the following name: <GROUP> <NAME2> <NAME3> J2CA7001I: Resource adapter ola installed in seconds.. where: <GROUP>, <NAME2>, and <NAME3> must match the wolagroup, wolaname2 and wolaname3 attribute alues specified on the zoslocaladapters element in serer.xml. The aailability of the LOCALCOM serice group is a key indicator that the angel process is running and your Liberty Serer ID has READ access to that serer profile. The aailability of the WOLA serice group is another key indicator that the configuration was completed successfully. Message CWWKB0501I shows the successful use of the WOLA three-part name alues you proided in the serer.xml file. This message indicates that an external address space might register into the Liberty Profile serer, in this instance the z/os Connect EE serer, by using this three-part name on the BBOA1REG API. The J2CA7001I message indicates that the WOLA JCA resource adapter is aailable. 3. Ensure that the CICS region is started. 4. Start the WOLA TRUE and Link Serer 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: 128 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

137 WOLA TRACE 1: Exit enabled successfully. b. Enter the following command to start the link serer task and register to your serer: Results BBOC START_SRVR RGN=<registerName> DGN=<GROUP> NDN=<NAME2> SVN=<NAME3> SVC=* SEC=N REU=Y The following message indicates success: WOLA TRACE 0: Start serer completed successfully. 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 topic Optimized local adapters for z/os APIs in the WebSphere Application Serer z/os documentation. Search on the string cdat_olaapis. Open the link and go to the Register section, also known as the BBOA1REG section and look for the RC and RSN codes. You can now send requests from the z/os Connect EE serer ia WOLA to CICS. What to do next To unregister the CICS region from WOLA and stop the Link Serer task, open a terminal session with the CICS region and issue the following command: BBOC STOP_SRVR RGN=<registerName> where: <registername> must match the registername attribute alue specified on the localadaptersconnectserice element in serer.xml. The following message indicates that the serer was stopped: WOLA TRACE 0: Stop serer 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 serice proider You can create a serice to enable RESTful access to IMS transactions through the IMS serice proider. Chapter 6. Configuring 129

138 The solution inoles the use of the IMS Mobile feature (imsmobile-2.0), which seres as the IMS serice proider. The IMS Mobile feature was preiously included in the IMS Enterprise Suite as the IMS Mobile Feature Pack for z/os Connect EE. Important: V (APAR PI70432) or later is required for the embedded IMS serice proider. Configuration scenarios Identify your scenario and follow the corresponding steps. Table 22. Configuration scenarios Scenario You are setting up the serer to use the IMS serice proider the first time. You are upgrading from IMS Mobile Feature Pack for z/os Connect EE in IMS Enterprise Suite Steps 1. Check the Operational requirements. 2. Reiew the IMS serice security process flow. Determine if basic or SAF registry must be configured on the serer for the initial setup. Identify if RACF is turned on in IMS Connect and if an IMS technical ID, technical group, and technical password need to be configured. 3. Follow the steps in Configuring for the IMS serice proider on page 133. Follow the steps in Upgrading from the IMS Mobile Feature Pack in IMS Enterprise Suite on page 136. Operational requirements Examine the operational requirements to assist the planning and setup of your IMS mobile solution. IMS Connect is required. The IMS serice proider proides access to IMS transactions through the IMS Transaction Manager with IMS Connect being the TCP/IP gateway. The transactions can then access IMS DB, DB2, and other external subsystems. See IMS serice security process flow for more information about user authentication and authorization from z/os Connect EE to IMS. IMS Explorer for Deelopment V or later is required for creating, publishing, and testing the serices. Subsequent updates of IMS Mobile feature might require a newer ersion of IMS Explorer. The z/os Connect EE API Editor is required for creating APIs for IMS serices. IMS serice security process flow For a secure setup, the z/os Connect EE serer must be configured with SAF or LDAP registry authentication. For SAF, the serer must be configured with the SAF Authorization element. An access control list (ACL) must be configured to protect IMS mobile serice registry. The following diagram describes the user authentication and authorization process. 130 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

139 Figure 28. The IMS mobile solution security process flow and components inoled 1. The client, such as IMS Explorer for Deelopment, IBM MobileFirst Platform Foundation (preiously 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 to basic authentication. 3. The client (a mobile serer such as IBM MobileFirst Platform Foundation or a web client) sends to z/os Connect EE serer a client certificate. All clients must send a basic authentication credential. The user ID and password in the credential must be registered in the basic registry or SAF registry on the serer. Note that the IMS Explorer for Deelopment does not send in the client certificate. A alid administratie user ID (registered in the RACF or LDAP user registry) with read/write priileges to the IMS Mobile feature installation directory (the alue specified for the imsmobile.install.dir ariable in the serer.xml file) must be specified in IMS Explorer for Deelopment when you use the proided wizard to create and publish a mobile serice. With this user ID properly configured, IMS Explorer for Deelopment is considered a trusted client. 4. The serer erifies the client certificate with the preiously imported client certificate that is stored in the seer truststore or keyring. If the client certificate is missing, the serer applies basic authentication against the user registry that was configured (SAF or LDAP). 5. The client begins transmitting data oer a secure connection. Chapter 6. Configuring 131

140 6. For a serice request, z/os Connect EE serer authenticates the user credential. Then the serer authorizes the user by using a SAF call to alidate that the group names in the serice configuration matches one of the group names associated with the user ID in the request subject. Important: The user ID is determined based on the following rules: If a user name and a password are specified in IMS Explorer for Deelopment when the connection profile is created, the user name and the password are used for SAF authentication with IMS Connect. 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 serice proider retriees the user ID from the request subject. If the user ID is longer than 8 bytes, the use ID must be properly mapped to a RACF ID. Note: z/os Connect Enterprise Edition V or later is required. In older ersions, the user ID must be 8 bytes or less. For more information about, see the RACMAP command for mapping between a RACF ID and one or more distributed user IDs. com.ibm.zos.2r2.icha400/racmap.htm. If authentication is disabled on z/os Connect EE, the IMS serice proider retriees the user ID from the technical ID, an IMS mobile global element that is specified during initial installation and setup. The IMS technical password is the SAF password for the user. If the technical ID is left blank, the IMS serice proider uses the z/os Connect EE started job user ID. The IMS technical password, if specified, is the SAF password for the user. 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. If authentication 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 is used to manage the messages. The request triggers SSL handshake ia AT-TLS, if it is configured, to protect the communication between z/os Connect EE serer and IMS Connect. 10. IMS Connect flows the request with the SAF user ID, password, and IMS groupname to IMS. IMS might perform additional authorization, depending on the setting. IMS transaction runs. IMS returns response (bytes) to IMS Connect. 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: 132 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

141 Security configuration for the IMS mobile solution on page 140 You must configure the z/os Connect EE serer and the back-end IMS to ensure secure communications. Related information: Configuring for the IMS serice proider To set up a new serer to use the IMS serice proider, use the proided template to set up the required configuration, including the IMS mobile serice registry. If you hae already set up a serer (such as with the WOLA serice proider), or you hae specific layout requirements for the XML file, manually configure the serer.xml file. Before you begin Important: If you are upgrading from IMS Mobile Feature Pack for z/os Connect EE in IMS Enterprise Suite, following the steps in Upgrading from the IMS Mobile Feature Pack in IMS Enterprise Suite on page 136 instead. For a new installation or if you are using the IMS serice proider the first time, take the following prerequisite steps: 1. Install or upgrade to V (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 the product extensions directory exists and the required imsmobile.properties file is added by following the steps in Setting up the product extensions directory on page 113. About this task Use the proided template to set up a serer that is configured to use the IMS serice proider. Instructions are also proided for manual configuration of the serer.xml file. Manual configuration might be the approach to take for the following scenarios: You already hae other serice proiders set up and working, and now need to add the IMS serice proider. You want to presere specific layout of the serer.xml. Procedure For a new serer setup, start with step 1. If you already hae a serer set up to use other serice proiders, start with step To configure and set up the IMS serice proider, run the zosconnect command with the create option and specify the imsmobile template. zosconnect create <serer name> --template=imsmobile:imsdefault For a default installation directory, the IMS serice proider is set up under the /usr/lpp/ibm/zosconnect/2r0/imsmobile directory. 2. Proceed to step If you already hae an existing serer, manually update the serer.xml file to use the imsmobile-2.0 feature by adding the following configuration information in the <featuremanager> section: Chapter 6. Configuring 133

142 <featuremanager>... <feature>imsmobile:imsmobile-2.0</feature> </featuremanager> 4. Configure security. Security must be enabled in order to use the IMS Explorer for Deelopment to create, deploy, and test IMS serices. Uncomment the related tags and proide the appropriate alues. a. Uncomment the following tags for SSL and failoer to basic authentication: <!-- Define the SSL configuration <ssl id="defaultsslconfig" keystoreref="defaultkeystore" truststoreref="defaulttruststore" clientauthentication="false" /> <!-- Define a keystore, use securityutility to generate encoded password <keystore id="defaultkeystore" password="<add VALID PASSWORD>"/> --> --> <!-- Define a truststore, use securityutility to generate encoded password <keystore id="defaulttruststore" password="<add VALID PASSWORD>"/> --> <!-- Fail oer to basic authentication <webappsecurity allowfailoertobasicauth="true"/> Use the Liberty serer securityutility command (securityutility encode userid) to generate the encoded password. This utility is located in the <installation_path>/wlp/bin directory. For example, the uncommented security configuration might look as follows: <!-- Define the SSL configuration --> <ssl id="defaultsslconfig" keystoreref="defaultkeystore" truststoreref="defaulttruststore" clientauthentication="false" /> <!-- Define a keystore, use securityutility to generate encoded password --> <keystore id="defaultkeystore" password="{xor}pjmzbiw7kje="/> <!-- Define a truststore, use securityutility to generate encoded password --> <keystore id="defaulttruststore" password="{xor}pjmzbiw7kje="/> <!-- Fail oer to basic authentication --> <webappsecurity allowfailoertobasicauth="true"/> b. Configure your SAF registry or basic registry by uncommenting the related sections in the serer.xml file. For more information about SAF or basic registry configuration, see Configuring security for z/os Connect EE on page Sae your changes. You can now start the serer and erify if you can use the IMS serice proider. 6. Start the serer. Starting the serer is usually done by running a started task based on the sample JCL <install_location>/jcl/baqstrt.jcl. For information about starting the serer, see Starting and stopping z/os Connect EE on page 189. A GMOIG7777I message is issued in the console and logged in the messages.log file in <WLP_USER_DIR>/serers/{serername}/logs, indicating that the feature is initialized successfully. 7. Verify that the IMS serice proider is configured properly by inoking the IMS PingSerice serice that comes with the IMS Mobile feature. In your REST client or Jaa application, use the HTTP PUT method to inoke the proided IMSPingSerice serice: z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

143 Results You would receie the following response: { message: "The ping request to the z/os Connect EE serer through the IMS serice proider was successful." } What to do next To test and erify communications to IMS, you can use the IMS PingSerice serice by proiding additional parameters. For more information, see Verifying serer communication with IMS. To start creating a serice and an API, see the information in the following IMS scenarios. Each scenario includes a tutorial with detailed steps. Create an IMS mobile serice on page 48 Deelop an API to inoke an IMS serice on page 66 Verifying serer communication with IMS Use the IMSPingSerice to erify that the IMS serice proider can communicate with IMS Connect by specifying the hostname, port number, and IMS data store name. About this task The IMSPingSerice serice is included as part of the IMS Mobile feature that you can use to check if the IMS serice proider is configured correctly. This serice can also be used to erify that the IMS serice proider can communicate with IMS Connect. Procedure In your REST client or Jaa application, use the HTTP PUT method to inoke the proided IMSPingSerice serice, and specify host name, the port number, and the IMS data store name. my.ims.host.com&port=9999&datastore=ims1 The HOSTNAME, PORT, and DATASTORE parameters must be in all uppercase letters, and all three parameters must be specified. If one of the required parameters is missing or the parameter names are misspelled, the parameters are ignored, and the request is treated as a ping request to the z/os Connect EE serer. When these parameters are proided correctly, this serice issues a /DISPLAY OTMA command to erify that the IMS serice proider on the z/os Connect EE serer can access the IMS host system. Chapter 6. Configuring 135

144 Results You would receie the following response: {... "message": "The ping request for the IMS system \"HOSTNAME: , PORT: 9999, DATASTORE: IMS1, RACF ID: admuser\" through z/os Connect EE and the IMS serice proider was successful."... } Upgrading from the IMS Mobile Feature Pack in IMS Enterprise Suite If you are upgrading from z/os Connect EE V2.0.4 or earlier and IMS Mobile Feature Pack for z/os Connect EE in IMS Enterprise Suite, modify the imsmobile.properties file manually. Before you begin Stop your current serer. Ensure that all serer processes are stopped. Procedure 1. Apply APAR PI70432 (V ). Ensure that you follow the steps in the APAR holdcard. 2. Modify the imsmobile.properties file in the <WLP_USER_DIR>/2r0/extensions directory (default is /ar/zosconnect/2r0/extensions) by setting the alue for the com.ibm.websphere.productinstall property to imsmobile/wlp-ext as follows: com.ibm.websphere.productinstall=imsmobile/wlp-ext 3. Sae your changes. You can now start the serer and erify if you can use the IMS serice proider. 4. Start the serer. Starting the serer is usually done by running a started task based on the sample JCL <install_location>/jcl/baqstrt.jcl. For information about starting the serer, see Starting and stopping z/os Connect EE on page 189. In the console or the messages.log file in <WLP_USER_DIR>/serers/ {serername}/logs, the following message appears: GMOIG7777I: The IMS Mobile feature initialized successfully. 5. Verify that the IMS serice proider is configured properly by inoking the IMS PingSerice serice that comes with the IMS Mobile feature. In your REST client or Jaa application, use the HTTP PUT method to inoke the proided IMSPingSerice serice: You would receie the following response: { message: "The ping request to the z/os Connect EE serer through the IMS serice proider was successful." } 136 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

145 Results All your existing serices and APIs remain untouched. You can proceed to test one of your serices and APIs. What to do next Optionally, you can remoe the old IMS Mobile Feature Pack installation files to clean up your file system and to reduce confusion. (Optional) Remoing IMS Mobile Feature Pack installation files The old IMS Mobile Feature Pack installation files are no longer needed. You can remoe 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 Pack in IMS Enterprise Suite on page 136 to properly configure the serer to use the IMS serice proider. Procedure 1. Remoe the.esa file for IMS Mobile Feature Pack if you downloaded it or obtained it through Shopz as part of IMS Enterprise Suite. 2. Remoe the installed IMS Mobile feature files. This location is specified in the imsmobile.install.dir ariable in the serer.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 can be deleted from the system because it is no longer used to store the IMS Mobile feature files. 4. Open the serer.xml file and remoe the following imsmobile.install.dir ariable tag, which is no longer needed. <ariable name="imsmobile.install.dir" alue="<path_to_ims_mobile_feature_pack_install_dir>"/> 5. Sae your changes. Results The old IMS Mobile Feature Pack installation files are now cleaned up. IMS mobile serice definition An IMS mobile serice is created, published, and managed through IMS Explorer for Deelopment. A serice is started when it is published. A started serice can be inoked, stopped, and restarted by using REST calls. You can also use IMS Explorer for Deelopment to stop and restart a serice, or test a serice by inoking it. A published IMS mobile serice is a RESTful serice with associated back-end connections, interaction properties, and a transaction message pair based on the serice metadata. The serice metadata object contains metadata that describes the input and output data formats of the related IMS application. An IMS mobile serice loads serice metadata for request and response data transformation. The serice communicates with one or more connection endpoints as defined in the connection profiles based on the interactions that are stored in the interaction properties profile. Chapter 6. Configuring 137

146 IMS Explorer for Deelopment proides the tooling for generating the serice metadata files from the COBOL copybook or PL/I structure of the IMS application. You can also use IMS Explorer for Deelopment to define the connection properties and interaction properties. Based on the serice metadata, IMS Mobile feature transforms the RESTful request and response between JSON and bytes that are recognized by the back-end IMS COBOL or PL/I application. A RESTful IMS mobile serice has the following elements: Connection An IMS Connect connection profile contains parameters that are specified through IMS Explorer for Deelopment, such as a connection profile name, the host name, port number, data store name, and connection timeout alue. Interaction properties For each serice communicating with IMS Connect, a set of interaction properties can be specified, including interaction profile name, commit mode, sync leel, and whether the response data includes LLLL. Metadata A pair of references to metadata that describes the transaction's input and output message formats. Serice interface An oerlay of transaction metadata to: Specify a user-friendly serice field name. Select the fields to be included in the serice definition. Proide remarks for each field with possible information on the input alues. Specify default alues for fields. All this serice definition information is stored in the IMS mobile serice registry. Related concepts: IMS mobile serice registry, in-memory cache, and administratie serices on page 139 The IMS mobile serice registry is the authoritatie source of information for serice resources such as connection profiles, interaction profiles, serice metadata, and transaction message metadata. When a serice is first inoked or queried, related serice resources are stored in the in-memory cache to improe the performance of subsequent requests. Request and response messages for IMS mobile serices on page 50 Request and response messages for IMS mobile serices are represented in JSON format. The schema can be obtained through the getrequestschema and getresponseschema actions. Related reference: High-leel language and JSON schema mapping on page 51 The data mapping function in IMS Explorer for Deelopment communicates with the data transformation function in IMS Mobile feature to generate JSON schemas from high-leel language data structures and ice ersa. Related information: 138 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

147 IMS mobile serice registry, in-memory cache, and administratie serices The IMS mobile serice registry is the authoritatie source of information for serice resources such as connection profiles, interaction profiles, serice metadata, and transaction message metadata. When a serice is first inoked or queried, related serice resources are stored in the in-memory cache to improe the performance of subsequent requests. When you define a connection profile or an interaction profile, or create a mobile serice by using the IMS Explorer for Deelopment, the information is stored in the IMS mobile serice registry. When a serice is first inoked or queried, its resource information is loaded into the in-memory cache and stays there until the IMS gateway serer shuts down. Storing the serice information in the cache reduces access latency and shortens serer response time. You can dump the cache into the serer log or clear the cache by using IMS Explorer for Deelopment. These functions could be used for troubleshooting. IMS mobile serice registry The serice registry is installed into the location that is defined in the serer.xml file during initial installation. It is defined in the imssericeregistryhome attribute in the <imsmobile_imssericemanager> element. The serice registry default location is a resources/ directory under the serer directory (the <WLP_USER_DIR>/serers/<sererName> directory, with a typical location of /ar/zosconnect/serers/<serer_name>). To customize the location, you must specify an absolute path, for example, <imsmobile_imssericemanager imssericeregistryhome="/usr/lpp/imsmobile/resources"/>. The serice registry directory contains a subdirectory imsmobile-config/ that contains the serice registry artifacts with the following sub-directories: Table 23. IMS mobile serice registry structure Directory connections/ interactions/ serices/ tran_messages/ Description This directory contains the ims-connections.xml file that stores the connection profile information, such as the profile name and the associated host name, port number, and connection timeout alues. This directory contains the ims-interactions.xml file that stores the interaction properties information, such as the interaction profile name, the associated commit mode, and whether the response data includes LLLL. This directory contains the ims-serices.xml file that defines all the serices and their interfaces. Serice input interface (sericename_sii.xml) and output interface (sericename_soi.xml) for each serice are stored in the interfaces/ subdirectory. This directory contains the input and output message formats for transactions. Each transaction has its own directory that contains the tran_name - INPUT.xml and tran_name - OUTPUT.xml files. Chapter 6. Configuring 139

148 Store the serices definitions in a source control management system for ersioning control and for serice promotion enablement. IMS mobile administratie serices IMS mobile administratie serices are responsible for managing the creation, reading, updating and deletion of IMS mobile serice registry artifacts. The ims-admin-serices.xml file is the serice configuration file that contains information about these serices. These are z/os Connect EE serices and can be managed through the z/os Connect EE serice configuration options. This file is located in the same directory as serer.xml. Related tasks: Deploying an IMS serice to a different target serer on page 144 A serice is automatically deployed when you create or edit a serice by using IMS Explorer for Deelopment. After a serice is tested in one enironment (such as a deelopment enironment), to deploy the serice to a different target serer (such as a production serer), copy the serice definition and interfaces files from the IMS mobile serice registry to the target serer. Clearing or examining the IMS serice in-memory cache on page 268 To help troubleshoot issues, you can clear the cache or dump the content in the cache into the serer log by using the IMS Explorer for Deelopment without restarting the z/os Connect EE serer. Security configuration for the IMS mobile solution You must configure the z/os Connect EE serer and the back-end IMS to ensure secure communications. Examine the IMS serice security process flow on page 130 topic to gain an understanding of how user authentication and authorization are handled, and how the user ID and password for each serice request are determined. Table 24. Required security configurations Area z/os Connect EE serer IMS serices Configuration task See Configuring security for z/os Connect EE on page 180 and related security configuration topics for details. For serice-leel security, you can set the authority leel of a user in the <ims_serice_registry_home>/serices/ims-serices.xml file. The following example sets, for the phonebook serice, the administrator authority for users in ADMINGRP1 and the Inoke authority for users in USERGRP1. <zosconnect_zosconnectserice id="phonebook" inokeuri="/imsmobile/serices/phonebook" runglobalinterceptors="true" admingroup="admingrp1" inokegroup="usergrp1" sericedescription="" sericename="phonebook" sericeref="phonebook"/> See Oeriew of z/os Connect EE security on page 177 for more information. 140 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

149 Table 24. Required security configurations (continued) Area IMS serice proider Configuration task If authentication is disabled on the z/os Connect EE serer, the IMS serice proider retriees the user from the technical ID that you can specify in serer.xml. In addition, you can specify the technical group and technical password in an <imsmobile_imssericemanager>) element in the serer.xml file: <imsmobile_imssericemanager imssericeregistryhome="/usr/lpp/imsmobile/resources" imstechnicalgroup="imsgroup" imstechnicalid="imsuser" imstechnicalpassword="encoded_password"/> The IMS technical ID and IMS technical group name must be properly configured in SAF (or RACF) on the IMS host system. The IMS technical password is optional. This global technical password 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 serer securityutility command (securityutility encode userid) to generate the encoded password. Copy the encoded password into the serer.xml file for the imstechnicalpassword attribute. See Configuring the global IMS technical password on page 142 for more information. IMS Connect The user ID and the associated password for each request are passed to IMS Connect for authentication and authorization. If RACF is turned on in IMS Connect, the user ID and the password must be properly configured in RACF on the IMS host system. The IMS Connect HWSJAVA0 exit routine manages the messages for the IMS mobile solution and can be used to perform custom security checking. IMS Explorer for Deelopment To connect to an z/os Connect EE serer to begin creating and editing message metadata and specifying the interaction properties, you must first proide a user ID and password along with the host name or IP address and the port number. The user ID and password must be set up as an administratie user on the z/os Connect EE serer with read and write permission to the directory where the IMS Mobile feature and the IMS serice registry is located. If RACF is turned on in IMS Connect, when you create a connection profile for your IMS mobile serice, specify a user ID and a password for RACF authentication. You can create multiple connection profiles for each serer instance, with each connection profile associated with a user ID and password. For more information about how the user ID is determined when a user ID is not specified in the connection profile, see Authentication by IMS Connect on page 143. Client applications All client requests must proide basic authentication credentials in the header. The user ID and password in the credential must be registered in the basic registry or SAF registry on the serer. Important: Use of z/os Communications Serer Application Transparent Transport Layer Security (AT-TLS) SSL protection to secure the communication between the z/os Connect EE serer and IMS Connect is recommended. Chapter 6. Configuring 141

150 Optionally, you can turn on IMS security (/SECURE OTMA) for authorization that is based on RACF user ID in the request subject and the associated group name. Enhancing security through these options are recommended. Howeer, If you turn on IMS security, and you are using the basic user registry for user authentication in z/os Connect EE serer, you must use RACF ID as the user ID in your basic user registry in order for IMS OTMA to authorize the user. Configuring AT-TLS for IMS Connect and OTMA Setting up AT-TLS SSL for IMS Connect For more information about setting up AT-TLS for IMS Connect, see the IMS 14 IMS Connect information. /SECURE OTMA command For more information about setting up IMS security, see the IMS 14 IMS Commands information. Configuring the global IMS technical password If RACF security is turned on in IMS Connect (RACF=Y), configure a global IMS technical password per z/os Connect EE serer instance. Before you begin Examine the IMS serice security process flow on page 130 topic to gain an understanding of how user authentication and authorization are handled. About this task The IMS technical password is optional. If the connection profile is created with a user ID and a password defined, that user ID and the password are used for SAF authentication in IMS Connect. If a user ID is not specified in the connection profile, this technical password is sent to IMS Connect as part of the request with the request user ID. The user ID might be the ID that issues the request, the IMS technical ID, or the ID that started the serer, depending on your setup. When IMS Connect RACF security is turned on, a RACF password is required for the user ID that is associated with the mobile serice request. This RACF password is specified in this IMS technical password. Only one IMS technical password can be specified per z/os Connect EE serer instance. This password must be set up in RACF for the user ID or IDs that are associated with the mobile serice requests. Procedure To configure the IMS technical password, modify (uncomment) the imstechnicalpassword attribute and specify the password in the <imsmobile> element in the serer.xml file. Possible approaches to update the serer.xml file include: Use WebSphere Application Serer Liberty Profile Deeloper Tools to configure the password and then transfer the file to the serer by using FTP. Use the securityutility command (securityutility encode userid) to generate the encrypted password to copy into the serer.xml file for the imstechnicalpassword attribute. This utility is located in the <installation_path>/wlp/bin directory. 142 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

151 Results The updated <imsmobile_imssericemanager> element in the serer.xml file might look as follows: <imsmobile_imssericemanager imssericeregistryhome="./resources" imstechnicalgroup="sys1" imstechnicalid="imsguest" imstechnicalpassword="{xor}pjmzbiw7kje=" > Authentication by IMS Connect For authentication with IMS Connect, a user ID and a password can be specified in the IMS Explorer for Deelopment when you create a connection profile. The user ID is determined based on the following rules: If a user name and a password are specified in IMS Explorer for Deelopment when the connection profile is created, the user name and the password are used for SAF authentication with IMS Connect. 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 serice proider retriees the user ID from the request subject. If the user ID is longer than 8 bytes, the use ID must be properly mapped to a RACF ID. Note: z/os Connect Enterprise Edition V or later is required. In older ersions, the user ID must be 8 bytes or less. For more information about, see the RACMAP command for mapping between a RACF ID and one or more distributed user IDs. com.ibm.zos.2r2.icha400/racmap.htm. If authentication is disabled on z/os Connect EE, the IMS serice proider retriees the user ID from the technical ID, an IMS mobile global element that is specified during initial installation and setup. The IMS technical password is the SAF password for the user. If the technical ID is left blank, the IMS serice proider uses the z/os Connect EE started job user ID. The IMS technical password, if specified, is the SAF password for the user. 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 a password when you create a connection profile in IMS Explorer for Deelopment. You can create multiple connection profiles per serer instance, each with its user ID and password. If no user ID is specified in the connection profile, ensure an IMS technical ID and a technical password are specified. This IMS technical password is used as the password for RACF authentication. If RACF is turned off in IMS Connect, you can either specify a user name and a password in the connection profile (all serices using the connection profile would share the same user name for IMS authorization), or leae the user name in the connection profile blank, in which case the user ID coming from the z/os Connect EE serer would be used for IMS authorization. Chapter 6. Configuring 143

152 Deploying an IMS serice to a different target serer A serice is automatically deployed when you create or edit a serice by using IMS Explorer for Deelopment. After a serice is tested in one enironment (such as a deelopment enironment), to deploy the serice to a different target serer (such as a production serer), copy the serice definition and interfaces files from the IMS mobile serice registry to the target serer. About this task Important: This step assumes the related connection profiles and interaction properties profiles are already created on the target serer. Procedure 1. Obtain the following files from the deelopment serer or your source control management system. These files are located in the IMS mobile serice registry in the imsmobile-config/ directory. serices/ ims-serices.xml interfaces/sericename_sii.xml interfaces/sericename_soi.xml tran_messages/tranname/ tranname-input.xml tranname-output.xml 2. For each serice to deploy on the target serer, you need the serice interfaces files and transaction input and output message format files in the same location in the IMS mobile serice registry on the target serer. a. Copy the following files into the serice registry on the target serer. Ensure the same directory structure is presered. Put the serice interfaces files in the serices/ directory. interfaces/sericename_sii.xml interfaces/sericename_soi.xml Put the transaction message format files in the tran_messages/tranname/ directory. tranname-input.xml tranname-output.xml b. Copy the serice definitions in the ims-serices.xml file to the same file on the target serer. Each serice has an associated <zosconnect_zosconnectserice..> element and a <imsmobile_imszserice...> element: <zosconnect_zosconnectserice id="cbltmbcsserice"... sericeref="cbltmbcsserice"/> <imsmobile_imszserice... id="cbltmbcsserice" Copy these two set of tags into the ims-serices.xml file on the target serer. Tip: Any new or changed serice definitions are appended to the end of the ims-serices.xml file. 3. If your updatetrigger attribute of the config element in serer.xml is set to mbean, restart the serer. The default setting is polled, and the serer will pick up the new serices without a restart. 144 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

153 Example Using other serice proiders For sample scripts that demonstrate how to deploy serices, see Sample shell scripts for deploying IMS mobile serices to a different target serer. Using the serice proiders that are supplied with other products. Both WOLA and IMS serice proiders are included with z/os Connect EE. You can also write your own serice proider or you can use one that is supplied with the SoR to plug into the framework. The following list proides references to the documentation for other products that supply their own serice proiders. IBM MQ for z/os Serice Proider for z/os Connect The IBM MQ serice proider allows REST aware applications to interact with z/os assets that are use IBM MQ for z/os queues and topics. The application can be written without the need to code for asynchronous messaging. Configuring the z/os Connect EE REST client serice The z/os Connect EE REST Client support enables z/os Connect EE users to route requests to remote REST applications through z/os Connect EE, taking adantage of the existing interceptor infrastructure. About this task This function is aailable when you configure z/os Connect EE. The z/os Connect EE REST Client serice is a z/os Connect EE serice SPI implementation. Requests can use the following methods to inoke this serice: 1. Use the?action=inoke query parameter mechanism as follows: where sericey is the serice name that is associated with the configured zosconnectsericerestclient element. 2. Use the zosconnectserice attribute definition that is called inokeuri. You can use this attribute to define a custom URI that is associated with a serice name and any of the following HTTP erbs: GET, POST, PUT, DELETE; for example: <zosconnect_zosconnectserice sericename="sericey" sericeref="restclientsericey" inokeuri="/my/custom/uri" /> 3. Use an API to inoke the serice. An example of a serice inocation for the defined serice is: my/custom/uri (HTTP erb: GET/POST/PUT/DELETE). z/os Connect EE understands the association between the inokeuri attribute and the sericename attribute defined in the example. z/os Connect EE calls the inoke method on the implementation of the z/os Connect EE associated serice (restclientsericey). For more information on the capability and flexibility that the inokeuri attribute offers, see zosconnect_zosconnectserice on page 318 in the Reference section. Chapter 6. Configuring 145

154 Procedure 1. Configure the zosconnectsericerestclient element and associate it with a zosconnectserice element. You should use the zosconnect_zosconnectsericerestclientconnection element to configure the HTTP endpoint information independently of the Serice definition. This method allows you to deploy the same SAR file into multiple enironments which might need to connect to different backend systems. <featuremanager> <feature>zosconnect:zosconnect-2.0</feature> </featuremanager> <!-- Global interceptor definition to run for all serice requests --> <zosconnect_zosconnectinterceptors interceptorref="auth,audit,filesystemlogger" id="globalinterceptorlist1"/> <filesystemloggerinterceptor id="filesystemlogger" logname="serice1log_%servername%"sequence="1"/> <authorizationinterceptor id="auth" sequence="2"/> <auditinterceptor id="audit" sequence="3"/> <!-- ZosConnectManager definition --> <zosconnect_zosconnectmanager globaladmingroup="admin" globaloperationsgroup="ops" globalinokegroup="invoke" globalinterceptorsref="globalinterceptorlist1" /> <zosconnect_zosconnectserice sericename="sericey" sericeref="restclientsericey" inokeuri="/my/custom/uri" /> <zosconnect_zosconnectsericerestclient id="restclientsericey" connectionref="restclientconnectiony" uri="/remote/endpoint" httpmethod="delete" /> <zosconnect_zosconnectsericerestclientconnection id="restclientconnectiony" connectiontimeout="30s" host="remotehostname" port="8800" receietimeout="60s" /> In the example, requests that target the sericey serice are routed to the remote host and port that is configured under the associated restclientsericey serice and that uses the configured URI and DELETE HTTP method. The JSON payload is automatically sent with the remote request. The host name and port number attributes are specified in the assoicated zosconnectsericerestclientconnection element. If you do not specify the uri or httpmethod attributes, the alues that are used are the ones from the original client request that is targeting the sericey serice. The example also shows that because interceptors are configured to run globally, eery request that targets the sericey serice is logged, authorized, and audited before it is routed to the remote endpoint. The interceptors also log and audit the responses on the return from the remote endpoint. Because an inokeuri attribute is configured for the sericey serice, the requester can start the implementation of the sericey inoke method by using the following URL: and using either the GET, POST, PUT, or DELETE HTTP methods. In this case, because the sericey serice refers to an instance of the z/os Connect REST client serice, the inoke() method on this instance is called. For more information about aailable configuration attributes and default alues, see Configuration elements on page 283 in the Reference section. 146 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

155 <featuremanager> <feature>zosconnect:zosconnect-2.0</feature> </featuremanager> Alternatiely, you can define the connection information directly in the zosconnectsericerestclient element and associate it with a zosconnectserice element, but using this method means that the same SAR file cannot be deployed into multiple enironments. <!-- Global interceptor definition to run for all serice requests --> <zosconnect_zosconnectinterceptors interceptorref="auth,audit,filesystemlogger" id="globalinterceptorlist1"/> <filesystemloggerinterceptor id="filesystemlogger" logname="serice1log_%servername%"sequence="1"/> <authorizationinterceptor id="auth" sequence="2"/> <auditinterceptor id="audit" sequence="3"/> <!-- ZosConnectManager definition --> <zosconnect_zosconnectmanager globaladmingroup="admin" globaloperationsgroup="ops" globalinokegroup="invoke" globalinterceptorsref="globalinterceptorlist1"/> <zosconnect_zosconnectserice sericename="sericey" sericeref="restclientsericey" inokeuri="/my/custom/uri" /> <zosconnect_zosconnectsericerestclient id="restclientsericey" host="remotehostname" port="8800" uri="/remote/endpoint" httpmethod="delete" /> 2. Optional: Configure basic authentication. Add the appsecurity-2.0 feature to the serer.xml file. <featuremanager> <feature>zosconnect:zosconnect-2.0</feature> <feature>appsecurity-2.0</feature> </featuremanager> <zosconnect_zosconnectsericerestclientbasicauth id="fredbasicauth" username="fred" password="{xor}os06oy8oow=="/> <zosconnect_zosconnectsericerestclient id="restclientsericey" host="remotehostname" port="8800" uri="/remote/endpoint" httpmethod="post" basicauthref="fredbasicauth" /> <zosconnect_zosconnectserice sericename="sericey" sericeref="restclientsericey" /> The configuration enables the user name and password that is configured for the zosconnectsericerestclientbasicauth element to be propagated when the request to the remote REST application endpoint is made. 3. Optional: Configure certificate authentication. Add the appsecurity-2.0 feature to the serer.xml file. The example shows how to configure the client keystore and client truststore and associate them with the zosconnectsericerestclient configuration. Chapter 6. Configuring 147

156 Configuring interceptors <featuremanager> <feature>zosconnect:zosconnect-2.0</feature> <feature>appsecurity-2.0</feature> </featuremanager> <keystore id="clientkeystore" password="zosconnect" location="${serer.config.dir}/resources/security/clientkey.jks" /> <keystore id="clienttruststore" password="zosconnect" location="${serer.config.dir}/resources/security/clienttrust.jks" /> <ssl id="sslcertificates" keystoreref="clientkeystore" truststoreref="clienttruststore"/> <zosconnect_zosconnectsericerestclient id="restclientsericey" connectionref="restclientconnectiony" uri="/remote/endpoint" httpmethod="put" /> <zosconnect_zosconnectsericerestclientconnection id="restclientconnectiony" basicauthref="fredbasicauth" connectiontimeout="30s" host="remotehostname" port="8800" receietimeout="60s" sslcertsref="sslcertificates" /> <zosconnect_zosconnectserice sericename="sericey" sericeref="restclientsericey" /> z/os Connect EE proides a framework that enables interceptors, or methods, to work with operations such as serice inoke, status, start, or stop. Interceptors are OSGi serices that implement the com.ibm.zosconnect.spi.interceptor Serice Proider Interface (SPI) that is proided by z/os Connect EE. About this task You can use interceptors for many purposes. z/os Connect EE does not know what an interceptor is used for. For example, an interceptor might be written to perform some infrastructure setup that is based on the message payload before the request is processed. z/os Connect EE proides a copy of the input request payload to all interceptors. z/os Connect EE proides the zosconnect_zosconnectserice configuration element that enables the administrator to configure a set of attributes that apply to a particular serice. One of these attributes is interceptorsref, which points to a configuration element that lists one or more interceptors to run for a specific serice. This task describes how to define a z/os Connect EE interceptor and a list of interceptors, and also explains how to associate the interceptors with one or more serices in the configuration for a serer. This task also includes a description of how to enable the z/os Connect EE, proided audit and authorization interceptors for serices. If defined, interceptors are called in a specific order: 1. Global interceptor pre-inoke methods 2. User interceptor pre-inoke methods 148 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

157 3. API is inoked 4. User interceptor post-inoke methods 5. Global interceptor post-inoke methods Within each category, the sequence attribute determines the order in which the interceptors run. For pre-inoke methods, the lowest number runs first. For post-inoke methods, the lowest number runs last. If the sequence numbers are the same, there is no set order. If the sequence is not defined (or incorrectly defined), these interceptors run their pre-inoke methods after all other interceptors of the same type, and their post-inoke methods before all other interceptors of the same type. For more information, see Interface Interceptor. Procedure 1. Update the <zosconnect_zosconnectserice> element for each serice in your serer.xml configuration for which you want to enable an interceptor or list of interceptors for. <!--z/os Connect serice definitions --> <zosconnect_zosconnectserice id="zcs1" sericename="recordopscreate" sericeref="wolaopscreateserice" interceptorsref="opscreateinterceptorlist"/> 2. Create the associated <zosconnect_zosconnectinterceptors> element. <!-- User Interceptor definitions --> <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. Interceptor implementations use the Liberty SPI extensions. These interceptors must define their metatypes to the z/os Connect EE profile serer and create an implementation of the com.ibm.zosconnect.spi.interceptor class. In this example, an implementation of this class is created with a metatype that defines the elements usr_userinterceptorone and usr_userinterceptortwo. The name of the configuration element where the list of interceptors is proided is called 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 is the name of the element in the configuration that describes the set of z/os Connect EE interceptors that apply to all of the serices in the configuration. <zosconnect_zosconnectmanager globalinterceptorsref="globalinterceptors"/> <!-- User Interceptor definitions --> <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-proided audit, authorization, or logging interceptors for a serice or set of serices. The z/os Connect EE-supplied audit interceptor implements the com.ibm.zosconnect.spi.interceptor SPI to store audit or tracking information in the z/os System Management Facility (SMF) data sets. The authorization interceptor gies the ability to erify that the current authenticated user has the authority to perform the requested action. Examples of actions that are checked include serice action=inoke, start, or stop. You enable these interceptors Chapter 6. Configuring 149

158 <!-- z/os Connect serice definition --> <zosconnect_zosconnectserice id="zcs1" sericename="recordopscreate" sericeref="wolaopscreateserice" interceptorsref="opscreateinterceptorlist1"/> for one or more serices in the z/os Connect EE serer configuration. The following example shows how to enable both the audit and authorization interceptors for a single serice: <!-- Audit and authorization interceptor definitions --> <zosconnect_authorizationinterceptor id="authinterceptor1" sequence="1"/> <zosconnect_auditinterceptor id="auditinterceptor1" sequence="2"/> <zosconnect_zosconnectinterceptors id="opscreateinterceptorlist1" interceptorref="auditinterceptor1, authinterceptor1"/> Configuring the file system logger interceptor The file system logger interceptor enables z/os Connect EE users to log request information in a file. About this task This function is aailable when you configure z/os Connect EE. Table 25. Descriptions of the entries that are in the generated log file Entry DateTime ThreadID UserName RequestID RemoteAddress LocalAddress MessageType MessageSize MessageData Description The date and time that is calculated by the logger interceptor before the serice inocation The ID of the thread under which the serice request is being processed The user name for which the request is being processed The request tracking ID that is generated by z/os Connect EE The Internet Protocol (IP) address of the client who originated the request or last proxy that sent the request The Internet Protocol (IP) address of the interface on which the request was receied Identifies whether the payload is from a request or a response The character size of the payload A request or response payload ***************************************************************************** SererName: com.ibm.zosconnect.interceptor.logger.fs ***************************************************************************** DateTime: _ ThreadId:47 UserName:Fred RequestID: RemoteAddress: LocalAddress: MessageType:REQUEST MessageSize:27 MessageData:{"payload":"HELLO_SERVICE"} DateTime: _ ThreadId:47 UserName:Fred RequestID: RemoteAddress: LocalAddress: MessageType:RESPONSE MessageSize:26 MessageData:{"payload":"HELLO_CALLER"} 150 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

159 The file system logger interceptor is configured ia a zosconnect_filesystemloggerinterceptor entry in serer.xml. This entry has the following attributes: Table 26.. Descriptions of the entries that are in the zosconnect_filesystemloggerinterceptor Attribute name Data type Default alue Description buffersize int 8192 Buffer size setting to be used when the bufferlogging attribute is set to true. bufferedlogging boolean false Indicates whether entries to the log is buffered before they are written to the log file. encoding string UTF-8 Encoding used when writing to the log file. id string A unique configuration ID. logname string Log file name pattern used for payload logging. logoption RESPONSE REQUEST ALL ALL Log option that controls what is logged. RESPONSE Indicates that only response data is logged. REQUEST Indicates that only request data is logged. ALL Indicates that both request and response data are logged. logpath string File system location in which the file log is created. If the enironment ariable ${serer.output.dir} is configured, its alue is used by default. maxpayloadsize int Maximum payload size in bytes allowed to be written to the log file. rollofflogpolicy SIZE DURATION SIZE Indicates that log file should be rolled off based on size or duration. SIZE Indicates that the log file should be roll off based on size. DURATION %rollofflogpolicy.duration rollofflogpolicyduration int 1440 Roll off policy duration in minutes. Chapter 6. Configuring 151

160 Table 26. (continued). Descriptions of the entries that are in the zosconnect_filesystemloggerinterceptor Attribute name Data type Default alue Description rollofflogpolicysize int Roll off policy size in bytes. sequence int (Minimum: 0 Maximum: ) 0 Sequence in which the interceptor is processed with respect to others. Procedure 1. 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 serice requests are logged in a file called globallog_myserer1_yyyy-mm-dd_hh_mm_ss_sss.log, where myserer1 is the name of the serer. The only required configuration element is the logname attribute definition. The configuration element accepts a %SERVERNAME% string that is replaced with the name of the serer when the log is created. The default log file location is ${serer.output.dir}/logs/zosconnect. For more information about aailable configuration attributes and default alues, see Configuration elements on page 283 in the Reference section. You can also configure the filesystemloggerinterceptor element for specific serices. <zosconnect_filesystemloggerinterceptor id="sericeyfilesystemlogger" logname="serice1log" logpath="/zosconnect/logs" logoption="response" maxpayloadsize="30720"/> <zosconnect_zosconnectinterceptors id="sericeyinterceptorlist" interceptorref="sericeyfilesystemlogger" /> <zosconnect_zosconnectserice sericename="sericey" sericeref="sericey" interceptorsref="sericeyinterceptorlist"/> <usr_myserice id="sericey"/> In the example, information is logged in a file called serice1log_yyyy-mmdd_hh_mm_ss_sss.log which is located in the path /zosconnect/logs. The log path is a fully qualified path. Only response data is logged for all incoming requests that target sericey. The maximum JSON payload is configured to be 30,720 characters, so any JSON response payload that is greater than 30,720 characters is truncated to the configured maximum payload size. 2. Optional: Configure the bufferedlogging and the buffersize attribute definitions to enable buffered logging. The default buffer size is 8 kilobytes. All records in the buffer are flushed to the disk when the buffer becomes full. Using buffered logging is appropriate when performance is a concern and when it is acceptable for a possible loss of records from the buffer during a failure condition. <zosconnect_filesystemloggerinterceptor id="globalfilesystemlogger" logname="globallog_%servername%" bufferedlogging="true" buffersize="16384"/> 3. Optional: Configure the rollofflogpolicy attribute. This policy states when a new file is created based on when the actie log file reaches the specified or default file size of 50 megabytes, or when the specified or default time of 24 hours expires since the actie log file was created. In the following example, a new file is created when the file reaches 16 kilobytes in size. The naming schema is the same: globallog_myserer1_yyyy-mm-dd_hh_mm_ss_sss.log. The difference between the newly created log files is the time stamp that is used when the new file is created: 152 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

161 <zosconnect_filesystemloggerinterceptor id="globalfilesystemlogger" logname="globallog_%servername%" rollofflogpolicy="size" rollofflogpolicysize="16384"/> Auditing and tracking To audit and track requests, you can use the audit interceptor included with z/os Connect EE, or lie statistics for z/os Connect EE serices. Audit Interceptor You can use a RESTful interface to retriee lie statistics data for z/os Connect EE serice requests. For example, to obtain the feature start time, total number of serice requests and the distribution of requests. You can enable the interceptor in z/os Connect EE on a single or group of z/os Connect EE serices. The z/os Connect EE audit interceptor records request actiity to the SMF data store on z/os operating systems. SMF type 123, subtype 1 records are generated. Note: For z/os Connect EE to write to SMF, the user ID under which z/os Connect EE runs, must hae READ access to the RACF BPX.SMF profile of the FACILITY 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 UNIX System Serices Planning documentation. The SMF type 123 subtype 1 record contains the following information in sequence: 1. Standard SMF header 2. SMF type 123 subtype 1 header extension 3. Triplet #1 for the serer identification section 4. Triplet #2 for the user data section 5. Serer 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 alues, 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 to format the SMF 123 subtype 1 records. The JCL uses the z/os ICETOOL utility and formats each of the following sections. Standard SMF header The standard SMF header that is used by z/os Connect EE is a Standard SMF Record Header for Records with Subtypes. Note: The first 4 bytes of the standard SMF header, the record descriptor word (RDW), contains the fields SMFxLEN and SMFxSEG. The SMF offload utility, IFASMFDP, strips the RDW from each record so, offsets for the subsequent header fields must be adjusted. SMF type 123 subtype 1 header extension The SMF type 123, subtype 1, header extension is defined in Table 1: Chapter 6. Configuring 153

162 Table 27. SMF 123 subtype 1 header extension. Offset Length Data type. Data 0 4 Binary Subtype ersion number. 4 4 Binary Number of triplets. 8 4 Binary Index of this record Binary Total number of records EBCDIC Record continuation token. Note: SMF 123 subtype 1 records are typically non-spanning. In this case, the alue of index is 0 (zero), total records is 1 (one), and the records continuation token is 8 bytes of nulls. The SMF type 123 subtype 1 header for SMF records is followed by two triplets. The first triplet points to the serer identification section. Only one serer identification section is allowed. The second triplet points to the user data section, which can hae multiple instances. Triplet #1 for the serer identification section Triplet #1 describes the serer identification section that is detailed in Table 2. The serer data section consists of the following parameters: (alues in decimal). Table 28. Serer data section parameters. Offset Length Data type. Data 0 4 Binary Version of SMF record. 4 8 Character System name Character Sysplex name Character Job ID (jsabjbid) Character Job name (jsabjbnm) Binary SToken (assbstkn) N/A Resered. Triplet #2 for the user data section Triplet #2 describes the user data sections that are detailed in Tables 3 and 4. The user data section consists of the following parameters (alues in decimal): Table 29. User data section parameters. Offset Length Data type. Data 0 4 Binary Version. 4 4 Binary Type 8 4 Binary Length of data (user data sections are 2 KB, this field indicates how much of that is used). 12 N/A Data (See Table 4). For z/os Connect EE, the alue of the user data type field is 66 (hexadecimal) or 102 (decimal). The data contains the following parameters: 154 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

163 Table 30. User data section parameters. Offset Length Data type. Data 0 4 Binary Version. 4 8 Store Clock (STCK) Store Clock (STCK). Arrial date and time. Completion date and time Character Target URI (EBCDIC, right padded with blanks) Binary Request payload length in bytes Character API or Serice name (EBCDIC, right padded with blanks) Character Method (EBCDIC) Binary Response payload length in bytes Character User name (EBCDIC, right padded with blanks) Binary Request ID (bytes, right padded with zeros) Boundary padding (zero) Character Serice grouping name (EBCDIC, right-padded with blanks) Character Mapped user name (EBCDIC, right-padded with blanks). Retrieing lie statistic data Feature start time, total number of serice requests and the distribution of requests are aailable by using this operational capability. Valid authenticated clients are able to use a HTTP GET for one of the following URIs to retriee statistics about the z/os Connect EE serer: Get statistics for a single serice. For example, to get statistics for the HelloWorld serice: Get statistics for all serices in the serer: Get statistics for all serices under a single serice proider by specifying the proider="<serice proider name>" query parameter. For example, to retriee statistics for all serices that are associated with the proider name of WOLA-1.0 use the following URL The response data is returned in JSON object format. Configuring the audit interceptor You can use the audit interceptor included with z/os Connect EE, to audit and track 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 EE serices. Chapter 6. Configuring 155

164 Procedure Enable the audit interceptor supplied with z/os Connect EE for a serice or set of serices. The audit interceptor implements the com.ibm.zosconnect.spi.interceptor SPI to store auditing and tracking information in the audit interceptor supplied with z/os System Management Facility (SMF) data sets. The following is an example that shows how to enable the audit interceptor for a single serice: <!-- Audit interceptor configuration --> <zosconnect_auditinterceptor id="auditinterceptor" sequence="1"/> <!-- Interceptor list configuration --> <zosconnect_zosconnectinterceptors id="interceptorlist1" interceptorref="auditinterceptor"/> <!-- z/os Connect serice definitions --> <zosconnect_zosconnectserice id="zcs1" sericename="recordopscreate" sericeref="wolaopscreateserice" interceptorsref="interceptorlist1"/> You can use the sequence parameter to control the sequence in which the interceptors are called. For more information, see zosconnect_auditinterceptor on page 301 in the Reference section of this documentation. Configuring API specific interceptors The z/os Connect EE administrator can configure a user-defined set of interceptors for an API. The zosconnectapi element represents a single API definition that is made aailable at runtime by the serer associated with a gien serer.xml configuration file. The zosconnectapi element accepts an interceptorsref element, which can be used by the z/os Connect EE administrator to configure the API with a user-defined set of interceptors. These interceptors are inoked wheneer a request is matched to that API for inocation (pre-inoke), and before the result is returned to the caller (post-inoke). 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 serer.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 alues true or false, and defaults to true. You can use this element to exclude indiidual APIs from a configured global interceptor. For example, the following configuration would exclude the Health API from any global interceptor definition: 156 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

165 <zosconnect_zosconnectapis location=""> <zosconnectapi name="health" interceptorsref="medstaffinterceptorlist" runglobalinterceptors="false" /> <zosconnectapi name="foo" interceptorsref="admininterceptorlist" /> <zosconnectapi name="bar" interceptorsref="patientinterceptorlist" /> </zosconnect_zosconnectapis> Configuring Data Transformers IBM z/os Connect EE proides the ability to optionally transform request and response payloads that are used for calling a business asset on z/os operating systems. You can create message payload transformers to satisfy specific needs by implementing the com.ibm.zosconnect.spi.dataxform Serice Proider Interface (SPI), which is included with z/os Connect EE. About this task z/os Connect EE proides an implementation that requires the request and response message format be JSON. This product supports the conersion of the request to a byte array, which can be mapped by a natie 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 is used by a supplied utility to generate a binding file and JSON request and response schema files. The bind file that is generated by this utility is used by z/os Connect EE to complete the data conersion to and from JSON and natie data formats as requests arrie and responses are returned. You can retriee the JSON schemas for the request and response message with a RESTful API call that is proided by z/os Connect EE. z/os Connect EE proides the zosconnectserice configuration element that enables the administrator to configure a set of attributes that apply to a particular serice. One of these attributes is dataxformref, which points to a data transformation configuration that is to be used for a specific serice. This task describes how the data transformer supplied with z/os Connect EE is used. Note: 1. In the examples shown in steps 1 & 2, the sericename and bindfilesuffix must 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 sericename specified in the zosconnectserice element with _request or _response appended. The alues, including the file type, must match the requestschemasuffix or responseschemasuffix respectiely. For example: recordopscreate_request.json and recordopscreate_response.json. These files must reside in /u/json. Procedure 1. Update the zosconnectserice element for each serice in your serer.xml configuration for which you want to enable the data transformation supplied by z/os Connect EE. <!-- z/os Connect serice definition --> <zosconnect_zosconnectserice id="zcs1" sericename="recordopscreate" sericeref="wolaopscreateserice" dataxformref="xformjson2byte"/> 2. Create the associated zosconnectdataxform element. Chapter 6. Configuring 157

166 <!-- z/os Connect data transformation proider --> <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 serices. Set the globadataxformref of the zosconnectmanager element to the configured data transformer's ID that is intended for global use. If both global and serice data transformers are defined and requests come in for a serice with a configured data transformer, z/os Connect EE will use the data transformer configured specifically for the serice. <zosconnect_zosconnectmanager globaldataxformref="globaldataxform"/> <!-- z/os Connect data transformation proider --> <zosconnect_zosconnectdataxform id="globaldataxform" bindfileloc="/u/bindfiles" bindfilesuffix=".wsbind" requestschemaloc="/u/json" responseschemaloc="/u/json" requestschemasuffix=".json" responseschemasuffix=".json"/> Creating bind and schema files z/os Connect EE proides the ability to optionally transform request and response payloads 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 setup complies with these conditions: Your high-leel language data structures must meet the following criteria: The data structures must be defined separately from the source program. For example, in a COBOL copybook. If your PL/I or COBOL application program uses different data structures for input and output, the data structures must be defined in two different members in a partitioned data set. If the same structure is used for input and output, the structure must be defined in a single member. For C and C++, your data structures can be in the same member in a partitioned data set. The language structures must be aailable in a partitioned data set. You must define to Open Multiple Virtual Storage (OMVS) the user ID that BAQLS2JS or BAQJS2LS uses to run. The user ID must hae 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. The user ID must hae a sufficiently large storage allocation to run Jaa. You can use any supported ersion of Jaa. The BAQLS2JS and BAQJS2LS utilities use the Jaa ersion that is specified by JAVA_HOME in BAQLS2JS.jcl and BAQJS2LS.jcl. Otherwise, the ID uses the Jaa ersion specified on the PATH statement. About this task The BAQLS2JS utility reads a COBOL copybook, PLI structure, or C structure file and generates a binding file and JSON schema files. The BAQJS2LS utility reads a JSON schema and generates the corresponding binding file and language structure file. The utilities are similar to the existing DFHLS2JS and DFHJS2LS tools, which are part of the CICS Transaction Serer Mobile Extensions feature pack. 158 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

167 Configuring SARs Procedure 1. Copy the BAQLS2JS.jcl or BAQJS2LS.jcl procedure to a writeable directory or dataset 2. Use the BAQLS2JS procedure to generate a z/os Connect EE serice binding file from a language structure. You will need to proide JCL to inoke the BAQLS2JS procedure with the input parameters. Refer to the BAQLS2JS reference documentation for information on the input parameters and an example job to help you use the procedure. When you submit the BAQLS2JS procedure, the utility generates the serice binding file to the location that you specified with the WSBIND parameter. The generated JSON schemas are placed in the location that you specified with the JSON-SCHEMA-REQUEST and JSON-SCHEMA-RESPONSE parameters. For more information, see Conersion for z/os Connect Enterprise Edition data transformation on page 250. Note: In order to generate a serice archie file, SERVICE-ARCHIVE and SERVICE-NAME must be specified in BAQLS2JS. 3. Reiew the generated JSON schema. These schemas are used to define the input and output data formats for interacting with the z/os Connect EE serice. The application deeloper must use these schemas when creating an application to call the serice and pass the JSON request payload. Note: Changing the generated schema inalidates the generated binding file at WSBIND. If you want to change the schema, for example, to rename the fields within the schema, you must use BAQJS2LS to generate a new binding file, and a new set of language structures. The application program must be re-compiled to use the new language structures. You can add the zosconnect_serices element to serer.xml and configure where serice archie packages for the REST Client serice proider are stored. You copy a SAR file into a directory where it can be accessed during API deelopment. The definition of the serice must be added to the serer.xml configuration file before it can be used. Important: This feature is supported for the REST Client serice proider only. The zosconnect_serices element in the configuration file defines the z/os Connect EE serices to be deployed. For example, <zosconnect_serices location="/ar/zosconnect/serices" updatetrigger="polled" pollingrate="100ms <serice name="addcustomer" /> <serice name="inquirecustomer" /> <serice name="updatecustomer" /> </zosconnect_serices> The serer.xml configuration file can contain the following elements: zosconnect_serices Only one zosconnect_serices element is allowed. The location parameter is optional and specifies where the SAR packages are deployed. If it is not defined, then the ${serer.config.dir}/resources/zosconnect/serices directory is used as the SAR package installation directory. When the serer is started, all the SAR packages are deployed in the serer. Chapter 6. Configuring 159

168 Configuring APIs serice property The updatetrigger parameter is optional and controls when z/os Connect EE is notified about changes in the serices directory. The default alue of the updatetrigger parameter is disabled. For more information, see zosconnect_serices on page 306 in the Reference section. One or more serice elements can be contained in the zosconnect_serices element. Supports other optional attributes that, for example, can be used to define authentication, authorization, or interceptors specific to a serice. For more information, see Configuration elements on page 283. The attributes admingroup, inokegroup, operationsgroup, readergroup, requireauth, and requiresecure are aailable to specify authentication and authorization for a serice. For more information, see Chapter 8, Securing, on page 177. The attributes interceptorsref and runglobalinterceptors are aailable to specify interceptors for a serice. For more information, see Configuring API specific interceptors on page 156. One or more property elements can be contained in the serice element. Defines optional properties for the serice proider. Properties can only be defined by editing the serer.xml file. Properties remain in the configuration file after the SAR file is moed or deleted. Related concepts: Chapter 12, Administering SARs, on page 231 Use this information to learn how to manage your serice archies. How to add the zosconnect_zosconnectapis element to serer.xml and configure where API packages are stored. Note: For information about deploying APIs with the Administration Interface, see Chapter 13, Administering APIs, on page 233. A new element is added to serer.xml, which defines the z/os Connect EE APIs are to be deployed and, optionally, the APIs that are expected to be deployed. For example, <zosconnect_zosconnectapis location="/ar/zosconnect/apis" updatetrigger="polled"> <zosconnectapi name="health" /> <zosconnectapi name="inentory" /> <zosconnectapi name="ordering" /> </zosconnect_zosconnectapis> The serer.xml configuration file can contain the following elements: zosconnect_zosconnectapis Only one zosconnect_zosconnectapis element is allowed. The location parameter is optional and specifies where the API packages are deployed. If it is not defined, then the ${serer.config.dir}/resources/zosconnect/apis directory is used as 160 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

169 zosconnectapi the API package installation directory. When the serer is started, all the API packages in the location directory are deployed in the serer. Note: The serer does not create the API package installation directory. If the directory does not exist, then APIs cannot be dynamically deployed by the API Editor or RESTful administration interface. Either change the location to a directory that exists and restart the serer, or create the required directories. The updatetrigger parameter is optional and controls when z/os Connect EE is notified about changes in the apis directory. The apis directory is specified on the location parameter. For more information, see Configuration elements on page 283. You can use the nested zosconnectapi elements to specify the APIs that are expected to be in the location directory. If a defined API is not found in the location directory, then a message is written to the log. If an API package is inalid, then the API fails to load and an error is written to the log. Note: The zosconnect_zosconnectapis element cannot be changed while the serer is running; its alue is set when the serer is started. One or more zosconnectapi elements can be contained in the zosconnect_zosconnectapis element. Supports other optional attributes that, for example, can be used to define authentication, authorization, or interceptors specific to an API. For more information, see Configuration elements on page 283. The attributes admingroup, inokegroup, operationsgroup, readergroup, requireauth, and requiresecure are aailable to specify authentication and authorization for an API. For more information, see Chapter 8, Securing, on page 177. The attributes interceptorsref and runglobalinterceptors are aailable to 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 the serer is running, proided the serer is enabled for dynamic configuration. For more information about enabling the serer for dynamic configuration, see Administering Liberty in the WebSphere Application Serer Liberty documentation. Related information: Chapter 13, Administering APIs, on page 233 Use this information to learn how to manage your APIs. Configuring Cross-Origin Resource Sharing on a z/os Connect Enterprise Edition Serer z/os Connect EE supports Cross-Origin Resource Sharing (CORS). CORS is a mechanism that allows a resource to be requested from a different domain than the one from which the resource originated. Usually, client applications that support CORS send a preflight request before some certain Chapter 6. Configuring 161

170 cross-domain requests are sent. z/os Connect EE serers are enabled to answer preflight requests by using different methods depending on the different ersions of z/os Connect EE. 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 ersion. 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 support this function. For the latest ersion of z/os Connect EE, CORS and CORS preflight checks are enabled by using the Liberty CORS function. When a serer is created, a cors element is automatically added to the serer.xml. The cors element defines the CORS settings for the URL being setup in the domain. The following excerpt from the serer.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 topic Configuring Cross-Origin Resource Sharing on a Liberty Serer in the WebSphere Application Serer for z/os Liberty Knowledge Center Serer configuration updates on demand A running z/os Connect EE serer uses information from arious files that are stored in UNIX System Serices. Serer configuration files. Data transformation files, if any of your z/os Connect EE serices use DataXForms. If you need to modify, create or delete these files while the serer is running, you can use any one of these methods: 1. Polling the files at regular interals to check whether any changes were made and update the serer with the detected changes. Continuous polling uses CPU resources. This method can be useful in a deelopment or test enironment. 2. Disable dynamic updates. This method requires the serer to be restarted to pick 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 enironment. The update mechanism is specified on the following serer configuration elements: Updates to the serer configuration files are controlled by the config configuration element. For more information, see Configuration Management (config) in the Reference section. Updates to data transformation files are controlled by the zosconnect_zosconnectdataxform configuration element. For more information, see zosconnect_zosconnectdataxform on page 312 in the Reference section. Updates to APIs are controlled by the zosconnect_zosconnectapis configuration element. For more information, see zosconnect_zosconnectapis on page 309 in the Reference section. 162 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

171 Using an MBean to trigger updates An MBean called the FileNotificationMBean is proided, which can be called to trigger an update of a running serer. The MBean can make the following updates to the serer: Use new, modified, or deleted configuration files. Use new, modified, or deleted data transformation files. Use new, modified, or deleted API archie files. MBeans are inoked by using a Jaa Management Extensions (JMX) connector. Two supported JMX connectors are aailable: The local connector is enabled through the Liberty feature localconnector-1.0. Access through the local connector is protected by the policy that is implemented by the SDK in use. The client must run on the same host as the serer, and under the same user ID. The REST connector is enabled through the Liberty feature restconnector-1.0. Remote access through the REST connector is protected by a single administrator role. In addition, SSL is required to keep the communication confidential. You must configure the JMX connectors as described in the topics Configuring local JMX connection to Liberty or Configuring secure JMX connection to Liberty in the WebSphere Application Serer documentation. Note: If you intend to use the REST connector with SAF authentication, the following steps are required. Instead of following the link to the topic Map to the administrator role for Liberty, see the alternatie topic Mapping the administrator role for Liberty on z/os. Define the following RACF definitions (or equialent definitions for your SAF proider). 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 granting administrator authority to, and <SAF_profilePrefix> is alue of the profileprefix attribute specified on the serer configuration file element safcredentials. The default profileprefix alue is BBGZDFLT. For more information, see Liberty: Accessing z/os security resources using WZSSAD in the WebSphere Application Serer documentation. MBeans can be called from jaa based client applications. For example, a Jaa program, Jython script, or a REST API. Inoking the FileNotificationMBean from a jaa program Jaadoc for the FileNotificationMBean is proided in the file <installation_dir>/ wlp/de/api/ibm/jaadoc/com.ibm.websphere.appserer.api.basics_1.2- jaadoc.zip. The following jaa code snippet proides an example of using the REST connector to inoke the FileNotificationMBean method notifyfilechanges. This example updates the running serer configuration with changes that are made to either of two serer configuration files: /ar/zosconnect/serers/serername/serer.xml and /ar/zosconnect/serers/serername/includedconfig.xml. Chapter 6. Configuring 163

172 /** z/os Connect serer hostname */ priate final static String hostname = "companyhost.company.com"; /** z/os Connect serer HTTPS port */ priate final static String httpsport = "9443"; /** z/os Connect serer administration role user */ priate final static String adminuserid = "adminuser"; /** z/os Connect serer administration role user s password */ priate final static String adminpassword = "adminpswd"; /** Truststore containing z/os Connect serer s public certificate */ priate final static String truststorelocation = "/mydir/trust.jks"; /** Truststore password */ priate final static String truststorepassword = "truststorepswd"; /** Absolute paths of configuration files to monitor */ priate final static String configfilepath1 = "/ar/zosconnect/serers/serername/serer.xml"; priate final static String configfilepath2 = "/ar/zosconnect/serers/serername/includedconfig.xml"; /** FileNotificationMBean name */ priate final static String MBEAN_FILE_NOTIFICATION = "WebSphere:serice=com.ibm.ws.kernel.filemonitor.FileNotification /** FileNotificationMBean method notifyfilechanges signature */ priate final static String[] MBEAN_FILE_NOTIFICATION_NOTIFYFILECHANGES_SIGNATURE = new String[] { Collection.class.getName(), Collection.class.getName(), Collection.class.getName() }; /** JMX serice URL*/ priate static String jmxsericeurl = "serice:jmx:rest://" + hostname + ":" + httpsport + "/IBMJMXConnectorREST";... public oid inokefilenotificationmbean() {... // Get secure remote JMX MBean serer connection System.setProperty("jaax.net.ssl.trustStore", truststorelocation); System.setProperty("jaax.net.ssl.trustStorePassword", truststorepassword); HashMap<String, Object> enironment = new HashMap<String, Object>(); enironment.put("jmx.remote.protocol.proider.pkgs", "com.ibm.ws.jmx.connector.client"); enironment.put("com.ibm.ws.jmx.connector.client.disableurlhostnameverification", Boolean.TRUE); enironment.put(jmxconnector.credentials, new String[] { adminuserid, adminpassword }); JMXSericeURL url = new JMXSericeURL(jmxSericeURL); JMXConnector jmxconnector = JMXConnectorFactory.newJMXConnector(url, enironment); jmxconnector.connect(); MBeanSererConnection mbsc = jmxconnector.getmbeansererconnection(); // Inoke FileNotificationMBean ObjectName filemonitormbeanname = new ObjectName(MBEAN_FILE_NOTIFICATION); if (mbsc.isregistered(filemonitormbeanname)) { // Create a list of absolute paths of each file to be checked List<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 }; // Inoke FileNotificationMBean method notifyfilechanges mbsc.inoke(filemonitormbeanname, "notifyfilechanges", params, MBEAN_FILE_NOTIFICATION_NOTIFYFILECHANGES_SIGNATURE); } else { System.err.println("MBean inoke request failed " + MBEAN_FILE_NOTIFICATION + " is not registered."); }... } Note: The client-side REST connector, which is proided in wlp/clients/ restconnector.jar, must be in the class path that is used to compile and run a jaa application that inokes an MBean. 164 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

173 Inoking FileNotificationMBean from the REST API MBeans can also be inoked by using a REST interface. This method is described in the WASde article Accessing Liberty s JMX REST APIs. As described in that article, if the JMX Connector is installed, you can get help on the syntax that is required to inoke an MBean by making an HTTP GET call to and selecting the MBean operation inocation and JSON grammar for POJO options from the menu. The following instructions proide an example of using the REST API to inoke the FileNotificationMBean method notifyfilechanges. This example updates the running serer configuration with changes that are made to either of two serer configuration files: /ar/zosconnect/serers/serername/serer.xml and /ar/zosconnect/serers/serername/includedconfig.xml. { } Issue an HTTP POST request to mbeans/websphere%3aserice %3Dcom.ibm.ws.kernel.filemonitor.FileNotificationMBean/operations/ notifyfilechanges with a HTTP header : Content-Type application/json and a request JSON payload as in the following sample. "params":[ { "alue" : [""], "type" : {"classname":"jaa.util.arraylist","items":["jaa.lang.string"]} }, { "alue" : ["/ar/zosconnect/serers/serername/serer.xml","/ar/zosconnect/serers/serername/includedconfig.xml"], "type" : {"classname":"jaa.util.arraylist","items":["jaa.lang.string","jaa.lang.string"]} }, { "alue" : [""], "type" : {"classname":"jaa.util.arraylist","items":["jaa.lang.string"]} } ], "signature":[ "jaa.util.collection", "jaa.util.collection", "jaa.util.collection" ] The FileTransferMBean The FileTransferMBean can be used to transfer your API archie files from a remote 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 serer instance. This MBean is aailable as part of the restconnector-1.0 feature. Jaadoc is proided in the file <installation_dir>/wlp/de/api/ibm/jaadoc/ com.ibm.websphere.appserer.api.restconnector_1.1-jaadoc.zip. Note: To use this MBean, you must also define the remotefileaccess serer configuration element attributes readdir and writedir to define the directories to which the restconnector within that serer is authorized to read to and write from. For more information about this element, see Remote File Access (remotefileaccess) in the WebSphere Application Serer documentation. For more information about using this MBean, see the WASde article Using File Serice and File Transfer MBeans with Liberty. Chapter 6. Configuring 165

174 166 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

175 Chapter 7. High aailability Workload distribution The key concepts of a high aailability (HA) enironment and how they can be implemented with z/os Connect EE. This information is aimed at architects and z/os system programmers who need to implement a z/os Connect EE HA enironment. Implementation requires z/os system programming skills, such as the use of TCP/IP workload balancing software and creation of zfs file systems. By implementing a high aailability solution, you can minimize the impact on daily operations of the failure of one or more components within the oerall system. You can use arious IBM or third-party products with z/os Connect EE to build such a system. You hae a number of options aailable so that you can choose a solution that suits the needs of your organization. The solution might be just two z/os Connect EE serers that run in a single LPAR. Or you can design a more complex parallel sysplex solution with many z/os Connect EE serers that are spread across multiple LPARs. It is also necessary to plan for ariations in workloads, especially increased workloads, when it might be necessary to increase the capacity of the system. The system must respond in a predictable way to workload ariation to meet SLAs. For z/os Connect EE, scalability can be achieed by manually increasing the number of serers. High aailability can be achieed with z/os Connect EE by the workload distribution of HTTP and HTTPS API and serice requests from clients across seeral serers with shared configuration. For more information, see Workload distribution and Sharing serer configuration on page 170. To ensure that workload distribution can route requests to any configured z/os Connect EE serer, the serers must be maintained as clones of each other. That is, the serers hae the same configuration with the same z/os Connect APIs and serices deployed. A z/os Connect EE HA enironment can take adantage of TCP/IP load balancing technologies. Requests to inoke APIs and serices in z/os Connect EE serers are made by using HTTP, which means that an HA enironment can use known TCP/IP load balancing technologies to distribute connections from clients across multiple serers. TCP/IP port sharing can be used to load balance requests across multiple z/os Connect EE serers in the same z/os LPAR. Sysplex Distributor can be used to distribute requests across multiple z/os Connect EE serers in a Parallel Sysplex. Used with TCP/IP port sharing within each LPAR. By configuring the httpendpoint in the serer configuration file of multiple z/os Connect EE serers to listen on the same shared TCP/IP port, clients can send requests to a single hostname and port and allow the TCP/IP load balancing technologies to distribute the request to one of the aailable serers. z/os Connect Copyright IBM Corp. 2015,

176 EE APIs and serices hae no persistent state and do not use HTTP sessions, so no affinities exist between client applications and z/os Connect EE serers, simplifying both workload distribution and the retry of failed requests. TCP/IP port sharing The TCP/IP port sharing component of the z/os TCP/IP Communications subsystem allows multiple listeners to listen on the same combination of port and IP address. Port sharing can be configured to distribute HTTP requests across multiple z/os Connect EE serers in a single LPAR. Shared ports are defined by the PORT statement in the TCP/IP profile. A shared port definition reseres a specific port number to be shared by specific z/os address space job names. Two options of the PORT statement control port sharing: SHAREPORT Requests are distributed by a weighted round-robin distribution method based on the Serers' accept Efficiency Fractions (SEFs) of the listeners that share the port. SHAREPORTWLM Requests are distributed based on WLM serer-specific recommendations, which are modified by the SEF alues for each listener. Load balancing can be more efficient if you consider the status that is proided by dynamic feedback from the z/os Workload Manager (WLM). When you configure port sharing for z/os Connect EE, define shared ports for any ports that receie HTTP or HTTPS requests to inoke APIs or serices. For example, the port alues specified on the httpendpoint element with id="defaulthttpendpoint" in your serer's configuration file. For multiple z/os Connect EE serer address spaces to share a port, their job names must start with the same characters. It is the common portion of the job name that must be specified on the PORT definition. For example, to uniquely identify two serers: 1. Use the baqstrt.jcl started task procedure proided in /usr/lpp/zosconnect/ <ersion>/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. See Starting a system task from a console in the z/os MVS System Commands documentation. If you choose to use identifiers, be aware that it is the common portion of the identifier alue that is used as the job name in the shared port definition. Related information: Considerations for multiple serers sharing a TCP port in the z/os Communications Serer IP Configuration Guide. TCP/IP profile (PROFILE.TCPIP) and configuration statements in the z/os Communications Serer: IP Configuration Reference documentation. PORT statement in the z/os Communications Serer: IP Configuration Reference documentation. 168 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

177 Sysplex distributor Sysplex Distributor is the strategic IBM solution for connection workload balancing across an IBM Parallel Sysplex. Sysplex Distributor is a component of IBM z /OS Communications Serer and proides TCP/IP load balancing across multiple LPARs. It can be combined with TCP/IP port sharing. Sysplex distributor is a combination of the high aailability features 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 the workload of each of the target stacks. The WLM workload information is based on a comparison of aailable general CPU capacity for each target system. z/os Connect EE is a Jaa based product, so it can use System z Integrated Information Processor (ziip) capacity. You can configure the TCP/IP stacks to consider the aailable ziip CPU capacity. You can also configure WLM-based forwarding based on serer-specific workload. Related information: Configuring distributed DVIPAs sysplex distributor in the z/os Communications Serer documentation. Workload distribution between z/os Connect EE serers and serice proider SORs Workload distribution depends on a number of factors. Whether you can distribute work between z/os Connect EE serers and a serice proider system of record (SOR) depends on the serice proider you are using and the type of connection that is configured to the z/os subsystem used for the SOR. If the serice proider uses TCP/IP, then TCP/IP port sharing and or Sysplex distributor might be appropriate. The WOLA serice proider has some restrictions: Connections to SORs must be local within the same LPAR. A single serice can be connected to only one SOR. Currently, no options are aailable to allow workload balancing or failoer to an alternatie SOR for WOLA connections from a Liberty profile-based serer. WLM Classification Classify HTTP traffic to improe workload distribution. You can classify HTTP traffic in a z/os Connect EE serer so that it can be managed by z/os workload management (WLM) along with other work in the system by enabling Liberty feature zoswlm-1.0. This identifies work by classification rules and pass that into z/os WLM for mapping to serice classes and reporting classes. Different URIs can hae different priority and performance criteria. Classification of HTTP requests is based on host, port, method, and resource and is configured in the serer configuration file. A WLM enclae is associated with the thread that the request is dispatched on. It is also associated with a WLM Serice Class. A WLM Serice Class is assigned to the WLM enclae by WLM, based on rules that you define in the WLM configuration. The WLM Serice Class indicates the WLM goals for each class of client work, for example, 95% complete in 1 second or less. The WLM Serice Chapter 7. High aailability 169

178 Class also indicates the importance of the goals relatie to other work on the system. WLM uses information that is proided by the Liberty serer during classification to assign a WLM Serice Class. In a high aailability enironment, you can specify the same alue on the WLM Natie Enclae Manager Configuration element for all your serers. For example, <zosworkloadmanager collectionname="<alue>" /> This method allows the serers to use the same collection name in WLM, instead of the default collection name, which is the serer name for each serer. Related information: Sharing serer configuration Enabling workload management for Liberty on z/os in the WebSphere Application Serer for z/os documentation. Workload distribution across a group of serers that use a shared port requires that the same configuration is maintained across all serers. To ensure that workload distribution can route requests to any of the aailable z/os Connect EE serers that use a shared port, the serers must hae the same APIs and serices aailable. Note: Some minor systematic ariations might exist. For example, in a solution that uses WOLA, where each z/os Connect EE serer is configured to use a different CICS region. To aoid the need to manually edit multiple z/os Connect EE serer configuration files with the same content each time an update is required, you can share a configuration file between the z/os Connect EE serers. Sharing a configuration file simplifies administration and maintenance because only a single file needs to be updated and ensures that all serers are using the same configuration. To use a shared a configuration file between serers, you must consider the following aspects: The mechanisms that allow serer configuration to be split into multiple files. Which configuration elements can be shared and which elements must be serer-specific. Where to store the shared configuration file. The following topics describe how to set up a shared configuration. Splitting serer configuration information Configuration elements that are common to all z/os Connect EE serers can be included from a shared configuration file. Each serer must hae a alid Liberty serer configuration file that is called serer.xml in its serer configuration directory ${serer.config.dir}. The following mechanisms can be used to split a serer configuration file into serer-specific content and content that is common to multiple serers: Use include elements in serer configuration files to include additional serer configuration files, in the format: <include location="pathname/filename"/>. For example, each serer's configuration file might contain only those entries that 170 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

179 are specific to that serer and specify an element to include another configuration file whose content is common to all serers. When you use include elements, be aware of the Liberty profile configuration element merging rules. See Liberty:Configuration element merging rules in the WebSphere Application Serer for z/os documentation. Specify each element's attribute in only one of the configuration files to ensure that only one alue takes effect. For more information, see Using include elements in configuration files in the WebSphere Application Serer for z/os documentation. Use properties in serer configuration files to enable an otherwise serer-specific element to be contained in the common serer configuration file. Properties for each serer are defined in a file that is called bootstrap.properties in the serer configuration directory ${serer.config.dir}. The properties are defined in the format of name=alue pairs that are written one line per property. For example, propertyname=propertyvalue. Serer configuration files can reference these properties by using the syntax: ${propertyname}. For example, for two serers to specify unique three part names for WOLA, the configuration file contains the following statements. serer1 has a bootstrap.properties file with the following content: - wola_dgn=zc1dgn - wola_ndn=zc1ndn - wola_sn=zc1svn serer2 has a bootstrap.properties file with the following content: - wola_dgn=zc2dgn - wola_ndn=zc2ndn - wola_sn=zc2svn A shared configuration file might then specify the element by using these properties: <zoslocaladapters wolagroup="${wola_dgn}" wolaname2="${wola_ndn}" wolaname3="${wola_sn]" /> Note: If you update the bootstrap.properties file, you must restart the serer for the changes to take effect. For more information, see Using ariables in configuration files in the WebSphere Application Serer for z/os documentation. Serer-specific configuration elements Whether configuration elements are common or serer specific depends on your enironment, APIs, and serice proiders. When you use the WOLA serice proider, the three part name is deried from the wolagroup, wolaname2, and wolaname3 attribute alues on the local adapter's configuration element zoslocaladapters. This three part name must be unique for each serer in the same z/os LPAR. Location of shared configuration files A shared configuration file must be stored in a location that can be read by all serers. It is good practice to use the Liberty profile's shared directory structure. The shared.config.dir property specifies the location <WLP_USER_DIR>/shared/config. You can use this property name within your serer configuration file. By default the alue of WLP_USER_DIR is /ar/zosconnect, so this location might not be suitable if you want to use shared zfs in a Parallel Sysplex, because the /ar mount point cannot be shared. Howeer, you can customize the alue of the Chapter 7. High aailability 171

180 WLP_USER_DIR enironment ariable before you install z/os Connect EE. For more information, see Installing z/os Connect EE on page 112. In a single LPAR, a UNIX System Serices directory that is not in the ${serer.config.dir} directory structure can be used so that it is not nested in the directory structure of a single serer. In a Parallel Sysplex, you can mount a shared zfs to share a single configuration file between multiple serers. For more information about using shared zfs in a Parallel Sysplex, see z/os File System oeriew. You can further improe the resilience of these file systems by using RAID arrays and DASD mirroring technologies. Alternatiely, you can share configuration files only among the serers in each LPAR and maintain separate physical copies of the file on each LPAR. These files must be kept in sync manually. Related information: Customizing the Liberty enironment in the WebSphere Application Serer for z/os Liberty:Directory locations and properties in the WebSphere Application Serer for z/os Maintenance of API and serice deployments Workload distribution requires z/os Connect EE serers to be kept in sync. To enable workload distribution across a group of serers, the serers must hae the same APIs and serices deployed. Any changes to those APIs or serices must be reflected across all the serers that participate in the shared workload. APIs are deployed to a location directory that is specified by the location attribute of the zosconnect_zosconnectapis element. By default, this attribute contains the serer-specific directory ${serer.config/dir}/resources/zosconnect/apis. Storing the API archie files in a single directory that is shared by all serers ensures that the same ersions of all APIs are aailable in all serers. Files that are associated with Serices can also be stored in UNIX System Serices directories, depending on the serice proider they use. For example, the WOLA serice proider uses the supplied DataXForm to transform JSON payload to bytes. This serice requires WSbind files and JSON schema files whose locations are specified to the zosconnect_zosconnectdataxform serer configuration element. Choosing to store all the serice files in directories that are shared by all the serers ensures that the same ersions of all serices are aailable in all serers. Deciding where to store the API and serice files. The API location directory and any directories that contain serice files must be stored in a location that all serers hae read and write access to. It is good practice to use of the Liberty profile's shared directory structure. The shared.resource.dir property specifies the location $WLP_USER_DIR/shared/ resources. You can use this property name within your serer configuration file. You can choose to create nested subdirectories within this directory that are appropriate for your APIs and serice artifact files. 172 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

181 For more information about storing shared files, see Location of shared configuration files on page 171. Administration and Operation Tasks in an HA enironment In an HA enironment, administration and operation tasks require further considerations. Stopping and starting z/os Connect EE serers in an HA enironment There are some things you must consider when stopping or starting a z/os Connect EE serer When a serer is shutdown, the order of eents causes the z/os Connect EE APIs and serices to become unaailable while the HTTP and HTTPS ports are still enabled. This can result in the client application receiing HTTP response code 404 (Not Found). To aoid this situation, you can disable the HTTP ports before shutting down the serer by setting the enabled attribute on the httpendpoint configuration element to false. As soon as the endpoint is disabled, TCP/IP port sharing will no longer route work to that serer, until the httpendpoint is re-enabled. Note: If the httpendpoint element is defined in a shared configuration file, you will need to oerride the attribute definition to specify the enabled attribute uniquely in each serer, so that you can control the alue per serer. For example, add the following entry to the serer.xml files used by each serer. <!-- Oerride the httpendpoint enabled attribute on a per serer basis --> <httpendpoint id="defaulthttpendpoint" enabled="true" /> When a serer is started, its HTTP ports may be enabled before all the z/os Connect EE APIs and serices are started. In a HA enironment, with an actie workload, requests could be distributed to the starting serer before it is fully initialized. A similar approach could be used to start the serer with the httpendpoint initially disabled and then update the configuration to enable it once the serer startup has completed. Management of z/os Connect EE APIs and serices in an HA enironment Considerations for querying, starting, stopping, deploying, updating, and undeploying APIs and serices in an HA enironment z/os Connect EE proides an administration interface for serices, and a RESTful administration interface for APIs. See The z/os Connect EE administration interface on page 245 and Using the RESTful administration interface on page 235. These administration interfaces connect to the HTTP or HTTPS port of a z/os Connect EE serer and proide arious functions such as: Listing currently deployed APIs and serices and retrieing details of an indiidual API or serice. Stopping and starting indiidual APIs or serices. Deploying, updating, or undeploying an API. Chapter 7. High aailability 173

182 In an HA enironment, HTTP, and HTTPS requests are targeted at a single host name and port but are then distributed across multiple serers when those serers use TCP/IP port sharing, Sysplex Distributor or both. Routing of an administration request cannot be guaranteed. Therefore, in an HA enironment, administration, or operation actions through HTTP administration interfaces cannot be targeted at either a specific serer or to all of the serers. Querying APIs and serices If all the serers in a high aailability group are configured with the same APIs and serices, then a shared HTTP or HTTPS port can still be used to retriee details of currently deployed APIs and serices, because any serer can return the same information. Howeer, it is not possible to determine the API and serice status on any particular serer. In that case, a second httpendpoint can be configured as described below. Starting and stopping APIs and serices To start or stop an indiidual API or serice and to retriee definitie deployment and status information from indiidual serers in an HA enironment, configure a second httpendpoint element in serer.xml to specify an additional HTTP and HTTPS port pair for each serer. These ports must be unique for each serer and not shared. They are used only for the RESTful Administration interface administration and operation requests. Requests to inoke APIs and serices continue to use the shared ports so that those requests are distributed across the serers. For example, add the following entry into each serer's serer.xml file: <httpendpoint id="operationshttpendpoint" host="*" httpport="<unique_http_port>" httpsport="<unique_https_port>" /> Note: 1. In a production enironment, you might restrict this administration endpoint to require SSL. By default, an httpendpoint serer configuration element uses the serer's default SSL configuration, an ssl element with id=defaultsslconfig. Howeer, if you want to use different SSL certificates to protect requests oer this administration endpoint, you can associate this endpoint with a different SSL configuration. For more information, see the Configuring an httpendpoint to use an SSL configuration other than the default. 2. Requests receied on either httpendpoint are authenticated against the same z/os Connect EE roles that are defined in your configured security repository. For more information, see Oeriew of z/os Connect EE security on page 177. Deploying APIs If the RESTful Administration interface is used to deploy, update, or undeploy APIs to a location directory that is shared by multiple serers then the time at which the change to the API takes effect in each serer is unpredictable. This is because the serer that the administration request is distributed to immediately implements the change to the API in its runtime and the API archie file is updated in the location directory. Howeer, the other serers reflect the change to the API only when they refresh their API information, as specified by the updatetrigger attribute specified on zosconnect_zosconnectapis serer configuration element. For more information, see zosconnect_zosconnectapis on page z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

183 A better alternatie in an HA enironment is to deploy or update APIs by copying or FTPing the archie files in binary mode to a single location directory that is shared by all serers. Similarly, an API archie file can be deleted from the location directory so that new, updated, or deleted APIs are reflected on all serers at the same time. The change to the API archie file again takes effect in the running serers based on the updatetrigger attribute that is specified on zosconnect_zosconnectapis serer configuration element. When run in production, an mbean trigger is preferable to a polled trigger for performance reasons. Deploying serices To deploy, update, or undeploy serices in an HA enironment, use the standard Liberty functions appropriate for your serice proider. Updates to the serer configuration file can be made to the common shared configuration file and take effect dependent on the updatetrigger attribute that is specified on the config serer configuration element. For more information, see Configuration Management (config) in the Reference section. If your z/os Connect EE serices use DataXForms, then creation, modification, or deletion of the data transformation files in the UNIX System Serices directory can be updated based on the updatetrigger attribute that is specified on the zosconnect_zosconnectdataxform serer configuration element. For more information, see zosconnect_zosconnectdataxform on page 312. Note: If you specify the updatetrigger attribute alue of mbean on any of the applicable serer configuration elements, then you must also configure your serer to use the Jaa Management Extensions (JMX) connector, for more information see Using an MBean to trigger updates on page 163. Chapter 7. High aailability 175

184 176 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

185 Chapter 8. Securing Connections to the serer can be secured through user authority roles. Access to applications can be configured at different leels. For z/os Connect EE to use z/os authorized serices, the Liberty angel process must be configured. Oeriew of z/os Connect EE security z/os Connect EE proides user authority roles and the ability to configure SSL connections, so that you can secure access to your serer. Leels of user authority You can set the authority leel of a user to perform actions on APIs and serices according to the security credentials proided with requests. Note: A user must be a member of a global admin group to be able to see all the resources by using the URI../zosConnect/(serices apis). If a user is a member of a specific resource, then that user has authorization only to that specific resource and must use the URI../zosConnect/(serices apis)/ (<sericename> <apiname>). z/os Connect EE supports four leels of authority: Administrator For a user with Administrator authority, all z/os Connect EE actions are allowed, including all Operator, Inoke, and Reader actions. Operator A user with Operator authority is able to request all z/os Connect EE operations and actions except for inoke. These actions include deploying, updating, querying and deleting APIs, querying serices and requesting action=start, stop, status, getrequestschema, getresponseschema and getstatistics for serices. Inoke Reader A user with Inoke authority is able to request action=inoke for the serice or use the inokeuri parameter on the z/os Connect EE serice definition. Such users can also inoke APIs. Permission for Inoke does not proide access to z/os Connect EE operations. A user with Reader authority is able to read the Swagger document, access and import the API, read a list of all APIs and serices, and get detailed information. A user with Reader authority is not authorized to request actions that are permitted for users with Operator or Inoke authority. z/os Connect EE supplies an authorization interceptor that implements the com.ibm.zosconnect.spi.interceptor SPI, and supports both SAF and LDAP. This interceptor uses the getgroupsforuser() security API internally to determine which groups the current user is in, and then compares these groups to the groups proided in the API definition, serice definition, or global definition. The authorization interceptor can be enabled using either the globalinterceptorsref attribute on the zosconnectmanager element or, for a specific API or serice, the interceptorsref attribute on the zosconnectapi or zosconnectserice element. Copyright IBM Corp. 2015,

186 Any zosconnectapi or zosconnectserice element which does not specify runglobalinterceptors="false" will run all of the global interceptors in addition to any it specifies. When the z/os Connect EE supplied authorization interceptor is enabled, the RACF or LDAP user registry group names that are associated with users can also be associated with any of the groups that are mentioned preiously at the global, API, or serice definition leels. At the global leel, they can be defined under the zosconnectmanager configuration element. The attributes that are defined at this leel include: globaladmingroup, globaloperationsgroup, globalinokegroup, and globalreadergroup. If configured, they apply to all configured APIs and serices. If more granularity is needed, the groups can also be configured at the API or serice leel under the zosconnectapi or zosconnectserice configuration element. The attributes that are defined at that leel are: admingroup, operationsgroup, inokegroup, and readergroup. These alues, if specified, oerride the alues that are defined globally. When an authorization interceptor is defined at the global leel, authorization checks are done once for all serices. When you use /zosconnect/operations/ getstatistics request for more than one serice and serice discoery, the user gets information on all serices that are registered with z/os Connect EE when the following conditions exist: The user passes the authorization check No other conditions preent serice information from being returned When an authorization interceptor is defined at the global leel, and a user in either the globaladmingroup or globaloperationsgroup requests /zòsconnect/apis to get a list of APIs, the returned list contains all installed APIs, regardless of the groups specified on the zosconnectapi element. If the authorization interceptor is placed in an API leel definition, either explicitly using the interceptorsref attribute, or implicitly using the runglobalinterceptors="true" attribute, access to information for that API is limited 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 the globaladmingroup on the zosconnectmanager element is authorized to: Perform all the actions described below for operationsgroup and inokegroup. A user in the operationsgroup on the zosconnectapi element, or, if omitted, in the globaloperationsgroup on the zosconnectmanager element is authorized to: Get details of that API Get the Swagger document for that API Deploy an API Update an API Delete an API A user in the inokegroup on the zosconnectapi element, or, if omitted, in the globalinokegroup on the zosconnectmanager element is authorized to: Inoke the API 178 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

187 A user in the readergroup on the zosconnectapi element, or, if omitted, in the globalreadergroup on the zosconnectmanager element is authorized to: Read the Swagger document. Access and import the API. Read a list of all APIs and serices. Get detailed information on APIs and serices. If the authorization interceptor is placed in a serice leel definition, access to information for those serices are limited to users that are in that serice definition. For example, gien the following configuration with the authorization interceptor defined at the serice leel: 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"/> Serice 1: <zosconnect_zosconnectserice admingroup="admins2" operationsgroup="operats2" interceptorsref="interceptorlist1"/> Serice 2: <zosconnect_zosconnectserice operationsgroup="operats2" interceptorsref="interceptorlist1"/> Serice 3: <zosconnect_zosconnectserice admingroup="admins1" interceptorsref="interceptorlist1"/> Where interceptorlist1 is defined as follows: <zosconnect_zosconnectinterceptors id="interceptorlist1" interceptorref="zosconnectauthorizationinterceptor"/> <zosconnect_authorizationinterceptor id="zosconnectauthorizationinterceptor"/> Gien the preious serice/group configuration and user/group allocation, the following table is what each user can see if a discoery request is issued: serice1 serice2 serice3 USR1 X X X USR X USR3 X -- X Chapter 8. Securing 179

188 Requesting SSL and Authentication You can secure communications between a client and the z/os Connect EE serer using the Secure Sockets Layer (SSL) protocol. In the serer.xml configuration file, the zosconnectmanager, zosconnectapi and zosconnectserice elements all support the following attributes: requiresecure Requires that requests are sent oer HTTPS. This is a boolean alue, the default alue is true. requireauth Requires that users specify security credentials in order to be authenticated when calling the URI. This is a boolean alue. The default alue is true. The alue specified on the zosconnectmanager element applies to all configured APIs and serices, unless an indiidual zosconnectapi or zosconnectserice element explicitly specifies a different alue. For example, both of the following serer.xml entries are equialent and indicate that requests must be sent oer HTTPS, and that users must specify security credentials. The first example uses the default alues: <zosconnect_zosconnectmanager /> The second example explicitly specifies the attributes: <zosconnect_zosconnectmanager requiresecure="true" requireauth="true" /> The following serer.xml entry indicates that requests to serice testserice can be sent oer HTTP, and that user security credentials are not required: <zosconnect_zosconnectserice id="testserice" sericename="testserice" sericeref="reftestserice" inokeuri="/test" requiresecure="false" requireauth="false" /> With z/os Connect EE API Editor V or later, you can set up client authentication in the API Editor to establish connections to the serer, and use the separate user ID for authorization based on the defined security role. Related tasks: Configuring client certificates for serer connections on page 217 Generate a client certificate and configure the Eclipse preferences to send in the certificate from the API Editor to the z/os Connect EE serer. On the serer side, import the client certificate into the serer truststore and disable failoer to basic authentication. Configuring security for z/os Connect EE The z/os Connect EE application can be accessed by authenticated users that are also authorized under the zosconnectaccess role. You can configure group authorization at the global, API, or serice definition leel. Group authorization is supported 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 the zosconnect_zosconnectmanager, zosconnectapi, and zosconnect_zosconnectserice elements of the serer.xml configuration file. The default alue is true. Setting this alue to false remoes the requirement for users to be authenticated. 180 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

189 Note: A user must be a member of a global admin group to be able to see all the resources by using the URI../zosConnect/(serices apis). If a user is a member of a specific resource, then that user has authorization only to that specific resource and must use the URI -../zosconnect/(serices apis)/ (<sericename> <apiname>). By default, the z/os Connect EE application requires an SSL connection from the client. It also defaults to client authentication. The SSL connection is controlled by the requiresecure attribute on the zosconnect_zosconnectmanager, zosconnectapi, and zosconnect_zosconnectserice elements of the serer.xml configuration file. The default alue is true. Howeer, this alue can be set to false to remoe the requirement for an SSL connection. If SSL is enabled, you can also use basic authentication instead of client authentication. If authentication and authorization are enabled, the security features must be enabled, and users must be defined in a user registry and authorized under the zosconnectaccess role. The steps that are required to configure the zosconnectaccess role depends on your chosen user registry. Note: At least one user registry must be defined een if authentication and authorization are not enabled If SSL is enabled, the SSL feature must be selected and SSL keystores and truststores must be configured. z/os Connect EE supports both SSL and user authentication by using the support that is proided in the Liberty profile. For instructions on configuring a z/os Connect EE serer to proide secure communications between a client and the serer that uses SSL, see the Liberty profile topic Securing communications with Liberty For instructions on configuring a z/os Connect EE serer to use a (Basic, LDAP or SAF) user registry to authenticate a user and determine their leel 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 to secure your z/os Connect EE serer. To use SAF, or to take adantage of other z/os authorized serices such as Workload Manager (WLM), Resource Recoery serices (RRS), or SVCDUMP, you must set up a Liberty angel process and grant access for your Liberty profile serer to use these serices. For more information, see Enabling z/os authorized serices on Liberty for z/os in the WebSphere Application Serer for z/os documentation. The following tasks describe how to configure a z/os Connect EE serer to require basic authentication and an SSL connection, that use either basic or SAF user registries. Configuring security with a basic user registry Configure group authorization at the global, API, or serice definition leel by using a basic user registry. Group authorization is also supported for SAF and LDAP user registries. Chapter 8. Securing 181

190 About this task In this task, you configure a z/os Connect EE serer to require basic user authentication and an SSL connection, by using a basic user registry. To set up client certificate authentication, see the documentation on configuring your web application and serer for client certificate authentication in the Liberty profile. Procedure <featuremanager> <feature>zosconnect:zosconnect-2.0</feature> <feature>ssl-1.0</feature> <feature>appsecurity-2.0</feature> </featuremanager> 1. Set up SSL and user authentication to access the z/os Connect EE application. Sample 1. Basic user registry configuration. <!-- Define the SSL configuration --> <ssl id="defaultsslconfig" keystoreref="defaultkeystore" truststoreref="defaulttruststore" clientauthentication="false" /> <!-- Define a keystore. --> <keystore id="defaultkeystore" password="zosconnect"/> <!-- Define a truststore. --> <keystore id="defaulttruststore" password="zosconnect"/> <!-- Fail oer to basic authentication --> <webappsecurity allowfailoertobasicauth="true"/> <!-- Basic user registry definition --> <basicregistry id="basic1" realm="zosconnect"> <user name="fred" password="fredpwd"/> </basicregistry> 2. Set up user authorization to access the z/os Connect EE application by assigning 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 authorization interceptor for z/os Connect EE. If required, define additional users and groups 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 to be used by the authorization interceptor for z/os Connect EE. For example: 182 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

191 <!-- Authorization interceptor --> <zosconnect_authorizationinterceptor id="authinterceptor1" sequence="1"/> <!-- Interceptor list to include authorization interceptor --> <zosconnect_zosconnectinterceptors id="interceptorlist" interceptorref="authinterceptor1"/> Then define the interceptor list and the OPERATS1 group at the appropriate scope. For example: <zosconnect_zosconnectmanager globaloperationsgroup="operats1" globalinterceptorsref="interceptorlist"/> or <zosconnectapi name="api1" operationsgroup="operats1" interceptorsref="interceptorlist"/> or <zosconnect_zosconnectserice sericeref="serice1" operationsgroup="operats1" interceptorsref="interceptorlist"/> Configuring security with SAF registries Configure group authorization at the global, API, or serice definition leel by using SAF registries. Group authorization is also supported for basic user and LDAP user registries. About this task In this task, you configure a z/os Connect EE serer to require basic authentication and an SSL connection, for a SAF user registry. To set up client certificate authentication, see the documentation on configuring your web application and serer for client certificate authentication in the Liberty profile. Procedure 1. 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> <!-- Define the SSL configuration --> <ssl id="defaultsslconfig" keystoreref="defaultkeystore" truststoreref="defaulttruststore" clientauthentication="false" / <!-- Define a keystore. --> <keystore id="defaultkeystore" password="zosconnect"/> <!-- Define a truststore. --> <keystore id="defaulttruststore" password="zosconnect"/> <!-- Fail oer to basic authentication --> <webappsecurity allowfailoertobasicauth="true" <!-- Saf registry definition --> <safregistry id="saf" realm="zosconnect"/> Create RACF definitions. For more details, follow the instructions in the Liberty documentation Accessing z/os security resources using WZSSAD. The alue of the profileprefix attribute is specified on the serer configuration file element Chapter 8. Securing 183

192 safcredentials. The default alue is BBGZDFLT. In this example, a alue of MYPROFIL is used, but you need to substitute your own alue. # Define the APPL class based on the default security prefix called MYPROFIL. RDEFINE APPL MYPROFIL UACC(NONE) # Actiate the APPL class. SETROPTS CLASSACT(APPL) # For FRED to be authenticated by the serer, 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 class PERMIT MYPROFIL CLASS(APPL) ACCESS(READ) ID(unauthenticatedUserId) # Grant the serer permission to make authentication calls. RDEFINE SERVER BBG.SECPFX.MYPROFIL UACC(NONE) PERMIT BBG.SECPFX.MYPROFIL ID(sererId) ACCESS(READ) CLASS(SERVER) <featuremanager> <feature>zosconnect:zosconnect-2.0</feature> <feature>ssl-1.0</feature> <feature>appsecurity-2.0</feature> <feature>zossecurity-1.0</feature> </featuremanager> Note: The serer needs to hae permission to use the SAFCRED authorized serice routines. See Configuring the Liberty angel process and z/os authorized serices on page Set up user authorization to access the z/os Connect EE application by assigning users the zosconnectaccess role. a. Update the configuration file to add the safauthorization element. For example, Sample2. Authorization configuration using SAF/RACF. <!-- Define the SSL configuration --> <ssl id="defaultsslconfig" keystoreref="defaultkeystore" truststoreref="defaulttruststore" clientauthentication="false" /> <!-- Define a keystore. --> <keystore id="defaultkeystore" password="liberty"/> <!-- Define a truststore. --> <keystore id="defaulttruststore" password="zosconnect"/> <!-- Fail oer to basic authentication --> <webappsecurity allowfailoertobasicauth="true" <!-- Saf registry definition --> <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.zosConnectAccess UACC(NONE) PERMIT MYPROFIL.zos.connect.access.roles.zosConnectAccess CLASS(EJBROLE) ID(FRED) ACCESS(READ) The alue of the profileprefix attribute is specified on the serer configuration file element safcredentials. The default alue is BBGZDFLT. In this example, a alue of MYPROFIL is used, but you need to substitute your own alue. 184 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

193 ADDGROUP OPERATS1 OMVS(GID(xxx)) OWNER(xxxx) 3. (Optional) Define authorization groups for use with the authorization interceptor for z/os Connect EE. If required, define more users and groups in the in the SAF registry. For example, to add user Fred to the OPERATS1 group: Sample 3. RACF Group definition for use with SAF. # Add user FRED under the OPERATS1 group ADDUSER FRED DFLTGRP(OPERATS1) OMVS(UID(xxx) HOME(/xxxx) PROGRAM(/bin/sh)) NAME( USER FRED ) NOPASSWORD ALTUSER FRED PASSWORD(xxxxxxx) NOEXPIRED # Connect user Fred to the OPERATS1 group CONNECT FRED GROUP(OPERATS1) The OPERATS1 group can then be used when defining authorization groups to be used by the authorization interceptor for z/os Connect EE. For example: <!-- Authorization interceptor --> <zosconnect_authorizationinterceptor id="authinterceptor1" sequence="1"/> <!-- Interceptor list to include authorization interceptor --> <zosconnect_zosconnectinterceptors id="interceptorlist" interceptorref="authinterceptor1"/> Then define the interceptor list and the OPERATS1 group at the appropriate scope. For example: <zosconnect_zosconnectmanager globaloperationsgroup="operats1" globalinterceptorsref="interceptorlist"/> or <zosconnectapi name="api1" operationsgroup="operats1" interceptorsref="interceptorlist"/> or <zosconnect_zosconnectserice sericeref="serice1" operationsgroup="operats1" interceptorsref="interceptorlist"/> Configuring the Liberty angel process and z/os authorized serices You need to configure the Liberty angel process so that z/os Connect Enterprise Edition can use z/os authorized serices. About this task To use z/os authorized serices such as WebSphere Optimized Local Adapters (WOLA), System Authorization Facility (SAF), Workload Manager (WLM), resource recoery serices (RRS), or SVCDUMP, you must set up a Liberty angel process and grant access for your z/os Connect EE serer to use these serices. The Liberty profile angel process must be run as a started task, but is lightweight, has no configuration or TCP ports, and consumes almost no CPU when running. To create the angel process started task you must customize the sample JCL and create SAF definitions to associate the started task with a userid and permit your z/os Connect EE serer to use the z/os authorized serices. The following examples use RACF commands. Note: Each LPAR can hae only one angel process. Ensure that the angel process is running at the latest installed leel of Liberty on the LPAR. If a Liberty serer instance that is embedded in z/os Connect EE serer connects to an angel process that is running at an earlier serice leel, some features of the serer might not be aailable. Chapter 8. Securing 185

194 Procedure 1. Create the JCL start procedure for the angel process. a. Open a Telnet or ssh session to your z/os system UNIX System Serices. 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/2r0/wlp/templates/zos/procs/bbgzangl.jcl "// USER.PROCLIB(BBGZANGL) " c. Customize the sample JCL by updating the SET ROOT alue to your z/os Connect EE installation directory. For example: SET ROOT= /usr/lpp/ibm/zosconnect/2r0/wlp In the following steps, work with your security administrator to create the necessary authorizations and artifacts for the angel process to run as a started task and to permit your z/os Connect EE serer to use z/os authorized serices. 2. Started tasks must be associated with a userid. If you do not hae a suitable userid, use the following commands to create a new userid and group. For example: to define a userid called angel_id in a group called admin_group, your security 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 started task. 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 serer authority to use the required z/os authorized serices. a. Define the following SAF SERVER profiles, if they do not already exist. Grant your z/os Connect EE serer userid READ access to each, by issuing the following commands where serer_id is the userid used to run the z/os Connect EE serer started task Alternatiely, you may choose to permit access at a group leel, in which case replace serer_id with the name of the group. The userid used to run the z/os Connect EE serer started task must be connected to this group: Note: To use WebSphere Optimized Local Adapters (WOLA) you need to define and permit access to the SERVER profiles for: BBG.ANGEL, BBG.AUTHMOD.BBGZSAFM, BBG.AUTHMOD.BBGZSAFM.LOCALCOM, BBG.AUTHMOD.BBGZSAFM.WOLA, BBG.AUTHMOD.BBGZSCFM and BBG.AUTHMOD.BBGZSCFM.WOLA. SERVER profile for the angel process to allow serer access to the angel process: RDEF SERVER BBG.ANGEL UACC(NONE) PERMIT BBG.ANGEL CLASS(SERVER) ACCESS(READ) ID(serer_id) 186 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

195 SERVER profile for the authorized module BBGZSAFM to allow serer access to z/os Authorized serices: RDEF BBG.AUTHMOD.BBGZSAFM UACC(NONE) PERMIT BBG.AUTHMOD.BBGZSAFM CLASS(SERVER) ACCESS(READ) ID(serer_id) SERVER profiles for the optimized local adapter authorized serice: RDEF SERVER BBG.AUTHMOD.BBGZSAFM.LOCALCOM UACC(NONE) PERMIT BBG.AUTHMOD.BBGZSAFM.LOCALCOM CLASS(SERVER) ACCESS(READ) ID(serer_id) RDEF SERVER BBG.AUTHMOD.BBGZSAFM.WOLA UACC(NONE) PERMIT BBG.AUTHMOD.BBGZSAFM.WOLA CLASS(SERVER) ACCESS(READ) ID(serer_id) SERVER profile for the authorized client module BBGZSCFM: RDEF SERVER BBG.AUTHMOD.BBGZSCFM UACC(NONE) PERMIT BBG.AUTHMOD.BBGZSCFM CLASS(SERVER) ACCESS(READ) ID(serer_id) SERVER profiles for optimized local adapter authorized client serice: RDEF SERVER BBG.AUTHMOD.BBGZSCFM.WOLA UACC(NONE) PERMIT BBG.AUTHMOD.BBGZSCFM.WOLA CLASS(SERVER) ACCESS(READ) ID(serer_id) SERVER profile for WLM serices (ZOSWLM): RDEF SERVER BBG.AUTHMOD.BBGZSAFM.ZOSWLM UACC(NONE) PERMIT BBG.AUTHMOD.BBGZSAFM.ZOSWLM CLASS(SERVER) ACCESS(READ) ID(serer_id) SERVER profile for RRS transaction serices (TXRRS) RDEF RDEF SERVER BBG.AUTHMOD.BBGZSAFM.TXRRS UACC(NONE) PERMIT PERMIT BBG.AUTHMOD.BBGZSAFM.TXRRS CLASS(SERVER) ACCESS(READ) ID(serer_id) SERVER profile for SVCDUMP serices (ZOSDUMP) RDEF SERVER BBG.AUTHMOD.BBGZSAFM.ZOSDUMP UACC(NONE) PERMIT BBG.AUTHMOD.BBGZSAFM.ZOSDUMP CLASS(SERVER) ACCESS(READ) ID(serer_id) SERVER profile for IFAUSAGE serices (PRODMGR) RDEF SERVER BBG.AUTHMOD.BBGZSAFM.PRODMGR UACC(NONE) PERMIT BBG.AUTHMOD.BBGZSAFM.PRODMGR CLASS(SERVER) ACCESS(READ) ID(serer_id) SERVER profile for SAF authorized user registry serices and SAF authorization serices (SAFCRED) RDEF SERVER BBG.AUTHMOD.BBGZSAFM.SAFCRED UACC(NONE) PERMIT BBG.AUTHMOD.BBGZSAFM.SAFCRED CLASS(SERVER) ACCESS(READ) ID(serer_id) b. Refresh to actiate the definitions: SETROPTS RACLIST(SERVER) REFRESH Chapter 8. Securing 187

196 5. Start the angel process as a started task: From the z/os operator console, issue the following command: S BBGZANGL You should see the following log messages to indicate that the angel process started successfully: IRR812I PROFILE BBGZANGL.* (G) IN THE STARTED CLASS WAS USED TO START BBGZANGL WITH JOBNAME BBGZANGL. $HASP100 BBGZANGL ON STCINRDR IEF695I START BBGZANGL WITH JOBNAME BBGZANGL IS ASSIGNED TO USER angel_id, GROUP admin_group $HASP373 BBGZANGL STARTED CWWKB0056I INITIALIZATION COMPLETE FOR ANGEL Note: You should leae the angel process running for any z/os Connect EE serer that requires access using z/os authorized serices. To stop the angel process, enter the following command at the z/os operator console: P BBGZANGL 188 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

197 Chapter 9. Operating Operating z/os Connect EE Starting and stopping z/os Connect EE Use these commands to start and stop your z/os Connect EE serer. Use a started procedure to run your z/os Connect EE serer. Setting up a started task to run z/os Connect EE serers A single instance of the started task JCL can be used to start multiple z/os Connect EE serers because the serer name is passed as a parameter on the start command. You might require multiple copies of the started task JCL, if your z/os Connect EE serers 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 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: RDEF STARTED BAQSTRT.* UACC(NONE) STDATA(USER(<userid>) GROUP(<group>) PRIVILEGED(NO) TRUSTED(NO) TRACE(YES)) If you use a non-ibm External Security Manager and receie a CHECK_PROC_OWNER error message when you start z/os Connect EE as a started task, check that you hae correctly defined the location where the serer instances are stored. Define the location in the HOME parameter of the OMVS segment of the started task user ID. Starting a z/os Connect EE serer To start the serer started procedure, enter the following command: /S BAQSTRT,PARMS='<sererName> --clean' Note: You must use the System Command Extension window within SDSF to presere the case of your serer name. From SDSF, enter / to open the System Command Extension window, then enter the START command. Stopping a z/os Connect EE serer To stop the serer started procedure, enter the following command: /P <JOB NAME> System Automation System Automation of z/os software usually inoles trapping messages issued to the z/os console and performing actions in response to those messages. For example, to confirm a z/os Connect EE serer has started or shutdown successfully. Copyright IBM Corp. 2015,

198 Specifying z/os Connect EE messages to be written to z/os operator console By default, z/os Connect EE logs all messages to the UNIX System Serices file messages.log, and only a subset of these messages are written to the z/os console. Howeer, the serer configuration file element zoslogging can be used to specify additional serer messages to be logged to the z/os console. For more information about the zoslogging serer configuration element, see z/os Logging (zoslogging) in the WebSphere Application Serer 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 aailable (default_host): These messages indicate that a z/os Connect EE serer has completed start up successfully. CWWKE1101I: Serer quiesce complete. Indicates that a z/os Connect EE serer has completed shutdown successfully To log these messages to the z/os console, specify the following in the serer configuration element: <zoslogging enablelogtomvs="true" wtomessage="baqr7000i,srve0250i,cwwkt0016i,cwwke1101i"/> When the z/os Connect EE serer is started with a deployed API, the following messages are written to the z/os console: N MVxx yyddd hh:mm:ss.sss JOBnnnnn nnnnnnnn +CWWKE0001I: The serer serername has been launched. N MVxx yyddd hh:mm:ss.sss JOBnnnnn nnnnnnnn +BAQR7000I: z/os Connect API package apiname installed successfully N MVxx yyddd hh:mm:ss.sss JOBnnnnn nnnnnnnn +CWWKF0011I: The serer serername is ready to run a smarter planet N MVxx yyddd hh:mm:ss.sss JOBnnnnn nnnnnnnn +SRVE0250I: Web Module z/os Connect has been bound to default_host. M MVxx yyddd hh:mm:ss.sss JOBnnnnn nnnnnnnn +CWWKT0016I: Web application aailable (default_host): E 870 nnnnnnnn When the z/os Connect EE serer is stopped, the following messages are written to the z/os console: N MVxx yyddd hh:mm:ss.sss JOBnnnnn nnnnnnnn +CWWKB0001I: Stop command receied for serer serername. N MVxx yyddd hh:mm:ss.sss JOBnnnnn nnnnnnnn +CWWKE1101I: Serer 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 ersion.rr.mm successfully deregistered from z/os. CWWKE0036I: The serer serername stopped after m minutes, s.sss seconds. Using IBM Tioli System Automation for z/os with z/os Connect EE IBM Tioli System Automation for z/os can be used to trap and respond to z/os console messages issued by z/os Connect EE serers to keep them highly aailable. IBM Tioli System Automation for z/os V5.3 APAR OA49939 supports a simple setup for automating and monitoring the angel and z/os Connect EE serers. This setup uses a pre-defined z/os Connect EE configuration that is proided by the *IBMCOMP add-on policy, similar to sample solutions for products like IMS, CICS, 190 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

199 DB2 and others. For more information see the deeloperworks article APAR OA Easy Automation of zos Connect EE and Using SA z/os Sample Policies in the IBM Tioli System Automation for z/os, Version 3.5 Knowledge Center documentation. Note: The support added by APAR OA49939 does not automatically use the additional WTO messages, but you can use the instructions aboe to produce the WTO messages and manually include these in your policy. With IBM System Automation for z/os V3.5 APAR OA51440, which will be aailable by January 2017, messages CWWKB0001I, CWWKF0011I, CWWKT0016I and CWWKE1101I will be used to automate and monitor z/os Connect EE. This automation also uses a pre-defined z/os Connect EE configuration that is proided by the *IBMCOMP add-on policy. Chapter 9. Operating 191

200 192 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

201 Chapter 10. Building a Serice Archie (SAR) by using the Build Toolkit You can use either the command line interface or the SDK to build your SAR file for the REST client and for IMS serices. A Serice archie (SAR) file contains the information that is needed by a z/os Connect EE serice proider to install and proide the serice, and to enable the serice as a JSON asset. You create a SAR file, then import it into the z/os Connect EE API tooling that represents a REST client serice. You can create the SAR file from your IDE with the Build toolkit SDK or from the command line with the zconbt command. In each case, you need to set the properties for the SAR file you are generating. Related reference: zconbt command syntax on page 329 Building a SAR for the REST client Table 31. Mandatory properties You can use either the command line interface or the SDK to build your SAR file for the REST client. To use the build toolkit to build your SAR file, the following properties must be defined. Property Importance Description proider Required Must be set to rest to build a SAR file for the REST client serice proider. name Required The name of the serice. Note: The name must match the sericename attribute in the zosconnect_zosconnectserice element in the serer.xml file. ersion Required The ersion of the serice. The following properties are aailable for the REST client serice proider: Table 32. Properties for the REST client serice proider Property Importance Description Copyright IBM Corp. 2015,

202 Table 32. Properties for the REST client serice proider (continued) connectionref Required The name of the connection details defined in the z/os Connect EE configuration for connecting to the remote serice. If not defined, then a alid zosconnect_zosconnectsericerestclient or zosconnect_zosconnectsericerestclientconnection element must be defined in the serer.xml file. description Optional The description of the serice. This name must match the sericename attribute in the zosconnect_zosconnectserice element in the serer.xml file. requestschemafile Required The JSON schema file that defines the request object for this serice. Note: If you do not specify an absolute path, then the Build Toolkit uses a relatie path from the directory in which the zconbt command is run. responseschemafile Required The JSON schema file that defines the response object for this serice. Note: If you do not specify an absolute path, then the Build Toolkit uses a relatie path from the directory in which the zconbt command is run. erb Optional The HTTP erb that is used to call the serice. If this erb is omitted, then the erb that is used to inoke the serice is used. uri Required The resource that this serice exposes. It must not contain the host name or port. You can now use the build toolkit to create the SAR file. See the following topics with samples: Building a SAR from the command line on page 198 Building a SAR with the z/os Connect EE Build Toolkit SDK on page 199 Related reference: zconbt command syntax on page 329 Building a SAR for the IMS serice proider With a z/os Connect EE connection, you can download IMS serice definition files from IMS Explorer for Deelopment to your serice project in the workspace. The project can be consumed by the build toolkit later to generate the SAR offline without haing to connect to a serer. 194 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

203 Table 33. Mandatory properties For more information about downloading IMS serice definitions, see Downloading IMS serice definitions (in IMS Explorer for Deelopment information). To use the build toolkit to build your SAR file, the following properties must be defined. Property Importance Description proider Required Must be set to imssp to build a SAR file for the IMS serice proider. name Required The name of the serice. ersion Optional The ersion of the serice. The following properties are required for the IMS serice proider. Table 34. Required properties for the IMS serice proider run time Property Importance Description imssericeprojectlocation Required The Eclipse workspace or a source control management folder that contains all the downloaded serice projects from IMS Explorer. imstransactionregistrylocationrequired imsconnectionref imsinteractionref Optional (see note) Optional (see note) The subfolder under the Eclipse workspace or a source control management folder that contains all the transaction message metadata. Name of the connection profile to use at serice inocation. Note: This property is optional during SAR file generation, but if it is not specified, errors occur when the generated SAR file is used at run time. Always specify this property when you use the build toolkit to generate the SAR files for IMS serices. Name of the interaction properties profile to use at serice inocation. Note: This property is optional during SAR file generation, but if it is not specified, errors occur when the generated SAR file is used at run time. Always specify this property when you use the build toolkit to generate the SAR files for IMS serices. The following properties are optional for the IMS serice proider. Table 35. Optional properties for the IMS serice proider Attribute Importance Description imstrancodeoerride Optional Oerrides the transaction code that the serice inokes at run time. imsdatastoreoerride Optional Oerrides the IMS datastore name that specifies the IMS subsystem against which to inoke the serice. Input-only properties: initializeinputfields Optional Initializes fields in the input data structure according to their type if a default is not specified for the field and either the field is omitted from the input interface or the field is included but the respectie JSON tag is not receied at run time. By default, fields are not initialized unless specified otherwise in IMS Explorer. enforceminarrayoccurrence Optional Enforces the minimum number of array occurrence in the input data structure as defined in the copybook. The default is true unless specified otherwise in IMS Explorer. Chapter 10. Building a Serice Archie (SAR) by using the Build Toolkit 195

204 Table 35. Optional properties for the IMS serice proider (continued) Attribute Importance Description Output-only properties: trimoutputleadingwhitespace Optional Trims the leading whitespace from JSON property alues in the output messages. By default, leading whitespace is not trimmed, unless specified otherwise in IMS Explorer. trimoutputtrailingwhitespace Optional Trims trailing whitespace from JSON property alues in output messages. By default, trailing whitespace is trimmed, unless specified otherwise in IMS Explorer. escapeoutputcontrolcharacters Optional Escapes non-printable control characters, such as tokens or control blocks, in JSON property alues as \unnnn for necessary internal processing, instead of remoing them. By default, control characters are omitted, not escaped, unless specified otherwise in IMS Explorer. omitoutputfieldsbyvalue Optional Omits the JSON name-alue pair for a non-numeric field from the JSON output message when the data for the field is composed of the same byte alue repeated throughout, such as all 0x00 or all 0xFF. By default, this option is not selected, unless specified otherwise in IMS Explorer. omitoutputfieldsbyvaluebyte Optional Specifies the hexadecimal alue that all bytes in a non-numeric field must contain to be omitted. The default alue 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 control characters are processed. By default, empty tags are not omitted, unless specified otherwise in IMS Explorer. The default alues are already set in IMS Explorer, and you can modify them in IMS Explorer when you create or edit an IMS mobile transaction serice or through the IMS mobile preferences for adanced data conersion options. These alues are stored with the downloaded serice definitions. Important: If these properties are not specified during SAR generation using the build toolkit, the alues that were specified in IMS Explorer are used at run time. If these properties are specified during SAR generation using the build toolkit, they oerride the alues that were specified in IMS Explorer. This behaior allows you to more easily generate a SAR file for different testing or production enironments without haing to modify the serice definitions. You can now use the build toolkit to create the SAR file. See the following topics with samples: Building a SAR from the command line on page 198 Building a SAR with the z/os Connect EE Build Toolkit SDK on page 199 Related reference: zconbt command syntax on page 329 Building a SAR for the WOLA serice proider You can use the build toolkit to build a SAR file for the CICS serice proider. 196 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

205 Table 36. Mandatory properties The SAR contains equialent function to a SAR built using the BAQLS2JS utility. For more information about the BAQLS2JS utility, see Conersion for z/os Connect Enterprise Edition data transformation on page 250. The WSBind file is included in the SAR file. To use the build toolkit to build your SAR file, the following properties must be defined. Property Importance Description proider Required Must be set to wola. name Required The name of the serice. For example, inquiresingle. ersion Required The ersion of the serice. channelname Required The CICS channel name to use for deliering messages and receiing payloads using CICS containers. connectionref Required The name of the configured connection factory element to be used. This element contains the JNDI name of the WOLA resource adapter connection factory. connectionwaittimeout Required The number of seconds to wait for an external address space application that matches the registration name to issue a WOLA Receie Request or Host Serice API and become actie. Set this parameter to 0 to disable timeout. contextencoding Required The encoding of the data in all context containers that are sent to the destination program. httpheaders Required The HTTP header name or list of comma-separated and case-sensitie HTTP header names that are passed to the destination program. program Required The name of the program to inoke 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 Serer link inocation task transaction ID. The following properties are aailable for the WOLA serice proider when used with DataXForm. Table 37. Other properties for the WOLA serice proider using DataXForm Property Importance Description ccsid Optional The CCSID that is used at run time to encode character data. For example, 037. charvarying Optional Defines how ariable-length character data is mapped. Valid alues are no null collapse binary. datatruncation Optional Controls if ariable length data is tolerated in a fixed-length field structure. Valid alues are false true. The default is false. Chapter 10. Building a Serice Archie (SAR) by using the Build Toolkit 197

206 Table 37. Other properties for the WOLA serice proider using DataXForm (continued) datetime Optional Specifies if potential ABSTIME fields in the high-leel language structure are mapped as timestamps. Valid alues are unused packed15. The default is unused language Required The language of the target program. Valid alues are COBOL C PLI- ENTERPRISE PLI-OTHER. requeststructure Required The relatie or absolute path to the file that contains the language structure for the request. responsestructure Required The relatie or absolute path to the file containing the language structure for the response. truncatenullarrays Optional Specifies how structured arrays are processed. Valid alues are false true. The default is false. truncatenullarraysvalue Optional Specifies which alues are treated as empty for truncatenullarrays processing. Valid alues are null space zero. The default is null. The following properties are aailable for the WOLA serice proider when used for migration. Table 38. Properties for the WOLA serice proider when used for migration Property Importance Description bindfile Required The relatie or absolute path to the bind file. requestschema Required The relatie or absolute path to the JSON schema for the request. responseschema Required The relatie or absolute path to the JSON schema for the response. The following properties are aailable for the WOLA serice proider when used without DataXForm. Table 39. Properties for the WOLA serice proider when without DataXForm Property Importance Description requestschema Required The relatie or absolute path to the JSON schema for the request. responseschema Required The relatie or absolute path to the JSON schema for the response. Related reference: zconbt command syntax on page 329 Building a SAR from the command line Enter the zconbt command on the command line to build your Serice archie file. 198 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

207 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. Procedure 1. Create the properties files with the properties you need for the SAR. For example, for the REST client: proider=rest name=example ersion=1.0 description=an example REST client serice requestschemafile=request.json responseschemafile=response.json erb=post uri=/resource/item connectionref=conn A description of the properties is proided in Building a SAR for the REST client on page 193. For the IMS serice proider: proider=imssp name=serice1 ersion=1.0 description=my first IMS serice imssericeprojectlocation=c:/myeclipse/workspace imstransactionregistrylocation=c:/myeclipse/workspace/myzceetrans imsconnectionref=newconnref imsinteractionref=newinteracref A description of the properties is proided in Building a SAR for the IMS serice proider 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=serice1.properties -f=./serice1.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 SDK Use the Build Toolkit SDK to build your Serice archie file. Chapter 10. Building a Serice Archie (SAR) by using the Build Toolkit 199

208 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. 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 SAR file. To learn more about the build toolkit, see The z/os Connect EE Build Toolkit on page 5. Procedure 1. 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 inalid, an InalidPropertyException occurs. The error message contains the property in error and the reason. 3. Sae the SAR file. Call the sae() method and pass the filename. For example 4. 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("proider", "rest"); properties.put("ersion", "1.0"); properties.put("description", "An example REST client serice"); properties.put("requestschemafile", "request.json"); properties.put("responseschemafile", "response.json"); properties.put("erb", "POST"); properties.put("uri", "/resource/item"); properties.put("connectionref", "conn"); SARGenerator sargenerator = new SARGenerator(properties); sargenerator.sae("/example/ouput/dir/file.sar"); Example 2: The IMS serice proider: Map<String, String> properties = new HashMap<String, String>(); properties.put("name", "serice1"); properties.put("proider", "imssp"); properties.put("ersion", "1.0"); properties.put("description", "My first IMS serice"); properties.put("imssericeprojectlocation", "C:/myEclipse/workspace"); properties.put("imstransactionregistrylocation", "C:/myEclipse/workspace/MyzCEETrans"); properties.put("imsconnectionref", "NewConnRef"); properties.put("imsinteractionref", "NewInteracRef"); SARGenerator sargenerator = new SARGenerator(properties); sargenerator.sae("c:/imsmobile/output/serice1.sar"); 200 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

209 Chapter 11. Designing and building APIs in the API Editor z/os Connect EE proides an Eclipse-based API editor for you to define APIs for your z/os Connect EE serices. When you are in the z/os Connect Enterprise Edition perspectie in the Eclipse enironment, you can do the following work: Create, edit, delete, deploy, and export an API project in the Project Explorer iew. Browse, start, stop, and remoe deployed APIs on connected serers in the z/os Connect EE Serers iew. 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 deploying APIs: Deelop an API to inoke a CICS serice ia WOLA on page 17 Deelop an API to inoke an IMS serice on page 66 YouTube ideo: &feature=youtu.be. RESTful web serices and API design The primary focus of RESTful web serice design is to identify the z/os assets that need to be exposed, determine the HTTP methods that you want to support for those assets, and then map the resource identifiers and methods to those assets. The methods that are defined by the HTTP specification proide a uniform interface for interacting with resources on the web. All web browsers, serers, and applications understand this uniform interface and the semantics of each operation. They can connect to one another and exchange information by using this uniform interface regardless of platforms or technology differences. After the resources that need to be exposed for the serice are determined, the next step is to design a REST API. This API is the user interface to the consumers of the API. The consumers of the API might be application deelopers who need to build RESTful clients to access the serices, or an integration deeloper who publishes your APIs in IBM API Connect. A REST API describes a set of resources and a set of methods that can be called on those resources. The methods in a REST API can be called from any HTTP client, including client-side JaaScript code that is running in a web browser. The REST API has a base path, which is similar to a context root. All resources in a REST API are defined relatie to its base path. The base path can be used to proide isolation between different REST APIs. The HTTP client uses a path relatie to the base path that identifies the resource in the REST API that the client is accessing. The paths to a resource can be hierarchical, and a well-designed path structure can help a consumer of a REST API understand the resources that are aailable within that REST API. The following table lists some example resources for a patient database in the REST API: Copyright IBM Corp. 2015,

210 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 HTTP client. The following table lists example methods for the resource /patients/12345: Table 41. Example operations HTTP Method GET PUT DELETE Description Retriee the patient details from the database. Update the patient details in the database. Delete the patient from the database. To update information for that patient, the HTTP client would make an HTTP PUT request to /patients/ With a uniform interface for communication, application deelopers can focus on the resources rather than the methods. They can create their applications without haing to deal with a complex system or learn the intricacies of new interfaces. They can also freely change their applications while the communication methods that connect to these resources remain stable. Each path and method combination in a REST API can also hae a set of parameters that can be used by the HTTP client to pass arguments. Each parameter must be defined in the definitions for the REST API. Each parameter has a unique name and type. Seeral types of parameters are supported by REST APIs in z/os Connect EE: Path parameters Can be used to identify a particular resource. The alue of the parameter is passed in by the HTTP client as a ariable part of the URL, and the alue of the parameter is extracted from the path for use in the operation. Path parameters are denoted by using the syntax {paramname} in the path to the resource. For example, the patient ID can be passed in as a path parameter named patientid: /patients/{patientid} Query parameters The alue of a query parameter is passed in by the HTTP client as a key-alue 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 maximum number of results to be returned by a particular call: /patients?min=5&max=20 Header parameters The HTTP client can pass header parameters by adding them as HTTP headers in the HTTP request. As an example, a header parameter might be used to pass in a unique identifier that identifies the HTTP client that is calling the API: 202 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

211 Designing RESTful APIs Api-Client-Id: fffe2c5d-42d f5f-abc34ab7f555 To assist you with the design and deelopment of this API, z/os Connect EE proides a graphical editor, the z/os Connect EE API Editor. The way that you design APIs can hae a significant impact on their adoption. This section lists considerations for API design in general, and principles for effectie RESTful implementation in particular. Think consumer APIs don't exist in isolation. Modern APIs are the way in which the capabilities of serices are shared with others. When implemented correctly, APIs that are used inside your organization can enforce consistency and promote efficient reuse. Public APIs that are used outside your organization can expand the reach of your business, by allowing deelopers to extend the serices that you proide. Ease-of-use for consumers is ital for the adoption of the API. Consumers are deelopers. They could be deelopers in your own organization, or a mix of internal and third-party deelopers. These deelopers expect APIs that make it quick for them to delier: quick to learn, easy to use, and aimed at their use cases. Using the API must be faster and more expedient than coding an alternatie solution. A successful API encourages deelopers to use it and to share it with other deelopers. An API designer of any API must decide on the following functional requirements: What function needs to be exposed, and how. 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 traditional application programming interfaces. A traditional application programming interface represents a piece of software that you hae built and deployed. A modern API represents a package of capabilities that is both attractie to a user and independent of any specific piece of back-end software. The API is designed from the perspectie of the intended user. Before you deelop one, you must understand: Who is the user? You might hae one clear target user for the API or a mix of users. If you hae a mix of users, you must understand each of them. 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. How can you make those use cases as easy as possible? Think about: Stability How can you minimize disruption for the consumer when you change the API? Flexibility Although you can't exhaustiely coer eery possibility, how can you build in some flexibility for the consumer? A simple example is allowing either uppercase or lower-case input. Chapter 11. Designing and building APIs in the API Editor 203

212 Consistency What standards can you set for your API so that consumers know what to expect? Documentation What documentation can you proide, and how do you make this as straightforward to use as possible? Think resources Traditional serices focused on methods, such as "createaccount" or "updateaccount". Designing RESTful serices means that you hae to think differently: you focus on resources. For example, a resource could be "Account", then the standard HTTP methods are used to operate on that resource. These methods act as erbs for the nouns of the resources. The erbs POST, GET, PUT, and DELETE are already defined. Try to handle all operations with a combination of these erbs and the resources. The more bespoke erbs that you define, the less generalized your interface becomes. Design the URIs From the standpoint of client applications addressing resources, the URIs determine how intuitie the REST Web serice is and whether the serice will be used in ways that the designers can anticipate. REST Web serice URIs should be intuitie to the point where they are easy to guess. Think of a URI as a kind of self-documenting interface that requires little, if any, explanation or reference for a deeloper to understand what it points to and to derie related resources. To this end, the structure of a URI should be straightforward, predictable, and easily understood. One way to achiee this leel of usability is to define directory structure-like URIs. This type of URI is hierarchical, rooted at a single path, and branching from it are sub-paths that expose the serice's main areas. According to this definition, a URI is not merely a slash-delimited string, but rather a tree with subordinate and superordinate branches connected at nodes. For example, in a discussion threading serice that gathers a range of topics, you might define a structured set of URIs like this: The root, /discussion, has a /topics node beneath it. Underneath that there are a series of topic names, such as technology and so on, each of which points to a discussion thread. Within this structure, it's easy to pull up discussion threads just by typing something after /topics/. In some cases, the path to a resource lends itself especially well to a directory-like structure. Take resources organized by date, for instance, which are a ery good match for using a hierarchical syntax. This example is intuitie because it is based on rules: The first path fragment is a four-digit year, the second path fragment is a two-digit day, and the third fragment is a two-digit month. This is the leel of simplicity we're after. Humans and machines can easily generate structured URIs like this because they are based on rules. Filling in the path parts in the slots of a syntax makes them good because there is a definite pattern from which to compose them: z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

213 Some additional guidelines while thinking about URI structure for a RESTful Web serice are: Hide the serer-side scripting technology file extensions (.jsp,.php,.asp), if any, so you can conert to another scripting language without changing the URIs. Keep eerything lowercase. Substitute spaces with either hyphens or underscores Aoid query strings as much as you can. Instead of using the 404 Not Found code if the request URI is for a partial path, always proide a default page or resource as a response. URIs should also be static so that when the resource changes or the implementation of the serice changes, the link stays the same. This allows bookmarking. It's also important that the relationship between resources that is encoded in the URIs remains independent of the way the relationships are represented where they are stored. Apply HTTP methods explicitly One of the key characteristics of a RESTful Web serice is the explicit use of HTTP methods in a way that follows the protocol as defined by RFC HTTP GET, for instance, is defined as a data-producing method that's intended to be used by a client application to retriee a resource, to fetch data from a Web serer, or to execute a query with the expectation that the Web serer will look for and respond with a set of matching resources. REST asks deelopers to use HTTP methods explicitly and in a way that's consistent with the protocol definition. This basic REST design principle establishes a one-to-one mapping between create, read, update, and delete (CRUD) operations and HTTP methods. According to this mapping: To create a resource on the serer, use POST. To retriee a resource, use GET. To change the state of a resource or to update it, use PUT. To remoe or delete a resource, use DELETE. An unfortunate design flaw inherent in many Web APIs is in the use of HTTP methods for unintended purposes. The request URI in an HTTP GET request, for example, usually identifies one specific resource. Or the query string in a request URI includes a set of parameters that defines the search criteria used by the serer to find a set of matching resources. At least this is how the HTTP/1.1 RFC describes GET. But there are many cases of unattractie Web APIs that use HTTP GET to trigger something transactional on the serer: for instance, to add records to a database. In these cases the GET request URI is not used properly or at least not used RESTfully. If the Web API uses GET to inoke remote procedures, it looks like this: GET /adduser?name=robert HTTP/1.1 It's not a ery attractie design because this Web method supports a state-changing operation oer HTTP GET. Put another way, this HTTP GET request has side effects. If successfully processed, the result of the request is to add a new user: in this example, Robert, to the underlying data store. The problem here is mainly semantic. Web serers are designed to respond to HTTP GET requests by retrieing resources that match the path (or the query criteria) in the request URI and return these or a representation in a response, not to add a record to a database. From the Chapter 11. Designing and building APIs in the API Editor 205

214 standpoint of the intended use of the protocol method then, and from the standpoint of HTTP/1.1-compliant Web serers, using GET in this way is inconsistent. 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 serer-side state in some way, inites Web caching tools (crawlers) and search engines to make serer-side changes unintentionally simply by crawling a link. A simple way to oercome this common problem is to moe the parameter names and alues on the request URI into XML tags. The resulting tags, an XML representation of the entity to create, may be sent in the body of an HTTP POST whose request URI is the intended parent of the entity: Before: GET /adduser?name=robert HTTP/1.1 After: POST /users HTTP/1.1 Host: myserer Content-Type: application/xml <user><name>robert</name> </user> This method is exemplary of a RESTful request: proper use of HTTP POST and inclusion of the payload in the body of the request. On the receiing end, the request may be processed by adding the resource contained in the body as a subordinate of the resource identified in the request URI; in this case the new resource should be added as a child of /users. This containment relationship between the new entity and its parent, as specified in the POST request, is analogous to the way a file is subordinate to its parent directory. The client sets up the relationship between the entity and its parent and defines the new entity's URI in the POST request. A client application may then get a representation of the resource using the new URI, noting that at least logically the resource is located under /users: HTTP GET request GET /users/robert HTTP/1.1 Host: myserer Accept: application/xml Using GET in this way is explicit because GET is for data retrieal only. GET is an operation that should be free of side effects, a property also known as idempotence. A similar refactoring of a Web method also needs to be applied in cases where an update operation is supported oer HTTP GET: GET /updateuser?name=robert&newname=bob HTTP/1.1 This changes the name attribute (or property) of the resource. Query strings aren't a bad thing (they're good for implementing filter specifications, for example) but the query-string-as-method-signature pattern that is used in this simple example can break down when used for more complex operations. Because your goal is to make explicit use of HTTP methods, a more RESTful approach is to send an HTTP PUT request to update the resource, instead of HTTP GET, for the same reasons stated earlier. PUT /users/robert HTTP/1.1 Host: myserer Content-Type: application/xml <?xml ersion="1.0"?> <user><name>bob</name> </user> 206 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

215 Using PUT to replace the original resource proides a much cleaner interface that's consistent with REST's principles and with the definition of HTTP methods. The PUT request in this example is explicit in the sense that it points at the resource to be updated by identifying it in the request URI and in the sense that it transfers a new representation of the resource from client to serer in the body of a PUT request instead of transferring the resource attributes as a loose set of parameter names and alues on the request URI. This also has the effect of renaming the resource from Robert to Bob, and in doing so changes its URI to /users/bob. In a REST Web serice, subsequent requests for the resource using the old URI would generate a standard 404 Not Found error. Another consideration is handling large result sets. A standard approach is to use explicit pagination: the GET returns a limited number of objects when it is inoked against a set (irrespectie 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 the GET, for example as a query string parameter) and, if there is a danger of returning 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 HTTP methods explicitly by using nouns in URIs instead of erbs. In a RESTful Web serice, the erbs POST, GET, PUT, and DELETE are already defined by the protocol. And ideally, to keep the interface generalized and to allow clients to be explicit about the operations they inoke, the Web serice should not define more erbs or remote procedures, such as /adduser or /updateuser. This general design principle also applies to the body of an HTTP request, which is intended to be used to transfer resource state, not to carry the name of a remote method or remote procedure to be inoked. Be stateless REST Web serices need to scale to meet increasingly high performance demands. Clusters of serers with load-balancing and failoer capabilities, proxies, and gateways are typically arranged in a way that forms a serice topology, which allows requests to be forwarded from one serer to the other as needed to decrease the oerall response time of a Web serice call. Using intermediary serers to improe scale requires REST Web serice clients to send complete, independent requests; that is, to send requests that include all data needed to be fulfilled so that the components in the intermediary serers may forward, route, and load-balance without any state being held locally in between requests. A complete, independent request doesn't require the serer, while processing the request, to retriee any kind of application context or state. A REST Web serice application (or client) includes within the HTTP headers and body of a request all of the parameters, context, and data needed by the serer-side component to generate a response. Statelessness in this sense improes Web serice performance and simplifies the design and implementation of serer-side components because the absence of state on the serer remoes the need to synchronize session data with an external application. Figure 1 illustrates a stateful serice from which an application may request the next page in a multi-page result set, assuming that the serice keeps track of where the application leaes off while naigating the set. In this stateful design, the serice increments and stores a preiouspage ariable somewhere to be able to respond to requests for next. Chapter 11. Designing and building APIs in the API Editor 207

216 Figure 29.. Diagram showing stateful design Stateful serices like this get complicated. In a Jaa Platform, Enterprise Edition (Jaa EE) enironment stateful serices require a lot of up-front consideration to efficiently store and enable the synchronization of session data across a cluster of Jaa EE containers. In this type of enironment, there's a problem familiar to serlet/jaaserer Pages (JSP) and Enterprise JaaBeans (EJB) deelopers who often struggle to find the root causes of jaa.io.notserializableexception during session replication. Whether it's thrown by the serlet container during HttpSession replication or thrown by the EJB container during stateful EJB replication, it's a problem that can cost deelopers days in trying to pinpoint the one object that doesn't implement the Serializable interface in a sometimes complex graph of objects that constitute the serer's state. In addition, session synchronization adds oerhead, which impacts serer performance. Stateless serer-side components, on the other hand, are less complicated to design, write, and distribute across load-balanced serers. A stateless serice not only performs better, it shifts most of the responsibility of maintaining state to the client application. In a RESTful Web serice, the serer is responsible for generating responses and for proiding an interface that enables the client to maintain application state on its own. For example, in the request for a multi-page result set, the client should include the actual page number to retriee instead of simply asking for next. Figure 30.. Diagram showing stateless design A stateless Web serice generates a response that links to the next page number in the set and lets the client do what it needs to in order to keep this alue around. This aspect of RESTful Web serice design can be broken down into two sets of responsibilities as a high-leel separation that clarifies just how a stateless serice can be maintained: Serer 208 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

217 Client application Generates responses that include links to other resources to allow applications to naigate between related resources. This type of response embeds links. Similarly, if the request is for a parent or container resource, then a typical RESTful response might also include links to the parent's children or subordinate resources so that these remain connected. Generates responses that indicate whether they are cacheable or not to improe performance by reducing the number of requests for duplicate resources, and by eliminating some requests entirely. The serer does this by including a Cache-Control and Last-Modified (a date alue) HTTP response header. Uses the Cache-Control response header to determine whether to cache the resource (make a local copy of it) or not. The client also reads the Last-Modified response header and sends back the date alue in an If-Modified-Since header to ask the serer if the resource has changed. This is called Conditional GET, and the two headers go hand-in-hand in that the serer's response is a standard 304 code (Not Modified) and omits 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 effect bypassing subsequent GET requests until the resource changes. Sends complete requests that can be sericed independently of other requests. This requires the client to make full use of HTTP headers as specified by the Web serice interface and to send complete representations of resources in the request body. The client sends requests that make ery few assumptions about prior requests, the existence of a session on the serer, the serer's ability to add context to a request, or about application state that is kept in between requests. This collaboration between client application and serice is essential to being stateless in a RESTful Web serice. It improes performance by saing bandwidth and minimizing serer-side application state. Transfer XML, JSON, or both? A resource representation typically reflects the current state of a resource, and its attributes, at the time a client application requests it. Resource representations in this sense are mere snapshots in time. This could be a thing as simple as a representation of a record in a database that consists of a mapping between column names and XML tags, where the element alues in the XML contain the row alues. Or, if the system has a data model, then according to this definition a resource representation is a snapshot of the attributes of one of the things in your system's data model. These are the things you want your REST Web serice to sere up. The last set of constraints that goes into a RESTful Web serice design has to do with the format of the data that the application and serice exchange in the request/response payload or in the HTTP body. This is where it really pays to keep things simple, human-readable, and connected. The objects in your data model are usually related in some way, and the relationships between data model objects (resources) should be reflected in the way they are represented for transfer to a client application. In the discussion threading serice, an example of connected resource representations might include a root discussion topic and its attributes, and embed links to the responses gien to that topic. Chapter 11. Designing and building APIs in the API Editor 209

218 And last, to gie client applications the ability to request a specific content type that's best suited for them, construct your serice so that it makes use of the built-in HTTP Accept header, where the alue of the header is a MIME type. Some common MIME types used by RESTful serices are shown in Table 1: Table 42. Common MIME types used by RESTful serices MIME-Type JSON XML XHTML Content-Type application/json application/xml application/xhtml+xml This allows the serice to be used by a ariety of clients written in different languages running on different platforms and deices. Using MIME types and the HTTP Accept header is a mechanism known as content negotiation, which lets clients choose which data format is right for them and minimizes data coupling between the serice and the applications that use it. z/os Connect EE API Editor for defining your APIs The z/os Connect EE API Editor helps you create an API package that describes the configuration of the API and the HTTP methods on the resources that can be called. For each path and method combination, you can select an existing z/os Connect EE serice and specify optional HTTP-to-JSON mappings. The mapping is based on a serice archie (SAR) file, a compressed collection of files that represent all the information that is needed by a z/os Connect EE serice proider to install and proide the serice, and to enable the serice as a JSON asset. The serice archie file is generated by the related tool for each of the z/os Connect EE serice proiders. For example, for IMS, use IMS Enterprise Suite Explorer for Deelopment. For CICS access through the WebSphere Optimized Local Adapters (WOLA), use the BAQLS2JS and BAQJS2LS utilities. With the serice archie, you can map an HTTP method to a field in the serice, or assign a alue to a field in the serice, by using the z/os Connect EE API Editor. After the mapping is complete, you export the API project into an API package in the form of an API archie file. The following diagram shows the API creation process. 210 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

219 Figure 31. API creation process in z/os Connect EE API package and API archie (AAR) A z/os Connect EE API package is generated as an API archie (AAR) file, a compressed collection of files with the following structure: package.xml, which describes the API and its implementation. An api/ directory that contains all the HTTP-to-JSON mapping information. An api-docs/ directory that holds the API documentation, including the Swagger document, swagger.json. A serices/ directory that contains serices that were imported in the z/os Connect EE API project. The generated Swagger document in the API package is the REST API equialent of a WSDL document for a SOAP-based web serice. Defining your API in z/os Connect EE API Editor With the API Editor, you can complete the following REST API deelopment tasks: Define an API by specifying a name, some description, the base path, and a ersion number. The base path is the root of all resources that are associated with this API. The base path can contain a ariable. Add or remoe one or more paths (relatie 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 remoe HTTP methods. You can reorder methods. Each method can be associated with: - A z/os Connect EE serice - One or more query parameters - One or more headers For each method, you can specify the following actions: Chapter 11. Designing and building APIs in the API Editor 211

220 - Assign a static alue to a field. - Assign a alue to a field from the header, path parameter, or query parameter. - Remoe a field. After the HTTP-to-JSON mapping is defined, you can deploy the API to the z/os Connect EE serer, or export the project as an API archie file for deployment by using the apideploy command. You can also deploy the API directly from the API Editor. Right click the API, then click z/os Connect EE > Deploy API to z/os Connect EE Serer. Testing, starting, and stopping an API After an API is deployed, you can single-click the API in the z/os Connect EE Serers iew to examine its properties. You can further use the proided Swagger UI to examine and test the operations in the API by double-clicking the API in the z/os Connect EE Serers iew. You can also start or stop a deployed API, or remoe an API from the serer, all from within the API Editor: Related concepts: RESTful web serices and API design on page 201 The primary focus of RESTful web serice design is to identify the z/os assets that need to be exposed, determine the HTTP methods that you want to support for those assets, and then map the resource identifiers and methods to those assets. 212 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

221 Related information: What is Swagger? Swagger RESTful API documentation specification Tips for using the API Editor for HTTP-to-JSON mapping You can use the common keyboard and mouse-click actions for your API design needs when you map HTTP request and response to the JSON schema of the serice. Use the keyboard and the mouse for HTTP to JSON mapping: Drag-and-drop to map data from the HTTP header, path parameter, or query parameters to fields in the serice. Right-click to access menus for actions applicable to the selected elements, such as adding/editing a query parameter, assigning a alue to a field, or undo a transform action. 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 and the fields in the serice on the other. As an API deeloper, your primary interest is to map the information from the HTTP request, typically in the header or a parameter to appropriate fields in the serice. If you open the response mapping, you see fields in the serice on the left and the HTTP response on the right. As an API deeloper, your primary interest is to determine what information from the serice to send back to the body in the HTTP response. Often times you would remoe some fields from the response and send back only needed information. Transform actions Designing your API is achieed mostly through the data transform actions: Moe: Moes data from the HTTP header, path parameter, or query parameters to appropriate fields in the serice. Remoe: Hides a field in the serice. This action is often used in the response mapping so unnecessary fields are not aailable to the API for the HTTP response. Assign: Assigns a static alue to a field in the serice. To moe data from the HTTP request to appropriate fields in the serice, moe your mouse oer the element in the HTTP request and drag. You can also easily add an HTTP header or a query parameter through the right-click menu. Chapter 11. Designing and building APIs in the API Editor 213

222 Figure 32. The right-click menu If you make a mistake, you can undo or delete your transform action by right-clicking the action and select Delete from the menu. Selecting multiple fields To select multiple fields for the same action, you hae seeral options: 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. Select a block of fields by drawing a box around the fields with your mouse. Figure 33. Selecting a block of fields by drawing a box 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 to select. 214 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

223 Figure 34. Selecting a block of fields by drawing a box Handling the null type in JSON schema Swagger 2.0 does not support the null type because Swagger supports only a subset of JSON schema. If a serice that is imported into the API contains nullable fields, as shown in the following example with "type": ["null", "string"], the first supported type (in this example, "string") is used, and only the Remoe transform is allowed in the mapping editor. { "type": "object", "properties": { "location": { "type": [ "null", "string" ], "maxlength": 16 } }, "required": [ "LOCATION" ] } Because Swagger 2.0 does not support the null type, nullable fields are indistinguishable from non-nullable fields in the Swagger document. When null types are sent to the z/os Connect EE serer, they are passed through in the body and not represented in the Swagger document. Setting preferences for the API Editor You can specify your preferences for default behaiors for host connections, API deployment, and logging in the preferences window. Chapter 11. Designing and building APIs in the API Editor 215

224 To set your preferences, from the menu bar, click Window > Preferences > z/os Connect EE. The API deployment and connection preferences apply to APIs that you will be deploying, updating, or remoing, or new connections that you will be creating. By default, APIs are started upon deployment and stopped upon update. You can oerride these default settings when you are creating indiidual host connections or deploying indiidual APIs. Connecting to a z/os Connect EE serer Create a host connection to the z/os Connect EE serer to iew, deploy, start, or stop an API. Before you begin Switch to the z/os Connect Enterprise Edition perspectie. About this task In the Host Connections iew, you can add connections to z/os Connect EE serers and credentials to store your user IDs and passwords. Tip: If you don't see the Host Connections iew, from the menu bar, click Window > Manage Connections to open the Host Connections iew. Procedure 1. In the Host Connections iew, click Add and select z/os Connect Enterprise Edition. 2. Specify the following information: Table 43. Adding a serer connection Field Name Host name Port number Description A descriptie name for the serer connection. The name or the IP address of the serer. The port number. Select the Secure connection (TLS/SSL) checkbox for secure connections. Connection timeout Read timeout The amount of time in milliseconds the API Editor will wait for a successful connection to be established with the z/os Connect EE serer before timing out. The default is 30 seconds unless specified otherwise in the z/os Connect EE preferences window. A alue of 0 indicates to wait foreer. The amount of time in milliseconds the API editor will read response data from the z/os Connect EE serer before timing out. The default is 30 seconds unless specified otherwise in the z/os Connect EE preferences window. A alue of 0 indicates to wait foreer. Tip: You can change the default connection timeout and read timeout alues. From the main menu bar, click Window > Preference > z/os Connect EE, and specify your default timeout alues. 216 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

225 3. Click Sae and Connect to sae the definition and connect to the serer. You will be prompted to either specify an existing credential to use, or create a credential 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 serer, this user credential is used for authorization. A trusted client certificate must be configured for user authentication by selecting Window > Preferences > Explorer > Certificate management. For more information, see Configuring client certificates for serer connections. This feature requires V or later of the API Editor. 4. After you select an existing credential or create a new one, click OK to use the credential to connect. Results The defined host connection shows up in the z/os Connect EE Serers iew. Deployed API packages are listed under the APIs folder. Related concepts: Setting preferences for the API Editor on page 215 You can specify your preferences for default behaiors for host connections, API deployment, and logging in the preferences window. Configuring client certificates for serer connections Generate a client certificate and configure the Eclipse preferences to send in the certificate from the API Editor to the z/os Connect EE serer. On the serer side, import the client certificate into the serer truststore and disable failoer to basic authentication. Before you begin Note: Support for client certificate configuration requires API Editor V or later. The embedded Swagger UI supports only basic authentication. Client authentication is not supported. If SSL is enabled on the z/os Connect EE serer (requiresecure attribute in serer.xml is set to true), and a trusted client certificate is not sent in for authentication, upon connection to the serer, you get an "HTTP 403 Forbidden" error. To connect to the serer from the API Editor, generate a client certificate first and import it into the truststore on the serer. 1. Generate your client certificate. This certificate is sent to the serer for authentication. Use a tool such as Keytool to create a keystore and then export the client certificate from the keystore. The following example shows the keytool command to create a keystore 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 Chapter 11. Designing and building APIs in the API Editor 217

226 Then export the client certificate (myclient.keystore.cer) from the client keystore: 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 EE serer. 3. On the z/os Connect EE serer, import the client certificate into the serer truststore. The following example shows the keytool command to import the client certificate into the serer truststore. keytool -import - -trustclientcerts -alias apieditor.client -file myclient.keystore.cer -keystore "<path_to>\serer.truststore.ks" -keypass mypassword -storepass mypassword 4. Modify the serer.xml file to ensure the following information is specified. Ensure the allowfailoertobasicauth attribute of the webappsecurity tag is set to false. <!-- Fail oer to basic authentication --> <webappsecurity allowfailoertobasicauth="false"/> Note: When you create an IMS serice in IMS Explorer, the allowfailoertobasicauth attribute must be set to true. If client authentication is required by the serer, change this attribute to false when you are designing and testing your APIs. The location and the password for the serer truststore is specified. For more information, see Configuring your web application and serer for client certificate authentication (WebSphere Application Serer for z/os Liberty). 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 saed. You can also click Browse to naigate 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 serices for the Windows operating system, which uses the standard Windows cryptography mechanism. To use a PKCS11 drier (mandatory on Mac OS and Linux operating systems), select Use PKCS11 drier and specify the drier path and PIN. 7. If you are instructed by your network administrator, select the correct protocol for your organization in the Secure socket protocol field. 8. Click Apply and OK to sae 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 iew. b. Click Add in the Credentials section and select Certificate from Keystore. c. Specify the user ID that is associated with the certificate. 218 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

227 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 serer connection authentication, allowing the serer to use the user ID that is specified for the host connection for authorization based on the defined security role. Related tasks: Creating a REST API Connecting to a z/os Connect EE serer on page 216 Create a host connection to the z/os Connect EE serer to iew, deploy, start, or stop an API. Related information: Defining connection credentials (IBM Explorer for z/os) For more information about defining connection credentials, see IBM Explorer for z/os documentation. Create a REST API for your z/os Connect EE serices by exporting your serice as a serice archie (SAR). Import the serice archie into your z/os Connect EE API project in the editor to model and define your API. Generating a serice archie You must first generate serice archie (SAR) files from z/os Connect EE serices for which you want to create APIs. About this task A SAR file contains the information that is needed by a z/os Connect EE serice proider to install and proide the serice, and to enable the serice as a JSON asset. Serice archies are required for serice interface mapping that uses the z/os Connect EE API Editor to map HTTP headers, path parameters, and query parameters with fields in the JSON schema of a z/os Connect EE serice. Procedure 1. Generate the serice archie (SAR) file for your serice by using the Build Toolkit. For more information about the Build Toolkit, see Chapter 10, Building a Serice Archie (SAR) by using the Build Toolkit, on page 193. Alternatiely, you can export your z/os Connect EE serices as serice archie (SAR) files in the supported tool for each of the z/os Connect EE serice proiders. For CICS access through WOLA, use the BAQLS2JS and BAQJS2LS utilities with the SERVICE-ARCHIVE and SERVICE-NAME parameters specified. 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 Explorer iew. You will import the SAR files into your API project. You will map path and methods to the serices that the SAR files contain. What to do next Create an API project. Chapter 11. Designing and building APIs in the API Editor 219

228 Creating an API project You can create a project by opening the z/os Connect EE API Project wizard when you are in the z/os Connect Enterprise Edition perspectie. Before you begin Switch to the z/os Connect Enterprise Edition perspectie. 1. From the main menu, select Window > Open Perspectie > Other. The Select Perspectie 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 Enterprise Edition perspectie: 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 Project name API name Base path Description Description Unique alphanumeric name for your project. The name of your API. If the API name matches an existing serice name, the API takes precedence oer the serice when the request is connected through IBM API Connect. The unique basepath attribute that specifies the root of all the resources in this API. If the same basepath is specified in different API packages, then the first is installed successfully and all others fail. If the API base path oerlaps with the inokeuri of a serice, the API is inoked rather than the serice. Description for your API. The API project is created in the Project Explorer iew. The API package.xml file opens in the API Editor where you can model your API. 3. Import your serice archie (SAR) files. Right-click an API project and click z/os Connect EE > Import z/os Connect EE Serices. What to do next Model your API. Modeling an API with the API Editor You can model your API by adding paths, creating methods, and associating the methods with related z/os Connect EE serices. Before you begin Generate a serice archie. Create an API project. 220 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

229 Procedure 1. In the Project Explorer iew, 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 a path parameter: /Patient/{patID} You can add paths by selecting the icon next to Path. Tip: When you sae your changes (Ctrl + S), package.xml is updated, and the changes are reflected in swagger.json. 3. Add methods. You can add methods by selecting the HTTP method POST GET PUT DELETE Description icon next to Methods. Adds a new instance of the specified resource. Retriees details about the specified resource. Updates information for the specified resource. Deletes information for the specified resource. 4. Assign a serice to a method by clicking Serice, then select a z/os Connect EE serice or import one from your Workspace or File System. Tip: If a serice is changed after the API is created, upon re-importing the changed serice, the impact of the changes is analyzed and reported. For more information, see Re-importing changed serices on page 225. What to do next Define HTTP-to-JSON mapping. Defining HTTP-to-JSON mapping The 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 EE serice. The JSON schema is the metadata that is used to communicate with the serice. Procedure 1. In the Project Explorer iew, 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 serice, and then select Open Request mapping (HTTP request) or Open Response mapping (HTTP response). The mapping editor opens. 3. Create HTTP headers and query parameters. To create an HTTP header, right-click HTTP Headers > Add HTTP Header. Chapter 11. Designing and building APIs in the API Editor 221

230 To create a query parameter, right-click Query Parameters > Add Query Parameter. 4. Map HTTP headers, path parameters, and query parameters with the serice JSON schema by dragging the header or parameter to a field in the JSON schema. 5. Assign any static alues or remoe any unnecessary field from the serice JSON schema. Mapping actions Assign Remoe Task Description Assigns a static alue to a field in the serice JSON schema for the HTTP request or HTTP response. Hides the alue from the HTTP request or HTTP response. Allows adding a description and detailed documentation for communication purposes. Note: With V of the editor or later, path and query parameters inherit the minimum, maximum, minlength, maxlength, exclusieminimum, and exclusiemaximum properties of the serice 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 iew. c. In the General tab of the Properties iew, type the required alue into the Value field. d. Optionally, add a description in the Documentation tab. Unmapped fields in the request JSON schema remain unchanged and get their alues from the body of the HTTP request. Example In the following example, a healthcare serice proider is deeloping an API to allow their patients to look up their registration information based on their patient ID. In the mapping editor, an API deeloper created and mapped the following HTTP header, path parameter, and query parameters for the GET HTTP method: HTTP header: X_TrackingID Enables the serice caller to proide the routing information (CA_ROUTING_CODE) for a patient with the HTTP header ariable called X_TrackingID. Path parameter: patid Enables the serice caller to set the alue for CA_PATIENT_ID as the proided patid alue. Query parameter: userid Enables the serice caller to set the alue for CA_USERID as the proided userid alue. Query parameter: zipcode Enables the serice caller to set the alue for CA_POST_CODE as the proided zipcode alue. 222 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

231 An example mapping configuration for the HTTP request and request JSON schema. What to do next Deploy an API. Deploying an API in the API Editor After you define your API, you can deploy the API directly to your z/os Connect EE serer from the API Editor. Before you begin By default, deployed APIs are automatically started. You can change this behaior by 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 to add security and authentication requirements. Manual changes to the Swagger document in the API editor are presered when saed. To edit the Swagger document by using your preferred JSON editor, the location of the Swagger document can be found by right-clicking the api-docs/ folder of your API project in the Project Explorer iew and selecting Properties. The location of the Swagger document is displayed in the Location field. Ensure that you are connected to the serer. For more information, see Connecting to a z/os Connect EE serer 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 Serer button ( ) in the corner. Chapter 11. Designing and building APIs in the API Editor 223

232 You can also deploy the API from Project Explorer iew, or by using the apideploy command on the serer. Procedure To deploy the API from the Project Explorer iew: 1. In the Project Explorer iew, select one or more API projects and right-click to select z/os Connect EE > Deploy API to z/os Connect EE Serer. 2. In the Deploy API window, select the serer to which to deploy the APIs. 3. If an API of the same name exists and you want to oerwrite it, select the Update existing APIs check box. 4. Click OK. Alternatiely, if you need to deploy the API by using the apideploy command on the serer: a. Right-click the API project and click z/os Connect EE > Export z/os Connect EE API Archie to sae the API as an API archie (AAR) file to a location of your choice. b. Transfer the API archie file in binary mode to a file system that the API Deployment utility can access. c. In an OMVS shell, issue the apideploy -deploy command. For more information, see. Results Deployment result is reported. Errors that occur during the deployment are recorded in the Problems iew. A deployed API is automatically started unless specified otherwise in the z/os Connect EE preferences window. Tips: To see the newly deployed APIs on the serer, in the z/os Connect EE Serers iew, right-click the serer, and select Refresh. As a software source code management best practice, sae a copy of the API project 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 215 You can specify your preferences for default behaiors for host connections, API deployment, and logging in the preferences window. Related tasks: Editing an existing API Generating an API archie on page 225 To deploy the API by using the API Deployment utility (apideploy -deploy command), you need to export your API project into an API archie (AAR) file. To edit an existing API in the editor, double-click the package.xml file in your project folder in the Project Explorer iew. To edit the request mapping or response mapping for a method, double-click the request.map or response.map file for the method in the /api folder of your project. 224 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

233 Re-importing changed serices If a serice is modified after an API is created, when it is re-imported into the project, the impact of the changes is analyzed. The impact is reported, and mapping problems are recorded in the Problems iew. About this task You can re-import one or more serices in one of two ways: Click Serice next to a method. Right-click the API project in the Project Explorer and click z/os Connect EE > Import z/os Connect EE Serices. Important: All APIs in the project that are associated with the re-imported serices are impacted. In the impact analysis dialog that is displayed, examine the impact. If the impact on the existing mappings is as expected, click OK to re-import the serices. The impacts are reported in the following categories: Errors An existing mapping is broken. A broken mapping occurs when a field that was inoled in an explicit Moe or Assign transform is remoed or renamed in the changed serice. The broken mapping is highlighted in the mapping editor when you open the request or response mapping. Generating an API archie Warnings A warning is a result of one of the following conditions: A field that was not explicitly inoled in any Moe or Assign transform but was implicitly passed through the request or response body is no longer aailable in the changed serice. The data type of a field is changed. A new field is added. Mapping issues are recorded in the Eclipse built-in Problems iew to assist problem resolution. To deploy the API by using the API Deployment utility (apideploy -deploy command), you need to export your API project into an API archie (AAR) file. Before you begin Make any final edits to the Swagger document. For example, you might want to add security and authentication requirements. Manual changes to the Swagger document are presered when saed. Procedure 1. In the Project Explorer iew, right-click an API project and click z/os Connect EE > Export z/os Connect EE API Archie. 2. Specify the location where you want to sae this API archie file. Chapter 11. Designing and building APIs in the API Editor 225

234 Results The API package is saed as a.aar file. What to do next 1. Transfer the file in binary mode to the host system where the API Deployment utility on the z/os Connect EE serer can access. 2. On the serer, issue the apideploy -deploy command to deploy the API. Related information: Examining, testing, starting and stopping an API You can examine, test, start, and stop an API in the z/os Connect EE Serers iew. Before you begin Switch to the z/os Connect Enterprise Edition perspectie. Ensure that you are connected to the serer. For more information, see Connecting to a z/os Connect EE serer on page 216. About this task The z/os Connect EE Serers iew in the z/os Connect Enterprise Edition perspectie proides a list of defined host connections and the APIs that are deployed on the serers. Procedure 1. In the z/os Connect EE Serers iew, ensure that the serer is connected. If the serer is not connected, right-click the serer and select Connect. 2. Expand the serer and the APIs folder to see all APIs that are deployed to the serer. 3. For each API, you can examine its status, description, and documentation. You can also start, stop, or remoe it. To examine the status, ersion number, api URL, description, and documentation of an API, click the API to see the information in the Properties iew. To examine and test the operations in the API in Swagger UI, double-click the 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/os Connect EE serer connection is secure (SSL/TLS), install and trust the serer's certificate by using Certificate Manager (Start > Run and select certmgr.msc) in Windows, or by using Keychain Access in MacOS. Because Swagger UI runs on a workstation rather than the serer where the API is hosted, cross-origin resource sharing (CORS) must be enabled on the serer, and the client (Swagger UI) must accept the self-signed certificate. For more information about CORS and related configuration, see Installing and trusting a self-signed certificate for Swagger UI on page 227. Tips: 226 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

235 You can disable the prompt about a alid TLS certificate is required. From the main menu bar, click Window > Preference > z/os Connect EE, and specify your choice. If you prefer to open the Swagger UI outside of the editor in an external browser, configure your Eclipse preferences by selecting Window > Preference > General > Web Browser, and specify your browser of choice. To temporarily stop further requests through the API, right-click the API and select Stop API. To restart the API, right-click and select Start API. To remoe an API, the API must be stopped first. After an API is stopped, right-click and select Remoe API. Tip: You can set the preferences to automatically stop an API upon remoal or to automatically start an API upon deployment in the z/os Connect EE preferences window. Related concepts: Setting preferences for the API Editor on page 215 You can specify your preferences for default behaiors for host connections, API deployment, and logging in the preferences window. Installing and trusting a self-signed certificate for Swagger UI To use the embedded Swagger UI, because it runs on a workstation rather than the serer where the API is hosted, cross-origin resource sharing (CORS) must be enabled on the serer, and the client (Swagger UI) must accept the self-signed certificate. Before you begin For more information about enabling CORS on the z/os Connect EE serer, see Configuring Cross-Origin Resource Sharing on a z/os Connect Enterprise Edition Serer on page 161. About this task Swagger UI does not proide diagnostics when the "Try It Out!" function fails due to a CORS issue. CORS is enforced by the browser and Swagger UI does not hae the isibility to the interaction between the browser and the resource (serer). When you use Swagger UI in the API Editor to inoke an API oer a secure connection, if the API is hosted on a serer with a self-signed or inalid certificate, you would encounter one of the following issues: The browser prompts you whether to accept or decline the self-signed or inalid certificate. If you accept, the request is sent to the serer. If you decline, the request is not sent and Swagger UI indicates that no response is receied. You are prompted again after restarting the browser. The browser does not prompt you at all, the request is not sent to the serer, and Swagger UI indicates that no response is receied. By default, when you open Swagger UI from within the API Editor, the Eclipse internal web browser is used. Installing the certificate into your external web browsers might not suffice. Installing and trusting the certificate at the operating system leel is the best way Chapter 11. Designing and building APIs in the API Editor 227

236 Procedure To install and trust a self-signed certificate, export the serer certificate from the serer and import it to the workstation where the API Editor is running: 1. On the z/os Connect EE serer, export the serer certificate. If the z/os Connect EE serer is using a SAF key ring: a. On the serer, generate a Certificate Authority (CA) root certificate. For example: RACDCERT CERTAUTH GENCERT SUBJECTSDN(CN( ZCEE Sample CA ) O( MYCOM ) OU( MYORG )) SIZE(1024 WITHLABEL( ZCEE-Sample-Certification ) TRUST NOTAFTER(DATE(2021/12/31) b. On the serer, create a serer certificate, signed by the CA. For example: RACDCERT ID (ZOSCONN) GENCERT SUBJECTSDN(CN( zceeserer.mycom.com ) O( MYCOM ) OU( MYORG )) SIZE(1024) SIGNWITH (CERTAUTH LABEL( ZCEE )) WITHLABEL( ZCEE-Serer ) NOTAFTER(DATE(2021/12/31)) c. Create a RACF key ring. RACDCERT ADDRING(ZCEE.KEYRING.wsc) ID(ZOSCONN) d. Connect the serer 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-Serer ) DEFAULT e. Update the serer configuration in serer.xml to point to the newly created key ring. <ssl id="defaultsslconfig" keystoreref="racfkeystore" sslprotocol="ssl_tls" sererkeyalias="zcee-serer" /> f. Export the certificate and sae 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 BINARY CONVERT(NO) RACDCERT ID(ZOSCONN) EXPORT(LABEL( ZCEE-Serer )) DSN( ZCONN.CERT.SERVER.P12 ) FORMAT(PKCS12 PASSWORD( password ) OPUT ZCONN.CERT.SERVER.P12 /u/deuser1/zcee/zcee.serer.p12 BINARY CONVERT(NO) If the z/os Connect EE serer is using a keystore: a. Locate the keystore for your z/os Connect EE serer. The default location of the keystore is /ar/zosconnect/serers/serername/ resources/security/keys.jks b. Extract your serer certificate from its keystore. Use the Jaa keytool to extract the certificate into a file named testserer.cer. Note that the alues of the parameters might differ for your configuration. keytool -export -alias default -file testserer.cer -keystore keys.jks -storepass zosconnect -storetype jks The message "Certificate stored in file testserer.cer" is displayed. 2. On your workstation, complete the certification configuration steps for your operation system. For Windows, take the following steps to configure the certificates. a. Open a command prompt or PowerShell, type certmgr.msc, and press Enter. b. Right-click Trusted Root Certification Authorities and select All Tasks > Import. c. Click Next when the Certificate Import Wizard appears. 228 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

237 d. On the "File to Import" page, specify the testserer.cer certificate file (created in Step 2). e. Click Next to adance 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 gien that the certificate cannot be erified (because it is self-signed), click Yes. i. Restart the API Editor and any web browsers that might be running. For MacOS, take the following steps to configure the certificates. a. Open the Keychain Access application. b. Select System in the Keychains iew. c. Select Certificates in the Category iew. d. Select File > Import items. e. Specify the testserer.cer certificate file (created in Step 2). You might be prompted for your user name and password to allow modification of the system keychain. The certificate is now displayed in the list, with the CN alue of the certificate as its name (for example, testserer.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 be prompted for your user name and password to allow modification of the certificate 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 Edition Serer on page 161 z/os Connect EE supports Cross-Origin Resource Sharing (CORS). Deeloping applications with Swagger documents The Swagger document that is generated by the z/os Connect EE API Editor can be examined and exposed in arious ways. A range of third-party tools are aailable for you to use with Swagger documents. Swagger UI With Swagger UI, you can isualize and test a REST API that is defined with Swagger from any web browser. The built-in testing functions let you graphically explore the APIs, test the APIs, and inspect the results. For more information, see GitHub: Swagger UI. Swagger Codegen With Swagger Codegen, you can generate a Software Deelopment Kit (SDK) in arious languages, including Jaa, Objectie-C, PHP, and Python, from a Swagger document for a REST API. You can use the resulting SDK to test the API in real time with a generated sample serer implementation before you fully implement the API. For more information, see GitHub: Swagger Code Generator. The editor.swagger.io site, for example, proides Swagger Editor, Swagger UI, and Swagger Codegen. Chapter 11. Designing and building APIs in the API Editor 229

238 Documenting your API using Swagger When you hae created your API, you can expose the API documentation to users. You can proide this documentation with Swagger. For more information, see Introduction to Swagger. For details in the Swagger specification, see Swagger RESTful API Documentation Specification. A RESTful administration interface for an API is aailable on the URI /<apibasepath>/api-docs and returns the Swagger document for the API, which is typically generated using the z/os Connect EE tooling. API Swagger documents are only returned if the API has been correctly initialized: HTTP method GET URI /<apibasepath>/api-docs Note: The only allowed methods for the URI are GET and OPTIONS. Return body Returns the Swagger document as a JSON string with an HTTP status code of 200 OK. Errors The host and port alues are added to the returned Swagger document, and oerride a host entry specified in the Swagger document on disk. The host name and port are deried from the request string. For any call using a HTTP method other than GET and OPTIONS, a HTTP status code of 405 Method Not Allowed is returned. If the <apibasepath> does not exist or cannot be accessed, a HTTP status code of 404 Not Found is returned. For more information, see Swagger RESTful API Documentation Specification. 230 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

239 Chapter 12. Administering SARs Automated SAR management Oerriding SAR properties Use this information to learn how to manage your serice archies. Serice archies (SARs) are deployed to a z/os Connect EE serer by copying them to a location which is defined in the serer.xml configuration file. Note: Only SAR files that are created by the build toolkit for the REST Client serice proider are suitable for SAR deployment. Deploy and undeploy your serice archies automatically when you add or remoe them from the serices folder. You can configure z/os Connect EE to deploy a serice archie automatically when you copy your SAR file to the location where your serices archies are stored. For example, resources/zosconnect/serices. When you remoe the SAR file from the folder, the serice is automatically undeployed. The serice location is monitored for changes to the SARs. You can control how and when z/os Connect EE reacts to these changes by setting the updatetrigger and pollingrate attributes of the zosconnect_serices element of the serer.xml configuration file. The default alue for pollingrate is 5000 msecs. For more information, see zosconnect_serices on page 306. Note: Serice definitions remain in the serer.xml configuration file after you delete or uninstall a SAR file. When you copy a SAR file to the SAR folder, ensure that the serice name is unique within the folder. For example, if test1.sar exists in the folder and contains a serice named test, then it must be remoed before you copy test2.sar, which also contains a serice named test. If both files are present when z/os Connect EE starts, the serice that is deployed is that of the first file that is read. When the other file is read, an error message is returned that the serice is already deployed. To update a serice, replace the SAR file in the SAR folder. The file must hae the same name. If the updatetrigger and pollingrate attributes of the zosconnect_serices element are set, the serice is installed automatically when the folder is polled. If you copy a SAR to the directory where a serice of the same name is already configured, the new serice will not be installed. When the serer is restarted, the new serice might install first, but this is unpredictable. Control the properties of a SAR when you deploy it. Copyright IBM Corp. 2015,

240 When you deploy a SAR that was supplied by a Serice Proider, certain properties can be oerridden. Properties are specified as nested elements inside a serice element. For example: <serice name="myserice" requireauth="true" requiresecure="true" runglobalinterceptors="false"> <property name="name1" alue="alue1"/> <property name= name2 alue= alue2 />... <property name= namex alue= aluex /> </serice> You must manually edit properties in the serer.xml configuration file. If the SAR file is deleted or moed, the properties remain in the configuration file and must be manually remoed. 232 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

241 Chapter 13. Administering APIs Automated API management Use this information to learn how to manage your APIs. APIs can be deployed to a z/os Connect EE serer using the API deployment utility, the API Editor, or the RESTful administration API. The API Editor or RESTful administration interface can also be used to get information on the APIs that hae been deployed and to stop an API from accepting requests. Deploy and undeploy your APIs automatically when you add or remoe them from the API folder. You can configure z/os Connect EE to deploy an API automatically when you copy your AAR file to the location where your APIs are stored. For example, resources/zosconnect/apis. When you remoe the API from the folder, it is automatically undeployed. The API location is monitored for changes to the API. You can control how and when z/os Connect EE reacts to these changes by setting the updatetrigger and pollingrate attributes of the zosconnect_zosconnectapis element of the configuration file serer.xml. The default alue for pollingrate is 5000 msecs. For more information, see zosconnect_zosconnectapis on page 309. Note: API definitions remain in the serer.xml configuration file after you delete or uninstall an API. This situation causes a warning message to be written to the log until the API is reinstalled. When you copy an AAR file to the API folder, ensure that the API name is unique within the folder. For example, if test1.aar exists in the folder and contains the API test, then it must be remoed before you copy test2.aar, which also contains an API named test. If both files are present when z/os Connect EE starts, one of the APIs is deployed. When the other file is read, an error message is returned that the API is already deployed. To update an API, replace the AAR file in the API folder. The file must hae the same name. If the updatetrigger and pollingrate attributes of the zosconnect_zosconnectapis element are set, the API is installed automatically when the folder is polled. Using the API Deployment utility Use this information to learn how to deploy, secure, and maintain your APIs. Securing access to APIs Before deploying an API, ensure that the underlying serice is aailable. Calling an API might fail if the called URI is not defined in the API, or if there is an error in the underlying serice. The failure will follow the standard HTTP rules. Related tasks: Copyright IBM Corp. 2015,

242 Deploying an API You must deploy an API to make it aailable to users. Undeploying an API on page 235 When you undeploy an API, you remoe it from the system and make it unaailable to users. Related reference: apideploy command syntax on page 328 Deploy or undeploy APIs Deploying an API You must deploy an API to make it aailable to users. Before you begin Note: To issue the API Deployment utility commands, you must be a z/os Connect EE serer administrator with access to the OMVS shell. You can also deploy an API directly from the z/os Connect EE API Editor. See instructions in Deploying an API in the API Editor on page 223. Follow these instructions to deploy an API using the API Deployment utility The API archie file must already reside on a UNIX System Serices file system on the same z/os LPAR where z/os Connect EE is installed. When transferring the API archie file to the file system, use binary mode. After the API archie file is transferred, ensure that the owner of the file has read and write permission (a minimum of 644 by using the UNIX System Serices chmod command). You must be a z/os Connect EE serer administrator to issue the API Deployment utility commands. The API deployment directory must already exist. The user that issues the API Deployment utility must hae the permission to write to the API deployment directory. The apideploy command is a supplied z/os UNIX command, so the administrator must hae access to the OMVS shell to use the command. Procedure 1. 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 relatie or absolute path to the API archie file (-a) and to the API deployment location (-p). For example, apideploy deploy a./myapi/goodhealth.aar -p <WLP_USER_DIR>/serers/<sererName>/resources/zosconnect/apis Results The API that is defined in the API archie file is saed to the z/os Connect EE serer directory. A directory that is based on the API name is created in the API deployment directory. 234 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

243 What to do next Depending on the configuration of your serer, you might need to restart the serer before the serer is ready to process HTTP requests for the related z/os Connect EE serices from a REST client. Related reference: apideploy command syntax on page 328 Deploy or undeploy APIs Undeploying an API When you undeploy an API, you remoe it from the system and make it unaailable 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 Connect EE serer 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 Serers iew in the editor, right-click the API and select Stop API to stop the API first. Then right-click the API and select Remoe API. Procedure 1. 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 relatie or absolute path to the API archie file (-a) and to the API deployment location (-p). For example, apideploy undeploy a./myapi/goodhealth.aar -p <WLP_USER_DIR>/serers/<sererName>/resources/zosconnect/apis. Results The API that is defined in the API archie file is undeployed. The directory with the name of the API is remoed from the API deployment directory. What to do next Depending on the configuration of your serer, you might need to restart the serer for the changes to take effect. Related reference: apideploy command syntax on page 328 Deploy or undeploy APIs Using the RESTful administration interface The administration interface for APIs is aailable in paths under /zosconnect/apis and proides meta-data for the APIs. Chapter 13. Administering APIs 235

244 A Swagger document describing the RESTful administration interface for z/os Connect EE is aailable on the URI /zosconnect/api-docs. Notes for all calls All successful calls return HTTP status code 200 unless otherwise specified. URLs returned by any of the calls contain the protocol, serer, and port from the request. Any call using a HTTP method with a URI not mentioned in these topics will return an error 405 Method Not Allowed. 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 error scenarios. GET a list of APIs You can use the HTTP method GET to obtain a list of the z/os Connect EE APIs installed in the runtime. HTTP method GET URI /zosconnect/apis Description Gets a list of the z/os Connect EE APIs installed in the runtime, including some basic information and a URL for more detailed information. APIs are included in the list whether they are started or stopped. Security Users with Administrator, Operator or Reader authority can get a list of APIs; users with Inoke authority cannot. Note: A user must be a member of a global group to be able to see all the resources. For more information about user authorization, see Oeriew of z/os Connect EE security on page 177. Return body { "apis":[ { "name":"{name}", "ersion":"{ersion}", "description":"{api description}", "adminurl":"http(s)://{host}:{port}/zosconnect/apis/{name}" },... repeats ] } where adminurl contains the URL where you can get more details for the specific API. For more information, see GET details of an API on page z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

245 Example body { "apis":[ { "name":"hospitalapi", "ersion":"1.0", "description":"api for Hospital app", "adminurl":" } ] } GET details of an API You can use the HTTP method GET to obtain information about a specific z/os Connect EE API. HTTP method GET URI /zosconnect/apis/{apiname} Description Gets the details of the requested z/os Connect EE API. Security Users with Administrator, Operator or Reader authority can get details of an API; users with Inoke authority cannot. Return body { "name":"{name}", "ersion":"{ersion}", "description":"{api description}", "status": "Started Stopped", "apiurl":"http(s)://{host}:{port}/{basepath}" "documentation": { "swagger":"http(s)://{host}:{port}/{basepath}/api-docs" } } where: apiurl is the URL you use to inoke the API. swagger contains the URL where the Swagger document for the API can be obtained. For more details see Documenting your API using Swagger on page 230 Example body { "name":"hospitalapi", "ersion":"1.0.0", "description":"api for Hospital app", "status": "Started", "apiurl":" "documentation": { "swagger":" } } Errors The following error can occur: 404 Not found The API was not found. Chapter 13. Administering APIs 237

246 GET a Serice Archie (SAR) You can use the HTTP method GET to retriee a serice archie for a specific serice. Note: This function is supported only by IMS HTTP method GET URI /zosconnect/serices/{sericename}?action=getarchie Description Gets a serice archie file, which is used to create a z/os Connect EE API. Security Users with Administrator, Operator or Reader authority can get an archie, users with Inoke authority cannot. Return body Returns the serice archie file, with the Content-Type for the response set to application/zip. Errors The following error can occur:: 204 No content The Serice proider returned null to signal it does not intend to support creating serice a Deploying an API You must deploy your API to make it aailable for use. You can use the HTTP method POST to deploy a z/os Connect EE API. HTTP method POST URI /zosconnect/apis Description Deploys an API into z/os Connect EE. Security Users with Administrator or Operator authority can deploy an API, users with Inoke or Reader authority cannot. Request body The API package file. The Content-Type for the request is application/zip. Response body { "name": "{name}", "ersion": "{ersion}", "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", "ersion": "1.0.0" "description": "Health API", "status": "Started", 238 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

247 Errors } "apiurl": " "documentation": { "swagger": " } The following errors can occur: 400 Bad request Inalid or missing API package 409 Conflict Package conflicts with the existing z/os Connect configuration 415 Unsupported media type Content-Type is not application/zip 500 Internal Serer Error Serer issue, may require administrator interention. Setting the initial status of a new API When you deploy a new API, the default initial status is set to Started. You can optionally set the initial status to Stopped by appending a query string to the HTTP POST method: HTTP method POST URI /zosconnect/apis?status=stopped Description Deploys a new API into z/os Connect EE and sets the status to Stopped. When an API is stopped, requests inoking the API will fail. Administration requests to /zosconnect/apis/{apiname} will still function as 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 Change the status of an API on page 241 Security Users with Administrator or Operator authority can set the initial status of an API, users with Inoke or Reader authority cannot. Request body API 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}", "ersion": "{ersion}", "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: Chapter 13. Administering APIs 239

248 400 Bad request Unknown status specified Update an API You can use the HTTP method PUT to update a z/os Connect EE API. Note: By default, an API will hae the status started. Howeer, it can be set to a specific initial status by appending a query string to the URI with a status. For example: /zosconnect/apis/{apiname}?status=stopped HTTP method PUT URI /zosconnect/apis/{apiname} Description Updates the named API in z/os Connect EE using the new API package file. Note: 1. The API needs to be stopped before updating. 2. The package being updated needs to be for the same API. Security Users with Administrator or Operator authority can update an API, users with Inoke or Reader authority cannot. Request body The API package file. The content type for the request is application/zip. Response body This function returns the Location header pointing to protocol:// serer:port/basepath { "name": "{name}", "ersion": "{ersion}", "description": "{API description}", "status": "Started Stopped", "apiurl": "http(s)://{host}:{port}/{basepath}" "documentation": { "swagger":"http(s)://{host}:{port}/{basepath}/api-docs" } where: apiurl is the URL you use to inoke the API. swagger contains the URL where the swagger document for the API can be obtained. For more details see Documenting your API using Swagger on page 230 Example response body { "name": "HospitalAPI", "ersion": "1.0.0", "description": "API for Hospital app", "status": "Started", "apiurl": " 240 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

249 "documentation": { "swagger":" } } Errors The following errors can occur: 400 Bad request Inalid or missing API package 409 Conflict A z/os Connect API must be stopped before it can be updated. 415 Unsupported Media Type Content-Type is not application/zip: 500 Internal Serer Error Serer issue, may require administrator interention. 503 Serice Unaailable A z/os Connect API must complete all outstanding requests before it can be updated. Change the status of an API A query string option can be used to set the status of an API. If the API package, is not usable, the operation fails. Note: When an API is stopped, the API will not inoke interceptors for new requests, and returns the following message: 503 Serice Unaailable 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 the status with the HTTP PUT method. HTTP method PUT URI /zosconnect/apis/{apiname}?status=started stopped Description Starts or stops the existing API. When an API is stopped, new requests will fail but existing requests will be allowed to complete. Administration requests to /zosconnect/apis/{apiname} will still function normally and the API will appear in the list returned by the /zosconnect/apis request. Security Users with Administrator or Operator authority can change the status of an API, users with Inoke or Reader authority cannot. Request body To change the status of an API, the request body should hae no content. If an API package is in the request body then the request is to update the API and set the initial status after the update. For more information, see Update an API on page 240. Example request To change the status of the API called apiname to started: /zosconnect/apis/apiname?status=started Chapter 13. Administering APIs 241

250 Response body { "name": "{name}", "ersion": "{ersion}", "description": "{API description}", "status": "Started Stopped", "apiurl": "http(s)://{host}:{port}/{basepath}", "documentation": { "swagger":"http(s)://{host}:{port}/{basepath}/api-docs" } } Errors Note: Responses from GET requests, such as GET /zosconnect/apis/ {apiname}?status=started, include the status property. For example: { "name": "API name", "ersion": "ersion", "description": "API description", "status": "Started Stopped", "apiurl": "API base path", "documentation": { "swagger": "API Swagger document location" } } 400 Bad request Unknown status specified Delete an API You can use the HTTP method DELETE to delete a z/os Connect EE API. HTTP method DELETE URI /zosconnect/apis/{apiname} Description Uninstalls the named API from z/os Connect EE, and deletes the API package from the file system. An API must be in stopped state to be deleted. Security Users with Administrator or Operator authority can delete an API, users with Inoke or Reader authority cannot. Return body { "name":"{api name}" } Example body { "name":"hospitalapi" } Errors The following errors can occur: 409 Conflict A z/os Connect API must be stopped before it can be deleted. 500 Internal Serer Error Serer issue, may require administrator interention. 242 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

251 503 Serice Unaailable A z/os Connect API must complete all outstanding requests before it can be deleted. Chapter 13. Administering APIs 243

252 244 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

253 Chapter 14. Client application deelopment When z/os Connect EE is successfully installed, you can create the artifacts that are needed for client applications to access your z/os serices. Related concepts: Auditing and tracking To audit and track requests, you can use the audit interceptor included with z/os Connect EE, or lie statistics for z/os Connect EE serices. The z/os Connect EE administration interface z/os Connect EE proides a set of APIs that you can use to discoer serices, check serice status, start or stop serices, get statistics, and complete other operations. You can use the z/os Connect EE administration interface from any client that is running in a web, mobile, or cloud enironment. The following examples demonstrate some of the calls that can be made by using the administration interface. 1. Discoer serices in the z/os Connect EE configuration by using a HTTP GET request. For example, The following sample shows the JSON payload that is returned: { zosconnectserices: [ { SericeName: "recordopscreate" SericeDescription: "Creates a new record" SericeProider: "SAMPLE-1.0" SericeURL: " }, { SericeName: "recordopsdelete" SericeDescription: "Deletes an existing record" SericeProider: "SAMPLE-1.0" SericeURL: " } ] } 2. Retriee configuration data for a serice. The output is returned in two parts: the first part contains the z/os Connect EE configuration parameters and the second part has the configuration that is returned by the serice proider implementation. The following sample shows the JSON payload that is returned: { zosconnect: { sericename: "recordopscreate" sericedescription: "Creates a new record" sericeproider: "SAMPLE-1.0" sericeurl: " sericeinokeurl: " dataxformproider: "jsonbyte-1.0" Copyright IBM Corp. 2015,

254 }, recordopscreate: { targetprogram: "CREATREC" timeout: "300ms" } } 3. Retriee serice status. The following sample shows the JSON payload that is returned: { zosconnect: { sericename: "recordopscreate" sericedescription: "Creates a new record" sericeproider: "SAMPLE-1.0" sericeurl: " sericeinokeurl: " dataxformproider: "jsonbyte-1.0" sericestatus: "Started" } } 4. Retriee request schema. 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 the serice name. 5. Retriee response schema. 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 the serice name. 6. Retriee statistics. Statistics include z/os Connect EE data for a serice such as InokeRequestCount, and a TimeOfRegistrationWithZosConnect, along with any other statistics returned by the serice proider by using the getstatistics() SPI implementation in the proider. Statistics for a particular serice can be retrieed through a /zosconnect/operation or an action= request call. /zosconnect/operations requests offer more flexibility because the product can retriee statistics for all serices. If the authorization interceptor is enabled, then the product returns statistics for only those serices that the user can request. See the documentation about z/os Connect security for more details. The following sample shows an HTTP GET request that uses action=getstatistics to return statistics: The following sample shows the JSON payload that is returned: 246 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

255 { recordopscreate: { SericeProider: "SAMPLE-1.0" InokeRequestCount: 100 TimeOfRegistrationWithZosConnect: "<yyyy-mm-dd hh:mm:ss:mmm tzn>" SericeStatistics: {.. <JSON name alue pairs showing statistical information about the serice returned.> } } } where yyyy-mm-dd is the date, hh:mm:ss:mmm time and tzn is the time zone. For example: :28:28:589 GMT. 7. Retrieing statistics for a serice can also be accomplished by using the URI in the administration interface. The information that is returned includes statistics for all serices that the current user can request. The following sample shows a HTTP GET request that uses /zosconnect/operation/getstatistics: The following sample shows the JSON payload that is returned: { zosconnectstatistics: [ { recordopscreate: { SericeProider: "SAMPLE-1.0" InokeRequestCount: 100 TimeOfRegistrationWithZosConnect: "<yyyy-mm-dd hh:mm:ss:mmm tzn>" SericeStatistics: {.. <JSON name alue pairs showing statistical information about the serice returned.> } } }, { recordopsdelete: { SericeProider: "SAMPLE-1.0" InokeRequestCount: 100 TimeOfRegistrationWithZosConnect: "<yyyy-mm-dd hh:mm:ss:mmm tzn>" SericeStatistics: {.. <JSON name alue pairs showing statistical information about the serice returned.> } } } ] } If no serices are registered with z/os Connect EE, the output resembles the following example: { zosconnectstatistics:[] } 8. Retriee statistics for all serices that are defined for a specific serice proider by using the URI in the administration interface. Sample HTTP GET request: Chapter 14. Client application deelopment 247

256 Sample format/output. { recordopscreate: { SericeProider: "SAMPLE-1.0" InokeRequestCount: 100 TimeOfRegistrationWithZosConnect: "<yyyy-mm-dd hh:mm:ss:mmm tzn>" SericeStatistics: {.. <JSON name alue pairs showing statistical information about the serice returned.> } } } 9. Retriee statistics for a single serice by using the URI in the administration interface. This operation is equialent to specifying action=getstatistics on a serice. HTTP GET request on: The following sample shows the JSON payload that is returned: { recordopscreate: { SericeProider: "SAMPLE-1.0" InokeRequestCount: 100 TimeOfRegistrationWithZosConnect: "<yyyy-mm-dd hh:mm:ss:mmm tzn>" SericeStatistics: {.. <JSON name alue pairs showing statistical information about the serice returned.> } } } 10. Stop z/os Connect EE serices by using an HTTP POST or PUT request with action=stop, or start the serices by using HTTP POST or PUT with the action=start query string. Stop and start actions do not require a payload. If one is proided, it is ignored. A user can retriee the status of a z/os Connect EE serice by using HTTP GET on the serice name with the action=status query string to retriee the serice status. If the authorization interceptor proided by z/os Connect EE is enabled, the user that is requesting the status change must be in the operator or administrator group that is required for the serice. For each, the Serice Proider SPI is called by z/os Connect EE to notify it that these actions were requested. The method names that are in the SPI for these actions are stop(), start(), and status(). Note: z/os Connect EE does not persist any state that is related to the serice and instead delegates this state to the serice proider. The serice proider can send responses other than stop or start. z/os Connect EE allows for a custom status to be returned. Stop a serice by using HTTP POST or PUT: The following sample shows the JSON payload that is returned: { zosconnect: { sericename: "recordopscreate" sericedescription: "Creates a new record" sericeproider: "SAMPLE-1.0" sericeurl: " sericeinokeurl: " 248 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

257 dataxformproider: "jsonbyte-1.0" sericestatus: "Stopped" } } 11. Start a serice sample by using HTTP POST or PUT: The following sample shows the JSON payload that is returned: { zosconnect: { sericename: "recordopscreate" sericedescription: "Creates a new record" sericeproider: "SAMPLE-1.0" sericeurl: " sericeinokeurl: " dataxformproider: "jsonbyte-1.0" sericestatus: "Started" } } 12. Inoke serices by using the z/os Connect EE query string: action=inoke, which runs the inoke() method of the Serice Proider SPI implementation. The sample in this step runs the inoke method for the serice that is named recordopscreate and passes a JSON object payload in the request body. The z/os Connect EE inoke method supports an input payload in JSON object form for this request. In the code example, it is assumed that z/os Connect EE looked up the Serice Proider and identified a serice reference for the serice called SAMPLE-1.0. A data transformation reference is contained in the z/os Connect EE serice definition with a proider called jsonbyte-1.0. When the inoke method of the serice proider gets control and calls the getbytes() method, the data transformation implementation gets control and conerts the request payload from JSON to a byte array and returns it to the serice proider. If the inoke action request has a URL that contains query parameters, then these parameters, and other HTTP request information, are passed to the serice proider by using thecom.ibm.zosconnect.spi.httpzosconnectrequest SPI interface that is proided by z/os Connect EE. Interceptors that are processed for actions or operations also receie HTTP request information through the same object. Another inocation style that is supported by z/os Connect EE proides a means to define a user-defined URI as the inokeuri in the z/os Connect serice definition. With this style, the HTTP request does not hae to contain zosconnect/serices and can instead be a user-defined string. When this style is employed, z/os Connect EE supports use of other HTTP methods, such as GET, PUT, POST, and DELETE. Requests arriing with this URI, regardless of the HTTP method that is employed, pass through z/os Connect EE interceptors and are passed to the inoke() method of the serice proider. Sample that uses HTTP POST or PUT: { <JSON object passed in for the serice inocation> } The following sample shows the JSON payload that is returned: { <JSON object returned from the serice inocation> } Chapter 14. Client application deelopment 249

258 Conersion for z/os Connect Enterprise Edition data transformation You can use the BAQLS2JS and BAQJS2LS utilities to generate the necessary z/os Connect Enterprise Edition artifacts to facilitate data conersion with the z/os Connect Enterprise Edition data transformation proider. The BAQLS2JS and BAQJS2LS utilities are proided for use with the supplied serice proider for CICS WOLA. Note: z/os Connect EE supports JSON integer alues in the range through Any language structures that you use as input to the BAQLS2JS utility, which generates JSON schemas with "type":"integer" and alues below or alues aboe are not supported. For example, For C, do not exceed long long. Unsigned long long is not supported. For COBOL, do not exceed PIC S9(18) COMP-5 or PIC S9(18) DISPLAY. 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 any integer alues do not exceed these limits. For more information about the language structure to JSON mappings and JSON to language structure mappings, see High-leel language and JSON schema mapping in the CICS TS Knowledge Center documentation. BAQLS2JS: High-leel language to binding and schema file conersion for z/os Connect Enterprise Edition data transformation The BAQLS2JS Job Control Language procedure generates a JaaScript Object Notation (JSON) schema and bind files from a high-leel data structure. The files that are generated are used by the z/os Connect Enterprise Edition data transformation process. Note: If you are generating a WSBind file and JSON schemas to use the z/os Connect EE data transformation feature, then you must use the naming conention that is required by the zosconnectdataxform element in the serer.xml file. The names of the request and response schemas must be of the format that is shown in the following example. The suffixes _request and _response are mandatory. The following example uses this naming conention: where SERVICE-ARCHIVE={sericearchie_dir}/{sericearchie} SERVICE-NAME={sericeName} WSBIND={wsbind_dir}/{sericeName}.wsbind JSON-SCHEMA-REQUEST={json_schema_dir}/{sericeName}_request.json JSON-SCHEMA-RESPONSE={json_schema_dir}/{sericeName}_response.json {sericename} must match the alue that is specified on the sericename attribute of the associated zosconnectserice element when you configure serer.xml file to use the DataXform. {sericearchie_dir>} is the UNIX System Serices directory in which the serice archie file is created {wsbind_dir} is the UNIX System Serices directory in which the wsbind file is created. 250 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

259 {json_schema_dir} is the UNIX System Serices directory in which the JSON request and response schemas are created. For example: <zosconnect_zosconnectserice id="inquirecatalogserice" sericename="<sericename>" sericeref="wolacatalogmanager" dataxformref="xformjson2byte" /> <!-- z/os Connect data transformation proider --> <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 EXEC Starts the job. Specifies the procedure name (BPXBATCH). Input Parameters BAQLS2JS runs a ersion of the CICS JSON assistant utility program DFHLS2JS. For input parameter descriptions, see the DFHLS2JS reference documentation. Where the documentation refers to DFHLS2JS, use BAQLS2JS. Two additional input parameters can be used to create a serice archie for z/os Connect Enterprise Edition: SERVICE-ARCHIVE The fully qualified z/os UNIX name of the serice archie file. DFHLS2JS creates the file, but not the directory structure, if it does not exist. SERVICE-NAME The name of the z/os Connect Enterprise Edition serice that is described by the serice archie. This name is specified by the SERVICE-ARCHIVE parameter. If you deelop APIs from the generated serice archie files, the API Editor uses the alue that is specified on the SERVICE-NAME parameter as the serice name associated with a specific API path and method. The following input parameters are alid for BAQLS2JS. The alue that is specified for the PGMNAME parameter is used in the generated JSON schema. Chapter 14. Client application deelopment 251

260 PDSLIB=alue PDSCP=alue REQMEM(data-alue) RESPMEM(data-alue) REQUEST-CHANNEL=alue RESPONSE-CHANNEL=alue LANG=COBOL LANG=PLI-ENTERPRISE LANG=PLI-OTHER LANG=C LANG=CPP STRUCTURE=(, ) request response PGMNAME=alue PGMINT=CHANNEL TRANSACTION=name USERID=id URI=alue PGMINT=COMMAREA CONTID=alue MAPPING-LEVEL=1.0 MAPPING-LEVEL=1.1 MAPPING-LEVEL=1.2 MAPPING-LEVEL=2.0 MAPPING-LEVEL=2.1 MAPPING-LEVEL=2.2 CHAR-VARYING=COLLAPSE DATETIME=UNUSED DATA-TRUNCATION=DISABLED CHAR-VARYING=BINARY MAPPING-LEVEL=3.0 DATETIME=PACKED15 DATA-TRUNCATION=ENABLED MAPPING-LEVEL=4.0 Adanced data mapping (mapping leel 4.0 and higher) MAPPING-LEVEL=4.1 Adanced data mapping (mapping leel 4.1 and higher) CHAR-VARYING=NO CHAR-VARYING=NULL MINIMUM-RUNTIME-LEVEL=MINIMUM MINIMUM-RUNTIME-LEVEL=CURRENT MINIMUM-RUNTIME-LEVEL=1.0 MINIMUM-RUNTIME-LEVEL=1.1 MINIMUM-RUNTIME-LEVEL=1.2 MINIMUM-RUNTIME-LEVEL=2.0 MINIMUM-RUNTIME-LEVEL=2.1 MINIMUM-RUNTIME-LEVEL=2.2 MINIMUM-RUNTIME-LEVEL=3.0 MINIMUM-RUNTIME-LEVEL=4.0 MINIMUM-RUNTIME-LEVEL=4.1 DATA-SCREENING=ENABLED DATA-SCREENING=DISABLED HTTPPROXY= domain name :port number HTTPPROXY-USERNAME=alue HTTPPROXY-PASSWORD=alue IP address CCSID=alue SYNCONRETURN=NO SYNCONRETURN=YES TRUNCATE-NULL-ARRAYS=DISABLED TRUNCATE-NULL-ARRAYS=ENABLED TRUNCATE-NULL-ARRAY-VALUES=NULL TRUNCATE-NULL-ARRAY-VALUES=SPACE TRUNCATE-NULL-ARRAY-VALUES=ZERO WSBIND=alue JSON-SCHEMA-REQUEST=alue JSON-SCHEMA-RESPONSE=alue LOGFILE=alue The following is sample JCL to run the BAQLS2JS tool. You can find this sample in the <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/2r0/bin/baqls2js LOGFILE=/u/userid/BAQLS2JS.log LANG=COBOL MAPPING-LEVEL=4.0 PDSLIB=//PROJECT.COBOL REQMEM=REQLS RESPMEM=RESPLS JSON-SCHEMA-REQUEST=/u/userid/schema/inquireCatalog_request.json JSON-SCHEMA-RESPONSE=u/userid/schema/inquireCatalog_response.json WSBIND=/u/userid/wsbind/inquireCatalog.wsbind 252 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

261 PGMNAME=DFH0XCMN PGMINT=COMMAREA /* //STDOUT DD SYSOUT=* //STDERR DD SYSOUT=* //STDENV DD * JAVA_HOME=/jaa/jaa71_64 // BAQJS2LS: JSON schema to high-leel language conersion for z/os Connect Enterprise Edition data transformation The BAQJS2LS JCL procedure generates a high-leel language data structure and binding file from a JSON schema. The files that are generated are used by the z/os Connect Enterprise Edition data transformation process. The alue that is specified for the PGMNAME parameter is used in the name of the generated high-leel language structure. Note: 1. If you use the WSBind file to call CICS ia an API, then JSON-SCHEMA-REQUEST and JSON-SCHEMA-RESPONSE must use schemas that specify only a single property at the top leel of the JSON format described. 2. If you are generating a WSBind file and JSON schemas for use in a z/os Connect Enterprise Edition DataXform, then you must use a naming conention that is expected by the zosconnectdataxform element in the serer.xml file. Specify the following alues for the BAQJS2LS parameters: SERVICE-NAME={sericeName} WSBIND={wsbind_dir}/{sericeName}.wsbind JSON-SCHEMA-REQUEST={json_schema_dir}/{sericeName}_request.json JSON-SCHEMA-RESPONSE={json_schema_dir}/{sericeName}_response.json where {sericename} must match the alue that is specified on the sericename attribute of the associated zosconnectserice element when you configure serer.xml file to use the DataXform {wsbind_dir} is the UNIX System Serices directory in which the wsbind file is created. {json_schema_dir} is the UNIX System Serice directory in which the JSON request and response schemas are stored. Job control statements for BAQJS2LS JOB EXEC Starts the job. Specifies the procedure name (BPXBATCH). Input parameters for BAQJS2LS BAQJS2LS runs a ersion of the CICS JSON assistant utility program DFHJS2LS. For input parameter descriptions, see the DFHJS2LS reference documentation. Where the documentation refers to DFHJS2LS, use BAQJS2LS. Two additional input parameters can be used to create a serice archie for z/os Connect Enterprise Edition: Chapter 14. Client application deelopment 253

262 SERVICE-ARCHIVE The fully qualified z/os UNIX name of the serice archie file. DFHJS2LS creates the file, but not the directory structure, if it does not exist. SERVICE-NAME The name of the z/os Connect Enterprise Edition serice that is described by the serice archie. This archie is specified by the SERVICE-ARCHIVE parameter. If you deelop APIs from the generated serice archie files, the API Editor uses this alue as the serice name associated with a specific API path and method. The following input parameters are alid for BAQJS2LS. The alue that is specified for the PGMNAME parameter is used in the name of the generated high-leel language structure. PDSLIB=alue PDSCP=alue REQMEM(data-alue) RESPMEM(data-alue) LANG=COBOL LANG=PLI-ENTERPRISE LANG=PLI-OTHER LANG=C LANG=CPP STRUCTURE=(, ) request response PGMNAME=alue PGMINT=CHANNEL CONTID=alue URI=alue PGMINT=COMMAREA TRANSACTION=name USERID=id MAPPING-LEVEL=1.0 MAPPING-LEVEL=1.1 MAPPING-LEVEL=1.2 Adanced data mapping (mapping leel 1.2 and higher) MAPPING-LEVEL=2.0 MAPPING-LEVEL=2.1 Adanced data mapping (mapping leel 2.1 and higher) MAPPING-LEVEL=2.2 Adanced data mapping (mapping leel 2.2 and higher) DATETIME=PACKED15 DATA-TRUNCATION=DISABLED MAPPING-LEVEL=3.0 Adanced data mapping (mapping leel 3.0 and higher) DATETIME=STRING DATA-TRUNCATION=ENABLED CHAR-OCCURS=STRING CHAR-USAGE=NATIONAL MAPPING-LEVEL=4.0 Adanced data mapping (mapping leel 4.0 and higher) MAPPING-LEVEL=4.1 Adanced data mapping (mapping leel 4.1 and higher) CHAR-OCCURS=ARRAY CHAR-USAGE=DBCS MAPPING-OVERRIDES= SAME-AS-MAPPING-LEVEL UNDERSCORES-AS-HYPHENS LESS-DUP-NAMES MINIMUM-RUNTIME-LEVEL=MINIMUM MINIMUM-RUNTIME-LEVEL=1.0 MINIMUM-RUNTIME-LEVEL=1.1 MINIMUM-RUNTIME-LEVEL=1.2 MINIMUM-RUNTIME-LEVEL=2.0 MINIMUM-RUNTIME-LEVEL=2.1 Adanced data mapping (runtime leel 2.1 and higher) MINIMUM-RUNTIME-LEVEL=2.2 Adanced data mapping (runtime leel 2.2 and higher) MINIMUM-RUNTIME-LEVEL=3.0 Adanced data mapping (runtime leel 3.0 and higher) MINIMUM-RUNTIME-LEVEL=4.0 Adanced data mapping (runtime leel 4.0 and higher) MINIMUM-RUNTIME-LEVEL=4.1 Adanced data mapping (runtime leel 4.1 and higher) MINIMUM-RUNTIME-LEVEL=CURRENT DATA-SCREENING=ENABLED DATA-SCREENING=DISABLED HTTPPROXY= domain name :port number HTTPPROXY-USERNAME=alue HTTPPROXY-PASSWORD=alue IP address JSON-SCHEMA-REQUEST=alue JSON-SCHEMA-RESPONSE=alue CCSID=alue NAME-TRUNCATION=alue LOGFILE=alue TRUNCATE-NULL-ARRAYS=DISABLED TRUNCATE-NULL-ARRAYS=ENABLED TRUNCATE-NULL-ARRAY-VALUES=NULL TRUNCATE-NULL-ARRAY-VALUES=SPACE TRUNCATE-NULL-ARRAY-VALUES=ZERO WSBIND=alue WIDE-COMP3=NO WIDE-COMP3=YES 254 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

263 Adanced data mapping (mapping leel 1.2 and higher): CHAR-VARYING=NO CHAR-VARYING=NULL CHAR-VARYING=YES CHAR-VARYING-LIMIT=32767 CHAR-VARYING-LIMIT=alue CHAR-MULTIPLIER=1 CHAR-MULTIPLIER=alue DEFAULT-CHAR-MAXLENGTH=255 DEFAULT-CHAR-MAXLENGTH=alue Adanced data mapping (mapping leel 2.1 and higher): INLINE-MAXOCCURS-LIMIT=1 INLINE-MAXOCCURS-LIMIT=alue 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/2r0/bin/baqjs2ls LOGFILE=/u/userid/BAQJS2LS.log LANG=COBOL MAPPING-LEVEL=4.0 PDSLIB=//PROJECT.COBOL REQMEM=REQLS RESPMEM=RESPLS JSON-SCHEMA-REQUEST=/u/userid/schema/inquireCatalog_request.json JSON-SCHEMA-RESPONSE=u/userid/schema/inquireCatalog_response.json WSBIND=/u/userid/wsbind/inquireCatalog.wsbind PGMNAME=DFH0XCMN PGMINT=COMMAREA /* //STDOUT DD SYSOUT=* //STDERR DD SYSOUT=* //STDENV DD * JAVA_HOME=/jaa/jaa71_64 // Return codes If the running utility program issues a non-zero return code, look in the job STDOUT and STDERR for messages about the cause of the problem. If no warning or error messages are found in STDOUT or STDERR, look for security-related messages in the system log of the LPAR. Fix the problem and rerun the utility program until a zero return code is obtained. Do not use artifacts that are generated with a non-zero return code. Chapter 14. Client application deelopment 255

264 Related concepts: z/os Connect EE API Editor for defining your APIs The z/os Connect EE API Editor helps you create an API package that describes the configuration of the API and the HTTP methods on the resources that can be called. Interacting with COBOL and TSO/ISPF Using WOLA in z/os Connect EE to allow a REST application to access z/os COBOL and z/os TSO/ISPF applications. Consider these requirements when you create a REST client that uses z/os Connect EE to access Batch applications. Figure 35. A REST client uses z/os Connect EE to access Batch applications. Essential requirements For a REST client to access z/os, COBOL, and z/os TSO/ISPF, certain functions must be proided, as shown in Figure 2: Figure 36. Functions required for a REST client to access COBOL and TSO/ISPF 1. Hosting of HTTP listen ports. 256 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

265 2. Proide 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, TSO/ISPF functions must hae good separation of the 3270 presentation layer from the business logic. Data requirements for COBOL must be understood. You can use z/os Connect EE and WOLA to proide these functions. Only 5 WOLA APIs are used. BBOA1REG The first step to using WOLA is to register to z/os Connect EE to create the cross-memory WOLA link. BBOA1SRV Host a serice. This serice holds program control until a request is receied. Output parameters include the connection handle, length of the request and address of the request. The TSO/ISPF function or COBOL module is started. BBOA1SRP Send a response back to z/os Connect EE. BBOA1CNR Release the connection that was gien to BBOA1SRV and return it to the pool. Return control to BBOA1SRV and listen on the HTTP port for the next request. BBOA1URG Unregister the connection to WOLA. Program structure A typical program would function as shown in Figure 3. Chapter 14. Client application deelopment 257

266 Figure 37. Typical program uses z/os Connect EE to connect to TSO/ISPF 1. BBOA1REG is called to create the connection between z/os Connect EE and WOLA. The HTTP port is then monitored for an incoming request. 2. The REST client sends a request. For example, 3. Request is mapped to the serice definition in the z/os Connect EE configuration file serer.xml: <zosconnectserice id="myserice" inokeuri="/myserice" sericename="myserice" sericeref="wolasc" /> 4. The serice definition maps to xml that defines the WOLA information and the serice to be started: 258 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition

267 <localadaptersconnectserice id="wolasc" registername="wolareg" sericename="sericename" connectionfactoryref="wolacf" /> 5. The serice name that is called by z/os Connect EE maps to the serice name hosted by BBOA1SRV. The request flows across WOLA, and the BBO1SRV API actiates and your program processes request: MOVE SericeName TO SRV-serice-name CALL BBOA1SRV USING register-name, SRV-serice-name, SRV-serice-name-length, SRV-rqst-area-addr, SRV-rqst-area-length, connect-handle, wait-time, rc, rsn, r In this example, serice-name is your BBOA1SRV serice name. Managing workload Processing of requests occurs relatiely quickly through z/os Connect EE, WOLA, and the COBOL bridge program. Any delay is likely to be in the TSO/ISPF functions or COBOL module. COBOL is single threaded, so if the requests arrie faster than they can be sericed, a queue forms. This queue is managed in the multi-threaded enironment 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: Chapter 14. Client application deelopment 259

268 Figure 38. Use z/os Connect EE to spread requests across multiple WOLA bridges. 2. Use WOLA into CICS and take adantage of the multi-threaded model of the WOLA link serer task. Note: You need to design the load-sharing interface between CICS and the TSO/ISPF functions or COBOL modules. Figure 39. Location of the load-sharing interface that you must design 3. Write a bridge program in C/C++ to take adantage of the multi-threaded capabilities. 260 z/os Connect Enterprise Edition: z/os Connect Enterprise Edition