Overview

Hopewiser's integrated CRM solutions provide a complete address capture solution. They allow you to capture an accurate and complete address, from either a postcode or partial address, and place it directly into your CRM.

Atlas for MSCRM

Product Features

  • Provides a quick and easy method for capturing addresses from either a postcode or partial address
  • Operates at all address entry points, ensuring a consistent method of address capture throughout the system
  • User-friendly interface, which is cross-browser compatible
  • Easily deployed and seamlessly integrated within the CRM environment
  • Formats the address to meet CRM requirements
 

Integrations are available for Microsoft Dynamics CRM, Sage CRM and Salesforce.com. Each ships with an installer and complete documentation, including an Administration Manual and User Guide. After installation, simply add your AddressServer in the Cloud username and password to start using the service.

To purchase Atlas for Microsoft Dynamics CRM or Atlas for Sage CRM please contact us.

You can install Atlas for Salesforce.com free of charge.

A general-purpose solution is also available to integrate with any IIS-based application.

1. Will my Hopewiser CRM integration still work if I upgrade my CRM platform?

This largely depends upon the CRM platform in play. For example, we have a number of Microsoft Dynamics CRM integrations to cater for different platform versions there. Please contact Hopewiser Technical Support to confirm upgrade compatibility.

2. My Microsoft CRM Hopewiser Integration renders incorrectly. Why?

Later versions of the Hopewiser Microsoft CRM integration feature cross-browser compatibility. Earlier versions (MS CRM 2013 version and earlier) may require you to use Internet Explorer Compatibility View to get the correct appearance.

 

3. Where do I set my AddressServer in the Client credentials?

These are entered (when you are looking to use and external service instead of local datafiles) in the <PafLocation> tag of the hpwConfig.xml. Latest versions of the integrations should have the <username> and <password> tags already in situ to utilise. Earlier versions of the CRM integhrations will need to have these included in a single service URL. Please contact Hopewiser Technical Support for guidance on the latter method if needed.

4. How do I implement address lookup capability within my MS Dynamics CRM Hopewiser Integration custom fields?

Guidance on this is within the Appendix A of the accompanying administration manual. This should be feasible if consistent field names and associated prefixes are used. The MS CRM 2016 integration features a means to stipulate a number of prefixes / field names to suit.

5. Why do I have the word ERROR! in red beside Atlas popup address window address fields?

This implies an error with the mappings associated with the field(s) in question. Please refer to the hpwConfig.xml mapping value concerned, or alternatively, assess the same through the page http://<crmroot>/Hopewiser/config.aspx.

Atlas for Salesforce.com

Hopewiser Atlas for Salesforce.com is the complete address capture solution. It allows you to capture an accurate and complete address from either a postcode or partial address, and place it directly into Salesforce.com.

Atlas for Salesforce

Product Features

  • Provides a quick and easy method for capturing addresses from either a postcode or partial address
  • Operates at all address entry points, ensuring a consistent method of address capture throughout the system
  • User-friendly interface, which is cross-browser compatible
  • Easily deployed and seamlessly integrated within Salesforce.com
  • Formats the address to meet Salesforce.com requirements
 

Installation

The installation packages are unmanaged packages that contain the static resources, Visualforce pages and the Find Address buttons. Installation packages are available for different editions of Salesforce.com.

If you have SalesforceIQ Starter edition or Salesforce.com Group edition, visit this URL to install the package for Leads, Accounts and Contacts into your organisation:

https://login.salesforce.com/packaging/installPackage.apexp?p0=04t24000000Ahfe

 

If you have Salesforce.com Professional edition or higher, visit this URL to install the package for Leads, Accounts, Contacts, Orders and Contracts:

https://login.salesforce.com/packaging/installPackage.apexp?p0=04t24000000Ep0m

 

Note: If you are installing into a sandbox organization please visit one of these URLs instead:

http://test.salesforce.com/packaging/installPackage.apexp?p0=04t24000000Ahfe

 

or, for Professional edition and higher:

http://test.salesforce.com/packaging/installPackage.apexp?p0=04t24000000Ep0m

 

Configuration

You must now add the Find Address button to the screens on which you wish to enable address lookup, and enter your username and password into the configuration. Please see the Administration Manual (PDF) for details.

User Guide

Download the User Guide (PDF).

1. What does the JavaScript Client do?

The JavaScript Client provides address capture capability to a web page. It operates very much like the Find Address button on our Sign Up page. (You need to be logged off to access the Sign Up page.)

2. How do I install the JavaScript Client?

Download

You do not have to download anything to use the JavaScript Client because your web page can reference the necessary files on our servers. However, if you'd like to download the client files and install them on your own web server, you can. Download the JavaScript Client files from the AddressServer Downloads page. (You will need to log on to access the downloads page).

AddressServer Downloads

Uncompress the downloaded JavaScriptClient.zip file and then upload the extracted files to a suitable location on your web server.

Setup

In the <head> of your web page, add this line (replacing 'https://cloud.hopewiser.com.au/jsclient' with the relative path of the folder you used above, if you chose to install these files on your own web server):

  <link rel="stylesheet" href="https://cloud.hopewiser.com.au/jsclient/hpw-jsclient.css" />

