The Receive JSON on a WebSocket Input Connector can be used to receive and adapt event data, formatted as generic JSON, on a WebSocket hosted by ArcGIS GeoEvent Server. Given a standard GeoEvent Server configuration, clients should expect to subscribe and send data to an endpoint formatted as wss://<machine_name>.<domain>:6143/path where path is the value specified as the input connector's URL Path property.
This input connector runs as a server in order to allow client applications to subscribe and send data to GeoEvent Server. If you are looking for an input connector which runs as a client and subscribes to receive data broadcast from a server's WebSocket, consider using Subscribe to an External WebSocket for JSON.
Usage notes
- Use this input connector to receive data, formatted as generic JSON, via a WebSocket hosted by GeoEvent Server.
- This input connector pairs the Generic JSON Inbound Adapter with the WebSocket Inbound Transport.
- This input connector runs as a server and provides a WebSocket to which client applications can subscribe to send data to GeoEvent Server.
- The adapter interprets generic JSON as opposed to feature JSON or GeoJSON. Note that GeoJSON and feature JSON are both variants of generic JSON; different GeoEvent Server adapters are used to process those specific formats.
- For additional information on JSON structures, see the Esri Community blog JSON Data Structures - Working with Hierarchy and Multicardinality.
- Typical event data, organized in a JSON array, is illustrated above.
- The adapter will handle both single JSON records and JSON records organized in an array.
- 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.
- Both the WebSocket (ws) and WebSocket Secure (wss) protocols are supported by this connector.
- Clients wishing to send data to the WebSocket endpoint should use ws://<machine_name>.<domain>:6180/path.
- 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.
Parameters
| Parameter | Description |
|---|---|
Name | A descriptive name for the input connector used for reference in GeoEvent Manager. |
URL Path | A complete URL endpoint includes a protocol, hostname or IP address, port and path. This connector expects only the path of the URL to be specified. The default is /ws. The complete URL clients will use to subscribe will resemble: ws://<machine_name>.<domain>:6180/path or wss://<machine_name>.<domain>:6143/path For example, if the URL Path were specified as /SampleRecords, clients sending data to the WebSocket Secure URL would use wss://PS000123.esri.com:6143/SampleRecords (for a machine named PS000123 on the esri.com domain). |
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. Parameter 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. Parameter is shown when Create GeoEvent Definition is set to No and is hidden when set to Yes. |
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. |
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. |
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 parameter 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. Parameter 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. Parameter 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. Parameter is shown when Construct Geometry from Fields is set to Yes and is hidden when set to No. |
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 parameter 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. |