User Guide

0 mins to read



Revision History

Version

Date

Changes

1.0

06/12/2021

Initial draft

1.1

15/12/2021

Initial release version














Introduction

Geotab has received a number of inquiries from Partners seeking the ability to have Rule ExceptionEvents published to the Google Pub/Sub service. Investigation resulted in the development of a proof-of-concept to determine feasibility. The outcome is the solution described in this document.

Target Audience

The target audience for this document includes technicians who have a solid understanding of Google Cloud Platform (GCP) and the Google Pub/Sub architecture, and who are seeking to implement the flow of Geotab Rule Exception Event data via Google Pub/Sub.

Problem Description

In the current era of complex system architecture, it is often necessary for distributed systems and services to communicate among each other. Using a microservice architecture is one way to achieve this goal.

A microservice architecture arranges an application (or multiple applications) into a collection of loosely-coupled services, thereby facilitating asynchronous processing, the use of lightweight protocols, and independent ownership of the individual services. Google implements this microservice architecture via the Google Pub/Sub interface.

Some Geotab Partners expressed interest in establishing a microservice-type setup around the MyGeotab Rules Exception Engine implementation. A MyGeotab Rule is the definition of conditions that, when met, generate an ExceptionEvent. When raised, ExceptionEvents can trigger several actions, including the initiation of a web request to an external system, which can invoke downstream actions or workflows in the external system.

Solution Description

On the MyGeotab side, the solution starts with creating or editing a Rule and its conditions, then configuring the Rule to POST a web request whenever the conditions are met and an associated ExceptionEvent is fired. The web request is configured to POST its data to a predefined Google function. Upon receiving the web request, the Google function parses the data, and makes any necessary decisions. If all conditions are satisfied, the Google function publishes the parsed data to the Google Pub/Sub service. The solution architecture diagram and sequence diagram provide a high-level visual representation of the solution.

Code Example

C# Example (Git)


Implementation

This section details the implementation of the various elements comprising this Geotab-to-Google Pub/Sub solution.

MyGeotab

On the MyGeotab side, there are two critical elements to the solution: a notification template and a Rule. Review the details of each element in the following subsections.

Notification Template

First, create a Notification Template (Web Template) in MyGeotab following the steps below:

  1. Navigate to Rules & Groups > Rules.
  2. Click the Notification templates button at the top of the page.
  3. Click the Add web template button at the top of the Notification Templates page.
  4. Enter the information on the Web Request Template Edit page based on the following table:

Field

Information

Template name

A meaningful name to be referenced in the Rule configuration that follows.

URL

The GCP cloud function trigger URL. Find this in the trigger tab in the cloud function.

HTTP request type

POST

POST Data

A list of key value pairs

Your secret authentication key and value.

Any available tokens you would like transmitted for eventual consumption in your destination system.

Example:

MyKey: MyKeyValue

Database:{Database}

Serial number:{Serial number}

Rule:{Rule}

Latitude:{Latitude}

Longitude:{Longitude}

Odometer:{Odometer}


✱ NOTE: The MyKey pair defined in the POST Data section above can be interrogated later in the Google function to establish a weak authentication implementation.

Rule

Once you create a notification template, you must configure a Rule to utilize the notification template when POSTing web requests to the Google Pub/Sub service upon the firing of associated ExceptionEvents. To configure a rule, follow the steps below:

  1. Navigate to Rules & Groups > Rules.
  2. Click Add at the top of the page to add a new Rule. Alternatively, edit an existing Rule by clicking the pencil icon next to a rule.
  3. On the Exception Rule Edit page, select the Notifications tab.
  4. Click More under Notification Recipients, then select Web request.
  5. Select the notification template that was created in the previous section.

Google Cloud Platform

On the Google Cloud Platform (GCP) side, create a Cloud Function using the following table as a configuration guideline:

Item

Setting

Function name

A meaningful name.

Region

The applicable region.

Trigger

Trigger type

HTTP

Authentication

Allow unauthenticated invocations. See note below.

Require HTTPS

Set this to true.


✱ NOTE: At the time of writing rule, web requests can only be sent unauthenticated. A project is underway to add authentication to this feature. This process will be updated once this has been implemented.

The Google Cloud Functions Documentation provides guidance related to the function creation, which can be harnessed to act upon the data contained in the Geotab-initiated web request.

✱ NOTE: It is possible to dynamically publish to different topics based on the Rule type of the ExceptionEvent. To do this, add a decision path in the code implementation based on different notification template structure inputs.

Diagrams

Solution Architecture

A high-level architecture view of the solution:

Sequence Diagram

Conclusion

The solution outlined here has been tested in a limited proof of concept scenario with limited volumes of data. The amount of Rule Event Exceptions that can be feasibly handled using this approach is unclear. We recommend that you conduct load testing and other analyses to validate compliance with your solution architecture and throughput requirements. Additionally, any other risk and technical factors should be assessed prior to incorporating this solution into your integration.

scroll-up