Getting Started – XService API

NOTE: After entering your IP in the mapping table, you must deploy
“All client IP ranges (WS and XS IP mapping table)” that exists in the deploy screen.

Identifying your IP address

Below are two possible options (more exist)

1. From the computer that is going to run this application, open a browser and search in Google for “What Is My IP”.
2. If you have access to the Primo FE machine – Execute the URL in the step below. You will receive a negative response saying you are not authorized.

Now enter the log directory (fe_log) and view the library_server.log, look for a line such as:

[c-WsXsIpFilter] [O -(2000001,2160632,null)] –
Unauthorized access level:(2000001,2160632,null) for ip:10.1.116.182

The IP at the end of the line, is the IP you need to register.

You can use the following URL in your browser to check if the XService is working:

http://<your primo domain>/PrimoWebServices/xservice/search/brief?institution=<primo institution>&indx=1&bulkSize=10&query=any,contains,science

(fill in the two place holders (primo domain and institution))

If you get a result displaying on the page, it is working.

If you get a result with status 403 (access denied), something is wrong with the IP registration.

There is no point continuing if the above URL is not working for you.

In order to get the application working, you must edit the index.html page and modify 2 lines:

host : “<your primo domain>”,

institution: “<institution code>”,

(For example, these 2 lines can look like:

host : “primodemo:1701”,

institution: “VOLCANO”,)

host – You must modify the host value to the domain you are working against
(this will be the domain used in the step above for checking your IP).
Note, the host might include the port number (for example:  primo.hosted.exlibris.com:1603)

institution – modify the value to hold your institution code, as done in the step above, for checking your IP.

Once these 2 values have been set, save the index.html file, and then just double click it, so it will open in your browser.

That’s it!!! The application is ready to be used.

The index.html page holds an empty HTML structure which gets populated once the “search” button is clicked.

The structure looks like this:

Each square in the image above is represented by a <div> element.

<div id="searchbox" style="float: top">

    <input id="search" type="text" placeholder="Type here" value="book">

    <input type="button" value="Search" onclick="searchRequest.reset();search()">

</div>

<div id="pagination" ></div>

<div id='body'>

  <div id="facets" style="float: left; width: 10%;"/>

  <div>
       <div id="totalResults" style="padding-bottom:10px;"/>
       <div id="facetsbreadcrumbs"/>
       <div id="results"/>
  </div>

  <div id="details"/> 

</div>

The default result coming back from the XService is in the XML format.

As the Javascript language can parse and handle JSON objects easily, this application we call the XService, requesting the results to be returned as JSON (this is done by adding to the URL, the parameter: &json=true).

All explanations below will be done using XML examples (although application uses JSON)  as it is more structured an easier to understand.

The response coming back from the XService is called a “Result Set”.

The result set is built from 3 main parts:

1. Did you mean – not used in this application.
2. Facets
3. Records (a list of PNX records)

Below is a look at the returned XML response when the facets (FACETLIST) and the records section (DOCSET) are collapsed (the did you mean (QUERYTRANSFORMS) is empty in this example)

The facets section contains all the different facet types and values.

<sear:FACET NAME="lcc" COUNT="20">
    <sear:FACET_VALUES KEY="K - Law." VALUE="321"/>
    <sear:FACET_VALUES KEY="U - Military science." VALUE="112"/>
     …
</sear:FACET>

The DOCSET section includes a list of PNX records.

Each PNX will look like this:

<sear:DOC ID="204765>
  <PrimoNMBib>
    <record>
       <control>
           <sourcerecordid>001887023</sourcerecordid>
       </control>
       <display>
          <type>book</type>
          <title>The World Book dictionary</title>
       </display>
        …
</sear:DOC>

As said above, the application comes with an empty template that gets populated once data is ready to be displayed.

There is a javascript function responsible for populating each different section in the template.

The application uses a searchRequest Object, to keep and maintain data entered by the user.

Such data can be: the chosen facets, the interface locale and the query performed.

The searchRequest object looks like this:

searchRequest = {

                host : "primodemo.exlibrisgroup.com:1701",

                institution: "VOLCANO",

                locale:'en',

                facets: [],

                searchTerm:'',

                page:1,

                totalResults:0,

                sort:'', //relevance

                reset: function() {this.facets = [];this.page = 1}

}

<div>Language

  <ul class=’muted’>

     <li>eng (10)</li>

     <li>fre (10)</li>

     <li>heb (10)</li>

  </ul>

</div>

Below is the real code doing the work:

$.each(data["SEGMENTS"]["JAGROOT"]["RESULT"]["FACETLIST"]["FACET"], 

          function(key, record) {                          

                var facetValues = getFacetValues(record['@NAME'], record["FACET_VALUES"]);

                if (facetValues == "") return;

                $("#facets").append(

                       "<div>" + I18n.t(record['@NAME']) +                        

                       "<ul class='muted'>" +  facetValues + "</ul>" +                    

                       "</div>");

})

var records = data["SEGMENTS"]["JAGROOT"]["RESULT"]["DOCSET"]["DOC"];

   if (!(records instanceof Array)) {records = [records];} //only 1 record returned               
          $.each(records,
               function(index, record) {
                   var pnx = record;

                                             ...