Workbench Configure Address Typeahead

Configuring the Address Typeahead functionality in the Web UI starts in the workbench. Setting up the functionality involves supplying JSON Path expressions to handle requests and responses for suggestions and selections. JSON Path (also written 'JSONPath') expressions are used to query JSON by specifying the path to an element (or set of elements) in a JSON structure. For more information, refer to the Understanding JSON Paths in Address Typeahead topic here.

A one-time setup is required to configure Address Typeahead, as defined in the Workbench Initial Setup for Address Typeahead topic here.

Important: Before starting the workbench setup, obtain or verify that you have purchased an active key from your address search service. This key is required within the Address Typeahead configuration.

The Address Typeahead Value Type object includes the following tabs:

• The Address Typeahead Value Type tab includes the Description section with the same parameters typically displayed on any object. Only the Name can be edited. The additional sections within the Address Typeahead Configuration section are defined in the Configuration Parameters section.

• The Log tab lists changes and other events relevant to the object. Examples of changes or events listed on the Log tab are when a user or import creates a configuration, a user or import modifies a configuration, or when a revision is revived or purged.

• The Status tab includes revisions made to the configuration and allows a user to revert to a previous revision. Hidden Values and Diagnostics are available as necessary.

To remove an unnecessary Address Typeahead Value Type object, right-click the object and click the Delete option.

Configuring Address Typeahead includes:

• Resolving issues identified in the Configuration Validation Status.

• Supplying the data required in the Configuration Parameters.

• Resolving issues identified by the JSON Path Evaluator.

When the workbench configuration is complete, proceed with configuration in the Web UI, as defined in the Web UI Configure and Use Address Typeahead topic here.

Configuration Validation Status

Configuration validation is run without accessing the external REST service, but it identifies items that should be resolved to avoid issues when the external REST service is accessed.

Errors are reported in the Configuration Validation Status section, in the configuration editor (including the JSON Path Evaluator dialog), and also in the step.0 log based on configured logging output levels (as defined in the Workbench Initial Setup for Address Typeahead topic here).

Errors Reported on the Section

On the Configuration Validation Status section:

• A green checkmark () indicates that the configuration is error-free and is ready to be used.

• A red x () indicates that the configuration has errors, such as missing mandatory fields, invalid JSON Path syntax, or the REST gateway was deleted. While the configuration can be saved, the errors must be corrected before the configuration can be used in the Web UI.

• A yellow checkmark () indicates that the configuration has warnings, such as the selected REST gateway is not enabled. While the configuration can be saved, the warnings must be corrected before the configuration can be used in the Web UI.

Click the Edit Address Typeahead Configuration link to make corrections on the Edit Address Typeahead Configuration dialog defined in the Configuration Parameters section.

Errors Reported on the Configuration Editor

On the Edit Address Typeahead Configuration dialog, mandatory parameters are indicated with an asterisk (*) and also display with a red background once the user exits a mandatory field without a value or when the configuration is saved with missing mandatory information.

To save the configuration with missing information for additional work later, click the Save button on the Edit Address Typeahead Configuration dialog and then click the Save button on the Invalid Operations dialog.

When adding a JSON Path on the configuration parameters editor or within the JSON Path Evaluator, the following errors are identified:

