Skip navigation
All Places > GIS > Enterprise GIS > GeoEvent > Blog > 2017 > May
2017
This article is the second of two articles examining enhancements made to the HTTP transport for the GeoEvent Server 10.5 release. This article examines the outbound transport. The previous article examining the inbound transport can be found here.

 

In this article, I would like to provide detail for an enhancement made to the HTTP outbound transport for the GeoEvent Server 10.5 release. The following capability is listed on the What's new in ArcGIS GeoEvent Server web help page:

  • HTTP outbound transport now supports field value substitutions in the HTTP GET mode

 

Beginning with the 10.5 product release, an output leveraging the HTTP transport can be configured to substitute event attribute values into the URL of a request GeoEvent Server will send to an external server. The attribute values are incorporated as query parameters (as opposed to the request’s content body).

The new capabilities of the HTTP transport will be described below with exercise steps you can follow to demonstrate the capabilities.

~~~

When you want to send data from event records to an external server or application you typically configure an outbound connector – such as the Push JSON to an External Website output. GeoEvent Server will incorporate the event data into the content body of a REST request and send the request to the external server as an HTTP/POST. This capability has been available in the last several releases.

A device on the edge of the Internet of Things, however, might prefer to receive requests with event data organized as query parameters rather than in a request's content body. This way the entire data payload is in the URL of the request -- leaving the content body of the request empty.

It might seem a little odd for a GeoEvent Server output, which is not intended to receive or process any type response, to make an HTTP/GET request. But the capability was introduced to enable GeoEvent Server to issue activation requests to devices which require data values be sent using query parameters.

~~~

Exercise 2A – Use HTTP/GET to send event data as query parameters to an external server

 

Why exactly are we configuring a custom outbound connector?

How's it different than the the Push JSON to an External Website connector available out-of-the-box?

 

For this exercise:

  1. Configure the following GeoEvent Server output connector.
    Browse to Site > GeoEvent > Connectors and select to create a new outbound connector. Default values for the "Shown", "Advanced", and "Hidden" properties are included beneath the illustration.


     

    Shown PropertiesDefault Value
    URL[ no default value defined ]

     

    Advanced PropertiesDefault Value
    Use URL ProxyFalse
    URL Proxy[ no default value defined ]
    HTTP Timeout (in seconds)30

     

    Hidden PropertiesDefault Value
    Formatted JSONFalse
    MIME Typetext/plain
    Acceptable MIME Typestext/plain
    Post/Put body MIME Typetext/plain
    Parameters[ no default value defined ]
    Header Parameter Name:Value List( blank )
    HTTP MethodGet
    ModeClient
  2. Save your newly configured custom outbound connector.
  3. Navigate to Services > Outputs and select to create a new (Custom) HTTP/GET request with event data as query parameters output. Configure the output as illustrated below, replacing yourServer and yourDomain with a valid server and domain for your organization.


    Note the URL specified in the illustration:

    https ://yourServer.yourDomain/server/rest/services/SampleWorldCities/MapServer/0/query?where=city_name='${Origin}'&f=json

    The format of the URL assumes that an ArcGIS web adapter (named 'server') has been configured and that an external server or client application receiving this URL could use it to query the "Sample World Cities" map service on your ArcGIS Server. GeoEvent Server will substitute the variable ${Origin} in the URL's query parameter with an actual attribute value from a received event record, enabling the external server or client application to make a more specific query based on real-time events.
     
  4. Save your updated output, then publish a GeoEvent Service which incorporates your output and an input of your choice. You can use any type of input, so long as the GeoEvent Definition associated with event records received by the input includes an attribute field named Origin.

    Queries through a web adapter to a Portal secured web service from an unauthenticated source will return an error. Since the Sample World Cities web service is secured by Portal in my current deployment, I expect the request made by GeoEvent Server will generate an error. In order to complete the demonstration we will use the GeoEvent Server's debug logs to confirm that the output has constructed a valid query and sent the request to the ArcGIS Server map service.
  5. Navigate to the Logs page in GeoEvent Manager. Click 'Settings' and enable DEBUG logging for the feature service outbound transport logger (com.esri.ges.transport.http.HttpOutboundTransport).
  6. Send an event record to your GeoEvent Server input whose Origin attribute is the name of one of the cities in the Sample World Cities map service (e.g. Chicago). Refresh the Logs page in GeoEvent Manager and you should see log messages with information similar to the following:

 

