XML patron data loading

This documentation provides the requirements for XML patron data files, including detailed information about the XSD format used by OCLC to load patron data.

 Note: This information presupposes a fundamental knowledge of XML. Because library local systems and practices vary widely, this document is best used as a high-level overview.

File Description
Patron persona XSD Template for creating XML patron data file.

Symbols and HTML code

XML files must contain valid HTML code. These symbols, if present in the patron data, must be replaced as HTML code (entity references), as below:

Symbol HTML code (entity references)
& &
< &lt;
> &gt;
" &quot;

Filename

File naming must follow specific rules:

  1. Filenames can contain letters, numbers, periods and underscores.
  2. Filenames cannot contain spaces or special characters.
  3. XML files must have the XML file extension.

Example: OCLCsymbolpatrons.xml

Send patron data

Once your data is prepared, send your patron data files via SFTP with your OCLC file exchange account.

Directory Use for
/xfer/wms/test/in/patron

Data being evaluated for automated data loads

 Note: To ensure that your test file is handled appropriately, notify OCLC Support after uploading a file to the test directory and provide an explanation of the analysis required.
/xfer/wms/in/patron Data approved for automated data loads

Ongoing patron load updates

  • If new data is included in an update record, all will be replaced with new information.
  • Name and Postal address information are treated as a group; if there was a full address previously and the update record only includes the country, then the Postal Address will be overwritten with just the country. If nothing new is provided in the update record, then the old address will be maintained.
  • If an update record does not include data for an optional field, but contained data in a previous update, the original data will be maintained.
  • If you want to bulk delete library patron records, see XML patron data bulk delete.
  Fields Action
For WorldShare Circulation, if any of these fields are present > barcode, homeBranch, borrowerCategory, circRegistrationDate > It will be treated as a WorldShare Circulation record and will assume the WorldShare Circulation required fields are present.
For Tipasa, if any of the ILL fields are present > illId, illApprovalStatus, illPatronType, illPickupLocation > It will be treated as an ILL record and assume the ILL required fields are present.
For WorldShare Circulation, if any required WorldShare Circulation fields are missing > givenName OR familyName, institutionId, barcode, borrowerCategory, homeBranch > The record will be ignored.
For Tipasa, if any fields are missing > givenName OR familyName, institutionId, illId, at least one piece of contact information (postal address, phone or email) > The record will be ignored.
If both WorldShare Circulation and Tipasa fields are present >   It will take on requirements for both types of records.

Record elements

OCLCPersonas and Persona

complexType Attribute / Element Type Required / Repeatable for WorldShare Circulation libraries Required / Repeatable for Tipasa Libraries Description Character Limit
OCLCPersonas persona Persona

Required
Not repeatable

Required
Not repeatable
  1. Top level element of XSD structure; does not contain data of its own; contains all other elements
  
Persona correlationInfo CorrelationInfo

Optional
Repeatable

Required if using a non-OCLC authentication system.

Optional
Repeatable

Required if using a non-OCLC authentication system.
  1. Contains the identification of the user at the external system to allow correlation with an IDM user for update if one exists (the idAtSource) and possibly a login username to assist the user.
  2. Examples of external systems: PeopleSoft, Banner, LDAP, Shibboleth, CAS, etc.
  
oclcUserName string Optional
Not repeatable		 Optional
Not repeatable
  1. This is the user's login name for the use only in OCLC-managed authentication.
  2. Depending on your institution's configuration, barcode and User Name may be linked.
  3. Ignored if authentication is performed by the institution or a third party (in which case OCLC does not store login credentials).
  4. Must be unique.
 50
oclcExpirationDate dateTime Optional
Not repeatable		 Optional
Not repeatable
  1. If you are using basic WorldShare  authentication, the date on which the access to certain OCLC-provided services expires; the user will no longer be authenticated or permitted to use services such as circulation or ILL after this date. Note: If you are using third-party authentication (e.g., LDAP/CAS/SAML), this field does not have an effect. 
  2. Use this format date and time:
    YYYY-MM-DDThh:mm:ss
    2016-12-31T00:00:00
  3. If no default expiration period has been configured, no expiration date will appear.
  4. If a default expiration period has been configured, but no date is provided, the expiration date will be set to 60 months (five years) by default.
  5. If a timestamp component is included, it will be discarded as the oclcExpirationDate is stored as a date without a timestamp component.
  6. If present, this date may also be used by WorldShare Circulation to calculate item due date during checkout
  
