Skip to main content

Relais Server Addon

Relais Documentation Resources​

General documentation for the Relais web service: https://relais.atlassian.net/wiki/spaces/JLL/pages /321 I 2643/Relais+web+services

Documentation for the authentication endpoint of the Relais service: https://relais.atlassian.net/wiki/spaces /JLL/pages/36798540/Authentication

Documentation for the encryption layer of the authentication endpoint: https://relais.atlassian.net/wiki/spaces /ILL/pages/3 7224619/Encryption

Summary​

This addon is a server addon for ILLiad. It will search the queue specified by the FindItemSearchQueue setting and will make calls to a Relais FindItem DWS. Depending on the availability the addon will route those transactions to other queues.

  • If the item is requestable via the consortium the item will be requested using the Relais API and will be routed to the queue indicated in the RequestItemSuccessfulQueue setting. If an error occurs during the Relais RequestItem call the ILLiad transaction will be routed to the queue indicated in the RequestItemErrorQueue setting.
  • If the item is not requestable but available locally, the transaction will be routed to the queue specified by the AvailableLocallyQueue setting.
  • If the item is not requestable and not available locally, the transaction will be routed to the queue specified by the ManualProcessingQueue setting.
  • If an error occurs during this process, a note will be added to the transaction and it will be routed to the queue specified by the ErrorQueue setting.

Workflow​

For Relais service authentication, the addon is currently sending the following pieces of information. All of these parameters are being sent as plaintext, in its current configuration.

  • ApiKey
  • UserGroup
  • Partnershipld
  • LibrarySymbol
  • Patronld
  • UserPassword

When enabled, the Relais service uses RSA to decrypt the following parameters:

  • ApiKey
  • Patronld
  • Surname
  • UserLogin
  • UserPassword

If the encryption system is enabled, these parameters cannot be sent as plaintext and must be enc1ypted. None of the other Relais service endpoints will use RSA enc1yption. This enc1yption scheme only applies to the authentication endpoint of the Relais service.

Important Considerations​

  1. If any of these parameters are being sent, they must be enc1ypted using an RSA public key.
  2. The plaintext for each encrypted value will be concatenated with a timestamp, to prevent replay attacks: confidential Plaintext Data in yyyyMMdd HHmmss.
  3. Only the values of the parameters are encrypted. The message as a whole is a plaintext JSON object. The encrypted values must be formatted using base-64.

Example​

Below is a sample JSON object, showing which fields are currently being used for Relais service authentication, and showing which will be enc1ypted.

