Community

Working with Verizon Connect Reveal in ArcGIS GeoEvent Server

1196
0
04-21-2023 07:00 PM
Jeff_G
by Esri Contributor
Esri Contributor
3 0 1,196
‎04-21-2023 07:00 PM

Introduction

Verizon Connect provides multiple fleet management solutions for tracking and managing your fleet of vehicles. This guide will focus specifically on Verizon Connect Reveal’s GPS Push Service and how you can connect to the data feed and perform real-time ingestion and analysis with ArcGIS GeoEvent Server. This approach requires a HTTPS endpoint to be set up in such a way that a Verizon Connect can connect and send the data to it. The HTTPS endpoint needs to be protected using basic authentication and be accessible outside of your organization’s network firewall. This guide uses Windows IIS and the following steps highlight enabling basic authentication and routing from an IIS endpoint to an ArcGIS GeoEvent Server connector endpoint. An organization firewall or a load balancer can be used in place of IIS.

This guide will demonstrate the following:

  • Creating an HTTPS endpoint on GeoEvent Server.
  • Creating an HTTPS endpoint on IIS with basic authentication enabled.
  • Routing traffic from the HTTPS endpoint on IIS to the HTTPS endpoint on GeoEvent Server.

Requirements

  • ArcGIS GeoEvent Server installed and configured.
  • Verizon Connect Reveal requires a public-facing endpoint configured with basic authentication to send data to. Please consider solutions for accomplishing this such as a web server on a DMZ, an application gateway, or a load balancer. This guide will use IIS to create an endpoint that is publicly accessible.
  • Familiarity with configuring inputs, GeoEvent Services, and outputs in GeoEvent Manager. Access the available quick start guide, documentation, and tutorials. This guide refers to GeoEvent Server 11.1.

Import the GeoEvent Server Configuration file

This guide contains a downloadable GeoEvent configuration file which contains GeoEvent Definitions (schemas) that are needed to process data from Verizon Connect Reveal.

The download is at the bottom of the blog page in a .zip file. Download the .zip file, extract the VerizonConnectReveal_Config.xml file, and import it to GeoEvent Server using the following steps.

  1. In a web browser, navigate to ArcGIS GeoEvent Manager and go to Site > GeoEvent > Configuration Store
    Jeff_G_0-1682123441005.png
  2. Click Import Configuration and select the downloaded configuration file for import.
  3. Click Next and choose Import Configuration to import the entire configuration and click Import
    Jeff_G_1-1682123441006.png

