Exposing CICS transactions with z/OS Connect
This chapter describes how to build a cloud-native application in IBM Bluemix and connect it to an IBM CICS Transaction Server running in your data center.
At the end of the chapter, you will know how to set up IBM z/OS Connect for CICS Transaction Server, create Representational State Transfer (REST) application programming interfaces (APIs) for your existing CICS transactions, and connect your application in IBM Bluemix to your CICS Transaction Server.
This chapter has the following sections:
7.1 Solution overview
CompanyB is looking for ways to drive more sales at the store and increase their customer satisfaction. The line of business is proposing a “virtual shopping list,” which will remind customers that they need to purchase something.
For example, a customer is probably using pencil and paper to build their weekly shopping list. They think they have remembered everything, but after the shopping trip, the customer realizes they forgot milk. Now they run to the convenience store to buy the milk, rather than spending that money at CompanyB’s store.
With this app, customers will be reminded that they need milk at the store the next time they go based on the purchasing history. The new application sees that they have been buying milk every two weeks and it has been about two weeks since they last bought milk. The customer will now spend the money at CompanyB’s store and be happy he did not have to make an extra trip to get milk.
The line of business is working with IT to determine how to take advantage of the vast amounts of data stored on their systems. The data is stored on their z Systems platform. They trust their business transactions to IBM CICS Transaction Server for z/OS, the premier enterprise-grade, mixed-language application server for mission critical applications.
The line of business wants to see this application delivered as soon as possible. To accomplish this, they want to do their development as well as host the initial version in a cloud environment.
They have chosen Bluemix as the platform to build their application for their easy to use platform with integration technologies for connecting to on-premises systems of record.
Here is a proposed architecture for the solution in Figure 7-1.
Figure 7-1 Proposed architecture of the virtual shopping list solution
CompanyB wants to reuse their proven programs running in CICS to get the data needed to provide recommendations to customers. z/OS Connect uses WebSphere Liberty Profile for z/OS to host the web application, which translates the REST APIs to a CICS transaction or program.
To connect their on-premises system of record, they use the Secure Gateway service in Bluemix, which connects via a DataPower gateway appliance.
 
Business case for this scenario: For more information about the business case for this scenario and the company profile, refer to 1.3.10, “Solutions and actions by the CompanyB CIO” on page 13.
This chapter describes how to configure z/OS Connect, set up the Secure Gateway service, configure DataPower, and build an application to get the data to come up with recommendations for their customers.
7.2 Step-by-step implementation
To implement this scenario, we first configure z/OS Connect for CICS, then connect IBM Bluemix to CICS using z/OS Connect, and finally use IBM API Management for the new APIs. In the following section, we describe these steps.
7.3 Configuring z/OS Connect for CICS
z/OS Connect for CICS is distributed as part of CICS Transaction Server V5.2 and later. You can configure z/OS Connect for CICS manually, and it is typically performed one time, with further configuration for individual services.
Before using this guide to configure z/OS Connect for CICS, you should be familiar with how to administer a CICS Transaction Server.
Enabling z/OS Connect should not affect the normal operation of the CICS Transaction Server.
To configure z/OS Connect, perform the following steps:
1. Create the Java virtual machine (JVM) server to host WebSphere Liberty Profile.
2. Configure the JVM server.
3. Create the pipeline for the existing CICS transactions to z/OS Connect.
4. Configure the WebSphere Liberty Profile.
5. Install the JVM server and pipeline.
6. Validate the configuration.
7.3.1 Creating the JVM server for z/OS Connect
It is important to consider whether you already have a WebSphere Liberty Profile JVM server that is configured in CICS. Although it is possible to host z/OS Connect and other unrelated services in the same WebSphere Liberty Profile environment, it is a good practice to configure a separate JVM server for the sole use of z/OS Connect. It is also a good practice to only have a single WebSphere Liberty Profile JVM server that is configured in any single CICS region. You can host z/OS Connect in its own CICS region, or group of CICS regions, and use the Distributed Program Link mechanism to call CICS programs in the application-owning CICS regions.
Enter the CICS terminal and use the CEDA transaction to define a JVM server:
CEDA DEF JVMSERVER
You are presented with the panel shown in Figure 7-2. The descriptions for the attributes of a JVM server are described in Table 7-1.
Figure 7-2 Defining a JVM server to host WebSphere Liberty Profile for z/OS Connect
Table 7-1 Description for the attributes of a JVM server
Attribute
Description
Jvmserver
Specifies the 1 - 8 character name of the JVMSERVER resource.
Description
The description text can be up to 58 characters in length. No restrictions apply to the characters that you can use. However, if you use parentheses, ensure that for each left parenthesis there is a matching right one. If you use the CREATE command, for each single apostrophe in the text, code two apostrophes.
Group
Every resource definition must have a GROUP name. The resource definition becomes a member of the group and is installed in the CICS system when the group is installed.
 
