Postcode Anywhere PCA Predict v1.5

This package provides capabilities that extend the Avoka Transact platform with integration to the PCA Predict (formerly Postcode Anywhere) suite of services for data validation. These include:

  1. Real-time Global address search and auto-complete - demo
  2. Real-time email address validation - demo
  3. Real-time phone number validation - demo

For address auto-complete support, this package includes 3 components:

  1. PCA Predict Short Address Lookup
    This component provides address lookup capabilites for short format addresses and includes a short format address field set for manual address entry if required.
  2. PCA Predict Long Address Lookup
    This component provides address lookup capabilites for long format addresses and includes a long format address field set for manual address entry if required.
  3. PCA Predict Address Autocomplete
    This is a is used in the short and long address lookup components and is a single field address lookup that can be used to populate a custom address block where the short and long formats provided are not suitable.

For email validation support, this package includes the component:

  1. PCA Predict Email Validation
    This component provides email address validation capabilities.

For phone validation support, this package includes the component:

  1. PCA Predict Phone Validation
    This component provides phone validation capabilities.

Address Formats

Avoka provides 2 address format options:

Short format address (sometimes called standard 5 field address) is a very common address format used in systems of record and consists of the following fields:

  1. Address Line 1
  2. Address Line 2
  3. Locality
  4. State
  5. Postal Code

Long format address provides a more explicit breakdown of address components:

  1. Building Name
  2. Subdwelling
  3. Street Number
  4. Street Name
  5. Street Type
  6. Locality
  7. State
  8. Postal Code

Where practical we also provide the following addtional fields:

  1. Country
  2. Country Code
  3. Full Address
  4. Lookup Key
  5. Postal Flag

Address Field Definitions

FieldDescription
Address Line 1
(short format only)		 This will be the first of 2 address lines. The contents of this element will depend on the existence of a building name or subdwelling where a subdwelling could be a unit/flat/shop/suite number or a level/floor number. If any of these elements exist then this field will contain these sub-location elements in the following order:

[buildingName] [floor/level] [unit/flat/shop/suite]

If none of these sub-location elements exist then this field will contain:

[streetNumber] [streetName] [streetType]

Address Line 2
(short format only)		 This will be the second of 2 address lines and will be blank unless addressLine1 contains sub-location elements, in which case the addressLine2 will contain:

[streetNumber] [streetName] [streetType]

Building Name
(long format only)		 Occasionally physical addresses include the name of the building they are located within. For example, performing a lookup for 34/267-277 CASTLEREAGH ST will return a building name of MUSEUM TOWERS.
Subdwelling
(long format only)		 The subdwelling value will contain floor/level identifiers and/or unit/flat/shop/suite identifiers.
Street Number
(long format only)		 For physical addresses this value will contain the street number of the address which does not include the unit or flat number, but may be represented as a range (e.g. 267-277). For non-physical addresses this field will contain the PO Box, Locked Bag, or similar data.
Street Name
(long format only)		 Where practical, this field will contain the name of the street only, with street type being provided separately (see below).
Street Type
(long format only)		 The street type value may be provided as an expanded value (e.g. ROAD) or abbreviation (e.g. RD), depending on the lookup service response data.
Locality The locality information varies from country to country but will usually be either suburb or city.
State The State that the address resides in. For some countries (e.g. New Zealand) this may be blank.
Postal Code The regional postal code, also referred to as Zip Code (US) and Postcode.
Country The Country that the address is located wihin, in its expanded form (e.g. Australia).
Country Code Where practical, the Country code will be provided as represented in the ISO 2 character (e.g. AU) or 3 character (e.g. AUS) standards, depending on the data provided by the lookup service.
Postal Flag The postal flag field indicate whether this address is a non-physical address (e.g. PO Box, Locked Bag etc...). Most address lookup providers support the ability to exclude non-physical addresses from lookup searches if required.
Full Address The intention of this field is to provide the full address with the exclusion of Country, as a single one line string. For example:

MUSEUM TOWERS U 34 267-277 CASTLEREAGH ST SYDNEY NSW 2000

Lookup Key This field represents a unique identifier for the address in the 3rd party system and will be different for each provider.

Licensing

Clients must ensure they are appropriately licenses in order to use this package. Organisations who wish to use this package are required to establish a commercial relationship with PCA Predict directly.

Compatibility

This package has the following compatibility requirements:

ModuleCompatibilityNotes
Transact Manager5.1.4 or above
Transact Maestro5.0 or above
CapturePlus Interactive Findv2.10
CapturePlus Interactive Retrievev2.10

Installation Instructions

To install this package please walk through the following proceedure:

  1. Unzip the package to a directory on your computer
  2. Import each zip archive found in the services folder to Transact Manager under the Services >> All Services menu item.
  3. Review the Help Doc tab for each of the imported services and make any required adjustments to service parameters.
  4. Review the Service Connection requirements under the same Help Doc tab for each of the imported services and make any required configurations to the Service Connection. Service Connections can be configured in Transact Manager under the Services >> Service Connections menu item.
  5. Import each archive found in the libraries folder to Maestro. Importing these into the Organisation level libraries folder is recommended as this will make the components available to all projects, however they can be imported at the Project level if required.

