This repository contains sample Node.js applications that demonstrates how you can combine data from multiple sources with API orchestration (sample-1.js and sample-2.js). The samples use REST APIs created by z/OS Connect Enterprise Edition to access z/OS applications and data hosted in subsystems such as CICS, IMS and Db2. The samples are designed to work on z/OS and non-z/OS environments.
It also contains another sample of writing a microservices API with Node.js (sample-3.js). This sample contains a business rule for claims processing that was extracted from a COBOL program and created as microservices API using Node.js.
Note: For the REST APIs created by z/OS Connect Enterprise Edition, you also have the option to use zosconnect-node to call the REST APIs.
- The IBM SDK for Node.js on z/OS is installed and configured. There is a trial version available that you can download and use if you want to try Node.js on z/OS. Refer to the Node.js trial site for additional information.
- Clone this repository
git clone git://github.com/zosconnect/sample-nodejs-clients.git - Install Node.js on your preferred platform (MacOS, Windows, Linux or z/OS). See the prerequisites section for information on installing the IBM SDK for Node.js on z/OS.
- Open a command window (Note: You will need to use a telnet session when using Node.js on z/OS) and issue the following to install express and request in the sample1 and sample2 directories:
npm install
Description: This sample uses the IMS phonebook application (IVTNO). The phonebook application can add a contact, delete a contact, display a contact, and update the contact. The data is stored in an IMS database. In this sample, we will use the display a contact function to list information about the contact based on the last name. The REST API for the IMS transaction was created using z/OS Connect Enterprise Edition.
Here is a sample output from the REST API that calls the IVTNO IMS transaction:
{
"OUTPUT_AREA":
{
"OUT_ZIP_CODE": "90210",
"OUT_FIRST_NAME": "JOHN",
"OUT_LAST_NAME": "DOE",
"OUT_EXTENSION": "84881",
"OUT_MESSAGE": "ENTRY WAS DISPLAYED"
}
}
After retrieving the contact information, it will extract additional information related to the zip code of the contact using a postal code REST API provided by zippopotam.us. Here is a sample output from the postal code REST API:
{
"post code": "90210",
"country": "United States",
"country abbreviation": "US",
"places": [
{
"place name": "Beverly Hills",
"longitude": "-118.4065",
"state": "California",
"state abbreviation": "CA",
"latitude": "34.0901"
}
]
}
To run the sample-1.js, issue the following commands from a command window or Telnet session if using Node.js on z/OS:
cd sample1
node sample-1.js
The following output is displayed on the terminal:
Demo application listening on port 50001
To test sample-1.js, type the following from a web browser:
http://<hostname>:50001/phone/contact/DOE
The following is the sample output returned by the orchestration API:
{
"lastname": "DOE",
"firstname": "JOHN",
"extension": "84881",
"zipcode": "90210",
"country": "United States",
"latitude": "34.0901",
"longitude": "-118.4065",
"state": "California",
"city": "Beverly Hills"
}
You can also try the following samples:
http://<hostname>:50001/phone/contact/JAMES
http://<hostname>:50001/phone/contact/MILLER
Description: This sample uses the CICS catalog manager application (EGUI). The catalog manager program can inquire products in the catalog, get details of a specific item in the catalog, order an item in the catalog, and other functions. In this sample, we will use the order an item in the catalog and get details of a specific item in the catalog. The sample will also insert order information into a Db2 table using REST API. The REST APIs for the CICS transaction were created using z/OS Connect Enterprise Edition. For Db2, it uses the Db2 REST service function and extends that with z/OS Connect Enterprise Edition. The products in the catalog (office supplies) are stored in a VSAM file.
This sample is an HTTP POST call and requires a JSON payload as input. The JSON payload must contain the following fields:
{
"itemNumber" : "<item-num>", (valid values: 0010, 0020, ..., 0210)
"userID" : "<user>", (8-char user ID)
"chargeDept" : "<dept-id>", (8-char department ID)
"orderQty" : n-qty, (1-999)
"shiptoStreet" : "<street>",
"shiptoCity" : "<city>",
"shiptoState" : "<state>",
"shiptoZipcode" : "<zipcode>"
}
When an order is received, the CICS transaction to process an order is called first, the following fields are used as input:
- User ID (userID)
- Department charge dode (chargeDept)
- Item reference number (itemNumber)
- Order quantity (orderQty)
After order is processed, the inquire item function is called. The following fields are returned:
- Item reference number
- Item description
- Department
- Items in stock
- Cost per item
- Items on order
Once product is ordered it is logged into a Db2 table in z/OS to keep track of the orders. Update to the table is done using Db2 REST service exposed as REST APIs using z/OS Connect Enterprise Edition. The Db2 table contains columns for the following:
- Item reference number
- User ID
- Description
- Department charge code
- Order Quantity
- In-stock Quantity
- Ship-to Address (Street, city, state, zipcode)
- Order timestamp
The sample first calls the API to process order for an item. After that, it checks for current inventory using the API to inquire details on the item that was ordered. And finally, the order is logged into an order history table in Db2.
To run the sample-2.js, issue the following commands from a command window or Telnet session if using Node.js on z/OS:
cd sample2
node sample-2.js
The following output is displayed on the terminal:
Demo application listening on port 50002
To test sample-2.js, type the following from REST client using POST:
http://<hostname>:50002/product/order
You need to specify a JSON payload like the one below
{
"userID" : "JOHNDOE",
"chargeDept" : "AB1",
"itemNumber" : "0050",
"orderQty" : 2,
"shiptoStreet" : "3039 E Cornwallis Rd",
"shiptoCity" : "Research Triangle Park",
"shiptoState" : "NC",
"shiptoZipcode" : "27709"
}
You will receive an output similar to the one below
{
"itemNumber": "0050",
"chargeDept": "AB1",
"userID": "JOHNDOE",
"orderQty": 2,
"inStockQty": 75,
"itemDescription": "Pencil with eraser 12pk",
"itemCost": "1.78",
"totalCost": "3.56",
"status": "ORDER COMPLETED SUCCESSFULLY"
}
To find out the list of items in the product catalog, you can issue the following GET call from a web browser:
http://cap-sg-prd-4.securegateway.appdomain.cloud:20522/product/catalog/items?startItemID=0010
To find out details on a specific item, you can issue the following GET call from a web browser:
http://cap-sg-prd-4.securegateway.appdomain.cloud:20522/product/catalog/item?itemID=0050
To find out all the orders that were processed successfully, you can issue the following GET call from a web browser:
http://cap-sg-prd-4.securegateway.appdomain.cloud:20522/db2/supplies/all/orders
Description: This sample is the Node.js microservice API that provides the health claim business rule that is used in the z/OS Connect EE GitHub Sample on API requester. The sample provides automatic approval for a health claim based on the claim type and claim amount submitted. It handles the following claim types: MEDICAL, DRUG, DENTAL. The claim amount limits are 100 for MEDICAL, 800 for DENTAL, and 1000 for DRUG. If the amount exceeded these limits then the business rule will not approve the claim automatically.
To run the sample-3.js, issue the following commands from a command window or Telnet session if using Node.js on z/OS:
cd sample3
node sample-3.js
The following output is displayed on the terminal:
Demo application listening on port 50003
To submit an approved claim, type the following from a REST client using GET:
http://<hostname>:50003/claim/rule?claimType=MEDICAL&claimAmount=100.00
Here is a sample output of a claim that is approved:
{
"claim-type": "MEDICAL",
"amount": "100.00",
"status": "Accepted",
"reason": "Normal claim"
}To submit a claim that is not approved, type the following from a REST client using GET:
http://<hostname>:50003/claim/rule?claimType=MEDICAL&claimAmount=250.00
Here is a sample output of a claim that is not approved:
{
"claim-type": "MEDICAL",
"amount": "250.00",
"status": "Rejected",
"reason": "Amount exceeded $100. Claim require further review."
}