In an earlier post, a CICS TS sample for an IBM API Management custom registry was announced. This article describes how to set up and run a service discovery application, which can be used to advertise web services (composed of WSDL and WSBind file pairs) to IBM API Management.

1 Introduction

To run the application in CICS, we have used the following:

  • CICS Transaction Server 5.2
  • WebSphere Application Server Liberty profile (installed with a CICS Bundle)

For more information about web services and their relation to CICS, see for example Implementing CICS Web Services. The setup process consists of the following steps:

  1. Download CICS Explorer v5.2 and a copy of the service discovery application source files
  2. Install dependencies for the application: WebSphere Liberty Profile, and JARs obtained from your CICS installation
  3. Optional: run Liberty locally to confirm the application works
  4. Build CICS bundles to hold a CICS Liberty server, and the service discovery application
  5. Upload CICS bundles and enable and configure the Liberty server
  6. Confirm the application is advertising the available CICS web services correctly
  7. Configure API Management to discover the CICS web services.

We will now step through this process, starting by installing CICS Explorer.

2 Local Setup and Creation of WAR File

 

2.1 Installation of WebSphere Profile Developer Tools

Download CICS Explorer v5.2 and run it. To this base install, we will need to add WebSphere Liberty Profile developer tools. To do this, choose Help, then Install New Software…. Click Add… to add the following repository:

http://download.eclipse.org/releases/juno

Choose this repository and install Marketplace Client from the General Purpose Tools section. After restarting, choose Help, then Eclipse Marketplace …. Search for Liberty Profile Developer Tools for Juno and click Install. After another restart, click Help, then Install New Software… again, choose the IBM Explorer for z/OS Update Site repository, and install IBM CICS SDK for Servlet and JSP support v5.2.0 under IBM CICS Explorer. After a final restart, switch to the Java EE perspective.

2.2 Service Discovery Application Setup

We are now ready to download the service discovery application source code. After downloading the zip file, choose New, then Web Project. In the wizard that appears, name the web project CICSServiceDiscovery, with project template REST Services. Configure Type as Disable Library Configuration, and untick Update Deployment Descriptor.

In Enterprise Explorer view, under CICSServiceDiscovery/CICSServiceDiscovery/Java Resources, a src folder can be found. Right-click src and choose New, then Package. Give the package the name com.ibm.cicsts.CICSServiceDiscovery. Right-click the newly-created package, and choose Import…. Choose General, then Archive File. Choose the zip file containing the application source code, and click Finish.

APIM-tree-properties.png

Figure 1: Location and contents of CICSServiceDiscovery.properties.

Under the WEB-INF folder, create a file CICSServiceDiscovery.properties (see Fig. 1), with the following content:

baseServiceURL = http://winmvs2d.hursley.ibm.com:20205
rootPath = /u/chpoole/WS-files/
codePage = CP037

codePage will be used when serving the WSDL files, rootPath is where on zFS the WSDL/WSBind pairs will be located, and baseServiceURL is used when constructing SOAP endpoints. The files and directories containing WSDL and WSBind files in this article (on zFS under rootPath) are shown in Fig. 2.

APIM-tree-ws-files.png

Figure 2: WSDL and WSBind file pairs on zFS.

WSBindInfo.java will show errors, as JARs from a CICS region install are not available. To fix this, we must import these from a CICS installation. The location is given by the USSHOME SIT parameter, by default /usr/lpp/cicsts/cicsts52. Extract from the lib/wsdl/ sub-directory all the JAR files, and copy them to the WEB-INF/lib directory in the Enterprise Explorer view. The source tree will now look like that in Fig. 3. The overall view will be like that in Fig. 4.

APIM-jars-tree.png

Figure 3: WebContent tree in Enterprise Explorer view showing imported JARs.

APIM-source-tree.png

Figure 4: Application source tree in Enterprise Explorer view.

2.3 Optional: Local WebSphere Liberty Profile Runtime Setup for Confirmation

If you wish, you can store your WSDL and WSBind files locally, and test the service discovery application works by using a REST client (such as Postman) to request the list of services from a local WebSphere Liberty server. Update rootPath in CICSServiceDiscovery.properties to point to your local directory where the WSDL and WSBind files are stored 1.

To install Liberty, download the WebSphere Liberty Profile runtime, and extract it to a local directory. Open the Servers view in CICS Explorer, right-click, and choose New, then Server. Choose WebSphere Application Server V8.5 Liberty Profile, and click Next. The wizard will now ask for an installation folder for a Liberty Profile runtime environment: click Browse… and choose the wlp directory under where you have just extracted the runtime. Click Next twice, add the CICSServiceDiscovery resource, before clicking Finish.

Right-click the Liberty server, and click Start. The Console view will show a line like

CWWKT0016I: Web application available (default_host): http://localhost:9080/CICSServiceDiscovery/

