Receive JSON on a REST Endpoint

The Receive JSON on a REST Endpoint input connector can be used to receive and adapt event data, formatted as generic JSON, on a REST endpoint hosted by ArcGIS GeoEvent Server. Given a standard GeoEvent Server configuration, data providers should expect to send data through HTTP/POST to an endpoint formatted as https://<machine_name>.<domain>:6143/geoevent/rest/receiver/name in which name is the name of the configured input connector.

Usage notes

Keep the following in mind when using the Receive JSON on a REST Endpoint input connector:

• Use this input connector to receive data, formatted as generic JSON, sent using an HTTP/POST to a GeoEvent Server hosted REST endpoint.
• This input connector pairs the Generic JSON inbound adapter with the HTTP inbound transport.
• A typical block of generic JSON is illustrated above. This example organizes three event records in an array.
• The adapter will handle each object in an array as a separate event record.
• 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.
• Configuring and saving a new Receive JSON on a REST Endpoint input connector creates a GeoEvent Server hosted REST endpoint.
• You can recover the fully qualified path to the GeoEvent Server hosted REST endpoint by editing the input after it has been saved.
• GeoEvent Server can be configured to use a different base URL for its REST receiver or connect through a port other than 6143.
• A data provider must include, in the header of their HTTP/POST, the MIME type associated with data being sent.
• The input you configure should specify which MIME types the transport will accept.
• This input connector expects the MIME type application/json, which is a default MIME type for the exchange of JSON between a client and server.
• The adapter supports the ability to construct a point geometry from x, y, and z attribute values.
• The transport will accept both HTTP/GET and HTTP/POST requests. A data provider is typically expected to make an HTTP/POST request to send event data to GeoEvent Server with JSON in the request’s body and no query parameters. This input connector, however, can also extract event data formatted as generic JSON when the data is included as one or more query parameters in an HTTP/GET request’s URL. Use the Get Request Contains Raw Data parameter to use this capability. For more information, see the Esri Community blog Enhancements to the GeoEvent Server HTTP Inbound Transport.
• This input connector includes a Learning Mode parameter, which can be used 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.

  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 the learning mode for as brief a period of time as possible to produce a GeoEvent Definition that supports all expected variants of your inbound data. The learning mode can then be turned off and the autogenerated GeoEvent Definition will be copied and tailored for production deployment.

Parameters

The following are the parameters for the Receive JSON on a REST Endpoint input connector:

Parameter	Description
Name	A descriptive name for the input connector used for reference in GeoEvent Manager.
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 when 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 can also be specified.
JSON Object Name	The name of a JSON element that 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 searches for substructures whose object name matches the specified element name. Only data within the identified substructure is considered. When left blank, which is the default, the uppermost JSON object is used as the root of the entire JSON structure.
Create GeoEvent Definition	Specifies whether a new or an existing GeoEvent Definition is used for the inbound event data. A GeoEvent Definition is required for GeoEvent Server to interpret the inbound event data attribute fields and data types. Yes—A new GeoEvent Definition is created based on the schema of the first event record received. No—No GeoEvent Definition is created. Choose an existing GeoEvent Definition that matches the schema of the inbound event data.
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 is used. The first data record received is used to determine the expected schema of subsequent data records, and a new GeoEvent Definition is created based on that first data record's schema. This parameter is shown when Create GeoEvent Definition is set to Yes and is hidden when it's 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. This parameter is shown when Create GeoEvent Definition is set to No and is hidden when it's 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 when 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 can also be specified.
Acceptable MIME Types (Server Mode)	Specifies the MIME types the input connector accepts. Use commas to separate values, for example, text/plain,application/xml,text/xml. MIME types typically consist of a type and subtype structure and are used when a server must specify the internet media types of data it accepts from clients. The default is application/json, which is the official MIME type for the exchange of JSON between a client and a server. For more information about official MIME types, refer to Internet Assigned Numbers Authority (IANA). For more information about the MIME types not used by ArcGIS Server, refer to MIME types not used by ArcGIS Server.
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. While the preferred pattern for date/time values in GeoEvent Server is 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 value. These include the following: "2019-12-31T23:59:59"—The ISO 8601 standard format 1577836799000—Java Date (epoch long integer; UTC) "Tue Dec 31 23:59:59 -0000 2019"—A common web services string format "12/31/2019 11:59:59 PM"—A common format used in the United States (12-hour clock) "12/31/2019 23:59:59"—A common format used in the United States (24-hour clock) If the date/time values received use a convention other than one of those listed above, you must specify an expected date format pattern so GeoEvent Server can adapt the date/time values.
Construct Geometry from Fields	Specifies whether the input connector will construct a point geometry using coordinate values received as attributes. The default is No. Yes—Values from specified event attribute fields are used to construct a point geometry. No—No point geometry is constructed. It is assumed that an attribute field contains a value that can be interpreted as a geometry or the event record is nonspatial (does not have a geometry).
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. This parameter is shown when Construct Geometry from Fields is set to Yes and is hidden when it's 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. This parameter is shown when Construct Geometry from Fields is set to Yes and is hidden when it's set to No.
Z Geometry Field (Conditional)	The attribute field in the inbound event data containing the z-coordinate part (for example, depth or altitude) of a point location. If no value is provided, the z-value is omitted, and a 2D point geometry is constructed. This parameter is shown when Construct Geometry from Fields is set to Yes and is hidden when it's set to No.
Learning Mode	Specifies whether Learning Mode is active or unavailable. When Learning Mode is set to Yes, the inbound adapter appends new fields to a GeoEvent Definition it has created and is maintaining. Yes—Learning mode is active. The GeoEvent Definition is updated with new fields from event records sharing different schemas. No—Learning mode is unavailable. The GeoEvent Definition is not modified. 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 has a variable schema or data structure. The input connector uses a sample of received data records to identify 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 adversely impact the design of real-time analytics in a GeoEvent Service. If schema variance is expected in the inbound event data, it is recommended that you use Learning Mode for as brief a period of time as possible to produce a GeoEvent Definition that supports all expected variants of the inbound data. Learning mode can then be turned off and the automatically generated GeoEvent Definition copied and tailored for production deployment.
Get Request Contains Raw Data	Specifies how the connector handles data included in received HTTP requests. Raw data can be sent as the value of a single query parameter using an HTTP/GET request when Parameter Name for the Raw Data specifies the query parameter’s name. Otherwise, an HTTP/GET request must include several query parameters whose names correspond to attribute fields specified in the GeoEvent Definition the connector has been configured to use. This connector uses the Generic JSON inbound adapter; consequently, when the single query parameter form is used, its value must be formatted as generic JSON. Ensure that the request’s content body is empty when using HTTP/GET requests to send data. Data is normally sent using an HTTP/POST request without any query parameters. The request’s payload is expected to be formatted as generic JSON with the event data included in the request’s content body. Any data included in the request’s query parameters is ignored when using HTTP/POST to send event data to GeoEvent Server. Yes—Assume that HTTP/GET requests are received, and extract event data from a specified query parameter. Only one query parameter can be considered as the source of the request’s raw data, and the request’s content body should be empty. No—When HTTP/POST requests are received, ignore any query parameters, and extract event data from the request’s content body (which should be formatted as generic JSON). When HTTP/GET requests are received, the request’s content body should be empty, and event data should be extracted from several query parameters whose names correspond to the GeoEvent Definition being used.
Parameter Name for the Raw Data (Conditional)	The name of the query parameter whose value provides the raw data for inbound HTTP/GET requests. Format the query parameter’s value as a single string generic JSON. This parameter is shown when Get Request Contains Raw Data is set to Yes and is hidden when it's set to No.