Configuring NCIP in Relais ILL

Find information about configuring NCIP in Relais ILL, including NCIP server connection information, patron profiling, and circulation components.

There are 3 components to configuring NCIP in Relais ILL:

  1. NCIP server connection information:  Includes information such as the NCIP server address and port.
  2. Patron profiling: If you are using NCIP Lookup User to authenticate or authorize patrons, you can specify more detail such as which patron types are allowed to submit requests.
  3. Circulation components: When using NCIP to update circulation transactions, configuration of generic patron ids and pickup locations is needed.

NCIP Server connection information

Configure your NCIP server connection information in Relais ILL. Where appropriate, any configuration specific to a particular library system is noted.

  1. Login to Library Registration.
  2. Retrieve your home library record.  See Retrieve or view a library record for more information.  
  3. Click Contact.
  4. In the lower right hand corner, enter your home library symbol in the NCIP Server Library field to activate the Configure NCIP Server button.
    RelaisILL_NCIP_Server_Library.png
  5. Click the Configure NCIP Server button to display the NCIP Server Connection window. Enter the information as defined below.  
    Field Characters Description
    ILS System   Select your library system from the drop down list.
    Version  

    Select the version of NCIP your library system is running.

    • All library systems currently run NCIP V1.0, with the exception of Innovative Interfaces and Alma who run NCIP V2.0
    Connection Type  

    Select the method by which Relais connects to your NCIP server from the drop down list:  tcp/ip, http or https.

     Caution:  We strongly recommend that libraries use https as their connection type. Using https ensures that patron data transmitted back and forth between Relais and your library system is done securely. Furthermore, the use of NCIP messaging when processing requests through the Windows client is only supported through the connection types http and https.
    Server Address 80 Enter the IP or base host name for your NCIP server.
    Port 10

    Enter the port number through which your NCIP server communicates.

    • If you use the Relais Hosted Service, ask your local IT staff to open your NCIP port in your firewall to incoming traffic from the IP address of the Relais web forms. Please contact OCLC Support if you are not sure what the correct IP address is for your Relais web forms.
    NCIP URI 80

    Enter any remaining part of the url needed to access your NCIP server.

    • This field is only populated when the connection type is http or https.
      • For example, the typical NCIP URL for SirsiDynix Symphony or Unicorn sites is: /sirsi-ncip/nciprequest and for Innovative Millennium systems: /iii/nciprelais/Restful. Please check with your library system vendor to confirm the exact NCIP URL for your site if required.
    Application Profile 20 Required by ExLibris Alma to determine which system is making the message call.
    Server Agency 20 Required by ExLibris Alma in the ToAgencyID field in the xml InitiationHeader.  This may be different than Agency ID fields used in the rest of the message.
    Agency Schema 100

    Required by TLC. The typical url used by TLC is http://www.tlcdelivers.com/ncip/schemes/uniqueagencyid.scm If you are a TLC customer, please confirm this schema with TLC before profiling it in Relais.

    • For all other library systems, please check with your vendor to see if they use any specific agency schemas.
    To Agency 20

    Enter your library's agency code as the agency to which Relais sends NCIP messages.

    • Not used for SirsiDynix Symphony.
    From Agency 20

    Enter Relais as the agency from which NCIP messages are sent.

    • Not used for SirsiDynix Symphony.
    Active Messages  

    Check the messages you wish to use

    • Lookup User
    • Check Out Item
    • Check In Item
    • Accept Item
    • Request Item (currently available for TLC and Symphony only)
    • Delete Item - not yet available
    • Update Item - not yet available

  6. Click OK to accept the new settings. A pop up screen displays to confirm the settings have been added. Click OK to acknowledge the message.

Patron profiling

There are three ways to configure Relais to do more detailed validation of your patrons using the NCIP Lookup User message and determine whether a patron is allowed to submit requests. These three areas include:

Patron Profiles

