VuFind Primo Central Bridge

Ex Libris Developer Network Primo Documentation More VuFind Primo Central Bridge

General Purpose

An adaptor that allows VuFind to connect and get results from Primo Central, a mega-index of electronic material.

Download

blender-1.4.zip – Relevant for customers using VuFind V1.3 and higher. Removed warnings from log

blender-1.3.zip – Relevant for customers using VuFind V1.3 and higher

blender-1.2.zip – Relevant for customers using VuFind V1.2 and lower

Supported VuFind versions

The PC Bridge was tested to support the following VuFind versions:

Note – Each version of VuFind uses a different version of the PC Bridge. See the attachments, to find your relevant PC Bridge version.

Primo Central Registration

In order to use the PC Bridge, you must have a PC key, meaning you must be registered to Primo Central.

The registration is not done via the PC Bridge.

If you would like to register to Primo Central please contact us at: http://www.exlibrisgroup.com/category/ContactUs

The registration includes the IP address of the machine (multiple IP addresses can be entered for testing on production servers) which will be running the PC Bridge.

If the IP address changes, you must update it in the registration wizard (My Profile). The update will take affect up to 24 hours after.

Installation

After you receive the blender.zip file, provide the Account/Implementation Manager with the IP address of your server so that it can be authorized to access Primo Central.
Note that you will need your Primo Central ID key later in this procedure.
Extract the blender.zip and place the blender directory at the chosen location as described below:
The PC Bridge can be installed in 2 different modes:
a) Local – On the same server that is running your VuFind.
The common location to place the PC Bridge directory is below the main vufind directory (i.e. /some path/vufind/blender/)
b) Remote – On a different server which is not your VuFind server.
In such cases you must make sure you have got the needed ports open between your VuFind server and your PC Bridge server (see below step #5).
Enter the following commands to change the ownership of the PC Bridge’s startup script:
cd /some path/vufind/blender
chmod 775 blender.sh
Enter the following commands to open VuFind’s config.ini file for editing:
vi /some path/vufind/web/conf/config.ini
Under the Index section, change the url parameter so that it points to the PC Bridge’s host and port (the default is localhost:8984). For example:
[Index]
engine   = Solr
# changed for blender
;url     = http://localhost:8080/solr
url      = http://localhost:8984/solr
If you have installed the PC Bridge using the Remote mode, the url should point to the remote machine.
You must choose a port which is opened and free to be used.
Exit and save your changes to the file.
Enter the following commands to open the PC Bridge’s conf.properties file for editing:
vi /some path/vufind/blender/home/conf/conf.properties
Update the following mandatory fields to configure your local settings for the PC Bridge (see figure below):
pc.id – enter your Primo Central ID. This must be changed before using the PC Bridge.
jetty.port – this is the port the PC Bridge will listen on. This port must match the port you used in step #5.
VUFIND_SOLR – this is the URL to your Solr index.
jetty.port=8984
VUFIND_SOLR=http://localhost:8080/solr/biblio/
pc.url=fe.p.prod.primo.saas.exlibrisgroup.com:1701
pc.id=XYZ
if the PC Bridge is running, you will need to restart it in order to load the new settings.

Starting and Stopping the PC Bridge

The commands to start and stop the Blender are stored in the following directory:

/usr/local/vufind/blender

To start the PC Bridge:


cd /usr/local/vufind/blender
./blender.sh start

To stop the PC Bridge:


cd /usr/local/vufind/blender
./blender.sh stop

Note: After you configure the PC Bridge, you must restart VuFind with the regular vufind.sh script in order to start Solr.

Configuring VuFind to Stop and Start the Blender

If you want the PC Bridge to start and stop automatically when VuFind is stopped and started, add the highlighted lines as shown below to the vufind.sh script.

case "$ACTION" in

      start)

        echo "Starting VuFind ... "


        if [ -f $JETTY_PID ]

        then

            echo "Already Running!!"

            exit 1

        fi


        # Export variables for Import Tool

        export VUFIND_HOME


        echo "STARTED VuFind `date`" >> $JETTY_CONSOLE

        echo "$RUN_CMD"

        nohup sh -c "exec $RUN_CMD >>$JETTY_CONSOLE 2>&1" &

        echo $! > $JETTY_PID

        echo "VuFind running pid="`cat $JETTY_PID`

        exec "cd blender"

        exec "blender.sh start"

        ;;


      stop)

        PID=`cat $JETTY_PID 2>/dev/null`

        echo "Shutting down VuFind ... "

        kill $PID 2>/dev/null

        sleep 2

        kill -9 $PID 2>/dev/null

        rm -f $JETTY_PID

        echo "STOPPED `date`" >>$JETTY_CONSOLE

        exec "cd blender"

        exec "blender.sh stop"

        ;;

Logs

When the PC Bridge is running, log entries are added to the following file:

/some pathl/vufind/blender/home/log/blender.log

Configuring the PC Bridge

The PC Bridge configuration files described in the following sections are located in the following directory:

/some path/vufind/blender/home/conf

NOTES: If the PC Bridge is running while you make changes, restart the PC Bridge to load the new settings.

General Configuration – conf.properties

The conf.properties file holds the basic configuration for the Primo Central bridge. It contains the following parameters:

Mandatory

jetty.port – this is the port for the blender. Change if you wish to use another port
VUFIND_SOLR – this is the URL to your Solr index
pc.id – This is your Primo Central ID. This must be changed before starting to use the blender

Utilities