• Invalid JSON Path syntax that fails the compiler.

  For example: $['Items'

  In this scenario, the final bracket is missing and should be corrected as $['Items']

• Invalid JSON Path syntax displays a 'Suggested Change' when available.

  For example, typing: $['Items'][0][

  displays the message: Invalid JSON Path syntax. Suggested Change: $['Items'][0]

  Consider the suggestion and correct the syntax. While the suggestion is a valid JSON Path expression, also consider that additional text may be necessary to produce the desired result, such as $['Items'][0][*]

  Suggested Changes are not displayed for JSON Path expressions that filter results via a conditional statement. Using the ‘?’ character, is an example of this.

When applicable on a multi-value editor, both messages can display.

Refer to the JSON Path Evaluator section for additional troubleshooting assistance.

Configuration Parameters

After clicking the link to edit the configuration, the Edit Address Typeahead Configuration dialog displays. The configuration can be saved with incomplete data, allowing the user to continue configuration in multiple sessions if necessary.

JSON Paths are used to query the JSON response document for both address typeahead suggestion and selection responses. While in the address typeahead configuration editor, the user adds JSON Paths for fields in the Suggestion Response Mapping section, the Selection Response Mapping JSON Paths section, and the Error Handling section. For details on JSON Paths, refer to the Understanding JSON Paths in Address Typeahead topic here.

Configuration Sections

Refer to the following areas for details on the parameters in each of the sections:

• Service Endpoint Configuration

• Suggestion Request Query Parameters

• Suggestion Response Mapping

• Selection Request Query Parameters

• Selection Response Mapping JSON Paths

• Error Handling

Note: In the following sections, 'service' refers to your address search service, such as Loqate, Google Places, or another address service. Parameters that are required for all services are indicated with an asterisk. Additional parameters are used as available from the selected address search service.

Service Endpoint Configuration

Use this section to add the REST call to the address search service, as defined below:

• Gateway Integration Endpoint – mandatory; use the dropdown to select an existing GIEP. If needed, create a new endpoint as defined in the Gateway Integration Endpoints topic of the Data Exchange documentation here.

• Suggestion URL – mandatory; the suggestion endpoint URL from the service. This is also used for drill-down functionality, available when using Loqate.

• Selection URL – mandatory; the selection endpoint URL from the service. This is also used for drill-down functionality, available when using Loqate.

• API Key Query Parameter Key – the key for the API Key in the request URLs.

• API Key – the key to authenticate with the service. While the key is visible in this configuration, it is not included in the URLs written in the log or in validation responses.

• Session Token Query Parameter Key – the query parameter key for session tokens in the request URL. Session tokens are used by the service to charge per transaction. If no value is specified, no session token is sent in either the suggestion or selection requests.

  Session tokens update after a selection request, upon reloading the Web UI screen, and when error responses from either suggestion or selection requests are generated. For more information, refer to the online help for your selected address search service.

• Language Query Parameter Key – key for the language parameter on the service.

• Language – indicates a specific language. Refer to your address service provider's documentation for details on how defining a language impacts your searches as regional or international.

• URL Postfix – extension of a URL (not encoded) used to target specific parameters on the service. Consider the following about the URL Postfix encoding:

  • The REST Gateway Endpoint encodes every character inserted in this parameter according to the HTML URL encoding standards. This means that text added in the URL Postfix parameter must not be manually encoded to avoid 'double encoding.'

    For example, the system encodes the text 'Street=Main Street' to 'Street=Main%20Street'. If the user is unaware of the automatic encoding and attempts to manually encode the URL to 'Street=Main%20Street', the system then encodes it again, which results in double encoding to 'Street=Main%25%32%%30Street'. Double encoding results in unexpected results from the address search service.

  • The ‘&’ character is interpreted as a property separator by the URL encoding, and therefore, using it as a character in the property value breaks the request.

    For example, the property value 'Street=Main Street&Third' is interpreted as two different properties which may result in an unexpected response.

  Refer to the documentation for your address search service to identify available parameters. For Loqate, refer to https://www.loqate.com/resources/support/apis/Capture/Interactive/Find/1.1/.

Suggestion Request Query Parameters

Use this section to add the information defined below:

• Search Query Parameter Key – mandatory; targets the Suggestion URL identified under the Service Endpoint Configuration section. Add the key for the query parameter that contains the value of the text the user types into the address input box in the Web UI.

• Maximum Suggestions Query Parameter Key – targets the maximum suggestions received from the Suggestion URL identified under the Service Endpoint Configuration section. This represents the query key for the specific parameter.

• Drilldown Address Container ID Query Parameter Key – the parameter key when the suggestion from the service was not 'address', which identifies the drill-down parameter on the service, if available. Drill-down is an expanded menu that displays when multiple responses are available from a search. Drill-down is available in Loqate, but is not available in Google Places. Refer to your address search service for availability.

  This parameter is used when the 'Suggestion Type Selection Value' in the 'Suggestion Response Mapping' section (below) is not 'Address.' For Loqate, use the 'Container' key; for Google Places, leave this field blank since drill-down is not available.

Suggestion Response Mapping

For information on the Two-Level Mapping Functionality used in this section, refer to the Understanding JSON Paths in Address Typeahead topic here.

Use this section to add the information defined below:

• Suggestion Array JSON Path – mandatory; extracts the suggestion record array.

• Display Text JSON Path(s) – mandatory; extracts the text displayed in the Address Typeahead. Ordering of a list of paths can be added, removed, and changed via a dialog.

• Suggestion Type JSON Path – mandatory; extracts the type of the suggestion response item, set as:

  • street - to display the drill-down in the Web UI and use the ID to search in the container parameter described above to allow a selection.

  • address - to display the final address as a suggestion, which can be selected.

• Suggestion Type Selection Value – add either the text 'Address' or 'Drilldown' to define the type of data displayed in the Address Typeahead suggestion (second level record on the array). 'Drilldown' functionality is available for Loqate.

• Address ID JSON Path – mandatory; extracts the ID value from the suggestion response array. This is necessary once a suggestion is selected to invoke the selection endpoint and return either an address or street (container concept)

Selection Request Query Parameters

Use this section to add the information defined below:

• Address ID Query Parameter Key – mandatory; parameter to invoke the selection endpoint. Once the user selects a suggestion, this endpoint requests the same ID to the service to return the full data for that specific address.

Selection Response Mapping JSON Paths

Use this section to map a JSON Path to the related Address Component Model fields to extract data from the service, as shown in the image above.

Error Handling

Use this section to add the information defined below:

• Error detection JSON Path – when the response contains a value for this JSON Path, it is considered an error response.

• Error message JSON Path(s) – extracts JSON error messages to display in the Web UI. The order and messages can be edited within a dialog. Multiple messages are concatenated with the <br/> tag for display in the Web UI.

JSON Path Evaluator

For each JSON Path parameter on the configuration, use the JSON Path Evaluator to test the JSON Path expression against the input and report invalid syntax. Resolve the reported errors in the input to ensure successful configuration.

To use the evaluator:

1. Click the ellipsis button () on a JSON path parameter to display the JSON Path Evaluator dialog.

   

2. The JSON Path is displayed.

   • For invalid syntax scenarios, an error is displayed as well as suggested corrections when available.

   • Correct the JSON Path if necessary. To use the suggestion, copy the text and paste it into the JSON Path field.

3. Paste the document intended for processing into the Input field to evaluate against the JSON Path and display results in the Evaluation Result field.

   • 'No results' is displayed on the Evaluation Result field if:

     The JSON Path does not accommodate the Input document. For example, when the JSON Path includes 'Item' but the Input includes 'Items' or when the JSON Path is blank.

     The Input document is invalid. Use an online tool to test the validity of the JSON document.

   • Since the Input document is the same for all JSON Path fields, the document is retained and displays when testing all JSON Paths from the editor while the Address Typeahead Value Type object is being edited. The Input document is not saved in the Input field once the user leaves the object.

4. If necessary, modify the JSON Path to process the Input accurately.

   • Click OK to save the update to the configuration.

   • Click Cancel to leave the configuration unchanged.