W1.8 - Configuring the findIT S2 Interface – Software Support

matchIT Web Index

The ControlConfig.xml file, by default found in the ‘config’ sub folder of the findIT S2 installation, controls the content of the findIT S2 Web UI. Most elements are configurable, from cosmetic placement of controls to the fields of information you need to enter or return when considering matches. Each section of the ControlConfig.xml file, and what it controls, is described in detail below.

New Entry Settings

In the case of an install for MS Dynamics integration, the first section of the Control Config file is the <newentrysettings> node. This controls whether or not the ‘Add New’ button is displayed on the findIT S2 Web UI form (which when clicked will bring up the ‘Add New’ Dialog. The button can be enabled / disabled by setting the enabled="true" attribute accordingly. It is also possible with this node to specify which actions are available (as radio buttons) on the ‘Add New’ Dialog, namely Add as Contact, Lead or Account. There are again enabled / disabled in the same way. The <addascontact> action is a special case in that it is possible to specify a parent account to link to when adding a contact, so it is necessary to specify the data source set up in the findIT S2 Service that contains this data. By default, this is set to parentdatasourceid="3".

Button Shortcuts

The next node in the ControlConfig.xml file is the <buttonshortcuts> node. Here it is possible to specify what keys execute the different buttons / controls on the findIT S2 form when holding down the ‘Alt’ key on the keyboard. These can be amended to suit the user.

Modules

The <modules> section of the configuration determines what findIT S2 UI module are enabled. It is possible to enable / disable the <addressing> modules (explained further on), as well as determine whether AJAX is enabled / disabled for both the <matching> and <addressing> modules.

Unique Fields

This node is used to define text boxes that can be used to do unique searches on particular fields of particular data sources. The <uniquefield> tags can contain a collection of sub <ds> tags that define the mappings of the unique field for specific data sources –

</uniquefield>

</uniquefields>

In the example above there is a single mapping for the unique field in question for data source ‘1’ – The field to query is the ‘ID’ column in the ‘Contacts’ table. You can have multiple unique field lookups.

Contact and Address Input Fields

The next 2 sections of the configuration file, <contactinputfields> and <addressinputfields>, control the text boxes on the form used to input search data. Both the contact and address input field nodes share the following common parameters :

name – This is the reference name for the particular control, these are mapped to specific matchIT fields and should not be changed.

label – This is what appears beside the input box or as a watermark inside the box itself. This describes what data element is being captured to the user.

enabled – This controls if the box is actively displayed on the screen.

interactive – This allows you to turn on or off the interactive functionality outlined in the modules section independently. The modules section has priority, so this parameter allows you to turn off interactive lookup if it was actually set to true in the relevant modules section.

For the address input field node, there is an additional parameter

addressfield – This is how we map the address fields to the US address correction service, these will be set up for US address correction users by default.

The <addressinputfields> section also contains another type of node, the <addressingserviceselector> node, which is described in more detail in the Addressing Modules section.

Results Grid

Within the <results> node it is possible to specify multiple <resultsgrid> nodes, each of which correspond to a tab in the results pane of the findIT S2 UI. A <resultsgrid> node takes the following parameters –

datasource – This attribute can be used to specify a particular data source for this form to query. If left blank, all data sources will be queried.

title – This determines how the data set tab in the findIT S2 screen is labelled.

tabcolor – This determines the colour of the text on the grid tab.

enabled – True/false, you can choose to hide a tab you have set up as required.

The only other type of node in the <resultsgrid> section is the <gridfield> node. This node is used to define a results column in the given results grid. All <gridfield> nodes share the following common attributes -

name – This is the name of the field you wish to display in the column. It should match the name of the XML attribute that is returned from the FindMatches() Web service method. If a field is specified that doesn’t exist, a blank value will appear.

type – This determines the type of column that is displayed. The types available are FIWResultsGridColumn (a standard column), FIWLinkedResultsGridColumn (a hyper-linked column) and FIWRelevanceMeterGridColumn (a column that displays a relevance meter).

header – This is the title that will appear at the top of the column.

width – This controls the width of the particular column, by default setting it to 0 will auto-size the column width according to the data displayed.

enabled – True/False, display or hide the configured column.

When using a type FIWLinkedResultsGridColumn column, it is necessary to also specify the following attribute -

LinkUrl – This is the value that is used for the ‘href’ of the rendered ‘a’ tag. It is possible to specify a JavaScript call as well as a standard URL. It is also possible to use the field value of the column in the URL itself, by using the {0} place holder, as per the following - "JavaScript:GoToDetail('contact','{0}')"

Output Fields

The final section in the config file, the <outputfields> node, contains definitions for hidden fields on the form that contain cleaned and normalised data relating to the search data entered into the form. This cleaned data is produced by taking the input data and processing it with the matchIT API (through the findIT S2 Web Service), and US Addressing Web Service if installed. The cleaned fields are then used, in the case of a Microsoft Dynamics Implementation, to be entered into a system. The following attributes should be specified for an <outputfield> node.

name - The name of the specific mapping against the findIT S2 information. By default a complete list has been added to ControlConfig.xml.

label – The label property is for internal use, and has no functionality relevant to the user.

enabled – This property specified whether or not to output the hidden field to the page.

type – Internal mark up to designate where the data element is returned from, these should remain unchanged.

Addressing Modules

The addressing modules, although part of the modules section, require an explanation on their own as the subject is quite in depth. There are currently 3 modules on offer – US addressing, UK addressing and ROW addressing, each with their own configuration node.

For US addressing (only available to US customers) there are simply 2 boolean settings, enabled and interactive, that specify whether the addressing module is turned on, and whether the fields are Ajax Enabled.

For both UK and ROW Addressing, you can enable / disable addressing through the enabled attribute. Both the <ukaddressing> and <rowaddressing> nodes contain the same following sub node –

In the case of UK addressing, the dataset and ipaddress attributes should not need to be changed from their default values of PAF and localhost respectively – the account and client attributes are not used in this case.

In the case of ROW addressing, the dataset and ipaddress attributes should again not need to be changed from their default values of WORLD ADDRESSING and blank, however in this instance you will need to fill in the relevant account and client attributes, encrypted using the findIT S2 Administration Program – If you provided these details on installation, they should already be populated.

At this point it should be noted that, in the case of UK and ROW addressing, it is necessary to enable the <addressingserviceselector> node in the <addressinputfields> section. This node enables a control on the form with a country drop down and lookup button necessary to perform the address validation. The <addressingserviceselector> node has the following attributes –

matchitfield – This should not be changed, as it is used by the service to indicate that it is of type Country.

enabled – Specifies whether or not the control is enabled or hidden.

defaultcountry – This property sets the country in the drop down list that will appear at the top, and will be defaulted to.

enabledefaultcountrycookie – This property can be used to specify that, whenever a selection is made in the drop down, the selected country becomes the new default, and overrides the defaultcountry This value is persisted in a cookie and preserved between visits to the site.

enablebydefault – This specifies whether or not the lookup button is enabled by default to begin with, so that if any issue occurs on the form, the control can still be used to perform address validation.

matchIT Web Index