The GROUP name can be up to 8 characters in length. Lowercase characters are treated as uppercase characters.
Jvmprofile
Specifies the 1 - 8 character name of the JVM profile containing the JVM options for running a JVM server. The file containing the JVM profile must have a file extension of .jvmprofile.
 
For a JVM profile for a JVMSERVER resource defined by online resource definition, the file path is specified by the system initialization parameter JVMPROFILEDIR.
 
For a JVM profile for a JVMSERVER resource defined by online resource definition, the file path is specified by the system initialization parameter.
Lerunopts
Specifies the 1 - 8 character name of the program that defines the runtime options for the IBM Language Environment® enclave. DFHAXRO is a supplied program that provides a set of default values. The source for DFHAXRO is in the hlq.SDFHSAMP library if you want to change the defaults for any of the Language Environment runtime options.
 
If you want to use a different program, put the program in the hlq.SDFHLOAD library and specify the program name in uppercase characters.
Status
Specifies the initial status of the PIPELINE when it is installed. Valid values are ‘Enabled’ or ‘Disabled’
Threadlimit
Specifies the maximum number of threads that are allowed in the Language Environment enclave for the JVM server. Each thread runs under a T8 TCB. You can specify a limit in the range of 1 - 256 threads.
 
If you specify a thread limit that exceeds the maximum of 2000 threads that is allowed for the CICS region, considering all other enabled and disabled JVMSERVER resources, CICS allocates the remaining threads up to 2000 to the resource as the thread limit value. If CICS is already at the maximum number of JVMSERVER threads, the resource installs in a disabled state.
Here are the values used in this scenario to create the JVM server in Figure 7-3.
Figure 7-3 Values for creating the JVM server
7.3.2 Configuring the JVM server
After the JVM is created, the .jvmprofile file needs to be created. The location where the .jvmprofile should be created is defined in the system initialization data set when CICS is started. The location of this data set is specified in the user PROCLIB of the CICS installation (see Figure 7-4).
Figure 7-4 User PROCLIB for the CICS Transaction Server named CICS52. The system initialization data set for CICS is specified in SYSIN when CICS is started
Next, the data set needs to be modified to specify the path in zFS where the .jvmprofile should go in Figure 7-5. The data set needs to specify the JVMPROFILEDIR property with the path where the .jvmprofile should go.
Figure 7-5 The system input parameter table is modified to specify JVMPROFILEDIR as /u/user1/CICS/JVMProfiles
A template can typically be found in zFS here:
/usr/lpp/cicsts/JVMProfiles/DFHWLP.jvmprofile
 
Note: The template file might be in a different directory depending on how the CICS Transaction Server was installed.
This file can be copied to the path specified by the JVMPROFILEDIR. The file name must be the same as the JVMPROFILE attribute, which was specified when the JVM server was created. In this scenario, the JVM profile directory was created here:
/u/user1/CICS/JVMProfiles/DFHZOSC.jvmprofile
The following properties should be modified to values that are applicable to the system running z/OS Connect:
•JAVA_HOME should be set to the location of your installed IBM Java SDK.
•WORK_DIR should be set to your choice of destination directory for messages, trace, and output from the JVM server. In this scenario, it has been set to /u/user1/CICS.
•WLP_INSTALL_DIR should be set to &USSHOME;/wlp.
 
 
Note: The -Dcom.ibm.cics.jvmserver.wlp.autoconfigure property is purposely left uncommented, which means that the server.xml must be provided by the user. This is recommended for production environments.
When the autoconfigure property is not set, the following properties are ignored from the .jvmprofile configuration file:
-Dcom.ibm.cics.jvmserver.wlp.server.http.port.
-Dcom.ibm.cics.jvmserver.wlp.server.host.
-Dcom.ibm.cics.jvmserver.wlp.server.name.
Note: The WLP_USER_DIR property is left uncommented, which means that it uses the default value, which is WORK_DIR/<APPLID>/<JVM server name>. In this scenario, the effective value for WLP_USER_DIR is /u/user1/CICS/CICS01/DFHZOSC.
7.3.3 Mapping the pipeline for existing CICS transactions to z/OS Connect
You can follow these steps to map the pipeline for existing CICS transactions to z/OS Connect.
 