Usage Instructions

All Maestro components in this package can be located in the PCA Predict folder in the palette.

To configure the 'PCA Predict Long/Short Address Lookup' components, please walk through the following procedure:

  1. Open your form in Maestro and drag and drop the component from the palette onto your form in the desired location.
  2. Select the component root element and rename it to reflect the address type (e.g. Applicant Residential Address)
  3. In the Properties tab for the component root element and under Options, configure your properties as defined in the component definitions below. E.g. Consider adding a Country Code to limit search scope. You can also set a preferred language if PCA service supports.

To use the single field 'PCA Predict Address Autocomplete', please walk through the following procedure:

  1. Open your form in Maestro and drag and drop the component from the palette onto your form in the desired location.
  2. Open the properties section of the field.
  3. Under 'Second DDS Configuration' section, map the response data fields to your Maestro fields.

To use the email/phone validation, drag and drop the field from Maestro palette.

Release Notes

Version 1.5 Oct 15, 2018

  • Fixed issue with group of addresses within the auto-complete component in Maestro 18.05.

Version 1.4 Jan 17, 2018

  • Fixed issue with group of addresses within the auto-complete component.

Version 1.3 Jan 5, 2018

  • Added preferred language option (ENG or FRE) for Canada.

Version 1.2 Jun 28, 2017

  • Added second call to PCA to support result lists that include grouped addresses.

Version 1.1 Jun 14, 2017

  • Added support for Maestro 5.1 language translation features.

Version 1.0 Feb 8, 2017

  • Baseline release.

Maestro Assets

PCA Predict Address Autocomplete Library: exchange.pca.predict Category: PCA Predict

Australian address autocomplete service using the PCA Predict APIs

Used In

Service Calls

Rule Templates

You may add your own logic to handle the following rule types triggered by this component:

  • On Success : a script to run on success of the dynamic data call, the parameter info contains the response
  • On List Item Select : a script to run on the click of a result
  • On Extra Item Select : a script to run on the click of an extra item
  • On Label Button Click : a script to run on the click of an optional button next to label
  • On Complete : a script to run when the auto-complete process is successfully completed.

PCA Predict Long Address Lookup Library: exchange.pca.predict Category: PCA Predict

Address lookup component with long format address block

Uses

Properties

Property Category Description Type Default
Mandatory Options

Controls the mandatory status of the address capture

boolean false
All Capital Letters Options

Controls whether the address label in the auto-complete field is all capitalised

boolean false
Maximum Result Size Options

Controls the maximum number of results to be returned in address searches

integer
Show Address Block Options

Controls whether to always show the address block or not

boolean false
Show Country Field Options

Controls whether to present the Country field in the address block

boolean false
Country Code Options

Specify a country code to limit search scope. Expects ISO standard 2 character codes (e.g. AU, US)

text
Preferred Language Code Options

You can set a preferred language code and it will be used to show the result in that language if backend supports.

text
PCA Predict Phone Validation Library: exchange.pca.predict Category: PCA Predict

This component provides phone validation using PCA Predict API

Service Calls

PCA Predict Short Address Lookup Library: exchange.pca.predict Category: PCA Predict

Address lookup component with short format address block

Uses

Properties

Property Category Description Type Default
Mandatory Options

Controls the mandatory status of the address capture

boolean false
All Capital Letters Options

Controls whether the address label in the auto-complete field is all capitalised

boolean false
Maximum Result Size Options

Controls the maximum number of results to be returned in address searches

integer
Show Address Block Options

Controls whether to always show the address block or not

boolean false
Show Country Field Options

Controls whether to present the Country field in the address block

boolean false
Country Code Options

Specify a country code to limit search scope. Expects ISO standard 2 character codes (e.g. AU, US)

text
Preferred Language Code Options

You can set a preferred language code and it will be used to show the result in that language if backend supports.

text
PCA Predict Email Validation Library: exchange.pca.predict Category: PCA Predict

Validate email address

Service Calls

Services

PCA Predict - Address Details v2
This Dynamic Data service executes a lookup on the PCA Predict API to retrieve an address and return a address details in the requested format.

Service Connection

Compatibility

Module Compatibility
Manager 5.0

Inputs

Name Description Required
lookupKey The lookup key. Yes
next The next id to search. Some items are group of items which require another search call. No
allCaps Optionally request that results are returned in all capital letters [ true | false ] (default: false) No
format Optionally specify the format of the address to be returned [ short | long ] (default: short) No
languageCode Optionally specify a preferred language code. No

Outputs

