Introduction

Purpose of this Guide

This guide is for system administrators who plan to deploy AFD Postcode Evolution Server for the Windows platform. It details the installation and configuration options available to enable customisation of the service, and also provides information to assist the upgrade of existing AFD Postcode Everywhere installations.

This document contains new terms specific to this product or service. These terms are explained in the Glossary section.

Quick Setup

Existing users of AFD Postcode Everywhere must read the full guide to ensure upgrade compatibility, however, new AFD Postcode Evolution users who do not have Postcode Everywhere can follow these simple steps:

  1. Download Postcode Evolution from http://www.afd.co.uk/evolution/
  2. Install the service on a Windows Server with access to the Internet
  3. Add the serial number and password from the Licence Certificate using the "Postcode Evolution Server Management" program

Product Overview

The AFD Postcode Evolution Server is a flexible new solution provided by AFD Software that allows access to a variety of data-sets, including Postcode Plus address data, BankFinder information for UK and Republic of Ireland Banks, and Names & Numbers edited electoral roll information.

The service is designed to be installed on servers providing data to network clients, or multi-user applications running directly on the server through a HTTP/XML interface.

Installation and Setup

Downloading and Installing the Service

The most up to date version of the AFD Postcode Evolution installer is available for download from http://www.afd.co.uk/evolution/. It requires an operating system capable of running Windows services, i.e. (Windows2000 / XP - Server 2003 / 2008). The installation includes Postcode Plus and BankFinder address and Bank data, although access to each of these data- sets is controlled through a data licence. Additional data not included in the standard installer can be provided by AFD as an additional installation.

Important: If installing on a server with an existing installation of AFD Postcode Everywhere or an existing DLL integration with AFD software, please pay special attention to the following section titled Ensuring Compatibility with Existing Integrations. The installer prompts for a location where Postcode Evolution should be installed (default is C:\Program Files\Postcode Evolution\ ). When complete, the installer will run the Postcode Evolution (PCE) Management program where licence details can be added, and the port number for the service can be configured.

If the port number shown in the PCE Management program does not conflict with any existing services, use the Start button to start the service listening on that port.

Once provided with valid licence details, the PCE Management program on the server will need to connect to the Internet and establish a connection with the AFD Postcode Evolution Network (hereby referred to as PCE Network) for activation. See the section Configuring the Service for more information.

Ensuring Compatibility with Existing Integrations

The AFD Postcode Evolution Server can be used as a replacement solution to the Postcode Everywhere XML service, as well as direct integration with our Windows DLLs.

In order to avoid or minimise any disruption to existing applications using either of these two legacy integration methods, the Postcode Evolution Server has been designed to be backwards compatible. This means that, with minimal configuration and setup, existing applications using either the Postcode Everywhere XML interface or Windows DLL interface do not need to be altered and can continue to work with Postcode Evolution. Please read the following section relevant to the integration method in use by the application.

Existing Postcode Everywhere Installations

The AFD Postcode Evolution Server is based on Postcode Everywhere technology and is therefore a direct replacement service, and compatible with existing applications that have been designed for Postcode Everywhere.

It is recommended that the existing Postcode Everywhere service is stopped and disabled in the Windows Services Control panel prior to installation so that there is no conflict between the two services.

Applications designed for the existing Postcode Everywhere service will send requests to Postcode Everywhere on a specific port number. The new Postcode Evolution service should therefore be set to listen on the same port number to avoid having to modify application code. By default, both Postcode Everywhere and Postcode Evolution will be installed on port 81, however, if Postcode Everywhere has been set to listen on a different port, the PCE Management program for Postcode Evolution can be used to change the port number to match that of the Postcode Everywhere port.

Another important feature of the PCE Management program is the ability to set a default serial number for the service. Unlike Postcode Everywhere, the new Postcode Evolution Server requires a serial number and password presented on every query in order to return data.

The Change Default button will prompt for a serial number and password to be used as the default serial number for the service. This is crucial to support any legacy applications designed for Postcode Everywhere, which it does by appending the default serial number and password to any queries sent to the service which do not have a serial number in the request.

Since this sets the default serial number this feature cannot be used for multiple serial numbers on the same server, so it is always preferable to have the serial number and password supplied by the application itself. This option should only be used if existing applications rely on Postcode Everywhere and cannot be amended, new applications should not set this value.

Existing Windows DLL Integrations

The Windows DLL interface for Postcode Plus based products is provided through either a native library called PCPV232.DLL or a COM / ActiveX library called PCPINETX.DLL . To provide backwards compatibility with these DLLs, the Postcode Evolution Server supports an additional legacy compatibility layer which is provided as a separate installation.

The AFD Postcode Evolution Legacy installer can be downloaded from http://www.afd.co.uk/evolution/ along with the installation program for the AFD Postcode Evolution Server.

To ensure the compatibility system is set up correctly, please carefully follow the installations procedure below:

  1. Install the Postcode Evolution Server from the above link and start the Postcode Evolution service using the PCE Management program (this should open automatically following installation)
  2. Add the correct serial number and password provided with the renewal letter or email using the PCE Management program
  3. Set this serial number to be the Default Serial Number (using the Change Default button in the PCE Management program) 4) Install the AFD Postcode Evolution Legacy software from the link provided above

The installation may request a restart of the server. If the application is written in .NET and uses the COM / ActiveX DLL, the application will need to rereference the PCPINETX.DLL component and be re-compiled due to .NET interoperability requirements.

If there is any uncertainty regarding the integration method being used, or any of the above installation instructions, please contact AFD Support for assistance.

