Create Address Lookup integration

This article will show how to create an address lookup integration using ArcGIS

ArcGIS allows us to search for addresses for free, but once we save an address into our database, we need to consume a credit, which is a paid-for service.

Description

ArcGIS exposes several REST baseAPIs. We will be configuring two integrations, one to search for the address and one for fetching the address and consuming a credit.

1. Variables

We want to store the inbound an outbound requests for both the Search and Save APIs so that we can consume them during execution. For this, we need to create some Integration Variables

From within the ProcessFactorial Portal, browse to the Integrations Tab, click on Variables and click New

Create each of the following variables

Name	Description	Data Type	Sample JSON
Forms Address Search Request	Request send to ArcGIS	JSON	{}
Forms Address Search Response	Response back from ArcGIS	JSON	{"suggestions":[{"isCollection":false,"magicKey":"dHA9MCN0dj0xZWJkOWY4YiNsb2M9NzIxMzA5MTkjbG5nPTQxI2xicz0xMDk6OTI3MjY2MjcjbG49V29ybGQ=","text":"Main Street N, Ōhingaiti, Manawatu-Wanganui, 4785, NZL"}]}
Forms Address Save Request	Request sent to ArcGIS	JSON	{}
Forms Address Save Response	Response back from ArcGIS	JSON	{"candidates":[{"address":"Main Drain Road, Glen Oroua, Manawatu-Wanganui, 4473","attributes":{"Address":"Main Drain Road","City":"Glen Oroua","Country":"NZL","District":"","Postal":"4473","Region":"Manawatu-Wanganui","SubRegion":"Manawatu"},"extent":{"xmax":175.412615611711,"xmin":175.410615611711,"ymax":-40.331319790187,"ymin":-40.333319790187},"location":{"x":175.411615611711,"y":-40.332319790187},"score":100}],"spatialReference":{"latestWkid":4326,"wkid":4326}}

2: The Search API Integration Workflow

The Suggest api provided by ArcGIS allows us to search for an address:

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest

Integration Service Definition

From within the ProcessFactorial Portal, browse to the Integrations Tab, click on Service Definitions and click New

Fill in the following details

Field	Purpose	Example Value
Name	A friendly name to identify this integration	Forms Address Lookup - Search Addresses
Description	A one paragraph description on this integration	Look up addresses via ArcGIS
Message Exchange Pattern	Because we want to call an API and receive data back, set this to Two Way	Two Way
Integration Verb	GET, PUT, POST, DELETE, etc	GET
Base URL		Fixed Value and "https://geocode.arcgis.com"
Path		Fixed Value and "/arcgis/rest/services/World/GeocodeServer/suggest"
Headers		No headers are needed for this specific integration
Query Parameters	Some of these parameters are pre-configured (Type = Value) and others are dynamic (Type = Caller Input)	see Query Parameters for Search API below
Sample Output JSON	This particular address endpoint does not take a request body, so we provide an empty JSON object {}. The Sample Output JSON Tree will automatically update.	{}

Query Parameters for Search API

Name	Data Type	Type	Value	Comments
f	String	Fixed Value	pjson	Default value required by ArcGIS
category	String	Fixed Value	Address	Default value required by ArcGIS
maxSuggestions	String	Fixed Value	10	Default value required by ArcGIS. Specifies how many addresses to return during the search. 10 is an optimal number
text	String	Caller Input	search	This field will be dynamically updated on the ProcessFactorial Form. The label 'search' is the name of the parameter that we will use on the Form Event
sourceCountry	String	Caller Input	country	This field will be dynamically updated on the ProcessFactorial Form The label 'country' is the name of the parameter that we will use on the Form Event

Integration Workflow

From within the ProcessFactorial Portal, browse to the Integrations Tab, click on Integration Workflows and click New

Fill in the following details

Field	Purpose	Example Value
Name	A friendly name to identify this integration workflow	Forms Integration Workflow - Address Search
Description	A one paragraph description on this integration	Search for addresses via ArcGIS
Input Parameters	These are the input parameters into the Integration Workflow, that we will capture from the ProcessFactorial form	see Input Parameters below

Input Parameters

Name	Data Type	Type	Value	Comments
Street Text	String	Caller Input		Search string for the address being searched for
Country Text	String	Caller Input		ISO2 code for the country where the address is being searched for

In the canvas that opens after creating the Integration Workflow, add the following Actions by clicking on the + icon

Create Integrate Action