{"ApiKey": "(the patron's api key) (encrypted) (base-64) 11,"UserGroup": "patron", "Partnershipid11 : " ( the patron's partnership ID)", "LibrarySymbol": "(the patron's library symbol)", ''Patronid'': ''(the patron's ID) (encrypted) (base-64)'', "User Password": "(the patron's password) (encrypted) (base-64)"}

____

The addon will perform Find Item calls for ISBN searches. If it is determined that the request is available locally it will route to the queue defined by the AvailablelocallyQueue setting. If the item is available a Requestltem call will be placed to the Relais API. Depending on the availability the addon will route those transactions to other queues.

  • The server addon will perform a Find Item call and search using the ISBN if available. If the item did not have an ISBN and/or the Find Item results provided no results a subsequent Findltem search using keywords will be performed. Relais Findltem keyword searching will be comprised of title, author, and when available, supply the ILLiad publication date and document type. The addon will supply either the LoanDate or PhotoArticleDate depending on the ILLiad RequestType. The addon will not perform any type of cleanup of the date and will provide the entire value to Relais. The format of the request provided to Relais will be based upon the mapping found in the DocumentTypeRelaisFormatMappings setting. If the ILLiad request has a document type that is not found in the mapping a format will not be provided in the Findltem request to Relais.
    • If the item is requestable via Relais D2D the item will be requested on Relais using the RelaisRequestltem API action. The request will then be routed to the queue indicated in theRequestltemSuccessfulQueue setting. If an error occurs during the Relais Requestltem call the ILLiad transaction will be routed to the queue indicated in the RequestltemErrorQueue setting.
    • If the item is not requestable but available locally, the transaction will be routed to the queue specified by the AvailableLocallyQueue setting.
    • If the item is not requestable and not available locally, the transaction will be routed to the queue specified by the ManualAvailabilityProcessingQueue setting.
    • If an error occurs during this process, a note will be added to the transaction and it will be routed to the queue specified by the ErrorQueue setting.

Settings​

FindltemSearchQueue

  • Defines the name of the queue that indicates the transaction is to be searched using Find Item DWS.
  • Default: BorrowDirect Find Item Search

MaximumAuthenticationAttempts

  • Defines the maximum number of attempts to authenticate per transaction before giving up. Default value is “3”

FindItemSearchQueue

  • Defines the name of the queue that indicates the transaction is to be searched using Find Item DWS. Default value is “BorrowDirect Find Item Search”

ManualAvailabilityProcessingQueue

  • Defines the name of the queue for manual ILLiad processing to which requests will be routed if a No response is returned from the BorrowDirect Find Item DWS but there were additional records that should be checked.
  • Default: BorrowDirect Manual Availability Processing.

RequestltemErrorQueue

  • The queue a transaction is routed to if an error occurs while attempting to perform the Requestltem call within Relais.
  • Default: Error Processing BorrowDirect Find Item DWS

RequestltemSuccessfulQueue

  • The queue a transaction is routed to if placed successfully within Relais
  • Default: Request Finished

ManualProcessingQueue

  • Defines the name of the queue for manual ILLiad processing to which requests will be routed if a No response is returned from the BorrowDirect Find Item DWS and the item is not available locally. Default value is “BorrowDirect Manual Processing”.
  • Default: BorrowDirect Manual Processing

RequestItemSuccessfulQueue

  • The queue a transaction is routed to if placed successfully within Relais.

RequestItemErrorQueue

  • The queue a transaction is routed to if an error occurs while attempting to perform the RequestItem call within Relais

ErrorQueue

  • Defines the name of the queue to which transactions will be routed if an error occurs during processing. Default value is “Error Processing BorrowDirect Find Item DWS”

RequestItemErrorQueue

  • The queue a transaction is routed to if an error occurs while attempting to perform the RequestItem call within Relais. Default value is “Error requesting item via BorrowDirect”

AvailableLocallyQueue

  • Defines the name of the queue to which items that are available locally will be routed.
  • Default: Request Available Locally

AvailableLocallyButtonLabelText

  • Defines the Button Label that the Find Item DWS sends back if the item is available locally. Example value: “Available at the UCHICAGO library”
  • e.g. In this sample provided by Relais, the Button Label would be View in the CORNELL Library Catalog. { "Available":false, "SearchTerm":"isbn=9780821419755 or isbn=0821419757 or isbn=9780821420393 or isbn=0821420399", "Req uestli nk": {"Button Link": "http ://newcatalog. Ii bra ry. corn el I. ed u/ catalog/7 5917 46"," Button Labe l":"View in the CORNELL Library Catalog.", "RequestMessage":"This item is available locally."}, "NumberOfRecords": 1}

NotePrefix

  • Prefix to add before notes added to transactions processed by this adddon. Default Value is "BorrowDirectFindItem - ".

RelaisHostURL

  • The URL for the Find Item DWS.

PartnershiplD

  • The Partnership ID to use when making calls to the DWS.
  • Default: BO

RelaisReturnsProxyUrls

  • Boolean value that specifies whether the URL returned by the Relais Find Item service includes a proxy URL. This should be changed to true for anyone using EZProxy. Default value is “false”

PartnershipID

  • The Partnership ID to use when making calls to the DWS. Default value is “BD”

LibrarySymbol

  • The Library Symbol to use when making calls to the DWS. Default value is blank.

UserBarcodeMapping

  • The mapping to indicate where to find the user’s barcode. This is used for authentication to the DWS. E.g. {TableField:User.UserInfo1}

UserBarcodeExternalLookupUrl

  • The URL to an external HTTP lookup service to retrieve user barcodes. Tags for transaction and user in the setting URL will be replaced. The response is parsed using the UserBarcodeExternalMatch regular expression to obtain a user’s barcode. This should be blank if the user barcode mapping should be retrieved from the ILLiad user record. E.g. https://api.library.edu/?netid=\{#User.SSN\}.

UserBarcodeExternalMatch

  • The match string used to parse the response from the UserBarcodeExternalLookupUrl. e.g. \"status\":\"Active\".*\"bc\":\"(?<Barcode>\d+)\".

UserPasswordMapping

  • The mapping to indicate where to find the user’s password to use to authenticate to the DWS. This value can be blank if password authentication is not required. E.g. {TableField:User.UserInfo1}

PickupLocationMapping

  • The mapping to indicate where to find the user’s pickup location E.g. {TableField:Transaction.ItemInfo1}

RequestItemPickupLocationMapping

  • A comma-separated mapping of value pairs to map between the ILLiad PickupLocationMapping value and the single-letter character code expected by Relais. If a mapping cannot be found, the PickupLocationMapping value will be sent as-is. E.g. LAW=A,JRLMAIN=B

RequestItemExternalNumberMapping

  • The mapping to indicate what to set the Relais request item ExternalNumber to. Default value is “{TableField:Transaction.TransactionNumber}”.

RequestItemNotesMapping

  • The mapping to indicate what to add to the Relais request notes. Default value is empty.

DocumentTypeRelaisFormatMappings

  • A comma-separated mapping of name-value pairs to indicate a mapping between the ILLiad document type and the Relais format. If a mapping is not found for a document type, a format will not be provided in the FindItem request. The addon will search for ILLiad document types in a case-insensitive manner. The first value (name) is the ILLiad document type. The second value is the Relais format. Default value is “Book=Book,Article=Article,Thesis=thesis,Book Chapter=Book”

ApiKey

  • The API Key to use to authenticated with the DWS. Default value is blank.

RSAPublicKeyFile

  • The name of a PEM formatted RSA public key file. This setting must be the name of the PEM formatted public key file that was added to the addon’s ZIP package. The key file MUST be PEM formatted.

RelaisTestInstance

  • Indicates if you are connecting to the Relais test instance (i.e. bd-test). This option should only be enabled if the partnership subscribes to a test instance with Relais.

Templated Settings​

The UserBarcodeMapping, UserPasswordMapping, PickupLocationMapping, and RequestItemNotesMapping settings all make use of templated tags to allow for mapping to other values in the system. The values for these settings can include static text and/or a mapping to a User or Transaction field.

UserBarcodeMapping

  • The mapping to indicate where to find the user's barcode. E.g. User.Number

UserPasswordMapping

  • The mapping to indicate where to find the user's password to use to authenticate to the DWS. This value can be blank if password authentication is not required. E.g. {TableField: User. User! nfo 1}

PickuplocationMapping

  • The mapping to indicate where to find the user's barcode. E.g. Transaction.ltemlnfo1

RequestltemNotesMapping

  • The mapping to indicate what to add to the Relais request notes. E.g. This example adds the ILLiad TNto the Relais request notes for future reference: <ILLiad TN:{TableField:Transaction.TransactionNumber}>

---Table field tags

  • The TableField tag allows for replacing a value from another ILLiad table. The addon can support retrieving values from the User or Transaction tables.
  • The tag syntax uses curly braces to denote a tag and must start with TableField: followed by the ILLiad table, then a period, and finally the field name.
  • Example: {TableField:User.FirstName}

Combining tags and static text

  • When the addon setting is evaluated tag replacement values are processed and all other text stays as-is. As an example, to set the RequestItemExternalNumberMapping value to have a prefix of “ILLiad TN:”, the setting value would be set to ILLiad TN:{TableField:Transaction.TransactionNumber}. This would get evaluated as “ILLiad TN:12345” if the addon was processing transaction 12345.

External User Barcode Lookup

  • The addon will allow for an external user barcode lookup using an HTTP GET request. The response will be parsed using the UserBarcodeExternalMatch regular expression. The expression must contain the named group “Barcode”, i.e. (?<Barcode>\d+). A match set to \"status\":\"Active\".*\"bc\":\"(?<Barcode>\d+)\" requires the JSON element status to be included with an exact value of Active and will parse the bc element looking for a string containing digits.