Skill Level: Any Skill Level

Technical competence and z Systems access


Texas Instrument's SensorTag

Bluemix account

IBM z/OS Connect Enterprise Edition

Back-end (e.g. CICS) service


  1. Expose an existing z Systems application as a RESTful API

    Valuable business applications on backend z Systems’ subsystems have been developed and built up over many years. The willingness to rewrite these is a risk and effort that many do not want to undertake. Therefore, another method is required and this is where z/OS Connect Enterprise Edition can help. It enables you to take an existing application and expose it (unchanged) for RESTful API interactions.

    For the benefits of this tutorial a basic CICS-COBOL application was created which increments or retrieves counters for a specific hour or 5-minute period. Details of setting everything up can be found in the Scenario available in the z/OS Connect Enterprise Edition Knowledge Center (https://www.ibm.com/support/knowledgecenter/SS4SVW_2.0.0/com.ibm.zosconnect.base.doc/topics/sc01_intro.html) and works with the sample CICS catalog program.

    Starting with the application interface (the code that describes a program’s input and output data), the z/OS Connect Enterprise Edition tooling enables an API designer, working with the z Systems application owner, the creation of RESTful APIs which map to the back-end program. Once the mappings are deployed to the z/OS Connect Enterprise Edition server then REST requests can be made directly to invoke the program. In this case we have a PUT request to increment a counter and a GET request to retrieve counter data.

    Requests made to the z/OS Connect Enterprise Edition server, using the deployed APIs, will result in the invocation of the back-end application. Additionally, an OpenAPI (Swagger 2.0) document can be retrieved that describes the available APIs that have been deployed. Web browser HTTP requests can be used to invoke GET requests. Alternatively, you could install a REST client to test out other RESTful API verbs like PUT, POST and DELETE. For example:

    GET http://{on-premise-z-Systems:port}/api/counter/25042016/11 will return:

    {“COUNTSOperationResponse”:{“response”:{“out_message”:”Counter(s) read okay”,”counter”:”000000000000000000000000026402330002001900100009″}}}

  2. Enable your SensorTag device to Watson IoT Quick Start

    An IoT device requires an IoT gateway to communicate to a Cloud service. A Samsung Galaxy S5 was used as the IoT gateway for this recipe. The IoT device used in this recipe is a Texas Instrument’s SensorTag. The SensorTag’s broadcasted data can be read by the “BLE SensorTag” application available from Google’s Play Store. Bluetooth 4.0 is required on the IoT gateway so that the SensorTag can communicate with it. With the SensorTag and the gateway paired you can begin to view the data being broadcast, as seen in this screenshot:

    At the top of this same page there is a Cloud View section, giving the device ID and the ability to ‘Push to Cloud’. In the Advanced page ensure that the Cloud service is set to IBM IoT Quick Start. Move the ‘Push to Cloud’ slider from OFF to ON and the IoT gateway will immediately start publishing data to the IBM Internet of Things cloud. Obtain your SensorTag’s MAC address (from the same Cloud View section) and copy it into the Quickstart field on http://quickstart.internetofthings.ibmcloud.com/ (no log-in is required). The data will start to be displayed on the IBM Watson IoT Platform page:

  3. Connect the Cloud to on-premise (Hybrid Cloud)

    Within Bluemix there is an Integration tile that provides secure tunneled access from the Cloud to a proxy hosted behind a corporate firewall. The tile to use is the Secure Gateway.

    A Secure Gateway Client also needs to be installed and running on the proxy machine within the Enterprise. Links to the appropriate install files are presented within Bluemix when you click on Connect Client. There are three options; an IBM Installer (e.g. for Windows 7), Docker, or IBM DataPower.

    Once connected, a new endpoint URL is generated within the Secure Gateway on Bluemix which can be used in exactly the same way as though you were on-premise. The GET or PUT request will get passed through the secure tunnel to the on-premise proxy machine and then on to z/OS Connect Enterprise Edition and into the back-end application.

  4. Enable the published IoT data to trigger a RESTful API

    The final step is to link the data that’s being pushed to the IBM IoT Quick Start Cloud service to invoke a RESTful request. What we will do is use the light sensor data to trigger the PUT REST request to increment the counter on the back-end z Systems application. The Bluemix tile to enable this is the Internet of Things Platform Starter Boilerplate.

    Once started you can link to the route URL provided and open up the Node-RED Flow Editor to configure the sample flow. For this recipe the flow was updated to pull data from the IoT device (by specifying the Quickstart as the Authentication and the device’s MAC address as the Device Id in the ibmiot Input node). The light sensor data (payload:msg.payload.d.light) was passed through to the switch node that determined whether the reading was high enough or not. If the switch determined that it was ‘dark’ then a http request node invoked the PUT request to the exposed Secure Gateway URL:

    We now have connected our IoT device, through an IoT gateway, published its data to the Cloud, performed a check on that data, invoked an API that was made available using the Secure Gateway, which invoked z/OS Connect Enterprise Edition, and invoked the exposed back-end application.

Join The Discussion