Creating the pipeline in CICS
The first step in mapping a CICS transaction to z/OS Connect is to create a CICS pipeline.
To define the pipeline in CICS, it must know which JVM server to use as well as the directory where the web service bind files are located.
Creating the pipeline XML file for the JVM server
The JVM server for the pipeline must be defined in an XML file. A template for this file is found in zFS here:
/usr/lpp/cicsts/samples/pipelines/jsonzosconnectprovider.xml
 
Note: The template file might be in a different directory depending on how the CICS Transaction Server was installed.
In this scenario, the template file was copied here:
/u/user1/CICS/pipeline/DFHZOSC_pipeline.xml
In this file, the value of the jvmserver property needs to be changed to match the name of the JVMSERVER used for z/OS Connect. In this scenario, the JVM server name is DFHZOSC. The pipeline XML file used in this scenario is in Example 7-1.
Example 7-1 The pipeline XML file that will be used in the definition of the pipeline
<?xml version="1.0"?>
<!--
<copyright
notice="cics-lm-source-program"
pids="5655-Y04"
years="2013,2014"
crc="2249679448" >
Licensed Materials - Property of IBM
5655-Y04
(C) Copyright IBM Corp. 2014 All Rights Reserved.
US Government Users Restricted Rights - Use, duplication or
disclosure restricted by GSA ADP Schedule Contract with
IBM Corp.
@{[**]copyright.years=2014}
</copyright>
-->
<provider_pipeline_json xmlns="http://www.ibm.com/software/htp/cics/pipeline">
<jvmserver>DFHZOSC</jvmserver>
</provider_pipeline_json>
Creating the directory for the web service bind files
A set of web service bind files will be created for each program or transaction that is mapped to a web service.
The directory for these bind files must be manually created. In this scenario, this directory was created:
/u/user1/CICS/wsbind/
Defining the pipeline
After creating the pipeline XML file and the directory for the web service bind files, the pipeline can be defined in CICS. From a CICS terminal, use this command:
CEDA DEF PIPELINE
The panel for defining a pipeline is displayed as shown in Figure 7-6 on page 166. The attributes for the pipeline definition are described in Table 7-2 on page 166.
 
Figure 7-6 Defining a CICS pipeline for the web service
Table 7-2 Descriptions for the attributes of a pipeline
Attribute
Description
Configfile
Specifies the fully qualified or relative name of a z/OS UNIX file that contains information about the processing nodes that act on a service request, and on the response.
 
A sample pipeline configuration file for z/OS Connect can be found in “Creating the pipeline XML file for the JVM server” on page 164.
Description
The description text can be up to 58 characters in length. No restrictions apply to the characters that you can use. However, if you use parentheses, ensure that for each left parenthesis there is a matching right one. If you use the CREATE command, for each single apostrophe in the text, code two apostrophes.
Group
Every resource definition must have a GROUP name. The resource definition becomes a member of the group and is installed in the CICS system when the group is installed.
 
The GROUP name can be up to 8 characters in length. Lowercase characters are treated as uppercase characters.
Pipeline
Specifies the name of this PIPELINE. The name can be up to 8 characters in length.
Respwait
Specifies the number of seconds that an application program should wait for a response message from a remote web service. The value can range 0 - 9999 seconds.
 
To use the default timeout value of the transport protocol, specify DEFT. The default timeout value is also used if you do not specify any value for RESPWAIT.
Shelf
Specifies the 1 – 255 character fully qualified name of a directory (a shelf, primarily for web service binding files) on z/OS UNIX.
 
CICS regions into which the PIPELINE definition is installed must have full permissions to the shelf directory: Read, write, and the ability to create subdirectories.
 
