DLXS IDRESOLVER
From DLXS Documentation
Main Page > Ancillary Resources > DLXS IDRESOLVER
Contents |
[edit] IDRESOLVER
IDRESOLVER is a simple mechanism for resolving a unique ID to a URL. The DLXS Classes can use it to, for example, link digital object identifiers in an Electronic Finding Aid to the actual digital object in another Class.
IDRESOLVER is the combination of a data table and a CGI. The table stores IDs and URLs, and the CGI responds to requests for ID resolution. It is also possible to skip the CGI and query the table directly, and some ofthe Classes take this approach.
The MySQL table in the DLXS database is named "idresolver". It has three fields: id, url, and modified. IDs must be unique.
The IDRESOLVER CGI ($DLXSROOT/cgi/i/idresolver/idresolver) will return a single URL (wrapped in XML) when given an ID that is in the database.
Below is an example from the Bentley Image Bank, which links from a digital image record in Image Class to the Bentley Electronic Finding Aid (in FindAid Class) using IDRESOLVER. It is also possible to link in the other direction, but this way is easier to explain and understand.
The image record has a field named "Finding Aid" containing an ID. The field is configured (in Collmgr) so that Image Class uses IDRESOLVER to turn the ID into a link. The Image Class middleware takes the value of the field, "umich-bhl-02160", passes to IDRESOLVER in the form of an HTTP request, which returns the value from the URL field in IDRESOLVER.
| ID | URL |
| umich-bhl-02160 | http://www.hti.umich.edu/cgi/f/findaid/findaid-idx?c=bhlead;idno=umich-bhl-02160 |
The above example links to the top level of the Finding Aid. Going the other direction, from the finding aid to the image record in Image Class is more specific. The list of objects in the finding aid has several links, each built by using IDRESOLVER to look up the URL by ID.
An ID may resolve to any type of URL, for instance, one that returns a result set (many items) rather than a single item. In all cases, it is up to you to create and maintain the IDs and URLs. The IDRESOLVER table and and CGI do nothing to help with this. The University of Michigan keeps a FileMaker database of IDRESOLVER IDs and URLs. Data is periodically added, removed, and updated in the FileMaker database. And then as needed, the data is dumped out of FileMaker as XML and loaded in to MySQL, replacing the existing IDRESOLVER data.
Here are the generic steps for loading or updating IDRESOLVER data.
- Load all ID/URL pairs in to an intermediate/short term table in MySQL.
- Create an empty copy of the current, production, "idresolver" table.
- Transfer all IDs/URLs from the intermediate table to the copy of the production table.
- Rename the current production table, essentially taking it out of service.
- Rename the copy of the production table as 'idresolver' so that it becomes the production table.
- Test the new production table. If all is well, drop/delete the intermediate table and the previous production table.
Using the above method keeps the definition of the MySQL table in tact,including indexes.
Michigan has a more specific set of instructions for internal use that might be helpful to you in creating your own set of steps and instructions for updating idresolver.
It is worthwhile to come up with a well defined plan for creating IDs so that they are unambiguous and, in particular, unique.</p>
For example, let's say you have a book in Text Class that has full color figures in Image Class and you want to display thumbnails for the figures in Text Class and link them to the full record and large image in Image Class. Plus, you want Image Class to link back to the page in the book. This requires 3 ID/URL pairs.
- ID/URL for the thumbnail image
- ID/URL for the full record in Image Class
- ID/URL for the book page in Text Class
In order to disambiguate these related items, add to each ID a suffix such as "rec" for record and "th" for thumbnail. Also prefix each with a DLXS Class abbreviation and the collection id. The following is an ID for linking from Text Class to Image Class. Let's break it down because it is slightly counter-intuitive how it is constructed.
Example ID: ic-micounty-2911266.0001.001-P0000063.TIF-rec
Assume the Text Class object (i.e., XML) contains a Text Class (not Image Class) collection ID, volume ID, and page ID. And the middleware has been configured/programmed to resolve IDs for this collection in order to link to Image Class. Text Class does not, however, know the Image Class collection ID that it needs to link to. Granted, this could be hardcoded into the middleware, but it is better to leave the Image Class collection ID out of the code and let IDRESOLVER take care of it. Again, we want the above Example ID to resolve to an Image Class URL. The counter-intuitive part is that the collection id is the Text Class collection ID, but we are linking to an Image Class collection.
Keep in mind that the DLXS classes do not require IDs to follow a particular convention, but you may have to make middleware changes/overrides if you choose your own convention.
Once you have your database of IDs and URLs, you need to know how to make the Classes do look-ups.
[edit] Image Class
To make Image Class look up the value of a field as an ID, use Collmgr to turn on the "idres" option in any list of display fields such as (dfltentryflds). The field value must match the ID in the IDRESOLVER table exactly. For more information about enabling the idres option see <a href="../class/image/colldb.html" target="_blank">Image Class COLLDB (Collection Database) Configuration</a>. (fix link)
[edit] FindAid Class
If DaoResolution is enabled in findaidclass.cfg, Findaid Class will look for an href attribute to the <dao> element.It will then check to see if it contains the string "http". If it does, FindaidClass will not us ID Resolver, but will create a link based on the content of the href attribute of the <dao>.
If there is no "http" string in the href attribute, FindaidClass assumes that the href attribute is an id and will look up that id in in the idresolver and build a link if it finds the ID in the IDRESOLVER table. The method FilterAllDaos_XML in $DLXSROOT/cgi/f/findaid/FindaidClass.pm can be overridden per collection if different behavior is needed.
During the preparation and concatenation step of data preparation, the preparedocs.pl script also adds a prefix to any dao href which doesn't contain the string "http". The prefix is set in the variable $gDaoIdPrefix and the default is 'dao-bhl-' .
[edit] Text Class
Text Class attempts to resolve all FIGURE IDs. It uses IDRESOLVER if the FIGURE TYPE is INLINE or THUMBAIL. IDRESOLVER lookups assume image class. The method GenerateExternalId in $DLXSROOT/cgi/t/text/TextClass.pm can be overridden per collection if different behavior is needed.
[edit] More Information
More information about subclassing can be found in the document <a href="../program/subclassing.html" target="_blank">Subclassing in TextClass</a> (fix link).
The utility script $DLXSROOT/bin/data2db.pl is useful for loading data into a MySQL table and it can be subclassed for different formats.
[edit] NAMERESOLVER (idresolver-nr)
The new IDRESOLVER CGI can be used for the existing idresolver and is intended to replace the functionality of the nameresolver (bibperm), previously in Bib Class. The difference between idresolver and idresolver-nr (the new nameresolver) is that idresolver returns a URL in an XML response for a given ID and idresolver-nr redirects the user to the URL.
[edit] Create table
The data is stored in a MySQL table. To create the table for nameresolver you can use the CreateTable.pl script. To create a table in your development environment:
# cd $DLXSROOT/bin/n/nameresolver # ./CreateTable.pl
to add the table to "production", add the -p option:
# ./CreateTable.pl -p
This script reads from the config in $DLXSROOT/lib/LibGlobals.cfg for connection information to the database and creates a table called nameresolver.
If you would like to create the table manually, this is an example SQL statement:
CREATE TABLE nameresolver (id tinytext NOT NULL,
coll tinytext, url tinytext,
modified timestamp DEFAULT CURRENT_TIMESTAMP,
KEY (id (255), coll(255)));
NOTE: The collection (coll) is optional and is only used if a record is held in more than one DLXS collection. In these cases, the user is not taken to the record but is presented with links to view the record in the different collections.
[edit] Loading Data
We provide two scripts for loading data into the nameresolver or idresolver database. The first $DLXSROOT/bin/n/nameresolver/IdParser.pl can load data in many different ways. It will read XML file(s) or will load records one at a time. Read the help message (./IdParser.pl -h) message for more instructions.
The second (LoadLLMCIds.pl) is an example of how you can load simple data from a plain text file. This is provided as an example and would need to be modified to be used.
[edit] Script Alias
To redirect the short URLs (ex. name.umdl.umich.edu/id123) to the nameresolver (idresolver-nr) add a simple Redirect statement in the apache config. The mod_alias apache module must be enabled for this to work. The ServerName and Alias below should be changed to reflect the hostname that you have chosen to use.
<VirtualHost *:80>
ServerName name.your.inst.edu
ServerAlias name name.your.inst.edu
DocumentRoot "/n1/web/n/name"
# simple name resolver
Redirect / http://your.inst.edu/cgi/i/idresolver/idresolver-nr?id=
</VirtualHost>
