How to Set up and Use the NCIP Server

How to Set up and Use the NCIP Server

Version 18.01 and later

CONFIDENTIAL INFORMATION

The information herein is the property of Ex Libris Ltd. or its affiliates and any misuse or abuse will result in economic loss. DO NOT COPY UNLESS YOU HAVE BEEN GIVEN SPECIFIC WRITTEN AUTHORIZATION FROM EX LIBRIS LTD.

This document is provided for limited and restricted purposes in accordance with a binding contract with Ex Libris Ltd. or an affiliate. The information herein includes trade secrets and is confidential.

DISCLAIMER

The information in this document will be subject to periodic change and updating. Please confirm that you have the most current documentation. There are no warranties of any kind, express or implied, provided in this documentation, other than those expressly agreed upon in the applicable Ex Libris contract. This information is provided AS IS. Unless otherwise agreed, Ex Libris shall not be liable for any damages for use of this document, including, without limitation, consequential, punitive, indirect or direct damages.

Any references in this document to third-party material (including third-party Web sites) are provided for convenience only and do not in any manner serve as an endorsement of that third-party material or those Web sites. The third-party materials are not part of the materials for this Ex Libris product and Ex Libris has no liability for such materials.

TRADEMARKS

"Ex Libris," the Ex Libris bridge , Primo, Aleph, Alephino, Voyager, SFX, MetaLib, Verde, DigiTool, Preservation, URM, Voyager, ENCompass, Endeavor eZConnect, WebVoyage, Citation Server, LinkFinder and LinkFinder Plus, and other marks are trademarks or registered trademarks of Ex Libris Ltd. or its affiliates.

The absence of a name or logo in this list does not constitute a waiver of any and all intellectual property rights that Ex Libris Ltd. or its affiliates have established in any of its products, features, or service names or logos.

Trademarks of various third-party products, which may include the following, are referenced in this documentation. Ex Libris does not claim any rights in these trademarks. Use of these marks does not imply endorsement by Ex Libris of these third-party products, or endorsement by these third parties of Ex Libris products.

Oracle is a registered trademark of Oracle Corporation.

UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Ltd.

Microsoft, the Microsoft logo, MS, MS-DOS, Microsoft PowerPoint, Visual Basic, Visual C++, Win32,

Microsoft Windows, the Windows logo, Microsoft Notepad, Microsoft Windows Explorer, Microsoft Internet Explorer, and Windows NT are registered trademarks and ActiveX is a trademark of the Microsoft Corporation in the United States and/or other countries.

Unicode and the Unicode logo are registered trademarks of Unicode, Inc.

Google is a registered trademark of Google, Inc.

Document released: August 31, 2014

Web address: http://www.exlibrisgroup.com

Table of Contents 3

1 General 5

2 Transport Layer 5

3 LookupVersion 6

4 Supported Services 6

4.1 Authenticate User Service 6

4.2 Lookup Item Service 6

4.3 Lookup User Service 6

4.4 Check Out Item Service 7

4.5 Check In Item Service 7

4.6 Request Item Service 7

4.7 Cancel Request Item Service 8

4.8 Accept Item Service 8

5 Supported Element and Values 8

5.1 General Elements 8

5.1.1 The Response Header 8

5.1.2 The Item Element Type and Item Optional Fields 9

5.1.3 The User Element Type and User Optional Fields 9

5.2 Services 11

5.2.1 Authenticate User Service 11

5.2.2 Lookup Item Service 12

5.2.3 LookupUser Service 13

5.2.4 CheckOutItem Service 14

5.2.5 CheckInItem Service 14

5.2.6 Request Item Service 15

5.2.7 Cancel Request Item Service 17

5.2.8 Accept Item Service 18

6 ALEPH as a Pickup Agency 18

6.1 Building the BIB Record 19

6.2 Building the Item Record and the Request 21

7 Setup 23

7.1 ADM Tables 23

7.1.1 tab_ncip.conf 23

7.1.2 tab_ncip_record_id 24

7.1.3 DTD 25

7.2 Alephe Tables 25

7.2.1 tab_ncip_interface 25

7.2.2 Tab_ncip_scheme 27

7.3 www_server.conf 27

