Transfer Hold Request

Start Transfer Hold Request Process

POST /api/.../workflow

Transfer an existing local hold request for a patron at either the bibliographic or item level. For detailed workflow process information, see Overview.

Permissions

This call requires the HoldRequests_Modify (ID: 90) permission to modify the request and the OverrideRequestBlocks_Allow (ID: 132) permission to override hold request blocks.

Workflow Steps

  • Patron is blocked (can be bypassed). Get patron blocks for precheck
  • Title is not holdable (can be bypassed)
  • Patron already has maximum number of holds total (can be bypassed)
  • Patron already has maximum number of holds by material type (can be bypassed)
  • Select a specific designation (list of possible values is returned in the DesignationsOrVolumes attribute). This step is skipped in bulk mode.
  • Select a specific volume (list of possible values is returned in the DesignationsOrVolumes attribute). This step is skipped in bulk mode.
  • Prompt for whether a specific item or serial should be used for hold request. This step is skipped in bulk mode.
  • Prompt for whether or not to promote an item-level request to a bib level (related to serials/multi-part monograph processing). This step is skipped in bulk mode.
  • Duplicate hold requests exist (can be bypassed)

For title is not holdable step, the following are reasons a hold request is blocked and can NOT be bypassed:

  • Hold request not permitted. The bibliographic record has been created for ILL.
  • The bibliographic record is Provisional
  • The bibliographic record is Deleted
  • This item is marked 'Do not mail to patron'
  • Hold request not permitted
  • The item record is Provisional
  • The item record is Deleted.

For title is not holdable step, the following are reasons a hold request is blocked and CAN be bypassed:

  • No items are attached to the bibliographic record
  • An item at this branch is IN
  • All items have a prohibited status and will not fill this request
  • All items are restricted from filling this request
  • All items are restricted from filling this request according to their assigned branch policy
  • All items will not fill this request because they do not belong to a responder branch for this pickup location
  • The item is IN
  • The item has a prohibited status and is not available to fill your request
  • This item is not holdable
  • This item cannot fill the request according to its assigned branch policy
  • This item will not fill this request because it does not belong to a responder branch for this pickup location
  • This multipart item is restricted from filling requests
  • This serial item is restricted from filling requests

Request Information

