Doorgaan naar de website
OCLC Support

RequestItem

  1. Laatst bijgewerkt
  2. Opslaan als 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.