Overview and Integration Principles

Search webhook (previously called Third Node) enables customers to enhance the standard Primo search engine with their own search engine functionality, using the standard Primo services and view.

This webhook allows sites to create multiple search webhooks, where each one is designed to work with a different external search engine (such as Google and EBSCO).

Currently the searches in the search webhook will not support blending with local Primo data nor any additional search webhook plugin.

The following diagram illustrates the search flow when using a search webhook adaptor:

Target Audience

This document applies to content vendors who want to expose their content to Primo users, and it describes the specifications needed to create an API that allows Primo customers to perform searches against an external search webhook.

API Specifications

This section describes the technical requirements needed to implement a search webhook. For the initial setup, you must configure a token in Primo for authorization purposes and enable the search webhook adaptor.

When searching, the general flow is as follows:

1. Primo sends a query request to the service’s Rest API.
   This request will contain the token configured in the setup phase.
2. The service should validate the request using the token that was sent in the request.
3. If the token is validated, the service returns results to Primo.

Request Definition

Primo specifies a few parameters which required to be implemented by the search service:

Query Structure

Primo supports search query that has the following structure:

<field>:(<value>) <operator> <field>:(<value>) <operator> ….

field – The data field that you want to search within.

The field is optional and if omitted, results that have the value in any of the fields will be returned.

Examples:

Title:(American History) – query for value ‘American History’ in field ‘Title’ field.

(American History) – query for value ‘American History’ in any field.

The following fields are valid:

title, secondary_title (if you have one), third_title (if you have one), creator (author), sub (subject), desc (description), rtype (resource type), isbn, issn, ftext (fulltext), general, toc (table of content), fmt, lang (language), rectype (record type), dlink (down link), uplink (up link), cdate (creation date),startdate (start date), enddate (end date), sid (source id), rid (record id), addsrcid (addsrcrecordid – see pnx), addtitle, Alttitle, contributor, citation, orcidid, abstract, fiction, local fields.

Advanced Search fields

Primo offers users the option to search records by advanced search.

There are several fields which need to be supported for that kind of search.

Full example of advanced search query (searching for books in French, published in last 5 years, containing title ‘sea’ or exact subject ‘water’):

 (title:(sea) OR sub:("water")) AND facet_lang:("fre") AND facet_pfilter:("books") AND facet_creationdate:[2014 TO 2019]

value – The search terms, which can be a word, phrase, or exact phrase (group of words enclosed by quotes), and can include the following logical operators: AND, OR, and NOT

if there is no explicit operator between the terms, AND will be used.

Terms also can be grouped by parenthesis to alter the order of precedence and supports the ‘*’ and ‘?’ wildcards.

Examples:

• (American History) – Querying for strings containing ‘American’ and ‘History’ terms.
• (American AND History) – same as above.
• (American OR History) – Querying for strings containing ‘American’ or ‘History’ terms.
• (“American History”) – Querying for strings containing the exact phrase ‘American History’

Note: exact phrase can be part of other string, that is, when querying for one term there is no difference between exact and contains match.

Primo also supports search by title that starts with a value (prefix query). In this case the value will be enclosed by quotes and include * at the end and the field will be swstitle. Example:  swstitle:(“American History*”) – Querying for strings starting with the phrase ‘American History’

For more information and examples of search terms, please see: https://knowledge.exlibrisgroup.com/Primo/Product_Documentation/050New_Primo_User_Interface/End_User_Help_-_New_UI/010Performing_Basic_Searches#Searching_for_a_Phrase

operator – When specifying multiple search fields for advanced searches, this parameter applies the following logical operations between fields: AND (specified values must be found in both fields), OR (specified values must be found in at least one of the fields), NOT (the specified value of the next field must not be found).

Example: in order to search for records with subjects containing the word ‘Sea’ and title starting with the word “Water”, the query will look like:

sub:(Sea) AND title:("Water*")

Note: When using facets, the following query structure for example, should be supported in the search webhook:

((sea)) AND facet_topic:("Bering Sea" OR "Black Sea Region") AND NOT facet_topic:("Chukchi Sea") AND facet_creator:("Bly, R") AND NOT facet_domain:("LINTE")

Full example of service url:

