Purpose

To familiarize developers with the powerful features of the Vantiq Catalog.

Objectives

By the end of this tutorial, the developer should be able to:

• Access and configure a Catalog
• Link subscribers and publishers to the Catalog
• Set up access tokens to the Catalog for maximum security
• Subscribe to events from the Vantiq IDE
• Create and publish simulated events with VAIL Rules and Procedures
• Be able to verify event receipt to subscribers
• Create and publish a Service to the Catalog
• Subscribe to a Catalog Service and execute Service Procedures in an Application

Tutorial Overview

In this tutorial, we will create a simple application that publishes “overheat” events when a simulated machine sensor reports a temperature that is too high. Our Catalog set-up will allow such events and related “reaction” events to communicate across different Namespaces.

The basic steps involved to accomplish this are:

• Create separate Namespaces for the Catalog, publisher, and subscriber
• Register the publisher and subscriber to the Catalog
• Define Event Types
• Define a Catalog Service
• Receive events
• Generate and publish events
• Execute Procedures from a Catalog Service

Part 1: Setup Catalog Infrastructure

Step 1: Create Catalog Namespaces

This tutorial requires three Namespaces, which means you should first familiarize yourself with creating and managing Namespaces in the User and Namespace Administration Tutorial.

The first step is to sign into a Namespace in which you have developer or higher privileges. From there, you will create Namespaces to act as each of the three Catalog roles: Catalog, Subscriber and Publisher.

Use the Administer button to select Namespaces, then use the New button in the Namespaces list to create three Namespaces with the following names: catalog, publisher and subscriber. You should be the administrator of each of these Namespaces.

Once you’ve created the three Namespaces, switch into the catalog Namespace using the Current Namespace button at the top right of the IDE Navigation Bar and selecting catalog from the list of available Namespaces.

Step 2: Configure Catalog

Now that all of the Namespaces have been created and you’re in the catalog Namespace, it’s time to configure each Namespace for its respective role. The catalog Namespace is currently just a standard developer Namespace. To allow this Namespace to host a Catalog of events and Services, use the Administer button to select Advanced>Catalog which displays the Manage Catalog pane. Click the Create Catalog button and confirm that you want to create a Catalog.

This Namespace is now ready to host events and Services in the Catalog. Other Namespaces that connect to the catalog Namespace can read the Catalog of events and Services and register as publishers and subscribers of events and Services.

Of course, we’ll be publishing important information through this catalog. We don’t want just anyone to be able to send out messages. To avoid this, we can change the default permissions for connected namespaces.

In the Manage Catalog pane, find the catalog namespace (it should be the only one present right now) and click on Edit Permissions. Toggle off the box for publish under Event Types then click OK. Now no members of the catalog will be allowed to publish to Event Types unless we explicitly let them.

Step 3: Connect Publisher and Subscriber to Catalog

The next step is to connect the publisher and subscriber Namespaces to the catalog Namespace.

To connect the publisher and subscriber Namespaces to the catalog Namespace, we need to get credentials that can be used by those Namespaces to communicate with the catalog Namespace. To that end, we create an access token by clicking the Create Token button in the Manage Catalog pane. Name the access token “CatalogToken” then click Save. This creates a new token and copies it to the browser clipboard. Save this token string somewhere readily accessible as we’ll need it to configure the subscriber and publisher Namespace Catalog connections.

Switch into the publisher Namespace using the Current Namespace button at the top right of the IDE Navigation Bar and selecting publisher from the list of available Namespaces. You will see the page reload and you will now be in the publisher Namespace. Verify this by checking that the Namespace name in the Navigation Bar has changed from catalog to publisher.

Once in the publisher Namespace, we must connect to the catalog Namespace using the access token we just created. Use the Show button to select Catalogs to display the Catalogs pane. Use the New button to display the Connect to Catalog dialog. Paste the token string into the New Catalog Access Token field, verify the URL in the URL to Connect to Catalog Namespace field, and click the Connect button.

Switch to the subscriber Namespace and repeat the process of connecting to the catalog. Afterwards, both the publisher and subscriber Namespaces are now able to view the Catalog of Event Types and Services hosted by the Catalog Namespace. To view the Catalog of Event Types and Services from any connected Namespace, use the Show button to select Catalogs to display the Catalogs pane. Click on any listed Catalog Namespace to display its list of known Event Types and Services.

Both the publisher and the subscriber namespace need to perform publishes as part of this tutorial. Because we changed the default catalog permissions to disallow publishing, we must now override the default permissions for both namespaces. To do this, return to the catalog namespace and open the Manage Catalog pane. For the publisher and subscriber namespaces in the list, click Edit Permissions. Select “Event Types” and “publish” in the dropdowns, then click Add Override. Make sure the box is checked, then click Save.

