ILLiad Symphony Circulation System Addon

This addon is only compatible with ILLiad version 9.0 and higher.





Symphony Circulation1.0.7Atlas SystemsThis is a system addon for the ILLiad Client to integrate with a Symphony catalog via the Symphony API for circulation processing.


Download zip file:

Do not overwrite your custom mappings

If you are updating to a newer version of this addon, do not replace the ItemTypeMapping.lua or SymphonyAPIServiceClient.Datamapping.lua files. These files often contain institution-specific data mapping that should not be overwritten by the default values provided in the zip file on this page.

Release Notes

Release notes are available for Symphony Circulation Addon v1.0.7 and later.
  • v1.0.7:
    • Updated the descriptions used for the UseLoanPeriodForItemType and DefaultItemType settings for better clarity.
    • Updated the Readme.html file to fix minor errors and to include an additional section describing the addon's item type mapping functionality. 


The addon is a system addon for the ILLiad Client. The addon must be installed on each client where Symphony functionality is used; any ILLiad Client performing checking in from lending libraries, checking in borrowing items from patrons, marking lending items as found, and handling lending returns. See Installing and Uninstalling Client Addons for more information.


Configuring Required ILLiad Customization Keys

The ILLiad Symphony Circulation System Addon uses the Symphony API rather than NCIP/SIP/SIP2 standards to integrate the ILLiad Client with a Symphony catalog. In order to integrate your Symphony catalog with ILLiad using the Symphony API, the following customization keys must be configured in the ILLiad Customization Manager (under Web Interface | Symphony) prior to using the addon:

  • SymphonyAPIAddress

  • SymphonyAPIClientID

  • SymphonyAPILibraryID

  • SymphonyAPIStaffUsername

  • SymphonyAPIStaffPassword

  • SymphonyUserLookupField

  • SymphonyUserLookupType

For more information on how to configure these keys, see SymphonyAPI: Customizing Settings.

Configuring Addon Settings

Addon settings are configured in the Manage Addons form.

Setting Name

Default Value




Symphony Errors


Defines the name of the queue to which borrowing transactions will be routed if there is an error in processing.

BorrowingCheckedInFromLibraryRoutingAwaiting Customer Contact,Customer Notified via E-MailStringComma separated list of statuses a request is routed to after successfully creating a record in Symphony and placing the item on hold for the user.
SymphonyBarcodeMappingTN:{TableField:Transaction.TransactionNumber}StringFormat for barcode mapping in Symphony.
PickupLocationField{TableField:User.NVTGC}StringDefines the field in which the pickup location is stored.
StringComma separated list of ILLiad pickup locations mapping to the Symphony library. e.g. ILL=MAIN,LAW=LAW.




Format for call number used in Symphony.




Defines the mapping to indicate the home location for the item.

HistoryEntryCreateBibRecordSuccessSymphony: Bib Record created. (Bib Key: {bibKey})StringThe history entry made when the bib record is created in Symphony successfully. Leave blank for no history entry.
HistoryEntryPlaceHoldSuccessSymphony: Item placed on hold. (Hold Key: {holdKey})StringThe history entry made when the hold is placed in Symphony successfully. Leave blank for no history entry.
NotePrefixSymphony:StringPrefix to add before notes added to transactions processed by this addon.



If true, addon will use the values in ItemTypeMapping.lua to determine item type.



Item type to use if loan period mapping is not defined or if UseLoanPeriodForItemType is set to false. The value of this setting must match an item type in Symphony.



If not empty, this item type will be used for all items marked Library Use Only.



If not empty, this pickup location will be used for all items marked Library Use Only.



If true, the addon will place a hold even if the user is blocked in Symphony.



Override code to use when overriding a user block.




Price value that item records will be given in Symphony. Currency code is USD.




Comma-separated list of Symphony statuses. If an item is in any of these statuses when checked in in ILLiad, a Check In message will be sent to Symphony.

General Notes

  • The system addon works in conjunction with functionality that is performed in the ILLiad Staff Client. If a request is modified in an application other than the ILLiad Client (such as Web Circ) the Symphony processing functionality will not be initiated. Each Client that will be performing the Check in from lending library functionality will need to have this addon or the Symphony processing functionality will not be initiated.
  • Users must have a barcode defined in the field specified in the SymphonyUserLookupField customization key. If the barcode is not set the Symphony calls will fail.
  • The Symphony functionality will only work for ILLiad requests whose request type is set to Loan.

Borrowing Functionality

The Symphony functionality will be initiated when using the Check In button on the Check In from Lending Library form. Symphony calls are made to create a bib record item with an item and place it on hold for the user. If an error occurs during either Symphony call the request will be routed to the ErrorQueueBorrowing defined in the addon settings. The request will be routed to Awaiting Post Receipt Processing and any of the queues defined in the BorrowingCheckedInFromLibraryRouting setting if no errors were encountered.


  1. In the ILLiad Client on the main form, navigate to the Borrowing ribbon and click on Check In From Lending Library.
  2. Search for the request that is being checked in.
  3. Click on Check In. The Symphony processing will happen after the standard ILLiad processing occurs.

DataMapping Customization

The SymphonyAPIServiceClient.DataMapping.lua file allows for customization of data that is sent via Symphony calls.

Item Type Mapping

The ItemTypeMapping.lua file allows for customization of item types assigned to items created in Symphony based on their loan periods in ILLiad.

Pickup Location Mapping

Pickup location mapping is based on the PickupLocationMappings and PickupLocationField addon settings.


The SymphonyAPIServiceClient.Datamapping.lua file allows for tagged values. The tagging syntax will look for values inside of curly braces( i.e., { }) and must match a specific format.

The TableField replacement will retrieve a value from an ILLiad table and field. The format is the TableName, followed by a period, followed by the FieldName. Transaction, User, and Lender are the only allowed table names for tag replacement. 


  • {TableField:Transaction.ReferenceNumber} would be replaced with the ReferenceNumber of the ILLiad request.
  • {TableField:User.LastName} would be replaced with the LastName of the user associated with the ILLiad request.