RequestItem

Last updated
Save as PDF

Find information about the RequestItem service, which allows the library to submit a request into Relais ILL through the Discovery web services framework.

Once a requestable item is found using FindItem, the RequestItem service allows the library to submit a request into Relais through the Discovery web services framework.

Note: This service is used only when Relais is used for request management.

Request Item

Request Item service URL:

http://HOSTNAME/dws/item/add?aid=${aid}

where ${aid} is the authorization id for the user logged in. The {aid} is provided by the Authentication service.

HTTP Method: POST
HTTP Header Content-Type: application/json

RequestItem request json

The value(s) or values to be used in the ExactSearch. If a valid Type is provided but there is no corresponding value, an error is returned: "No Value for ExactSearch Type: {type} provided."

Value	Description
PartnershipId	Required. Partnership ID indicating to which consortium/group the library belongs. Contact Relais International for the Partnership ID.
PickupLocation	The pickup location selected by the patron at the time the request was submitted. A list of pickup location codes and descriptions is returned to the client in the FindItem response when the item is requestable, i.e., Available = true.
Notes	Any notes provided by the patron at the time the request was submitted.
ExactSearch	Notes: One of ExactSearch or BibSearch must be provided. Only one of ExactSearch or BibSearch may be provided.
Types	ISBN (repeatable) ISSN (repeatable) LCCN OCLC Control Notes: Values are case-sensitive. If an invalid Type is supplied then an error is returned: "Invalid Type: {type} provided."
Value	The value(s) to be used in the ExactSearch. If a valid Type is provided but no corresponding value and error is returned: "No Value for ExactSearch Type: {type} provided."
BibSearch	Notes: One of ExactSearch or BibSearch must be provided. Only one of ExactSearch or BibSearch may be provided.
Title	Mandatory when BibSearch is provided. Searched as a phrase. Cleanup, such as the removal of special characters, is done prior to the search.
Author	Repeatable. Commas and periods will be replaced with a space. Any initials are dropped. Example: For DICKSON, BRUCE J. the keywords = DICKSON and BRUCE are used. the following keywords are dropped: author, editor, edited by, and DR. Example: For Begun, David R, the keywords Begun and David are used. Dates are dropped. Example: For Enterline, Lynn, 1956-, the keywords Enterline and Lynn are used.
ResultFilter	Date and format filters can be used to narrow the results. Only one of Include and Exclude filters may be provided.
Include	Include the records that match the filter(s) provided.
PublicationDate	Include the records that match the year(s) provided. Repeatable. For publication dates, the four digit year is extracted based on the valid dates configured. Example: For c2013, the date 2013 is used. For 2015-01-01 the date 2015 is used.
Format	Include the records that match the format(s) provided. Repeatable. The value for format must be from the configurable list of formats supported.
Exclude	Exclude the records that match the filter(s) provided.
BibInfo
ArticleTitle	The title of the article or book chapter as entered by the patron or provided as part of the request.
ArticleAuthor	The author of the article or book chapter as entered by the patron or provided as part of the request.
Volume	The volume as entered by the patron or provided as part of the request.
Issue	The issue as entered by the patron or provided as part of the request.
AdditionalNumbers	Additional numbers as entered by the patron or provided as part of the request.
RequestInfo
PublicationType	Publication type as selected by the patron or provided as part of the request. Must exist in the publication type code table.
ServiceType	Service type as selected by the patron or provided as part of the request. Must exist in the service type code table.
ServiceLevel	Service level as selected by the patron or provided as part of the request. Must exist in the service level code table.
RequestSource	Request source as selected by the patron or provided as part of the request. Must exist in the request source code table.
ExternalNumber	Request number from an external ILL management system.
NeedByDate	Need by date as entered by the patron.
MaximumCost	Maximum cost as entered by the patron. In BigDecimal type, such as 1, 2, 10.59, etc.
DeliveryMethod	Delivery method as selected by the patron or provided as part of the request. Must exist in the delivery method code table.
DeliveryAddress	Delivery address as entered by the patron or provided as part of the request.

RequestItem request - template (for download)

Examples

Example 1 - single ISBN

Example 2 - title and author

Example 3 - single ISBN with BibInfo & RequestInfo

RequestItem response json

{ 
  "RequestNumber":"requestNumber", 
  "RequestLink":{ 
     "ButtonLink":"buttonLink", 
     "ButtonLabel":"buttonLabel", 
     "RequestMessage":"requestMessage" 
 }
}

Note: One of RequestNumber or RequestLink will be returned, but not both.

RequestItem response - JSON elements

Element	Description
RequestNumber	The request number assigned by Relais.
RequestLink
ButtonLink	The ButtonLink used depends on the results of the Requestability evaluation. The following options are possible: Deep link to the local catalog. For example: http://dla.library.upenn.edu/dla/franklin/record.html?id=${md-id} The link to display to submit a request to another consortium member via a web form. For example: https://rc.relais-host.com/dws/incrementRequest?pid=${pid}&SS=${oclcSymbol1}&targetURL=https://ill.lib.umich.edu/illiad/illiad.dll/OpenURL%3fsid=UBILL AddRequest when the library is configured to not use a web form when submitting a request to another consortium member. The link to display to submit an ILL request. For example: https://mit.illiad.oclc.org/illiad/illiad.dll/OpenURL%3fsid=BDILL Blank if no ILL requesting is allowed. These links are taken from the library's configuration.
ButtonLabel	The text to display for the link. For example: Request. This text is taken from the library’s configuration.
RequestMessage	A configurable message that accompanies the button described above. Example: This item is not available from another consortium member. It may be available via ILL. The text of this message is taken from the library’s configuration.

RequestItem response - template (for download)

Errors

The following is a sample response for an unsuccessful request:

{
"Problem":{
"ErrorCode":"PUBRI002",
"ErrorMessage":"Invalid aid"
}
}

This service may return the following error codes and messages:

Code	Type	Message
PUBSC001	Public	Invalid request The following message could be appended: Missing required URL parameter: aid
PUBSC005	Public	Invalid JSON request
PUBAZ001, PUBRI001	Public	Missing parameter The following message could be appended: PartnershipId is required ExactSearch or BibSearch is required Invalid Type: {Type} provided. No Value for ExactSearch Type: {Type} provided. No title provided. PublicationDate provided in Include and Exclude filters. Format provided in Include and Exclude filters.
PUBRI004	Public	Not a valid format: {Format}
PUBRI005	Public	Could not parse valid date: {PublicationDate}
PUBRI002	Public	Invalid aid
PUBSC006	Public	User group not authorized to access the service
PUBRI003	Public	No result
PRIAZ001, PRIRI001, PRISC001	Private	Internal error
PRIRI002	Private	Error returned by the Requestability service. The error may be appended.
PRIRI003	Private	Error returned by the AddRequest service. The error may be appended.