Before the </body> closing tag of your web page, add these lines (replacing 'https://cloud.hopewiser.com.au/jsclient' with the relative path of the folder you used above, if you chose to install these files on your own web server):

  <script src="https://cloud.hopewiser.com.au/jsclient/jquery.min.js"></script>
  <script src="https://cloud.hopewiser.com.au/jsclient/bootstrap.min.js"></script>
  <script src="https://cloud.hopewiser.com.au/jsclient/json2.min.js"></script>
  <script src="https://cloud.hopewiser.com.au/jsclient/easyXDM.min.js"></script>
  <script src="https://cloud.hopewiser.com.au/jsclient/hpw-jsclient.min.js"></script>

If your web site is already using jQuery, Bootstrap, json2 or easyXDM, you may be able to omit the applicable lines or reference your existing installation as necessary.

Add a button with the following attributes to your web page:

  <button type="button" data-toggle="modal" data-target="#hpwModal" data-backdrop="static" onclick="btnFindAddress_onclick()">Find Address</button>

In the <head> of your web page, add a script to handle the button's onclick event. In the button's onclick handler, call the HPW.FindAddress() function:

  <script>
  function btnFindAddress_onclick() {
    HPW.FindAddress({...});
  }
  </script>

The HPW.FindAddress() function takes a JavaScript object containing:

  • your authorisation code,
  • the dataset to look up against,
  • the HTML ID of your input field,
  • an object containing the HTML IDs of your output fields, and
  • optionally, parameters to indicate if you want to include the County or any Organisation Name within the matched address, and whether you want the town in upper or lower case.

Your authorisation code is the User Name of a service user, followed by a colon, followed by the Password of the service user, all Base64 encoded. You can use the Authorisation Code Generator in the last subsection of this document to get your authorisation code. For your security, it is important that you use a User Name with only service user permissions so that nobody can decode your credentials and use them to log on to Your Account. The dataset reference you specify must be one that is available to the service user that you used to generate the authorisation code.

Optional Parameter Description
IncludeCounty

Select when the county should be included within the formatted address label. Allowed values are Always (the default), Never or AsRequired.

The value AsRequired will only include the county when appropriate, for example when it meets PTT guidelines or when it is required to disambiguate UK town names.

NOTE: It is strongly recommend to include this parameter as its default is subject to change from Always to AsRequired.
ReserveOrganisationLine

Select the position of the organisation within the formatted label. Allowed values are AsRequired, Always or Never (the default).

The value AsRequired includes the organisation within the address label following standard formatting rules.

The value Always reserves the first line of the formatted address label for the organisation and forces it to be output on a separate line. If there is no organisation then the first line will be empty.

The value Never removes the organisation from the formatted address label.

NOTE: It is strongly recommend to include this parameter as its default is subject to change from Never to AsRequired.
organisation Deprecated; replaced by ReserveOrganisationLine

Select the position of the organisation within the formatted label. Allowed values are true or false (the default).

The value true includes the organisation within the address label following standard formatting rules.

The value false removes the organisation from the formatted address label.

TownFormat Select the required town format. Allowed values are Uppercase (the default) or Lowercase.

If your web page has separate address fields

Specify their HTML IDs in the output object, e.g.

  function btnFindAddress_onclick() {
    HPW.FindAddress({
      auth: "yourAuthCode",          // required
      dataset: "uk-rm-paf-external", // required
      input: "txtInput",             // required
      output: {
        line1:    "txtLine1",        // required
        line2:    "txtLine2",        // required
        line3:    "txtLine3",        // optional
        line4:    "",                // optional
        town:     "txtTown",         // required
        county:   "txtCounty",       // optional
        postcode: "txtPostcode",     // required
        country:  "txtCountry"       // optional
      },
      IncludeCounty: "AsRequired",            // optional (default = "Always")
      ReserveOrganisationLine: "AsRequired",  // optional (default = "Never")
      TownFormat: "Uppercase"                 // optional (default = "Uppercase")
    });
  }

If your web page has a single multi-line address field

Specify its HTML ID against each address line you want to be returned, e.g.

  function btnFindAddress_onclick() {
    HPW.FindAddress({
      auth: "yourAuthCode",          // required
      dataset: "uk-rm-paf-external", // required
      input: "txtInput",             // required
      output: {
        line1:    "txtAddress",      // required
        line2:    "txtAddress",      // required
        line3:    "txtAddress",      // optional
        line4:    "",                // optional
        town:     "txtAddress",      // required
        county:   "txtAddress",      // optional
        postcode: "txtAddress",      // required
        country:  "txtAddress"       // optional
      },
      IncludeCounty: "AsRequired",           // optional (default = "Always")
      ReserveOrganisationLine: "AsRequired", // optional (default = "Never")
      TownFormat: "Uppercase"                // optional (default = "Uppercase")
    });
  }

If your web page has a mixture of multi-line and individual address fields

For each address line you want, specify the HTML ID of the field you want it returned to, e.g.

  function btnFindAddress_onclick() {
    HPW.FindAddress({
      auth: "yourAuthCode",          // required
      dataset: "uk-rm-paf-external", // required
      input: "txtInput",             // required
      output: {
        line1:    "txtStreet",       // required
        line2:    "txtStreet",       // required
        line3:    "txtStreet",       // optional
        line4:    "",                // optional
        town:     "txtTown",         // required
        county:   "txtCounty",       // optional
        postcode: "txtPostcode",     // required
        country:  "txtCountry"       // optional
      },
      IncludeCounty: "AsRequired",           // optional (default = "Always")
      ReserveOrganisationLine: "AsRequired", // optional (default = "Never")
      TownFormat: "Uppercase"                // optional (default = "Uppercase")

    });
  }

