ILLiad BL on Demand Addon

Atlas and OCLC do not support default addons or user-created addons.

If you need assistance with using, troubleshooting, or writing addons, please contact Atlas Systems for a custom services quote.

NameBL on Demand
Version1.2
AuthorBritish Library
DescriptionThe BL on Demand addon facilitates ordering materials in ILLiad using the British Library's BL on Demand service. OCLC IFM is used for making payments for the BL on Demand orders.

Download

Download zip file: BritishLibrary.zip

Requirements

  • BL on Demand user account 
  • ILLiad version 8.4 or higher installed
  • The ILLiad Web Platform configured and functioning properly.
  • OCLC Web Services Key (WSKey) & Secret provisioned for the IFM Webservice

For more information on obtaining a British Library institution account please contact the British Library.

Configuration

Addon settings are configured in the Manage Addons form (System tab, Manage Addons).

NameTypeDescription
IFMSpendingLimitStringThe maximum amount allowed for an order. This is a numeric value and should not include currency symbols.
BritishLibraryUsernameStringUsername for logging into the British Library. This setting can be left empty but will require logging into manually to complete an order.
BritishLibraryPasswordStringPassword for logging into the British Library. This setting can be left empty but will require logging into manually to complete an order.
BritishLibraryAccountKeyStringThe British Library account key (with the format nn-nnnn [n is any digit]) that the user is wanting to order against. When supplied, the availability and pricing will be specific to that account.
OrderNumberFieldStringThe ILLiad transaction field to store the British Library order number.
OrderCostFieldStringThe ILLiad transaction field to store the British Library cost. Regardless of your CurrencyDisplayFormat, this value is stored in IFM.
CurrencyDisplayFormatString

The currency symbol used to display British Library price ranges. This may not be the same as the IFM charges that are processed.

The available currency formats are based on British Library supported currencies. The allowed values are: USD, GBP, EUR, HKD, CAD, AUD, CHF, DKK, INR, ISK, JPY, NOK, NZD, SEK, SGD, THB, ZAR

PricingRegionStringThe British Library pricing region to indicate which price list is used for display purposes. Valid values are UK or OS (overseas).
DeliveryFormatPreferenceStringA comma-separated list of preferred delivery formats. The addon will attempt to set the selected delivery format based on the first option that is available to an order. The available formats are based on the button names that display in the BL ordering interface such as Encrypted Download, Unencrypted Download, and Paper.
DeliverySpeedPreferenceStringA comma-separated list of preferred delivery speeds. The addon will attempt to set the selected delivery speed based on the first option that is available to an order. The available speed options are based on the button names that display in the BL ordering interface such as 2 Hours, 24 Hours, and 4 Days.
DeliveryQualityPreferenceStringA comma-separated list of preferred delivery qualities. The addon will attempt to set the selected delivery quality based on the first option that is available to an order. The available quality options are based on the button names that display in the BL ordering interface such as Standard and High.
LibraryPrivilegePreferenceBooleanSets the initial state for the 'Library Privilege' option if it is available on the British Library ordering form.
CacheDirectoryStringThe directory to cache data to. If the directory does not exist, the addon will attempt to create it. For this setting, the string "{MyDocuments}" will be replaced with the path to the current user's MyDocuments directory.
DebugEnabledBooleanSpecifies whether additional debug logging should be written to the log file

Using this Addon

The BL on Demand addon facilitates ordering materials in ILLiad using the British Library’s BL on Demand service. OCLC IFM is used for making payments for the BL on Demand orders.

ILLiad Request Requirements

The BL on Demand addon will only display on the ILLiad request form if the ILLiad request is an article and if the British Library is able to supply the document. The determination of if a document can be supplied is dependent on a high level match using the BL API. The British Library requires certain bibliographic data to be set on the ILLiad request to determine if a match can be found.

  1. A valid ISSN or journal title must be provided.
  2. A year, volume and issue, or edition must be provided.
  3. The article title, author, or pages must be provided.

