The GeoTagger Processor is used to enrich an event record with the name of an area of interest, also known as a geofence, with which the event record's geometry has a spatial relationship. The processor is unique in that it performs event enrichment and spatial filtering. For example, you can configure the processor to append the names of any geofences an event record's geometry is found to be inside. Event records processed by the GeoTagger Processor will have a field appended to it that contains the names of any geofences in which its geometry is found.
Examples
The following are example uses of the GeoTagger Processor:
- The processor can be used to keep an ongoing record of city blocks that have been patrolled by parking enforcement officers in real time. As officers patrol different city blocks over the course of a shift, a record can be kept of which blocks were visited and by which officer.
- The processor can be used to geotag parcels with the names of active wildfires impacting them. As a wildfire grows in surface area, impacted parcels can be geotagged with the name of the wildfire currently impacting them.
- The processor can be used to monitor a hurricane for its impact on affected counties. As the hurricane intersects the counties, the hurricane’s event record can be enriched with a list of geotagged counties impacted.
Usage notes
Keep the following in mind when working with the GeoTagger Processor:
- The GeoTagger Processor uses the event record's geometry and one or more geometries registered as geofences. A regular expression can be used to specify several different geofences and enrich an event record with the names of the geofences the event record's geometry is inside or intersects.
- Geofences must be imported into GeoEvent Server from a feature service prior to configuring the GeoTagger Processor. For more information about working with geofences in GeoEvent Server, see Manage geofences.
- When configuring a GeoTagger Processor, select a spatial operator to specify the relationship that must be satisfied for the processor to tag an event record. For example, you may want to enrich event records by tagging them with the name of any geofence an event record's polygon intersects.
- The processor will emit an event record for each event record it receives. When an event record's geometry satisfies the spatial relationship the processor is evaluating, the names of relevant geofences are written to the specified target field. If an event record's geometry does not satisfy the spatial relationship the processor is evaluating for any identified geofence, a null value will be appended to the GeoTag field value.
- The GeoTagger Processor supports a range of spatial operators including Contains Any, Crosses Any, Disjoint Any, Enter Any, Equals Any, Exit Any, Inside Any, Intersects Any, Outside Any, Overlaps Any, Touches Any, and Within Any. The spatial operators assume any geofence being considered, which satisfies the operator's defined spatial relationship, is enough to trigger the GeoTagger Processor to enrich the GeoEvent being processed. For example, if the Intersects Any spatial operator is used, and several dozen geofences modeling non-overlapping areas of interest are being considered, the name of any geofence whose area intersects a GeoEvent's geometry would be added to that processed GeoEvent.
- When specifying the name of the field containing an event data’s geometry, the GeoTagger Processor will accept either the name of the field or a tag (typically the GEOMETRY tag) applied to a field in the GeoEvent Definition.
- The processor alters the event record’s schema, which requires GeoEvent Server to create a new GeoEvent Definition. The new GeoEvent Definition will be managed by GeoEvent Server and deleted if changes are made to the processor or the GeoEvent Service in which the processor is used.
- The processor provides three options for formatting the enriched values. Delimited Value specifies geofence names that should be written as a simple comma-separated list. The other two, Group and List, format the enriched values as a JSON group or as elements in a JSON list.
- The Geometry Field parameter displays the name of every field in every GeoEvent Definition that has a type geometry. When selecting the geometry field by name, it is important to choose the name of the geometry field that corresponds to the event data’s GeoEvent Definition.
Parameters
The following are the parameters for the GeoTagger Processor:
| Parameter | Description |
|---|---|
|
Name |
A descriptive name for the processor used for reference in GeoEvent Manager. |
|
Processor |
Specifies the processor selected. |
| Geofences | The category and name of the geofence registered with GeoEvent Server. The geofences are evaluated for their spatial relationship with the inbound event data. The processor supports regular expressions, allowing multiple geofences in a category or multiple categories to be specified. The required format is category/name, specified as a pair of regular expression patterns, for example:
Note:Regular expressions are used for both the category and the name. For example, Campus/.* is used to include all geofences in the Campus category for geotagging. The expression .*/.* includes all geofences. The Geotagger Processor supports dynamic substitution. For example, an event record with an attribute target_area can be used to in an expression like Campus/${target_area} to name an area. Remember, regular expression pattern matches are case-sensitive. Note:Multiple geofence category/name expressions cannot be specified as a comma separated list. For example, specifying Countries/France, Countries/Germany cannot be used to specify the geofences France or Germany. Note:Regular expressions are used for both the category and the name. The expression .*/.* includes all geofences in all categories. Remember, regular expression pattern matches are case-sensitive. |
| Spatial Operator | The spatial operator to use for geotagging. The spatial operator defines how geofences are spatially evaluated in relationship to the event data. The default is Contains Any. The available spatial operators include the following:
|
| Geometry Field | The name of the geometry field or the GEOMETRY tagged field in the inbound event data. The processor uses the event data’s geometry to evaluate the spatial relationship with geofences for geotagging. |
| Target Field | The target field to write the geotagged values. The default is Existing Field.
Note:When the processor is configured to write to a new field, data written to the specified field can be formatted as either delimited values or as a JSON group or JSON list. When configured to write to an existing field, the names of the geofences that satisfy the spatial relationship the processor is evaluating are appended to the existing field's value as delimited text. The option to enrich the processed event record with geofence names formatted as a JSON group or JSON list is not supported when writing to an existing field. |
| Geotag Field Name (Conditional) | The name of the new field that stores the geotagged values. The parameter is shown when Target Field is set to New Field and is hidden when set to Existing Field. |
| Geotag Format (Conditional) | The format of the geotagged values in the GeoTag field. Geotagged values can be formatted as a comma-separated list, a JSON group, or as a JSON list. The default is Delimited Value.
The parameter is shown when Target Field is set to New Field and is hidden when set to Existing Field. |
| New GeoEvent Definition Name (Conditional) | The name assigned to the new GeoEvent Definition. The new GeoEvent Definition will combine the schema of the inbound event record with the new GeoTag field containing the geotagged values. The parameter is shown when Target Field is set to New Field and is hidden when set to Existing Field. |
| Existing Field Name (Conditional) | The name of the existing field from the event record used to store the geotagged values. The existing field must be a string to receive the geotagged values. Note:Use the Definition menu to identify the GeoEvent Definition of the inbound event data. Choosing a GeoEvent Definition will limit the available fields to choose from. Use the Field menu to identify the specific name of the existing field where the geotagged values will be stored. The parameter is shown when Target Field is set to Existing Field and is hidden when set to New Field. |
| Include Geofence Category in Geotag | Specifies whether to include the geofence category in the geotagged values. The default is Yes.
|
Considerations and limitations
There are several considerations to keep in mind when using the GeoTagger Processor:
- It is common to think of a geofence as modeling an area of interest, implying that geofences are always polygon geometries. A geofence could also be a point or polyline geometry, as the list of supported spatial operators implies. A polygon geometry associated with an event record could be tested to see whether it intersects, crosses, or contains a geofence whose geometry is a point or polyline.
- Consider the geometry of the geofences and the geometry of the event record when setting the Spatial Operator parameter. Certain spatial operators may be invalid given the type of geometries involved. For example, the Contains Any spatial operator cannot be used if the event record is a point and the geofence is a polygon. A point cannot contain a polygon. For more information on spatial relationships, see Spatial filters.