Configure a GeoEvent Server connector endpoint to receive data from Verizon Connect Reveal

    1. Open a web browser and navigate to ArcGIS GeoEvent Manager (e.g., https://<hostname>:6143/geoevent/manager).
    2. Click Add Input and then click Receive JSON on a REST Endpoint.Jeff_G_2-1682123441010.pngJeff_G_3-1682123441012.png
    3. Configure the new input connector with the following parameters:
      • Name — VerizonConnectReveal-rest-json-in
Note: For this guide, we will be using this name. However, you are free to use any name of your choosing.
      • GeoEvent Definition Name (Existing) — VerizonConnectReveal-SubscriptionConfirmation
      • Expected Date Format — yyyy-MM-dd'T'HH:mm:ss'Z'
Note: This date format is mandatory. Data will not be processed unless this date format is configured with the input connector.
    • X Geometry Field — longitude
    • Y Geometry Field — latitude
      Jeff_G_40-1682125382076.png
  2. Click Save to save the new input connector.
  3. Start the newly created input connector by clicking on the play icon.Jeff_G_5-1682123441016.png
  4. Click on the input connector to open the properties window.Jeff_G_6-1682123441017.png
  5. Copy the URL parameter and save it in a text editor. This will be used to create a URL Rewrite rule.Jeff_G_7-1682123441017.png

Enable basic authentication

To receive data from Verizon Connect Reveal, the HTTPS endpoint you just created needs to have basic authentication. GeoEvent does not support basic authentication out of the box, so we will need to use an application such as IIS to route traffic from this HTTPS endpoint to a HTTPS endpoint enabled with basic authentication.

  • The following steps assumes the following:
  • IIS is installed and enabled on the machine
  • The machine is on the DMZ of your organization’s network, or traffic from outside your organization’s network can be configured to access the web server

Note: IIS does not have to be on the same machine as your GeoEvent Server. However, the web server must be able to communicate with GeoEvent Server.

Windows Server 2019 and up

  1. Open Server Manager and select Manage > Add Roles and FeaturesJeff_G_8-1682123441028.png
  2. Keep selecting Next until Server Roles is selected.
  3. Navigate to Web Server (IIS) > Web Server > Security and check the Basic Authentication checkbox.Jeff_G_9-1682123441032.png
  4. Keep clicking Next until the Confirmation section is selected.
  5. Click Install, wait until the installation completes, then click Close.

Windows 10

  1. Open the Control Panel and navigate to Programs > Programs and Features.
  2. Click Turn Windows features on or off.Jeff_G_10-1682123441034.jpeg
  3. Navigate to Internet Information Services > World Wide Web Services > Security and check the Basic Authentication checkbox.
    Jeff_G_11-1682123441038.jpeg
  4. Click OK to apply the change and Close once the change is applied.

Next, you will create a local account on the machine that will provide the HTTPS endpoint for the Verizon Connect Reveal server to authenticate, connect to, and send data to.

  1. Open Computer Management and navigate to Local Users and Groups > Users
  2.  Under More Actions, click New User.
  3. Enter your Username and Password and check Password never expires.Jeff_G_12-1682123441041.jpeg
  4. Click Create to create the new user.

Next, we will create a virtual directory in IIS that will serve as our HTTPS endpoint.

  1. In File Explorer, create a new folder with the name of HTTPS endpoint for the Verizon Connect Reveal server. This may be a name of your choosing. For this guide, we will be using C:\VerizonReveal.
  2. Open Internet Information Services (IIS) Manager and navigate to Sites and right-click Default Web Site and choose Add Virtual Directory.
    Jeff_G_13-1682123441045.jpeg
  3. Enter the Alias and Physical path as illustrated below, then click the OK button to dismiss the dialog.Jeff_G_14-1682123441047.jpeg
  4. Click OK to add the new virtual directory. The new virtual directory should now appear under Default Web Site.
    Jeff_G_15-1682123441048.jpeg
  5. To test the virtual directory, create a new index.html file in C:\VerizonReveal
  6. Open index.html in a text editor and copy and paste the content below.
    <!DOCTYPE html>
    <html>
    <body>
    Hello Verizon
    </body>
    </html>
  7. Save the text file.
  8. In a browser, enter http://localhost/verizonrevealJeff_G_38-1682124219105.png
    The text Hello Verizon should display on the page.

Next, it is necessary that basic authentication be enabled for the virtual directory in IIS Manager.

  1. Open Internet Information Services (IIS) Manager and navigate to Sites > Default Web Site and select the verizonreveal virtual directory.
  2. Double-click Authentication.
    Jeff_G_17-1682123441053.jpeg
  3. Select Basic Authentication then choose Enable under Actions on the right paneJeff_G_18-1682123441056.jpeg
  4. The Anonymous Authentication status is Enabled by default, select it and then choose Disable from the Actions panel on the right.
  5. To test the basic authentication, open the browser and navigate to http://localhost/verzionreveal/. A Sign in dialog will pop up.
    Jeff_G_19-1682123441057.jpeg
  6. Enter your Username and Password for the verizonconnect user you previously created and click Sign in.

If authentication is successful, the webpage will display Hello Verizon, indicating basic authentication is working properly.

Route traffic from an IIS endpoint to a GeoEvent Server connector endpoint

The URL Rewrite and Application Request Routing are IIS modules that are needed to redirect HTTP traffic. The URL Rewrite module should be installed first, followed by the Application Request Routing module.

  1. Download and install URL Rewrite from IIS.net here: https://www.iis.net/downloads/microsoft/url-rewrite
  2. Download and install Application Request Routing here: https://www.iis.net/downloads/microsoft/application-request-routing
  3. After both modules are installed, relaunch IIS Manager to refresh its content.
  4. Under the IIS group, double-click Application Request Routing Cache to open it.Jeff_G_20-1682123441065.png
  5. In the Actions panel, in the Proxy subgroup, click Server Proxy Settings.
    Jeff_G_21-1682123441068.jpeg
  6. Check the box for Enable proxy and keep the default values for all other parameters.Jeff_G_22-1682123441075.png
  7. Click on Apply under the Actions panel to save your changes.
  8. Navigate back to Home in IIS Manager by clicking the machine name in the tree view.
  9. Double-click on the URL Rewrite to open it.
    Jeff_G_23-1682123441081.png
  10. Click Add Rule(s) from the Actions panel.
    Jeff_G_24-1682123441083.jpeg
  11. On the Add Rule(s) dialog, select Blank rule and click OK.
    Jeff_G_25-1682123441085.jpeg
  12. Enter the rule configuration as illustrated in the example below.
    Note: The Rewrite URL you enter should be the same URL as the GeoEvent Server input connector you created in the Configure a GeoEvent Server connector endpoint to receive data from Verizon Connect Reveal section above.
    Jeff_G_26-1682123441087.png

For this example, the Rewrite URL is

https://<your_server>:6143/geoevent/rest/receiver/VerizonConnectReveal-rest-json-in

  1. Click Apply to create the rule.
  2. Click Back to Rules to navigate back, the newly created rule will be listed.Jeff_G_27-1682123441089.jpeg

Your URL should now be accessible via https://<webserverhostname>/verizonreveal

This is the URL that will be used to provide to Verizon Connect in future steps.

It is recommended you encrypt the traffic using an HTTPS URL to avoid exposing the basic authentication information in the HTTP header. Since the HTTP traffic is being sent over a public network, it is also recommended you obtain a CA-signed certificate for your server from a trusted certificate provider (e.g., Verisign, DigiCert, etc.) and apply it to your server.

Confirm Subscription

Verizon Connect requires users to confirm the subscription to the GPS Push Service with a subscription confirmation URL. The initial message from the GPS Push Service contains the SubscribeURL parameter. We will need to use the input connector to receive this message and send it to an output.

In the Configure a GeoEvent Server connector endpoint to receive data from Verizon Connect Reveal section, we already configured the input connector to receive the subscription confirmation message.

Jeff_G_39-1682125369568.pngGeoEvent Server needs to be able to send the subscription confirmation message to an output using an output connector, such as Send an Email or Write to a JSON File. In this guide, we will be using Write to a JSON File.

  1. Remote into the GeoEvent Server machine and create a folder where the output connector can write a JSON file to. Alternatively, you can register a folder on a file share that the GeoEvent service account can access.
  2. In GeoEvent Manager, click Add Output under GeoEvent Services and name it SubscriptionConfirmation-file-json-out
    Jeff_G_29-1682123441095.png
  3. Click Register Folder and enter the path name of the folder you created in step 1.
  4. For Filename Prefix, enter SubscriptionConfirmation
    Jeff_G_30-1682123441096.png
  5. Keep all other values as default and click Save.

Now we must create a GeoEvent Service to connect the input and output connectors that we just created.

  1. In the GeoEvent Manager page, click Add Service under GeoEvent Service.
    Jeff_G_31-1682123441100.png
  2. You may provide any name of your choosing. In this guide we will be naming it Verizon Connect Reveal Confirmation.
  3. Drag-and-drop the VerizonConnectReveal-rest-json-in and SubscriptionConfirmation-file-json-out connectors into the service designer and connect them together.
    Jeff_G_32-1682123441102.png
  4. Click Publish.

Now that the input and output connectors have been configured, we are ready to receive the subscription confirmation message from the GPS Push Service. Ensure that the GeoEvent service and both input and output connectors are turned on and have been configured correctly.

You will now need to submit the following to Verizon Connect:

  • The credentials created in the Enable basic authentication section.
  • The HTTPS endpoint created in the Route traffic from an IIS endpoint to a GeoEvent Server connector endpoint section.

For more information, go to the following link or contact Verizon Connect Customer Support.

Once HTTPS endpoint and credentials are provided to Verizon Connect, the first message from the GPS Push Service will be the subscription confirmation message.

Note: You will have three days to confirm the submission request. If the subscription has not been confirmed by then, you will need to resubmit the endpoints to Verizon Connect.

If the message was output to a JSON file, it should appear like this:

"Type" : "SubscriptionConfirmation",
"MessageId" : "165545c9-2a5c-472c-8df2-7ff2be2b3b1b",
"Token" : "2336412f37...",
"TopicArn" : "arn:aws:sns:us-west-2:123456789012:MyTopic",
"Message" : "You have chosen to subscribe to the topic arn:aws:sns:us-west-2:123456789012:MyTopic.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
"SubscribeURL" : "https://sns.us-west-2.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-west-2:12345......",
"Timestamp" : "2012-04-26T20:45:04.751Z",
"SignatureVersion" : "1",
"Signature" : "EXAMPLEpH+DcEwjAPg8O9mY8dReBSwksfg2S7WKQcikcNKWLQjwu6A4VbeS0QHVCkhRS7fUQvi2egU3N858fiTDN6bkkOxYDVrY0Ad8L10Hs3zH81mtnPk5uvvolIC1CXGu43obcgFxeL3khZl8IKvO61GWB6jI9b5+gLPoBc1Q=",
"SigningCertURL" : "https://sns.us-west-2.amazonaws.com/SimpleNotificationService-f3ecfb7224c7233fe7bb5f59f96de52f.pem"

Copy and paste the SubscribeURL value (without quotes) into a browser. For example:

https://sns.us-west-2.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-west-2:12345......

This should confirm your subscription to the GPS Push Service.

Configure GeoEvent Server to process the Verizon Connect Reveal data

Once subscribed, we need to reconfigure the input connector to be able to receive data.

  1. In GeoEvent Manager, click on VerizonConnectReveal-rest-json-in under Inputs.
  2. Change the following parameters:
    • JSON Object Name — data ­
    • GeoEvent Definition (existing) — VerizonConnectReveal-data
    • Ensure all parameters match the ones in the image below:
      Jeff_G_41-1682125507044.png
  3. Click Save to save your changes.

The input connector is now ready to receive data from the Verizon Connect Reveal GPS Push Service.

Mapping event records to a flattened schema

The Verizon Connect Reveal GPS Push Service data contains sub-hierarchies in its data structure. This data is not easily translated to a feature schema that can be used in ArcGIS applications. So, in this case, the GPS Push Service data needs to be mapped to a flattened schema first.

The GeoEvent configuration file included in this guide which includes two GeoEvent Definitions (schemas):

  • VerizonConnectReveal-data – The incoming data from the GPS Push Service from Verizon Connect Reveal
  • VerizonConnectReveal-data-flat – The flattened version of the above schema. The GeoEvent service should use the Field Mapper processor to map to this GeoEvent Definition.

When creating your GeoEvent Service, please ensure you use a Field Mapper processor to map event records to the flattened schema.

Jeff_G_34-1682123441105.png

Jeff_G_35-1682123441109.png

Troubleshooting

Testing the HTTPS endpoint using applications such as Postman or Boomerang

  • If you are unable to receive data from Verizon Connect Reveal and you have confirmed the subscription, then you can use an application such as Postman to send test requests to your configured HTTPS endpoint.
Note: Ensure that you configure the request as a POST with the Authentication set to Basic Authentication. Set the content-type to application/json.
  • Copy the sample JSON data below and paste into the JSON body panel:
{
  "data": {
    "SequenceId": 162517,
    "UpdateUTC": 1614364635000,
    "DeviceTimeZoneOffset": -5,
    "DeviceTimeZoneUseDST": false,
    "DisplayState": "Moving",
    "IsPrivate": false,
    "SpeedKmph": 30,
    "DirectionDegrees": 340,
    "Heading": "North",
    "DeltaDistanceKm": 0.54,
    "OdometerKm": 64853.82300541169,
    "TotalEngineMinutes": 179742,
    "IdleTimeMinutes": 0,
    "Latitude": 35.78075055555556,
    "Longitude": -77.90424,
    "DeltaTimeInSec": 89,
    "SensorBits": 0,
    "geometry": {
      "x": -77.90424,
      "y": 35.78075055555556,
      "spatialReference": {
        "wkid": 4326
      }
    },
    "f": null,
    "token": null,
    "SensorValues": null,
    "Vehicle": {
      "Number": "1234",
      "Name": "Truck1234",
      "VIN": "1ABCDEF567890",
      "ESN": 13000000
    },
    "Address": {
      "AddressLine1": "4020 State Rd 1327, Elm City, NC 27822, USA",
      "AddressLine2": "4020 State Rd 1327",
      "Locality": "Elm City",
      "PostalCode": "27822",
      "AdministrativeArea": "NC",
      "Country": "USA"
    },
    "Driver": {
      "DriverKeyFobId": 0,
      "DriverLastName": "Bond",
      "DriverFirstName": "Jason",
      "DriverNumber": null
    }
  }
}

Gateway Error (502)

Contributors

  • Jeffrey Garcia, Author
  • Morakot Pilouk, Ph.D., Author
VerizonConnectReveal_Config.zip
Related Articles

Working with Verizon Connect Reveal in ArcGIS GeoEvent Server

MorakotPilouk
MorakotPilouk Esri Contributor
4 Kudos
0 Comments