XML Patron Data Requirements
This document presupposes a fundamental knowledge of XML. Because library local systems and practices vary widely, this
document is best used as a high-level overview.
This document contains the requirements for the XML patron data file. Use it when working with the file below:
1. The patron persona XSD file:
https://www.oclc.org/content/dam/community/implementation/data_migration/IDMPersonas-2.2.xsd
Symbols and HTML code
XML files must contain valid HTML code. These symbols, if present in the patron data, must be represented as HTML code
(entity references), as below:
Symbol
HTML code (entity references)
&
&
<
&lt;
>
“
&gt;
&quot;
Filename rules
1. Filenames cannot contain spaces or special characters (such as @, ?, *, #, !, &, %, $, ^, etc.)
2. XML files must have the XML file extension.
Example: OCLCsymbolpatrons.xml
Send patron data
1. Send your patron data files to your FTP/sFTP account. For more information, see: WorldShare FTP.
2. If you require ongoing patron loads after your initial file has been loaded, send only new or changed accounts, if possible
(do not resend your entire database).
3. Patron directories differ, depending on whether data has been approved for automated loads:
Directory
Use for
/wms/test/in/patron
Data being evaluated for automated data loads
/wms/in/patron
Data approved for automated data loads
Ongoing patron load updates

If an update record does not include a field, but there was data in a previous update, the original data will be
maintained.

If new data is included in an update record, all will be replaced with the new information.

Note that 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 is maintained.
Questions
If you have questions, please contact your OCLC Implementation Manager or OCLC Support (contact your local support
desk).
1
complexType
Attribute /
Element
Type
Required /
Repeatable for
WMS libraries
OCLCPersonas
persona
Persona
Required
Not repeatable
Required /
Description
Repeatable for
Tipasa*
Libraries
Required
1) Top level element of XSD structure; does not contain
Not repeatable
data of its own; contains all other elements
Persona
correlationInfo
Optional
Repeatable
Optional
Repeatable
Required if using
a non-OCLC
authentication
system.
Required if
using
a non-OCLC
authentication
system.
Optional
Not repeatable
Optional
1)
Not repeatable
2)
oclcUserName
CorrelationInfo
string
1)
2)
3)
4)
oclcExpirationDate dateTime
Optional
Not repeatable
Optional
1)
Not repeatable
2)
3)
Character
Limit
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 assign the user.
Examples of external systems: PeopleSoft, Banner,
LDAP, Shibboleth, CAS, etc.
This is the user's login name for use only in OCLCmanaged authentication.
Depending on your institution’s configuration, barcode
and User Name may be linked.
Ignored if authentication is performed by the institution
or a third party (in which case OCLC does not store
login credentials).
Must be unique.
50
The date on which the access to certain OCLCprovided services expires; the user will no longer be
authenticated or permitted to use services such as
circulation or ILL after this date.
Use this format date and time:
YYYY-MM-DDThh:mm:ss
2016-12-31T17:45:59
If no date is provided, the date the record was added
plus five years will be the default.
nameInfo
NameInfo
Required
Not repeatable
Required
1)
Not repeatable
Top-level element for all name fields. Does not contain
data of its own.
nickname
string
Optional
Not repeatable
Optional
1)
Not repeatable
2)
Alternate name, does not include salutation or epithets 50
like PhD.
Does not display in patron record in WorldShare Admin
or Circulation modules but is indexed for searching.
2
complexType
Persona
Attribute /
Element
Type
Required /
Repeatable for
WMS libraries
dateOfBirth
Date
Optional
Not repeatable
Required /
Description
Repeatable for
Tipasa*
Libraries
Optional
1) Date of birth in year-month-day format:
Not repeatable
YYYY-MM-DD
gender
string
Optional
Not repeatable
1)
Optional
Not repeatable
2)
If present, must contain one of these capitalized
values:
FEMALE
MALE
UNKNOWN
Default value is UNKNOWN if left blank.
wmsCircPatronInfo WmsCircPatronIn Required
fo
Not repeatable
Not applicable
1)
2)
WMS functionality only.
WMS Circulation specific information about patrons.
wsILLInfo
WsILLInfo
Not applicable
Required
Not repeatable
1)
2)
Tipasa functionality only.
ILL specific information about patrons.
contactInfo
ContactInfo
Required
Repeatable
Required
Repeatable
1)
2)
An address, telephone number, or email address.
At least one piece of contact information, postal
address, email or phone number is required.
Optional
Repeatable
1)
2)
Tipasa functionality only.
One or more destinations (e.g. email address,
telephone number for voice mail, mobile number for
SMS text messages, etc.) to which notifications from
various OCLC services are desired to be delivered.
Note that the preference service is used to specify
which delivery notification service to use for the
various different OCLC notifications.
If notificationDeliveryDestination is used, the two subelements deliveryService and destination are
required.
notificationDeliveryDe NotificationDeliver Not applicable
stination
yDestination
3)
4)
Character
Limit
3
complexType
Persona
Attribute /
Element
Type
note
Note
additionalInfo
KeyValuePair
photoURL
anyURI
Required /
Repeatable for
WMS libraries
Character
Limit
Optional
Repeatable
Optional
Repeatable
Required /
Description
Repeatable for
Tipasa*
Libraries
Optional
1) A note about the patron.
Repeatable
Optional
1) Optional data fields that could be used to store many
Repeatable
kinds of custom data and can differ by institution.
Optional
Not repeatable
Optional
Not repeatable
8,192
1)
2)
3)
4)
institutionId
numeric
Required
Not repeatable
Required
Not repeatable
1)
2)
(Attribute)
3)
NameInfo
prefix
string
givenName
string
middleName
string
familyName
string
Optional
Not repeatable
Required
Not repeatable
Optional
Not repeatable
Required
Not repeatable
givenName or
familyName is
required
givenName or
familyName is
required
Optional
Not repeatable
Required
Not repeatable
Optional
Not repeatable
Required
Not repeatable
givenName or
familyName is
required
givenName or
familyName is
required
A URL which displays or links to the user's photo.
The photo is displayed in the patron’s profile in the
WorldShare Admin and Circulation modules.
OCLC does not currently store photos.
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.
The institutionId (aka WorldCat Registry ID) is a
unique identifier of a library
Groups are supported by allowing libraries to submit a
file in which patron records are associated with
different institutionIds.
The institutionId is provided by your OCLC
Implementation Manager or can be found using an
institution symbol search (identifiers) at :
http://www.worldcat.org/registry/Institutions
1)
Prefix or title, such as Ms, Dr, Sir.
10
1)
2)
First name of patron.
givenName or familyName is required.
50
1)
Middle name of patron.
100
1)
2)
Last name of patron.
givenName or familyName is required.
50
4
complexType
NameInfo
WMSCircPatronInfo
Attribute /
Element
Type
suffix
string
canSelfEdit
boolean
barcode
string
Required /
Repeatable for
WMS libraries
Optional
Not repeatable
Optional
Not repeatable
Required
Not repeatable
Required /
Description
Character
Repeatable for
Limit
Tipasa*
Libraries
Optional
1) A generation indicator such as Jr, III, and/or an epithet 10
such as PhD, FRS.
Not repeatable
Optional
1) Indicates that a user may manage the name
themselves for future functionality.
Not repeatable
2) Supported values are (lowercase required):
true
false
3) Default value is false.
Not applicable
1)
2)
(barcode can be 3)
4)
sent as illId)
5)
6)
pin
string
Optional
Not repeatable
Not applicable
1)
2)
3)
4)
borrowerCategory string
Required
Not repeatable
Not applicable
(illPatronType
can be used)
1)
2)
3)
4)
5)
circRegistrationDate dateTime
Optional
Not repeatable
Not applicable
1)
2)
3)
4)
WMS functionality only.
20
A unique identifier per patron.
Can contain letters or numbers.
Spaces within the barcode string are acceptable, but
leading and trailing spaces are problematic.
Matching on patron updates starts with idAtSource
and sourceSystem (if supplied) and then matches on
barcode.
For more information, see Matching Rules for Patron
Data
Future functionality for WMS libraries.
Personal Identification Number.
Used to authorize operations that another user is
not authorized to do (overrides). Not a user’s WMS
password.
May be used with the SIP/NCIP service.
WMS functionality only.
30
Category of borrower (patron type) provided by the
library.
Used to set circulation policies.
New values can be provided in patron update files and
also added in OCLC Service Configuration.
Examples: Student, Adult, Faculty, Staff, etc.
WMS functionality only
Date the patron account was created.
Use this format for date:
YYYY-MM-DD
If no date is provided, the date the record was added
will be added by default.
5
complexType
WMSCircPatronInfo
Attribute /
Element
Description
Required
Not repeatable
Required /
Repeatable for
Tipasa*
Libraries
Not applicable 1)
2)
Optional
Not repeatable
Not applicable 1)
2)
WMS functionality only.
Blocked users have their library privileges suspended.
Patron is not allowed to borrow items.
Two values: true/false
Type
Required /
Repeatable for
WMS
homeBranch
string
isCircBlocked
boolean
WMS functionality only.
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) This value can be found in Service Config > My
WorldCat.org > Holdings Code Translation Table.
3)
isCollectionExempt
boolean
Optional
Not repeatable
Not applicable 1)
2)
3)
isFineExempt
boolean
Optional
Not repeatable
Not applicable 1)
2)
3)
isVerified
boolean
Optional
Not repeatable
Not applicable 1)
2)
3)
ContactInfo
Note:
At least one piece of
contact information,
postalAddress, email
or phone number is
required.
WMS functionality only.
Patron fines are not moved to collections (patron is
exempt from having account sent to collection
agency).
Two values: true/false
Future WMS functionality.
Fines are not charged to patron’s account (patron is
exempt from accruing fines).
Two values: true/false
WMS functionality only.
Indicates whether patron's identity established via
acceptable ID (driver's license, etc.)
Two values: true/false
storeCheckoutHistory
boolean
Choice:
postal address
PostalAddres Optional
s
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
1)
See Phone for description.
Optional
Not repeatable
Optional
Repeatable
Character
Limit
Not applicable 1)
2)
3)
Future WMS functionality.
Stores checkout history if flag set.
Two values: true/false
6
complexType
ContactInfo
PostalAddress
Note:
At least one piece of
contact information,
postalAddress, email
or phone number is
required.
Attribute /
Element
Type
Required /
Repeatable for
WMS
Required /
Description
Character
Repeatable for
Limit
Tipasa*
Libraries
Optional
1) A label indicating the nature or intended use of this
Not repeatable
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.
label
string
Optional
Not repeatable
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
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)
2)
State or province.
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)
2)
Country.
Do not abbreviate. Use United States, not United
States of America or USA
120
isPrimary
boolean
Optional
Not repeatable
Optional
Not repeatable
1)
2)
Only one postal address can be primary.
If present, must contain one of these values to
indicate whether an address is primary:
true
false
7
complexType
Attribute /
Element
Type
Required /
Repeatable for
WMS
PostalAddress
isPermanent
boolean
Optional
Not repeatable
validFrom
dateTime
Optional
Not repeatable
Optional
1)
Not repeatable 2)
Future functionality.
Date from which the Physical Location is valid.
validTo
dateTime
Optional
Not repeatable
Optional
1)
Not repeatable 2)
Future functionality.
Date to which the Physical Location is valid. A range of
dates for a location is needed because many students
are in temporary accommodation, such as halls of
residence. The date range avoids sending notices there
after term ends.
Note:
At least one piece of
contact information,
postalAddress, email
or phone number is
required.
EmailAddress
Required /
Description
Repeatable
for Tipasa*
Libraries
Optional
1) A user can have only one permanent address. For
Not repeatable
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
emailAddress
string
Optional
Not repeatable
Optional
1)
Not repeatable
2)
An email address is required for the patron access via
OCLC Authentication.
For patrons without email addresses, it is best to
provide a default value (can use any value).
isPrimary
boolean
Optional
Not repeatable
Optional
1)
Not repeatable 2)
Only one email address can be primary.
If present, must contain one of these values to indicate
whether the email address is primary:
true
false
Note:
At least one piece of
contact information,
postalAddress, email
or phone number is
required.
Character
Limit
254
8
complexType
Phone
Note:
At least one piece of
contact information,
postalAddress, email
or phone number is
required.
CorrelationInfo
Attribute /
Element
Type
Required /
Repeatable for
WMS
number
string
Optional
Not repeatable
Required /
Description
Repeatable
for Tipasa*
Libraries
Optional
1) Telephone number
Not repeatable 2) Mobile telephone number
isPrimary
boolean
Optional
Not repeatable
Optional
1)
Not repeatable 2)
sourceSystem
string
idAtSource
Note
text
string
string
Optional
Optional
Required if using a
non-OCLC
authentication
system.
2)
Required if
using a
3)
non-OCLC
authentication 4)
system.
Optional
Optional
Required if using a
non-OCLC
authentication
system.
Required if
2)
using a
non-OCLC
authentication 3)
4)
system.
Optional
Not repeatable
Optional
1)
Not repeatable 2)
1)
1)
3)
KeyValuePair
Character
Limit
50
Only one phone number can be primary.
If present, must contain one of these values to indicate
whether the phone number is primary:
true
false
URN identifying the external authentication system (e.g. 255
urn:mace:oclc:idm:testlibrary.ldap).
Supplied by OCLC (e.g. LDAP) or institution (e.g.
Shibboleth).
If present, idAtSource must also be present.
For more information, see Matching Rules for Patron
Data
ID of a user in the external system (e.g. ILS,
PeopleSoft, Banner, CAS) from which the data is being
migrated.
If your system is not case sensitive, these must be
unique and in lowercase.
If present, sourceSystem must also be present.
For more information, see Matching Rules for Patron
Data
50
Body of the note.
If ongoing data loads contain new notes that exactly
match existing notes, the new notes are ignored.
If ongoing data loads contain new notes that do not
exactly match existing notes, the new notes are added.
255
businessContext
string
Optional
Not repeatable
Optional
1)
Not repeatable
If present use value:
Circulation_Info
key
string
Optional
Not repeatable
Optional
1) Use for up to four pieces of custom data, must contain
Not repeatable
one of these values:
customdata1
customdata2
customdata3
customdata4
9
complexType
KeyValuePair
Attribute /
Element
Type
Required /
Repeatable for
WMS
value
string
Optional
Not repeatable
deliveryService
string
Not applicable
Optional
1)
Not repeatable 2)
Tipasa functionality only.
If present, must contain one of these values:
Email
SMS
string
Not applicable
Optional
1)
Not repeatable 2)
3)
Tipasa functionality only.
4,096
Patron’s email address.
Full international format including country code is
required e.g. "+1 232-456-7890" for a U.S. number or
"+44 20 4961 5678" for a UK number.
Causes errors if the + is missing.
NotificationDeliveryDestin
ation
Note:
destination
If
notificationDeliveryDesti
nation is used, the two
sub-elements
deliveryService and
destination are required.
WsILLInfo
Required /
Description
Character
Repeatable
Limit
for Tipasa*
Libraries
Optional
1) Can match predefined values in OCLC Service
8,192
Configuration or be free text (not entered in OCLC
Not repeatable
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 Circulation modules.
illId
4)
string
Not applicable
Required
1)
Not repeatable 2)
3)
4)
Tipasa functionality only.
A unique identifier for the user in the Tipasa system.
It may, but need not be, the user's library barcode.
For more information, see Matching Rules for Patron
Data
254
10
complexType
WsILLInfo
Attribute /
Element
Type
Required /
Repeatable for
WMS
Required /
Description
Character
Repeatable
Limit
for Tipasa*
Libraries
Optional
1) Tipasa functionality only.
Not repeatable 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 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.
illApprovalStatus
string
Not applicable
illPatronType
string
Not applicable
Optional
1)
Not repeatable 2)
3)
Tipasa functionality only.
50
Does not connect with OCLC Service Configuration
Reserved for future functionality – libraries will be able
to run reports based on this value.
illPickupLocation
string
Not applicable
Optional
1)
Not repeatable 2)
3)
Tipasa functionality only.
Does not connect with OCLC Service Configuration
This value does not pre-populate the patron request
form with a desired pickup location. It is reserved for
future functionality.
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.
4)
1000
* Tipasa is a new, cloud-based ILL management system that is available only in the U.S. at this time.
11