When it is determined that the BL can supply the article the addon will be displayed on the ILLiad request form. The addon will display some detailed reference information before the order is made.

Generic pricing information is displayed for various formats, speeds, and qualities. Please note that users who provided institutional account information may obtain alternate pricing which is displayed during the order process when options are chosen. The pricing information that is displayed before the process is initiated uses the CurrencyDisplayFormat and PricingRegion settings.

Making an order

After deciding to fulfill an ILLiad request with the BL on Demand service:

  1. Click the ‘Initiate IFM Payment’ button in the ribbon. This will start the process of obtaining an OCLC IFM payment token that will be used for paying for the order. The pricing grid will be replaced with the British Library’s ordering interface.
  2. If the BritishLibraryUsername and BritishLibraryPassword settings are supplied, the addon will attempt to automate the login process. If they are not supplied, the credentials will need to be manually entered.
  3. If your British Library credentials are configured for more than one account an Account Selection screen may be displayed. When the BritishLibraryAccountKey is supplied, the addon will attempt to choose that account to proceed to the next ordering screen. If the account cannot be selected the user should manually choose the British Library account that should be used for the order.
  4. The next step is choosing the delivery format and options. The addon will attempt to choose the default options based on the DeliveryFormatPreferenceDeliverySpeedPreference, and DeliveryQualityPreference settings. Please ensure the proper delivery format options are set and that all other details on the form are correct.
  5. By default, the ILLiad transaction number is automatically entered in the ‘Your Reference’ field on the order form. The value entered in this form can be modified; see the DataMap Customization section for more information.
  6. Your IFMSpendingLimit setting must be more than the total cost for the order. If the order will exceed your specified limit you may see a warning to indicate that the selected options exceeds the maximum cost. If you wish to proceed with the order you will need to close the ILLiad request form, modify the addon settings to accommodate the higher price, and re-start the process of making the order.
  7. After ordering the material you will see an order confirmation screen. The confirmation will include a BL order reference and the order cost. The addon will check the amount that the BL has charged against your IFM account and display the costs in the IFM Charges. To complete the order process you must click the Approve IFM Payment button once you have verified the IFM Charges matches the expected cost for the order you are submitting.
  8. In the event an error occurs in which the addon cannot retrieve the payment details the ‘Retry IFM Payment’ button will become enabled. While unlikely, you may have to retry this process to proceed if there are networking issues or delays.
  9. After approving the IFM Payment the addon will switch back to the request detail tab and will import information about the British Library order. The BL reference number will be imported into OrderNumberField as defined by your addon settings. The cost of the order will be imported into the OrderCostField as defined by your addon settings. The LendingString and Lender will be set to BRI. After approving the IFM payment your order has been successfully made and will be fulfilled by the British Library.

For security purposes, orders must be completed within 20 minutes of clicking the ‘Initiate IFM Payment’ button.

DataMap Customization

There is some flexibility in the values that can be used for setting the British Library order reference and for displaying the citation. While the DataMap file also allows for customization of the values used to search for BL availability and making the order they should not be modified without detailed knowledge of the British Library API as it may result in issues preventing your addon from working properly.

The DataMapping.Order.CustomerReference mapping is used to set a default value for the British Library order reference. By default this is set to ILLiad TN: {TableField:Transaction.TransactionNumber}. This will be entered as “ILLiad TN: 1234” assuming that transaction 1234 is the request being processed. Additional tags or static text can be used.

Tagging

The DataMap file allows for tagged values. The tagging syntax will look for values inside of curly braces. i.e. { }. The allowed replacements are uin (The BL unique identifier of the item), accountkey (The British Library Account entered into the addon settings), or paymenttoken (The value of the IFM payment token). Two additional complex replacements are allowed of TableField and MatchXML.

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.

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


The MatchXML replacement can retrieve a value from the British Libraries API Match document that is obtained. This must be a valid XPATH syntax or an empty string will be the replaced value. For more information on the Match API result, please see http://apitest.bldss.bl.uk/docs/ref/Match/match.html.