Field	Purpose	Example Value
Name	A friendly name to identify this action	Execute Search Integration
Description	A one paragraph description on this integration	Executes the Search Integration Service
Service Definition	The Integration Service that will be executed	Select the Forms Address Lookup - Search Addresses Service Definition from above. This will auto-create the Query Parameters
Sample Outbound Message	There is no request JSON object required for ArcGIS, so an empty JSON object is all we need	{}
Store Outbound Request in	The outbound request is stored in a variable we created earlier	Forms Address Search Request
Store Outbound Response in	The inbound response is stored in a variable we created earlier	Forms Address Search Response

For each of the Query Parameters, map them to an Integration Workflow Parameter as in the below table

Name	Source Type	Source
text	Integration Workflow Parameter	Street Text
sourceCountry	Integration Workflow Parameter	Country Text

Create Return Data Action

In the canvas that opens after creating the Integration Workflow, add the following Actions by clicking on the + icon after the Integrate action from above

Field	Purpose	Example Value
Name	A friendly name to identify this action	Return Search Integration Data
Description	A one paragraph description on this integration	Return Search Integration Data to the ProcessFactorial Form
Message to be returned	What type of message should be returned	New Message

In the Messages section, add a new message with the following values

Field	Purpose	Example Value
Name	A friendly name to identify this action	Return Data Address
Caller Type	What type of service will consume this integration response	Form
Value	A sample output that will be consumed by the caller	{"id":"formPayload","keyFieldName":"key","referenceRecordsJSON":[{"key":"somekey1","value":"Some Value 1"},{"key":"somekey2","value":"Some Value 2"}],"valueFieldName":"value"}

Once the new Action is saved, right click it and select Configure.

On the dialog, expand the "Root (Object)" section, then for each of the fields, map them to the value that is returned by ArcGIS. This is done by adding a new Map Field Action

Name	Source Type	Source	Select Source Context
id	Fixed Value		id
keyFieldName	Fixed Value		key
referenceRecordJSON	Stored Variable	Forms Address Search ResponseForms Address Search Response	Two different Field Mapping Actions: key = root -> suggestions -> [0] -> magicKey value = root -> suggestions -> [0] -> text
valueFieldName	Fixed Value		value

This is an example for key

TODO: Missing Context on the form to map the array location of referenceRecordJSON

The final canvas should look something like this:

3: The Save Address API

The Find Address Candidates api provided by ArcGIS returns the full address object in its parts, such as line 1, line 2 and city, and consumes a paid-for credit from ArcGIS

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

Creating the Integration Service Definition

From within the ProcessFactorial Portal, browse to the Integrations Tab, click on Service Definitions and click New

Fill in the following details

Field	Purpose	Example Value
Name	A friendly name to identify this integration	Forms Address Lookup - Save Addresses
Description	A one paragraph description on this integration	Fetch single address details to save. Also consume quota
Message Exchange Pattern	Because we want to call an API and receive data back, set this to Two Way	Two Way
Integration Verb	GET, PUT, POST, DELETE, etc	GET
Base URL		Fixed Value and "https://geocode.arcgis.com"
Path		Fixed Value and "/arcgis/rest/services/World/GeocodeServer/findAddressCandidates"
Headers		No headers are needed for this specific integration
Query Parameters	Some of these parameters are pre-configured (Type = Value) and others are dynamic (Type = Digital Journey Form)	see Query Parameters for Save Address API below
Sample Output JSON	This particular address endpoint does not take a request body, so we provide an empty JSON object {}. The Sample Output JSON Tree will automatically update.	{}

Query Parameters for Save Address API

Name	Data Type	Type	Value	Comments
f	String	Value	pjson	Default value required by ArcGIS
outFields	String	Value	Address,District,City,SubRegion,Region,Postal,Country	List of fields to be returned in the repsonse
maxLocations	String	Value	1	Maximum number of locations to be returned in the response
langCode	String	Value	EN	Language for the returned results
magicKey	String	Caller Input	key	This field will be dynamically updated on the ProcessFactorial Form. The label 'key' is the name of the parameter that we will use on the Form Event

Integration Workflow

From within the ProcessFactorial Portal, browse to the Integrations Tab, click on Integration Workflows and click New

Fill in the following details

Field	Purpose	Example Value
Name	A friendly name to identify this integration workflow	Forms Integration Workflow - Address Save
Description	A one paragraph description on this integration	Save a single selected address via ArcGIS
Input Parameters	These are the input parameters into the Integration Workflow, that we will capture from the ProcessFactorial form	see Input Parameters below

Input Parameters

Name	Data Type	Type	Value	Comments
Address Key	String	Caller Input		Magic Key that ArcGIS uses as the unique identifier for a specific address

In the canvas that opens after creating the Integration Workflow, add the following Actions by clicking on the + icon

Create Integrate Action

