Patron file format specifications
Patron file format specifications
Overview
To be imported successfully into Destiny, a patron file must be in the correct format. This document contains detailed
information about the file, the acceptable format, and the record and field contents.
File sources
Destiny accepts an exported patron file from any of the following Follett applications:
l
Destiny (all versions)
l
TextLink v4.x, v5.x
l
Circulation Plus v4.x, v5.x, v6.x
If the patron information you have is from another vendor or a school administration system, you can convert it with
Follett’s Patron Conversion Utility.
If you prefer to create your own file or edit a text file using a text editor, this document explains the formatting details
for a patron import file. You can create the file with any text editor, such as Notepad or Simple Text. Do not use
Microsoft® Word or Apple TextEdit. Hidden characters created by these programs can cause the upload to fail.
Note: This information is provided to help you or your technical personnel prepare a patron file for import into Destiny.
If you don't have experience creating or editing comma-delimited text files, you may want to seek additional assistance.
File requirements
The import file format is flat ASCII text, comma-delimited. It consists of a header line and multiple patron record lines.
It must meet the following requirements:
l
The file must have one header record.
l
Each patron record takes up one line of the file.
l
Each record must end with a hard return (CR/LF).
l
String (text) fields are surrounded by quotes (e.g., "Smith").
l
Numbers, including dates, are the actual numeric value.
l
Each field is separated from the one after it by a comma.
Before you begin
Import Patrons performs several checks when importing your file. To ensure a successful import, be aware of the
following actions that Import Patrons takes:
l
It checks the maximum length of each field.
Any field larger than the maximum length is truncated when imported.
l
It deletes any trailing spaces in string fields. It does not delete any leading spaces.
l
It applies standard month/day checking. Destiny stores all date fields as numbers in the yyyymmdd format.
Years must be between 1900 and 2037.
l
It generates a line in the job summary for any record that is invalid, listing the patron name (if possible) and a
brief error message.
Patron file format specifications
Header portion of the file
The first line in the import file must be a header line. It is a file identifier. Although it is not required that the
header fields contain values, each field, listed the following table, must exist in the header.
The one exception is the third field, Patron file format version.
l
If your patron records contain 31 fields, this field must contain 4.00.
l
If your patron records contain 36 fields, this field must contain 5.00.
Do not enter a higher number. Do not enter the version number of the Follett application that you are currently
running.
Field
Format
Maximum length
Example
School name
String
30
"Anytown
Elementary"
Program name
String
20
"Patron
Maintenance"
Patron file format version String
10
"4.00"
Date created
Num, yyyymmdd
8 (exactly)
Patron count
Num
4 (exactly, zero-padded)
0354
Disk number *
Num
2 (exactly, zero-padded)
01
Final disk? *
String
1
"Y"
20070914
* Import Patrons does not accept a single file that spans multiple floppy disks.
If you are using floppy disks, make sure you create a patron file that fits on a single disk.
Examples
The following example of a file header indicates that patrons from Anytown Elementary were exported by Patron
Maintenance module version 4.00 on Sept. 14, 2007 (20070914). There are 354 (0354) patron records. This is the
first disk (01) in the series and is also the last disk ("Y") in the series.
"Anytown Elementary","Patron Maintenance","4.00",20070914,0354,01,"Y"
The smallest valid header would be:
"","","4.00",,,,""
Page 2 of 5
© Copyright 2010 Follett Software Company
Rev 16 05-11-A
Patron file format specifications
Patron record portion of the file
The remaining lines in the import file are patron records. For a successful import, make sure to conform to the
following requirements:
l
Each record must contain either 31 or 36 fields, whether or not they contain data.
l
String fields must be surrounded by quotation marks.
l
All fields are separated (delimited) by commas.
l
Each record must end with a hard return; there must not be any trailing space after the last field.
l
The Barcode and/or Alternate ID (District ID) field(s) must contain data. This requirement depends on your
preference. If you are exporting from TextLink or Circulation Plus, refer to your System Setup | Patron
Maintenance | Patron Defaults for your Required Patron Field(s).
l
Barcodes, of any symbology, may not be longer than 14 characters.
l
If your Destiny Administrator requires it, the District ID must contain unique data.
l
The Last Name field must contain data.
l
If your records don't have Patron Types, Destiny assigns the default Patron Type to the patrons.
You can designate the default Patron Type on the Patron Types tab of Library Policies, Textbook Policies,
or Asset Policies, in the Back Office. For Media Manager only, the default Patron Type is "Faculty".
The following table contains the specific information for each field:
Field name
Format
Maximum length
Example
1
Barcode
String
14
"P 528452"
2
Alternate ID
District ID 2
String
40
"241661234"
3
Last name
String
42
"Sellers"
4
First name
String
42
"Patty"
5
Middle name
String
42
"Jo"
6
Card expiration date
Num yyyymmdd
8 (exactly)
20080630
7
Graduation year
Num yyyy
4 (exactly)
2008
8
Birth date
Num yyyymmdd
8 (exactly)
19980214
9
Gender 3
String
1
"F"
10 Patron Type 4
String
30
"Student"
11 Patron Status 5
String
1
"A"
12
Location 1
User Defined 1
String
15
"Johnson"
13
Location 2
User Defined 2
String
15
"Gymnasium"
14
User field 1
User Defined 3
String
15
"4th Period"
15
User field 2
User Defined 4
String
15
"ESL"
16
Address 1 Line 1
Primary Address Line 1
String
32
"19 Ridge St"
Page 3 of 5
© Copyright 2010 Follett Software Company
Rev 16 05-11-A
Patron file format specifications
17
Address 1 Line 2
Primary Address Line 2
String
32
"Route 3"
18
Address 1 Line 3 City
Primary Address City
String
32
"Sycamore"
19
Address 1 Line 4 State/Province
Primary Address State/Province
String
32
"Illinois"
20
Address 1 Zip/Postal Code
Primary Address Postal Code
String
20
"60987"
21
Address 1 Email
Email 1
String
32
"[email protected]"
22
Address 1 Phone 1
Primary Address Phone 1
String
28
"815-828-9598"
23
Address 1 Phone 2
Primary Address Phone 2
String
28
"(895) 982-8518"
24
Address 2 Line 1
Secondary Address Line 1
String
32
"1037 Tame Rd"
25
Address 2 Line 2
Secondary Address Line 2
String
32
"P O Box 1972"
26
Address 2 Line 3 / City
Secondary Address City
String
32
"McHenry"
27
Address 2 Line 4 State/Province
String
Secondary Address State/Province
32
"Wisconsin"
28
Address 2 Zip/Postal Code
Secondary Address Postal Code
String
20
"70998"
29
Address 2 Email
Email 2
String
32
"[email protected]"
30
Address 2 Phone 1
Secondary Address Phone 1
String
28
"(724) 737-8487"
31
Address 2 Phone 2
Secondary Address Phone 2
String
28
"724-887-3754"
32
Is teaching?
Currently Teaching 6
String
1
"N"
33
none
Grade Level
String
30
"Fourth"
34
none
Homeroom
String
30
"Politsch"
35
none
Nickname
String
30
"PJ"
36
none
Acceptable Use Policy on File? 7
String
1
"N"
Page 4 of 5
© Copyright 2010 Follett Software Company
Rev 16 05-11-A
Patron file format specifications
Footnotes:
1 First field name is that used in TextLink and Circulation Plus.
If different, Destiny's field name is listed second.
2Import Patrons allows you to move either the incoming Barcode or Alternate ID into the Barcode field.
You can then move the other number into the User Defined 5 or District ID field, or discard it.
Your Destiny Administrator, however, may require that all incoming patron records contain unique District IDs.
3 Gender can be "M", "F", or "U" — Male, Female, Unknown.
Any other character or a blank field is set to "U".
4 Patron Type can be any string up to 30 characters. Import Patrons sets an "S" to Student and an "F" to Faculty.
Any other characters cause Import Patrons to create a new Patron Type if it does not exist in Destiny.
If Import Patrons cannot create the Patron Type, or if the field is blank, it assigns the default Patron Type to the
patron.
5 Patron Status can be "A", "I", or "R" — Active, Inactive, Restricted.
Destiny sets a blank field or a field containing any other character to Active.
6 This field exists in TextLink and Destiny Textbook Manager. It indicates whether the patron is a teacher. If the
import file is from either TextLink or Destiny Textbook Manager and the field contains a "Y" or "y", Import Patrons
selects the "Currently Teaching" check box in the patron record in Destiny.
7 This field exists only in Destiny. It indicates whether the patron has an AUP on file.
If the field contains a "Y" or "y", Import Patrons selects the "Acceptable Use Policy on File?" check box in the
patron record in Destiny.
Examples
The patron in the following example is Patty Sellers, whose record data is the same as that shown in the above
table. In the export file, this record would appear as a single line terminated by a hard return.
31-field record with data in all fields
"P52","241661234","Sellers","Patty","Jo",20050630,2005,19880214,"F","S","A","Johnson","Gymnasium","4th Period","ESL","19 Ridge
St","Route 3","Sycamore","Illinois","60987","[email protected]","815-828-9598","(895) 982-8518","1037 Tame
Rd","P O Box 1972","McHenry","Wisconsin","70998",
"[email protected]","(724) 737-8487","724-887-3754"¶
31-field record with minimal data
"P52","","Sellers","","",,,,"","","","","","","","","","","","","","",
"","","","","","","","",""¶
36-field record with data in all fields
"P52","241661234","Sellers","Patty","Jo",20050630,2005,19880214,"F","S","A","Johnson","Gymnasium","4th Period","ESL","19 Ridge
St","Route 3","Sycamore","Illinois","60987","[email protected]","815-828-9598","(895) 982-8518","1037 Tame
Rd","P O Box 1972","McHenry","Wisconsin","70998",
"[email protected]","(724) 737-8487","724-887-3754","N","Fourth","Politsch",
"PJ","N"¶
Note: The paragraph symbol (¶) in the examples is being used to show the hard return (CR/LF) at the end of the
record. Normally, it would not be visible.
Page 5 of 5
© Copyright 2010 Follett Software Company
Rev 16 05-11-A