GeoEvent Server: Geofence Best Practices
Over the course of the last six months I have been configuring and managing a GeoEvent Server, specifically Geofences. I have learned a lot of about configuring them and how and when to use them efficiently. I felt compelled to share this with the community, to help others who are new to working with Geofences to get started. Here are the best practices I use to manage and work with Geofences effectively.
What are Geofences
A “geofence” is a geometry that GeoEvent Server uses to identify a geometry of interest. Configurable filters and processors added to GeoEvent Services use geofences to determine if geometry associated with an event record shares a spatial relationship with one or more secondary geometries or “geofences”.
Geofences are organized in categories; within each category every geofence must have a unique name. It is natural to think of geofences as areas modeled using polygon features, but geofences do not have to represent polygonal areas. GeoFences can, in fact, model any of the basic types of geometry exposed through a feature service: point, multipoint, polyline, or polygon.
Event records received for processing typically have an associated geometry. When designing and publishing a GeoEvent Service, the filters and/or processors you configure can test to see if a particular spatial relationship returns ‘true’ or ‘false’. For example, assuming you have imported a set of geofences from polygon feature records, you can use a filter to retain (allow to pass) any event record whose associated geometry (a point) is INSIDE, OUTSIDE, ENTERING, EXITING a specified set of geofences. You can also buffer an event record’s point geometry and test to see if the area surrounding the point INTERSECTS, OVERLAPS, or is DISJOINT from a specified set of geofences.
When importing feature records as new geofences only the feature record’s geometry is imported along with a single attribute which is used as a unique name for the geofence. You must select an attribute, usually a String field, the import can use to uniquely name each geofence being imported. If no other suitable attribute field exists, you can use the OBJECTID to uniquely identify geofences.
When specifying the category into which geofences should be imported you can select an attribute field or manually key in a string value to “hard code” the category name. The category name is technically not part of the geofence – it is used to organize geofences into groups.
It is important to recognize that the general attributes associated with a feature record are not included with a GeoEvent Server geofence. Geofences only have a name and a geometry.
This is by design; geofences are intentionally very lightweight. A feature record may include a rich set of attributes describing its features, but maintaining all this attribute information in-memory along with the geofence geometry would impact event record processing and throughput.
When importing geofences from feature records, work to make the feature record geometries as simple as possible. Complex, multipart geometries with many thousands of vertices tend to negatively impact event record processing and throughput.
Also, because geofences are maintained in-memory, you should avoid importing thousands of geofences with complex geometries (many thousands of vertices) because the complex geometry will consume more RAM. This is often the case with features whose boundaries include river or ocean coastlines.
Geofence Spatial Reference
When importing geofences from feature records, GeoEvent Server must establish a common spatial reference for all imported geofences. This simplifies the in-memory organization and allows geofence retrieval to be optimized. GeoEvent Server retains the spatial reference of the first geofence loaded until the product’s configuration is reset and the GeoEvent Server Service is restarted.
When importing geofences you’ll notice the Import Geofences panel defaults a property WKID to 4326, the well-known identifier of the WGS 1984 geographic coordinate system. This can be changed – and should be changed – if the feature record geometries you are importing use a projected coordinate system and you expect coordinates or geometries associated with event records you will receive to be expressed in same projected coordinate system. If the default is left unchanged, GeoEvent Server will have to perform on-the-fly projections to place received event records and geofences in the same spatial reference before evaluating a spatial condition or relationship.
Filters and processors can be configured with a spatial expression (INTERSECTS, DISJOINT, ENTER, EXIT, etc.) which consider one or more geofences. The specification of a set of geofences to consider is done using a pair of regular expressions.
The first expression refers to the geofence category and selects any category name by matching any character ‘.’ any number of times ‘*’. The second expression refers to the geofence names within a category and selects any named geofence by again matching any character ‘.’ any number of times ‘*’.
- .*/.* considers every geofence in every category
- CategoryName / .* considers every geofence in the category ‘Arizona’ (Arizona/.*)
- CategoryName /GeoFenceName considers only the geofence ‘Maricopa’ in the category ‘Arizona’ (Arizona/Maricopa)
Geofence Synchronization Using Feature Services
In addition to a one-time import used to establish geofences in GeoEvent Server’s in-memory catalog, you can periodically synchronize GeoEvent Server’s geofences by configuring a synchronization rule to point to a feature service.
You should not both conduct a one-time import and configure a synchronization rule to update the same set of geofences in a specified geofence category. The geofences you explicitly import (one-time) will take precedence and will never be updated by the synchronization. If you want to switch to begin synchronizing geofences, first select all the geofences in the target category and explicitly delete them.
The synchronization rules you configure will periodically query a feature service for feature records and use the feature records from the query to update the in-memory geofences. Each synchronization rule should have a unique name. Synchronization rules run asynchronously and are independent of the rate or frequency of event record ingest.
You should consider geofence synchronization only when you know that feature records you want to use to model geofences are dynamic and synchronize as infrequently as possible. Keep in mind that querying a feature service for feature records and applying those feature records to add and update geofences does not happen instantaneously. If your GeoEvent inputs and services are busy ingesting and processing event data during the time a synchronization is occurring, spatial relationships may be evaluated incorrectly.
Geofence Synchronization Using Stream Services
The best way to handle highly dynamic feature records to use a stream service to broadcast the feature data and configure your synchronization rule to subscribe to the stream service (rather than to periodically poll a feature service). This tends to minimize the latency between discovery that a feature record has changed and the need to update the corresponding geofence.
Geofence Properties: Active Field
When importing geofences, either one-time or using a synchronization rule, there are a few properties you can use to control whether a geofence will be considered by a filter or processor.
When importing (or synchronizing) geofences, use the ‘Active Field’ property to select an appropriate String attribute whose value will specify whether an individual geofence is Active/True or Active/False. You can also accept the property’s default ‘Always Active’ which will import every geofence as “active”.
- String values "true", "y", "yes", "on", and "1" evaluate as Active/True.
- String values "false", "n", "no", "off", and "0" evaluate as Active/False.
- The string comparisons are case insensitive.
Geofences are not often set Active/False, but the setting can be useful for some real-time analytics. When a geofence is Active/False it will not be considered by a filter or processor. This is important because if a spatial expression cannot be proven true, it will evaluate as false.
For example, if none of the known geofences are set to Active/True, a DISJOINT evaluation will return FALSE even if an event record’s geometry does not intersect any known geofence. There is no active geofence to provide a geometry against which the event’s geometry can be compared, so the spatial relationship cannot be proven true.
Geofence Properties: Time Extent Start, Time Extent End
When importing geofences, either one-time or using a synchronization rule, it is possible to establish a temporal extent during which a geofence will be considered by a filter or processor.
When importing (or synchronizing) geofences, use the ‘Time Extent Start’ and ‘Time Extent End’ properties to select an appropriate Date attribute whose value will specify the date/time a geofence is “effective from” and the date/time the geofence is “effective until”. If no suitable Date attribute field exists, you can use a long integer attribute whose value represents epoch milliseconds (GMT).
When an event record arrives at a filter or processor, geofences whose “effective from” date/time is greater than the date/time associated with the event record are excluded from spatial relationship tests performed by the filter/processor. Likewise, geofences whose “effective until” date/time is less than an event record’s associated date/time are excluded from spatial evaluations.
The date/time associated with an event record is determined by the attribute field tagged TIME_START.
If no event record attribute field has been tagged TIME_START (or TIME_END) an internal property (the time the event was created by an input’s adapter) may be used to associate a date/time with the event record to determine if the event falls within a geofence’s temporal extent.
If no known geofence shares a temporal intersection with an event record no spatial relationship will be considered – and if a spatial relationship cannot be proven true the filter or processor evaluating the relationship will assume the relationship is FALSE. When setting geofence ‘Time Extent Start’ and ‘Time Extent End’ property values, it is important to know when geofences and event records being received temporally intersect with one another.
Another reason to be aware of the ‘Time Extent Start’ and ‘Time Extent End’ properties of geofences is that GeoEvent Server, by default, is actively considering the geofences in its in-memory catalog and deleting those geofences whose ‘Time Extent End’ is sometime in the past relative to the server’s clock.
When importing geofences, either one-time or via synchronization, only features whose date/time is less than the specified ‘Time Extent End’ (according to the server’s clock) are included in the in-memory catalog. This prevents geofences which have already “expired” from taking up unnecessary memory.
Geofence Properties: GeoSync Filter Field
When configuring geofence synchronization, it is possible to limit which feature records are returned by the synchronization rule’s query. Use the ‘GeoSync Filter Field’ to select an appropriate Date attribute (or other integer) whose value can be incorporated into a WHERE clause by the synchronization rule.
The synchronization rule will consider feature records returned by its query, caching the greatest value from the set of returned features, so that when the next query is executed only feature records whose attribute value is greater-than or equal-to the cached value from the last synchronization cycle are used to update geofences in the in-memory catalog.
You should only use the ‘GeoSync Filter Field’ when many thousands of feature records could potentially be considered for geofence update – and the majority of those feature records have not actually changed since the last synchronization. This property is one way to optimize geofence synchronization and is not appropriate in all workflows.
- Every geofence must have a unique name.
- Every geofence is associated with a category (used to group geofences).
- Geofences only consist of a name and a geometry; attributes associated with a feature record used as the source of a geofence are not imported along with the geofence.
- Before importing geofences from feature records:
- Simplify the feature record geometries to minimize RAM consumption and allow spatial relationships to be more efficiently evaluated.
- Project your feature record geometries to match the spatial reference of the event records you plan to ingest.
- Choose to either establish geofences using a one-time import or synchronize your geofences using a synchronization rule – never both.
- A pair of regular expressions are used to specify which geofences a filter or processor will consider when determining if a spatial relationship exists.
- When a spatial condition cannot be proven true, it is assumed to be false.
- Set geofence “active”, “effective from”, and “effective until” values with care.
- Avoid inadvertently excluding geofences from spatial relationship evaluations.
- Geofence synchronization is not instantaneous.
- Real-time analytics run as geofences are being updated may return unexpected results.
- Consider using stream services to “push” geofence updates to the in-memory catalog to reduce the number of feature records and the latency associated with catalog updates.
- Use the ‘GeoSync Filter Field’ to limit the number of feature records returned when a synchronization rule is used to poll a large feature service.