(Replace yourAuthCode with your authorisation code and the example HTML IDs with your actual HTML IDs.) If you do not specify an ID for line3 or line4, the returned address will be formatted to fit the available lines. The county ID should be used in conjunction with the IncludeCounty parameter, and must be specified when the county is required. If you do not specify an ID for country, then it will be omitted. The input field does not have to be a separate field; it can be one of the output fields, in which case it would most likely be the postcode field.

3. How do I perform an address search?

Type a postcode into your input field then click the Find Address button. Select an address from the list of possible matches then click the Select button. Repeat if necessary until you have the address you want.

4. How do I troubleshoot my installation?

Please note that your web page must be served up via a web server, using the http:// or https:// protocol. The JavaScript Client will not work if you open your web page directly from the file system, using the file:// protocol.

You can use the debug version of Hopewiser JavaScript Client to check your integration for errors. This version will display a message box to the user if there are any missing or invalid fields.

In the lines you added before the </body> closing tag of your web page, replace this line:

  <script src="https://cloud.hopewiser.com.au/jsclient/hpw-jsclient.min.js"></script>

 

with this one:

 

  <script src="https://cloud.hopewiser.com.au/jsclient/hpw-jsclient.debug.js"></script>

(Replace 'https://cloud.hopewiser.com.au/jsclient' with the relative path of your installation folder, if you chose to install these files on your own web server.) When you have resolved the problem, be sure to switch back to the non-debug version of Hopewiser JavaScript Client.

IE Compatibility Modes

The JavaScript Client uses Bootstrap, which is not supported in the old Internet Explorer compatibility modes. To be sure you're using the latest rendering mode for IE, consider including the appropriate <meta> tag in your page:

<meta http-equiv="X-UA-Compatible" content="IE=edge">

 

Confirm the document mode by opening the debugging tools: press F12 and check the "Document Mode".

5. How can I return individual address elements?

This can be useful if, for example, you need delivery point information or if you want premise details separately from the street information. In the JavaScript object that you pass in to the HPW.FindAddress() function, you can include an optional detail object containing the names of the address elements that you want, and the HTML IDs of the fields that you want the values returned to. For example:

  function btnFindAddress_onclick() {
    HPW.FindAddress({
      auth: "yourAuthCode",          // required
      dataset: "uk-rm-paf-external", // required
      input: "txtInput",             // required
      output: {
        line1:    "txtLine1",        // required
        line2:    "txtLine2",        // required
        line3:    "txtLine3",        // optional
        line4:    "",                // optional
        town:     "txtTown",         // required
        county:   "txtCounty",       // optional
        postcode: "txtPostcode",     // required
        country:  "txtCountry"       // optional
      },
      detail: {                      // optional
        Premise: "txtPremise",
        UDPRN:   "txtUdprn"
      },
      IncludeCounty: "AsRequired",           // optional (default = "Always")
      ReserveOrganisationLine: "AsRequired", // optional (default = "Never")
      TownFormat: "Uppercase"                // optional (default = "Uppercase") 
    });
  }

The available detail elements are:

Field Description
Department Department associated with the organisation.
Organisation Organisation name for the delivery point.
Flat Formatted flat.
Floor Formatted floor.
HouseName1 Primary house name for the delivery point.
HouseName2 Secondary house name for the delivery point.
Premise Formatted premise.
StreetName1 First street of the address.
StreetName2 Second street of the address.
DistrictName1 Minor district of the address.
DistrictName2 Major district of the address.
DPID UK: 3-character Delivery Point Suffix.
Australia: 8-character Delivery Point ID.
UDPRN UK: 8-digit Unique Delivery Point Reference Number.
DedupeKey Hopewiser field used for deduplication purposes.

6. How can I return extra data?

Depending on your dataset, you may be able to return extra data. In the JavaScript object that you pass in to the HPW.FindAddress() function, you can include an optional extra object containing the names of the extra data elements that you want, and the HTML IDs of the fields that you want the values returned to. For example:

  function btnFindAddress_onclick() {
    HPW.FindAddress({
      auth: "yourAuthCode",            // required
      dataset: "uk-nspd-paf-external", // required
      input: "txtInput",               // required
      output: {
        line1:    "txtLine1",          // required
        line2:    "txtLine2",          // required
        line3:    "txtLine3",          // optional
        line4:    "",                  // optional
        town:     "txtTown",           // required
        county:   "txtCounty",         // optional
        postcode: "txtPostcode",       // required
        country:  "txtCountry"         // optional
      },
      extra: {                         // optional
        Extra_Grid_Latitude:  "txtLatitude",
        Extra_Grid_Longitude: "txtLongitude"
      },
      IncludeCounty: "AsRequired",           // optional (default = "Always")
      ReserveOrganisationLine: "AsRequired", // optional (default = "Never")
      TownFormat: "Uppercase"                // optional (default = "Uppercase") 
    });
  }

The available extra data elements will depend on your dataset. To view the available extra data elements, visit:

https://cloud.hopewiser.com.au/atlaslive/json/dataset?q=listoutputs