A single shelf directory can be shared by multiple CICS regions and by multiple PIPELINE definitions. Within a shelf directory, each CICS region uses a separate subdirectory to keep its files separate from those of other CICS regions. Within each region’s directory, each PIPELINE uses a separate subdirectory.
 
You should not attempt to modify the contents of a shelf that is referred to by an installed PIPELINE definition. If you do, the effects are unpredictable.
 
Status
Specifies the initial status of the PIPELINE when it is installed. Valid values are ‘Enabled’ or ‘Disabled’
Wsdir
Specifies the 1 – 255 character fully qualified name of the web service binding directory (also known as the pickup directory) on z/OS UNIX. Each PIPELINE installed in a CICS region must specify a different web service binding directory.
 
The web service binding directory contains web service binding files that are associated with a PIPELINE, and that are to be installed automatically by the CICS scanning mechanism. When the PIPELINE definition is installed, CICS scans the directory and automatically installs any web service binding files that it finds there. This happens regardless of whether the PIPELINE is installed in an enabled or disabled state.
 
If you specify a value for the WSDIR attribute, it must refer to a valid z/OS UNIX directory to which the CICS region has at least read access. If not, any attempt to install the PIPELINE resource fails.
 
If you do not specify a value for WSDIR, no automatic scan takes place on installation of the PIPELINE.
For the pipeline that is created in this scenario, the values are displayed in Figure 7-7.
Figure 7-7 Define pipeline window
Create the mapping between JSON and COBOL program
The CICS JSON assistant is a set of batch utilities that creates a mapping between JSON schema and language structures. This mapping is used by CICS at run time to do the transformation between JSON and application data. The assistant supports rapid deployment of CICS applications for use in service providers and service requesters, with the minimum of programming effort.
When you use the JSON assistant for CICS, you do not have to write your own code for parsing inbound messages and for constructing outbound messages; CICS maps data between the JSON message and the application program's data structure.
In this scenario, the DFHLS2JS procedure is used to generate a JSON schema file from our COBOL program.
The DFHLS2JS JCL procedure is installed in the data set HLQ.XDFHINST, where HLQ is the high-level qualifier where CICS is installed.
The JCL used to create the mapping in this scenario is shown in Example 7-2. In this scenario, the program being called is BBIORD01 and the transaction is BBOI. There are three output files, the .wsbind file, the request JSON file, and the response JSON file. The three files are placed into the directory named:
/u/user1/CICS/wsbind
This directory is the same one that was created in “Creating the directory for the web service bind files” on page 165 and specified as a parameter when the pipeline was defined.
The URI that is used when the web service is called is /BBAPP/InquireOrder. This is arbitrary and the name that is chosen for this scenario.
Example 7-2 JCL that calls DFHLS2JS JSON assistant for CICS to create the proper mapping from JSON to the program’s data structure
//LS2JS EXEC DFHLS2JS,
// USSDIR='dfh520',
// PATHPREF='',
// JAVADIR='java/J7.1_64',
// TMPDIR='/tmp',
// TMPFILE=''
//INPUT.SYSUT1 DD *
LOGFILE=/u/user1/CICS/LS2JS_LGIJORD01.LOG
PDSLIB=USER1.BB12.SOURCE
REQMEM=SOAIO01
RESPMEM=SOAIO01
LANG=COBOL
PGMNAME=BBIORD01
URI=/BBAPP/InquireOrder
TRANSACTION=BBOI
PGMINT=COMMAREA
MAPPING-LEVEL=3.0
WSBIND=/u/user1/CICS/wsbind/getOrderDetails.wsbind
JSON-SCHEMA-REQUEST=/u/user1/CICS/wsbind/getOrderDetailsReq.json
JSON-SCHEMA-RESPONSE=/u/user1/CICS/wsbind/getOrderDetailsResp.json
/*
7.3.4 Configure WebSphere Liberty Profile for z/OS Connect
The WebSphere Liberty Profile for z/OS Connect needs to be configured by creating the server.xml file manually. A template of the server.xml file can be found here:
/usr/lpp/cicsts/wlp/templates/servers/defaultServer/server.xml
 
Note: The template file might be in a different directory depending on how the CICS Transaction Server was installed.
The template server.xml file should be copied here:
/u/user1/CICS/CICS01/DFHZOSC/wlp/usr/servers/defaultServer/server.xml
This path is based on the WLP_USER_DIR property in the .jvmprofile configuration file. In this scenario, the WLP_USER_DIR is /u/user1/CICS/CICS01/DFHZOSC. The rest of the directory structure is expected by the WebSphere Liberty Profile for the server.xml.
 
Note: The server.xml file must be encoded in UTF-8. The EU command can be used under z/OS UNIX Directory List utility (ISPF menu option 3.17).
Example 7-3 is the server.xml file used for this scenario. It has been updated from the template file to add the following:
•The feature managers for cicsts:zOS-Connect-1.0
•The httpEndpoint was modified to specify the httpsPort
•The CICSEndpoint attribute
•The zOSConnectService attribute. The values are from the JCL that was executed to create the web service bindings in Example 7-2 on page 169
Example 7-3 The server.xml configuration file for WebSphere Liberty Profile for z/OS Connect
<?xml version="1.0" encoding="UTF-8"?><server description="CICS Liberty profile sample configuration">
 
<!-- Enable features -->
<featureManager>
<feature>cicsts:core-1.0</feature>
<feature>jsp-2.2</feature>
<feature>wab-1.0</feature>
<feature>blueprint-1.0</feature>
<feature>ssl-1.0</feature>
<feature>cicsts:zosConnect-1.0</feature>
<feature>appSecurity-2.0</feature>
</featureManager>
 
<!-- Default HTTP End Point -->
<httpEndpoint host="*" httpPort="9080" httpsPort="9443" id="defaultHttpEndpoint"/>
<com.ibm.cics.wlp.zosconnect.CICSEndpoint id="com.ibm.cics.wlp.zosconnect.CICSEndpointService"/>
s
<zosConnectService invokeURI="/BBAPP/InquireOrder" serviceName="getOrderDetails" serviceRef="com.ibm.cics.wlp.zosconnect.CICSEndpointService"/>
 
<!-- CICS Bundle Installed Applications -->
<include location="${server.output.dir}/installedApps.xml"/>
 
<!-- The following configuration controls how often server.xml
is scanned for updates. The default is every 500ms which may
cause excessive I/O and CPU cost on z/OS.
The values shown below reduce the overhead while still
providing a relatively timely detection of new applications
that have been installed/removed via a CICS Bundle
(WAR bundlepart). If you use CICS bundles to install Web
Applications (WAR files) do not disable the polling.
-->
<config monitorInterval="5s" updateTrigger="polled"/>
 
<!-- Further scanning is performed to detect application updates or
addition/removal of applications to the dropins directory. If
you are using CICS Bundles as the vehicle for Application
deployment you should disable the dropins directory as shown.
Further I/O and CPU reduction can be achieved by disabling
the application scan. To effect changes to your applications
while the server is still running, you should disable and
re-enable the CICS bundle that contains the Web application.
The pollingRate is only applicable when the updateTrigger is
set to the 'polled' value.
Consult the WebSphere Application Server Liberty Profile
documentation for further information on these parameters.
-->
<applicationMonitor dropins="dropins" dropinsEnabled="false" pollingRate="5s" updateTrigger="disabled"/>
 
<ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" sslProtocol="TLS"/> <keyStore id="defaultKeyStore" password="defaultPassword"/>
 
</server>
7.3.5 Starting the JVM server and pipeline
Now, all the artifacts needed for our web service have been created and we can install the JVM server configured to z/OS Connect for CICS and the pipeline from z/OS Connect to our CICS transaction.
The JVM server should be installed before the pipeline is installed.
Installing the JVM server
To install the JVM server, use the CEDA transaction to open the JVM server with this command:
CEDA INSTALL GROUP(DFH$ZOSC) JVMSERVER(DFHZOSC)
Use the same GROUP and JVMSERVER parameters when the JVM server was defined in 7.3.1, “Creating the JVM server for z/OS Connect” on page 160.
Installing the pipeline
To install the pipeline, use the CEDA transaction to install the pipeline with this command:
CEDA INSTALL GROUP(DFH$ZOSC) PIPELINE(ZOSCPIPE)
Use the same GROUP and PIPELINE parameters when the pipeline was defined in 7.3.3, “Mapping the pipeline for existing CICS transactions to z/OS Connect” on page 164.
7.3.6 Accessing the REST API
Now that z/OS Connect is running and the web services have been mapped to the CICS transaction, z/OS Connect can be validated to ensure that it is running as well as the available web services it is providing.
Simply call this URL:
https://<server name or IP Address>:9443/zosConnect/services
The port 9443 is the httpsPort that was defined in the server.xml file in 7.3.4, “Configure WebSphere Liberty Profile for z/OS Connect” on page 169.
The output in this scenario looks like what is shown in Example 7-4.
Example 7-4 Output from REST API for validating z/OS Connect setup
{
"zosConnectServices": [
{
"ServiceName":"getOrderDetails",
"ServiceDescription":"DATA_UNAVAILABLE",
"ServiceProvider":"com.ibm.cics.wlp.zosconnect.CICSEndpointServiceImpl",
"ServiceURL":"https://cics-server:9443/zosConnect/services/getOrderDetails"
}
]
}
7.4 Connecting IBM Bluemix to CICS
Bluemix has a service named Secure Gateway service to connect Bluemix to on-premises systems.
In this scenario, the Secure Gateway service is used to connect the application running in Bluemix to the CICS system via z/OS Connect.
The Secure Gateway service requires a client that can reach the z/OS Connect system. In this scenario, the client running on-premises is a Data Power appliance.
Configuring the Secure Gateway
To configure the Secure Gateway service, log on to Bluemix and complete the following steps:
1. Click Catalog. Then, enter Secure Gateway in the Search field as shown in Figure 7-8. Click Secure Gateway.
Figure 7-8 Bluemix catalog with Secure Gateway service
2. Click CREATE as shown in Figure 7-9.
Figure 7-9 Secure Gateway service details
3. Click ADD GATEWAY to create a new gateway instance, as shown in Figure 7-10.
Figure 7-10 Secure Gateway landing page
4. Enter My gateway in the What would you like to name this new gateway? field, as shown in Figure 7-11. Click CONNECT IT.
Figure 7-11 Secure Gateway creation process
5. Click IBM DataPower as shown in Figure 7-12. Click COPY to copy the generated Gateway ID to clipboard.
Figure 7-12 Secure Gateway connection process
Configuring the IBM DataPower Gateway
To continue the integration process, open a new web browser window, connect to IBM DataPower Gateway web interface, and complete the following steps:
1. Log in to IBM DataPower Gateway web interface as shown in Figure 7-13.
Figure 7-13 IBM DataPower Gateway login page
2. Enter secure gateway in the Search field in the upper left corner of the window, as shown in Figure 7-14. Click Secure Gateway Client.
Figure 7-14 IBM DataPower Gateway search
3. Click Add as shown in Figure 7-15.
Figure 7-15 Secure Gateway Client list
4. Enter Bluemix in the Name field. Paste the Gateway ID previously copied in the Gateway ID field, as shown in Figure 7-16. Click Apply.
Figure 7-16 Secure Gateway Client creation form
5. Click Review changes as shown in Figure 7-17.
Figure 7-17 Secure Gateway Client pending changes
6. Click Save Config as shown in Figure 7-18.
Figure 7-18 IBM DataPower Gateway saving configuration
7. A confirmation message appears as shown in Figure 7-19. Click Close and close the web browser window.
Figure 7-19 IBM DataPower Gateway configuration changes confirmation
Adding a destination in the Secure Gateway
To terminate the integration process, go back to the window displayed at the end of step 5 on page 175 and complete the following steps:
1. Click ADD DESTINATIONS as shown in Figure 7-20.
Figure 7-20 Secure Gateway connection process continued
2. In the Create Destinations area, complete the following actions, as shown in Figure 7-21.
a. Enter CICS in the Destination name field.
b. Enter cics_server_hostname in the Hostname or IP Address field.
c. Enter httpsPort of z/OS Connect in the Port field.
d. Make sure TCP is selected in the list.
e. Click the round plus shaped icon.
Note: For more information about Advanced Options, refer to the Bluemix documentation:
Figure 7-21 Creating a new destination for the secure gateway
3. Click I’M DONE to finish the gateway’s creation as shown in Figure 7-21.
4. This completes the setup of the Secure Gateway to our CICS Transaction Server. To validate that the connection is working, retrieve the cloud host name and port to use for connecting to our system. This can be done by opening the Secure Gateway service for the Bluemix space from the dashboard and drilling down to the gateway that was created to view the destinations.
5. Now select the information icon as shown in Figure 7-22. In the dialog box that is displayed, record the Cloud Host:Port field to use as the host and port name to connect to when validating the connection.
Use this URL to test the connection:
https://<Cloud Host>:<Port>/zosConnect/services.
The result should be the same as shown in Example 7-4 on page 172.
Figure 7-22 Destination for z/OS Connect
7.5 Using IBM API Management for your new APIs
When the Secure Gateway destination has been created and validated to z/OS Connect, the API Management service can be used to manage the lifecycle, access control, and traffic of the API.
7.5.1 Creating the IBM API Management Service
Follow these steps to create the IBM API Management Service:
1. From the catalog window as shown in Figure 7-23, choose API Management.
Figure 7-23 Catalog of the Integration services in Bluemix
2. Select the plan that best fits the intended usage. Currently, only one plan includes a free tier. When finished, click the Use button as shown in Figure 7-24.
Figure 7-24 Select the appropriate plan for the API Management Service
The service should now be created and a panel with the launch button into the API Management console should appear, as shown in Figure 7-25.
3. Click Go to API Manager to open the API Management console.
Figure 7-25 Launchpad for the API Management service that was created
7.5.2 Using API Manager to build and publish a new API
The process for building and publishing an API involves four steps:
1. Create the API. This is where we define the URL and the mapping to our z/OS Connect server as well as documentation for the API.
2. Create an environment. This is the environment where the API will be run. The environment can be customized with a custom URL as well as other properties, such as developer portal URL, user registry, and permissions for who can do what in the environment. For example, who can publish a plan in the environment.
3. Create a plan. This is where the traffic management, such as rate limiting for the API can be set. Multiple plans can be created for the same API to allow for charging of different rates. In this example, only one plan is created.
4. Stage and publish the plan into an environment.
Creating the API
When creating an API, there are multiple options to define the API. The API can be defined in the API Manager via a wizard or by importing a Swagger 2.0 document or Web Service Description Language (WSDL) file. In this example, the API is defined with a Swagger document:
 
Note: Swagger 2.0 is an open standard for defining and documenting APIs. To learn more about the Swagger 2.0, see http://swagger.io.
1. The Swagger document that is used for this example is shown in Example 7-5. The Host field in the example should refer to the Secure Gateway destination, which was described in “Adding a destination in the Secure Gateway” on page 179.
The basePaths and paths fields come from the URI parameter of the JCL program on z/OS, as shown in Example 7-2 on page 169.
Example 7-5 Swagger 2.0 document used for representing the new API
{
"swagger": "2.0",
"info": {
"title": "Virtual Shopping List",
"description": "API to service the Virtual Shopping List App",
"version": "1.0.0"
},
"host": "<Cloud Host>:<Port>",
"schemes": [
"https"
],
"basePath": "/BBAPP",
"produces": [
"application/json"
],
"paths": {
"/InquireOrder": {
"post": {
"summary": "Retrieve shopping list of specified customer",
"description": "This API is used for retrieving customer order history via CICS running on premise on z/OS.",
"responses": {
"200": {
"description": "Orders were successfully created",
"schema": {}
},
"default": {
"description": "",
"schema": {}
}
}
}
}
},
"definitions": {
}
}
2. With the Swagger 2.0 document ready, go back to the API Manager console and go to the API view by selecting the API icon on the left, as shown in Figure 7-26.
Figure 7-26 API Manager home page
3. Click the Add icon as shown in Figure 7-27 to begin creating a new API. A menu should be displayed to select the method for defining the API. Select Import Swagger 2.0 to import a swagger document.
Figure 7-27 API list. Currently, there are no APIs. Use the Add button to create a new API
4. A dialog should be displayed to import a swagger definition as shown in Figure 7-28. Choose Select a File to choose the file containing the Swagger definition.
Figure 7-28 Dialog for importing a file for a Swagger definition
When the file is selected, the service validates that the file is a valid Swagger file and displays the API that is created as shown in Figure 7-29.
5. Click Add to complete the process.
Figure 7-29 Importing a Swagger file
6. When the import is complete, the API is listed under APIs in the API Manager console, as shown in Figure 7-30.
Figure 7-30 The list of APIs now includes the new API imported from a Swagger file
Creating an environment
Environments are used to configure access to the APIs. Environments contain the information of the URL to use for accessing the APIs as well as the developer portal. Environments can be customized to allow only certain users to do things like publish an API.
1. To create an environment, click the Environments icon as shown in Figure 7-31.
Figure 7-31 Select the Environments icon to create a new environment
By default, there is an environment that is created called Sandbox. It is recommended to create a separate environment for publishing new APIs, which is not a sandbox. A sandbox type environment automatically forces the staging and publishing of new plans.
2. Click the Plus button to create a new environment as shown in Figure 7-32.
Figure 7-32 List of environments. A new environment should be created for this scenario
3. When the new environment is created, it can be updated. In this scenario, the default values for everything except the name and the path segment of the environment. When finished, click Save as shown in Figure 7-33.
Figure 7-33 Modify the Name and Path Segment of the environment and click Save
Creating a plan to publish for the API
Plans are used for bundling a set of one or more APIs and used to determine how often an API can be used, for example, an API can be called only 20 times in 1 minute by a given user. This prevents the backend server from becoming overwhelmed with calls to our API.
1. In the API Manager console, select the Plans icon as shown in Figure 7-34.
Figure 7-34 Select the Plans icon to view the list of plans
2. There are two options for defining plans. In this scenario, a brand new plan is created. Click the Add icon to create a new plan as shown in Figure 7-35.
Figure 7-35 Plans list. There are no plans defined. Use the Add icon to create a new plan
3. A dialog is displayed. Enter the name and description of the new plan and click Add as shown in Figure 7-36. The plan can also be restricted by moving the slider across. Restricting a plan means that a developer needs approval from an administrator before using the plan. A plan can be restricted after it has been created as well.
Figure 7-36 Dialog for creating a new plan
4. Now that the plan is created, click the Pencil icon to update the plan to allow only 60 requests per minute, as shown in Figure 7-37. Click Apply to finish it.
Figure 7-37 Update the plan to allow only 60 requests per minute
5. Next, the APIs that were previously imported into the API Manager should be added. This is done by pressing the Add icon, as shown in Figure 7-38.
Figure 7-38 Add the APIs to this plan
6. This opens a list of all the APIs to choose from as shown in Figure 7-39. Select all of the APIs to include in this plan and click Add.
Figure 7-39 Select the APIs to be a part of this plan
7. After clicking Add, click Save to save the plan.
Staging and publishing the plan into an environment
Now that the plan is updated with the right policies and APIs, it can be staged and published:
1. In the details view of the new plan, click the Stage icon as shown in Figure 7-40. This opens the list of available environments. Choose the name of the environment that was created before.
Figure 7-40 The Basic plan is ready to be staged to an environment
2. The plan should be staged and now it needs to be published. Click the name of the environment that the plan has been staged into to publish it, as shown in Figure 7-41.
Figure 7-41 The plan has been staged and is ready to be published
3. To publish the plan, select the Gear icon under Actions for the plan, as shown in Figure 7-42, and click Publish.
.
Figure 7-42 The plan is ready to be published. Select the Gear icon to publish the plan
4. A dialog is displayed to select who is able to see this plan in the environment’s developer portal, as shown in Figure 7-43. Click Publish to complete the process.
Figure 7-43 Determine which developers should have access in the developer portal
5. When the process is complete, we can see the plan has been published in the API Management console as shown in Figure 7-44. Now the plan is ready to be used in a Bluemix application.
Figure 7-44 The plan is now published and ready to be used by Bluemix applications
7.6 Putting it all together
In this scenario, now that the API has been published to Bluemix, a new application can be created to consume this API, which has been published.
The application can be bound to the API, which has been created by the API Management service. A new token that is specific to the application is automatically created, which can be used by the application.
Figure 7-45 shows an image from their application.
Figure 7-45 Shopping list with recommendations based on data from CICS on z/OS
CompanyB was able to build a new application leveraging their previous investments on
z Systems to gain new insights into their customers and provide additional value to their customers.
They used z/OS Connect to transform their existing CICS transactions into an API, which was easily consumed by a mobile application. They were able to extend their datacenter into Bluemix by using the Secure Gateway service with a DataPower appliance to ensure a secure end-to-end connection.
Finally, by using Bluemix, CompanyB was also able to deliver their application quickly and it gave them the ability to respond quickly to fix issues in the application and the ability to easily roll out new features going forward.
 
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
13.59.187.201