Example: Exporting data in Esri geocoding integrations

You can select the outbound HTTP post scheme to export data from your IBM® Maximo® Real Estate and Facilities database to an Esri server. Then, you can map the response parameters from the HTTP request to your location records to update their geocodes.

Background

Ichiro is an integration specialist at Company ABC. He develops Maximo Real Estate and Facilities integrations for the customers of Company ABC.

Ichiro is developing an outbound HTTP post integration with an external Esri geocoding service. For the Esri geocoding service to determine which addresses to geocode, the HTTP request must contain specific parameters in the query string. The response is in JSON format. The following HTTP URL provides Esri geocoding services through the REST API:

http://geocode.arcgis.com/arcgis/rest/services
  /World/GeocodeServer/findAddressCandidates

Ichiro remembers that since the latitude and longitude values for building records are being stored in the Maximo Real Estate and Facilities database, the HTTP URL must also contain specific parameters for Esri authentication. To refresh his memory, he visits Authenticate a request to the World Geocoding Service (https://developers.arcgis.com/rest/geocode/api-reference/geocoding-authenticate-a-request.htm). He uses his Client ID and Client Secret credentials to generate his unique Esri authentication token that is contained in the query string of the HTTP request. The following HTTP URL contains the required forStorage and token parameters and parameter values:

http://geocode.arcgis.com/arcgis/rest/services
  /World/GeocodeServer/findAddressCandidates?forStorage=true
  &token=Z43nqkyXY48Kx1iiPgCCZsh7Kf7ZxsKSH4xEO2Q8x34wiHU8wysAljsRzzYI51eg-
  zAr114CR0vgQ6fUt5a4eatD9FGejE4w8hTBY-f5vy5v1asxh_rXvLZsw6upiRPU

Step 1: Define the integration data scheme

Ichiro defines the integration object record with the following field details:

Name

Geocode Address

Scheme

Http Post

Direction

Outbound

Post Type

Query String

Response Type

JSON

Http URL

http://geocode.arcgis.com/arcgis/rest/services
  /World/GeocodeServer/findAddressCandidates?forStorage=true
  &token=Z43nqkyXY48Kx1iiPgCCZsh7Kf7ZxsKSH4xEO2Q8x34wiHU8wysAljsRzzYI51eg-
  zAr114CR0vgQ6fUt5a4eatD9FGejE4w8hTBY-f5vy5v1asxh_rXvLZsw6upiRPU

Query For Outbound section: Is Dynamic?

Yes

Step 2: Define the data map

Since Ichiro selected a dynamic query, he defines the data map by specifying the Location module, triBuilding business object, triBuilding form, and fields. The External field attribute values represent the parameter names that are added to the query string. Since the Default field attribute is not used, the field data is dynamically pulled from the Maximo Real Estate and Facilities location records. He defines the following fields with the following External attribute values:

triAddressTX: Address
triZipPostalTX: ZIP
triCityTX: City
triStateProvTX: State

For two more fields, Ichiro defines two more External values to specify the corresponding Default values that are required by the Esri geocoding service. His External values are outSR for the WKID and f for the format. His corresponding Default values are 102100 for the WKID and json for the format. To verify his 102100 value, he checks the WKID values for the geographic coordinate system (resources.arcgis.com/en/help/rest/apiref/gcs.html) and the projected coordinate system (resources.arcgis.com/en/help/rest/apiref/pcs.html). He defines the following fields with his External and Default attribute values:

triIdTX: outSR and 102100
triDescriptionTX: f and json

Ichiro saves the data map.

Step 3: Define the response map

Next, Ichiro defines the response map to retrieve the response from the Esri geocoding service and map the retrieved latitude and longitude values to the Maximo Real Estate and Facilities location record. He defines the response map by specifying the Location module, triBuilding business object, triBuilding form, and fields. Since the response is in JSON format, the External attribute values are in JSONPath syntax. He defines the following fields with the following External attribute values:

triGisLongitudeNU: candidates[0].location.x
triGisLatitudeNU: candidates[0].location.y

Ichiro saves the response map and saves the integration object record.

Step 4: Execute the integration definition

When Ichiro selects the Execute form action to start the integration definition, the following process occurs:

The data map values are used to construct a dynamic query. The query is called.

Because the post type is a query string, each result from the query is transformed into the following URL structure:

http://geocode.arcgis.com/arcgis/rest/services 
  /World/GeocodeServer/findAddressCandidates?forStorage=true
  &token=Z43nqkyXY48Kx1iiPgCCZsh7Kf7ZxsKSH4xEO2Q8x34wiHU8wysAljsRzzYI51eg-
  zAr114CR0vgQ6fUt5a4eatD9FGejE4w8hTBY-f5vy5v1asxh_rXvLZsw6upiRPU
  &Address=6720+Via+Austi+Pkwy&ZIP=89119&City=Las+Vegas
  &State=Nevada&outSR=102100&f=json

The actual parameters depend on the actual Maximo Real Estate and Facilities data.

The following JSON object shows the response:

{
	"spatialReference": {
		"wkid":102100,"latestWkid":3857 
	},
	"candidates": [{
		"address":"6720 Via Austi Pky, Las Vegas, NV, 89119",
		"location": {
			"x":-12819684.945332458,
			"y":4309927.0270621451
		},
		"score":100,
		"attributes": {

		}
	},
	{
		"address":"6720 Via Austi Pky, Las Vegas, NV, 89119",
		"location": {
			"x":-12819744.862808136,
			"y":4309924.3334144857
		},
		"score":100,
		"attributes": {

		}
	},
	{
		"address":"6721 Via Austi Pky, Las Vegas, NV, 89119",
		"location": {
			"x":-12819808.664131654,
			"y":4309995.0691041043
		},
		"score":79,
		"attributes": {

		}
	},
	{
		"address":"Via Austi Pky, Las Vegas, NV, 89119",
		"location": {
			"x":-12819804.948472099,
			"y":4309871.0261052754
		},
		"score":100,
		"attributes": {
	
		}
	}]
}

The response map values are used to extract candidates[0].location.x and candidates[0].location.y from the JSON object and map them to the triGisLongitudeNU and triGisLatitudeNU fields in the Maximo Real Estate and Facilities location record. The location record is updated with the new data.
Since no action was specified for the exported data in the Query for Outbound section, no actions are triggered on the location data.
The final count of the integration process is collected and an execute history record is created with the details about the integration run and any errors that occurred.