The Postcode worker provides services for performing an address look-up using a UK postcode.
There are many different postcode lookup systems. Some will use an external web service, others database queries. Each of these different systems are made available to the Postcode worker as "providers". Providers are written in (server-side) JavaScript, and it is the provider that actually performs the postcode look-up. The worker itself provides a standard interface for invoking these plug-in providers.
Alongside the Postcode worker, the iCM Forms Designer includes an Address Lookup field type. This field type provides the interface into which a user can enter a postcode, perform a search, and select the relevant address from the results.
By default the lookup field performs a search using the postcodeSearch method. The addresses returned by the field are stored in a variable called FIELDNAME_ADDRESS. See postcodeSearch (postcode, provider) for more information.
Worker Configuration Properties
These are the standard configuration properties that can be set for the worker. In the majority of cases you will only need to set the defaultProvider and providers properties, the rest can be empty strings/arrays.
| Property | Type | Description |
|---|---|---|
| defaultProvider | String, required | The name of the provider that will be used if one isn't specified in the postcode lookup request (ie if you set one here the address lookup form field will "just work") |
| providers | Array, required | An array of the provider names that should be set in the postcodeSearch method call or defined in the form designer's Address Lookup field Implementations must exist for each of the providers in the API Server's Postcode worker providers directory |
| providersDir | String, required | The directory in which the pre-installed provider implementations can be found Its default value, providers, is within the worker distribution and should not be changed |
Additional properties can also be included, depending upon the provider you are using. The properties for the built-in providers are:
| Property | Type | Description |
|---|---|---|
| EndPoint_ApiClientConfig | Object | If you are using the End Point provider you can provide an apiclient configuration object (to set an apiKey, serverid, user/password etc if needed) |
| EndPoint_Name | String | If you are using the default End Point provider, this is the name of the End Point that will be called by it |
| EndPoint_Worker | String | Either ajaxlibrary or serverlibrary, depending upon where your End Point is deployed |
| EndPoints | Array of objects | An array of End Point provider detail objects. The properties set for each provider override those defined above |
| EndPoints[n].Provider | String | The name of this provider that should be set in the postcodeSearch method call or defined in the form family's Address lookup field |
| EndPoints[n].EndPoint_Name | String | The name of the End Point that will be invoked when this provider is used |
| EndPoints[n].EndPoint_Worker | String | The worker this End Point is deployed to |
| EndPoints[n].EndPoint_ApiClientConfig | Object | Any configuration to supply to the End Point |
| IdealPostcodes_Key | String | If using Ideal Postcodes, the API key supplied with your account |
| MyGovScot_callertoken | String | If using MyGovScot, the name of the user used to authorise the request |
| NLPGAddressDB_Datasource | String | If using an NLPG address database, the name of the datasource to use in the query. The default datasource (usually iCM) will be used if none is specified |
| PostcodeAnywhere_Key | String | If using Postcode Anywhere, the API key supplied with your account |
| PSMA_apikey | String | An API key provided by GOSS so the worker can access the GOSS Postcode Lookup Service (these are unique per environment) |
| PSMA_url | String | The URL of the GOSS-hosted postcode lookup service |
Example
{
"name": "postcode",
"instances": 4,
"defaultProvider": "PSMA",
"providers": ["Example", "EndPoint", "PSMA"],
"EndPoint_Name": "Tests.postcodeHandler",
"EndPoint_Worker": "serverlibrary",
"EndPoint_ApiClientConfig": {},
"EndPoints": [{
"Provider": "local",
"EndPoint_Name": "Tests.postcodeHandlerLocal",
"EndPoint_Worker": "serverlibrary",
"EndPoint_ApiClientConfig": {}
}, {
"Provider": "national",
"EndPoint_Name": "Tests.postcodeHandlerNational",
"EndPoint_Worker": "serverlibrary",
"EndPoint_ApiClientConfig": {}
}],
"PSMA_url": "http://the-url",
"PSMA_apikey": "17ED5F1F-XXXX-XXXX-XXXX-6D653E263AF5"
}
In the example configuration above, if no value is entered into the Provider property of the form designer's Address Lookup field, the "PSMA" provider will be used.
If the field has "EndPoint" set as the provider, the
To use the
API
listProviders()
postcodeSearch (postcode, provider)
Share this page
