Adlib API home page > Documentation > Retrieving data from linked records

Retrieving data from linked records

Available from wwwopac.ashx version 3.6.327.0 (yet redesigned in version 3.6.1174.0), is the option to include fields from linked databases in the search result. This is especially useful for fields which are currently not merged in with linked fields in the main database. An example explains best: in the Collect database (which holds object records), there exists the linked field Creator. This field links to the Name field in the People database (in which persons and institutions are registered). In a name record there also appear the Place and Country fields, amongst others. The place and name are not merged-in with the Name field: this means that in an object record, a name is retrieved in the linked Creator field, but the accompanying place and country are not retrieved nor displayed alongside. This is a choice made by your database administrator. Now suppose you do want to display the place and country when displaying object records in your Adlib API application, without changing the database structure of Collect, then this functionality offers that possibility. Implementing this functionality for one or more fields does mean that the resulting (grouped) XML yielded by wwwopac.ashx will become different as far as the relevant field nodes are concerned.

What you have to do is make some changes to your adlibweb.xml configuration file, and adapt the XSLT stylesheets of your API application to handle the different XML output which wwwopac.ashx will then generate (from the version mentioned above). If you are currently using unstructured XML, you must also switch to the grouped XML type because the flat unstructured XML format cannot contain the nested XML structure. (You can set the XML type in your adlibweb.xml configuration file.) Note that any unstructured or grouped XML output remains unchanged if you do not apply this nesting functionality in your adlibweb.xml, even if you have a new version of wwwopac.ashx.

As a bonus, you cannot only retrieve data from a linked database, but also from a database linked to the linked database (and so on). The Place field in People for example, is itself linked to the Term field in the Thesau database (the thesaurus). In a term record you can also find the Equivalent term field, amongst others, and with this new functionality you can even retrieve data from this field, for instance because not only do you want to display the place for the creator, but also the equivalent terms for the place (which could be translations of the city name for example).

Let's see how to implement this in adlibweb.xml. In the adlibweb.xml section below, which shows the actual <briefFields> settings now used for a lot of demo searches on this website, the example discussed above has been implemented. (You could also set this up for the <detailFields> by the way.) Any linked field node can now contain nested field nodes from the linked database, and these nested field nodes themselves can contain further nested field nodes from the database linked in the second degree, and so on. Observe this in the creator field node. Behind the field name and before the closing node, the nested address.place and address.country fields from the People database have been included. The address.place node then, has the nested field nodes for the term and equivalent_term fields from the Thesau database.

<briefFields>
  <field>object_number</field>
  <field>object_category</field>
  <field>title</field>
  <field>creator
     <field>address.place
       <field>term</field>
       <field>equivalent_term</field>
     </field>
     <field>address.country</field>
     ...
  </field>
  ...
</briefFields>

The relevant part of the XML output of an object record in the list view may become as follows:

<record priref="11" selected="False">
  <object_category>painting</object_category>
  <object_number>150</object_number>
  <priref>11</priref>
  ...
  <Production>
    <creator>
      <name>Hals, Frans</name>
      <address.place>
        <term>Antwerpen</term>
        <equivalent_term>Antwerp</equivalent_term>
        <equivalent_term>Anvers</equivalent_term>
      </address.place>
      <address.country>Belgium</address.country>
    </creator>
  </Production>
  ... 

So the grouped XML data structure of linked fields set up for this functionality is different from normally set up linked fields (in effect making grouped XML a variable structure type): normally structured linked field data would be <creator>Hals, Frans</creator> while the new structure is <creator><name>Hals, Frans</name></creator>. The data of the linked field is nested, first within the <name> node, because that is the field which actually holds the data, and secondly within the <creator> node, because the Creator field links to the Name field. The equivalent terms of the place are nested even deeper: <creator><address.place><equivalent_term>Anvers </equivalent_term></address.place></creator>.

Although easy to set up, do consider that you'll also have to change the relevant XSLT stylesheets to handle the new data and the different structure of the resulting grouped XML: for example, existing XSLT stylesheets made for normally structured grouped XML can no longer display the data from linked fields after you've created nested field nodes for them in adlibweb.xml.
Also note that the grouped XML as produced by adlwin.exe (running your Windows Adlib applications) always contains the nested linked field structure (although it doesn't retrieve any extra fields from linked records and does have some added linked field node attributes as well), whilst the grouped XML from the default adlibweb.xml doesn't contain the nested linked field structure; this means that XSLT stylesheets may not be readily exchangeable between adlwin.exe and wwwopac.ashx.

The following URL request retrieves all records with creator Frans Hals:

http://test2.adlibsoft.com/api/wwwopac.ashx?database=collect.inf&search=creator='Hals, Frans'