W1.7 - International Address Verification WCF Interface – Software Support

matchIT Web Index

As well as the SOAP based addressing service for UK and ROW address correction, there is also a strongly typed WCF based interface available. Integration into certain CRM systems may be better suited to this interface. The WCF based service can be referenced on the following URL –

http://{your local domain}/findITS2AddressingService/InternationalAddressVerifyService.svc

Address Formatting

For a fuller explanation on this interface and its types / methods, please refer to Appendix F.

It is possible to specify custom formatting for the address elements that are returned as part of a Process Result Item. This is controlled through xml configuration files that, by default, are configured in the Web.config file of the service to exist in the ‘Formatting’ sub folder in the service installation directory. To apply a custom formatting configuration to a web service result, you need to pass the name of the configuration file (without the .xml file extension) in the ‘FIS2AddressLineFormatConfig’ parameter of the Process Options argument. Each Process Result Item returned from the service will contain information about the custom formatting that was applied to the result in the ‘FIS2FormattingInfo’ property.

The structure of an element in an address line formatting configuration file is as follows (A default example configuration is installed to the Formatting directory with S2, so you can also refer to that) –

<countries>United Kingdom|Default</countries>

<address1>{BUILDINGNAME} {PREMISENUMBER} {STREET}</address1>

<address2>{LOCALITY}</address2>

<address3>{ADMINISTRATIVEAREA}</address3>

<address4>{POSTCODE}</address4>

</mappings>

</formattingConfiguration>

Note that it is possible to specify a pipe delimited list of countries to save repetitive definitions. Also note that there is a special case ‘Default’, which is used if the country of the address in question is not defined in the configuration. If no ‘Default’ is defined, then the standard formatting provided by the addressing engine will be used, as will be the case if no custom formatting option is provided in the call to the service.

A complete list of the address fields that can be configured is included in the example formatting file. By default, if a custom formatting configuration is used to format a returned address, any elements that are not defined in the configuration are returned blank.

Character Translation

It is possible to enable character translation within address elements that are returned as part of a Process Result Item. This is controlled through an xml configuration file that, by default, is called CharacterTranslationConfiguration.xml and is located in the Translation sub folder. The name and location of this file is configured in the Web.config file, which can be changed if necessary. To activate character translation, the XML node ‘active’ must be changed to ‘true’.
To add or remove characters to translate and the characters that they must be translated to, add or remove ‘translation’ nodes within the translations area.

By default, the XML file contains a list of nodes that will translate certain foreign characters to their English equivalents.

The format of the XML file is as follows. Changes made to the XML file will not take effect until the findIT S2 service is restarted.

<config>
<active>false</active>
<translations>
   <translation in="à" out="a" countries="" />
   <translation in="ê" out="e" countries="" />
   <translation in="ì" out="i" countries="" />
   <translation in="ò" out="o" countries="" />
   <translation in="ù" out="u" countries="" />
   <translation in="À" out="A" countries="" />
   <translation in="È" out="E" countries="" />
   <translation in="Ì" out="I" countries="" />
   <translation in="Ò" out="O" countries="" />
</translations>
</config>

To restrict certain translations to addresses of specific countries, add those country names to the countries attribute, separated by a comma. E.g. the following translation would only be carried out on addresses from France or Spain.

<translation in="à" out="a" countries="France,Spain" />

By leaving the countries attribute blank, the translation will be carried out on all addresses.

CRM Field Translation

It is possible to enable CRM field translation within addresses that are returned as a Process Result Item. The field translation process will translate strings within any specified field. This is controlled through an xml configuration file that, by default, is called CRMFieldTranslationConfiguration.xml and is located in the Translation sub folder. The name and location of this file is configured in the Web.config file, which can be changed if necessary. To activate CRM field translation, the XML node ‘active’ must be changed to ‘true’.

To add or remove field translations, simply add or remove ‘translation’ nodes within the translations area.

By default, the XML file contains no translation nodes.

The format of the XML file is as follows. To restrict a translation to addresses of a particular country, add the country code to the countryCode attribute of the translation. Otherwise, leave countryCode blank to ensure that the translation is applied to all addresses, regardless of country.

<active>false</active>

</translations>

</config>

Changes made to the XML file will not take effect until the findIT S2 service is restarted.

Please note, the loquatevalue attributes are case sensitive and must exactly match the strings in the Process Result Item that they are intended to replace.

Address Service Usage Logging

