In Geovonic Connect, data sources provide connectivity to third-party business systems. The Generic HTTP Web Service data source allows you to fetch real-time data from any web service following the prescribed interface specification.

For example, the Generic HTTP Web Service data source allows you to build your own web services that can be accessed using the Geovonic Connect widget and feature layers.

Overview

When a user selects one or more features on the map, the attributes and geometry of the features are passed to your web service. The web service is responsible for adding additional related data to the features and returning it to Geovonic Connect.

For example, a user might select an asset feature on the map. Your web service adds information about the maintenance record of the selected feature. Geovonic Connect then displays the maintenance records on the map widget without the user having to leave the map.

Details of the interface specification (data formats) is provided below.

Data Source Configuration

The Generic HTTP Web Service data source configuration requires a few fields: –

• Web Service URL – the full URL of the web service.
• HTTP Method – the HTTP method to use when calling the web service. Note that the feature data will always be sent in the request body regardless of your selected HTTP method.
• HTTP Headers (Optional) – an optional list of headers to include on the web service call. For example, an authorisation header could be included with the call.

Layer Link Configuration

The layer link configuration describes the relationship between the map features and your related records. Choose the attributes and/or geometry that are required to be passed to your web service.

• Attribute List – The list of feature attributes required by your web service. Use the [+] button to choose from a drop-down of available attributes. The list of attributes should be separated by spaces. Your chosen attributes must include a unique index field for the features (for example, OBJECTID or FID) allowing Geovonic Connect to link the returned data to the correct features.
• Include Geometry – Check this box if your web service requires the feature geometry to be included in the request. The geometry will not be included on the web service call if not checked.
• Additional HTTP Headers (Optional) – an optional list of headers to include on the web service call. These headers will be added to the any headers defined on the data source configuration. Headers with the same name will be overwritten by the values in the layer link configuration.

Interface Specification

Request

Geovonic Connect sends a request to your web service with a JSON body. The JSON object includes two top-level attributes: –

• features – An array of feature objects representing each of the selected map features. Each feature object includes the attributes selected in the Layer Link Configuration, and the geometry if the Include Geometry option is selected.
• fields – A hint describing the list of fields that the web map widget is requesting. Each record returned from your web service should include the requested fields. If your web service returns more fields than requested, the excess fields will be removed by Geovonic Connect before being returned to the user. If your web service returns a nested object, the field names will be described using dot.notation. For example, { address: { line1: "613 King St" } } would be listed as address.line1.

{
  "features": [
    {
      "feature": {
        "attributes": {
          // Attributes based on the attributeList layer link property
          "FID": "1",
          "STOP_ID": "123"
        },
        "geometry": { ... } // Included only if isGeometryRequired is true
      }
    },
    // ... more features
  ],
  "fields": [ // Array of field names to be returned
    "address.line1", "status", "lastAuditDate"
  ]
}

Where requested, the geometry uses the ArcGIS geometry object format.

Response

The web service is responsible for adding related records to the selected map features. The web service adds a records array to each of the features passed in by Geovonic Connect. The records array can continue zero to many records for each feature. The rest of the response should be returned exactly as passed in by Geovonic Connect – modifying the attributes or geometry is not allowed.

Your web service must return a 2XX HTTP status code. Any non-2XX response will be classified as an error.

{
  "features": [
    {
      "feature": {
        "attributes": {
          // DO NOT CHANGE THE ATTRIBUTES
          // MUST BE RETURNED AS IS
        },
        "geometry": // Included if isGeometryRequired is true
      },
      "records": [
        {
          "fieldA": "valueA",
          "fieldB": "valueB"
          // ...
        }
      ]
    },
    // ... more features
  ]
}

Each object in the features array is returned as [ { feature: {}, records: [] } ] where feature is the original feature object passed by Geovonic Connect and records is the data being returned by your web service.

One feature can return many records. For example, the maintenance history for an asset might contain multiple entries.