https://<your_host>/<service_path>?token=<configured_token>&query=%28%28sub%253A%28Sea%29%2520AND%2520title%253A%28%2522Water%2A%2522%29%29%29&from=1&bulksize=10&sort=stitle

Response Definition

Note: Each API request is restricted to a maximum of 2000 search results

The results returned to Primo should be in JSON format.
The response should contain a map of the following attributes:

• docs
• facets
• info

docs – contains a list of PNXs, each PNX section contains a map of the relevant pnx sections.

facets – contains a list of maps, each map has name and values, each ‘values’ contain a list of count and value (the facets names should be identical to the ones defined in Primo – please see below the list of the out of the box facets names; For Primo VE – it is taken from the ‘Facets Code Fields Labels’ (the last part of the code)).

info – contains a map of the following attributes: total (=total results count), last (results ending offset), first (results starting offset).

The response should be sent in the following structure:

{

“docs”:

[record_1_PNX (see structure below),

record_2_PNX,

……

record_n_PNX],

“facets”: [

{

“values”: [

{“count”:<count number>, “value”:”<value>”},

{“count”:<count number>, “value”:”<value>”},

…………

]

“name”:”<facet_name>”

},

{

“values”: [

{“count”:<count number>, “value”:”<value>”},

{“count”:<count number>, “value”:”<value>”},

…………

]

“name”:”<facet_name>”

},

………

],

“info”:

{“total”:<total_results_count>,“last”:<results_ending_offset>,”first”:<results_starting_offset>}

}

Record PNX structure

“pnx”:

{

“pnx_section”: {“pnx_field”:[“value”],

“pnx_field”:[“value”]

….                                           },

“pnx_section”: {“pnx_field”:[“value”],

“pnx_field”:[“value”]

…..                                          },

………..

{

Example of the above structure with possible values:

************************************************

{

“docs”:

[

“pnx”:

{

“control”:

{

“sourceid”:[“WorldCat”],

“recorded”:[“WorldCat1021172652”],

“sourcerecordid”:[“1021172652”],

“sourcesystem”:[“worldcat”]

},

“display”:

{

“type”:[“book”],

“title”:[“ The Pilot : A Tale of the Sea”]

“creator”:[“Cooper, James Fenimore, 1789-1851,”]

“subject”:[“Jones, John Paul, 1747-1792–Fiction. ; Sea stories, American. ; Impressment. ; United States–History–Revolution, 1775-1783–Naval operations–Fiction.”],

“identifier”:[“9788381151504”,”8381151503”],

“source”:[“WorldCat”],

“language”:[“eng”],

“description”:[“An attempt during the Revolutionary War to abduct some Englishmen.”]

},

“delivery”:

{

“fulltext”:[“worldcat”],

“delcategory”:[“Remote Search Resource”],

“fulltext”:[“no_fulltext”]

}

}

],

“facets”:

[

{

“values”:

[

{“count”:1, “value”:”book”},

]

“name”:”rtype”

},

{

“values”:

[

{“count”:1,“value”:“Cooper, James Fenimore, 1789-1851,”},

]

“name”:”creator”

},

……

],

“info”:

{“total”:1,”last”:1,”first”:1}

}

************************************************

Facets Names:

The facets names need to be taken from the “Field Names” field under the “Facets Code Fields” code table in the Primo Back Office (only the part after ‘facet_’).

The out of the box values are:

PNX sections:

There are 3 mandatory sections in each PNX record:

• The Control section – The Control section in the PNX includes formatted data used for control purposes.
• The Display section – The Display section in the PNX includes data used in the brief and full display formats of the UI.
• The Delivery section – The Delivery section in the PNX includes information that Primo requires to configure and manage the delivery of institutional resources.

The Delivery section should include the following values:

• • “delcategory”:[“Remote Search Resource”] – the value should be “Remote Search Resource”.
  • “fulltext”:[“no_fulltext”] – the value should be taken from the “Calculated Availability Text Labels” code table – Only the last part of the code should be taken.
    In Primo VE –  if you would like the link to resource to appear also under the “How to get it” section in addition to the links section, the delivery should include: “fulltext“: [“fulltext_ linktorsrc”]
    
    For example:
    

Note: Beside of those 3 mandatory sections, the following sections are also supported: adddata (required for the citation display), links (the supported links types for Primo VE are: linktorsrc, addlink), enrichment.

For more information on the available PNX sections:

https://knowledge.exlibrisgroup.com/Primo/Product_Documentation/Primo/Technical_Guide/010The_PNX_Record/010PNX_Record_Sections

Each of those mandatory sections contain the following fields:

** Response For “No results”:

The response when there are no results should be as follows:

{“docs”:[],”info”:{“total”:0,”last”:”0″,”maxTotal”:0,”first”:”1″},”facets”:[]}

Enabling the Search Webhook API in Primo

Primo customers must perform the following steps In the Primo Back Office to search the remote content using the search webhook API:

1. On the All Mapping Tables page (Primo Home > Advanced Configuration > All Mapping Tables), edit the Deep-Search Plugins mapping table, specify the following fields for the Deep Search plug-in if it has not been defined or if it has been removed:

• Enabled – Select this check box to enable the plug-in.
• Plugin ID – name of the plugin (example: SearchWebhook)

You can configure a different search plug-in for each institution so that they insert their own API key. At the institution level, use the following naming convention to define a different Deep Search plug-in for an institution:

<Plugin_ID>_<institution_code>

• Plugin Class = generic.SearchWebhook
• Plugin Display Name – Enter the display name (such as ‘Search Webhook’).
• Description – Enter an optional description (such as ‘Primo to generic search webhook’).

2. On the All Mapping Tables page (Primo Home > Advanced Configuration > All Mapping Tables), edit the Deep Search Plugin Parameters mapping table, specify the following fields for each parameter that you want to modify:

• Enabled – Select this check box to enable the parameter.
• Param name – Specify the name of the parameter (see Search Webhook Plug-In Parameters).
• Param value – Specify the value of the parameter if encryption is not needed (see Search Webhook Plug-In Parameters)
• Param value – Encrypted – Specify the value of the parameter if encryption is needed. Use this field to encrypt sensitive information (such as keys and passwords).
• Plugin – Select the plug-in ID of the plug-in that uses the parameter.
• Description – Specify text that describes the functionality of the parameter. This field is optional.

Search Webhook Plug-In Parameters

• URL – The URL for the search webhook API.
• GenKey – The key used by the institution to authenticate with the search webhook services. You should not encrypt it in any way.

Make sure though to insert the value in the “Param value – Encrypted” column, and leave the “Param value” column empty for this row.

3. On the Deploy All page (Primo Home > Deploy All), select the Deep Search Configuration option, and then select Deploy.
4. Add the deep search plug-in to the search scope in the Views Wizard (Views List > Edit View > Search Scope List > Edit Scope).
5. Deploy the view.

** Other optional parameters available for this plugin are:

• primo_services/primo_highlighting
• warmup/enable
• cache/enable
• cache/batchsize

(The explanation can be found here:

https://knowledge.exlibrisgroup.com/Primo/Product_Documentation/Primo/Back_Office_Guide/110Additional_Primo_Features/Primo_to_Primo_Deep_Searches)

Note: After configuring the search webhook, a new search scope should be created and defined to use the search webhook – for more details on defining a search scope – https://knowledge.exlibrisgroup.com/Primo/Product_Documentation/Primo/Back_Office_Guide/060Configuring_Primo%E2%80%99s_Front_End/020Views_Wizard#ww1052871

Enabling the Search Webhook API in Primo VE

Primo VE customers must perform the following steps to search the remote content using the search webhook API:

1. Under “Discovery > Search Profiles > Other Indexes”, choose “Search Webhook” in order to create a new profile.
2. Edit the “Search Webhook” configuration, and fill the following fields:
   
   Scope Details:
   – Scope Name
   – Code
   – Description
   Remote Index Details:
   – URL: Should contain the remote’s search index url
   – API Token: Should contain the key set in the remote index server; This key will enable the search from Primo VE in the remote index.

Note: After configuring the search webhook profile, a new search scope should be defined to use the search webhook – for more details on defining a search scope –

https://knowledge.exlibrisgroup.com/Primo/Product_Documentation/020Primo_VE/022Search_Configuration/010Configuring_Search_Profiles_for_Primo_VE

Appendix:

1.      Links section in the PNX – for Primo only:

Note: A link structure should be the as following: ‘link: $$U<url>$$D<display_name>’