Create An Extension Part 4

[#1]

• Step 9: Create Event and Subscription
• Step 10: Add Composer Entities

 

Step 9: Create Event and Subscription

In this section, you will create a mechanism to notify the user when inclement weather occurs. For example, whenever the weather indicates storm/snow/rain, an Event should be triggered. This event is then handled by a service called a Subscription.

For this tutorial, while updating weather information inside the service UpdateWeatherInfo,we need to fire an Event: BadWeather when the weather description indicates either storm/snow/rain. This Event is handled by a Subscription: HandleWeather, which is a service that gets called whenever the BadWeather Event is fired. The subscription service HandleWeather updates a property called AlertNotification.

Create Event

In this part of the lesson, we will create an Event: BadWeather that updates weather information inside the service UpdateWeatherInfo when the weather description indicates either storm/snow/rain.

1. Create a property AlertNotification with a baseType STRING using the Add Property feature of the plugin we discussed before.
   
   
2. Right click inside your java file->ThingWorx Source->Add Event.
   
   

3. Set the name to BadWeather and set a name for the Data Shape to Weather.
   
   NOTE: This custom Data Shape has to be created in Composer. Importing Datashapes and other custom entities created in Composer into your extension will be discussed later in the tutorial. Our DataShape Weather includes one field called WeatherDescription with a STRING base type. 
   
   

4. Click Finish.
   
   
   

   NOTE: This will create annotation for your EventDefinition. 

Create Subscription

In this part of the lesson, we will create a Subscription: HandleWeather, which is a service that gets called whenever the BadWeather Event is fired. The subscription service HandleWeather updates a property called AlertNotification.

1. Right click inside your java file ->ThingWorx Source->Add Subscription

   
   

2. Set the Event Name to BadWeather and Handler Service to HandleWeather.
   
   
   NOTE: This means that whenever the BadWeather event is fired, the HandleWeather service will be executed. Source is left blank if the event belongs to the same template.
   
   

3. Click Finish. This creates annotation for subscription service and also creates a new service called HandleWeather.
   

Modify Service

In this part of the lesson, you'll ensure that when the properties are updated, BadWeather event is triggered if the description indicates rain/snow/thunderstorm. To do this, we will modify the UpdateWeatherInfo service.

After we have called the setPropertyValue method for the properties WeatherDescription and Temperature, we can check if the weather description contains snow/rain/thunderstorm. We will create an InfoTable from the Weather Datashape. InfoTables represent data sets that take the structure of the Datashape. Each row of an InfoTable can be passed as a ValueCollection to hold data within the table. When an event is fired, we need to send data along with it. This data will be passed as an InfoTable and it is then handled by the Subscription handling the Event.We use a ValueCollection to add the weatherDescription to the InfoTable. Then, this InfoTable is set as the Event Data.

1. Add the code snippet to UpdateWeatherInfo section at the end of the service after setting the properties- Temperature and WeatherDescription.
   
   

   /* fire event BadWeather */
    if (description.contains("snow") || description.contains("rain") || description.contains("thunderstorm")) {
        ValueCollection v = new ValueCollection();
        v.put("weatherDescription", new StringPrimitive(description));
        InfoTable data = InfoTableInstanceFactory.createInfoTableFromDataShape("Weather");
        data.addRow(v);
        _logger.info("Firing event");
        ThingworxEvent event = new ThingworxEvent();
        event.setEventName("BadWeather");
        event.setEventData(data);
        this.dispatchEvent(event);
    }
   
   

2. Inside the HandleWeather service, set the property AlertNotification. Ensure that you have created the property AlertNotification using the eclipse plugin.
   
   

3. Add the following code snippet to the HandleWeather service.
   
   

   @ThingworxServiceDefinition(name = "HandleWeather", description = "Subscription handler", category = "", isAllowOverride = false, aspects = {"isAsync:false"})
   public void HandleWeather(
    @ThingworxServiceParameter(name = "eventData", description = "", baseType = "INFOTABLE") InfoTable eventData,
    @ThingworxServiceParameter(name = "eventName", description = "", baseType = "STRING") String eventName,
    @ThingworxServiceParameter(name = "eventTime", description = "", baseType = "DATETIME") DateTime eventTime,
    @ThingworxServiceParameter(name = "source", description = "", baseType = "STRING") String source,
    @ThingworxServiceParameter(name = "sourceProperty", description = "", baseType = "STRING") String sourceProperty) throws Exception {
        _logger.trace("Entering Service: HandleWeather with: Source: \"\", Event: \"BadWeather\", Property: \"\"");
        this.setPropertyValue("AlertNotification", new StringPrimitive("Alert:"+eventData.getFirstRow().getStringValue("weatherDescription")));
        _logger.trace("Exiting Service: HandleWeather");
    }

Now we have an event BadWeather fired every time weather description indicates storm/snow/rain and it is handled by HandleWeather service that sets the AlertNotification property to the InfoTable data passed by the event.

Step 10: Add Composer Entities

In previous parts of this tutorial, we assumed we had a datashape Weather available with field weatherDescription as the Datashape of our event: BadWeather.

In this part of the lesson, we'll create a DataShape.

1. Go to ThingWorx Composer. Click the + button.

   
   

2. In the dropdown, select Data Shape.
   
   
   
   
3. Enter a name, for example: Weather.
   
   
4. Add a Field Definition weatherDescription with baseType STRING.
   
   
5. Click check mark in the top left, then Save.
   
   
6. Click the More drop-down, then click Export. Export the DataShape entity from Composer, it will download in your system as an xml file.
   
   
7. Go back to Eclipse, right-click on your project ->Import..->ThingWorx->Entities.
   
   
   
8. Click Next. Browse to the directory where the xml file was downloaded. Select the xml file and Click Finish.
   
   

    
   NOTE: This adds the xml file to the Entities folder in your project.
   
   

9. Following the same procedure, import other entities required for this Extension stored in the Entities folder of the download we provided for this training.
   
   NOTE: You can uncheck the box for importing DataShapes_Weather.xml, if you already loaded your Datashape in the previous steps.

Click here to view Part 5 of this guide.