Skip to main content
OCLC Support

Tab-delimited patron data loading

  1. Last updated
  2. Save as PDF
This documentation explains the requirements for tab-delimited patron data files, the rules and requirements for sending patron data in tab-delimited format and provides a template for your patron data file.
File Description
Tab-delimited patron data template (Microsoft Excel) Contains 46 columns. Save as a tab-delimited text file (an Excel file cannot be used to send data).

Columns

Use the following criteria to create columns for your data:

  • The text file must contain all 46 tab-delimited columns in the order listed in the table below.
  • The first line of the text file is the header and must contain column names separated by tabs.
  • Column header names are not case sensitive, but must be spelled correctly.
  • Each line in the tab-delimited file must contain 45 tab characters, which function as column separators.
  • All values in columns are strings (text string, numeric string, etc.).
  • If you have no data to put in a column, leave it empty.

Filename

File naming must follow specific rules:

  • Filenames can contain letters, numbers, periods and underscores.
  • Filenames cannot contain spaces or special characters.
  • If you are using a non-Windows machine, save the file as a Windows-formatted text file.

Example: OCLCsymbolpatrons.txt

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. This does not apply to the sourceSystem/idAtSource fields. If those fields are changed, a new entry will be added in the account accordion.
  • 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 Tab-delimited 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 fields

Columns 1-17

Column
number

 Column name Required for
WorldShare Circulation Libraries		 Required for
Tipasa Libraries		 Description Character limit
1 prefix Optional Optional
  1. Prefix or title, such as Ms, Dr, Sir.
 254
2 givenName

Required

givenName or familyName is required

Required

givenName or familyName is required
  1. First name of patron.
  2. givenName or familyName is required.
 50
3 middleName Optional Optional
  1. Middle name of patron.
 100
4 familyName

Required

givenName or familyName is required

Required

givenName or familyName is required
  1. Last name of patron.
  2. givenName or familyName is required.
 50
5 suffix Optional Optional
  1. A generation indicator such as Jr, III, and/or an epithet such as PhD, FRS.
 254
6 nickname Optional Optional
  1. Alternate name, does not include salutation or epithets like PhD.
  2. Does not display in patron record but is indexed for searching.
 50
7 canSelfEdit Optional Optional
  1. Indicates that a user may manage the name themselves for future functionality.
  2. Permits values of:
    True
    False
  3. Default value is false.
  
8 dateOfBirth Optional Optional
  1. Date of birth in year-month-day format: YYYY-MM-DD
  
9 gender Optional Optional
  1. If present, must contain one of these values:
    Female or F
    Male or M
    Unknown or U
     

     Note: All values are case insensitive.

  2. Default value is Unknown if left blank.
  
10 institutionId Required Required
  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 institutionIds.
  3. The institutionId is provided by your OCLC Implementation Manager or can be found using an institution symbol search (identifiers).
  
11 barcode Required 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
12 idAtSource

Optional

Required if using a non-OCLC authentication system.

Optional

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
13 sourceSystem

Optional

Required if using a non-OCLC authentication system.

Optional

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
14 borrowerCategory Required Not applicable (illPatronType can be used)
  1. WorldShare Circulation functionality only.
  2. Category of borrower (patron type) provided 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
15 circRegistrationDate Optional Not applicable

  1. WMS functionality only.

  2. Date the patron account was created.

  3. Use this format for date:
    YYYY-MM-DD 2016-12-31

  4. If no date is provided, the date the record was added will be added by default.

  

16

 oclcExpirationDate Optional Optional
  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.
  
17 homeBranch Required 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. This value can be found in OCLC Service Configuration > WorldCat Discovery and WorldCat Local > Holdings Code Translation Table
  

 

Columns 18-35

Column
number

 Column name Required for
WorldShare Circulation Libraries		 Required for
Tipasa Libraries		 Description Character limit
At least one piece of contact information, postalAddress, email or phone number is required.
18 primaryStreetAddressLine1 Optional Optional
  1. Primary street address line 1.
 120
19 primaryStreetAddressLine2 Optional Optional
  1. Primary street address line 2, if applicable.
 120
20 primaryCityOrLocality Optional Optional
  1. Primary city or location.
 50
21 primaryStateOrProvince Optional Optional
  1. Primary state or province.
  2. For US states, use the United States Post Office abbreviations.
 120
22 primaryPostalCode Optional Optional
  1. Primary US zip code or non-US postal code.
 20
23 primaryCountry Optional Optional
  1. Primary country.
  2. Do not abbreviate. Use United States, not United States of America or USA.
 120
24 primaryPhone Optional Optional
  1. Primary telephone number.
  2. Can use any format.
 50
25 secondaryStreetAddressLine1 Optional Optional
  1. Secondary street address line 1.
 120
26 secondaryStreetAddressLine2 Optional Optional
  1. Secondary street address line 2.
 120
27 secondaryCityOrLocality Optional Optional
  1. Secondary city or location.
 50
28 secondaryStateOrProvince Optional Optional
  1. Secondary state or province.
  2. For US states, use the United States Post Office abbreviations.
 120
29 secondaryPostalCode Optional Optional
  1. Secondary US zip code or non-US postal code.
 20
30 secondaryCountry Optional Optional
  1. Secondary country.
  2. Do not abbreviate. Use United States, not United States of America or USA.
 120
31 secondaryPhone Optional Optional
  1. Secondary telephone number.
 50
32 emailAddress Optional Optional
  1. An email address is required for patron access via OCLC Authentication.
  2. For patrons without email addresses, it is best to provide a default value (can use any value).
 254
33 mobilePhone Optional Optional
  1. Mobile telephone number.
 50
34 notificationEmail Not applicable Optional
  1. Tipasa functionality only.
 4,096
35 notificationTextPhone Not applicable

Optional

 Note: If a mobile number is present in this field and does not validate, the patron load will be rejected.
  1. Tipasa functionality only.
  2. 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,096

 

Columns 36-46

Column
number

 Column name Required for
WorldShare Circulation Libraries		 Required for
Tipasa Libraries		 Description Character limit
36 patronNotes Optional Optional
  1. Notes from ongoing data loads that are identical to previously-loaded notes are ignored.
  2. Notes from ongoing data loads that are not identical to previously-loaded notes are added.
 255
37 photoURL Optional Optional
  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
38 customdata1 Optional Optional
  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 Circulation modules.
 8,192
39 customdata2 Optional Optional
40 customdata3 Optional Optional
41 customdata4 Optional Optional
42 username Optional Optional
  1. This is the user's login name for the use only in OCLC-maintained authentication.
  2. This should only be provided if the institution is not using barcode as User Name.
  3. Depending on your institution's configuration, barcode and User Name may be linked.
  4. Ignored if authentication is performed by the institution or a third party (in which case OCLC does not store login credentials).
  5. Must be unique.
 50
43 illId Not applicable Required
  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
44 illApprovalStatus Not applicable Optional
  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 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.
  
45 illPatronType Not applicable Optional
  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
46 illPickupLocation Not applicable Optional
  1. This value will automatically populate in the Pickup Location field on Patron Request Workforms.
  2. 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.
 1,000

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.