Patron Information and Machine Management System

Attachment #11 – PIMMS Requirements

PIMMS HLAPI

Patron Information and Machine Management System

High Level Application Programming Interface

Version 0.3 10/8/2014

PIMMS HLAPI (High Level Application Programming Interface)

Introduction

Essentially, the PIMMS system is a data repository intended to maintain a consolidated image of the data maintained by the several different implementations of circulation systems running in client libraries.

By design, PIMMS development used a “bottom-up” approach, to create a flexible data model and a set of web-service functions that allow maintenance of all data attributes within the system. These comprehensive functions were not intended as the primary “every day” interface to the PIMMS system, but primarily as the building blocks for a HLAPI that would streamline the interactions between the circulation systems and the central system. The functions also provide a secondary benefit, as a fallback mechanism to provide access to obscure data attributes that might not be relevant during mainstream operations. The low-level functions have been described in a separate document.

In this document we intend to explain the functions that the circulation systems use to perform the common business practices, and give concrete examples of how calls can be made from a number of different development environments. As the capabilities available in PIMMS client environments vary, the HLAPI attempts to both to simplify the I/O parameters in PIMMS web service calls, and improve performance by minimizing the transmission of redundant data during normal operations.

PIMMS Client Authentication and Authorization

In addition to security by source IP address, all calls to PIMMS web services (and all interactions through the PIMMS GUI) require that the client have a valid userid and pass phrase. For the web services, the userid and pass phrase must be included in the SOAP envelope which encapsulates the transaction data.

When a client obtains a reference to a PIMMS web service, it is required to insert “wsse” security information into the request message. In java, this can be accomplished through a custom HeaderHandlerResolver class. The following java code snippet, from a SOAP header handler, shows the insertion of the relevant SOAP headers which specify the security mechanism, and pass the userid and password to the PIMMS system.

PIMMS Reference Information and Global identifiers

Overview

PIMMS, and previously CMLS, use a number of different types of reference data. The values of these data items are essentially static (changes are extremely rare, or even non-existent), but to maintain flexibility PIMMS has built a mechanism to allow maintenance of this data. In practice, it is expected that client circulation systems will access and cache a local copy of this data, prior to calling other PIMMS HLAPI functions. To remain current, the cache should be refreshed periodically, for example, at boot time or initial client system startup. The caching mechanism and identification of specific reference data values are the responsibility of the client system.

Reasoning

Different circulation systems may use different internal identifiers for data attributes that are present in all systems. In order to maintain consistent data between all the libraries, PIMMS has defined a set of data objects containing unique global identifiers for these attributes. These data objects may be thought of as “lookup tables”. The objects are simple, usually having 3 attributes:-

Id / PIMMS Global identifier. This value must be used to identify a data characteristic in a PIMMS HLAPI transaction
type_code / Short description or abbreviation. This value will normally contain the corresponding value from the old CMLS system, with the intention that circulation systems converting to PIMMS may “know” about CMLS codes and use it to derive the PIMMS Global Identifier.
description / A free-from text description of the attribute.

Table 1: PIMMS Reference Data

A concrete example of a PIMMS reference data object type could be the ReaderInterest object. Three ReaderInterest's are defined, taken from the legacy CMLS system. Note that for this particular reference data, the type_code (e.g. CMLS identifier) happens to be the same as the PIMMS Global id, but this is not necessarily the case. In all cases, where a PIMMS HLAPI web-servicerequires a reference identifier, it is expecting the PIMMS global Id field, not the type_code field.

Id / type_code / description
1 / 1 / Braille
2 / 2 / For Young Reader
3 / 3 / Large Print

Table 2: PIMMS Reader Interest actual values

Specific Reference Data

The web services listed in the table below each export a method getXXXX. This method takes no parameters, and returns a list of available reference data objects. The reference data provided by the web services is contained in the web service names. The circulation system client should call this method on each web service to retrieve the list of valid values for caching.