Parameters
Name Type Required Description
WorkflowRequest DtoWorkflowRequest Yes Define this parameter in the request body.
DtoWorkflowRequest
Property Type Nullable Description
WorkflowRequestType Int No Required. For transferring a hold request, this must be set to 24.
TxnBranchID Int No Transacting branch ID. This should represent where the request originated from. Typically the same as the logged on branch, but in the case of offline processing it would be the branch that was logged into during offline processing.
TxnUserID Int No Transacting Polaris user ID. This should represent who originally created this request. Typically the same as the logged on user, but in the case of offline processing it would be the user that was logged on during offline processing.
TxnWorkstationID Int No Transacting workstation ID. This should represent where the request originated from. Typically the same as the logged on workstation, but in the case of offline processing it would be the workstation that was logged into during offline processing.
RequestExtension DtoWorkflowRequestExtension No To transfer hold request requires a TransferRequestExtensionData object.
WorkflowReplies List of DtoWorkflowReply Yes It is possible to pass in a list of replies for automated processing.
TransferRequestExtensionData
Property Type Nullable Description
WorkflowRequestExtensionType Int No For an update hold request, the extension type must be a 20 (TransferRequestExtensionData).
Data Object No This must be an extension data object of type DtoTransferRequestExtensionData
DtoTransferRequestExtensionData
Property Type Nullable Description
SysHoldRequestID Int No No
BibliographicRecordID Int Yes Both BibliographicRecordID and ItemRecordID cannot be null
ItemRecordID Int Yes Only required if it is an item-level request.
IgnorePatronBlocksPrompt Boolean Yes Set to true if the caller has already checked patron blocks.
BulkMode Boolean No When set to true, checking serial multipart steps are skipped.
IgnorePromptForMaterialTypeIDs List of Integers No Used only if 'BulkMode' is set true. The caller may choose to provide a list of material type IDs that may be ignored on future placing hold request (within this patron's holds session). This basically allows them to only display the material exceeded prompt a single time for each material type that is exceeded. The bib record primary MARCTOM ID is returned in the prompt message's extension data. WorkflowPromptID 100. The caller should store the ID for use in this list.

Hold Request Request body

application/json, text/json 
{
    "WorkflowRequestType":24,
    "TxnBranchID":"5",
    "TxnUserID":"1",
    "TxnWorkstationID":"1237",
    "WorkflowReplies":null,
    "RequestExtension":
    {
        "WorkflowRequestExtensionType":20,
        "Data":
        {
            "SysHoldRequestID":829526,
            "BibliographicRecordID":343351,
            "ItemRecordID":9348637
        }
    }
}

Response Information

Example - Patron blocks response

Summary data for the list of patron blocks will be returned in the PatronBlocks and LinkedPatronBlocks properties. They can be displayed to the user for acknowlegment or bypass.

application/json, text/json 
{
    "WorkflowRequestType":24,
    "TxnBranchID":"5",
    "TxnUserID":"1",
    "TxnWorkstationID":"1237",
    "WorkflowReplies":null,
    "RequestExtension":
    {
        "WorkflowRequestExtensionType":20,
        "Data":
            {
            "SysHoldRequestID":829526,
            "BibliographicRecordID":343351,
            "ItemRecordID":9348637
        }
    },
    "WorkflowRequestGuid":"b559184b-4912-4d9f-83ce-96c1fb95d1e8",
    "WorkflowStatus":-3,
    "Prompt":
    {
    "WorkflowPromptID":96,
    "Name":null,"Description":null,
    "WorkflowPromptType":3,
    "WorkflowPromptOptions":6,
    "DefaultPromptOption":0,
    "Title":"Patron is blocked (Argyle Custom)",
    "Message":"Do you want to continue with this operation?",
    "AlternateMessage":"",
    "AlternateYesText":"",
    "AlternateNoText":"",
    "AlternateCancelText":"",
    "AlternateContinueText":"",
    "PromptExtension":
    {
    "WorkflowPromptExtensionType":8,
    "Data":
    {
    "HeldItemBlock":false,
    "FirstLevelFineBlock":false,
    "UnreadMessageBlock":false,
    "SecondLevelFineBlock":false,
    "OverdueItemBlock":true,
    "ClaimLimitBlock":true,
    "BlockingNoteBlock":false,
    "CollectionAgencyBlock":false,
    "PatronSystemBlock":false,"LibraryAssignedBlock":true,
    "FreeTextBlock":false,"AssociatedPatronBlock":false,"OverrideRequestBlocksPermitted":false,
    "PatronBlocks":
    [
    {
    "PatronID":358502,
    "PatronFullName":"ramaraos, Test",
    "BlockType":3,
    "BlockID":103,
    "BlockDescription":"Total overdue items: 7",
    "PatronBranchID":3,
    "CreationDate":null
    },
    ],
    "LinkedPatronBlocks":[]}}},
    "InformationMessages":[],
    "AnswerExtension":null,
    "CircTranType":0,"ReceiptType":0,
    "ReceiptUrl":"",
    "FineEReceiptSent":false,
    "LinkToItem":false,
    "NoDefaultButton":false,
    "HighlightedInstruction":"Do you want to continue with this operation?",
    "Message":"",
    "id":"b559184b-4912-4d9f-83ce-96c1fb95d1e8",
    "WorkflowPromptID":96,
    "WorkflowPromptResult":5,
    "ReplyValue":null,
    "ReplyExtension":null
}
Example - Exceeded total request limit
application/json, text/json 
{
    "WorkflowRequestGuid":"cdb2461d-d9d9-43f3-bada-36fa1c269f23",
    "WorkflowRequestType":24,
    "WorkflowStatus":-3,
    "Prompt":
    {
        "WorkflowPromptID":68,
        "Name":null,
        "Description":null,"WorkflowPromptType":1,
        "WorkflowPromptOptions":6,
        "DefaultPromptOption":4,
        "Title":"Exceeded total request limit",
        "Message":"Patron (వనజ Ramaraos) has exceeded the maximum number of requests permitted.

Title:  Eileen [electronic resource] : A Novel

Do you want to place this request?",
        "AlternateYesText":"",
        "AlternateNoText":"",
        "AlternateCancelText":"",
        "AlternateContinueText":"",
        "PromptExtension":null
    },
    "InformationMessages":[],
    "AnswerExtension":null,
    "CircTranType":0,
    "ReceiptType":0,
    "ReceiptUrl":"",
    "FineEReceiptSent":false
}
Example - Material type limit reached
A list of material types affected is returned in the MaxHoldMaterialTypes field.
application/json, text/json 
{
    "WorkflowRequestGuid":"4b31805a-06d9-430a-95ce-404ebfbeddb1",
    "WorkflowRequestType":24,
    "WorkflowStatus":-3,
    "Prompt":
    {
        "WorkflowPromptID":21,
        "Name":null,
        "Description":null,
        "WorkflowPromptType":1,"WorkflowPromptOptions":6,
        "DefaultPromptOption":0,
        "Title":"Exceeded material type request limit","Message":"Patron (వనజ Ramaraos) has exceeded request limit for the title.
Title:  Harry Potter and the sorcerer's stone

Patron has made 20 of 5 requests permitted for material type Book.
Do you want to place this request?",
        "AlternateMessage":"",
        "AlternateYesText":"",
        "AlternateNoText":"",
        "AlternateCancelText":"",
        "AlternateContinueText":"",
        "PromptExtension":
        {
            "WorkflowPromptExtensionType":34,
            "Data":
            {
                MaxHoldMaterialTypes:[1]
            } 
        }   
    },
    "InformationMessages":[],
    "AnswerExtension":null,
    "CircTranType":0,
    "ReceiptType":0,
    "ReceiptUrl":"",
    "FineEReceiptSent":false
}
Example - Title is blocked
application/json, text/json 
{
"WorkflowRequestGuid":"cdb2461d-d9d9-43f3-bada-36fa1c269f23",
"WorkflowRequestType":24,
"WorkflowStatus":-3,
"Prompt":
{
    "WorkflowPromptID":89,
    "Name":null,
    "Description":null,
    "WorkflowPromptType":1,
    "WorkflowPromptOptions":6,
    "DefaultPromptOption":5,
    "Title":"Title is blocked",
    "Message":"Title: Eileen [electronic resource] : A Novel

All items are restricted from filling this request.

Do you want to place this request?",
    "AlternateYesText":"",
    "AlternateNoText":"",
    "AlternateCancelText":"",
    "AlternateContinueText":"",
    "PromptExtension":null
},
"InformationMessages":[],
"AnswerExtension":null,
"CircTranType":0,
"ReceiptType":0,
"ReceiptUrl":"",
"FineEReceiptSent":false
}
Example - Bib Serial multipart answer

A list of unique designation strings will be returned in the DesignationsOrVolumes attribute. They can be displayed to the user for selection or bypass. SA "Manage Item Requests" option (REQPARM_ITEM_REQUESTS_FROM_PAC) is set to 2 (Limit item requests to first available copy). SA "Limit item requests to first available copy" option (REQPARM_SERIAL_MULTIPART_REQ) set to 0 (Allow requests on serials in PAC and Staff Client) or 2 (Both).

application/json, text/json 
{
    "WorkflowRequestGuid":"c4571e09-274b-4d91-8caf-14ccd6929c03",
    "WorkflowRequestType":24,
    "WorkflowStatus":-3,
    "Prompt":
    {
        "WorkflowPromptID":93,
        "Name":null,
        "Description":null,
        "WorkflowPromptType":32,
        "WorkflowPromptOptions":6,
        "DefaultPromptOption":4,
        "Title":"Serial/Multi Volume Holds",
        "Message":"You have selected a serial or multi-part title. A request placed on the title will trap any available item.\nWould you like to:",
        "AlternateMessage":"",
        "AlternateYesText":"",
        "AlternateNoText":"",
        "AlternateCancelText":"",
        "AlternateContinueText":"",
        "PromptExtension":
        {
            "WorkflowPromptExtensionType":33,
            "Data":
            {
                "ItemRecordCount":0,
                "DesignationsOrVolumes":
                [
                    "Vol. 18  (Dec. 2009)",
                    "Vol. 15  (Sep. 2009)",
                    "Vol. 12  (June 2009)",
                    "Vol. 11  (May 2009)",
                    "Vol. 10  (Apr. 2009)",
                    "Vol. 9  (Mar. 2009)",
                    "Vol. 8  (Feb. 2009)","Vol. 7  (Jan. 2009)",
                    "Vol. 6  (Dec. 2008)","Vol. 5  (Nov. 2008)",
                    "Vol. 4  (Oct. 2008)","Vol. 3  (Sep. 2008)",
                    "Vol. 2  (Aug. 2008)","Vol. 1  (July 2008)"
                ],
                "IsDesignation":true
              }
        }
    },
    "InformationMessages":[],
        "AnswerExtension":null,
        "CircTranType":0,
        "ReceiptType":0,
        "ReceiptUrl":"",
        "FineEReceiptSent":false
    }
}
Two possible options available for Bib Serial multipart reply.
  • 1. Request any item (bib-level request):
    Example DtoWorkflowReply: 
    {
    "WorkflowPromptID": 93,
    "WorkflowPromptResult": 24,
    "ReplyValue": null,
    "ReplyExtension": {
        "WorkflowReplyExtensionType": 20,
        "Data": {
            "BibLevelOption": 1,
            "IsDesignation": false
        }
    }
}
  • 2. Request the first available copy of one of the listed items.
    Example DtoWorkflowReply: 
    {
    "WorkflowPromptID": 93,
    "WorkflowPromptResult": 5,
    "ReplyValue": null,
    "ReplyExtension": {
        "WorkflowReplyExtensionType": 20,
        "Data": {
            "FirstAvailableOption": 1,
            "DesignationOrVolume": "JV",
            "IsDesignation": true
        }
    }
}
Example - Bib Serial answer