blend.pc.timeout – The timeout in seconds for results to return from Primo Central.
If the timeout reaches, no results will be returned from Primo Central.
record.title.suffix – A suffix which will be added to the title for records returning from Primo Central.
If you do not want any suffix, remove the value or remove completely the parameter from the file.
This suffix might be useful when debugging or configuring the blending settings.

Link Resolving

link.resolver.base.url – If you have a link resolver installed you can use this feature.
Records returning from Primo Central include an availability indication.
If a positive indication exists, the PC bridge will populate the SOLR “url” field
for each record with the direct link to it’s full text.
Below are 2 relevant parameters to use:
link.resolver.base.url – Should hold the base URL for your link resolver
openurlfull_article =
openurlfull_article – See above. A URL template which will be used and populated by the bridge.
The template includes in it place holders. You can use 3 different place holders:
1) base_url – will be replaced with the value under link.resolver.base.url
2) timestamp – will be replaced withthe current timestamp in the format of:
yyyy-MM-dd–HH:mms
3) <PNX section>/<PNX field> – Will place the relevant PNX value which exists under the
relevant section under the relevant field.
For example: display/title

Currently the openurlfull_article is an SFX working template. If you have a different link resolver, you will need to change this template

Blending

TBD

Authorization

By default, the queries sent to PC are sent as “logged off” or “off campus”.
In order to indicate to the Blender to send an “on campus” request to PC, you need to add a facet to the query coming from VuFind.

Using the configuration below, you configure which is the facet to look for, and what is the expected value in it that indicates when I am “on campus”.
In the example below, if the query will include the facet: restricted_mode = true , the query sent to PC will hold the “on campus” indication.

authorized.field.name = restricted_mode
authorized.field.value = true

Mapping PNX Fields to Solr Fields – pnxMapping.properties

This file holds the mappings between the fields in the Solr index and the fields in the PNX file received from Primo Central (PC).
The format is as follows:

Where the PC field is formatted as follows:

For example:

author=display|creator join(“, “)

After mapping to a specific PC field, you can use several filters to manipulate the content from Primo Central before it is mapped to a Solr field. Note the <tab> between the <field name> and the filters. You can use more than one filter delimited by a semicolon, as follows:

The filters will be applied one at a time in the order in which they are entered, from left to right.

Filters

The following filters are valid:

default(“<value>”) – if the field in Primo Central returns no value, this filter returns the specified default <value>.
makearray() – always returns an array even if the field is a single string.
join(“<value>”) – always returns a string. If the field is an array, this filter joins the different values by using <value> as a separator.
first() – always returns a string. If the field is an array, this filter returns the first cell.
trimword(<max>) – trim strings after the maximum number of words <max> is met. If the field is an array,
this filter trims every string in the array. If any string has been trimmed,
this filter will append the ellipsis string (“…”) to the end.
trimchars(<max>) – trim strings after maximum number of characters <max> is met. If the field is an array, this filter trims every string in the array.
If any string has been trimmed, this filter will append the ellipsis string (“…”) to the end.
removemarkup() – removes markup (XML/HTML) code from the field contents. If the field is an array, this filter removes markup from each string in the array.
map(“<file>”) – maps the value of the field according to the properties file specified in <file>. If the field is an array, this filter maps every string in the array.
If no mapping is found for a string, the filter will not change the string.
constant(“<value>”) – adds fields with a constant value <value> to Solr. In these cases, specify the PC field definition, as follows:
recordtype=constant(“PrimoCentral”)
explode(“<value>”) – splits a string on every occurrence of <value>.
geturl() – extracts the URL from the links|backlink field, which is built using the MARC subfield codes ($$u and so forth).

Configuring Facets – facet_fields_mappings.properties

The facet_fields_mappings.properties field maps specific fields in Primo Central to facets defined in VuFind, as follows:

For example:

topic=topic_facet

NOTE: Queries arriving with an un-mapped facet field/s will not return results from PC, only from local.

Mapping Facet Values – facetMappings.properties

The facetMappings.properties file is used to map the facet values used in Primo Central to those used in the VuFind Solr index.

Each mapping row in the file must use the following format:

For example:

language>>abk=Abkhazian
language>>ace=Achinese

Mapping Search Fields – search_fields_mappings.properties

The search_fields_mappings.properties file is used to map the Solr search terms to the field names used in Primo Central searches. Each mapping row in the file must use the following format:

For example:

author=creator

Facets Display order – facets_order.properties

Although you configure the facets display order in VuFind’s configuration files, you must re-configure them in the PC Bridge as well.
The PC Bridge cannot access VuFind’s configuration files therefor you must let the bridge know the requested order.
Facets which are not in the list will display at the end.
Each line should hold one facet name

Ignore Filter Queries (fq) – ignore_fq.properties

In Vufind you can define filters to be added to specific queries.
For example in /vufind/web/conf/searches.ini you can define a filter under [RawHiddenFilters].
If these filters are only meant to filter out specific local results you will want the PC bridge to ignore these filters.
Each filter you which to ignore, should appear in it’s own separate line exactly like defined for VuFind.
For example:
institution:”GD-1″ or institution:”GD-2″

Static Facets – static_facets.properties

A static facet is such a facet which will be associated to all PC returned results.
Clicking on the facet will return only relevant PC results (and not local).
You can define 1 or more such static facets.
Each line should hold one facet.

For example:
collection = Electronic Resources

VuFind will receive back a facet called collection holding a value named: “Electronic Resources” with the relevant PC returned count for this value.