or

https://cloud.hopewiser.com.au/atlaslive/xml/dataset?q=listoutputs

Replace dataset with the dataset you want to use, e.g. https://cloud.hopewiser.com.au/atlaslive/json/uk-nspd-paf-external?q=listoutputs or https://cloud.hopewiser.com.au/atlaslive/xml/uk-nspd-paf-external?q=listoutputs. Enter your User name and Password when prompted. The available extra data elements are those Outputs that have a TableName of "Extra Data".

 

7. How can I call a function on successful address lookup?

This can be useful if, for example, you need to enable a button or if you want to display the address on a map. In the JavaScript object that you pass in to the HPW.FindAddress() function, you can include an optional success attribute containing the function that you want to call. For example:

  function btnFindAddress_onclick() {
    HPW.FindAddress({
      auth: "yourAuthCode",          // required
      dataset: "uk-rm-paf-external", // required
      input: "txtInput",             // required
      output: {
        line1:    "txtLine1",        // required
        line2:    "txtLine2",        // required
        line3:    "txtLine3",        // optional
        line4:    "",                // optional
        town:     "txtTown",         // required
        county:   "txtCounty",       // optional
        postcode: "txtPostcode",     // required
        country:  "txtCountry"       // optional
      },
      success: EnableButton,         // optional
      IncludeCounty: "AsRequired",           // optional (default = "Always")
      ReserveOrganisationLine: "AsRequired", // optional (default = "Never")
      TownFormat: "Uppercase"                // optional (default = "Uppercase") 
    });
  }

  function EnableButton() {
    document.getElementById("btnNext").disabled = false;
  }

8. How can I style the user interface?

The Select and Cancel buttons have a class of btn. You can define this class in your CSS or you can use jQuery to add your own class:

  $(".btn").addClass("myButtonClass");

The Select button has a class of btn-primary and the Cancel button has a class of btn-default. If you want to style the buttons individually, you can define these classes in your CSS or you can use jQuery to add your own classes:

  $(".btn-primary").addClass("myPrimaryButtonClass");
  $(".btn-default").addClass("myDefaultButtonClass");

You can also reference the Select button using its ID hpw-btnOK.

The status bar has a class hpw-info and its ID is hpw-status. The ID of the list of possible matches is hpw-possibles. Both the status bar and the list of possible matches are contained within div elements that have the class form-group.

9. Sample code download

We have a HTML and a PHP sample code available for download:

To make a working Address Search demo web page from the sample code, follow the steps below:

  1. Download the zip file.
  2. Unzip the file and save the sample under an appropriate directory in a web server.
  3. Obtain an authorisation code for your AddressServer in the Cloud account with the Authorisation Code Generator.
  4. Edit the sample file to replace the YOUR_AUTHORISATION_CODE place holder with your authorisation code.

 

10. Authorisation Code Generator

Your authorisation code is calculated in your browser.
No account information is sent over the internet by this page.

 

Please enter your credentials for your AddressService in the Cloud account, then click on the "Generate My Code" button to display the code

1. What does the AutoComplete JavaScript Client do?

The AutoComplete JavaScript Client provides address capture capability to a web page. It facilitates an address search by automatically displaying partial and/or fully matched address items in a selectable menu. The menu items will be updated dynamically as the user enters more address information. When a fully matched address is selected, the requested address field information will be populated onto the nominated address fields on the web page.

2. How do I install the AutoComplete JavaScript Client?

Download

You do not have to download anything to use the AutoComplete JavaScript Client because your web page can reference the necessary files on our servers. However, if you'd like to download the client files and install them on your own web server, you can. Download the AutoComplete JavaScript Client files from the AddressServer Downloads page. (You will need to log on to access the downloads page).

AddressServer Downloads

Uncompress the downloaded AutoCompleteJavaScriptClient.zip file and then upload the extracted files to a suitable location on your web server.

Setup

In the <head> of your web page, add this line (replacing 'https://cloud.hopewiser.com.au/jsclient' with the relative path of the folder you used above, if you chose to install these files on your own web server):

  <link rel="stylesheet" href="https://cloud.hopewiser.com.au/jsclient/jquery-ui.min.css" />
  <link rel="stylesheet" href="https://cloud.hopewiser.com.au/jsclient/hpw-autoc-jsclient.css" />

Before the </body> closing tag of your web page, add these lines (replacing 'https://cloud.hopewiser.com.au/jsclient' with the relative path of the folder you used above, if you chose to install these files on your own web server):

  <script src="https://cloud.hopewiser.com.au/jsclient/jquery.min.js"></script>
  <script src="https://cloud.hopewiser.com.au/jsclient/jquery-ui.min.js"></script>
  <script src="https://cloud.hopewiser.com.au/jsclient/json2.min.js"></script>
  <script src="https://cloud.hopewiser.com.au/jsclient/easyXDM.min.js"></script>
  <script src="https://cloud.hopewiser.com.au/jsclient/hpw-autoc-jsclient.min.js"></script>

If your web site is already using jQuery, jQuery UI, json2 or easyXDM, you may be able to omit the applicable lines or reference your existing installation as necessary.