This bibliographic record is a serial and the SA "Manage Item Requests" option (REQPARM_ITEM_REQUESTS_FROM_PAC) is set to 1 (Allow item requests from PAC).

application/json, text/json 
{
  "WorkflowRequestGuid": "c07ba982-b123-48df-99fb-e9b03cd82dab",
  "WorkflowRequestType":24,
  "WorkflowStatus": -3,
  "Prompt": {
    "WorkflowPromptID": 94,
    "Name": null,
    "Description": null,
    "WorkflowPromptType": 33,
    "WorkflowPromptOptions": 6,
    "DefaultPromptOption": 4,
    "Title": "Serial Holds",
    "Message": "You have selected a serial title. A request placed on the title will trap any available item.\nSelect one of the following:",
    "AlternateMessage": "",
    "AlternateYesText": "",
    "AlternateNoText": "",
    "AlternateCancelText": "",
    "AlternateContinueText": "",
    "PromptExtension": {
      "WorkflowPromptExtensionType": 33,
      "Data": {
        "ItemRecordCount": 0,
        "DesignationsOrVolumes": [
          "Vol. 18  (Dec. 2009)",
          "Vol. 15  (Sep. 2009)",
          "Vol. 12  (June 2009)",
          "Vol. 11  (May 2009)",
          "Vol. 10  (Apr. 2009)",
          "Vol. 9  (Mar. 2009)",
          "Vol. 8  (Feb. 2009)",
          "Vol. 7  (Jan. 2009)",
          "Vol. 6  (Dec. 2008)",
          "Vol. 5  (Nov. 2008)",
          "Vol. 4  (Oct. 2008)",
          "Vol. 3  (Sep. 2008)",
          "Vol. 2  (Aug. 2008)",
          "Vol. 1  (July 2008)"
        ],
        "IsDesignation": true
      }
    }
  },
  "InformationMessages": [],
  "AnswerExtension": null,
  "CircTranType": 0,
  "ReceiptType": 0,
  "ReceiptUrl": "",
  "FineEReceiptSent": false
}
Two possible options available for Bib Serial reply.
  • 1. Request any available item (bib-level request):
    Example DtoWorkflowReply: 
    {
    "WorkflowPromptID": 94,
    "WorkflowPromptResult": 5,
    "ReplyValue": null,
    "ReplyExtension": {
        "WorkflowReplyExtensionType": 20,
        "Data": {
            "BibLevelOption": 1,
            "IsDesignation": false
        }
    }
}
  • 2. Request a specific item and submit a new item level hold request.
