The purpose of the ConvertInternalLinks.exe tool is to convert both the structure and contents of fields internally linked on value (as was the case in model applications older than version 4.5.2a) in one or more tables in your SQL database to fields internally linked on reference. The tool takes care of everything, provided you’ve created a correct preferences.xml configuration file to instruct the tool about the relevant fields and database tables.

Internal link types

Internally linked fields are fields that link to other fields in the same database table. Typically, such fields appear in thesau.inf and people.inf (the Thesaurus and Persons and institutions data source), but other database table definitions can have them as well.

Internally linked fields can be linked on value (the term registered in the linked record) or reference (the record number of the linked record). Model applications older than version 4.5.2a typically have internally linked fields linked on value, where the Forward reference field property is empty for the used_for field (and all other internally linked fields): if this property does not contain a field name or tag to store the record number of the internally linked record in, then the link will be on value.

Internally linked fields on reference have several advantages, amongst which: they allow for non-unique term indexes (so you can register identical terms with different meanings in separate records) and the displayed values in the internally linked fields on reference always reflect the current state of the linked record. So in model applications 4.5.2a and higher this type of internal link has become the default.

Axiell Collections and the WebAPI (from version 3.7.14032), require the internal links in your database tables to have been linked on reference: if not, most WebAPI seaches on linked fields won’t work any more and yield errors. This means that only if you wish to use Axiell Collections or the WebAPI to access pre-4.5.2a databases, then your database will have to be converted using the ConvertInternalLinks tool.

Follow the steps below to execute the conversion:

1.Edit the preferences.xml file that comes with the tool. You can specify multiple database tables and per table multiple internally linked fields. You should always convert all internal links in a database, not just some of them. The link reference tags you enter in this file must be tags that do not appear in the relevant data dictionary already: they will be added to the .inf file by the conversion procedure. An example of a preferences.xml file is the following:

 

<?xml version="1.0" encoding="utf-8"?>
<Preferences xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <DatabasePath>C:\Axiell\data</DatabasePath>
 <DatabaseCollection>
   <Database>
     <Name>thesau</Name>
     <LinksCollection>
       <Link>
         <BaseTag>te</BaseTag>
         <Tag>us</Tag>
         <LinkrefTag>l1</LinkrefTag>
       </Link>
       <Link>
         <BaseTag>te</BaseTag>
         <Tag>uf</Tag>
         <LinkrefTag>l2</LinkrefTag>
       </Link>
       <Link>
         <BaseTag>te</BaseTag>
         <Tag>bt</Tag>
         <LinkrefTag>l3</LinkrefTag>
       </Link>
       <Link>
         <BaseTag>te</BaseTag>
         <Tag>nt</Tag>
         <LinkrefTag>l4</LinkrefTag>
       </Link>
       <Link>
         <BaseTag>te</BaseTag>
         <Tag>rt</Tag>
         <LinkrefTag>l5</LinkrefTag>
       </Link>
       <Link>
         <BaseTag>te</BaseTag>
         <Tag>et</Tag>
         <LinkrefTag>l6</LinkrefTag>
       </Link>
       <Link>
         <BaseTag>te</BaseTag>
         <Tag>so</Tag>
         <LinkrefTag>l7</LinkrefTag>
       </Link>
       <Link>
         <BaseTag>te</BaseTag>
         <Tag>se</Tag>
         <LinkrefTag>l8</LinkrefTag>
       </Link>
     </LinksCollection>
   </Database>
 </DatabaseCollection>
</Preferences>

XML element

Meaning

DatabasePath

the path to your \data folder

Database

must contain the mapping for a single table

Name

the name of the relevant .inf file

Link

must contain a single field mapping

BaseTag

the tag of the lookup field for the link

Tag

the tag of the linked field

LinkrefTag

a new tag for the link reference field

 

2.Create a backup of your SQL database and \data subfolder. This conversion may have far-reaching consequences if anything goes wrong. Therefore you should create a backup of your database and .inf files before you start the procedure, just to be safe. That way, you can always repair any errors.
3.Make sure that no-one is working in Collections and run Con-vertInternalLinks.exe from a location that has (write) access to the \data subfolder. The preferences.xml file should be present in the folder from which you run ConvertInternalLinks.exe. To write a log file with the result of the procedure, add > log.txt to the command line, e.g.:
 
C:\Temp\ConvertInternalLinks.exe > log.txt
 
The created log file will resemble the following:
 
ConvertInternalLinksLogExample
 
In the background, the procedure performs the following tasks:
1. a clone (SQL) table will be created for the processed database table;
2. all records which contain internal links will be copied to the clone table and will be adjusted with link references after which the locally stored terms will be removed;
3. the data dictionary (.inf file) of the source database will be adjusted with the new link reference fields (as specified in your configuration file), the linked fields are upgraded with the link reference tags, any merged-in fields will be added, indexes will be created for the link reference fields and local indexes will be removed;
4. the records from the clone table will then be copied back to the original table and the indexes will be updated;
5. the clone table will be removed.
4.The new link reference field names will be formatted like <tag>_linkref, so l8_linkref for example, while the index names will be formatted like <tag>_linkr, so l8_linkr for example. If you want, you can adjust these names afterwards. You could change the link reference field names format to <linked_field_name>.lref for example, as is custom in Axiell Collections applications. Changing the field names of these new link reference fields has no impact elsewhere.
For the automatically generated index names it can be wise to check if they are unique (case-insensitive) within the relevant database table definition: if not, you’ll have to change the relevant name. After you change an index name, you’ll have to reindex it to create a new SQL table for it. For completeness’ sake (although not a requirement) you may then remove the SQL table for the index that was created by this tool automatically, because it no longer serves a purpose. Removing an index table can be done with SQL Server Management Studio.