Address Validation with Spectrum OnDemand (SPOD) Integration

Address verification in a web form is a common use case, such as creating or updating business partner, customer, or supplier. SPOD provides web services to validate addresses in specific regions or globally, with an option to add geocoding information.

The service can derive missing values through inputs given, such as deriving the city from the address line, region, country and postal code, or deriving the postal code given an address, city, region and country. Please ensure you test the service to meet your needs.

For information on SPOD offerings, please see the documentation:

• Spectrum OnDemand Services

• SPOD Address Validation

 

Pre-requisites

Following are the pre-requisites to use a SPOD service in an Evolve form.

  1. REST web service endpoint that contains the header parameters input fields.

  2. Basic authentication credentials, a user ID and password.

  3. JSON payload for output.

Any customizations like support for different region, global address validation, or customizing inputs and outputs can be done through SPOD services.

Note:

Refer to the documentation Known Limitations for API calls in Evolve. For example, you may request SPOD services to rename fields with a “.” (period) in them to use them successfully in an Evolve form.

Implement SPOD service with Evolve solutions

Following are the steps to implement a SPOD service with Evolve solutions.

  1. Optional: Test the API call in an API testing tool, like Postman, to ensure it works for your needs and to see the JSON output structure.
  2. Create a REST API Data Connection in Evolve > Connections, which can then be reference in Evolve solutions:

    1. Choose Connection Type: Rest API

    2. Add the URL of the SPOD site, example https://prestaging.spectrum.precisely.com/rest

    3. Choose Authentication: Basic

    4. Enter SPOD credentials

    5. Choose Date Format Type: ISO

    6. Select the check-box Applies to Composer

    7. Click Save

      Note:

      Data Connections can be set for the various SPOD sites, such as Staging, QA and Production.

  3. In Composer, add a Data Connection.

    1. Enter a Data Connection name

    2. Choose Type: Rest API

    3. Select the SPOD Data Connection you created in Evolve

    4. The URL will default to the one you entered in the Data Connection

    5. Choose HTTP operation GET for address validation

    6. Complete the URL in the URL Builder by adding

    The SPOD service name and specifying results to be returned in JSON, example, /ValidateMailingAddressPremium/results.json

  4. - Input parameters for the Address Validation service

    &Data.AddressLine1=[/my:myFields/my:BP_Address_Addr1]

    • Input parameter is Data.AddressLine1

    • Use the value in the form field BP_Address_Addr1 as the value

    Use the expression builder to make it easy to select a solution/form field as the value

    - Example complete URL:

    https://staging.spectrum.precisely.com/rest/ ValidateMailingAddressPremium/results.json?

    &Data.AddressLine1=[/my:myFields/my:BP_Address_Addr1]

    &Data.AddressLine2=[/my:myFields/my:BP_Address_Addr2]

    &Data.City=[/my:myFields/my:BP_Address_City]

    &Data.StateProvince=[/my:myFields/my:BP_Address_State]

    &Data.PostalCode=[/my:myFields/my:BP_Address_Zip]

    &Data.Country=[/my:myFields/my:BP_Address_CountryCode]

  5. Outputs should be specified in the API Output Schema. Based on the service you select, you may have a different number of possible output fields. Example: 
        {
		"Output": [
			{
					"AddressLine1": "string",
					"AddressLine2": "string",
					"AddressLine3": "string",
					"City": "string",
					"StateProvince": "string",
			    	"PostalCode": "string",
				    "Country": "string",
					"HouseNumber": "string",
					“Status” : ”string”,
					"StatusCode": "string",
					"StatusDescription": "string",
					"Confidence": "integer",
			 }
		  ]
		}
  6. Form Fields can be created with any Composer Data Connection which will be the output fields from your SPOD service.
  7. Map the fields to the form.

    1. Input fields - The input fields may vary based on the SPOD service you selected. Examples may include: Address line 1, Address line 2, City, State Region, Postal Code and Country. This will be used in the URL builder for the data connection to pass inputs. You can use the address element or other form fields, which contain the input values to be passed to the SPOD Address Validation web service.

    2. Output fields - To create the form fields for the SPOD service right click on the data connection and select the required fields. The SPOD service will generate the output fields based on the API Output Schema used. The results will be repeating content, whether a single address or multiple addresses. Map them according to your needs in the form. The repeating content, which will be address suggestions/corrections can be mapped to a repeating or selectable table.

  8. Add a web service control to your form and map it to the SPOD web service. Add a button or rule to trigger the web service.
  9. Deploy and test solution.