Community
Select to view content in your preferred language

Creating A 'Receive JSON on a REST Endpoint' Input

1652
0
02-20-2019 02:34 PM
EricIronside
by Esri Regular Contributor
Esri Regular Contributor
1 0 1,652
‎02-20-2019 02:34 PM

The input ‘Receive JSON on a REST Endpoint’ can be used to allow external data providers to push events into GoeEvent. As the name implies, the input presents an HTTP transport that implements a REST interface which allows data to be POSTed.  The adapter for this input is the JSON adapter (XML, GeoJSON, and Esri Feature are other adapter options). Any valid JSON structure can be converted by the adapter into events.  This post reviews the various settings and options when setting up this input.  By default, this input expects a POST method will be used to post raw data.  The GET method may be used along with URL parameters (see the Advanced properites settigns below).

 

Setting Properties 

Shown Properties

The following properties should be configured.

  • Name
    • The name of this input (underscores and dashes are ok; you can use spaces, but I avoid them)
    • I typically add to the beginning or end of the default name (e.g. rest-json-in-gps-location or gps-location-rest-json-in)
  • JSON Object Name
    • If blank, the top-level incoming json object (or array of objects) will be converted to a geoevent.
    • If not blank, the incoming json data will be searched for fields with this name, and the contents of those fields will be converted to GeoEvents.
  • Create GeoEvent Definition: True
    • When set to True,
      • a new GeoEvent Definition will be created using the first incoming JSON object as a model
      • See learning mode if the JSON objects vary.
    • When set to False,
      • You must select a GeoEvent Definition to put the incoming JSON objects into.
      • Note that GeoEvent Definitions are case sensitive.
  • GeoEvent Definition Name (New): Generated-GeoEventDefinition
    • A string name for the new GeoEvent Definition
    • If the definition is already created by this input, then that definition is used.

  • GeoEvent Definition Name (Existing)
    • Select from the current list of GeoEvent Definitions known to the system.
    • Data will be marshalled into this GeoEvent definition
    • GeoEvent Definitions are case sensitive.

 

Advanced Properties

The following properties are under the Advanced tab.

  • Default Spatial Reference
    • Specify the default WKID or WKT for geometries that do not contain spatial reference.
    • Or the field that contains the WKID or WKT in each event.
  • Acceptable MIME Types (Server Mode): application/json
    • Comma-separated list of MIME Types that are acceptable to the REST Transport in Server Mode.
    • This input works with JSON so the value is defaulted to application/json
  • Expected Date Format
    • If left empty, the ISO8601 date format is used.
    • Otherwise, the date format is specified in a format string using standard Java conventions:

      y - Year.

      M - Month in year.

      d - Day in month.

      H - Hour in day (0-23).

      h - Hour in am/pm (1-12).

      m - Minute in hour.

      s - Second in minute.

      S - Millisecond.

      z - Time zone (General time zone).

      Z - Time zone (RFC 822 time zone).

      X - Time zone (ISO 8601 time zone).

      a - am/pm marker.

      G - Era designator (AD).

      w - Week in year.

      W - Week in month.

      D - Day in year.

      F - Day of week in month.

      E - Day in week.

      k - Hour in day (1-24).

      K - Hour in am/pm (0-11).

      Y - Week year (2009, 09).

      u - Day number of week (1=Monday,...,7-Sunday).

    • An example of a common date format would be:

      MM/dd/yyyy HH:mm:ss.SSS Z

  • Construct Geometry From Fields: False
    • If set to False, the incoming events will either already have a geometry defined or will not have a geometry.
    • If set to True, the values in the provided fields will be used to create a point geometry.
      • The X and Y Geometry Field parameters are required.
  • X Geometry Field
    • The name of the field that has the X (or Horizontal, or longitude) part of the Geometry
    • This property is required if Construct Geometry is True.
    • This property is case sensitive.
  • Y Geometry Field
    • The name of the field that has the Y (or Vertical, or latitude) part of the Geometry
    • This property is required if Construct Geometry is True.
    • This property is case sensitive.
  • Z Geometry Field
    • The name of the field that has the Z (or Depth or Altitude part of the Geometry).
    • This is optional.
    • If blank the z value will be set to 0
  • Learning Mode: False
    • If False, the schema of the first event will be used to build the GeoEvent Definition.
      • It is assumed the schema of all subsequent events is the same.
      • Additional field values not in the definition will be ignored.
    • If True, the GeoEvent Definition will be enhanced with each new message received.
      • Please notice that the learning mode will alter the GeoEvent Definition so that some of the downstream processes may encounter issues when the GeoEvent Definition is altered.
      • Also, the learning mode should not be used in production as it involves extra overhead.
      • If learning mode is used, you should briefly turn it on until a representative sample set of data has been received, then turn it off.
  • Get Request Contains Raw Data: False
    • This property applies to the Server Mode (Receive Mode) with a client’s Get Request (instead of a post).
    • If False, and a GET method is used to push data,
      • the name-value pairs of request parameters will be converted to JSON.
    • If True, and a GET method is used to push data,
      • The raw data, is assumed to be the value of a single query parameter,
      • The data can be either a JSON String or a CSV string.
      • Only one query parameter will be considered as the raw data.
      • This input assumes the parameter data is JSON.
  • Parameter Name for the Raw Data
    • If the user selects True for Get Request Contains Raw Data then this property defines the name of the URL parameter that contains the JSON data.

Using the Input

Once you set the properties of the input and press the 'Save' button, your REST endpoint will be created. If you re-open the new input you will see the URL property is populated for you.

Please note that either the HTTP or HTTPS format of this URL will work. For example, both of the following should work:

               http://<yourserver>:6180/geoevent/rest/receiver/<inputname>

               https://<yourserver>:6143/geoevent/rest/receiver/<inputname> 

Using your favorite test application, you can use this URL to POST JSON data to your new input.  

  1. Use one of the URLs above and set the method to POST.
  2. Set the header value ‘Content-type’ to ‘application/json’.
  3. Enter some Json into the Raw Body
  4. Press ‘Send’
  5. You should see the counter in GeoEvent for the input increase by 1 on the GeoEvent Manager Monitor page.
  6. If you set the input to create a new GeoEvent, go to GeoEvent Definitions to check and see if it was created correctly.

Other Properties (don't worry about these) 

Hidden Properties

The following properties are hidden or read only and cannot be changed.

  • Mode: Server
    • This setting tells the HTTP transport that it is hosting the end point and should accept REST connections when data is POSTed (pushed).
  • URL: http://yourserver:6180/geoevent/rest/receiver/inputname

               https://<yourserver>:6143/geoevent/rest/receiver/<inputname> 

 

 

Unused/Hidden Properties

The following properties for the transport/adapter are hidden and not used/applicable.

  • Use Long Polling: False
  • Frequency: 5 seconds
  • Receive New Data Only: True
  • Post body MIME Type
  • HTTP Method: Get
  • Header Parameter (name:value list)
  • Post From: Content Body
  • Content Body
  • Post Parameters
  • Parameters
  • URL Proxy
  • Use URL Proxy: False
  • Acceptable MIME Types (Client Mode)
  • HTTP Timeout (in seconds): 30
  • Append to the End of Payload
  • As GeoJson: False
About the Author
Esri Professional Services Real-Time GIS Team GeoEvent Sr. Product Enginner