About

Secondary Lookup plugin performs an additional HTTP request (based on the preconfigured URL pattern) to enrich the data (e.g the 'record' command) coming from Pazpar2. The target of the request may be either an arbitrary GET HTTP endpoint or the pazpar2 "raw" record command.

For the former, if the retrieved data is XML-encoded it is injected (imported) to the response as-is. Any other text format (e.g JSON) is first XML-encoded and and then embedded as a new element in the response.

For the latter, the record command is executed on the active Pazpar2 search session.

The plugin is chainable so you can map multiple instances to a single command.

Protocol

Assuming the plugin has been mapped to the record chain (see configuration) it is invoked transparently when this particular command is called.

Request parameters

NONE

Configuration

Registration

This plug-in is configured in service-proxy.properties or equivalent as follows:

  plugins.sl  = com.indexdata.serviceproxy.plugins.SecondaryLookup

Chain mapping

Example:

  chains.record = relay,sl

Properties

URL_PATTERN

URL recipe used to perform the secondary request. You can use placeholders of the form: ${md-value} to inject metadata from the original record (or any data injected earlier in the chain). A special switch, '/u' is used to URL encode the value. When any of the injected values are missing the lookup is aborted.

In case the pattern starts with search.pz2 prefix, the lookup is treated as a pazpar2 record request executed on the current search session. You can specify additional pazpar2 record parameters in the query string.

Mandatory

Example (arbitrary XML service):

  sl.URL_PATTERN = http://www.someservice.com/AddInfo?id=${md-id/u}

Example (Pazpar2 record lookup):

  sl.URL_PATTERN = search.pz2?esn=F

IN_LOC_ID, IN_LOC_NAME

Allows to scope the source of data injected to the pattern to a specific locations (either by name or id). When the location is missing the lookup is aborted. In case the record contains multiple locations with the same ID/NAME, multiple requests are sent.

Not applicable to pazpar2 record lookups.

Optional

Example:

  sl.IN_LOC_ID = loc.gov/voyager

COMBINE

Specifies the character used to combine multiple placeholder values of the same type within a single URL pattern. This works across 'location' elements and can be used to bundle external requests. No bundling is done when the character is not specified.

Optional

Example that combines values of all 'md-id' fields across all locations using a comma and fires off a single request to the external web service:

  sl.URL_PATTERN = http://www.someservice.com/AddInfo?ids=${md-id/u}
  sl.COMBINE = ,

OUT_LOC_ID, OUT_LOC_NAME

Allows to embed the result of the lookup under particular 'location' elements.

Not applicable to pazpar2 record lookups.

Optional

Example:

  sl.OUT_LOC_ID = loc.gov/voyager

FILTER

When used, the lookup is executed only for records with a particular metadata fields. The expression is a comma-separated list of keys (the field must be present) or key=value pairs (must be present and matching). For each pair, multiple alternative values can be specified using the '|' symbol.

Optional

Example:

  sl.FILTER = md-medium=track|album
  sl.FILTER = md-medium=track|album,md-subject=rock

SEARCH_PZ2_LOC_IDS, SEARCH_PZ2_LOC_NAMES

A CSV list of location IDs or names against which the secondary pazpar2 lookup is performed.

Not applicable to arbitrary web service lookups.

Optional

Example:

  sl.SEARCH_PZ2_LOC_IDS = target-id-1,target-id-2