scriptotek / php-alma-client Goto Github PK

The "Get Lending Requests" API returns max 100 results, but do not support pagination (limit and offset parameters). Should report this upstream.

XmlImporter will trigger an error while reading xml depending on the version of Alma.
Alma might return an XML document in the wrong encoding, encoding in XML file is said to be UTF-16 but actually it is UTF-8.
A solution is to catch this error, then change the encoding in the XML using a preg_replace from UTF-16 to UTF-8 and then parse the XML file.

See attached XMLImporter file
XmlImporter.php.zip

curl -X GET --header 'Accept: application/json; charset=utf-8' --header 'Authorization: apikey {key}' 'https://api-eu.hosted.exlibrisgroup.com/almaws/v1/users?limit=5&[email protected]' | jq '.'

gives "total_record_count": 5, but only 3 records are returned. Anonymized response:

{
  "user": [
    {
      "primary_id": "li",
      "first_name": "Li",
      "last_name": "Aker",
      "gender": {
        "value": "FEMALE",
        "desc": "Female"
      },
      "password": "",
      "status": {
        "value": "ACTIVE",
        "desc": "Active"
      },
      "requests": null,
      "loans": null,
      "fees": null,
      "link": "https://api-eu.hosted.exlibrisgroup.com/almaws/v1/users/li"
    },
    {
      "primary_id": "n003548402",
      "first_name": "Stein",
      "last_name": "Gal",
      "gender": {
        "value": "",
        "desc": ""
      },
      "password": "",
      "status": {
        "value": "ACTIVE",
        "desc": "Active"
      },
      "requests": null,
      "loans": null,
      "fees": null,
      "link": "https://api-eu.hosted.exlibrisgroup.com/almaws/v1/users/n003548402"
    },
    {
      "primary_id": "N003548424",
      "first_name": "Sol",
      "last_name": "Storm",
      "gender": {
        "value": "",
        "desc": ""
      },
      "password": "",
      "status": {
        "value": "ACTIVE",
        "desc": "Active"
      },
      "requests": null,
      "loans": null,
      "fees": null,
      "link": "https://api-eu.hosted.exlibrisgroup.com/almaws/v1/users/N003548424"
    }
  ],
  "total_record_count": 5
}

Today's surprise: The Alma users API can return users without any identifiers! 😲 Within the normal Alma GUI these are shown as "contacts".

Another weird thing is that the primary_id field is not something like null, but a not very machine-friendly string: "no primary id (123456789023)". Here's a full (anonymized) response example:

    {
      "primary_id": "no primary id (123456789023)",
      "first_name": "Hans",
      "last_name": "Jonas",
      "gender": {
        "value": "",
        "desc": ""
      },
      "status": {
        "value": "ACTIVE",
        "desc": "Active"
      },
      "requests": null,
      "loans": null,
      "fees": null,
      "link": "https://api-eu.hosted.exlibrisgroup.com/almaws/v1/users/-"
    }

Also notice that the link field is also not null, but an invalid URL that can not be dereferenced.

SimplePaginatedList->limit is a protected property with a default value of 10 and no setter:

Legitimate values, for endpoints supporting the limit parameter, are 0 - 100.

Support GET of conf/code-tables:

https://developers.exlibrisgroup.com/alma/apis/docs/conf/R0VUIC9hbG1hd3MvdjEvY29uZi9jb2RlLXRhYmxlcy97Y29kZVRhYmxlTmFtZX0=/

Retrieve jobs and submit a job via the conf/jobs endpoint.

https://developers.exlibrisgroup.com/alma/apis/conf/

Following documentation of Alma API at
https://developers.exlibrisgroup.com/alma/apis/#lang

Language Support
By default all APIs return error messages and textual information in English. To run an API with another language include the ‘lang’ parameter with a 2 letter code of the language. E.g. for French: ...&lang=fr. Note that only languages which are enabled in Alma can be used (according to ‘Institution Languages’ mapping-table).

Adding this "extra parameter" to AlmaClient can make easier to handle multiple language instances.

I solved the issue for the moment extending AlmaClient:

class LocalizedAlmaClient extends  AlmaClient {
  
    public $lang;

    public function __construct(
        $key = null,
        $region = 'eu',
        $lang = 'en',
        $zone = Zones::INSTITUTION,
        HttpClientInterface $http = null,
        RequestFactoryInterface $requestFactory = null,
        UriFactoryInterface $uriFactory = null
    ) {
        $this->lang = $lang;
        parent::__construct($key,$region,$zone,$http,$requestFactory,$uriFactory);
    }

    public function buildUrl($url, $query = [])
    {
        $url = explode('?', $url, 2);
        if (count($url) == 2) {
            parse_str($url[1], $query0);
            $query = array_merge($query0, $query);
        }
        $query['apikey'] = $this->key;
        $query['lang'] = $this->lang;

        $url = $url[0];

        if (strpos($url, $this->baseUrl) === false) {
            $url = $this->baseUrl . $url;
        }

        return $this->uriFactory->createUri($url)
            ->withQuery(http_build_query($query));
    }
}

Love this client SDK so far, but I need to be able to perform an update to the User. I've forked the client and plan to add this feature locally and then via pull request.

Do y'all have any preferences/requirements as to how this is implemented?

I'm up for adding dedicated helper methods ala $bib->record->appendField(), or just adding support via the Users class to update( $identifier, $json ) or update( $identifier, $User) or store( $User ).

In particular, we will immediately be targeting updating Addresses and Fines/Fees.

@danmichaelo ?

With no further explanation, but seems to indicate unsupported queries. For instance, while AND is supported, querying the same field twice doesn't seem to work:

curl -X GET --header 'Accept: application/json; charset=utf-8' --header 'Authorization: apikey l7xx53d521c9cb214131913a31ac5c4cbd29' 'https://api-eu.hosted.exlibrisgroup.com/almaws/v1/users?limit=5&q=primary_id~dan%20ANDprimary_id~michael' | jq '.'

gives

{
  "total_record_count": -1
}

We're using lazy loading e.g. in in Bib::getRecord. Perhaps the implementation could benefit from using ProxyManager.