Web Service Name / Method / Notes
MaintainAddressType / getAddressTypes()
MaintainContactType / getContactTypes() / In this context, the contact is the individual to be contacted in reference to an entity e.g. a library, a patron etc.
MaintainCountry / getCountries()
MaintainDisabilityType / getDisabilityTypes()
MaintainEmailType / getEmailTypes()
MaintainLanguage / getLanguages()
MaintainLibraryType / getLibraryTypes()
MaintainMachineType / getMachineTypes()
MaintainMediaType / getMediaTypes()
MaintainNamePrefixType / getNamePrefixTypes()
MaintainNameSuffixType / getNameSuffixTypes()
MaintainPatronStatus / getPatronStatuses()
MaintainPatronType / getPatronTypes()
MaintainPhoneType / getPhoneTypes()
MaintainPublication / getPublications() / <TODO> Publications may not be “static” enough to load at startup time.
MaintainReaderInterest / getReaderInterests()
MaintainStateProvince / getStateProvinces()

Table 3: PIMMS Reference Data Web Services

Usage

Client systems should call the methods listed above in their system startup/initialization code, and save the data returned in a format that they can reference during processing. The implementation of this cache is up to the client; possible implementations include in-memory arrays, database tables, or even flat files. The client must be able to access the returned information to retrieve the global identifiers that PIMMS expects in its transactions.

The PIMMS HLAPI Methods

The following tables contain the current list of the PIMMS HLAPI method calls. Methods in the API are subject to change, based on client feedback and experience during integration of the API into existing client circulation systems. Note that these methods are described in the WSDL documents that can be retrieved from the following URL XXXX.xml

where XXXX is the name of a PIMMS web service e.g. MaintainPatron.xml

Table 4 – MaintainPatron

Table 5 – MaintainPatronCircId

Table 6 – MaintainContact

Table 7 – MaintainAddress

Table 8 – MaintainEmail

Table 9 – MaintainPhone

Table 10 – MaintainMachine

Table 11 – MaintainSubscription

Table 12 – MaintainPatronTransfer

Table 13 – MaintainMachineTransfer

Table 14 – MaintainUser

Table 15 – MaintainClient

Table 16 – Repair Agency