Part 2: Creating Events

Step 1: Create Event Schema

To get started on creating the machine temperature and overheat Event Types, switch back to the catalog Namespace.

Before we can create the Event Types, we first need to define a schema type which defines the schema for the machine temperature and overheat events. Use the Add button to select Type and create a new type. In the resulting dialog, name the type MachineData, change the role to schema then click OK. From the Type: MachineData pane, assign the type the following properties, making sure to check them all as required:

• machineId (String) – A unique identifier that associates a reading with a specific machine.
• temperature (Integer) – The sensor reading in degrees fahrenheit.
• timestamp (DateTime) – The time at which the sensor reading was recorded.

Step 2: Define Event Types

Now we finally get to add events to the Catalog. While still in the catalog Namespace, open the Catalogs pane by using the Show button to select Catalogs. Select the catalog Catalog Namespace from the list, then use the New button to select Create New Event Type. The Event Type pane is displayed in which we create our first Event Type. Configure this Event Type with the following values:

• Event Name: /machine/temp
• Description: A new machine temperature sensor reading.
• Schema: Select MachineData from the droplist

Note that the Event Type name is a Topic. Topics must contain a leading slash but often contain additional slashes, which is a good practice for organizing events in a hierarchical manner. The prefix /machine indicates this is an event on a machine and the suffix /temp indicates this is a temperature event. In the future, we will add another event with the same /machine event prefix. Giving events common prefixes makes it easier to find them in the Catalog and helps users looking at the Catalog get a sense for how different events are related.

Once you’ve completed the new Event Type pane, click the Save Changes icon and you’ll see a list of suggested keywords found by parsing the specified description. Leave machine and temperature, delete the rest, then click OK. This will add some keyword tags to the newly created Event Type, which offers users a different way to query for interesting Event Types.

Follow the same process to create an Event Type for the overheating event. Use the following configuration:

• Event Name: /machine/overheat
• Description: The temperature of a machine has risen above the normal operating range.
• Schema: Select MachineData from the droplist

Save the Event Type, then uncheck any unhelpful suggested keywords. (In this case, everything except machine and temperature.) Click OK. You should now see two Event Types listed in the Catalog pane.

Step 3: Register a Publisher

Now that we have the necessary events in the Catalog, it’s time to switch to the publisher Namespace and start producing temperature events. Create a project by entering a name “MachineData” to the right of the Vantiq logo in the Navigation Bar then clicking the green Save button. After each step, save the project by clicking the green Save button again.

Next, open the Catalog by using the Show button to select Catalogs. Select the catalog Catalog Namespace from the list, then click on the /machine/temp event in the list. In the resulting Event Type pane, click on Click to View next to Publishers. In the Publishers of /machine/temp dialog, specify a local Topic, /my/machine/temp/event, for the /machine/temp event. Click + Become Publisher.

The local name of an Event Type is the Topic on which the events will occur in this Namespace. For this tutorial, we set the local name to /my/machine/temp/event. This means that when an event occurs on /my/machine/temp/event, it will be forwarded to all of the subscribers of /machine/temp.

Step 4: Publish Events

We now need to generate events in this publisher Namespace that will be published to /my/machine/temp/event so the subscriber Namespace will have some data to consume. To generate random data, we create a rule that runs every five seconds and publishes the data to /my/machine/temp/event. To create a rule, use the Add button to select Rule then click the New Rule button.

Create a rule with the following text:

RULE tempEventTrigger
WHEN PUBLISH OCCURS ON "/random"
// Publish one random temperature event each for 3 machineIds
PUBLISH {temperature: random(0, 100), machineId: "Machine1", timestamp: now()} TO TOPIC "/my/machine/temp/event"
PUBLISH {temperature: random(0, 100), machineId: "Machine2", timestamp: now()} TO TOPIC "/my/machine/temp/event"
PUBLISH {temperature: random(0, 100), machineId: "Machine3", timestamp: now()} TO TOPIC "/my/machine/temp/event"

This rule will run every time an event publishes to the /random Topic. Next we need to create a Scheduled Event that will publish to /random once every five seconds. To create the Scheduled Event, use the Add button to select Advanced>Scheduled Event then click the New Scheduled Event button.

Create a new Scheduled Event with the following properties:

   Name: "RandomTempGenerator"
   Topic: /random
   Periodic?: True
   Active?: True
   Scheduling Type: Periodically, starting now
   Interval: 5 seconds

If you want to verify that the events are being published as you expect, use the Show button to select Resource Graph then find and click on the Topic /my/machine/temp/event. Click the Test Data Receipt button in the top left of the resulting pane. This displays a subscription pane that streams all of the events in real time that occur on that Topic, all of which are forwarded to all subscribers of the Event Type /machine/temp. Wait five seconds and you should see an event like this: