The Receive XML on a REST Endpoint input connector can be used to receive and adapt event data, formatted as XML, 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 XML on a REST Endpoint input connector:
- Use this input connector to receive data, formatted as generic XML, sent using an HTTP/POST to a GeoEvent Server hosted REST endpoint.
- This input connector pairs the XML inbound adapter with the HTTP inbound transport.
- A typical XML data structure, with event records organized using a hierarchy of XML tags, element, and attribute values, is illustrated above.
- The XML Object Name parameter is used to identify the name of a group element within the XML document structure.
- Data records organized under a specified group element will be handled as separate event records when the grouping element’s name is specified.
- When the XML Object Name parameter is left unspecified, the entire data structure under the XML document’s root element is considered; the schema of event records (in other words, the GeoEvent Definition) will reflect the entire XML document structure. For additional information on XML data structures, see the Esri Community blog XML Data Structures - Characteristics and Limitations.
- Configuring and saving a new input 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 and connect through a port other than 6143.
- A data provider must include, in the header of their HTTP/POST, the MIME type associated with the data being sent.
- The input you configure should specify which MIME types the transport will accept.
- This input connector expects the MIME type application/xml or text/xml, standard MIME types used for the exchange of XML 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 XML in the request’s body and no query parameters. This input connector, however, can also extract event data formatted as generic XML when the data is included as one or more query parameters in an HTTP/GET request’s URL. Use the Parameter Name for the Raw Data option 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, which can be used 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 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 XML on a REST Endpoint input connector:
| Parameter | Description |
|---|---|
Name | A descriptive name for the input connector used for reference in GeoEvent Manager. |
XML Object Name | The name of an XML element used to identify individual data records within a received XML data structure. When XML Object Name is used to specify an XML element by name, the adapter will search for nodes matching the specified name and will only consider those nodes as data records. When left unspecified, which is the default, all data under the uppermost XML root element are considered. |
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. The 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. The 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. |
Acceptable MIME Types (Server Mode) | Specifies the MIME types the input connector will accept. Use commas to separate values, for example: text/plain,application/xml,text/xml. MIME types typically consist of a type/subtype structure and are used when a server is specifying the internet media types of data it will accept from clients. The default is application/xml,text/xml, which are standard for the exchange of XML between a client and server. For more information on official MIME types, see Internet Assigned Numbers Authority (IANA). For more information on the MIME types not used by ArcGIS Server, see MIME types not used by ArcGIS Server. |
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. The 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. The 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. The parameter is shown when Construct Geometry from Fields is set to Yes and is hidden when set to No. |
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 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 the following:
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 pattern so GeoEvent Server knows how the date/time values should be adapted. |
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. 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 your 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 your inbound data. Learning mode can then be turned off and the automatically generated GeoEvent Definition copied and tailored for production deployment. |
Parameter Name for the Raw Data (Conditional) | The name of the query parameter whose value provides the raw data for inbound HTTP/GET requests. The query parameter’s value should be a single string formatted as generic XML. When client applications use HTTP/POST requests to send data, this property should be left blank. The content body of the HTTP/POST request is assumed to contain the XML formatted data. |