Patron Import Service

General Purpose

The patron import service will will be to add, update, or (for some data) delete existing patron personal information such as Name, Address, and the like. This program will not update or change Patron barcodes or Patron Groups because of the associated circulation history – barcodes can be expired, though.

Requirements

Voyager 8.2 and higher.

XSD

The input is based on the patron schema.

Input Parameters

The input file must be in xml format which conforms to the patron.xsd schema.  Each patron record will be represented by a single xml record.  The error codes and texts are:

ParameterDescriptionValue
testWhen test=yes, process the attached record in test mode, reporting what in the patron record would be updated or any errors encountered if the record cannot be updated (in the appropriate children of the <info> element.yes or no – defaults to no if not specified
opidan operator ID for putting in the MODIFY_OPID where possibleDefaults to XMLLOAD if not specified.
helpWhen help=yes, provide help information in the <pat:helpText> element.

Input XML Format

The input is based on the patron.xsd schema.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<patron xmlns="http://www.exlibris.com/Voyager/patron" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <action>Add</action>
    <matchId>
        <idNumber>123</idNumber>
        <idType>InstitutionID</idType>
    </matchId>
    <patronBarcodeList>
        <patronBarcode>
            <barcode>abc123</barcode>
            <patronGroup>group</patronGroup>
            <barcodeStatus>Active</barcodeStatus>
            <barcodeModifiedDate>1967-08-13</barcodeModifiedDate>
        </patronBarcode>
    </patronBarcodeList>
    <registrationDate>1967-08-13</registrationDate>
    <expirationDate>1967-08-13</expirationDate>
    <purgeDate>1967-08-13</purgeDate>
    <voyagerDate>1967-08-13</voyagerDate>
    <libraryLocationCode>location</libraryLocationCode>
    <institutionID>abc123</institutionID>
    <ssn>123456789</ssn>
    <nameType>personal</nameType>
    <firstName>Patron</firstName>
    <lastName>Patron</lastName>
    <middleName>Q</middleName>
    <title>Dr.</title>
    <patronPin>abc123</patronPin>
    <smsNumber>1234567890</smsNumber>
    <department>department</department>
    <major>major</major>
    <birthDate>1967-08-13</birthDate>
    <transactionCounters>
        <historicalCharges>0</historicalCharges>
        <claimsReturnedCount>0</claimsReturnedCount>
        <selfShelvedCount>0</selfShelvedCount>
        <lostItemsCount>0</lostItemsCount>
        <lateMediaReturns>0</lateMediaReturns>
        <historicalBookings>0</historicalBookings>
        <cancelledBookings>0</cancelledBookings>
        <unclaimedBookings>0</unclaimedBookings>
        <historicalCallslips>0</historicalCallslips>
        <historicalDistributions>0</historicalDistributions>
        <historicalShortLoans>0</historicalShortLoans>
        <unclaimedShortLoans>0</unclaimedShortLoans>
        <recallsPlaced>0</recallsPlaced>
        <holdsPlaced>0</holdsPlaced>
        <itemsRecalled>0</itemsRecalled>
    </transactionCounters>
    <tempAddressList>
        <tempAddress>
            <addressStatusCode>Normal</addressStatusCode>
            <beginDate>1967-08-13</beginDate>
            <endDate>1967-08-13</endDate>
            <line1>a</line1>
            <line2>a</line2>
            <line3>a</line3>
            <line4>a</line4>
            <line5>a</line5>
            <city>a</city>
            <stateProvince>a</stateProvince>
            <postalCode>a</postalCode>
            <country>a</country>
            <patronPhoneList>
                <patronPhone>
                    <phone>a</phone>
                    <type>Primary</type>
                </patronPhone>
            </patronPhoneList>
        </tempAddress>
        <overlayAction>Overlay</overlayAction>
    </tempAddressList>
    <permAddress>
        <addressStatusCode>Normal</addressStatusCode>
        <line1>a</line1>
        <line2>a</line2>
        <line3>a</line3>
        <line4>a</line4>
        <line5>a</line5>
        <city>a</city>
        <stateProvince>a</stateProvince>
        <postalCode>a</postalCode>
        <country>a</country>
        <patronPhoneList>
            <patronPhone>
                <phone>a</phone>
                <type>Primary</type>
            </patronPhone>
        </patronPhoneList>
    </permAddress>
    <emailList>
        <patronEmail>
            <email>a</email>
            <beginDate>1967-08-13</beginDate>
            <endDate>1967-08-13</endDate>
            <addressStatusCode>Normal</addressStatusCode>
        </patronEmail>
        <overlayAction>Overlay</overlayAction>
    </emailList>
    <noteList>
        <patronNote>
            <note>a</note>
            <type>a</type>
        </patronNote>
        <overlayAction>Overlay</overlayAction>
    </noteList>
    <patronStatList>
        <overlayAction>Overlay</overlayAction>
        <patronStat>a</patronStat>
    </patronStatList>
</patron>

Input URL Syntax

http://server:port/vxws/patronImport with attached XML file

Output XML Format

Service response example – when no error occurs

<?xml version="1.0" encoding="UTF-8"?>
<patron xmlns="http://www.exlibris.com/Voyager/patron" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <info>
        <reply>
            <reply-text>OK</reply-text>
            <reply-code>00</reply-code>
        </reply>
    </info>
</patron>

Service response example – when error occurs. The response will be the POSTed document with an <info> element added with the errors listed in the <reply> elements.

<?xml version="1.0" encoding="UTF-8"?>
<patron xmlns="http://www.exlibris.com/Voyager/patron" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <info>
        <reply>
            <reply-text>Action = Insert, but match found in database. Record not processed.</reply-text>
            <reply-code>12</reply-code>
        </reply>
    <info>
    <action>Insert</action>
    <matchId>
        <idNumber>123</idNumber>
        <idType>InstitutionID</idType>
    </matchId>
    <patronId>123</patronId>
    <patronBarcodeList>
        <patronBarcode>
            <barcode>abc123</barcode>
            <patronGroup>group</patronGroup>
            <barcodeStatus>Active</barcodeStatus>
            <barcodeModifiedDate>1967-08-13</barcodeModifiedDate>
        </patronBarcode>
    </patronBarcodeList>
    <registrationDate>1967-08-13</registrationDate>
    <expirationDate>1967-08-13</expirationDate>
    <purgeDate>1967-08-13</purgeDate>
    <voyagerDate>1967-08-13</voyagerDate>
    <libraryLocationCode>location</libraryLocationCode>
    <institutionID>abc123</institutionID>
    <ssn>123456789</ssn>
    <nameType>personal</nameType>
    <firstName>Patron</firstName>
    <lastName>Patron</lastName>
    <middleName>Q</middleName>
    <title>Dr.</title>
    <patronPin>abc123</patronPin>
    <smsNumber>1234567890</smsNumber>
    <department>department</department>
    <major>major</major>
    <birthDate>1967-08-13</birthDate>
    <transactionCounters>
        <historicalCharges>0</historicalCharges>
        <claimsReturnedCount>0</claimsReturnedCount>
        <selfShelvedCount>0</selfShelvedCount>
        <lostItemsCount>0</lostItemsCount>
        <lateMediaReturns>0</lateMediaReturns>
        <historicalBookings>0</historicalBookings>
        <cancelledBookings>0</cancelledBookings>
        <unclaimedBookings>0</unclaimedBookings>
        <historicalCallslips>0</historicalCallslips>
        <historicalDistributions>0</historicalDistributions>
        <historicalShortLoans>0</historicalShortLoans>
        <unclaimedShortLoans>0</unclaimedShortLoans>
        <recallsPlaced>0</recallsPlaced>
        <holdsPlaced>0</holdsPlaced>
        <itemsRecalled>0</itemsRecalled>
    </transactionCounters>
    <tempAddressList>
        <tempAddress>
            <addressStatusCode>Normal</addressStatusCode>
            <beginDate>1967-08-13</beginDate>
            <endDate>1967-08-13</endDate>
            <line1>a</line1>
            <line2>a</line2>
            <line3>a</line3>
            <line4>a</line4>
            <line5>a</line5>
            <city>a</city>
            <stateProvince>a</stateProvince>
            <postalCode>a</postalCode>
            <country>a</country>
            <patronPhoneList>
                <patronPhone>
                    <phone>a</phone>
                    <type>Primary</type>
                </patronPhone>
            </patronPhoneList>
        </tempAddress>
        <overlayAction>Overlay</overlayAction>
    </tempAddressList>
    <permAddress>
        <addressStatusCode>Normal</addressStatusCode>
        <line1>a</line1>
        <line2>a</line2>
        <line3>a</line3>
        <line4>a</line4>
        <line5>a</line5>
        <city>a</city>
        <stateProvince>a</stateProvince>
        <postalCode>a</postalCode>
        <country>a</country>
        <patronPhoneList>
            <patronPhone>
                <phone>a</phone>
                <type>Primary</type>
            </patronPhone>
        </patronPhoneList>
    </permAddress>
    <emailList>
        <patronEmail>
            <email>a</email>
            <beginDate>1967-08-13</beginDate>
            <endDate>1967-08-13</endDate>
            <addressStatusCode>Normal</addressStatusCode>
        </patronEmail>
        <overlayAction>Overlay</overlayAction>
    </emailList>
    <noteList>
        <patronNote>
            <note>a</note>
            <type>a</type>
        </patronNote>
        <overlayAction>Overlay</overlayAction>
    </noteList>
    <patronStatList>
        <overlayAction>Overlay</overlayAction>
        <patronStat>a</patronStat>
    </patronStatList>
</patron>

Service response (when help=yes parameter is included or no document is POSTed):

<?xml version="1.0" encoding="UTF-8"?>
<help xmlns="http://www.exlibris.com/Voyager/patron" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    <helpText> This web service allows you to update individual patron records.
The patron record should be in the format compatible with the Ex Libris Voyager patron
import/export XML schema (see http://www.exlibrisgroup.org/display/ElCommons) (login required),
and should be attached to the URL.
See the documentation for more information about using the patron import/export schema

Possible Error Codes

Success or error is displayed in the

<pat:info>
<pat:reply>
<pat:reply-text>OK</pat:reply-text>
<pat:reply-code>00</pat:reply-code>
</pat:reply>
</pat:info>

The reply text may have the success (OK) or error text.
The reply code may have the success (00) or error code

The error codes and texts are:

CodeTextNotes
00OKNo error.
01Barcode and patron group not unique : record updated, second instance skipped
02Incoming address overlaps dates with an existing address; address not processed
03Existing permanent address is protected and therefore cannot be replaced; address not processed.
04Incoming address has an begin date which precedes the end date; address not processed
11Patron record does not conform to XSD. Record not processed.
12Action = Insert, but match found in database. Record not processed.
13Action = Update, but match not found in database. Record not processed.
14multiple match on identifier <xxx> found. Record not processed.
15libraryLocationCode <xxx> not present in database. Record not processed.
16patronStat code <xxx> not present in database. Record not processed.
17patronGroup code <xxx> not present in database. Record not processed.
18patronNote/type code <xxx> not present in database. Record not processed.
19Barcode may not be blank. Record not processed.
20If matchId/idType = ‘VoyagerID’ then the matchId/idNumber value must be a number. Record not processed.
21Name type <xxx> not found. Record not processed.
22System errorUnexplained error
23Institution id already assigned to another patron. Record not processed.