An Introduction to NCIP

October 2, 2002Mark H Needleman Sirsi CorporationNCIP Implementers Forum

Revised January 2, 2008Lynne Branche BrownInnovative Interfaces, Inc.NCIP Implementers Group

Scope of the Standard

A repertoire of messages & associated rules of syntax and semantics

Between and among computer based applications

Does not define circulation functions or policies

Does not define user interface

Functions Supported

Direct consortial borrowing

Circulation/InterLibrary Loan Interaction

Self-service Circulation

NCIP Structure

Part 1: Protocol DefinitionPart 2: Implementation Profile 1XML DTD and SchemaVendor Application Profiles

NCIP Documentation has multiple parts:

Circulation Interchange Part 1: Protocol

Defines the ServicesDefines the MessagesDefines the Data ElementsDefines the error codesDefines the extensibility mechanismProvides some lists of enumerated

data typesProvides a simple state table

Circulation Interchange Part 1: Protocol, con’t

Defines the concept of profilesProvides a template for building

Implementation and Application Profiles

Provides guidelines for activities of maintenance and registration agencies

Not bound to any particular technologies

Circulation Interchange Part 2: Protocol Implementation Profile 1

Defines the message encoding (XML)Defines the underlying Transport

Protocols - HTTP/HTTPS and TCPDefines Character Set - Unicode/UTF-

8Defines some behavior rulesProvides an encoding of enumerated

datatypes

XML DTD and Schema

Provides the XML encoding of the messages

Used by a parser or application to ensure received message is valid

Vendor Application Profiles

Define how to use NCIP within a particular application domain

Conform to an Implementation ProfileDescribes application area and

participating applicationsDefines the business rulesDefines required servicesDefines required and conditionally

required data elements

Vendor Application Profiles, con’t

Defines an event table and messages sent and received when those events occur

May provide additional enumerated data types

Defines transport protocolsMay define security and privacy

requirementsMay provide additional

implementation guidelines

Vendor Application Profiles MAY NOT

Redefine data elements specified in the protocol

Add additional messages Define new objects Define additional transport protocols Add data elements to messages Make required data elements optional Specify a data type inconsistent to how its

defined in the protocol or implementation profile

Technical Architecture

3 Service Types

3 Object Classes

3 Service Types

Lookup “Tell me these things about this

object.”Update

“Please take this action.”Notification

“I have taken this action.”

Service Definitions

Every “Service” is a pair of messages: an “Initiation Message” and a “Response Message”

Each message provides complete context for it to be understood The protocol is designed NOT to

require any particular sequence of services.

3 Object Types

UsersItems Agencies (Libraries)

Transactions are associations between one or more of the objects

Lookup Service Type

Lookup AgencyLookup ItemLookup UserAuthenticate UserLookup Version

Lookup Service Type

Lookups are about a unique thing

They do not support discovery or searching.

Update Services

Typical Update Transactions: Request Item and Cancel Request

Item Check Out Item and Undo Check Out

Item Renew Item Recall Item and Cancel Recall Item Send User Notice Check In Item

Update Services

Object maintenance: Create Agency and Update Agency Create Item, Update Item and Update

Request Item Create User and Update User Create User Fiscal Transaction

Create Services used for new objectsUpdate Services include modify and

delete

Notification Services

Typical Notification Transactions: Item Requested and Item Request

Cancelled Item Checked Out Item Renewed Item Recalled and Item Recall

Cancelled User Notice Sent Item Checked In

Notification Services

Object maintenance: Agency Created and Agency

Updated Item Created, Item Updated and

Item Request Updated User Created and User Updated User Fiscal Transaction Created

Notification Services

Item ShippedItem ReceivedCirculation Status Change

ReportedCirculation Status Updated

Notification Response

Notifications occur after the fact - no ability to say “don’t do that”

Only possible responses: Did not understand message Understood message

Mandated Action

Flag on Request Messages

Used to turn a request into a de facto notification

May require out of band handling

Syntax and Encoding

XML DTDUTF-8 encoding of Unicode (UCS-

2) ASCII is valid in this encoding. But other systems are NOT

restricted to ASCII, and you should be prepared to receive such data.

Scheme/Values

Mechanism for extensibilityProvides mechanism for NCIP to

make use of other standardized lists

Some defined in NCIP ProtocolProvides ability for locally

defined values

Schemes and Values

Two kinds of Schemes: Closed

Must be supported in order to conformCannot be extended

OpenCan be extended

For many (but not all) data elements NCIP provides some lists that must be supported for interoperability purposes

Use of other Standardized Lists

Language CodesDefined by ISO 639-2 Bibliographic

Language Codes

Currency Codes Defined by ISO 4217 Codes for the

representation of currencies

Allow for Extensibility

Bibliographic Record Identifier Code:ANBNBGFBNBNCARL: UNCOVERCNLCCNNLM TCNOCLCRLIN

Allow for Local Practice

Agency User Privilege Type (Public)AdultChildSeniorStaffYoung Adult

Agency User Privilege Type (Academic)FacultyGraduatePostdoctoralStaffUndergraduate

Scheme Defintion

