Name: increase-retail-revenues-leveraging-hybrid-cloud-on-mainframes
Owner: International Business Machines
Description: To showcase the business challenges that a typical retail company might be experiencing, we share a case study about a fictitious retail company, and how they leverage IBM Z
Created: 2017-06-29 23:02:40.0
Updated: 2018-03-03 03:08:03.0
Pushed: 2018-05-23 20:16:37.0
Size: 21323
Language: JavaScript
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
To showcase the business challenges that a typical retail company might be experiencing, we share a case study about a fictitious retail company, which we refer to as Breadbox Groceries.
Today, they run three data centers across the country with IT reaching into the stores and distribution centers as well. In the data centers, they host their core Business Support Systems on IBM Z. Supporting applications are hosted on IBM CICSŪ and IBM z/OSŪ Db2 systems.
One of the initiative for Breadbox was to implement the virtual shopping list. With this app, customers will be reminded that they need milk at the store the next time they go based on the purchasing history.
This diagram shows the Virtual Shopping List mobile application and two supporting microservices or web services: The Virtual Shopping List List Web Service (vsl-list-ws) and the Virtual Shopping List Recommendation Web Service (vsl-rec-ws).
The Recommendation Service is a simple recommendation engine, that finds patterns in customer?s purchases, mostly around durations between purchases, and makes recommendations for new purchases.
The List Service supports the mobile phone app (breadboxportal), by managing and persisting the list seen on the mobile phone app, merging in customer added items with customer selected recommendations.
App users can add or ignore recommendations, can enter free form items, and can delete items at any time. List Service has the smarts, and uses a Cloudant database behind it, to maintain the current list.
Use the API Connect Developer Portal to test the GET /customerHistory operation of the Breadbox API. This operation retrieves customer purchase history and will be used in Part two of this journey.
Sign up for an IBM ID if you don't have one already. This is required for the next step.
Go to the Developer API Portal.
Create an account if you have not done do already.
Click Create an account.
Provide all required information. Be sure to use your IBM ID (Email) for this account.
Click Submit.
An account activation email will be sent to your registered Email. Click on the link in this email to activate your account before.
Log in to your account.
Create a new application (work space for this project).
Click Apps from the menu.
Click Create new app.
Fill in all required fields.
Click Submit.
Make a note of the client ID and client secret. You will need them to access the API later in Part two.
Display a list of available API products.
Click API Products from the top menu.
Select the Breadbox product.
Click Breadbox.
From the left navigation panel, you will see one published API named breadbox team dinosaur.
In order to work with this API, you must subscribe to it first.
Click Subscribe for the Default Plan.
Select the app that you have just created.
Click Subscribe
Let's take a closer look at this API.
Click breadbox team dinosaur
This page has 3 sections:
The left panel is the navigation panel that lists all the available operations and their definitions.
The middle panel displays detail information for the item you have selected.
The right panel contains sample code in various programming languages.
This API has one operation: GET /customerHistory”.
Click GET /customerHistory”.
This operation retrieves purchase history for a customer. The required parameters and their formats are described.
Generate code to test this operation. Go to the right panel.
Code example in the selected programming language and an example output of a successful response are displayed. You can copy the code and use it in your own application.
Test the GET /customerHistory” operation with the generated code.
Scroll down to Try this operation section.
Fill in the following:
| Field | Value | Comment |
| ————— | ————————– | ———————————————– |
| Client ID | ID of the application | Should be defaulted to the one you just created |
| Client secret | Secret for the application | Secret generated when app was created |
| customer_number| 1000100 | Valid #s are 1000100-1000140 |
| request_date | 2013-09-01 | Purchase history since this date |
| shorten | 2 | Number of records to retrieve |
Click Call operation.
You should see the output returned at the bottom of the page.
:thumbsup: Congratulations! You have successfully tested the Breadbox API and ready to move on to part 2 of this journey.
This section takes you through the steps to install the Breadbox Groceries sample mobile web application and associated web services in IBM Cloud.
Complete Part 1 of this journey, [Test the Retail REST API on the Developer Portal](#test-the-retail-rest-api-on-the- developer-portal).
If you don't have an IBM Cloud account, sign up for one here.
Follow the instructions here to install the IBM Cloud CLI tools.
Login to your IBM Cloud account.
If you have not created an org and space yet, do the following:
Create an organization.
Important: Plese choose the US South region. The development tools used in this section were validated with this region only.
Create a space.
On the summary page, click I'm Ready.
Note your org and space. You will need this information later.
From the main Apps dashboard, click Create App.
In the left navigation pane, click Cloud Foundry Apps.
Select SDK for Node.js.
For App name and Host name, fill in vslrecws-something-unique
IMPORTANT: The Host name must be unique across all of the bluemix.net domain. IBM Cloud should enforce this uniqueness, by checking for any prior users, before creating the placeholder Cloud Foundry applications. We recommended that you use the following format, vslrecws-something-unique where something-unique is a sequence number, or project nickname, or developer nickname, etc., such as vslrecws-dev02 or vslrecws-test03.
When ready, click Create.
The app is now Running!
Click Visit App URL to test it.
You have just instantiated a simple template Hello world web application.
Download the node.js app code.
Click download the sample code.
Save the code to your computer.
Unzip the file to a directory.
Go to a terminal and navigate to the sample code directory.
Authenticate to IBM Cloud. Enter:
mix login ?a https://api.ng.bluemix.net
Enter your IBM Cloud account and credentials
Set the target org and space. You can find this information on your cloud portal dashboard. For example:
arget -o xyz -s dev
Push the unchanged code for the sample node.js app we created earlier to IBM Cloud.
pp push vslrecws-something-unique
When processing completes, your app will restart. You should receive messages similar to the following:
Return to the IBM Cloud portal and navigate the the Cloud Foundry Apps. You should see the vslrecws app you just created.
Click on the route to load the URL into your browser to make sure that the node.js sample app is still healthy.
When these steps are complete, you should see these three apps in your Cloud Foundry Apps list.
From the IBM Cloud main menu:
Click Catalog.
Click Data & Analytics
Click Cloudant NoSQL DB
Change the Service name to: cloudantconfig.
Important, Service name must be ?cloudantconfig?.
Scroll down to the bottom of the page, accept the default Lite PLAN, Click Create.
The cloudantconfig instance of the Cloudant NoSQL-DB service is now in place.
Select cloudantconfig from the Services list.
Click Launch from the Manage tab.
The Cloudant dashboard opens in a separate browser tab.
Create the rec database. This database holds purchase recommendations, based on customer purchase history.
From the Database tab, click Create Database.
Enter a database name of rec (short for recommendation)
Click Create.
Create the users database. This database stores basic user information and breadpoints.
From the Database tab, click Create Database.
Enter a database name of users.
Click Create.
Create the vsl database. This database holds shopping list items the user manually adds to their list.
From the Database tab, click Create Database.
Enter a database name of vsl.
Click Create.
You should now have 3 entries in Your Databases tab.
Populate a user in the users database.
Click the users database.
Click All Documents (+), select New Doc.
Copy/paste the sample text below over the existing text:
d": "074",
stomerid": 1000114,
mid": "jessejes@example.com",
eadpoints": 10,
alname": "Jesse JES"
When finished, click Create Document.
The new user is now in place.
Create Cloudant Credentials to use in the Breadbox VSL app.
Back to the IBM Cloud portal, Click Service credentials in the left navigation pane, and click New credential.
Provide a name for the credentials, click Add.
The credential is now in place.
You can use the View credentials Action to view the assigned credential. These will be used later.
Connect Cloudant Credentials to the Breadbox portal app.
Click Connections in the left navigation pane, and click Create connection.
Select the breadboxportal app, and click Connect.
Click on the Restage button.
The Cloudant NoSQL DB service is now connected to the breadboxportal app.
Connect Cloudant Credentials to the vsllistws app.
Repeat the procedures from the previous step.
Connect Cloudant Credentials to the vslrecws app.
Repeat the procedures from the previous step.
To see the results of this new Connection (for example, Breadbox portal app):
Click Breadboxportal conection.
Click Runtime tab in the left navigation pane, and click Environmental variables in the center selector.
We see the cloudantNoSQLDB environment variable that will be passed to the breadboxportal Cloud Foundary application, so that credentials don?t need to be in the code. It?s a little odd that the VCAP_SERVICE environment variable above isn?t cloudantconfig, to match the service name, but it works somehow. ;-)
The environmental variable JWT_SHARED_SECRET needs to be identical across breadboxportal, vsllistws, and vslrecws. This shared secret is used to encrypt and decrypt the JSON web token (JWT) passed between breadboxportal, vslistws and vslrecws.
Create the shared secret user defined environmental variable for the breadboxportal app.
Navigate to Bluemix / Cloud Foundry Apps / Breadbox portal App.
Click Runtime in the left navigation pane.
Click Environmental variables in the center selector.
Scroll down to the User defined section, Click Add.
Create a new user-defined environmental variable. Enter:
click Save.
The app will be restarted automatically.
Create the shared secret user defined environmental variable for the vsllistws app.
Repeat procedures from the previous step.
Create the shared secret user defined environmental variable for the vslrecws app.
Repeat procedures from the previous step.
In this section, you are going to upload the actual working code, to overlay the placeholders created earlier. Before proceeding, you must modify a few files to match your specific environment.
In a terminal on your computer, move to the home directory.
HOME
If not already installed, install Git for your computer.
Once Git is installed, run the following command to clone the needed materials for this exercise.
clone https://github.com/IBM/increase-retail-revenues-leveraging-hybrid-cloud-on-mainframes.git
To find the files you need:
ncrease-retail-revenues-leveraging-hybrid-cloud-on-mainframes/vsl
You should see 3 directories:
breadboxportal
vsllistws
vslrecws
Modify files in the breadboxportal directory.
Move to the breadboxportal directory.
breadboxportal
Edit the manifest.yml file. Replace the host: parameter with the URL (route) for your breadbox portal app.
Edit the server.js file. Replace the listservice parameter with URL (route) for your vsl listing web service app.
Modify files in the vsllistws directory.
Move to the vsllistws directory.
vsllistws
Edit the manifest.yml file. Replace the host: parameter with the URL (route) for your breadbox portal app.
Edit the server.js file. Replace the var recsServer parameter with the URL (route) for your vsl recommendations web service app.
Modify files in the vslrecws directory.
Move to the vslrecws directory.
vslrecws
Edit the manifest.yml file. Replace the host: parameter with the URL (route) for your vsl recommendations web service app.
Edit the server.js file.
nd the section that calls **analyze-history**.
place the value for **'x-ibm-client-id'** with the one you created in Part 1.
lace the value for **'x-ibm-client-secret'** with the one you per created in Part 1.
Authenticate to IBM Cloud, enter:
mix login ?a https://api.ng.bluemix.net
Upload the actual working code and overlaid the placholder for your breadbox portal app.
Navigate to the breadboxportal directory.
Push the code to IBM Cloud. Enter:
app push breadboxportal-something-unique
The following shows an example of a successful run.
Upload the actual working code and overlaid the placholder for your vsl listing web service app.
Navigate to the vsllistws directory.
Push the code to IBM Cloud. Enter:
app push vsllistws-something-unique
Upload the actual working code and overlaid the placholder for your vsl recommendation web service app.
Navigate to the vslrecws directory.
Push the code to IBM Cloud. Enter:
app push vslrecws-something-unique
IMPORTANT: When issuing the bx cf push commands, its very important to issue the commands for a given application from within the directory for that application. If this is not done, application hosts get cross wired, and your applications will start to be unreachable intermittently, as IBM Cloud seems to associate multiple routes with the same application, when a cross wired push is done. If cross wiring occurs, the IBM Cloud portal can be used to edit the application routes, and delete unintended routes. Use the Routes button in the upper left corner of any detailed views (Overview, Runtime, Logs, etc.) for the application.
As a quick check for proof that the actual working Breadbox Recommendation Service is running.
Click on the URL for the vslrecws app.
Now we are ready to see the final result, the full hybrid cloud application from IBM Cloud all the way back to z/OS Connect.
Navigate to the breadboxportal app in IBM Cloud.
Click the Route host you created before for the breadboxportal app.
Click the Login button at the bottom of the screen above.
This sample portal, mobile application lacks user login. Developers may choose to add user login themselves. The sample redirects directly to the mobile application screen.
Select the Virtual Shopping List app on the mobile phone.
The top two rows are recommendations coming from the Recommendation web service based on the customer purchase history coming from z/OS Connect!
You can use the plus (+) sign to add recommendations to your shopping list. The shopping list is persisted in the cloud, in the Cloudant database.
To get further validation that our integration of the engaging mobile app in the cloud, with the customer purchase history on IBM Z, you can double check the Recommendation web service log in IBM Cloud to see the recommendations coming from the analyze-history call.
We can also see the raw response from the API on the Developer Portal.
The cloudant “users” ?rec? and ?vsl? databases are self-priming, based on use of the portal, mobile app. Using the Cloudant management UI, you can see that the databases are working properly.
Navigate back to the Cloud management UI, and navigate to the Databases view.
Select the users table. Click the pencil in the upper right to view/edit the document.
Jesse now has 12 breadpoints!
Select the rec table. Click the pencil in the upper right to view/edit the document. Similarly, the recommendations for Jesse JES (_id=1000114) are in this database.
Select the vsl table. Click the pencil in the upper right to view/edit the document. The items that Jesse JES added manually to his virtual shopping list is now in this database.
:thumbsup: Congratulations! You have successfully completed deployment of the Virtual Shopping List web application.
In this section, you will explore and gain insights from Breadbox Groceries customer purchase history. This data exploration can have immense business value, looking for trends, such as products selling well, not so well, for specific customers, trends in customer retention, customer purchase volume per visit, customer visits to more than one store ? the possibilities are endless. Armed with insights, Breadbox Groceries might use the Virtual Shopping List mobile application to insert promotions to target customers, that might improve number of visits, quantity of purchases per visit, etc. After the promotion period, the results can be measured by further analytics on customer purchase history. In this section, we?ll use the API we created, to gather customer purchase history for various customers, feed that information into IBM Watson Analytics, running in the IBM Cloud, to see what types of insights are possible.
In the first Experience, we saw that the customerHistory API returns a large json document. The API returns data for a single customer. One tricky part is that IBM Watson Analytics doesn?t process json, so you will have to convert the API json response to CSV format.
There is a prepared CSV file result.csv which contains purchase history for customer 1000100. You can find it in the files you downladed earlier from Github.
ncrease-retail-revenues-leveraging-hybrid-cloud-on-mainframes/result.csv
*If you prefer to use this file, please skip this section and proceed to [5.2. Log in to IBM Watson Analytics](5.2.-log-in-to- IBM-Watson-Analytics)
Retrieve customer history for a customer.
There are a number of tools, techniques to do an API request. Using curl is shown here.
--request GET \
rl 'https://api.us.apiconnect.ibmcloud.com/spbodieusibmcom-prod/developer-contest/breadbox /customerHistory?customer_number=1000100&request_date=2013-09-01' \
eader 'accept: application/json' \
eader 'x-ibm-client-id: df2fecbf-01f5-41ed-90c0-2b8883db2a3b' \
eader 'x-ibm-client-secret: -----------------------------------------'
Convert results from json to csv format.
There are several ways to convert json to csv. In this example, a json2csv node module was used, found at: https://github.com/zemirco/json2csv#command-line-interface
Here is a sample session to convert json to csv at the command line, using the node module json2csv.
IMPORTANT: One slightly hidden step is to trim the json response to only the details portion of the response (ca_order_detail), the main part of the response, the long array of strings, between the square brackets: [ ? ]. The vi editor is used to remove the front and back matter, to leave the square brackets and everything in between.
Log in to IBM Watson Analytics.
Use your IBMid to log in. You will have to sign up for a free trial if you have not done so already.
Click New data in the upper left.
Click Local file and click Browse.
Select your .csv file using your OS file chooser.
Click Import in the bottom left.
Click the .csv file you just uploaded.
Various Starting points are shown. You can begin your data exploration, trying out various things you see, and see what you can come up with.
Here are a few examples:
This customer really likes Honeyed Preserve.
This customer buys mostly in Store 4 and 5, and really likes Tea Lemon Ginger.
This customer is spending more lately ;-)
?
The purpose for this sample app is a starting point for additional ?hacks? that can be done. Here are some ideas on possible hacks: