Overview

A PubNub Function that uses ArcGIS services to implement realtime geofence triggering behaviour.

Features

• Serverless architecture using ArcGIS Online and PubNub cloud solutions.
• PubNub Function for realtime geofence-based entry and exit triggering.
• Secure communication between PubNub Function and ArcGIS Online.
• Extensible to suit your needs.

Prerequisites

• Free ArcGIS Developer account.
• Free PubNub account.

Behavior

The PubNub Function requires an ArcGIS polygon feature service that represents geofences, and a point feature service that represents asset locations.

Passing an asset ID and its current location to the PubNub Function will return whether the asset has entered or exited any geofences since the last call. It will also update the asset's location record with the new location (and current geofence information).

Instructions

Follow the Set Up steps below to get your PubNub function and ArcGIS Online services operating together.

The default insructions cover the simple case. For custom configuration of fields for tracking asset locations and geofences, see the Customization section

Set up

There are 3 components to set up:

1. ArcGIS Online Services
2. ArcGIS Online OAuth Application
3. PubNub Function

Get started with a simple setup:

1. Publish ArcGIS Online Services

1. Sign in at www.arcgis.com.

2. Publish the SimpleGeofencing.sd Service Definition to your ArcGIS Online account. Browse to your "My Content" tab. Select Add Item > From my computer and upload the file, ensuring the Publish this file as a hosted layer checkbox is selected.

3. Once published, you will be redirected to the new service's Portal Item page. Make a note of the Service URL for the UserLocations and Geofences layers on the new published service (be sure to remove the ?token=... from the end of each URL).

2. Create ArcGIS Online OAuth Application

1. Browse to your "My Content" tab and select Add Item > An application, and select the Application radio button. Fill in the fields.

2. Under the Settings tab of the new Application, click the Registered Info button in the Application Settings panel. Make a note of the App ID and App Secret values.

3. PubNub Function

1. Create a new PubNub Function with the contents of the location-geofencing.js file.

2. Update the assetsURL and the geofencesURL consts with the URLs noted in Step 1 for UserLocations and Geofences respectively. Be sure not to include any URL parameters. The URLs should end in /0 or /1 for the samples provided.

3. Update the clientID and clientSecret consts with the App ID and App Secret noted in Step 2.

That's it. You can now Start your PubNub Function and begin using it.

Editing Geofences

There is no specific tool provided with this sample to edit the geofences, however you can use the ArcGIS Online Map Viewer to create, edit and delete geofences.

To do this, navigate to the Portal Item page created when the service was published in Step 1.3, expand the drop down Open in Map Viewer and pick Add layer to new map with full editing control. For instructions on how to edit the data, see here.

Customization

The Geofences service must include a unique ID field. This can be system-managed (such as the default OBJECTID field that ArcGIS Online creates) or a custom ID field.

The Asset Locations service must include two fields. A unique ID field, and a string field to store Geofence IDs. This latter field is used to determine whether an updated location represents a move into or out of a geofence.

By default, the SimpleGeofencing.sd Service Definition makes use of the OBJECTID fields. These are integer IDs for each location and geofence. Often you will want to use your own IDs. The CustomGeofencing.sd shows an example of this where the assets are Users and their IDs are email addresses. To set it up:

1. Follow Step 1 above to publish the CustomGeofencing.sd instead of the SimpleGeofencing.sd.
2. Follow Step 3 to configure the PubNub function. You can reuse the same application from Step 2.
3. Customize the geofenceIDField, assetIdField and assetLastKnownFencesField consts in the PubNub Function to reference the custom location and geofence tracking fields:

Variable	Field Name
geofenceIDField	FenceID
assetIdField	UserID
assetLastKnownFencesField	LastGeofenceIDs

Note: While the custom service still uses OBJECTID as row identifiers, the geofencing logic uses other fields to track the geofencing. This is useful if fences and asset locations are related to records coming from other systems.

For reference, the above variable configuration table would look like this for the SimpleGeofencing service definition:

Variable	Field Name
geofenceIDField	OBJECTID
assetIdField	OBJECTID
assetLastKnownFencesField	LastKnownGeofences

The most important thing here is to understand how many geofences a location can be within at any one time. If the geofences do not overlap, that number is 1. The assetLastKnownFencesField field must be long enough to contain the IDs (read from the geofenceIDField field) of all the geofences a location can be in at once, with commas between them.

Note: The sample data creates two layers within a single service. This is by no means a requirement. For example, if the layers are created using the New Layer developer tool, each will belong to a separate service.

Sample Data

The two sample Service Definitions include 1 asset and 3 geofences each. The geofences are in Manhattan at Union Square, Gramercy Park, and the dog park at Union Square. Since the Dog Park is within Union Square, the geofences could potentially overlap. The asset is a User.

The test user ID is:

• SimpleGeofencing: 1
• CustomGeofencing: jackdoe@awesomecorp.com

To test entering and exiting the fences, use the following payloads in your PubNub Function Editor (modify the asset values as appropriate depending on whether you're using the SimpleGeofencing layers or the CustomGeofencing layers):

• Gramercy Park:

   {
   	"asset": "1",
   	"lat": 40.73795,
   	"lng": -73.98688
   }

• Union Square:

   {
   	"asset": "1",
   	"lat": 40.73709,
   	"lng": -73.9902
   }

• Union Square Dog Park

   {
   	"asset": "1",
   	"lat": 40.7356,
   	"lng": -73.991
   }

• No Geofence

  {
  	"asset": "1",
  	"lat": 40.73836,
  	"lng": -73.9899
  }

Test each of those payloads and see how the JSON output of the PubNub function describes the geofences that were entered and exited.

If you're using the CustomGeofencing, instead the payload should look like this:

• Gramercy Park:

   {
   	"asset": "jackdoe@awesomecorp.com",
   	"lat": 40.73795,
   	"lng": -73.98688
   }

etc.

Contributing

Anyone and everyone is welcome to contribute. We do accept pull requests.

1. Get involved
2. Report issues
3. Contribute code
4. Improve documentation

Licensing

Copyright 2017 Esri

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

A copy of the license is available in the repository's license.txt file.