nameInfo NameInfo Required
Not repeatable		 Required
Not repeatable
  1. Top-level element for all name fields. Does not contain data of its own.
  
nickname string Optional
Not repeatable		 Optional
Not repeatable
  1. Alternate name, does not include salutation or epithets like PhD.
  2. Does not display in patron record in WorldShare Admin or Circulation modules but is indexed for searching.
 50
dateOfBirth Date Optional
Not repeatable		 Optional
Not repeatable
  1. Date of birth in the year-month-day format: YYYY-MM-DD
  
gender string Optional
Not repeatable		 Optional
Not repeatable
  1. If present, must contain one of these values:
    FEMALE
    MALE
    UNKNOWN

     Note:
    • All values are case sensitive
       
  2. Default value is UNKNOWN if left blank.
  
wmsCircPatronInfo WmsCircPatron
Info		 Required
Not repeatable		 Required
Not repeatable
  1. WorldShare Circulation functionality only.
  2. WorldShare Circulation specific information about patrons.
  
wsILLInfo WsILLInfo Not applicable

Required
Not repeatable
  1. Tipasa functionality only.
  2. ILL specific information about patrons.
  
contactInfo ContactInfo

Optional
Repeatable

 Required
Repeatable
  1. An address, telephone number, or email address.
  2. At least one piece of contact information, postal address, email or phone number is required.
  

notification
DeliveryDestination

Notification
DeliveryDestination

 Not applicable

Optional
Repeatable

 Note: If a mobile number is present in this field (when paired with the deliveryService value SMS) does not validate, the patron load will be rejected.
  1. Tipasa functionality only.
  2. One or more destination (e.g. email address, telephone number for voicemail, mobile number for SMS text messages, etc.) to which notifications from various OCLC services are desired to be delivered.
  3. Note that the preference service is used to specify which delivery notification service to use for the different OCLC notifications.
  4. If notificationDeliveryDestination is used, the two sub-elements deliveryService and destination are required.
  
note Note Optional
Repeatable		 Optional
Repeatable
  1. A note about the patron.
  
additionalInfo KeyValuePair Optional
Repeatable		 Optional
Repeatable
  1. Optional data fields that could be used to store many kinds of custom data and can differ by institution.
  
photoURL anyURL Optional
Not repeatable		 Optional
Not repeatable
  1. A URL which displays or links to the user's photo.
  2. The photo is displayed in the patron's profile in the WorldShare Admin and Circulation modules.
  3. OCLC does not currently store photos.
  4. The institution may provide security for the photo by hosting on a secure server. Consult your institution's policies regarding security for linked photo files.
 8,192
institutionId
(Attribute)		 numeric Required
Not repeatable		 Required
Not repeatable
  1. The institutionId (aka WorldCat registry ID) is a unique identifier of a library.
  2. Groups are supported by allowing libraries to submit a file in which patron records are associated with different institutionIds.
  3. The institutionId is provided by your OCLC Implementation Manager or can be found using an institution symbol search (identifiers) in the WorldCat registry.
  

 

NameInfo and WMSCircPatronInfo

complexType Attribute / Element Type Required / Repeatable for WorldShare Circulation libraries Required / Repeatable for Tipasa Libraries Description Character Limit
NameInfo prefix string Optional
Not repeatable		 Optional
Not repeatable
  1. Prefix or title, such as Ms, Dr, Sir.
 254
givenName string

Required
Not repeatable

givenName or familyName is required

Required
Not repeatable

givenName or familyName is required
  1. First name of patron.
  2. givenName or familyName is required.
 50
middleName string Optional
Not repeatable		 Optional
Not repeatable
  1. Middle name of patron.
 100
familyName string

Required
Not repeatable

givenName or familyName is required

Required
Not repeatable