The first message shows that 'Chicago' was indeed substituted into the query parameters by the GeoEvent Server output and a request was made. The error may or may not be displayed; as indicated above, the map service in my case is Portal secured and this request did not include a token authenticating the request.

 

There are a couple of things you'll want to keep in mind. The URL you use to configure the the output must URL Encode its query parameters to make them HTTP safe. But the value is being substituted by GeoEvent Server is based on a string received from a real-time data source. This means you may have some work to do to make sure that "San Francisco" is represented as San%20Francisco not San Francisco before an event record is sent to an output.

 

Also, the enhancement being introduced in this article was designed specifically for HTTP/GET since those requests do not include a JSON payload in the request’s body. However, some rudimentary testing suggests that you can use HTTP/POST as well; I suppose it would be up to the external server receiving the request whether or not to honor an HTTP/POST and either ignore the request’s JSON payload or potentially consider its content in addition to the values in the query parameter.

 

Finally, you do have some freedom in how the request’s query string is specified. For example, you could construct a parameterized string something like; GeoEvent Server will handle the substitution of the multiple parameter values:

query?where=city_name+IN+%28%27${CityA}%27%2C%27${CityB}%27%29&f=json

 

If you send the string highlighted above through an HTML decoder you'll see that it is equivalent to:

where=city_name IN ('${CityA}','${CityB}')&f=json

 

I hope these two blogs were helpful.  Please comment below with questions and I'll do my best to answer them.

 

-- RJ

This article is the first of two articles examining enhancements made to the HTTP transport for the GeoEvent Server 10.5 release. This article examines the inbound transport. The second article examining the outbound transport can be found here.

 

In this article, I would like to provide detail for an enhancement made to the HTTP inbound transport for the GeoEvent Server 10.5 release. The following capability is listed on the What's new in ArcGIS GeoEvent Server web help page:

  • HTTP inbound transport now accepts GET requests in the query parameters

 

Beginning with the 10.5 product release, an input leveraging the HTTP transport can be configured to support an external server or application which incorporates its data payload in the URL of the request (as opposed to the request’s content body).

The new capabilities of the HTTP transport will be described below with exercise steps you can follow to demonstrate the capabilities.

~~~

When you want to receive event records as an HTTP/POST request from an external server or application you typically configure an inbound connector – such as the Receive JSON on a REST Endpoint input. GeoEvent Server will create a REST endpoint to which the external server can post its event data with the event data included in the content body of the request. This capability has been available in the last several releases.

A device on the edge of the Internet of Things, however, might prefer to organize the event data as query parameters and incorporate its data payload in the URL of the request -- leaving the content body of the request empty. For example:

  • http :// localhost:6080/geoevent/rest/receiver/http-receiver?field1=v1&field2=v2&field3=v3
  • http :// localhost:6080/geoevent/rest/receiver/http-receiver?data=v1,v2,v3

Beginning with the 10.5 product release an input pairing either the out-of-the-box JSON or TEXT adapter with the HTTP inbound transport can be configured to support the use cases above with an HTTP/GET request.

~~~