Finally, add a script to enable the address autocomplete feature on a nominated input field by association with a HPWAUTOC.FindAddress() function:

  <script>
    HPWAUTOC.FindAddress({
      server:       X,        // optional (default = "https://cloud.hopewiser.com.au")
      auth:         X,        // required
      dataset:      X,        // required
      minLength:    N,        // optional numeric value (default = 1)
      delay:        N,        // optional numeric value (default = 300)
      input:        X,        // required
      outputlines:  N,        // optional range value 2-9 (default = 7)
      output: {
        line1:      X,        // required
        line2:      X,        // required
        line3:      X,        // optional
        line4:      X,        // optional
        line5:      X,        // optional
        line6:      X,        // optional
        line7:      X,        // optional
        line8:      X,        // optional
        line9:      X,        // optional
        country:    X         // optional
      },
      success:                 X,   // optional callback function
      LabelFormat:             X,   // optional (default = "Standard")
      ReserveOrganisationLine: X,   // optional (default = "AsRequired")
      IncludeCounty:           X,   // optional (default = "AsRequired")
      DropCountyToFitLabel:    X,   // optional (default = "Never")
      TownFormat:              X    // optional (default = "Uppercase")
    });
  </script>

The HPWAUTOC.FindAddress() function takes a JavaScript object containing:

  • your authorisation code,
  • the dataset to look up against,
  • the HTML ID of your input field,
  • an object containing the HTML IDs of your output fields, and
  • optionally, parameters to influence other service behaviours referenced in the below Optional Parameter table.

Your authorisation code is the User Name of a service user, followed by a colon, followed by the Password of the service user, all Base64 encoded. You can use the Authorisation Code Generator in the last subsection of this document to get your authorisation code. For your security, it is important that you use a User Name with only service user permissions so that nobody can decode your credentials and use them to log on to Your Account. The dataset reference you specify must be one that is available to the service user that you used to generate the authorisation code.

Mandatory Parameter Description
auth

A valid authorisation code is required to access the required dataset.

dataset

A dataset ID associated with the MAF and AutoComplete database files.

input

The search field to invoke the AutoComplete address lookup.

output.line1 to output.line2

The first two lines of the formatted label for the selected address.

Optional Parameter Description
server

This is the URL to the AutoComplete Server. It defaults to "https://cloud.hopewiser.com.au".

minLength

This is the minimum number of characters a user must type before a search is performed. Its default value is 1.

delay

This is a delay in milliseconds between when a keystroke occurs and when a search is performed. No menu will be displayed until the typist pauses for the specified delay period after the last keystroke. Its default value is 300.

outputlines

This parameter is used to specify the maximum number of formatted output lines which should to be mapped accordingly in the "output.line" block. Allowed range is 2 to 9. Its default value is 7.

output.line3 to output.line9

Configure field mappings to include additional address label lines.

output.country

Configure a field mapping to include the country field information.

'detail' matched address output fields

This optional configuration section contains mapping information for some of the common address output fields.

The available detail elements will depend on your dataset. To view the available detail elements, visit:

https://cloud.hopewiser.com.au/autoc/json/dataset?q=listoutputs

Replace dataset with the dataset you want to use, e.g. https://cloud.hopewiser.com.au/autoc/json/uk-nspd-paf-external?q=listoutputs. Enter your User name and Password when prompted. The available detail elements are those Outputs that have a TableName of "Address Fields" or "Data".

'extra' data fields

This optional configuration section contains mapping information for "Extra Data" fields of a given matched address.

The available extra data elements will depend on your dataset. To view the available extra data elements, visit:

https://cloud.hopewiser.com.au/autoc/json/dataset?q=listoutputs

Replace dataset with the dataset you want to use, e.g. https://cloud.hopewiser.com.au/autoc/json/uk-nspd-paf-external?q=listoutputs. Enter your User name and Password when prompted. The available extra data elements are those Outputs that have a TableName of "Extra Data".

success

Calls a callback function at the end of populating the returned address if this parameter is configured.

LabelFormat

Select the position of the town, county and postcode within the formatted address label. Allowed values are Standard (the default), FixedPostcode or FixedTown.

The value FixedPostcode reserves the last line of the formatted address label for the postcode and forces it to be output on a separate line.

The value FixedTown reserves the last three lines of the formatted address label for the town, county and postcode and forces each value to be output on a separate line. Please note that a line is reserved for the county even if none is output.

When a fixed value is requested, the formatted address label will comprise the maximum allowed number of address lines, some of which may be empty.

ReserveOrganisationLine

Select the position of the organisation within the formatted label. Allowed values are Always, Never or AsRequired (the default).

The value AsRequired includes the organisation within the address label following standard formatting rules.

The value Always reserves the first line of the formatted address label for the organisation and forces it to be output on a separate line. If there is no organisation then the first line will be empty.

The value Never removes the organisation from the formatted address label.

IncludeCounty

Select when the county should be included within the formatted address label. Allowed values are Always, Never or AsRequired (the default).

DropCountyToFitLabel

Select if the county may be dropped when it does not fit within the formatted address label. Allowed values are Never (the default), or Always.

TownFormat Select the required town format. Allowed values are Uppercase (the default) or Lowercase.

If your web page has separate address fields