With the WCF Interface, it is also possible to monitor the usage of the service through log files. By default, logging is disabled – the configuration of the logging is controlled through an xml file that is pointed to in the Web.config of the addressing service, which by default is ~/Logging/LoggingConfiguration.xml.

The configuration file itself is commented to give a description of each setting (all of which

should be self-explanatory), complete with a listing of available fields to use where appropriate, however below is a further description of each setting.

enabled – This setting simply determines whether the logging is on or off. By default logging is disabled.

logFilePath – This setting is used to specify the path to use for the log file. It is blank by default, which will cause the file to be written to the common application data folder within the sub folder structure findIT S2/Logs. You can use this setting to specify a custom path to write the file to (note the path should include the file name). In doing this, it is important to ensure that the directory in question has appropriate permissions on it to allow the user that the service is running under to write to it.

maxQueueSize – This is the max number of service call logs to queue up in memory before writing to disk. By default this is set to 1000, however this can be increased / decreased as necessary. There will be a performance overhead in processing the in-memory queue, which is processed on a call to the service that causes the queue limit to be hit, so this needs to be considered when setting the value.

The following three settings are related to the archiving of the log files. To save disk space, the text based log file will be archived to a compressed zip file according to the configuration settings below. There is a background thread that runs every 60 seconds when the service is active to verify the these settings against the current state of the log file, and take the appropriate action.

logArchiveTimeSpan – This setting is used to specify the minimum time span that should have elapsed between the first call recorded in the active log file and the current time. It is possible to set individually the number of days, hours, minutes and seconds to elapse between archiving each log. Whether or not the file gets archived due to this setting being satisfied is also dependent on the following settings, lowerLogFileSizeLimit.

lowerLogFileSizeLimit – This setting is used to define the minimum size (in bytes), that the log file must be in order to be archived. If this file size is not achieved, then the file will not be archived, regardless of any other archive setting.

upperLogFileSizeLimit – This setting is used to specify the maximum size that a log file can grow to before being automatically archived. If when checked the log file has exceeded this size, the file will be archived, regardless of any other setting.

inputFields – This setting is simply used to specify the input fields to store in the log that were submitted to the service call. An exhaustive list is included in the default logging configuration file.

outputFields – This setting is simply used to specify the output fields to store in the log that were returned to the client from a service call. An exhaustive list is included in the default logging configuration file.

The structure of the log file is set out so that each call to the service is logged line by line. Each line is tab delimited, and will contain information such as the time of the call, the IP address of the calling client, the windows user context that the call was executed under and the input / output fields that were specified to be output in the logging configuration file.

Configuring UK and ROW Addressing Formats

With the range of different formatting and casing rules for different countries, it is necessary to allow things to be configurable at a country level. The following 2 files allow that to be possible.

AddressFormatConfig.xml

This file controls the position that elements of a corrected verified address a placed in on the form. It is found in the config directory, and referenced in the Web.config file of the findIT S2 website. The following is an example of the configuration for UK addresses –

<country>United Kingdom</country>

<Address1>{BUILDINGNAME} {BUILDINGNUMBER} {STREET}</Address1>

<FlatNo>{SUBBUILDING}</FlatNo>

<Town>{LOCALITY} {POSTTOWN}</Town>

<Region>{COUNTY}</Region>

<Postcode>{POSTCODE}</Postcode>

</mappings>

</formattingConfiguration>

The country node specifies the country that this format applies to – this needs to match the name of the country in the drop down in the UI. The mapping nodes specify which elements in the verified address map to which fields on the form. The name of the node needs to match the field name it is intended for. As can be seen above, the corrected building name, building number and street are all mapped, separated by a space, to the address line 1 field on the form.

There is also an entry in the configuration file for a country labelled ‘Default’ – This is the format that will be used if an entry for a particular country does not exist.

CasingConfiguration.xml

This file controls the casing for each element in a verified address. It is found in the root directory of the findITS2AddressingService, and is referenced in its Web.config. The following is an example of the casing format for a UK address -

<country>United Kingdom</country>

<street>Proper</street>

<depstreet>Proper</depstreet>

<deplocality>Proper</deplocality>

<locality>Proper</locality>

<posttown>Proper</posttown>

<county>Proper</county>

<postcode>Upper</postcode>

</casingOptions>

</casingConfiguration>

The country node specifies the country that the casing applies to, and the enabled node is used to switch the configuration on or off. The casingOptions sub nodes need be named according to the corrected element that they apply to – Available options are Upper, Proper and Lower. There is also a default settings entry.

matchIT Web Index