ILLiad Symphony Circulation System Addon

Owned by Matt Calsada
Last updated: Nov 20, 2023 by Brittany de Gail

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

Name

Version

Author

Description

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

Download zip file:

SymphonyCirculation_v1.0.7.zip

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. 

Installation

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.

Configuration

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

Type

Description

ErrorQueueBorrowing

Symphony Errors

String

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.
PickupLocationMappings
StringComma separated list of ILLiad pickup locations mapping to the Symphony library. e.g. ILL=MAIN,LAW=LAW.

CallNumberMapping

TN{TableField:Transaction.TransactionNumber}

String

Format for call number used in Symphony.

SymphonyItemHomeLocationMapping

STACKS

String

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.

UseLoanPeriodForItemType

CheckedBoolean

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

DefaultItemType

ILLString

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.

LibraryUseOnlyItemType


String

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

LibraryUseOnlyPickupLocation


String

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

OverrideOnUserBlocked

CheckedBoolean

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

OverrideCode


String

Override code to use when overriding a user block.

ItemPrice

50.00

String

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

CheckInStatusList

CHECKED_OUT

String

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.

Process

  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.

Tagging

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. 

Examples 

  • {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.