W1.3 - Using the Administration Program

Once you have configured the XML configuration file to your specification, it needs to be loaded into matchIT web using the administration tool. 

This can be accessed via the shortcut in the ‘Start’ menu that was created during the installation of matchIT web, accessed through ‘Start > Programs > matchIT web > findIT S2 Admin’. Clicking on the shortcut will open up the admin program as follows.

The administration program is split into two sections, on the left are the functions and tools to help set up and maintain the configuration and database settings, on the right is the feedback window, which reports out the progress and status of the operations and functions as they are running.

The left-hand side has 4 main functions –

• Creating an encrypted string to permit administrative access to web service functions.
• Loading and validating the configuration file.
• Generating the matching keys table for each data source.
• Creating any indexes that don’t already exist and are defined as match keys in the configuration file *

Note * that the building of all indexes will take place during the Generate Keys– The rebuilding of key indexes should be run if any new match key combinations are defined in the configuration and reloaded, as to create the relevant indexes for these new combinations.

Connection String Encryption

The connection string encryption is used to create an encoded version of an administrative connection string to the SQL Server database.

i.e. Create a string for administrative level access to the database “

"Data Source=localhost; Initial Catalog=contacts; User ID=admin;Password=pw;"

Store this to the clipboard, and click the Encryption button to bring up this dialog :

Paste the admin string in the connection string box, press Encrypt, and you will be given an encrypted string in the Encrypted box :

You then can paste this value back into the connectionstringadmin value within the findITConfiguration.xml file.

The reason we use two different connections is for security purposes. A regular user of matchIT web may be someone who undertakes regular data entry, wants to look up records in a system, or even look up a validated address. However, the connection string also allows access to do things like create database tables, drop indexes and create database triggers.

As you can see the two levels of permission are very different, so we have two different connections. One to allow a regular user read/write access to the underlying database, and the other for administrative power users. The administrative string is encoded, to prevent any sensitive connection information being accessible outside of the database.

Load Configuration File

This section deals with the validation / loading of the XML configuration file.  The right side of the form shows information and progress for any job that is being run.

First, browse to the configuration file that you have just amended by using the ‘Browse’ button, and hit the load button.  If all is well with the configuration, you will get a ‘Configuration Loaded.  Result Code: 1’ message, a result code of 1 meaning that the executed method was successful.

If the load was unsuccessful, a result code of -2 will be returned (meaning ‘Not configured’), along with an error message explaining what the problem is.  Common errors are discussed in the ‘Troubleshooting’ section below.

The ‘Disable’ button will disable the web service, and make it unavailable to users.  Commonly this button will be used when a change is going to be made to the XML configuration file, which will then be reloaded to reactivate the Web Service.

The ‘Delete DBOs’ (Meaning Delete Database Objects) button will delete all database objects created by matchIT web (tables and triggers) from all databases in the current configuration, as well as disabling the web service.  Typically this would be used to clean a CRM database of any objects created by matchIT web before an upgrade, as to not corrupt any upgrading process to the database.

Generate Keys

Once the configuration is loaded the next step, generate keys, needs to be carried out if the keys do not already exist (for example, if this is the first time matchIT web has been used with the datasource in question).  Simply click the ‘Generate Keys’ button to execute the method.

 If the keys table for the datasource in question that you have specified does indeed already exist, you will be prompted with a message box like the one below

By clicking yes, the keys will be re-generated for the datasource.  Clicking no will skip the key generation for the datasource in question.

During the key creation process, the progress bar above the list box indicates how far into the key generation the program is, as well as counter in the list box actually stating how many records have been processed, and how many there are to be processed in total.  Once the actual key generation part of the process is complete, the progress bar and list box will give indications of the Indexing progress, which happens immediately after.  Also during the process, the ‘Cancel Generate Keys’ button will become active, which can be used at any time during the process to cancel the process.

Just to note, the process is a bulk process, using SQL Server’s bulk append functionality, because of this there will be a small delay at the end of the processing while SQL Server loads the information back into the table.

On success, the message ‘Key Generation Complete.  Result Code: 1’ will be displayed.  Otherwise, a result code of -2 will be displayed along with the accompanying error message.  Common errors for this process are discussed in the ‘Troubleshooting’ section below and additional information will be displayed in the event log, as previously mentioned.  If the generation for any data source was aborted by clicking ‘No’ on the dialog box displayed above, then this will also be mentioned in the summary message at the end of the process.

Note – As is covered in the AdminBulkGenerateKeys web method description in this document, the generate keys process is both multithreaded and monitored for errors.  If the key generation for a data source fails after being kicked off from the Admin Program, the user will be shown a message indicating why the process failed, and indicate to them that the key generation will be completed when re-initiated automatically through a call to PerformPendingKeyUpdates() in the Keys Synchronisation Windows Service.

Rebuild Indexes

If any new search key combinations are defined in the configuration file, the file should be reloaded and the ‘Rebuild Indexes’ button should be clicked to build the indexes relevant to the new search key combinations.  This process can also be cancelled at any time by clicking the ‘Cancel Rebuild Indexes’ button.