Scheme names are URI’sValues within any Scheme must

be uniqueOnce published, the list of

Values must not change in any way - if changes are made a different URI is defined

Example Scheme/Value<UserPrivilege>

<UniqueAgencyId><Scheme>http://www.librarylist.org </Scheme><Value> Needleman Library </Value></UniqueAgencyId><AgencyUserPrivilegeType><Scheme> http://www.needleman.com/patrons

</Scheme><Value> Platinum User </Value></AgencyUserPrivilegeType>...

</UserPrivilege>

Datatypes Each PCDATA element has a datatype associated

with it

Datatypes are subset of those defined in W3C XML Schema Language:

dateTimestringpositiveIntegernonNegativeIntegerInteger

In DTD datatypes defined using #FIXED attributes

NCIP Schema uses “real” datatypes

Headers

Each message has a header Initiation messages have an Initiation

Header Response Messages have a Response

Header

Header provides for security and identification From System and Agency From System and Agency Authentication To System and Agency

Unique Id’s

Agency Id’s Registration scheme to ensure

uniqueness Value in Scheme

User Id’s, Item Id’s and Request Id’s are compound; they include the Agency Id

Element Id’s

Lookup initiation messages (except Lookup Version and Authenticate User) must include “Element Id” elements.

These are used to specify “these things,” as in “Tell me these things about this object.”

Element Id can be used to ask for data about the object in other messages as well

Use of Element Id

One of these for each object class: Agency Element Id Item Element Id User Element Id

Each of them has a corresponding Closed Scheme

Identifies which elements of the object are desired in a Lookup service (or other relevant messages)

Element Id in a Request

<ItemElementType><Scheme>

http://www.niso.org/ncip/v1_0/schemes/itemelementtype/itemelementtype.scm

</Scheme><Value>Bibliographic Description

</Value></ItemElementType>

Optional Fields in Response

<ItemOptionalFields>

<BibliographicDescription><Author> Mark Needleman </Author><Edition> 1st </Edition><PlaceOfPublication> St Louis

</PlaceofPublication><PublicationDate> 2003 </PublicationDate><Title> A Nobel Prize Winning Novel </Title></BibliographicDescription>

</ItemOptionalFields>

Application Roles

For a given connection, there is: 1 and only 1 initiating application

(e.g., self-service machine), and 1 and only 1 responding application

(e.g., circ system). Initiators may NOT send a second

message until the first is responded to.Responders may NOT send initiation

messages EVER on that connection.

Application Roles

Applications MAY establish multiple connections at the same time.

The Standard is written in terms of “initiating application” and “responding application”; this is always in the context of a given connection, not in the broader context of the application as a whole

Application Roles

Initiating application waits for the response message or a timeout.

Applications may keep the connection open in an “Idle” state in anticipation of exchanging a series of message pairs (to avoid the costs of establishing a connection for each exchange).

State Tables

Do NOT govern the state of the circulation transaction

DO govern the state of the exchange of the initiation/response message pair Initiating application is in IDLE or

WAITING state Responding application is in IDLE or

PROCESSING state

Messaging State Tables

INITIATOR RESPONDER

IDLE

WAITING PROCESSING

IDLEInitiation Message

Messaging State Tables

INITIATOR RESPONDER

IDLE

WAITING PROCESSING

IDLE

Response Message

Transport Protocol Requirements

Confirmed Service Initiation/Response message pairs The Response message confirms

the service.The transport layer must

indicate that the peer has disconnected.

Supported Transport Protocols

Initiator chooses from these 3: TCP/IP HTTP HTTPS

Responder must reply on same connection - and thus using the same protocol with which it got the initiation message

Behavior Rules

Definition of SuccessOmission of requested elementsInclusion of unrequested elementsUpdate processingError identificationMessaging errorsProcessing errors

Omission of Requested Items

Applies to entire Lookup Service Type and to “piggy-backed” lookups on Update Services.

Permits omission of some of the data the initiator asked for.

Example: Initiation message requests user’s date of birth but policy at responder does not allow it to be revealed

Inclusion of Unrequested data

Some elements in the messages are defined so the requester can specify what information it wants to get back Element Id fields Information about holds on at item

Responder may not include such elements if not requested by Initiator

Update Processing

Responding application will behave as if all deletions requested were performed before all additions requested in the same message

If an update to one element causes an update to another element not specifically asked - a Notification message may be used to inform the other side Example - change of birthday causes user

category to change

Errors

Messaging Errors

Processing Errors

Messaging Errors

Indicate lack of understanding of the message: Invalid XML XML not conformant to the DTD Unknown scheme

Processing Errors

Indicate inability or unwillingness to perform the action requested User Delinquent Unknown item Item does not circulate (Checkout) Maximum renewals exceeded

(Renewal)

Security

Encryption HTTPS

Authentication of Systems and Agencies

Application Profiles can defined other security requirements and mechanisms

Support for Future Versions

Version Attribute on each message to identify version - attribute contains the URI of the DTD or Schema it conforms to

Lookup Versions to find out what versions the other side supports

Responder may (but is not required to) respond with list of supported versions if it gets a message in a version it does not support