Specify their HTML IDs in the output object, e.g.

  HPWAUTOC.FindAddress({
    auth: "yourAuthCode",          // required
    dataset: "uk-rm-paf-external", // required
    input: "txtInput",             // required
    output: {
      line1:    "txtLine1",        // required
      line2:    "txtLine2",        // required
      line3:    "txtLine3",        // optional
      line4:    "txtLine3",        // optional
      line5:    "txtTown",         // optional
      line6:    "txtCounty",       // optional
      line7:    "txtPostcode",     // optional
      country:  "txtCountry"       // optional
    },
    LabelFormat: "FixedTown",           // optional (default = "Standard")
    ReserveOrganisationLine: "Never",   // optional (default = "AsRequired")
    IncludeCounty: "Always",            // optional (default = "AsRequired")
    TownFormat: "Lowercase"             // optional (default = "Uppercase")
  });

If your web page has a single multi-line address field

Specify its HTML ID against each address line you want to be returned, e.g.

  HPWAUTOC.FindAddress({
    auth: "yourAuthCode",          // required
    dataset: "uk-rm-paf-external", // required
    input: "txtInput",             // required
    outputlines: 9,                // optional  range value 2-9 (default = 7)
    output: {
      line1:    "txtAddress",      // required
      line2:    "txtAddress",      // required
      line3:    "txtAddress",      // optional
      line4:    "txtAddress",      // optional
      line5:    "txtAddress",      // optional
      line6:    "txtAddress",      // optional
      line7:    "txtAddress",      // optional
      line8:    "txtAddress",      // optional
      line9:    "txtAddress",      // optional
      country:  "txtAddress"       // optional
    },
    IncludeCounty: "Always"        // optional (default = "AsRequired")
  });

If your web page has a mixture of multi-line and individual address fields

For each address line you want, specify the HTML ID of the field you want it returned to, e.g.

  HPWAUTOC.FindAddress({
    auth: "yourAuthCode",          // required
    dataset: "uk-rm-paf-external", // required
    input: "txtInput",             // required
    output: {
      line1:    "txtAddress",      // required
      line2:    "txtAddress",      // required
      line3:    "txtAddress",      // optional
      line4:    "txtAddress",      // optional
      line5:    "txtTown",         // optional
      line6:    "txtCounty",       // optional
      line7:    "txtPostcode",     // optional
      country:  "txtCountry"       // optional
    },
    LabelFormat: "FixedTown",           // optional (default = "Standard")
    ReserveOrganisationLine: "Never",   // optional (default = "AsRequired")
    IncludeCounty: "Always",            // optional (default = "AsRequired")
    TownFormat: "Lowercase"             // optional (default = "Uppercase")
  });

(Replace yourAuthCode with your authorisation code and the example HTML IDs with your actual HTML IDs.) If you do not specify an ID for line3..line6, the returned address will be formatted to fit the available lines. The county ID should be used in conjunction with the IncludeCounty parameter, and must be specified when the county is required. If you do not specify an ID for country, then it will be omitted. The input field does not have to be a separate field; it can be one of the output fields, in which case it would most likely be the postcode field.

3. How do I perform an address search?

Key in a search criteria into your input field, an autocomplete menu will be automatically displayed when the minimum length and delay conditions are met and one or more matched items is/are return from the AutoComplete server. You can narrow down the search by either keying in more information or select one of the returned items from the autocomplete menu. The menu will be closed automatically either by pressing the "ESC" key to abort the search or by selecting a fully completed address from the menu.

4. How do I troubleshoot my installation?

NOTE: your web page must be served up via a web server, using the http:// or https:// protocol. The AutoComplete JavaScript Client will not work if you open your web page directly from the file system, using the file:// protocol.

When the web page is loaded, the AutoComplete Javascript Solution will check for field mapping and configuration errors. An error message window will be displayed when these are detected. The solution might not function correctly until these errors are correctd.

5. How can I return individual address elements?

This can be useful if, for example, you need delivery point information or if you want premise details separately from the street information. In the JavaScript object that you pass in to the HPWAUTOC.FindAddress() function, you can include an optional detail object containing the names of the address elements that you want, and the HTML IDs of the fields that you want the values returned to. For example:

  HPWAUTOC.FindAddress({
    auth: "yourAuthCode",          // required
    dataset: "uk-rm-paf-external", // required
    input: "txtInput",             // required
    output: {
      line1:    "txtLine1",        // required
      line2:    "txtLine2",        // required
      line3:    "txtLine3",        // optional
      line4:    "txtLine4",        // optional
      line5:    "txtTown",         // optional
      line6:    "txtCounty",       // optional
      line7:    "txtPostcode",     // optional
      country:  "txtCountry"       // optional
    },
    detail: {                      // optional
      Premise: "txtPremise",
      UDPRN:   "txtUdprn"
    },
    LabelFormat: "FixedTown",           // optional (default = "Standard")
    ReserveOrganisationLine: "Never",   // optional (default = "AsRequired")
    IncludeCounty: "Always",            // optional (default = "AsRequired")
    TownFormat: "Lowercase"             // optional (default = "Uppercase")
  });

The available detail elements will depend on your dataset. To view the available detail elements, visit:

https://cloud.hopewiser.com.au/autoc/json/dataset?q=listoutputs

Replace dataset with the dataset you want to use, e.g. https://cloud.hopewiser.com.au/autoc/json/uk-nspd-paf-external?q=listoutputs. Enter your User name and Password when prompted. The available detail elements are those Outputs that have a TableName of "Address Fields" or "Data".

6. How can I return extra data?