Field	Purpose	Example Value
Name	A friendly name to identify this action	Execute Save Integration
Description	A one paragraph description on this integration	Executes the Save Integration Service
Service Definition	The Integration Service that will be executed	Select the Forms Address Lookup - Save Addresses Service Definition from above. This will auto-create the Query Parameters
Sample Outbound Message	There is no request JSON object required for ArcGIS, so an empty JSON object is all we need	{}
Store Outbound Request in	The outbound request is stored in a variable we created earlier	Forms Address Save Request
Store Outbound Response in	The inbound response is stored in a variable we created earlier	Forms Address Save Response

For each of the Query Parameters, map them to an Integration Workflow Parameter as in the below table

Name	Source Type	Source
magicKey	Integration Workflow Parameter	Address Key

Create Return Data Action

In the canvas that opens after creating the Integration Workflow, add the following Actions by clicking on the + icon after the Integrate action from above

Field	Purpose	Example Value
Name	A friendly name to identify this action	Return Save Integration Data
Description	A one paragraph description on this integration	Return Save Integration Data to the ProcessFactorial Form
Message to be returned	What type of message should be returned	New Message

In the Messages section, add a new message with the following values | Field | Purpose | Example Value | | ------------------------------------ | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | Name| A friendly name to identify this action | Return Full Address| | Caller Type| What type of service will consume this integration response| Form| | Value | A sample output that will be consumed by the caller| {"address":"address","city":"city","district":"district","latitude":0,"line1":"line1","longitude":0,"postcode":"postcode","region":"region","subregion":"subregion"}|

Once the new Action is saved, right click it and select Configure.

On the dialog, expand the "Root (Object)" section, then for each of the fields, map them to the value that is returned by ArcGIS. This is done by adding a new Map Field Action

Name	Source Type	Source	Select Source Context
address	Stored Variable	Forms Address Save Response	root -> candidates -> [0] -> address
city	Stored Variable	Forms Address Save Response	root -> candidates -> [0] -> attributes -> City
district	Stored Variable	Forms Address Save Response	root -> candidates -> [0] -> attributes -> District
latitude	Stored Variable	Forms Address Save Response	root -> candidates -> [0] -> location -> y
line1	Stored Variable	Forms Address Save Response	root -> candidates -> [0] -> attributes -> Address
longitude	Stored Variable	Forms Address Save Response	root -> candidates -> [0] -> location -> x
postcode	Stored Variable	Forms Address Save Response	root -> candidates -> [0] -> attributes -> Postal
region	Stored Variable	Forms Address Save Response	root -> candidates -> [0] -> attributes -> Region
subregion	Stored Variable	Forms Address Save Response	root -> candidates -> [0] -> attributes -> SubRegion

This is an example for City

Close the window. The final canvas should look something like this:

4. Form Config

The two Integration Workflows above will be triggered on a ProcessFactorial Form. For that, we need to first create a Form address fields. We will be mapping responses to these fields

Field	Purpose
Country	A supported country field that will limit search results to a specific country. It can be a string or lookup field, but the resultant value must be one of Country Name, ISO2 Code, `ISO3 Code'
Address	Full Address. Also used to search for an address. Must be a string with a Type Ahead format
Line 1
Line 2
Sub Region
Region
Post Code
Latitude
Longitude

After the fields above have been added, edit the Address field, and go to the Events tab.

Configure the OnKeyPressed Event

This event will trigger the Search integtation and will present the user with a list of addresses to select from.

1. Select Actions for the OnKeyPressed event
2. Add a new Integrate action and give it a name and description
3. Select Forms Integration Workflow - Address Search as the Integration Workflow
4. Map the Street Text to the Country field.
5. If this is a string, the value will be Field Value
6. If it is a lookup, use the Field Value for full country name, or the relevant field for the ISO code
7. Map Country Text to "this" Address field,Field Value. This is where the user will type in the address
8. Set Use Integration Workflow to to Show as Drop-Down Results

Configure the OnUpdate Event

This event will trigger the Save integration and will retrieve each field of the address that the user has selected from the search list above

1. Select Actions for the OnUpdate event
2. Add a new Integrate action and give it a name and description
3. Select Forms Integration Workflow - Address Save as the Integration Workflow
4. Map the Address to the Address "key". If all the above was done correctly, this key property should hold the magic key for the address search
5. Set Use Integration Workflow to to Populate Fields on Form
6. Paste this into the Sample Return Message. This is the same value as we configured earlier in the Return Data Action for the Save Integration Service:
7. {"address":"address","city":"city","district":"district","latitude":0,"line1":"line1","longitude":0,"postcode":"postcode","region":"region","subregion":"subregion"}
8. Below the Sample Return Message, map each object to a field on the form. Not all fields have to be mapped, so only map what is relevant to your use case. Remember to click Save every time