7.4 Setting up Agencies 27

7.5 Home Library 28

7.6 Creation and Retrieval of a Temporary Item 28

7.6.1 Temporary Item – Unique Barcode 28

7.6.2 Temporary Item – External Barcode (Retrieval by Non Unique call-Number 29

8 Running and Testing the NCIP Servers 30

Appendix A. Sample Messages and Responses 31

RequestItem Sample 31

RequestItemReponse Sample 32

AcceptItem Sample 35

AcceptItemReponse Sample 38

1 General

The NISO Circulation Interchange Protocol (NCIP) defines a repertoire of messages and associated rules of syntax and semantics for use by applications to:

· Perform the functions necessary to lend items.

· Provide controlled access to electronic resources.

· Facilitate co-operative management of these functions.

The standard specifically addresses conditions in which the applications that initiate the lending of items or control of access must transmit information about the user, agency, items, and/or access that is essential to successful conclusion of the function.

NCIP is a connection-oriented, sessionless, protocol.

· Connection-oriented - Circulation processes happen in real time, often with the user present and awaiting service. A connection-oriented protocol facilitates a timely interaction between applications and allows the application requesting a service to know with confidence that a message was received by the partner application.

· Sessionless - The lifecycle of a particular circulation activity provided by an agency to a user is often extended over days, weeks, or months. It is therefore impractical to maintain sessions between two applications.

An NCIP message must be valid XML that conforms to the NCIP DTD (Document Type Definition). The NCIP DTD defines the content of an NCIP message as a series of elements, each of a complex, simple or EMPTY type.

2 Transport Layer

The NCIP server is supported either over a TCP/IP transport layer or over HTTPS.

When TCP/IP is used, a special NCIP server port is used as the access point to the NCIP server. In that case the NCIP server activity is logged in a separate log file. Many separate NCIP servers can be run, each with its own configuration in the tab_ncip.conf table, and each serving a single ADM library. More than one NCIP server may serve the same ADM library.

When HTTPS is used, the access to the NCIP server is done through ALEPH’s web port. Each initiator is assigned an ADM library to which its NCIP messages will be directed. The way this is done is described below in the Setup chapter. The NCIP server activity will be logged in the www_server log file.

3 LookupVersion

The LookupVersion message is supported and can be used to report the NCIP protocol version number that is supported. The structure of the supported message and response is defined in the DTD file http://www.niso.org/ncip/v1_0/imp1/dtd/ncip_version.dtd

Successful Result: The responding application returns the requested data.

4 Supported Services

Out of the 45 messages that are defined in the NCIP Protocol, 7 are supported by the ALEPH NCIP server. The messages are supported according to the DTD http://www.niso.org/ncip/v1_0/imp1/dtd/ncip_v1_0.dtd.

4.1 Authenticate User Service

This service requests authentication of a User presumed to be known to an Agency. Authentication indicates only that the User is known by the responding Agency. The initiating application must determine the type of data the responding application requires for authentication.

Successful Result: The responding application authenticates the User and returns the unique Id of the User.

4.2 Lookup Item Service

This service requests data about a particular Item known to the responding application. The initiator provides the unique Id of the Item and a list of elements for which data is requested.

Successful Result: The responding application returns the requested data to the initiating application.

4.3 Lookup User Service

This service requests data about a particular User known to the responding application. The initiator provides the unique Id of the User and a list of elements for which data is requested.

Successful Result: The responding application returns the requested data to the initiating application.

4.4 Check Out Item Service

This service requests that the responding application check out an Item to a User. The initiating application may also request data about the User and/or Item involved with this check-out.

Successful Result: The responding application checks out the Item to the User until the date indicated in the response. It may also supply the data elements requested.

Note

The NCIP Server consults the "tab_attr_sub_library" settings (in the ADM library).

A "check out" service is only performed if the IP address of the sending application is registered as type 1 in Column 2 of tab_attr_sub_library.

4.5 Check In Item Service

This service requests that the responding application check in an Item. It also permits the initiating application to request data about the User and/or Item involved with this check in.

Successful Result: The responder checks in the Item and returns requested User or Item data.

Note

The NCIP Server consults the "tab_attr_sub_library" settings (in the ADM library).

A "check in" service is only performed if the IP address of the sending application is registered as a type 1 or 2 in Column 2 of tab_attr_sub_library.

4.6 Request Item Service

This service requests that the responding application place a request on an Item for a User whether or not the Item is immediately available. The initiating application indicates the type of request being made. The initiating application may also request data about the User and/or Item involved with this request.

Successful Result: The responding application places the request and provides data about where the Item may be picked up and the date it expects the Item to be available. It may also supply the data elements requested.

Note

The request will be placed with the pickup location set to the value that is specified as the FromAgencyId. Please refer to the chapter that describes Setting up Agencies for the required configurations.

4.7 Cancel Request Item Service

This service requests that the responding application cancel a previous request for an Item. The initiating application may also request data about the User and/or Item involved with this request cancellation.

Successful Result: The responding application cancels the request. It may also supply the data elements requested.

4.8 Accept Item Service

This service requests that the responding application accept an Item to be circulated to a User. The responding application may be a third party that has no prior knowledge of either the User or the Item. If there is a possibility that the responding application has no prior knowledge of either the User or the Item, the request may optionally include data about the User and/or the Item.

Successful Result: The responder accepts the Item for the action specified. It returns the Unique Request Id. It will also provide a Unique Item Id that the initiating application may use to reference the Item in subsequent messages.

Detailed information on the actions taken by the ALEPH system upon receiving an AcceptItem message can be found in a separate chapter (See chapter 6).

5 Supported Element and Values

The messages and responses that are supported by the ALEPH NCIP server conform to the DTD http://www.niso.org/ncip/v1_0/imp1/dtd/ncip_v1_0.dtd. The elements and values that are described below are taken from the above mentioned DTD.

5.1 General Elements

This chapter describes the supported elements that are common to many of the supported services.

5.1.1 The Response Header

The Response Header element in all of the NCIP server’s responses uses the following format:

ELEMENT ResponseHeader (FromAgencyId , ToAgencyId)

The values of the FromAgencyId elements will be those that were used in the initiating message as ToAgencyId.

The values of the ToAgencyId elements will be those that were used in the initiating message as FromAgencyId.

5.1.2 The Item Element Type and Item Optional Fields

The following values of the ItemElementType element are supported:

Item Description

BibliographicDescription

Circulation Status

If the ItemElementType element is used in the message with the value ‘Item Description’, the ItemOptionalFields element will be found in the response.

The following structure of the response ItemOptionalFields element is supported.

ItemOptionalFields

BibliographicDescription

Author

BibliographicItemId

BibliographicItemIdentifier

BibliographicRecordIdentifier

PublicationDate

Publisher

Title

MediumType

ItemDescription

VisibleItemId

CallNumber

Circulation Status

Either BibliographicItemIdentifier or BibliographicRecordIdentifier will be returned, depending on:

If the incoming message uses one of these elements, the response will include the same element.

If the incoming message did not use these elements then if the bibliographic_item_id variable of tab_ncip.conf is ISSN or ISBN, then BibliographicItemIdentifier will be returned. In any other case BibliographicRecordIdentifier will be returned.

5.1.3 The User Element Type and User Optional Fields

The following values of the UserElementType are supported:

Name Information

User Address Information

User Privilege

Visible User Id

If the UserElementType element is used in the message with the value ‘Name Information’, the UserOptionalFields element will be found in the response with the NameInformation element.

If the UserElementType element is used in the message with the value ‘User Address Information’, the UserOptionalFields element will be found in the response with the UserAddressInformation element

If the UserElementType element is used in the message with the value ‘User Privilege’, the UserOptionalFields element will be found in the response with the UserPrivilege element.

If the UserElementType element is used in the message with the value ‘Visible User Id’, the UserOptionalFields element will be found in the response with the UserVisibleId element.

The following structure of the response UserOptionalFields element is supported.

UserOptionalFields

NameInformation

PersonalNameInformation

UnstructuredPersonalUserName

VisibleUserId

UniqueAgencyId

VisibleUserIdentifierType

VisibleUserIdentifier

UserAddressInformation

UserAddressRoleType

ValidFromDate

ValidToDate

PhysicalAddress