With a REST client, issue the request 2

GET http://localhost:9080/CICSServiceDiscovery/discovery/services

A list of services should be returned, as described later in this article.

3 CICS Liberty Server Configuration

To run the application within CICS Liberty, we are going to create two CICS bundles: one to contain the JVM and configuration, and one for the application WAR file. Both will be deployed as Platform bundles.

In the CICS Cloud perspective of CICS Explorer, create a new bundle with the Liberty server. See this article for further instructions on running a Liberty server within CICS. Ensure you have supplied the correct details for your server configuration (JAVA_HOME, etc.) in DFHWLP.jvmprofile. For example, we use the following parameters:

JAVA_HOME=/usr/lpp/java/J7.1_64/
WORK_DIR=/u/chpoole/liberty
WLP_INSTALL_DIR=&USSHOME;/wlp
-Dcom.ibm.cics.jvmserver.wlp.autoconfigure=true
-Dcom.ibm.cics.jvmserver.wlp.server.http.port=20205
-Dfile.encoding=ISO-8859-1

In particular, the port number that the service discovery application sends responses and receives requests is that defined here.

Next, create another CICS bundle and, under the Defined Resources section, choose New… then Dynamic Web Project Reference. A dialog will prompt you for the project to be included in the bundle: choose the CICSServiceDiscovery project previously created. Specify the name of the JVM server we have just created too. This will create a warbundle resource inside the bundle. Finally, create a platform project, and add both CICS bundles to it. Together, the projects will look like those in Fig. 5.

APIM-project-explorer.png

Figure 5: Project Explorer view.

Export the platform to z/OS Unix file system, and install and enable the platform. Both bundles and the platform should now be enabled in the Cloud Explorer view, as in Fig. 6.

APIM-cloud-explorer.png

Figure 6: Cloud Explorer view.

Now, we need to add a few more features to Liberty's server.xml (found under WORK_DIR as specified earlier, under [server name]/wlp/usr/servers/defaultServer/). To do this, we'll use CICS Explorer's z/OS perspective, and its z/OS UNIX Files view 3, as in Fig. 7. Add to the featureManager block the following features:

<feature>jaxb-2.2</feature>
<feature>jaxrs-1.1</feature>

APIM-unix-files-liberty.png

Figure 7: z/OS UNIX Files view in CICS Explorer, showing the path to Liberty's server.xml.

To confirm the features have been updated, one can view Liberty's message log under logs/messages.log. Output similar to the following should be shown at the bottom of the file:

A CWWKF0012I: The server installed the following features: [json-1.0, jaxrs-1.1, jaxb-2.2].
A CWWKF0008I: Feature update completed in 1.594 seconds.
I SRVE0169I: Loading Web Module: CICSServiceDiscovery.
I SRVE0250I: Web Module CICSServiceDiscovery has been bound to default_host.
A CWWKT0016I: Web application available (default_host): http://sysplex2-dvipa32.hursley.ibm.com:20205/CICSServiceDiscovery/
A CWWKZ0003I: The application CICSServiceDiscovery updated in 1.734 seconds.

The application is now set up and running, and capable of returning information about CICS web services.

4 Confirming Functionality with a REST Client

We will use the REST client Postman to confirm that the correct responses to requests are being returned by the application. The service discovery application will return information on the following paths:

/registry
/services
/services/[service_id]
/wsdls/[service_id]

First, issue the following request 4:

GET http://[hostname]:[port]/CICSServiceDiscovery/discovery/registry

The returned JSON block should match

{
    "name": "CICSServiceDiscovery",
    "apiVersion": 1
}

Now, request a list of services discovered, by issuing

GET http://[hostname]:[port]/CICSServiceDiscovery/discovery/services

This will return a JSON array of services,

{
    "services": [
        {
            "id": "RemoveCustomer",
            "name": "RemoveCustomer",
            "url": "http://winmvs2d.hursley.ibm.com:20205/CICSServiceDiscovery/discovery/services/RemoveCustomer",
            "protocol": "SOAP"
        },
        {
            "id": "AddCustomer",
            "name": "AddCustomer",
            "url": "http://winmvs2d.hursley.ibm.com:20205/CICSServiceDiscovery/discovery/services/AddCustomer",
            "protocol": "SOAP"
        },
        {
            "id": "StockQuote",
            "name": "StockQuote",
            "url": "http://winmvs2d.hursley.ibm.com:20205/CICSServiceDiscovery/discovery/services/StockQuote",
            "protocol": "SOAP"
        }
    ]
}

Thus, even nested services are returned, provided they consist of a wsdl and wsbind file pair. Each service will have defined the following attributes: id, name, url, and protocol. The protocol implemented by the CICS Service Discovery application is SOAP. We can now use the returned URL for one of the services, for example StockQuote, to get more information about that particular service:

GET http://winmvs2d.hursley.ibm.com:20205/CICSServiceDiscovery/discovery/services/StockQuote

This returns

{
    "id": "StockQuote",
    "name": "StockQuote",
    "url": "http://winmvs2d.hursley.ibm.com:20205/CICSServiceDiscovery/discovery/services/StockQuote",
    "protocol": "SOAP",
    "soapInterface": {
        "wsdlURL": "http://winmvs2d.hursley.ibm.com:20205/CICSServiceDiscovery/discovery/wsdls/StockQuote",
        "operations": [
            {
                "operation": "STCKQUOTOperation",
                "description": "STCKQUOTOperation"
            }
        ]
    },
    "soapEndpoints": [
        {
            "name": "StockQuoteEndpoint",
            "address": "http://winmvs2d.hursley.ibm.com:20205/StockQuote"
        }
    ]
}

Defined is a soapInterface attribute, which holds the URL for the WSDL file, as well as an array of its supported operations. Thus, one may now issue the request

GET http://winmvs2d.hursley.ibm.com:20205/CICSServiceDiscovery/discovery/wsdls/StockQuote

and find that the XML-based WSDL file is returned. Note also that the context root of the soap endpoint is different to that of the service discovery application.

We have now proven that the service discovery application is functioning correctly, so can proceed to use it to enable IBM API Management to discover CICS web services.

5 Discovery with API Management

Log in to your API Management server (API Manager interface), and choose the APIs menu item on the left, as in Fig. 8. Choose to add a new API, then Import WSDL, as in Fig. 9. Choose the Find in registry toggle button, then click CustomReg, followed by the pencil icon (edit) next to CustomReg (see Fig. 10).

APIM-api-manager-apis.png

Figure 8: API Management's APIs view.

APIM-import-wsdl.png

Figure 9: API Management menu option for importing WSDL.

APIM-apim-customreg.png

Figure 10: API Management's interface for choosing a custom registry.

Give the service registry a name, and for the service registry type, choose Custom Registry. Specify the hostname and port as used previously, and HTTP as the protocol. Leave username and password blank (no BasicAuth is performed), and enter the context root used previously (in this example, CICSServiceDiscovery/discovery/). A completed form is shown in Fig. 11.

APIM-define-registry.png

Figure 11: Define a custom registry in API Management.

Click Test Connection, and wait until The registry has been saved successfully is displayed. Click Save, and then click CustomReg again, and choose the service registry just defined. Enter the name of a service (for example, StockQuote), and click the magnifying glass icon. This will return the service, which you can now choose and click Add (see Fig. 12).

APIM-service-choice.png

Figure 12: Choose the StockQuote service.

The service STCKQUOTService (the name pulled from the WSDL file by API Management) will be shown in the list of APIs, as in Fig. 13.

APIM-stock-service.png

Figure 13: The StockQuote service in the list of APIs.

If you click on the API name, you can get further details of the API, download its WSDL file, and show its resources (operations) (Fig. 14).

APIM-api-page.png

Figure 14: Details of the StockQuote API.

Footnotes:

1

Be sure to change this back to the correct location on zFS Unix file system, once local testing is complete.

2

One can use the Enterprise Explorer view to expand CICSServiceDiscovery/Services/REST, to see a list of exposed services to be called. Right-click on one and choose Show URI to obtain the calculated URI of that resource.

3

Alternatively, ISPF's UNIX System Services menu option may be used, followed by Edit a USS file (usually option =O.E).

4

With HTTP header Content-Type: application/json.

3 comments on"Discovering CICS Web Services with IBM API Management"

  1. After downloading the zip file, choose New, then Web Project. In the wizard that appears, name the web project CICSServiceDiscovery, with project template REST Services. Configure Type as Disable Library Configuration, and untick Update Deployment Descriptor.

    I don’t see that option available to me when I choose new, I have option ‘static web project’ or ‘dynamic web project’ and I don’t see any options available under those to select a prject tesmplate or config type.

    Is there something I am doing wrong here ? I am in JAVA EE view

    • Hey Wes. Looks like the Eclipse panels have changed since I wrote the article.

      Trying it now, I had success by choosing Dynamic Web Project. I chose WebSphere Application Server Liberty Profile as my target runtime, and then clicked the Modify button under configuration. There, I ticked “JAX-RS (REST Web Services)”. From then on, the rest of the article should still stand.
      When you have imported the zip file, ensure that the java source files are directly under the package, not within a folder under the package.

  2. Thanks Chris,
    I have a few more questions, in relation to setting up the WAS Liberty Profile Runtime Environment.
    Would it be possible to contact me direct on [redacted] and we could maybe arrange a call to discuss further ?

    Thanks
    Wes

Join The Discussion

Your email address will not be published. Required fields are marked *