Example - Serial Item Promote to Bib Request Answer

This item level request is for a serial. Provide the caller with the option to promote this request to a bib-level request.

application/json, text/json 
{
  "WorkflowRequestGuid": "c07ba982-b123-48df-99fb-e9b03cd82dab",
  "WorkflowRequestType":24,
  "WorkflowStatus": -3,
  "Prompt": {
    "WorkflowPromptID": 88,
    "Name": null,
    "Description": null,
    "WorkflowPromptType": 27,
    "WorkflowPromptOptions": 6,
    "DefaultPromptOption": 4,
    "Title": "Serial Holds",
    "Message": "You have selected a serial title. A request placed on the title will trap any available item.\nSelect one of the following:",
    "AlternateMessage": "",
    "AlternateYesText": "",
    "AlternateNoText": "",
    "AlternateCancelText": "",
    "AlternateContinueText": "",
    "PromptExtension": {
      "WorkflowPromptExtensionType": 33,
      "Data": {
        "ItemRecordCount": 0,
        "DesignationsOrVolumes": [
          "Vol. 18  (Dec. 2009)",
          "Vol. 15  (Sep. 2009)",
          "Vol. 12  (June 2009)",
          "Vol. 11  (May 2009)",
          "Vol. 10  (Apr. 2009)",
          "Vol. 9  (Mar. 2009)",
          "Vol. 8  (Feb. 2009)",
          "Vol. 7  (Jan. 2009)",
          "Vol. 6  (Dec. 2008)",
          "Vol. 5  (Nov. 2008)",
          "Vol. 4  (Oct. 2008)",
          "Vol. 3  (Sep. 2008)",
          "Vol. 2  (Aug. 2008)",
          "Vol. 1  (July 2008)"
        ],
        "IsDesignation": true
      }
    }
  },
  "InformationMessages": [],
  "AnswerExtension": null,
  "CircTranType": 0,
  "ReceiptType": 0,
  "ReceiptUrl": "",
  "FineEReceiptSent": false
}
Two possible options available for Bib Serial reply.
  • 1. This item only:
    Example DtoWorkflowReply: 
    {
    "WorkflowPromptID": 88,
    "WorkflowPromptResult": 5,
    "ReplyValue": null,
    "ReplyExtension": {
        "WorkflowReplyExtensionType": 20,
        "Data": {
            "BibLevelOption": 0
        }
    }
}
  • 2. First available copy.
    Example DtoWorkflowReply: 
    {
    "WorkflowPromptID": 88,
    "WorkflowPromptResult": 5,
    "ReplyValue": null,
    "ReplyExtension": {
        "WorkflowReplyExtensionType": 20,
        "Data": {
            "BibLevelOption": 1
        }
    }
}
Example -Duplicate hold exists