Name Description
fullAddress The full address of the matched address
lookupKey The unique identifier for the matched address in the source database
buildingName
subdwelling
streetNumber
streetName
streetType 		Where address format long is requested the address will be broken into these sub-elements
addressLine1
addressLine2 		Where address format short is requested the address will be returned with the simple breakdown
locality The suburb
state The Australian state, blank for NZ addresses
postalCode The postcode
country The country name E.g. Australia
countryCode The 2 character country code
languageCode The language code in response
executionStatus The status of the service execution [ SUCCESS | DATA_ERROR | SYSTEM_ERROR ].

Successful execution will be denoted by a SUCCESS value. DATA_ERROR will indicate that there was an issue identified with the input data that may be resolved and potentially retried by the user. SYSTEM_ERROR indicates that there was an unrecoverable system fault and the form should fall-back gracefully to an alternative path.
errorMessage When a DATA_ERROR is experienced, this value may provide more detail on the nature of the error.
next The next id to search. Some items are group of items which require another search call.
PCA Predict - Address Search v2
This service facilitates address searching using the PCA Predict API.

Service Connection

Compatibility

Module Compatibility
Manager 5.0

Service Parameters

Name Description Required Default
maxResultSize Default value for maximum number of matching search results returned from the search function (default 10). This value can be overridden as a request parameter if required. Must be between 1 and 20. Yes 10
defaultCountryCode Default country code is ISO standard 2 character code (e.g. AU, US). This value can be overridden as a request parameter if required. No

Inputs

Name Description Required
searchString The address search string. Yes
countryCode Optionally specify a country code to limit search scope. Expects ISO standard 2 character codes (e.g. AU, US) No
next The next id to search. Some items are group of items which require another search call. No
maxResultSize Optionally specify a numeric maximum result list size to override the default: 10. Cannot be less than 1 or greater than 20. No
allCaps Optionally request that results are returned in all capital letters [ true | false ] (default: false) No
languageCode Optionally specify a preferred language code. No

Outputs

Name Description
[] The results are provided as a JSON array of objects with the following attributes:
[].label The value to display in the result list, will be full address (excluding Country)
[].lookupKey The unique identifier to use when performing a detail lookup.
[].fullAddress The full address (excluding Country)
[].countryCode The country code is ISO standard 2 character code (e.g. AU, US)
[].next The next id to search. Some items are group of items which require another search call.
PCA Predict - Validate Email v1
This service facilitates email address validation using the PCA Predict API.

Service Connection

Compatibility

Module Compatibility
Manager 5.0

Inputs

Name Description Required
emailAddress The email address. Yes

Outputs

Name Description
validationStatus The status of the validation call, will be [ VALID | INVALID | UNKNOWN]. Clients should check that the validationStatus is not INVALID as an UNKNOWN result is not definitive. If validationStatus = INVALID a generic errorMessage will be provided and executionStatus will be set to DATA_ERROR.
executionStatus The status of the service execution [ SUCCESS | DATA_ERROR | SYSTEM_ERROR ].

Successful execution will be denoted by a SUCCESS value. DATA_ERROR will indicate that there was an issue identified with the input data that may be resolved and potentially retried by the user. SYSTEM_ERROR indicates that there was an unrecoverable system fault and the form should fall-back gracefully to an alternative path.
errorMessage When a DATA_ERROR is experienced, this value may provide more detail on the nature of the error.
PCA Predict - Validate Phone v1
This service facilitates Australian Phone Number validation using the PCA Predict API.

Service Connection

Compatibility

Module Compatibility
Manager 5.0

Inputs

Name Description Required
phone The phone number. Yes
countryCode specify a The ISO2 country code of the number you are trying to validate (e.g. AU, US) (default: AU). No

Outputs

Name Description
validationStatus The status of the validation call, will be [ VALID | INVALID | UNKNOWN]. Clients should check that the validationStatus is not INVALID as an UNKNOWN result is not definitive. If validationStatus = INVALID a generic errorMessage will be provided and executionStatus will be set to DATA_ERROR
executionStatus The status of the service execution [ SUCCESS | DATA_ERROR | SYSTEM_ERROR ].

Successful execution will be denoted by a SUCCESS value. DATA_ERROR will indicate that there was an issue identified with the input data that may be resolved and potentially retried by the user. SYSTEM_ERROR indicates that there was an unrecoverable system fault and the form should fall-back gracefully to an alternative path.
errorMessage When a DATA_ERROR is experienced, this value may provide more detail on the nature of the error.
phoneNumber The recipient phone number in international format.
networkCode The current operator serving the supplied number.
networkName The name of the current operator serving the supplied number.
networkCountry The country code of the operator.
nationalFormat The domestic network format (useful for dialling from within the same country).
countryPrefix The country prefix that must be prepended to the number when dialling internationally.
numberType The type of number that was detected in the request (MOBILE, LANDLINE OR VOIP).

Service Connections

The following service connections are used by this package.

PCA Predict
Property Name Description Required
Type HTTP Endpoint Yes
Endpoint Must point to the PCA Predict endpoint. For example

http://services.postcodeanywhere.co.uk/

Yes
Auth Key Should contain Your Referer key to access the service Yes