fiware / tutorials.tourguide-app

:mortar_board: FIWARE Tour Guide Application.

FIWARE Tour Guide Application

This repository is now archived. Since this application was created, a series of self-contained tutorials on each generic enabler have been created and are maintained separately for NGSI-v2 and NGSI-LD.

• The Step-by-Step Tutorials Complete collection of tutorials for the FIWARE ecosystem for NGSI-v2 developers
• The Linked Data Tutorials Complete collection of tutorials for the FIWARE ecosystem for NGSI-LD developers

More links and information can be found within the FIWARE Catalogue

FIWARE Tour Guide App was a Node.js sample application used in the FIWARE Tour Guide to show real code working with the Generic Enablers integrated.

This application is a smart, context-aware application which allows to manage large Restaurant chains which are operating worldwide. Is intended to both franchise managers and to customers. To this aim, the main functionalities provided by the application are:

• Admit Customer reservations
• Register customer reviews
• Real-time control of different parameters at each restaurant location (temperature and humidity)
• Restaurant geo-location
• Short time historic data of the different parameters monitored
• Publication of open data concerning the most relevant information about the different restaurant locations, grouped by different properties

Table of Contents

• Architecture
• How to build and install
  • Installation and Administration Guide
  • Deploying on a Cloud Fiware Lab Instance
• User and Programmers Manual
  • Miscellaneous configuration
    • How to configure a Context Provider in Orion
    • How to configure Cygnus in TourGuide
    • How to generate a new restaurant data image
    • How to run Feeders for the data image generation
    • How to retrieve an Oauth Token to use the API
• API Overview
• End to End tests
• Feedback

Architecture

It includes (for the moment) the following components:

• Orion Context Broker, providing the NGSIv2 interfaces.
• Backend Device Management - IDAS, to connect IoT devices (temperature & humidity).
• Cygnus for the Cosmos ecosystem to give persistance to the context data (using its sinks).
• Authorization PDP - AuthZForce, to get authorization decisions based on authorization policies.
• PEP Proxy - Wilma, to add authentication and authorization security to the application.
• IDM KeyRock, covering the user profile management, authorization and authentication among others.

How to build and install

This project integrates a set of Generic Enablers using those enablers inside docker containers. It also comes with restaurants, reviews and reservations loaded to start working out of the box, as well as users and organizations to play with it.

For that purpose, docker and docker-compose are required.

Installation and Administration Guide

Detailed information of how to start this environment can be found here.

Deploying on a Cloud Fiware Lab Instance

You can deploy an instance of the Fiware TourGuide App in a cloud instance using Docker-machine. Detailed information of this process can be found in the following documentation:

• Installing Docker on FIWARE Cloud

User and Programmers Manual

The complete user guide of this environment is available at Readthedocs.

Miscellaneous configuration

How to configure a Context Provider in Orion

Here you can find a simple example of how to configure a Context Provider using Orion.

How to configure Cygnus in TourGuide

As Cygnus can publish in several third-party storages, here we explain where you should add your credentials for each source to publish the TourGuide data.

How to generate a new restaurant data image

The image provided is based on Euskadi Open Data information. The image is already loaded, but we provide information on how to generate it yourself.

How to run Feeders for the data image generation

Find out how to load information into a new image using the Tourguide feeders.

How to retrieve an Oauth Token to use the API

Every TourGuide API request must be authenticated. For that purpose, we provide a simple script to generate an Oauth Token based on a username and password of the preloaded data.

API Overview

The application provides a RESTful API with different routes and functions that covers the functionalities described above:

• FIWARE TourGuide RESTful API

End to End tests

To run the end to end tests, you will need to first download the repository, then browse to server folder and run:

$ npm install
$ grunt

Grunt will run jshint and jscs linters as well as start a full TourGuide environment and run the End to End jasmine-node tests.

tutorials.tourguide-app's Issues

Drop any CEP references in the develop documentation