Summary data for the list of duplicate hold requests will be returned in the DuplicateHolds attribute. They can be displayed to the user for acknowlegment or bypass.

application/json, text/json 
{   
    "WorkflowRequestGuid":"cdb2461d-d9d9-43f3-bada-36fa1c269f23",
    "WorkflowRequestType":24,
    "WorkflowStatus":-3,
    "Prompt":
    {
        "WorkflowPromptID":77,
        "Name":null,
        "Description":null,
        "WorkflowPromptType":19,
        "WorkflowPromptOptions":6,
        "DefaultPromptOption":4,
        "Title":"Duplicate Hold requests exist",
        "Message":null,
        "AlternateYesText":"",
        "AlternateNoText":"",
        "AlternateCancelText":"",
        "AlternateContinueText":"",
        "PromptExtension":
        {
            "WorkflowPromptExtensionType":31,
            "Data":
            {
                "DuplicateHolds":
                [
                    {
                        "SysHoldRequestID":0,
                        "BrowseAuthor":"Moshfegh, Ottessa.",
                        "BrowseTitle":"Eileen [electronic resource] : A Novel",
                        "FormatDescription":"Ebook",
                        "CreationDate":"2018-04-30T12:01:06.173-04:00",
                        "PickupBranch":"Amsterdam Free Library",
                        "PickupBranchID":3
                    },            
                    {
                        "SysHoldRequestID":0,
                        "BrowseAuthor":"Moshfegh, Ottessa.",
                        "BrowseTitle":"Eileen [electronic resource] : A Novel",
                        "FormatDescription":"Ebook",
                        "CreationDate":"2018-04-30T14:24:42.527-04:00",
                        "PickupBranch":"Amsterdam Free Library",
                        "PickupBranchID":3
                    }
                ]
            }
        }
    },
    "InformationMessages":[],
    "AnswerExtension":null,
    "CircTranType":0,
    "ReceiptType":0,
    "ReceiptUrl":"",
    "FineEReceiptSent":false
}

Hold request Transfer Response Information

Example: DtoWorkflowAnswer - Transfer hold request successful
application/json, text/json 
{
    "WorkflowRequestGuid":"b559184b-4912-4d9f-83ce-96c1fb95d1e8",
    "WorkflowRequestType":24,
    "WorkflowStatus":1,
    "Prompt":null,
    "InformationMessages":[{"Type":1,"Title":"","Message":"hold transferred successfully"}],
    "AnswerExtension":null,
    "CircTranType":0,
    "ReceiptType":0,
    "ReceiptUrl":"",
    "FineEReceiptSent":false
}

HTTP Response Codes

Code Description
200 OK. Check for WorkflowStatus, continue until process is complete.
400

FAILURE due to invalid input or data validation.
409 CONFLICT. Patron record is secured.

Required Permissions

Permission IDs found here.

    CR_HoldRequests_Modify