public HLAPIAddPatronResult hlapiAddPatron( Integer patronTypeId, Integer patronStatusId, Integer disabilityTypeId, Integer libraryId, Integer readerInterestId, String circId, String nameFirst, String nameLast, String nameMiddle, String nameInstitution, String title, String description, String birthYear, Integer prefixTypeId, Integer suffixTypeId, String street, String aptSuite, String addressCity, String addressCounty, String addressZip, Integer countryId, Integer stateProvinceId, Integer languageId, String emailAddress, String phoneNumber)
public HLAPIAddContactResult hlapiAddContact(Integer patronGID, String nameFirst, String nameLast, String nameMiddle, String nameInstitution, String title, String description, String birthYear, Integer prefixTypeId, Integer suffixTypeId, String street, String aptSuite, String addressCity, String addressCounty, String addressZip, Integer countryId, Integer stateProvinceId, Integer languageId, String emailAddress, String phoneNumber, Integer contactTypeId)
public HLAPIAddContactResult HLAPIAddContactBasic(Integer patronId, String nameFirst, String nameLast,
String nameMiddle, String nameInstitution, String title, String description,
String birthYear, Integer prefixTypeId, Integer suffixTypeId, Integer languageId,
String emailAddress, String phoneNumber, Integer contactTypeId);
public HLAPIAddAddressResult hlapiAddAddress(Integer patronGID, String street, String aptSuite, String addressCity, String addressCounty, String addressZip, Integer countryId, Integer stateProvinceId, Integer addressTypeId)
public HLAPIPIMMSResult hlapiAddReaderInterest(Integer patronGID, Integer readerInterestId)
public HLAPIPIMMSResult hlapiAddCircId(Integer patronGID, String circId)
public HLAPIPIMMSResult hlapiAddLanguage(Integer patronGID, Integer languageId)
public hlapiAddEmailResult hlapiAddEmail(Integer patronGID, String emailAddress, Integer emailTypeId)
public hlapiAddPhoneResult hlapiAddPhone(Integer patronGID, String phoneNumber, Integer phoneTypeId)
public HLAPIPIMMSResult hlapiEditPatron( Integer patronGID, Integer patronTypeId, Integer patronStatusId, Integer disabilityTypeId, String nameFirst, String nameLast, String nameMiddle, String nameInstitution, String title, String description, String birthYear, Integer prefixTypeId, Integer suffixTypeId, String street, String aptSuite, String addressCity, String addressCounty, String addressZip, Integer countryId, Integer stateProvinceId, String emailAddress, String phoneNumber)
public HLAPIPIMMSResult hlapiEditPatronDemographics(Integer patronGID, Integer patronTypeId, Integer patronStatusId, Integer disabilityTypeId, String nameFirst, String nameLast, String nameMiddle, String nameInstitution, String title, String description)
public HLAPIPIMMSResult HLAPIEditCircId(Integer patronId, String circId)
Public HLAPIPIMMSResult HLAPIEditType(Integer patronId, Integer patronTypeId, String firstName, String middleName, String lastName, String institutionName)
public HLAPIPIMMSResult hlapiEditStatus(Integer patronGID, Integer patronStatusId)
public HLAPIPIMMSResult hlapiEditDisabilityType(Integer patronGID, Integer disabilityTypeId)
public HLAPIPIMMSResult hlapiEditName(Integer patronGID, String nameFirst, String nameLast, String nameMiddle)
public HLAPIPIMMSResult hlapiEditInstitutionName(Integer patronGID, String institutionName)
public HLAPIPIMMSResult hlapiEditTitle(Integer patronGID, String title)
public HLAPIPIMMSResult hlapiEditDescription(Integer patronGID, String description)
public HLAPIPIMMSResult hlapiEditBirthYear(Integer patronGID, String birthYear)
public HLAPIPIMMSResult hlapiEditNamePrefixType(Integer patronGID, Integer namePrefixTypeId)
public HLAPIPIMMSResult hlapiEditNameSuffixType(Integer patronGID, Integer nameSuffixTypeId)
public HLAPIPIMMSResult hlapiEditAddress(Integer patronGID, String street, String aptSuite, String addressCity, String addressCounty, String addressZip, Integer countryId, Integer stateProvinceId, Integer addressTypeId)
public HLAPIPIMMSResult hlapiEditStreet(Integer patronGID, String street)
public HLAPIPIMMSResult hlapiEditAptSuite(Integer patronGID, String aptSuite)
public HLAPIPIMMSResult hlapiEditCity(Integer patronGID, String addressCity)
public HLAPIPIMMSResult hlapiEditCounty(Integer patronGID, String addressCounty)
public HLAPIPIMMSResult hlapiEditZip(Integer patronGID, String addressZip)
public HLAPIPIMMSResult hlapiEditCountry(Integer patronGID, Integer countryId)
public HLAPIPIMMSResult hlapiEditStateProvince(Integer patronGID, Integer stateProvinceId)
public HLAPIPIMMSResult hlapiEditAddressType(Integer patronGID, Integer addressTypeId)
public HLAPIDeleteResult hlapiDeletePatron(Integer patronGID)
public HLAPIDeleteResult hlapiDeleteReaderInterest(Integer patronGID, Integer readerInterestId)
public HLAPIDeleteResult hlapiDeleteLanguage(Integer patronGID, Integer languageId)
public HLAPIDeleteResult hlapiDeleteCircId(Integer patronGID, String circId)
public HLAPIPIMMSResult hlapiSetActiveAddress(Integer patronGID, Integer addressGID)
public HLAPIPIMMSResult hlapiISetActiveEmail(Integer patronGID, Integer emailGID)
public HLAPIPIMMSResult hlapiSetActivePhone(Integer patronGID, Integer phoneId)
public HLAPIKeyListResult hlapiGetContactKeyList(Integer patronGID)
public HLAPIKeyListResult hlapiGetAddressKeyList(Integer patronGID)
public HLAPIKeyListResult hlapiGetEmailKeyList(Integer patronGID)
public HLAPIKeyListResult hlapiGetPhoneKeyList(Integer patronGID)
public HLAPIKeyListResult hlapiGetLibraryIdByPatronId(Integer patronGID)

Table 4: HLAPI methods from MaintainPatron web service

public HLAPIKeyListResult hlapiGetPIMMSIdByCircId(String patronCircId)
public HLAPICircIdSearchResult hlapiCircIdSearch(String patronCircId)