Exercise 1A – Use HTTP/GET requests to send event data to GeoEvent Server as query parameters

  1. Create the following GeoEvent Definition

  2. Configure the following GeoEvent Server input connector


    Note the new 10.5 parameter:  Get Request Contains Raw Data

    Review the help tip provided for this parameter. If the inbound connector is running in SERVER mode and receives an HTTP/GET request, if the request content body is empty and the request URL includes query parameters, the default (‘No’) will consider each name/value pair as a separate attribute value in an event record. If the default is changed to ‘Yes’ you will be expected to specify the one query parameter which will be considered the event’s raw data.

  3. Configure a GeoEvent Server output connector and publish a GeoEvent Service

    You can use any outbound connector which supports JSON event record displays. Recommended output connectors are ‘Send Features to a Stream Service’ or ‘Write to a JSON File’.




  4. Send the following HTTP/GET request to your input connector’s endpoint

    http://yourServer.yourDomain:6180/geoevent/rest/receiver/rest-json-in?fname=Robert&lname=Lawrenson&employee_id=123

 

You should observe the event count of your ‘Receive JSON on a REST Endpoint’ input increment as HTTP/GET requests are made on your input’s REST endpoint

~~~

Exercise 1B – Explore HTTP/GET requests whose query parameters include comma delimited values

Rather than incorporating the event data into a series of key/value pairs, the event data can be conveyed using a single query parameter whose value is a set of comma delimited values. The delimited text values will require an inbound connector which leverages the TEXT adapter (rather than the JSON adapter used in the previous exercise).

GeoEvent Server does not include a “Receive TEXT on a REST Endpoint” inbound connector out-of-the-box, so you will need to configure one for this exercise.

  1. Configure the following GeoEvent Server input connector.
    Browse to Site > GeoEvent > Connectors and select to create a new inbound connector. Default values for the "Shown", "Advanced", and "Hidden" properties are included beneath the illustration.



    Shown PropertiesDefault Value
    Event Separator\n (newline)
    Field Separator, (comma)
    Incoming Data Contains GeoEvent DefinitionFalse
    Create Unrecognized Event DefinitionsFalse
    Create Fixed GeoEvent DefinitionsFalse
    GeoEvent Definition Name (New)[ no default value defined ]
    GeoEvent Definition Name (Existing)[ no default value defined ]
    Language for Number Formatting[ no default value defined ]

    Advanced PropertiesDefault Value
    Acceptable MIME Types (Server Mode)text/plain
    Expected Date Format[ no default value defined ]
    Build Geometry From FieldsFalse
    X Geometry Field[ no default value defined ]
    Y Geometry Field[ no default value defined ]
    Z Geometry Field[ no default value defined ]
    Well Known Text Geometry Field[ no default value defined ]
    wkid Geometry Field[ no default value defined ]
    Get Request Contains Raw DataTrue
    Parameter Name for the Raw Datadata

    Hidden PropertiesDefault Value
    ModeServer
    Use Long PollingFalse
    Frequency (in seconds)[ no default value defined ]
    Receive New Data OnlyFalse
    Post/Put body MIME Type[ no default value defined ]
    HTTP MethodGet
    Header Parameter Name:Value List( blank )
    Post/Put FromParameters
    Post/Put Parameters( blank )
    Content Body[ no default value defined ]
    Parameters[ no default value defined ]
    URL[ no default value defined ]
    URL Proxy[ no default value defined ]
    Use URL ProxyFalse
    Acceptable MIME Types (Client Mode)[ no default value defined ]
    HTTP Timeout (in seconds)30
    Append to the End of Payload[ no default value defined ]
  2. Save your newly configured custom inbound connector.
  3. Navigate to Services > Inputs and select to create a new (Custom) Receive TEXT on a REST Endpoint input.
    Configure the input as illustrated below. Use the GeoEvent Definition you created for the last exercise.


  4. Publish a GeoEvent Service which incorporates your newly configured input and any outbound connector which supports JSON event record displays. You can use the outputs configured for the previous exercise if you wish.
  5. Send the following HTTP/GET request to your input connector’s endpoint (note the endpoint's name has changed):

    http://yourServer.yourDomain:6180/geoevent/rest/receiver/custom-receive-text-rest-in?data=Robert,Lawrenson,123

 

You should observe the event count of your ‘(Custom) Receive TEXT on a REST Endpoint’ input increment as HTTP/GET requests are made on your input’s REST endpoint.

~~~