AFD Robot API makes using address management and bank validation in .NET easy, minimising your work to get an integration up and running quickly, while also providing full flexibility to customise it to your requirements.

Introduction

Robot automatically configures itself for many Windows Forms minimising the work you need to do as a developer to get AFD Software working with your application.

This guide is intended to assist you in getting started with using Robot with Windows Forms. It is recommended you read this guide first and then refer to the main manual for advanced settings, if desired, once you have it working.

If you wish to integrate a non-WinForms application or in the backend of any application you should refer to the other .NET API Quick Start Guide instead.

Setup

To use AFD Robot API you first need to install an AFD product (Windows only) or have access to an Evolution server (Java as a client is then completely platform independent). For Windows development and testing you can download data-restricted evaluation products from our website's evaluation page.

To use AFD Robot API in .NET simply add a Reference to your project to our class library (AFD.API.dll). To do this right click the References item under your project in Solution Explorer select “Add Reference”, and use the Browse Tab to browse to the library file.

Adding to your Windows Form

You can quickly and easily add Address Management functionality to your application with the following steps:

  1. Add the following line to the top of your form’s .cs file:

    using AFD.API;
    
  2. In the Form_Load method of your form add the following line of code:

    Robot robot = new Robot(this);
    
  3. If using an evolution server rather than a locally installed product set the Authentication property to an instance of the Authentication class for your server, e.g.:

    robot.Authentication = new Authentication("http://myserver:81", "333333", "password");
    

    You should replace myserver:81 with the name of your server and port, 333333 with your AFD Serial number and password with your password.

When you run your application Robot will attempt to identify address fields on your form. If you type a postcode into any text box on your form you will be prompted to select the correct address for insertion if the user of your application wishes to do so.

In most cases you will want to customise this depending on your requirements to trigger the lookup from a field and button on your form, insert non-address elements etc. and potentially even obtain fields that you do not display on your Form. The following sections detail the options available to do so.

Customisation of Field Mappings

If you require to insert a field on your Form that is has not been detected by Robot or you need to tweak or alter the fields inserted you can easily do this by using the Methods of the Robot.Mapping object.

Robot.Mapping.Add

To add or replace a field mapping for a control on your form, e.g. a TextBox, use the Add method. For example if you have a TextBox Control named “txtCensation” that you want to use for the Censation Code, simply add the following line after instantiating the robot class:

robot.Mappings.Add(txtCensation, "CensationCode");

You can additionally specify the following additional parameters to the Add method:

  • UpperCase - (Default false) Specify that the field should be inserted in Upper Case
  • Replace - (Default true) Specifies that any existing value in the TextBox is replaced (if False the field is not inserted unless the field is blank Lines - For use when you use the generic “Address” field with a Multi-line TextBox to specify the number of lines that TextBox contains.

Robot.Mapping.Remove

If you wish to remove a mapping for a field that Robot has mapped that you don’t want included, simply pass that Control to the Remove method: For example if you don’t want a field txtStreet mapped:

robot.Mappings.Remove(txtStreet);

Robot.Mapping.Clear

This method clears all Mappings and is useful if you wish to change mappings substantially as you can then add each Control you wish to Map yourself using the Add method.

Mapping different Containers on the same Form

When you pass a Form, or keyword this, to Robot it will attempt to auto-detect all Input controls on that Form.

However if you have multiple addresses on the same screen, e.g. a Shipping and Billing address and wish these to be detected separately, simply initialise Robot twice with each of the Containers (e.g. a Frame or Panel) rather than the Form itself.

For example:

Robot robotShipping = new Robot(fraShipping);
Robot robotBilling = new Robot(fraBilling);

Triggering Robot from a Button on your Form

By default Robot will auto-detect when you enter a postcode into any field in your application and display matching addresses for the user to choose from.

However to provide full fast-find functionality you can trigger Robot from your own Button on your Form. To do this simply carry out the following steps:

  • Declare the Robot instance at Form level rather than in Form_Load. e.g. place “Robot robot;” above the Form_Load method.
  • In Form_Load change drop the Robot object name from the line that instantiates Robot so that it uses the Form wide variable, i.e. simply use “robot = new Robot(this);”.
  • In your Buttons Click event, use the following line to trigger a fast-find lookup from the contents of a TextBox called txtLookup when that button is clicked: robot.Find(txtLookup.Text, Operation.FastFindLookup);

Robot wlll then insert the selected address in the same way as when Robot auto-detects the Postcode.

If you would prefer Robot to only trigger from your own button when you create an instance of the Robot class use the AutoLookup parameter to disable automatic lookup, e.g. “robot = new Robot(this, true, false);”. (The middle parameter is used to disable automatic configuration of Form fields).

Additional Options for Robot

Robot contains many options for customisation, for example you can control the dialog position and size, its title, icon and other aspects of the Form. You can also carry out a search in the same way as the Lookup above. For full details of these please see the main Robot .NET API guide.

Account and Card Validation

Robot also contains support for Bank account and Debit/Credit card validation if you have BankFinder. For these please see the .NET API Quick Start Guide as there use is not Windows Forms specific.

Integration separate from your Interface logic

Even when displaying a Windows Form you do not need to use Robot in this way. If you prefer to integrate at the backend or manually set and retrieve the fields required you can also do this. For full details please see the .NET API Quick Start guide.