Table 5: HLAPI methods from MaintainPatronCircId web service

public HLAPIAddAddressResult hlapiAddContactAddress(Integer contactGID, String street, String aptSuite, String addressCity, String addressCounty, String addressZip, Integer countryId, Integer stateProvinceId, Integer addressTypeId)
public HLAPIPIMMSResult hlapiAddContactLanguage(Integer contactGID, Integer languageId)
public hlapiAddEmailResult hlapiAddContactEmail(Integer contactGID, String emailAddress, Integer emailTypeId)
public hlapiAddPhoneResult hlapiAddContactPhone(Integer contactGID, String phoneNumber, Integer phoneTypeId)
public HLAPIPIMMSResult hlapiEditContact(integer contactGID, String nameFirst, String nameLast, String nameMiddle, String nameInstitution, String title, String description, String birthYear, Integer prefixTypeId, Integer suffixTypeId, String street, String aptSuite, String city, String county, String zip, Integer countryId, Integer stateProvinceId, String emailAddress, String phoneNumber, Integer contactTypeId)
public HLAPIPIMMSResult hlapiEditContactName(Integer contactGID, String nameFirst, String nameLast, String nameMiddle)
public HLAPIPIMMSResult hlapiEditContactInstitutionName(Integer contactGID, String institutionName)
public HLAPIPIMMSResult hlapiEditContactTitle(Integer contactGID, String title)
public HLAPIPIMMSResult hlapiEditContactDescription(Integer contactGID, String description)
public HLAPIPIMMSResult hlapiEditContactBirthYear(Integer contactGID, String birthYear)
public HLAPIPIMMSResult hlapiEditContactNamePrefixType(Integer contactGID, Integer namePrefixTypeId)
public HLAPIPIMMSResult hlapiEditContactNameSuffixType(Integer contactGID, Integer nameSuffixTypeId)
public HLAPIPIMMSResult hlapiEditContactType(Integer contactGID, Integer contactTypeId)
public HLAPIPIMMSResult hlapiEditContactAddress(Integer contactGID, String street, String aptSuite, String addressCity, String addressCounty, String addressZip, Integer countryId, Integer stateProvinceId, Integer addressTypeId)
public HLAPIPIMMSResult hlapiEditContactStreet(Integer contactGID, String street)
public HLAPIPIMMSResult hlapiEditContactAptSuite(Integer contactGID, String aptSuite)
public HLAPIPIMMSResult hlapiEditContactCity(Integer contactGID, String addressCity)
public HLAPIPIMMSResult hlapiEditContactCounty(Integer contactGID, String addressCounty)
public HLAPIPIMMSResult hlapiEditContactZip(Integer contactGID, String addressZip)
public HLAPIPIMMSResult hlapiEditContactCountry(Integer contactGID, Integer countryId)
public HLAPIPIMMSResult hlapiEditContactStateProvince(Integer contactGID, Integer stateProvinceId)
public HLAPIPIMMSResult hlapiEditContactAddressType(Integer contactGID, Integer addressTypeId)
public HLAPIDeleteResult hlapiDeleteContact(Integer contactGID)
public HLAPIDeleteResult hlapiDeleteContactLanguage(Integer contactGID, Integer languageId)
public HLAPIPIMMSResult hlapieSetActiveContactAddress(Integer contactGID, Integer addressGID)
public HLAPIPIMMSResult hlapieSetActiveContactEmail(Integer contactGID, Integer emailGID)
public HLAPIPIMMSResult hlapiSetActiveContactPhone(Integer contactGID, Integer phoneGID)
public HLAPIKeyListResult hlapilGetAddressContactKeyList(Integer contactGID)
public HLAPIKeyListResult hlapiGetEmailContactKeyList(Integer contactGID)
public HLAPIKeyListResult hlapiGetPhoneContactKeyList(Integer contactGID)

Table 6: HLAPI methods from MaintainContact web service