givenName or familyName is required
  1. Last name of patron.
  2. givenName or familyName is required.
 50
suffix string Optional
Not repeatable		 Optional
Not repeatable
  1. A generation indicator such as Jr, III, and/or an epithet such as PhD, FRS.
 254
canSelfEdit boolean Optional
Not repeatable		 Optional
Not repeatable
  1. Indicates that a user may manage the name themselves for future functionality.
  2. Supported values are:
    True
    False
  3. Default value is false.
  
WMSCircPatronInfo barcode string Required
Not repeatable

Not applicable

(barcode can be sent as illID)
  1. WorldShare Circulation functionality only.
  2. A unique identifier per patron.
  3. Can contain letters or numbers.
  4. Spaces within the barcode string are acceptable, but leading and trailing spaces are problematic.
  5. Matching on patron updates starts with idAtSource and sourceSystem (if supplied) and then matches on barcode.
  6. For more information, see Patron data file reference.
 20
pin string Optional
Not repeatable		 Not applicable
  1. Personal Identification Number.
  2. Used to authorize operations that another user is not authorized to do (overrides). Not a user's WorldShare Circulation password.
  3. May be used with the SIP/NCIP service.
  
borrowerCategory string Required
Not repeatable

Not applicable

(illPatronType can be used)
  1. WorldShare Circulation functionality only.
  2. Category or borrower (patron type) proved by the library.
  3. Used to set circulation policies.
  4. New values can be provided in patron update files and also added in OCLC Service Configuration.
  5. Examples: Student, Adult, Faculty, Staff, etc.
 30

circRegistration

Date

 dateTime Optional
Not repeatable		 Not applicable
  1. WorldShare Circulation functionality only.
  2. Date the patron account was created.
  3. Use this format for date:
    YYYY-MM-DD
  4. If no date is provided, the date the record was added will be added by default.
  
homeBranch string Required
Not repeatable		 Not applicable
  1. WorldShare Circulation functionality only.
  2. Branch ID of the patron's home branch, which is a numeric code (not the holding library code).
  3. Branch IDs are provided by your OCLC Implementation Manager.
  4. The value can be found in OCLC Service Configuration > Holdings Code Translation Table.
  
isCircBlocked boolean Optional
Not repeatable		 Not applicable
  1. WorldShare Circulation functionality only.
  2. Blocked users have their library privileges suspended. Patron is not allowed to borrow items.
  3. Two values: true/false
  
isCollectionExempt boolean Optional
Not repeatable		 Not applicable
  1. WorldShare Circulation functionality only.
  2. Patron fines are not moved to collections (patron is exempt from having account sent to collection agency).
  3. Two values: true/false
  
isFineExempt boolean Optional
Not repeatable		 Not applicable
  1. Future WorldShare Circulation functionality.
  2. Fines are not charged to patron's account (patron is exempt from accruing fines).
  3. Two values: true/false.
  
isVerified boolean

Optional
Not repeatable

 Not applicable
  1. WorldShare Circulation functionality only.
  2. Indicates whether patron's identity established via acceptable ID (driver's license, etc.).
  3. Two values: true/false.
  
storeCheckout
History		 boolean Optional
Not repeatable		 Not applicable
  1. Future WorldShare Circulation functionality.
  2. Stores checkout history if flag set.
  3. Two values: true/false.
  

 

ContactInfo and PostalAddress

complexType Attribute / Element Type Required / Repeatable for WorldShare Circulation libraries Required / Repeatable for Tipasa Libraries Description Character Limit

ContactInfo

Note: At least one piece of information, postalAddress, email or phone number is required.

 Choice: postal address PostalAddress Optional
Repeatable		 Optional
Repeatable
  1. See PostalAddress for description.
  
Choice: email EmailAddress Optional
Repeatable		 Optional
Repeatable
  1. See EmailAddress for description.
  
Choice: phone Phone Optional
Repeatable		 Optional
Repeatable
  1. See Phone for description.
  
label string Optional
Not repeatable		 Optional
Not repeatable
  1. A label indicating the nature or intended use of this element.
  2. The administration panel provides elements stored as "home", "work", and "other" for all choices.
  3. The panel also uses "mobile" for phone values.
  4. Data loading of alternative labels is supported, e.g. "fax", and the user interface will display that label.
  