As develop is using latest Orion and CEP cannot interoperate with it, then drop any reference to CEP in the develop branch, both in code and documentation

Reviews generator fails patching 'aggregateRating'

When generating reservations with the feeder, the element passed to the function is wrong, leading into an error at every restaurant entity:

"aggregateRating": {
    "value": {
         "reviewCount" : 0,
         "ratingValue" : null
}

Also, we should add every string between single quotes inside the searching filters.

Use Orion latest image

Please, please, this is something we have reported so many times ... In the develop branch Orion Context Broker latest has to be used ....

Start using a Generic identifier for the restaurants

We've had several issues using the name as id for the restaurants. Due to that, it's a better approach to use a generic ID for that, by using a hash based in a sha1 or uuid's.

move data in Orion to default tenant

for the sake of simplicity and to align tour guide content and other tutorials I would ask to store all the data in the default tenant , thus avoiding any kind of fiware-service header. It would make testing easier.

change name from 'idm' to 'keyrock' in the docker-compose.yml file

as in the case of other GEs we are using the name of the GEri, we need to be consistent and do the same with the IDM

Add a README.md at the 'client' folder level

Use camelCase instead of underscore

for variable names, function names, etc.

[client] Comment code precisely, in order to facilitate learning

Dead link

Literally reported by a user:

"Following link is dead: Page: https://github.com/Fiware/tutorials.TourGuide-App/tree/master/docker/images/tutorials.tourguide-app "And example application is the restaurant data feeder."

docker-compose.yml has commented code without explanation

there are some code in the docker-compose.yml file which is commented out, I guess purpose is to show as a template, but if no comment is provided then it is useless ...

use the latest Orion Context Broker docker image

Use cygnus official image

As a new cygnus image was released following the requirements, we need to start using it as soon as possible.

Reconsider how IDAS is integrated

Integration between IDAS and Orion should be done without relying on any kind of notification mechanism. Actually, IDAS allows to map incoming readings from devices to entities in a Context Broker. So current approach seems to be unnecessary.

JSON error when loading restaurant data

When loading the restaurant data via restaurant_feeder.js there are multiple errors like:

{
  "errorCode" : {
    "code" : "400",
    "reasonPhrase" : "Bad Request",
    "details" : "Illegal value for JSON field"
  }
}

The JSON generated by the script seems to be OK, so there's something else going on here.

Application logic refactorization

Based in PR #62 comments, a refactorization for the server is needed. The main goals are:

• Fix/remove the 'promise hell', and remove the nested code
• Refactor the code used in several places
• Remove the 'filtering functions' and start using sql (simple query language) from Orion
• Adapt requests to the new Orion data model

Intructions on how to work with get-docker-hosts utility more clear

Literally reported by a user:

"Make the instructions how to work with the get-docker-hosts utility in clear steps and not only as "tricky" but necessary "

Note that the utility is at Bitergia's docker repository

client application folder structure is wrong

please only one folder javascript, one folder for stylesheets, not many

I would suggest

/js
/style

style/icons
style/images

remove pep proxy from docker-compose

until pep proxy is properly integrated I would suggest it is removed

Add a README.md at the 'server' folder level

describing what each folder contains

use a linter in the client app

Add unit tests to the client application

Restaurant filter by date returns wrong timestamp

As reported by @FiwareULPGC , the behavior when retrieving a restaurant by date is wrong.

The example provided:

GET http://tourguide/api/orion/restaurant/Uriarte/date/2016-05-31T15:00:00.000Z

Response:
[
    {
        "@context": "http://schema.org",
        "@type": "Restaurant",
        "additionalProperty":
        [
            {
                "value": 80,
                "name": "capacity",
                "@type": "PropertyValue"
            },
            {
                "value": 0,
                "name": "occupancyLevels",
                "@type": "PropertyValue",
                "timestamp": "2016-05-12T07:02:27.852Z"
            }
        ],
   .........

Let the marker show up even when not locked in

Literally reported by a user:

"Let the marker show up even when not locked in, this is a unusual behavior for me. Prevent to edit, yes, but not showing?"

Use pep proxy to protect Orion Context Broker

Right now with the actual approach, the pep proxy is 'disabled'. We will need to put pep-proxy in front of Orion. For that purpose, we will need to:

• Generate a Role 'Orion', and assign it to a test user
• Generate a custom XACML to allow access to all the resources with that role. The actual approach in Keyrock just allows to protect a resource by adding the action and the resource to protect, but not all.

Put a working example or some pictures to the install instructions

Literally reported by a user:

"Put a working example or at least some pictures to the install instructions, that one can have an idea what it will look like in the end."

Map view displays a limited amount of restaurants

While testing the map, I can only see restaurant POIs for about 40~50 restaurants. I've checked client/js/restaurants_api.js and there seems to be a variable clash between the len variable in the first for loop and that same variable in the inner for loop. Using different variable names seems to fix this and shows all the restaurant POIs.

Use module pattern in Javascript code

The Javascript modules of the client application are using plain functions which it is not a good practice. Please use the module pattern and expose to the outside the public functions exposed by the modules

var MyModule = (function() {
   function method1(param1, param2) {
   }

   return {
     method1: method1
   }
})();

Deploy TourGuide app in a Docker Swarm cluster

In a conversation with @KennethNagin, we've found an issue trying to deploy TourGuide in a cluster. After exposing to the host the following services at the following ports:

• Orion: 1026
• CEP: 8080
• IDM: 443
• TourGuide: 80

The application fails when redirecting the 'Log in' to IDM. The issue is caused for several reasons:

• This configuration in the keystone_provision.py file:

    tourguide_app = keystone.oauth2.consumers.create(
        name='TourGuide',
        redirect_uris=['http://tourguide/login'],
        description='Fiware TourGuide Application',
        scopes=['all_info'],
        client_type='confidential',
        grant_type='authorization_code',
        url='http://tourguide',
        img='/static/dashboard/img/logos/small/app.png')

Assumes that the application is being deployed at http://tourguide.

• The environment variables IDM_HOSTNAME and TOURGUIDE_HOSTNAME

Ater making the HOST at IDM provision at IDM configurable, we will need to modify the environment variables IDM_HOSTNAME and TOURGUIDE_HOSTNAME matching the requirements.

Create a readthedocs documentation project for the application

Adapt client to the new data model

Data model stored in Context Broker is wrong

Once you update to Orion >= 0.28 data model needs to be fixed: Here is the data model in normalized mode:

When creating data, if you issue a POST to /v2/entities with the JSON described below it will create the entities correctly.

{
    "address": {
        "type": "PostalAddress",
        "value": {
            "addressLocality": "Alegr\u00eda-Dulantzi",
            "addressRegion": "Araba",
            "postalCode": "01240",
            "streetAddress": "Cuesta de las Cabras Aldapa 2"
        }
    },
    "aggregateRating": {
        "value": {
            "ratingValue": 3,
            "reviewCount": 1
        }
    },
    "capacity": {
        "value": 120
    },
    "department": {
        "value": "Franchise3"
    },
    "description": {
        "value": "Restaurante de estilo sidrer\u00eda ubicado en Alegria-Dulantzi. Adem\u00e1s de su men\u00fa del d\u00eda y carta, tambi\u00e9n ofrece men\u00fa de sidrer\u00eda. El men\u00fa del d\u00eda cuesta 9 euros. Los fines de semana la especialidad de la casa son las alubias con sacramentos. En lo que a bebidas se refiere, hay una amplia selecci\u00f3n adem\u00e1s de la sidra. Cabe destacar que se puede hacer txotx. La capacidad del establecimiento es de 50 personas pero la sidrer\u00eda no dispone de aparcamiento.%5cn%5cnHORARIO: %5cn%5cnLunes a domingo: 9:00-17:00 y 19:00-23:00."
    },
    "id": "Elizalde",
    "occupancyLevels": {
        "metadata": {
             "timestamp": {
                "value": 1454350000000.0
            }
        },
        "value": 0
    },
   "location": {
        "type": "geo:point",
        "value": "42.8404625, -2.5123277"
    },
    "priceRange": {
        "value": 0
    },
    "telephone": {
        "value": "945 400 868"
    },
    "type": "Restaurant"
}

Re-write the Orion REST API for NGSI V2 implementation

As Jose Manuel said, it will be important to start using the FIWARE NGSI v2. Even though we are not using many different operations, we should start implementing it for later use.

Right now everything we have is here:

Orion REST API for Devguide

add new IDAS image to the Tour Guide

UL2.0 image as per https://github.com/telefonicaid/iotagent-ul

according to the following requirements:

hostname: 'idas', same as container target name in the docker compose.

ports opened aligned with what is said at

FIWARE-Ops/docs.TourGuide#25

no customizations of any kind, image as it is.

Drop any reference to activeX AJAX code

Please do not use activeX AJAX code THAT is VERY, VERY OLD

change attribute type `date` to `DateTime` to align with Orion Context Broker

with the recent change of Orion Context Broker from dateto DateTimewe need to align

this change also affects the Cookbook and the client app

/cc @FiwareULPGC

move docker-compose.yml to the root directory of the app

in order to make it easier to start with, I would suggest the docker-compose.yml is moved to the root directory of the app. Now it is not very conveniently situated behind a folder

Idas image fails while checking Orion is alive

Bitergia IDAS image checks for the expression <version> to check Orion is alive, but since Orion is not using XML anymore, this check fails. The official IDAS image does not check that, so this error should not appear using the official one.

unify naming conventions

sometimes '_' is used, sometimes camelCase

docker description needs to be updated

https://hub.docker.com/r/fiware/tutorials.tourguide-app/

Tour Guide and Tour Guide Application must be referenced instead of Developer Guide

I would use this issue to revise and update the content

Set branch 'develop' as default

One week ago we agreed to start using develop branch instead of master. After that, PR's #55 (which was already accepted) and #65 went against master branch, so we will need now to sync the branches.

@jmcanterafonseca I don't have the permission to set the default branch (described here). Could you please update it?

@FiwareULPGC please, take note of this change. All the new developments must go against develop, and master will be the branch used for releasing versions.

[server] Comment code precisely, in order to facilitate learning

nowadays the tour guide Application contains nearly no comments. We need to include comments at the beginning of each module, function, etc.

Use official FIWARE images for the different GEs

Add container_name to all containers in docker-compose

so that we management of containers can be more usable

https://docs.docker.com/compose/compose-file/#container-name

Authzforce official docker image name and tag changed.

The authzforce official docker image has been renamed to authzforce-ce-server and the old image has been removed, so both the release 0.5 and master are currently broken. Also, the new image only has the latest tag.

I've opened an issue to add versioned tags to the new image here: authzforce/fiware#3

Check returned codes when trying forbidden operations

As reported by @FiwareULPGC in #35:

"We also tested forbidden operations like delete and they returned 404 errors (maybe you could consider to return 403 errors instead)"

Use correct English in code

for instance 'petition' should be 'request'

Consider providing a mongo image with data for Mac Users

Unfortunately docker for Mac has not the capability of running mongoDB with an external data volume mapped to a local folder. That means that for Mac OS users we are going to need to provide an alternative Mongo image that includes both Mongo and the data.

We can reference such an image in the Docker Compose and provide a new target called 'orion-embedded' or a better name that will allow Mac users to overcome the issue with external data.

Add a README.md at the 'utils' folder level

Migrate to an Open Geocoder

Actually we are using Google's API to Geocode the restaurants. We should migrate to an Opensource geocoder provider.