Skip to main content
OCLC Support

Holds data

Find instructions, a file template, and a sample record for formatting and sending your holds data to OCLC.

Purpose

This document contains instructions for formatting and sending your holds data to OCLC. Holds data should only be sent for current hold requests yet to be fulfilled, not holds that are on the shelf waiting to be checked out.

 Note: Circulation files are required to be UTF-8 encoded.

File template

File Description
Tab-delimited holds template (Microsoft Excel) Contains 9 columns. Save as a tab-delimited text file (an Excel file cannot be used to send data).

 Note: Required fields have red column headings.

Column rules

  • The text file must contain all 9 tab-delimited columns in the order listed in the table below.
  • The first row 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 8 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, include the column header, but leave the rest of the column empty (do not delete the column header).

 Note: If columns are deleted, moved, or renamed, the file cannot be used to load data.

Filename rules

  • Filenames can contain letters, numbers, periods, and underscores.
  • Filename cannot contain spaces or special characters (e.g., @, ?, *, #, !, &, %, $, ^).
  • Tab-delimited files must have the .txt file extension.
    Example: OCLCsymbol.itemstats.txt

Send holds data

Send your holds data files via SFTP with your OCLC file exchange account.

Directory Use for
/xfer/wms/test/in/circdata/holds Loading holds data to WMS

Holds file format

 Note: None of the columns are repeatable.

Column number Column name Required Example Description
1 institutionID x 127941 The WorldCat Registry ID for the institution that owns the item.
2 borrowerBarcode x 123456789 The barcode of the patron who has the hold request on the material.
3 oclcNumber x 12345678 The OCLC number of the bibliographic record for the title that is on hold.
4 pickupBranch x 127111 The Branch ID of the patron's preferred pickup location.
5 earliestDateNeeded   2020-01-01
  • The date that the patron submitted the hold request.
  • Should be before neededBeforeDate.
  • If left blank, it will be populated with the date of the load.
  • In year-month-day format: YYYY-MM-DD
6 neededBeforeDate   2020-01-10
  • The date that the hold request expires.
  • Must be after the earliestDateNeeded.
  • Defaults to today's date + 20 years.
  • In year-month-day format: YYYY-MM-DD
7 suspensionStartDate   2020-01-01
  • The date that the patron wants to begin the suspension on the hold.
  • When using suspensionStartDate and suspensionEndDate, both should be present in the record.
  • In year-month-day format: YYYY-MM-DD
8 suspensionEndDate   2020-01-01
  • The date that the patron wants to end the suspension on the hold.
  • When using suspensionStartDate and suspensionEndDate, both should be present in the record.
  • In year-month-day format: YYYY-MM-DD
9 borrowerInstitutionId x 127941
  • The WorldCat registry ID of the institution that patron belongs to.
  • Intended for future group migrations (not currently implemented).

Sample record

File Description
Tab-delimited holds text file example (Text file) An example of a tab-delimited text file that results from saving the tab-delimited holds template as text. It contains sample data.

Questions

If you have questions, contact your OCLC Implementation Manager at WMSImp@oclc.org.