Depending on your dataset, you may be able to return extra data. In the JavaScript object that you pass in to the HPWAUTOC.FindAddress() function, you can include an optional extra object containing the names of the extra data elements that you want, and the HTML IDs of the fields that you want the values returned to. For example:

  HPWAUTOC.FindAddress({
    auth: "yourAuthCode",            // required
    dataset: "uk-nspd-paf-external", // required
    input: "txtInput",               // required
    output: {
      line1:    "txtLine1",          // required
      line2:    "txtLine2",          // required
      line3:    "txtLine3",          // optional
      line4:    "txtLine4",          // optional
      line5:    "txtTown",           // optional
      line6:    "txtCounty",         // optional
      line7:    "txtPostcode",       // optional
      country:  "txtCountry"         // optional
    },
    extra: {                         // optional
      Extra_Grid_Latitude:  "txtLatitude",
      Extra_Grid_Longitude: "txtLongitude"
    },
    LabelFormat: "FixedTown",         // optional (default = "Standard")
    ReserveOrganisationLine: "Never", // optional (default = "AsRequired")
    IncludeCounty: "Always",          // optional (default = "AsRequired")
    TownFormat: "Lowercase"           // optional (default = "Uppercase")
  });

The available extra data elements will depend on your dataset. To view the available extra data elements, visit:

https://cloud.hopewiser.com.au/autoc/json/dataset?q=listoutputs

Replace dataset with the dataset you want to use, e.g. https://cloud.hopewiser.com.au/autoc/json/uk-nspd-paf-external?q=listoutputs. Enter your User name and Password when prompted. The available extra data elements are those Outputs that have a TableName of "Extra Data".

7. How can I call a function on successful address lookup?

This can be useful if, for example, you need to enable a button or if you want to display the address on a map. In the JavaScript object that you pass in to the HPWAUTOC.FindAddress() function, you can include an optional success attribute containing the function that you want to call. For example:

  function btnFindAddress_onclick() {
    HPWAUTOC.FindAddress({
      auth: "yourAuthCode",                   // required
      dataset: "uk-rm-paf-external",          // required
      input: "txtInput",                      // required
      output: {
        line1:    "txtLine1",                 // required
        line2:    "txtLine2",                 // required
        line3:    "txtLine3",                 // optional
        line4:    "txtLine4",                 // optional
        line5:    "txtTown",                  // optional
        line6:    "txtCounty",                // optional
        line7:    "txtPostcode",              // optional
        country:  "txtCountry"                // optional
      },
      success: EnableButton,                  // optional
      LabelFormat: "FixedTown",               // optional (default = "Standard")
      ReserveOrganisationLine: "AsRequired",  // optional (default = "Never")
      IncludeCounty: "AsRequired",            // optional (default = "Always")
      TownFormat: "Uppercase"                 // optional (default = "Uppercase")
    });
  }

  function EnableButton() {
    document.getElementById("btnNext").disabled = false;
  }

8. Sample code download

We have a HTML and a PHP sample code available for download:

To make a working Address Search demo web page from the sample code, follow the steps below:

  1. Download the zip file.
  2. Unzip the file and save the sample under an appropriate directory in a web server.
  3. Generate an authorisation code for your AddressServer in the Cloud account.
  4. Edit the sample file to replace the YOUR_AUTHORISATION_CODE place holder with your authorisation code.

 

9. Authorisation Code Generator

Your authorisation code is calculated in your browser.
No account information is sent over the internet by this page.

 

Please enter your credentials for your AddressService in the Cloud account, then click on the "Generate My Code" button to display the code

1. How do I install the desktop client?

Download the FastAddressClient application from the AddressServer Downloads page (please note that you will need the username and password specified during registration to access the downloads page).

AddressServer Downloads

Uncompress the downloaded FastAddressClient.zip file and then run FastAddressClientSetup.exe. When prompted, allow the program to run at the "Unknown Publisher" warning.

Follow the setup instructions, choosing the default options, until the installation is complete.

fastaddressclient-installing

2. How do I sign in to my account?

The first time you run FastAddressClient you will be prompted to sign in to the AddressServer. You can also access the Sign in window from the Settings menu.

Enter your username and password, then click the Sign In button.

fastaddressclient-signin

You should then select the Master Address File (MAF) you wish to use and click OK. The uk-rm-paf-internal MAF is the dataset for which free clicks were created during registration. If you purchase a different dataset, then you will need to select it here.

An appropriate error message will be displayed if the sign in fails (please refer to the "Common errors" section below for more details).

3. How do I perform an address search?

From the FastAddressClient home page enter the required search criteria and click the Search button. The search criteria can be a postcode, full or partial address. Single character (?) and multi character (*) wildcards are also supported. Please note that separating individual address elements with a comma yields better results, for example "Downing Street, London".

Select the appropriate item from the Possible Matches text box, by double clicking on the item text. When a complete address is reached it will be displayed in the Completed Address text box.

fastaddressclient-search

4. How do I send address fields to another application?

FastAddressClient is installed with a predefined SendKeys configuration that will send address labels to the foremost window with each element output on a new line.

This section covers a step-by-step guide to setting up the SendKeys functionality. It sends keys to Notepad as a demonstration. Sending to other applications simply requires substituting the appropriate target window and key combinations for navigating between fields.

First, start an empty Notepad. You should have a screen such as the following:

fastaddressclient-notepad

Return to FastAddressClient, click the Setup icon in the toolbar and then click the Select Target Window link from the left hand options.

fastaddressclient-select-target-window

Select the window you wish to send the address fields to. In this case toggle the By Z-Order/By Title button so that Untitled - Notepad is displayed and select it, then click the Next >> button.

fastaddressclient-target-window-options

If you wanted to, you can now choose to start the target application each time address fields are sent to it by clicking the Configure Target Application Startup... button (Please refer to the online help for further information).

Click the Next >> button.

fastaddressclient-select-output-fields

Choose the fields that you would like to send to the target application. For the demonstration we will choose to send the address label and the UDPRN.

Click the Next >> button.

fastaddressclient-record-keystrokes

This page allows you to specify key strokes that are applied between each output field, such as tabs to navigate the cursor within the target application. For demonstration purposes we will change the predefined configuration to place a comma between each field.

Highlight the Final Keys column for all fields except the final UDPRN field, then click the Edit/Record Keys... button.

fastaddressclient-keystroke-recorder

Click the Clear All button, enter a comma and then click the OK button.

If the Final Keys value for the UDPRN field is not {ENTER}, then highlight the value, click Edit/Record Keys.. and repeat the above actions entering a carriage return instead of a comma.

When finished the page should look similar to that shown above.

Click the Next >> button.

fastaddressclient-sending-options

Next, choose what you want FastAddressClient to do after an address has been sent. You may select to close FastAddressClient after sending an address for example, then click the Done button.

fastaddressclient-send

Finally toggle the Send/Copy/Copy and Send button to specify a Send button, by clicking on the ... button and selecting Send from the available options.

The previous image shows a captured address ready to be sent to Notepad.

When you have matched an address click the Send button to send the address fields to the target application, in this case Notepad. The address fields will be sent to Notepad as seen in the image below.

fastaddressclient-notepad-with-1-address

5. Common errors

The most common problem is "401 Unauthorized" which indicates that an invalid username or password was entered:

fastaddressclient-error-401

A "Could not resolve host" error indicates an incorrect Host has been entered (and no such host exists):

fastaddressclient-error-unresolved-host

A "404 Not Found" error indicates an incorrect Host has been entered (it does exist but does not understand AddressServer requests):

fastaddressclient-error-404

A "MAF invalid" error indicates that an incorrect or unavailable value was used for the Dataset. Check that the user has permission to use the dataset:

fastaddressclient-error-invalid-maf

Any other errors are likely to be related to your firewall and/or proxy setup. Searching for the final part of the message online may help, alternatively email the support team with your settings and the exact error and they will be happy to help.

6. Where can I use the FastAddressClient application?

This application can be utilised in querying addresses and associated data either via a client hosted AddressServer, or the Hopewiser hosted services (AddressServer in the Cloud).

7. Why can't I Sign In using the FastAddressClient UI?

Ensure that the service is a valid one (eg, cloud.hopewiser.com.au for out hosted services) and that your username and password are as created or assigned (please note that passwords are case sensitive).

 

8. What is the Host2 setting for in the Sign In panel?

This allows the stipulation if a secondary service endpoint should the primary one be offline or unavailable. Use of a load balanced service (such as the cloud.hopewiser.com.au hosted Hopewiser service) should negate the need to make use of this.

9. How do I stop the auto-download of FastAddressClient updates?

Using the argument '--dont-check-for-updates' in a user shortcut to the FastAddressClient application will prevent the update of the application unless prompted by the user, or system-wide.

10. Can FastAddressClient be used over IPV6?

Yes it can. FastAddressClient can utilise either IPV4 or IPV6 protocols.

 

11. How can I change the appearance of addresses displayed or captured?

Changes to address presentation (how matching results are first shown to you) and captured format (how this is written to the intended target) can be achieved through the Setup facet of the application - specifically the Matching Options within. Here (including the Advanced section potentially), you should be able to find an option to suit the requirement.

12. How can I have my users capture data in a consistent way using FastAddressClient?

FastAddressClient has a setup saving capability (accessed through the toolbar). Here, you can define a processing setup you wish to be used across the department or company, store this centrally, and have this referenced through a user shortcut deployed throughout the business ('...FastAddressClient.exe X:\FACSetup.hpw - g' in the shortcut properties). You can also lock this down using the illustrated -g switch.

13. Can I change the way data is written once captured?

FastAddressClient comes with SendKeys technology allowing the traversing of most controls in most desktop target windows. These can be implemented / adapted using the Setup section Record keystrokes panel. Essentially, you should be able to recreate any keyboard navigation within this definition meaning data is written to the correct target window control given a consistent start point.

 

Mobile App

 

fastaddressmobile searchHopewiser's FastAddress mobile app makes it easy to search for postcodes and addresses whenever and wherever you are.

With FastAddress mobile you can:

  • Search the Royal Mail PAF for postcodes and premises
  • Search the Royal Mail PAF for a partial address
  • Select the address you are looking for from a list of suggested matches
  • Email or text a Royal Mail compliant address label to wherever you choose
  • Plot your chosen address on your favourite map or navigation app

It is free to download, and is available for Apple, Android and Windows Phone devices.

appstore 
googleplay 
winstore 

Once installed, simply sign-in (using your AddressServer in the Cloud username and password) to start using the service.