public HLAPIPIMMSResult hlapiEditAddress(Integer addressGID, String street, String aptSuite, String city, String county, String zip, Integer countryId, Integer stateProvinceId, Integer addressTypeId)
public HLAPIPIMMSResult hlapiEditAddressStreet(Integer addressGID, String street)
public HLAPIPIMMSResult hlapiEditAddressAptSuite(Integer addressGID, String aptSuite)
public HLAPIPIMMSResult hlapiEditAddressCity(Integer addressGID, String city)
public HLAPIPIMMSResult hlapiEditAddressCounty(Integer addressGID, String county)
public HLAPIPIMMSResult hlapiEditAddressZip(Integer addressGID, String zip)
public HLAPIPIMMSResult hlapiEditAddressCountry(Integer addressGID, Integer countryId)
public HLAPIPIMMSResult hlapiEditAddressStateProvince(Integer addressGID, Integer stateProvinceId)
public HLAPIPIMMSResult hlapiEditAddressType(Integer addressGID, Integer addressTypeId)
public HLAPIDeleteResult hlapiDeleteAddress(Integer addressGID)

Table 7: HLAPI methods from MaintainAddress web service

public HLAPIPIMMSResult hlapiEditEmailAddress(Integer emailGID, String emailAddress)
public HLAPIPIMMSResult hlapiEditEmailType(Integer emailGID, Integer emailTypeId)
public HLAPIDeleteResult hlapiDeleteEmail(Integer emailGID)

Table 8: HLAPI methods from MaintainEmail web service

public HLAPIPIMMSResult hlapiEditPhoneNumber(Integer phoneGID, String phoneNumber)
public HLAPIPIMMSResult hlapiEditPhoneType(Integer phoneGID, Integer phoneTypeId)
public HLAPIDeleteResult hlapiDeletePhone(Integer phoneGID)

Table 9: HLAPI methods from MaintainPhone web service

public HLAPIAddMachineResult hlapiAddMachine(String serialNumber, Integer machineTypeId, Integer machineStatusId, Integer patronGID)
public HLAPIMachineSearchResult HLAPIMachineSearch(String serialNumber, String machineTypeCode);
public HLAPIPIMMSResult HLAPIAssignMachine(Integer sourceCustodianId, Integer machineId,
Integer targetCustodianId);
public HLAPIPIMMSResult hlapiEditMachineStatus(Integer machineGID, Integer machineStatusId)
public HLAPIPIMMSResult hlapiSetMachineAccessoryCount(Integer custodianId, Integer machineTypeId, Integer quantity)
public HLAPIMachineAccessoryResult hlapiGetMachineAccessoryCount(Integer custodianId, Integer machinetypeId)
public HLAPIDeleteResult hlapiDeleteMachine(Integer machineGID)

Table 10: HLAPI methods from MaintainMachine web service

public HLAPIAddSubscriptionResult hlapiAddSubscription(Integer patronGID, Integer mediaTypeId, Integer publicationId, Integer quantity)
public HLAPIPIMMSResult hlapiEditSubscriptionQuantity(Integer subscriptionId, Integer quantity)
public HLAPIDeleteResult hlapiDeleteSubscription(Integer subscriptionId)

Table 11: HLAPI methods from MaintainSubscription web service

public HLAPIPatronTransferResult hlapiInitiateTransfer(Integer sourceLibraryGID, Integer patronGID, Integer targetLibraryGID)
public HLAPIPatronTransferResult hlapiAcceptTransfer(Integer patronTransferId)
public HLAPIPatronTransferResult hlapiRejectTransfer(Integer patronTransferId)
public HLAPIPatronTransferResult hlapiSendXMLData(Integer patronTransferId, String xmlData)
public HLAPIGetPatronTransferResult hlapiGetInitiatedPatronTransfers()
public HLAPIPatronTransferResult hlapiGetHistoricPatronTransfers()
public HLAPIPIMMSResult hlapiMergePatron(Integer oldPatronId, Integer newPatronId)

Table 12: HLAPI Methods from MaintainPatronTransfer web service

