4.3.1 Batchloading User Records

{{DISPLAYTITLE:'''Loading USER''' '''records from a file into a MOBIUS''' '''System'''}}

Each library creates a record for each user by keying (manual entry) or loading.  Regardless of the method used for creating a user record, it must have enough information to allow holds, checkouts, renewals, and notices.  For the user record to successfully update via subsequent batch loads, the record must have a match key (External ID Field).  The handout provides information on content of user records and the format for loading records.

There should be only one record in the database for a person at a given institution unless the person is a library staff member using FOLIO. Library staff should have two user accounts, one with user type “patron” and one with user type “staff”.  The staff account will contain the permissions for working in FOLIO, while the patron account will contain the External ID and barcode used for placing holds and circulation.  The staff account doesn’t need a barcode as it won’t be used to place requests.  Only patron records will be loaded in batch. Staff accounts must be created manually in the FOLIO interface. If a person is affiliated with more than one institution, each institution creates a record for that patron.

==Explanation of Fields==

User records contain required fields, optional fields, and can also contain custom fields.

The required fields include: Last Name, First Name, Patron Group, Status, External System ID, Barcode, Username, Email Address, User Type, and Preferred Contact.  As the system writes a record to the FOLIO database for the first time it assigns a system-generated FOLIO Number (UUID number). This number uniquely identifies a record.

Optional fields include: Middle Name, Preferred First Name, Expiration Date, Date Enrolled, Birth Date, Request Preference, Department (if configured), Phone, Mobile Phone, and Address.  

Custom fields are variable, but could include Class Level, General Notes, or Other Barcode (for example).

'''<br />Required''' '''Fields'''

====Last Name====

The surname of the user.

====First Name====

The given name of the user.

====Patron Group====

<span style='color: #222222;background-color: FFFFFF;'>Patron groups are classes of library users. </span>Each library defines their own patron groups.  Batch loading requires a numeric value mapped to the FOLIO patron group.  Please contact the MOBIUS Help Desk to get a list of the values for your patron groups.

====External System ID====

This is an extremely important field for user records in a FOLIO tenant.  Whether a record is loaded or keyed in at a circulation desk, it should have a properly constructed External ID.  The External ID is the matchpoint for external systems such as the library’s SSO system and needs to match the attribute being released by your institution’s identity provider.  It is also the matchpoint for batch loading of user records.  Libraries should contact the MOBIUS Help Desk for information on their External ID format.

====Username====

The username is used by library staff to login to FOLIO to perform library work.  The username is not needed by patrons (they do not use it to request or sign-in) but it is a required field for batch loading user records.  The username needs to be unique across all FOLIO subtenants in the ECS environment.  For this reason, we suggest including a library suffix at the end of the username.

Example:

	''Using Sequential Campus Number''  

12345678CC 		(Columbia College)

====Email====

Email address is required for users to receive circulation notices via email.

Status

Status is either Active or Inactive.  The user’s status is tied to expiration date.  Expired patrons have an inactive status while current patrons are active.  When the expiration date is updated during a batch load, the status is changed to active.

====Barcode====

The barcode number for the user’s library card.  Scanning the barcode is usually the quickest and most precise patron search at the Check Out.  Circulation staff do not have to use the barcode to look up a patron but the barcode is required to check an item out to the patron.  

User Type

The user type should be Patron or Staff.  Patrons are users who may borrow library materials but have no FOLIO permissions assigned to their account.  Staff are users who are employed by the library and have FOLIO permissions assigned to their account for the purpose of performing library work.

Preferred Contact

The preferred contact type is the user’s preferred method of contact (email, mail, or text).  Email is selected by default.

===''Optional'' ''Fields''===

Expiration Date

The incoming record expiration date replaces the one in the database record.  Libraries determine the expiration date needed to prevent loan periods longer than the expiration date in the patron’s record.

====Middle Name====

The middle name of the user.

==== Preferred First Name ====
<span style="color: #222222;background-color: FFFFFF;">The name by which the user prefers to be called. If a preferred first name is provided, it will display in the user record in place of the first name.</span>

====Address1====

This is the primary or local address field.  Enter a dollar sign (“$”) to indicate a line break as shown in the example record. Notice production does not upcase name and address information.  If your library will be sending notices through the mail, you may want to enter all this information in capital letters.

====Address2====

This is a secondary or permanent address.  For students this may be the home address.

====Phone====

This is the primary telephone number.  There is no automatic formatting of this data.  If you want “( )” around the area code and “-“ after the exchange, those characters need to be in the record.

====Mobile Phone====

Secondary telephone number.

====Department====

Department only appears if departments are configured in the FOLIO settings.  

====Note====

This is free text note field.  

==Record Loading==