Specify which patron or borrower types in your library system are permitted to place loan and/or copy requests in Relais ILL by defining patron profiles. To invoke this functionality, set the Use Server Profile button to Yes and then define the permissions of each patron or borrower type from your library system via the Update Profile button.

  1. Access Library Registration via Login – Staff.
  2. Search/retrieve your institution's library record. Upon retrieving your library's record, switch to the Contact tab.
  3. To use patron profiles for validation ensure the Use Server Profile button is set to Yes.
    RelaisILL_NCIP_Server_Library.png
    The various patron/borrower types you define via Update Profile must be associated with a patron type in Relais. Before you start entering your library's patron or borrower types for profiling, ensure that the Relais patron types to which you would like to associate your library's patron or borrower type codes are already created in Relais.
     
  4. Click Update Profile to configure your patron/borrower types and their permissions:
    Field Characters Description
    Profile Code 20 Enter the patron type code from your library system.
    Description 50 Enter in a description of the patron type code.
    Patron Type  

    Select the patron type code created in Relais from the drop down list that you would like to associate your library system patron code with.

    • You can associate multiple NCIP profiles with one single patron type code in Relais.
      • For example, if you have several different Undergraduate patron types/profiles in your library system, you could create one patron type in Relais called Undergraduate and associate each of your library system profiles with that one patron type. This is helpful for sites that have extensive patron types in their library system and need to map them to a finite number of codes that can be created in Relais.
    Loan Code   Select the loan code to be associated with the patron profile.
    File Format   Select the default file format that material is delivered in when sent via email.
    Message Format   Select the default message format.
    Billing Type   Select the billing type to be associated with the patron profile.
    Billing Rate   Select the billing rate to be associated with the patron profile.
    Copy
    Allow Copy   Select whether this patron profile is allowed to place copy requests
    Delivery Select   Select whether the patron is allowed to select their delivery type when placing copy requests.
    Delivery Method   Select the default delivery method for copy requests for this patron profile.
    Delivery Address 80 Enter the default delivery address for copy requests for this patron profile.
    Loan
    Allow Loan   Select whether this patron profile is allowed to place loan requests.
    Delivery Select   Select whether the patron is allowed to select their delivery type when placing loan requests.
    Delivery Method   Select the default delivery method for loan requests for this patron profile.
    Delivery Address 80 Enter the default delivery address for loan requests for this patron profile.
     

     Note:  If you chose a default delivery method of Pickup and wish to define a default delivery address, ensure that you have configured your pickup locations via Table Maintenance and ensure that these are associated with the correct pickup location code in your library system. It is this code that is sent in the AcceptItem Message when processing an LON request. See Circulation components for information on configuring pickup locations via Table Maintenance.  

  5. Click Add to add the patron profile to your system.

Patron statuses

Various statuses can be returned as part of the NCIP Lookup User response. These statuses indicate whether a patron's borrowing privilege in your library system is Delinquent, Blocked, Barred or Expired. Define these status codes in Relais and then indicate for a given code whether patrons would be permitted to place a request if their patron record returned that status.

  1. Access Library Registration via Login – Staff.
  2. Search/retrieve your institution's library record. Upon retrieving your library's record, switch to the Contact tab.
  3. To define patron statuses for validation select Status Codes.
    RelaisILL_NCIP_Server_Library.png

     
    Field Characters Description
    NCIP Status Code 20 Enter in the status code returned in the LookupUser response from your library system. The typical values returned are OK, DELINQUENT, BLOCKED, BARRED, and EXPIRED. Please check with your library system vendor to see if there are other specific status codes that are returned in their LookupUser response that you can configure.
    Allow ILL   Select whether a patron would be permitted to place a request if their record is returned with the configured status.
  4. Click Add to add the patron profile to your system.

 

Unit libraries

Some library system vendors return a patron's unit library (the library to which they are registered in your library system) in the NCIP LookupUser response. If this is the case, these library codes will need to be defined as part of your NCIP configuration in Relais. Check with your library system vendor to see if they return a unit library in their LookupUser response. Click the Unit Libraries button to invoke the NCIP Unit Library Mapping window.

  1. Access Library Registration via Login – Staff.
  2. Search/retrieve your institution's library record. Upon retrieving your library's record, switch to the Contact tab.
  3. To define patron statuses for validation select Unit Libraries.
    RelaisILL_NCIP_Server_Library.png
     
    Field Characters Description
    NCIP Library 25 Enter the code of the unit library in your library system that is sent back in the LookupUser response.
    Relais Library   Enter in your library symbol in Relais to associate the NCIP library to your library in Relais.
  4. Click Add to add the unit library to your configuration. 

Test the Lookup User message