public HLAPIMachineTransferResult hlapiInitiateTransfer(Integer sourceCustodianId, Integer machineId, Integer targetCustodianId)
public HLAPIMachineTransferResult hlapiAcceptTransfer(Integer machineTransferId)
public HLAPIMachineTransferResult hlapiRejectTransfer(Integer machineTransferId)
public HLAPIMachineTransferResult hlapiForceMachineTransfer(Integer machineId, Integer targetCustodianId);
public HLAPIGetMachineTransferResult hlapiGetInitiatedMachineTransfers()
public HLAPIGetMachineTransferResult hlapiGetHistoricMachineTransfers()

Table 13: HLAPI Methods from MaintainMachineTransfer web service

public HLAPIAddUserResult hlapiAddUser(String loginName, List<Integer> userGroupId, String password, List<Integer> libraryId)
public HLAPIPIMMSResult hlapiEditPassword(Integre userId, String password)
public HLAPIGetUserPasswordResult hlapiGetPassword(Integer userId)
Public HLAPIPIMMSIdResult hlapiGetUserIdByLoginName(String loginName)
public HLAPIDeleteResult hlapiDeleteUser(String loginName)

Table 14: HLAPI Methods from MaintainUser web service

public HLAPIGetClientLibrariesResult hlapiGetLibrariesByClientId(Integer clientId)

Table 15: HLAPI Methods from MaintainClient web service

public HLAPIAddRepairAgencyResult HLAPIAddRepairAgency(String repairAgencyId,
String firstName, String lastName, String institutionName, String aptSuite,
String street, String city, Integer stateProvinceId, String zip, String county,
Integer countryId, String emailAddress, String phoneNumber, List<Integer> libraryId)
public HLAPIDeleteResult HLAPIDeleteRepairAgency(Integer repairAgencyId)

Table 16: HLAPI Methods from MaintainRepairAgencyweb service

Patron Maintenance

With a few exceptions, adding, changing and deleting patron information from the PIMMS system is affected through the maintainPatron web service

Adding a Patron

When a new patron is added to a circulation system, the patron information is also added to the PIMMS system. This is achieved through a call to the maintainPatron web service, to the hlapiAddPatron method.

Adding a patron to PIMMS creates a number of data objects in the system. The hlapiAddPatron call returns the PIMMS global ID's (GID's) of all of these objects. PIMMS contains low-level API calls to manipulate each of these object independently.

IMPORTANT - Passing a null in a String parameter or a -1 in an Integer parameter is allowed for some parameters, and will the leave the existing value of that parameter unchanged in the PIMMS system. However, passing a blank String (indicated by “”) will replace the value stored in PIMMS with the empty String.

Refer to Table 4 for a list of required parameters, these parameters will not accept a null or -1.

Method signature

public HLAPIAddPatronResult hlapiAddPatron(Integer patronTypeId, Integer patronStatusId, Integer disabilityTypeId, Integer libraryId, Integer readerInterestId, String circId, String nameFirst, String nameLast, String nameMiddle, String nameInstitution, String title, String description, String birthYear, Integer namePrefixTypeId, Integer nameSuffixTypeId, String street, String aptSuite, String addressCity, String addressCounty, String addressZip, Integer countryId, Integer stateProvinceId, Integer languageId, String emailAddress, String phoneNumber)

Parameters

Parameter / Type / Description
patronTypeId / Integer / Id field from the PatronType reference list
patronStatusId / Integer / Id field from the PatronStatus reference list
disabilityTypeId / Integer / Id field from the DisabilityType reference list
libraryId / Integer / Id field from the Library reference list
readerInterestId / Integer / Id field from the ReaderInterest reference list
circId / String / Circulation-system assigned Patron Id
nameFirst / String / Patron first name
nameLast / String / Patron last name (surname)
nameMiddle / String / Patron middle initial or middle name
nameInstitution / String / Institution name
title / String / Patron title
description / String / Patron description
birthYear / String / yyyy format
namePrefixTypeId / Integer / Id field from the NamePrefixType reference list
aptSuite / String / Patron secondary address information line
addressCity / String / Patron city
addressCounty / String / Patron county
addressZip / String / Patron zip
countryId / Integer / Id field from the Country reference list
stateProvinceId / Integer / Id field from the StateProvince reference list
languageId / Integer / Id field from the Language reference list
emailAddress / String / Patron Email Address
phoneNumber / String / Patron Phone Number

Return Value (HLAPIAddPatronResult)