Web service implementation overview

The Bank Wizard web service works with the Bank Wizard core to validate bank account details for a wide range of countries. Bank Wizard has been specifically designed to be flexible so that new countries can be implemented and existing country information enhanced without having to upgrade the core software. For most checks you use the Validation service. However to return the metadata, use the Meta service and to search the data, use the Search service.

Your application passes the required data to the relevant Bank Wizard web service in XML format. The web service then uses the Bank Wizard core to validate this input. The core may return a number of conditions of varying severity:

• Fatal indicates a serious application problem, such as expired Licence Key. Typically, these are returned during initialisation and are included in the log file
• Error indicates that the account details are invalid
• Warning indicates that the account details may be invalid within the context of your application; you must decide how your application should react
• Information provides additional information conditions that your application must decide how to react to.

For the Java web service, any messages returned by Bank Wizard during initialisation are included in the log file. The messages are in the format Error (#) -Message. For example, Error (3) - The Licence Key cannot be found or read.

In addition, the core can return data such as the bank or branch address details or the transposed account information. This data is then passed from the web service to your application in XML format.

The validation and institution data are stored within an external Database Table File (DTF). You must update the DTFs regularly to make sure you always have access to the most recent data. Typically, you use the Online Update Service to update the DTFs.

Monitoring the Java web service

During normal operation you need to monitor the web service to make sure there are no problems with the database table files or the licence key.

You do this by checking for status conditions that are returned by the Bank Wizard core. These status conditions are displayed on the console and added to the log files, rather than returned via the web service.

Typically these conditions are returned when Bank Wizard is initialised, however some can be returned during function calls.

For example, to check for licence expiry, you monitor the log file for Error (3) The Licence Key cannot be found or read.

The status conditions that can be returned are:

• all fatal conditions
• Error 300 + country number (BWI_E_EXLIC) - The licence key for country n has expired
• Error 1 + country number (BWI_E_TABLE_MISSING) - The database table file for country n cannot be found or loaded
• Warning 1 + country number (BWI_W_30DAY) - The licence key for country n will expire within 30 days

Implementing Dynamic Update with the web service

To update the DTFs without stopping the web service, you use Data Manager to enable Dynamic Update. (For more information, see the Data Manager documentation.) You use bwiabsolute.properties to specify how often dynamic update runs. By default, this file is in the classes directory within the web service installation directory.

Use BW3TableSetUpdate to specify the time between updates. You specify this in minutes. It must be between 15 and 720 (12 hours).

...

# Property Name : BW3TableSetUpdate

# Desc          : The time in minutes when the data tables are updated via the dynamic update feature

# Value         : The time in minutes, must be between 15 and 720. if BW3TableSetUpdate is invalid/missing the default is 60

#                 See Bank Wizard API documentation on using dynamic update, BWI_R_TABLE_SET and the configuration file

#

BW3TableSetUpdate=300

...

You must stop and restart the web server for these changes to take effect.

Hints and tips

If the Bank Wizard web service is not working or does not use the correct tables, check that:

1. You have enabled dynamic update within Data Manager.
2. The configuration file, bwcfg.tbl, exists and has not been corrupted.
3. The correct version of the database table files exist.

The database tables have the letter specified in bwcfg.tbl appended to the name, for example bwiuka.tbl.

See also

• Accessing the Bank Wizard web service
• Available services
• Bank Wizard web service
• Fatal conditions
• System logging
• When conditions can occur