The MOBIUS Office loads files of user rec<span class="bookmark-start" id="_GoBack"></span>ords into FOLIO for member libraries using a script that imports users via the User Import API. Member libraries post their patron files to the MOBIUS dropbox and the script checks the dropbox, picks up the files, and loads them.  The script runs nightly at 1:00AM.  We are using the file format described below (Text File Image).

This format carries both required and optional data.  The fixed data is grouped in the first line (zero field) of each new record.  Each field in this format is a new line and begins with a single-character field tag.  Each field ends with a carriage return (hexadecimal 0D) and a line feed (hexadecimal 0A).

'''Example Record:'''

		0001ab001shb  --12-31-01<0D0A>

nSmith, Jane<0D0A>

aP.O. Box 177$305B East Hall<0D0A>

t(510) 555-1305<0D0A>

h123 Hill St.$Oakland, CA  95155<0D0A>

p(510)444-1010<0D0A>

dshb<0D0A>

u123456789UU<0D0A>

e123456789<ODOA>

b2117102003159<0D0A>

zjanesmith@campus.edu<0D0A>

====<span style='color: #FF0000;'>Note</span>====

<span style='color: #FF0000;'>Each line ends with a hard return.  Do not put the ASCII characters </span><span style='color: #FF0000;'>“<0D0A>”</span><span style='color: #FF0000;'> in your patron records.  </span><span style='color: #FF0000;'>“<0D0A>”</span><span style='color: #FF0000;'> is the translation of the hexadecimal character for hard return. </span>

==== Fixed Data (Zero Field) ====
Field code ('0')

This is the signal of the beginning of a new record and is always ‘0’. The first line of each record in the file is called the "zero" field because its field tag is “0”. It contains the fixed data for each patron record. 

====Patron Group (000 to 255)====

Each library defines their own patron groups.  Batch loading requires a numeric value mapped to the FOLIO patron group.  Each library (FOLIO subtenant) and MCO will work together to define these numeric values.  Please contact the MOBIUS Help Desk to get a list of the values for your patron groups.

====PCODE1 (1 character)====

No longer applicable.  The field should contain a hyphen (“-“)

====PCODE2 (1 character)====

No longer applicable.  The field should contain a hyphen (“-“)

====PCODE3 (000 to 255)====

No longer applicable.  The field should contain “   “ three blanks.

====Home Library (5 characters)====

No longer applicable.  For MOBIUS libraries this code should be the three-character bibliographic location entered in lower case letters and padded with two blanks. For example: “wdb  “

====Patron Message Code (1 character) ====

No longer applicable. The field should contain a hyphen (“-“)

Patron Block Code (1 character) 

No longer applicable. The field should contain a hyphen (“-“)

====Patron Expiration Date (8 characters, mm-dd-yy)====

The first line of the user record (zero field) is always 24 characters long.  Many of the fixed fields are no longer applicable in FOLIO, but the zero line must still have placeholder values for batch loading.
{| class="wikitable"
|-
| 

'''Field'''
| 

'''Length'''
|-
| 

Field Code
| 

1 Character (Always a ‘0’)
|-
| 

Patron Group
| 

3 Digits (000 to 255) (Check with MOBIUS for codes)
|-
| 

PCODE1
| 

No longer applicable (enter “-“)
|-
| 

PCODE2
| 

No longer applicable (enter “-“)
|-
| 

PCODE3
| 

No longer applicable (enter three blanks “   “)
|-
| 

Home Library
| 

5 Characters, padded with blanks if needed (e.g., “shb  “)
|-
| 

Patron Message Code
| 

No longer applicable (enter “-“)
|-
| 

Patron Block Code
| 

No longer applicable (enter “-“)
|-
| 

Patron Expiration Date
| 

8 Characters (mm-dd-yy)
|}

===''Variable Data''===

Each line following the zero field line contains a single-character field tag in the first column, followed by that field's data.  Each field code used in the incoming user record must be defined in the system.
{| class="wikitable"
|-
| 

'''Code'''
| 

'''Field'''
|-
| 

n
| 

Name
|-
| 

u
| 

Username
|-
| 

b
| 

Barcode
|-
| 

e
| 

External ID
|-
| 

z
| 

Email Address
|-
| 

a
| 

Address1
|-
| 

h
| 

Address2
|-
| 

t
| 

Phone
|-
| 

p
| 

Mobile Phone
|-
| 

d
| 

Department
|-
| 

s
| 

Preferred Name
|-
| 

x
| 

Note
|}

==Transferring Patron Files to the MOBIUS Consortium Office==

MCO uses secure copy (SCP) to receive patron files from the MOBIUS institutions. Please see the document File Transfer Policy & Procedures for instructions on setting up secure copy and connecting to the SCP server.

==== File Naming ====
Patron Files should have descriptive names, including elements identifying the School and the type of patron.

Examples:

===== ''drurypat_students.txt<br />'' ''drurypat_employees.txt<br />'' ''drurypat_alumni.txt''=====