Once you have configured your NCIP settings in Relais and ensured that the relevant configuration required on your library system side has been completed for your NCIP server and any required ports are open, you can test to see if Relais is communicating with your NCIP server by using your patron web pages to log and invoke the LookupUser message.

The patron is required to enter a barcode/ID and pin/password/lastname to validate themselves at the login screen of your patron web access pages.

The barcode/ID is typically the active unique ID associated with the patron record in your library system. The password/pin/lastname is often labeled as such.

Please check with your library system vendor to confirm which fields your patrons should be using to enter their barcode/ID and password/pin/lastname from.

If you are able to successfully log in through the patron access pages and place a request, your NCIP connection is active and working as expected. It is also good to test logging in with patrons who are either blocked or expired as well as those that have patron types that are not allowed to place any or certain types of requests to ensure that the NCIP elements you have configured for patron profiles or status codes are working as expected. 

Circulation components

If you plan to use the Checkout and AcceptItem NCIP messages in Relais, generic patron records and pickup location must be configured.  

Generic patron records

Generic patron records are the patron records in your local library system to which material loaned to other libraries is checked out. Once these generic patron records are created in your library system, update the ilsSettings.ini and/or the ILS Settings section of the Relais.ini as described below.  For customers using the Relais Hosted Service, contact OCLC Support with this information.  

The ilsSettings.ini is called upon updating requests via the staff web and is on the web server which serves up your Relais web pages.

The ILS Settings section in the Relais.ini is used when updating request via the windows Login.  

The basic configuration for generic patrons is identical for both the ilsSettings.ini and the ILS Settings section of the Relais.ini

Loans to default generic patrons

The typical configuration (for NCIP) for loaning items to other libraries is to use generic patron IDs. Use the ILL_Patron_#  fields to record the barcodes for each of the generic patron record(s) created in your local system.

Example:

[ILS SETTINGS - YOURLIBRARYSYMBOL]

USEGENERICPATRONID=N

ILL_PATRON_1=20190000000001

ILL_PATRON_2=20190000000002

It is possible to configure multiple generic patron barcodes. Relais will send the first patron barcode in this section in the CheckoutItem message. If a problem is encountered with this patron during the checkout  (i.e. the patron record is blocked or expired), Relais will automatically send the next barcode in the list until the material is successfully loaned in your local system.

Loans to institution specific patrons

Use the LibrarySymbol_Patron_# fields to record the barcode for any institution specific patron record(s) created in your local system. This allows libraries to track the material they lend to a specific library.

Example:

[ILS SETTINGS - YOURLIBRARYSYMBOL]

USEGENERICPATRONID=N

BVAU_PATRON1=20190000000003

OKQ_PATRON1=20190000000004

ILL_PATRON_1=20190000000001

ILL_PATRON_2=20190000000002

When a request for a given library is updated as a loan, Relais will send this library's barcode in the CheckoutItem message. Note there are also a couple of generic IDs.  These would be used if there is no entry for the library to which the item is to be loaned.

 Note: For Relais Hosted Service customers who use the staff web client to process requests, contact OCLC Support to update these settings. Please provide the appropriate generic patrons IDs as described above.

Pickup Locations

If you allow patrons to use the delivery method of Pickup for material they are requesting through ILL, you will need to ensure that you have your correct library system pickup location codes associated with the pickup locations used by patrons in Relais when they place requests in your system. The AcceptItem NCIP message creates a brief bib and item and places a hold on the brief bib for pickup in your library system when processing a LON request.

  1. Access Table Maintenance > Delivery/Messaging > Pickup Location
  2. Add or modify existing pickup location codes in your Relais system to associate with your library system pickup locations.
    RelaisILL_Pickup_Locations.png
     
    Field Characters Description
    Code   The pickup location code in Relais is a one character code.  You can use A-Z, 0-9, as well as the ~, !, @< #, $, %< ^, &, *, (, ), _, -, +, =, { etc. characters to define these pickup locations. Enter in a single character code.
    Library Symbol   Enter in your institution's library symbol.
    ILS Code 20 Enter in the pickup location code from your library system that represents the pickup location you are creating/modifying in Relais.
    Description 50 Enter in a description of the pickup location. This description will display in the Delivery Location drop down list when placing requests in the system and displays in alphabetical order by description.

     Note: If you wish a commonly used pickup location to move to the top of the display list, enter an * or character at the front of the description to move it to the top of the list.