Source Tutorial

Tutorial Overview

This tutorial guides a developer through lessons in the use of data sources in VANTIQ system. It uses a publicly available weather feed to retrieve a zip-coded temperature forecast which then triggers a rule to save that temperature value. The temperature value can then be combined with other data in rules to provide temperature-related decisions.

All lessons assume the developer has a working knowledge of VANTIQ Modelo. It is recommended that a new developer completes the lessons in the Introductory Tutorial before starting the lessons in this tutorial.

1: Creating a Source Project

The first task is to create a project in Modelo to assemble all the source components.

Use the Projects button, select Create New Project and title the project “WeatherSource”:

        SourceProject

The rest of the lessons take place inside this Modelo project.

2: Creating The Source

A source in VANTIQ system allows for the integration of external data sources, both for the retrieval of data and as the recipient of data. For in-depth information about sources, please refer to the Vantiq Reference Guides.

This tutorial retrieves weather information from OpenWeatherMap, which provides weather forecast data via a REST interface. The first task is to create the source, which defines how to interact with the OpenWeatherMap API. OpenWeatherMap requires the use of a free API key in order to retrieve data. Please visit the OpenWeatherMap key page in order to create the key you’ll use later in this lesson.

Use the Add button to select Source…:

        AddSource

Use the New Source button to create our source:

        CreateSource

Select the REMOTE Source Type since OpenWeatherMap provides its weather forecast data via a REST interface. Change the Polling Interval to 15 seconds which specifies how often the forecast data is retrieved. Select the application/json Content Type since the forecast data is returned in JSON format. No other Source Properties need to be entered for OpenWeatherMap.

Enter the Server URI to define the URI used to retrieve OpenWeatherMap data. For this example, the forecast data is retrieved using zip code, although forecast data can also be retrieved via city name, geographic coordinates, or city ID. Enter http://api.openweathermap.org/data/2.5/weather?zip=94549,us&APPID={YourRegisteredAppID} as the URI, making sure to substitute the OpenWeatherMap API key you created for {YourRegisteredAppID}.

Once the source has been configured, use Test Data Receipt to try to retrieve data from the source. (Test Data Receipt will only be enabled if a source’s Content Type property is application/json.) A new window will appear and display any data received by the source. For example, here is some sample data from our weather source:

        TestDataReceipt

Use Stop Data Receipt to stop receiving data and to return to the source definition.

Enter weather as the name of the source, use the Save button to save the source to return to the Modelo project. Use the Save button at the top, left of Modelo to save the project.

3: Creating a Data Type

The weather forecast data retrieved from OpenWeatherMap needs to be stored in the VANTIQ database so that it can be used with other data to trigger situational-specific rules. You must create a data type to specify that data.

Use the Add button to select Type…:

        AddType

Use the New Type button to create the forecast reading type:

        CreateForecast

The weatherReading type contains five properties:

Both location and zipCode are required to make sure OpenWeatherMap sends well-formed data. Once these five User Properties are defined, use the Save button to save the weatherReading type.

Use the Save button at the top, left of Modelo to save the project.

4: Creating a Data Instance

For our example, you must create an entry in the VANTIQ database that defines where the forecast data for the specified zip code is stored.

Use the Show button to select Add Record…, then use the Type pull-down menu to create the weatherReading instance:

        CreateWeatherInstance

Select the weatherReading Data Type since you are creating a weatherReading entry. Enter Lafayette as the location property, which is the city associated with the example zip code. Enter 94549 as the zipCode property. Use the Add New Record button to save the entry. This creates one weatherReading entry to store the weather forecast data for zip code 94549.

5: Creating a Rule

Rules are used to recognize that data has been added to or modified in the VANTIQ database and organize that data for further processing. In our example, there is one Rule, which is triggered whenever forecast data is retrieved from the weather source created in Lesson 2.

Use the Add button to select Rule…:

        AddRule

Use the New Rule button to create your weather forecast processing rule:

        ForecastRule

The weatherReading rule is defined as follows:

RULE weatherReading

WHEN MESSAGE ARRIVES FROM weather
UPDATE weatherReading(tempK:weather.main.temp) WHERE location == weather.name

This rule is triggered whenever forecast data is retrieved from the OpenWeatherMap weather source. The WHEN MESSAGE ARRIVES FROM weather statement specifies the weather source name and subsequent references to weather refer to the data returned by the source.

This rule simply updates the weatherReading current temperature (in Kelvin) for the location associated with the forecast (indicated by the location property). The forecast data is returned in JSON format so the rule uses the weather variable as the root of the JSON object to retrieve relevant forecast data: weather.main.temp is the temperature forecast in Kelvin and weather.name is the city location associated with the forecast. Check the Active checkbox (under the Save button) to enable the rule then use the Save button to save the rule and return to the Modelo project.

Use the Save button at the top, left of Modelo to save the project.

6: Verifying and Using The Data

This lesson verifies that weather forecast data is properly retrieved by the weather source and saved by the weatherReading rule. In addition, this lesson also demonstrates how that saved forecast data might be used in other rules.

Since forecast data is retrieved every 15 seconds (the weather source’s Polling Interval), no more than 15 seconds will pass after you created the weatherReading rule in Lesson 5 before data is stored in your weatherReading instance. To verify that the source and rule are triggering, use the Show button to select Find Records to display the Find Records query pane:

        QueryForecast

Select the weatherReading data type then use the Run Query button to retrieve all weatherReading objects from the VANTIQ database:

        ForecastData

There should only be one instance for the zip code (94549) you created in Lesson 4. The only weatherReading property updated by the weatherReading rule is tempK, which is set to 289.3 in the example above. This indicates that weather source has retrieved data, which triggered the weatherReading rule, which updated the weatherReading data type for the Lafayette location.

Now that the forecast data is available, you can use it in other rules. For example, the following rule could be defined:

WHEN UPDATE OCCURS ON Customer
SELECT UNIQUE weatherReading:wr WHERE zipCode EQ Customer.location

if (wr.tempK >= 300) {
    UPDATE Offer(offerMessage: "Buy a fan") WHERE (customerId == Customer.id)
}

Here is a breakdown of this example rule, starting with:

WHEN UPDATE OCCURS ON Customer
SELECT UNIQUE weatherReading:wr WHERE zipCode EQ Customer.location

This rule is triggered whenever a customer (defined by a Customer data type) instance is updated, for example, when the customer enters a store in a particular zip code. The SELECT UNIQUE statement instructs the rule to find the weather forecast (the weatherReading data type) entry for the customer location by referencing the zipCode.

Next is the if statement which evaluates whether the outside temperature forecast for the store’s zip code is greater than about 80F (300K):

if (wr.tempK >= 300) {

and, if so, updates the Offer data type associated with the customer’s ID:

    UPDATE Offer(offerMessage: "Buy a fan") WHERE (customerId == Customer.id)
}

7: Deactivating or Deleting a Source

When you are finished with this tutorial, you should either (1) deactivate the source or (2) delete the source so that data from OpenWeatherMap doesn’t continue to be collected. At this point, Modelo’s Project Resource Graph pane should look similar to this:

        PRG

To deactivate the source, click the Source: weather oval in the Project Resource Graph to display the Source: weather pane:

        Deactivate Source

Use the Toggle Keep Active Off icon button of the Source: weather pane (small checkmark in a square at the top, right of the pane), then use the Save Changes icon button in the pane (down arrow at the top, right of the pane) to save the source.

To delete the source, right-click on the Source: weather oval in the Project Resource Graph and select Remove from Project and Delete from the menu.