IBM-Cloud / logistics-wizard-recommendation

Makes shipment recommendations based on weather conditions
Other
7 stars 13 forks source link
ibm-bluemix ibm-cloud-solutions openwhisk serverless weather

Logistics Wizard / Architecture / logistics-wizard-recommendation

Logistics Wizard - Weather Recommendation

This service monitors the weather conditions around retail stores and makes recommendations on additional shipments of goods.

It is built with IBM Cloud Functions highlighting how Functions can be used to implement a backend API. The Functions actions are:

Simulating weather events

For demo purpose, the Recommend action can be called interactively to inject a weather event into the system.

Architecture

custom_mark10 digraph G { node [fontname = "helvetica"]; rankdir=TB; weather -> recommend; recommend -> database; database -> notify; ui -> retrieve; retrieve -> database; ui -> acknowledge; acknowledge -> database; recommend -> erp; ui -> erp; {rank=same; recommend -> notify -> retrieve -> retrieve [style=invis] }; {rank=source; weather -> erp -> ui [style=invis]}; weather [shape=rect label="Weather Company Data service" style=filled color="%234E96DB" fontcolor=white]; recommend [label="Recommend" color="%232e8c70" style=filled fontcolor=white]; notify [label="Notify" color="%232e8c70" style=filled fontcolor=white]; retrieve [label="Retrieve" color="%232e8c70" style=filled fontcolor=white]; acknowledge [label="Acknowledge" color="%232e8c70" style=filled fontcolor=white]; erp [shape=rect label="ERP service" color="%238ec843" style=filled]; ui [label="Dashboard" color="%23e8c228" style=filled]; database [shape=circle width=1 fixedsize=true style=filled color="%234E96DB" fontcolor=white label="Database"]; custom_mark10

Running the app on IBM Cloud

  1. If you do not already have a IBM Cloud account, sign up here.

  2. The Recommendation service depends on the Controller and ERP microservices. Deploy them first.

  3. Create an instance of Cloudant to store the recommendations.

    ibmcloud service create cloudantNoSQLDB Lite logistics-wizard-recommendation-db
  4. Create a set of credentials for this service.

    ibmcloud service key-create logistics-wizard-recommendation-db for-openwhisk
  5. View the credentials and take note of the url value.

    ibmcloud service key-show logistics-wizard-recommendation-db for-openwhisk
  6. Clone the app to your local environment from your terminal using the following command.

    git clone https://github.com/IBM-Cloud/logistics-wizard-recommendation.git
  7. Change directory using cd logistics-wizard-recommendation.

  8. Copy the file named template-local.env into local.env.

    cp template-local.env local.env
  9. In local.env, update the location of the CONTROLLER_SERVICE, and the url of the Cloudant database.

  10. Get the dependencies, and use webpack module bundler to create our final .js actions in the dist folder.

    npm install
    npm run build
  11. Ensure your IBM Cloud Functions command line interface is property configured with:

    ibmcloud cloud-functions list

    This shows the packages, actions, triggers and rules currently deployed in your Functions namespace.

  12. Deploy the Functions artifacts

    ./deploy.sh --install

    Note: the script can also be used to --uninstall the Functions artifacts to --update the artifacts if you change the action code, or simply with --env to show the environment variables set in local.env.

Code Structure

File Description
deploy.sh Helper script to create the recommendations database, install, uninstall, update the Functions trigger, actions, rules.
template-local.env Contains environment variables used by the deployment script. Duplicate this file into local.env to customize it for your environment.
package.json List dependencies used by the actions and the build process.
webpack.config.js Webpack configuration used to build Functions actions. This allows the actions to use modules (module versions) not packaged natively by Functions. Make sure to add explicit dependencies in the package.json for specific module versions used by the actions. The webpack build will look at the "dependencies" and webpack them. If a module is not listen in "dependencies" it is assumed to be provided by Functions.
recommend.js Entry point for the Recommend action.
prepare-for-slack.js Entry point for the Notify action. It formats newly added recommendations into a text suitable for a Slack post message.
retrieve.js Entry point for the Retrieve action.
acknowledge.js Entry point for the Acknowledge action.
test Unit test for the actions to be executed outside of Functions.

Troubleshooting

Polling activations is good start to debug the Functions action execution. Run

ibmcloud cloud-functions activation poll

and invoke actions.

License

See License.txt for license information.

Status

master Build Status Coverage Status
dev Build Status Coverage Status