Configuring the Service

The AFD Postcode Evolution Server runs as a Windows Service called AFD Postcode Evolution Server , which can be configured using the PCE Management program. This program will automatically run following installation, however, this can also be run from the Postcode Evolution program group in the Start menu.

Adding a Product to the Service

The PCE Management program is used to allocate a serial number held on the PCE Network. Serial numbers are allocated using the Add New Serial Number button, allowing entry of the Serial Number and Access Password, which are provided on the Licence Certificate.

This will contact PCE Network and validate the authentication details before updating the active serial number list. Each server requires an available Server Slot on the PCE Network. If the program returns the message No Free Server Slot when first adding a serial number, please contact AFD to discuss additional servers, or initial server setup.

The PCE Management program will confirm if the serial number has been added successfully, and will then display the licence information for that serial number, as demonstrated in the image:

Synchronisation

Once a serial number has been successfully added, the AFD Postcode Evolution Server will immediately synchronise with the PCE Network over the Internet in order to obtain licence information, including an initial credit allocation where appropriate.

The Postcode Evolution Server registers the Server Identity (a unique code that defines a physical server) with the PCE Network, whilst at the same time reserving a server slot. Each physical server can hold multiple serial numbers to allow different operation modes to be implemented on the same physical server.

The Postcode Evolution Service supports two different modes of licence operation, Pay-per-click mode and Unlimited mode.

Pay-per-click mode

Data-sets available for use with this mode of operation require the server to have credits available in order for data to be returned. In this mode, the Postcode Evolution Server installed on the server contacts the PCE Network and, subject to available Credit, downloads a number of credits to the local server.

These credits are allocated individually per serial number, meaning that individual servers and serial numbers can be set to obtain different quantities of credit whenever they synchronise with the PCE Network. This feature is useful if implementing both a Production and Development server, for example. Please contact AFD Support if custom credit quantities are a requirement.

The installed AFD Postcode Evolution Server holds a local credit pool which is topped up with credits from the PCE Network. These credits are downloaded (as required) from an AFD server whenever synchronisation occurs, and requests made to the service consume these credits locally. Therefore the only contact with PCE Network is when a synchronisation has been initiated, either manually from within the PCE Management program, according to a pre-determined schedule or because the number of credits has dropped to a certain minimum level (see Synchronisation Settings below).

Unlimited mode

Data-sets available in Unlimited mode do not require credits (either on the PCE Network, or the local server) in order to return data. Requests to the server are logged by the system and transaction logs are synchronised to the PCE Network regularly.

Synchronisation Settings

The synchronisation is controlled by four settings, which are primarily concerned when the service is used in Pay-per-click mode, although the Synchronisation Frequency is applicable in both operational modes.

  • Credit Target

    Specifies the number of credits that the local credit pool will be topped up to whenever synchronisation occurs. The default value for this setting is 1000 credits.

  • Credit Threshold

    When the number of credits in the local credit pool is lower than this value, a synchronisation with the PCE Network is triggered. The default credit threshold is 100 credits.

  • Synchronisation Frequency

    In addition to the synchronisation being triggered by the credit threshold, synchronisation is also performed on a regular basis. The service will attempt to synchronise once a day by default.

  • Synchronisation Max Interval

    If the service has not synchronised with AFD servers for the period of time specified as the max interval , the service will no longer return data. By default the maximum interval is 30 days.

Contact AFD Support if there is a requirement to change to non-default values of these settings.

Checking Service Status

Service Status

The Postcode Evolution Server includes a status function that is intended as a way to check the server is accessible. The status function returns an OK message when accessed. It is useful when used by a server monitoring program as it will not consume credits.

The status function can be accessed at the following location on the server:

http://localhost:81/status.pce.

Testing the Server

Existing applications can be used to test the service is operational, but for new application integrations we recommend developers use the Common APISoftware Development Kit (SDK) to create an example application for testing. The Common API SDK is available at http://www.afd.co.uk/commonapi/.

The SDK includes a programming manual for the Common API, as well as a code generator application, which can create sample code or projects in many common development languages and environments to demonstrate the core API functionality.

The XML development method option within the code generator application will require the serial number and password from the Licence Certificate and the location of the local Postcode Evolution Server, e.g.:

If there are any problems testing or integrating with the server, contact AFD Support at support@afd.co.uk or on 01624 811712.

Glossary

  • Serial Number - A six digit number, provided on the Licence Certificate, represents a software product licence. A single serial number has the ability to license more than one data-set (for example, Postcode Plus as well as BankFinder data). In addition, the mode of operation of the Postcode Evolution Server is applied on a per serial number basis.
  • Access Password - An alphanumeric code provided on the Licence Certificate used for authentication purposes. All requests made to the local server will need to include this password along with the serial number, unless a default serial number and password has been set (when supporting legacy applications that utilise Postcode Everywhere). The password is provided with the product Licence Certificate.
  • Credit - Unit of transaction use required for Pay-per-click operations. In Pay-per-click mode, every request to the service requires credit, and different products may use up different amounts of credit. A master credit pool is held on the PCE Network, and a local credit pool is allocated and topped up on each server using this operation mode.
  • Server Slot - The server slot holds the licence for a serial number, and there can be multiple server slots if more than one server is required. Each physical server must be licensed for use with a server slot before synchronisation with the PCE Network can occur.
  • Server Identity - This is a unique code that identifies a physical server which AFD Postcode Evolution Server has been installed on. A server identity can hold more than one serial number.