---
name: "WebService::ILS::OverDrive::Patron"
section: "3pm"
platform: "linux"
package: "libwebservice-ils-perl"
version: "0.18-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/WebService::ILS::OverDrive::Patron"
---

# WebService::ILS::OverDrive::Patron(3pm)

WebService::ILS module for OverDrive circulation services

## NAME

WebService::ILS::OverDrive::Patron - WebService::ILS module for OverDrive circulation services

## SYNOPSIS

```
    use WebService::ILS::OverDrive::Patron;
```

## DESCRIPTION

These services require individual user credentials. See "WebService::ILS INDIVIDUAL USER AUTHENTICATION AND METHODS"

See WebService::ILS::OverDrive

## CONSTRUCTOR

### new (%params\_hash or $params\_hashref)

*Additional constructor params:*

- "auth\_token" =\> auth token as previously obtained

  ## INDIVIDUAL USER AUTHENTICATION METHODS

### auth\_by\_user\_id ($user\_id, $password, $website\_id, $authorization\_name)

`"website_id"` and `"authorization_name"` (domain) are provided by OverDrive

*Returns (access\_token, access\_token\_type) or access\_token*

### Authentication at OverDrive - Granted or "3-Legged" Authorization

With OverDrive there's an extra step - an auth code is returned to the redirect back handler that needs to make an API call to convert it into a auth token.

An example:

```
    my $overdrive = WebService::ILS::OverDrive::Patron({
        client_id => $client_id,
        client_secret => $client_secret,
        library_id => $library_id,
    });
    my $redirect_url = $overdrive->auth_url("http://myapp.com/overdrive-auth");
    $response->redirect($redirect_url);
    ...
    /overdrive-auth handler:
    my $auth_code = $req->param( $overdrive->auth_code_param_name )
        or some_error_handling(), return;
    # my $state = $req->param( $overdrive->state_token_param_name )...
    local $@;
    eval { $overdrive->auth_by_code( $auth_code ) };
    if ($@) { some_error_handling(); return; }
    $session{overdrive_access_token} = $access_token;
    $session{overdrive_access_token_type} = $access_token_type;
    $session{overdrive_auth_token} = $auth_token;
    ...
    Somewhere else in your app:
    my $ils = WebService::ILS::Provider({
        client_id => $client_id,
        client_secret => $client_secret,
        access_token => $session{overdrive_access_token},
        access_token_type => $session{overdrive_access_token_type},
        auth_token = $session{overdrive_auth_token}
    });
    my $checkouts = $overdrive->checkouts;
```

### auth\_url ($redirect\_uri, $state\_token)

*Input params:*

- "redirect\_uri" =\> return url which will handle redirect back after auth

  - "state\_token" =\> a token that is returned back unchanged;

  for additional security; not required

### auth\_code\_param\_name ()

### state\_token\_param\_name ()

### auth\_by\_code ($provider\_code, $redirect\_uri)

*Returns (access\_token, access\_token\_type, auth\_token) or access\_token*

### auth\_by\_token ($provider\_token)

*Returns (access\_token, access\_token\_type, auth\_token) or access\_token*

## CIRCULATION METHOD SPECIFICS

Differences to general WebService::ILS interface

### place\_hold ($item\_id, $notification\_email\_address, $auto\_checkout)

`$notification_email_address` and `$auto_checkout` are optional. `$auto_checkout` defaults to false.

*Returns holds item record*

It is preferred that the `$notification_email_address` is specified.

If `$auto_checkout` is set to true, the item will be checked out as soon as it becomes available.

### checkouts ()

For formats see `"checkout_formats()"` below

### checkout ($item\_id, $format, $allow\_multiple\_format\_checkouts)

`$format` and `$allow_multiple_format_checkouts` are optional. `$allow_multiple_format_checkouts` defaults to false.

*Returns checkout item record*

An item can be available in multiple formats. Checkout is complete only when the format is specified.

Checkout can be actioned without format being specified. In that case an early return can be actioned. To complete checkout format must be locked later (see **lock\_format()** below). That would be the case with **place\_hold()** with `$auto_checkout` set to true. Once format is locked, an early return is not possible.

If `$allow_multiple_format_checkouts` flag is set to true, multiple formats of the same item can be acioned. If it is false (default) and the item was already checked out, the checked out item record will be returned regardless of the format.

Checkout record will have an extra field `"format"` if format is locked in.

### checkout\_formats ($item\_id)

*Returns a hashref of available title formats and immediate availability*

```
  { format => available, ... }
```

If format is not immediately available it must be locked first

### lock\_format ($item\_id, $format)

*Returns locked format (should be the same as the input value)*

### checkout\_download\_url ($item\_id, $format, $error\_url, $success\_url)

*Returns OverDrive download url*

Checked out items must be downloaded by users on the OverDrive site. This method returns the url where the user should be sent to (redirected). Once the download is complete, user will be redirected back to `$error_url` in case of an error, otherwise to optional `$success_url` if specified.

See \<https://developer.overdrive.com/apis/download\>

## NATIVE METHODS

### native\_patron ()

See \<https://developer.overdrive.com/apis/patron-information\>

### native\_holds ()

### native\_place\_hold ($item\_id, $notification\_email\_address, $auto\_checkout)

See \<https://developer.overdrive.com/apis/holds\>

### native\_checkouts ()

### native\_checkout\_info ($item\_id)

### native\_checkout ($item\_id, $format, $allow\_multiple\_format\_checkouts)

### native\_checkout\_formats ($item\_id)

### native\_lock\_format ($item\_id, $format)

See \<https://developer.overdrive.com/apis/checkouts\>

## LICENSE

Copyright (C) Catalyst IT NZ Ltd Copyright (C) Bywater Solutions

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

## AUTHOR

Srdjan JankoviX \<srdjan@catalyst.net.nz\>