The Watch a Folder for New JSON Files Input Connector can be used to read and adapt event data, formatted as generic JSON, from a system file. For examples illustrating how ArcGIS GeoEvent Server expects typical generic JSON data records to be formatted please refer to the Esri Community blog JSON Data Structures - Working with Hierarchy and Multicardinality.
When multiple event data records are specified in a generic JSON file, organize them in an array as illustrated below. The Generic JSON Inbound Adapter will handle each object in the array as a separate event record. The JSON illustrated below will be adapted to produce three individual event data records for a GeoEvent Service to process.
Usage notes
- Use this input connector to read event data, formatted as generic JSON, from a system file and adapt it to create event data records for processing.
- This input connector pairs the Generic JSON Inbound Adapter with the File Inbound Transport.
- The input connector watches the specified system folder and will read an entire file as soon as the file appears in the folder.
- The entire file’s content will be reread if changes are made to the file and are saved.
- All files in a watched folder will be reread, from the beginning of the files, if:
- The input connector’s properties are updated and saved.
- The input connector is stopped and restarted (or the ArcGIS GeoEvent Server service is restarted).
- A generic JSON record does not have to contain data which represents a geometry.
- The adapter supports the ability to construct a point geometry from X, Y, and Z attribute values.
- The registered server folder Input Folder Data Store can be specified using either an absolute path or UNC path. If a UNC path is used, the Windows service account running GeoEvent Server needs read/write permission to the folder.
- As a best practice, use absolute paths, for example C:\GeoEvent\input, for the Input Folder Data Store property.
- The Input Directory allows a subfolder relative to the registered server folder to be specified.
- Include Subfolders allows you to specify whether folders beneath the Input Folder Data Store should be searched recursively. Oftentimes, organizing data with different schemas into different folders, and changing Include Subfolders from its default to disable recursive search, allows a more direct and simpler configuration of this input connector.
- This input connector includes a Learning Mode which can be useful when you need to allow the input connector to modify a GeoEvent Definition it has constructed. The purpose of this property is to temporarily accept that event data received will have a variable schema or data structure. The input connector will use a sample of received data records to learn more about the variable data structure and append new, previously unobserved, attribute fields to an existing GeoEvent Definition.
Allowing a GeoEvent Definition to be changed on-the-fly can negatively impact the design of real-time analytics in a GeoEvent Service. As a best practice, it is recommended that if schema variance is expected in your inbound event data that you use Learning Mode for as brief a period of time as possible to produce a GeoEvent Definition which supports all expected variants of your inbound data. Learning mode can then be turned off and the auto-generated GeoEvent Definition copied and tailored for production deployment.
- Network latency can adversely impact the ability for GeoEvent Server to retrieve high volumes of event data.
Parameters
| Parameter | Description |
|---|---|
Name | A descriptive name for the input connector used for reference in GeoEvent Manager. |
Input Folder Data Store | The registered system folder beneath which files will be found. |
Input Directory | A subfolder directly beneath the registered system folder. Input Directory should be left blank if a subfolder beneath the registered system folder does not exist. |
Input File Filter | A regular expression pattern used to identify files appropriate for this input to ingest and adapt to create event data records for processing. The default is .*\.json which matches any filename (.*) ending with the literal suffix (.json). While this property is not required and can be left blank, it is recommended you specify a pattern which matches the file name of any file whose schema matches the GeoEvent Definition this input has been configured to use and exclude files (by name) which you do not want the input to ingest. |
Default Spatial Reference | The well-known ID (WKID) of a spatial reference to be used when a geometry is constructed from attribute field values whose coordinates are not latitude and longitude values for an assumed WGS84 geographic coordinate system, or geometry strings are received that do not include a spatial reference. A well-known text (WKT) value or the name of an attribute field containing the WKID or WKT may also be specified. |
Include Subfolders | Specifies whether subfolders beneath the Input Folder Data Store and Input Directory (optional) for files. The default is Yes, however, organizing data with different schemas into different folders and changing this property to No, to disable recursive search, allows a simpler configuration.
|
Delete Files After Processing | Specifies whether the files in the registered system folder will be deleted after their content has been processed. Note that even if a file's content cannot be adapted, no event records are created, and no real-time event processing occurs, the inbound transport will still delete a file whose contents were successfully read. The default is No.
Files not deleted will be reread, from the beginning of the file, if the input connector's properties are changed and saved or if the input is stopped and restarted, for example, if the ArcGIS GeoEvent Server service is restarted. |
Create GeoEvent Definition | Specifies whether a new or existing GeoEvent Definition should be used for the inbound event data. A GeoEvent Definition is required for GeoEvent Server to understand the inbound event data attribute fields and data types.
|
GeoEvent Definition Name (New) (Conditional) | The name assigned to a new GeoEvent Definition. If a GeoEvent Definition with the specified name already exists, the existing GeoEvent Definition will be used. The first data record received will be used to determine the expected schema of subsequent data records, a new GeoEvent Definition will be created based on that first data record's schema. Property is shown when Create GeoEvent Definition is set to Yes and is hidden when set to No. |
GeoEvent Definition Name (Existing) (Conditional) | The name of an existing GeoEvent Definition to use when adapting received data to create event data for processing by a GeoEvent Service. Property is shown when Create GeoEvent Definition is set to No and is hidden when set to Yes. |
Expected Date Format | The pattern used to match expected string representations of date/time values and convert them to Java Date values. The pattern's format follows the Java SimpleDateFormat class convention. This property has no default value. While GeoEvent Server prefers date/time values to be expressed in the ISO 8601 standard, several string representations of date/time values commonly recognized as date values can be converted to Java Date values without specifying an Expected Date Format pattern. These include:
If the date/time values received are expressed using a convention other than one of the five shown above, you will have to specify an Expected Date Format so GeoEvent Server knows how the date/time values should be adapted. |
Construct Geometry from Fields | Specifies whether the input connector should construct a point geometry using coordinate values received as attributes. The default is No.
|
X Geometry Field (Conditional) | The attribute field in the inbound event data containing the X coordinate part (for example horizontal or longitude) of a point location. Property is shown when Construct Geometry from Fields is set to Yes and is hidden when set to No. |
Y Geometry Field (Conditional) | The attribute field in the inbound event data containing the Y coordinate part (for example vertical or latitude) of a point location. Property is shown when Construct Geometry from Fields is set to Yes and is hidden when set to No. |
Z Geometry Field (Conditional) | The name of the field in the inbound event data containing the Z coordinate part (for example depth or altitude) of a point location. If left blank, the Z value will be omitted and a 2D point geometry will be constructed. Property is shown when Construct Geometry from Fields is set to Yes and is hidden when set to No. |
JSON Object Name | The name of a JSON element which can be used as the root node of a substructure within the received JSON data. When JSON Object Name is used to specify a JSON element by name, the adapter will search for substructures whose object name matches the specified element name. Only data within the identified substructure will be considered. When left blank, which is the default, the uppermost JSON object is used as the root of the entire JSON structure. |
Learning Mode | Specifies whether Learning Mode is active or disabled. When learning mode is set to Yes, the inbound adapter will append new fields to a GeoEvent Definition it has created and is maintaining.
Learning Mode can be useful when you need to allow the input connector to modify a GeoEvent Definition it has constructed. The purpose of this property is to temporarily accept that event data received will have a variable schema or data structure. The input connector will use a sample of received data records to learn more about the variable data structure and append new, previously unobserved, attribute fields to an existing GeoEvent Definition. |
Is the File Text | Specifies whether the file is text based or in a binary format. The default is Yes.
|
Max Number of Lines per Batch (Conditional) | The maximum number of lines to read from the file in each batch or interval. The default is 1000 lines. Reduce this value if each event record contains many attributes to limit the amount of data sent to the Text Adapter as a batch. Property is shown when Is the File Text is set to Yes and is hidden when set to No. |
Batch Flush Interval (milliseconds) (Conditional) | The number of milliseconds to wait before reading another batch of lines from the file. The default is 500. Reduce this value if file size is expected to be very large and/or additional time is necessary to process each batch of lines retrieved from a file. Property is shown when Is the File Text is set to Yes and is hidden when set to No. |
Number of Lines to Skip from Start of File (Conditional) | The number of lines to skip from the start of the file. The default is 0. Increase this value if you want a skip a specific number of lines, for example header lines specifying attribute field names or data types, because they do not contain actual data for processing. Property is shown when Is the File Text is set to Yes and is hidden when set to No. |
As GeoJSON | Specifies whether to parse the incoming geometry as a GeoJSON geometry object rather than as feature JSON. The default assumes that when a geometry is received as a string, the value will be feature JSON as described in Geometry objects.
Refer to the GeoJSON specification for valid and complete examples of GeoJSON geometry object formats. A single GeoJSON geometry object is assumed to have a member with the name coordinates whose value is an array. The structure of the array is determined by the type of geometry. |