isInvalid boolean Optional
Not repeatable		 Optional
Not repeatable
  1. If present, must contain one of these values to indicate whether email, phone or postal address is valid:
    true
    false
  

PostalAddress 

Note: At least one piece of contact information, postalAddress, email or phone number is required.

 streetAddressLine1 string Optional
Not repeatable		 Optional
Not repeatable
  1. Street address line 1.
 120
streetAddressLine2 string Optional
Not repeatable		 Optional
Not repeatable
  1. Street address line 2 (if applicable).
 120
cityOrLocality string Optional
Not repeatable		 Optional
Not repeatable
  1. City or location.
 50
stateOrProvince string Optional
Not repeatable		 Optional
Not repeatable
  1. State or province.
  2. For US states, use the United States Post Office abbreviations.
 120
postalCode string Optional
Not repeatable		 Optional
Not repeatable
  1. US zip code or non-US postal code.
 20
country string Optional
Not repeatable		 Optional
Not repeatable
  1. Country.
  2. Do not abbreviate. Use United States, not United States of America or USA.
 120
isPrimary boolean Optional
Not repeatable		 Optional
Not repeatable
  1. Only one postal address can be primary.
  2. If present, must contain one of these values to indicate whether an address is primary:
    true
    false
  
isPermanent boolean Optional
Not repeatable		 Optional
Not repeatable
  1. A user can have only one permanent address. For example, a student's permanent home address, as opposed to a campus address.
  2. If present, must contain one of these values to indicate whether an address is permanent:
    true
    false
  
validFrom dateTime Optional
Not repeatable		 Optional
Not repeatable
  1. Future functionality.
  2. Date from which the Physical Location is valid.
  
validTo dateTime Optional
Not repeatable		 Optional
Not repeatable
  1. Future functionality.
  2. Date to which the Physical Location is valid. A range of dates for a location is needed because many students are temporary accommodation, such as halls of residence. The date range avoids sending notices there after term ends.
  

 

EmailAddress, Phone, CorrelationInfo, Note, KeyValuePair, NotificationDeliveryDestination and WSILLInfo

complexType Attribute / Element Type Required / Repeatable for WorldShare Circulation libraries Required / Repeatable for Tipasa Libraries Description Character Limit

EmailAddress

Note: At least one piece of contact information, postalAddress, email or phone number is required.

 emailAddress string Optional
Not repeatable		 Optional
Not repeatable
  1. An email address is required for the patron access via OCLC Authentication.
  2. For patrons without email addresses, it is best to provide a default value (can use any value).
 254
isPrimary boolean Optional
Not repeatable		 Optional
Not repeatable
  1. Only one email address can be primary.
  2. If present, must contain one of these values to indicate whether the email address is primary:
    true
    false
  

Phone

Note: At least one piece of contact information, postalAddress, email or phone number is required.

 number string Optional
Not repeatable		 Optional
Not repeatable
  1. Telephone number.
  2. Mobile telephone number.
 50
isPrimary boolean Optional
Not repeatable		 Optional
Not repeatable
  1. Only one phone number can be primary.
  2. If present, must contain one of these values to indicate whether the phone number is primary:
    true
    false
  
CorrelationInfo sourceSystem string

Optional
Repeatable

Required if using a non-OCLC authentication system.

Optional
Repeatable

Required if using a non-OCLC authentication system.
  1. URN identifying the external authentication system (e.g. urn:mace:oclc:idm:testlibrary.ldap).
  2. Supplied by OCLC (e.g. LDAP) or institution (e.g. Shibboleth).
  3. If present, idAtSource must also be present.
  4. For more information, see Patron data file reference.
 255
idAtSource string

Optional
Repeatable

Required if using a non-OCLC authentication system.

Optional
Repeatable

Required if using a non-OCLC authentication system.
  1. ID of a user in the external system (e.g. ILS, PeopleSoft, Banner, CAS) from which the data is being migrated.
  2. If your system is not case sensitive, these must be unique and in lowercase.
  3. If present, sourceSystem must also be present.
  4. For more information, see Patron data file reference.
 50
