Broker is the CGI program that produces XML responses to OAI verbs as dictated by version 1.1 of the OAI protocol. Setting up broker will allow service providers to acccess and harvest metadata about your collections, for the purpose of aggregating and making this metadata, and consequently the collections, more broadly available to the public.
Contents:
Setting up broker involves understanding the six verbs behind the protocol. To learn more about the OAI protocol, see http://www.openarchives.org/.
This verb identifies the provider (i.e., you). The response of this verb is created based on the following parameters that reside in $DLXSROOT/cgi/b/broker/broker.cfg, and that are configurable when the dlxs middleware is installed:
$gRepositoryID : for DLPS, the value is dlpscoll
$gRepositoryName : for DLPS, the value is The University of Michigan. University Library. Digital Library Production Service.
$BaseUrl : for DLPS, the value is http://www.hti.umich.edu/cgi/b/broker/broker
$AdminEmail : for DLPS, the value is dlps-broker@umich.edu
$SampleID : for DLPS, the value is oai:dlpscoll:YEATS-YC023, with YEATS-YC023 being a sample record id ("YC023") from the YEATS collection.
Note that when you complete your installation and testing of broker at your institution, you will want to register your broker with OAI at their website [http://www.openarchives.org/]. At that point you will provide them with a repository ID and name, so select a repository id and a name that is meaningful for your institution. Also note the value of $SampleID. The format that broker uses as input and output for the ID is oai:repository ID:item identification.
ListSets will list the sets in your repository. Broker views sets as groups that have OAI access privileges. Therefore, if you create a group using collmgr (see documentation for collmgr for specific steps to do this), and you set the OAI parameter for that group to be Y or y, you will see these groups listed as sets when this verb is issued to broker. Also, any collections that make up that group will be listed as a set.
Because the setSpec values, which corresponds to collid and groupid values, need to be alphanumeric according to the OAI protocol, all groupid and collid values need to be alphanumeric. Here at DLPS we had collids ending in -bib, so broker will remove the hyphens to make them OAI compliant.
Set information is used as an optional input by ListIdentifiers and ListRecords.
ListMetadataFormats responds with a list of all the formats supported by broker. Currently, it responds with: oai_dc (Dublin Core) for a valid identifier passed in, and oai_dc if there are any records in the repository. DLXS's BibClass format is also supported as an output format.
This verb will list the identifiers,i.e., the unique record locators, in the repository. If a set is not specified, it will list all the identifiers in groups that have been made OAI enabled. If a set is specified, it will generate a list of identifiers for the requested set.
GetRecord will return a single record for the identifier requested, in the metadata format requested.
This verb works very much like GetRecord, but instead of returning one record, it creates a list of records based on the input parameters.
In order for broker to work, you need to create a group or groups made up of collections that you wish harvesters to gather via broker. You can do this through collmgr . Be sure to set the OAI parameter to Y or y for these groups. Most institutions will probably only create one group with the collections they feel a harvester should have access to, but there are cases where you want one harvester to harvest one group, and another to harvest another. In these cases you could create multiple groups and notify the harvester of the group they may be interested in. When they run their harvester, they will run them against that group.
To put collections online, you should follow the procedures to get BibClass collections online, since broker works against BibClass collections.
All searches for data are done with XPAT.
OAI is Unicode compliant, and in the broker cgi, there are routines for converting character entity references used by DLPS to XML numeric character entity references based on the Unicode equivalent for that character. If your institution has character entity references that are not included in the list that the release version of broker uses, you will need to add them to the broker code with the appropriate Unicode values. You will need to add the convertion in the routine ConvertStandardCharEnt
There is another routine, ConvertCollectionChars, that converts Latin-1 characters (x0a1 to x0ff) and a few other characters from ISO-8859-* into their Unicode equivalents also represented as XML numeric character entity references. You may need to add conversions in this routine if your records contain any characters from these ISO encodings not currently handled by broker.
In instances where a character entity reference does not have an obvious Unicode equivalent, the character entity reference is unchanged in the output. For example, if there is no obvious Unicode mapping for &abc;, broker will output &abc;. The user interface will simple display this string.