Download

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

Configuration

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

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 DeliveryFormatPreference, DeliverySpeedPreference, 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.

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.

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.