Note text string Optional
Not repeatable		 Optional
Not repeatable
  1. Body of the note.
  2. If ongoing data loads contain new notes that exactly match existing notes, the new notes are ignored.
  3. If ongoing data loads contain new notes that do not exactly match existing notes, the new notes are added.
 255
KeyValuePair businessContext string Optional
Not repeatable		 Optional
Not repeatable
  1. If present, use value:
    Circulation_Info
  
key string Optional
Not repeatable		 Optional
Not repeatable
  1. Use for up to four pieces of custom data, must contain one of these values:
    customdata1
    customdata2
    customdata3
    customdata4
  
value string Optional
Not repeatable		 Optional
Not repeatable
  1. Can match predefined values in OCLC Service Configuration or be free text (not entered in OCLC Service Configuration).
  2. Custom data fields from ongoing data loads that are not identical to previously-loaded fields, will replace the previously-loaded value.
  3. Custom data fields from ongoing data loads that are identical to previously-loaded fields are ignored.
  4. Custom data fields left blank in ongoing data loads are ignored and the previous value, if one exists, is maintained.
  5. Custom data fields can be deleted in the WorldShare Admin or WorldShare Circulation modules.
 8,192

NotificationDelivery
Destination

Note: If notificationDelivery
Destination is used, the two sub-elements deliveryService and destination are required.

 deliveryService string Not applicable

Optional
Not repeatable
  1. Tipasa functionality only
  2. If present, must contain one of these values:
    Email
    SMS
  
destination string Not applicable Optional
Not repeatable
  1. Tipasa functionality only.
  2. Patron's email address.
  3. Full international format including country code is required (e.g. +1 232-456-5678 for a US number,  +44 20 4961 5678 for a UK number, or +61 (0) 3 9929 0800 for an Australian number). For more information, see Notation for national and international telephone numbers, e-mail addresses and web addresses.
  4. Causes errors if the + is missing.
 4,096
WsILLInfo illId string Not applicable Required
Not repeatable
  1. Tipasa functionality only.
  2. A unique identifier for the user in the Tipasa system.
  3. It may, but need not be, the user's library barcode. 

     Note: WMS Circ-Tipasa integration only works if the user's illld and barcode value are the same.

  4. For more information, see Patron data file reference.
 254
illApprovalStatus string Not applicable Optional
Not repeatable
  1. Tipasa functionality only.
  2. Allows libraries to pre-approve or block patrons for Tipasa via the patron load or change patrons' approval status for Tipasa.
  3. Supported values are:
    New
    Approved
    Blocked
  4. If the value is left blank on the first load of a patron and there is an illID value in the patron file, the default value will be set to "New".
  5. If value is left blank on updates to existing patrons, the existing value set in the database will be retained.
  
illPatronType string Not applicable Optional
Not repeatable
  1. Tipasa functionality only.
  2. This value will automatically populate in the Status field on Patron Request Workforms if field values are configured there to match values sent in patron data records.
  3. If the patron status field is included on Patron Request Workforms, the data from illPatronType is captured in ILL usage statistics.
 50
illPickupLocation string Not applicable Optional
Not repeatable
  1. Tipasa functionality only.
  2. Does not connect with OCLC Service Configuration.
  3. This value does not pre-populate the patron request form with a desired pickup location. It is reserved for future functionality.
  4. If a library has multiple locations, it is advisable to use the exact same values for illPickupLocation in the patron load as are used in the patron request forms.
 1000

Sample records

Patron data file processing reports

Patron data reports are available in the wms/reports file exchange directory and can be downloaded using an open-source SFTP client or by using SFTP commands.

This table shows the directories for downloading files and reports.

File type SFTP file directory location Note
Patron Exception Report /xfer/wms/reports Lists patron records which fail to load into WMS and also failure reason. The exception report will only run if there is at least one patron record that failed to load into WMS within a patron file.
Patron Summary Report /xfer/wms/reports Runs after a patron file is loaded into WMS and tells how many patrons in the file read, processed, good (loaded), bad (did not load), new, and updated.