Project

General

Profile

Bug #3245

Visning af materialegruppens beskrivelse

Added by Steen Larsen over 1 year ago. Updated about 1 year ago.

Status:
Needs analysis
Priority:
High
Assignee:
Target version:
Estimated time:
URL med eksempel:
Kategorier:
Søgning - Materialevisning

Description

Med FBS-API (version 28042017) for beholdning er det muligt at vise materialegruppens beskrivelse istedet for navnet.

I den nuværende løsning kan man få vist navnet (der står dog noget andet i hjælpeteksten) men beskrivelsen vil give mere mening.
Det svarer til de øvrige profiler (filial/afdeling/opstilling/delopstilling) hvor det ikke er koden der vises.
Den eksisterende løsning konfigureres her: /admin/config/ting/holdings - Show material group description

Eksempel på svar fra FBSAPI (redigeret)

"materials" : [
   {
      "available" : false,
      "itemNumber" : "...",
      "materialGroup" : {
         "description" : "Std. materialegruppe",
         "name" : "standard"
      },
      "periodical" : null
   },
   {
      "available" : true,
      "itemNumber" : "...",
      "materialGroup" : {
         "description" : "",
         "name" : "test"
      },
      "periodical" : null
   },
   {
      "available" : true,
      "itemNumber" : "...",
      "materialGroup" : {
         "description" : "7 dages lån",
         "name" : "7dag-"
      },
      "periodical" : {
      ...
      }
   }
],

Her er også vist en materialegruppe "test" hvor beskrivelsen er tom.

For at være bagudkompatibel med den eksisterende løsning kunne man tilbyde et valg mellem de to: name / description

Beskrivelsen ("Description") for materialegruppen kan rettes i FBS Admin hvis det giver mere mening i beholdningslinjerne der skal vises.
Når man retter beskrivelsen i FBS Admin ser det ikke ud til, at der bliver sendt opdateringer til brønden (heller ikke forsinket) og det er ok,
da det er navnet som indekseres i holdingsitem.circulationRule. Beskrivelsen benyttes ikke i brønden.

 

For at løse sagen skal version 3 af holdings benyttes (/catalog/holdings/v3) og man skal have fat i den tilhørende swagger - hvilket måske giver nogle andre udfordringer jvf #2530

History

#1 Updated by Rolf Madsen over 1 year ago

  • Status changed from New to Need more info
  • Assignee set to Simon Holt
  • Target version set to DDB CMS - Analyse og prioritering udestår

@Simon, har du en holding til det?

#2 Updated by Simon Holt over 1 year ago

Jeg synes det lyder som en rigtig god forbedring. Beskrivelsen for material group kan bruges til at lave et element i opstillingen, der giver mere mening for brugerne.

Det er rigtig som Steen skriver, at vi skal have genereret den nye swagger, da jeg kan se at MaterialGroup i hvert fald mangler.

#3 Updated by Rolf Madsen over 1 year ago

  • Status changed from Need more info to Ready for development
  • Target version changed from DDB CMS - Analyse og prioritering udestår to Release 29-2 - Bugfixes (7.x-4.5.0)

#4 Updated by Gitte Barlach over 1 year ago

  • Priority changed from Normal to High

#5 Updated by Rolf Madsen over 1 year ago

  • Target version changed from Release 29-2 - Bugfixes (7.x-4.5.0) to Release 29-2 - Bugfixes (Vejle)

#6 Updated by Simon Holt over 1 year ago

https://github.com/ding2/ding2/pull/1082

Jeg kommer lige med noget yderligere forklaring af rettelserne, tests osv.. Det er en større ændring, da det krævede opdatering API kode + jsonmapper.

#7 Updated by Simon Holt over 1 year ago

For at få adgang til materialGroup var jeg nødt til at bruge version 3 af FBS holdings API, som Steen også pointerer. På nuværende tidspunkt anvender vi version 3, men den returnerer kun materialGroup navn og ikke en reference til et materialGroup objekt.

Jeg brugte derfor Prancer (https://github.com/reload/prancer) til at generere ny API kode ud fra den seneste specifikation af FBS API (08-03-2018). Hentet herfra: http://fbsudrulning.dk/vejledninger/#/Ops%C3%A6tning?id=44

Efter dette virkede integrationen med FBS ikke (jeg kunne ikke engang logge ind), og fandt ud af, at det var nødvendigt også at opdatere jsonmapper (til v1.4.0).

Herefter kunne jeg igen logge ind og reservere osv.

API-ændringer - Test

Den er ret vigtig at få testet denne her, da den opdatererer en del af den kode, der bruges til kommunikationen med FBS.

Så med udgangpunkt i de ændringer der er lavet i API'et, har jeg i nedenstående prøvet at teste relateret funktionalitet i DDB CMS.

1. getAvailability: /external/v2/{agencyid}/catalog/availability -> /external/{agencyid}/catalog/availability/v3

Test: Den her ser ikke ud til at blive brugt mere. Den eneste mulighed for at den bliver kaldt, som jeg kan finde, er hvis feltet ting_collection_types bruger formatteren ding_availability_with_labels (Availability information with labels). Men feltet bliver ikke engang brugt mere ting_collection hverken i standard eller smagsprøve viewmode. Selv om ting_object bruger formatteren "With availability information" på feltet ting_type i flere views modes, ser det ikke ud til at resultere i et kald getAvialability. Jeg har ikke fundet andre steder i systemet, så derfor:

Godkendt!

2. getHoldings: /external/v2/{agencyid}/catalog/holdings -> /external/{agencyid}/catalog/holdings/v3

Bliver brugt ved materialevisning til at vise "almindelig" holdings og til at vise teksten "Vi har X eksemplar(er). Der er Y reserveringer på materialet."

Bliver brugt ved visning af periodikum til at vise "specielle" holdings for disse.

a. Der vises korrekt beholdning ved materialevisning. Godkendt!

b. Der vises korrekt antal eksemplarer og reserveringer i teksten "Vi har X eksemplarer. Der er Y reserveringer på materialet." Godkendt!

c. Der vises korrekt beholdning ved periodikum Godkendt!

3. getLoans: /external/v1/{agencyid}/patrons/{patronid}/loans -> /external/{agencyid}/patrons/{patronid}/loans/v2

a. Lån/overskredne lån vises korrekt. Godkendt!

4. renewLoans: /external/v1/{agencyid}/patrons/{patronid}/loans/renew -> /external/{agencyid}/patrons/{patronid}/loans/renew/v2

a. Forny enkelt lån: Lånet fornyes og afleveringsdato opdateres korrekt. Godkendt!

b. Forny alle: Lånene fornyes og afleveringsdatoer opdateres korrekt. Godkendt!

5. payFees

a. Mellemværender vises korrekt Godkendt!

b. Mellemværender kan betales. Test af både "Betal valgte" og "Betal alle". Godkendt!

Ændringer i datamodel

Jeg har kigget alle de ændrede klasser igennem og har fundet følgende ændringer i modellen:

- Ny model MaterialGroup er tilføjet

- LoanDetails peger nu på en MaterialGroup (objekt) i stedet for et MaterialGroupName

- Material peger nu på en MaterialGroup (objekt) i stedet for et MaterialGroupName

- $coAddress ændret til $secondaryAddress i Patron-model

- $preferredLanguage tilføjet i PatronSettings model

Tilføjelse af null-værdier

Derudover er der, i kræft i JSONMapper opdatering, tilføjet mulighed for null i en række af data modellerne:

- AuthenticatedPatron.php: $patron

- Booking.php: $note

- BookingResponse.php: $booking

- CreateBooking.php: $note

- CreateReservation.php: $expiryDate, $pickupBranch, $periodical

- Fee.php: $paidDate, $dueDate

- FeeMaterial.php: $periodical

- Fee.php: $paidDate, $dueDate

- Holdings.php: $location, $sublocation, $department

- ILLBibliographicRecord.php: $author, $isbn, $periodicalNumber, $edition, $language, $bibliographicCategory, $title, $publicationDateOfComponent, $recordId, $issn, $placeOfPublication, $mediumType, $periodicalVolume, $publisher, $publicationDate

- LoanDetails.php: $periodical, $ilBibliographicRecord

- Material.php: $periodical

- Patron.php: $birthday, $secondaryAddress, $preferredLanguage, $address, $onHold, $blockStatus, $emailAddress, $phoneNumber, $name, $allowBookings

- PaymentConfirmation.php: $confirmationId

- Period.php: $to, $from

- Periodical.php: $volume, $volumeYear, $volumeNumber

- PeriodicalReservation.php: $volume, $volumeYear, $volumeNumber

- ReservationDetails.php: $pickupDeadline, $periodical, $ilBibliographicRecord, $numberInQueue, $pickupNumber

- ReservationResult.php: $periodical, $reservationDetails

- UpdatePatronRequest.php: $patron, $pincodeChange

- UpdateReservation.php: $expiryDate, $pickupBranch

 

 

 

#8 Updated by Rolf Madsen over 1 year ago

  • Status changed from Ready for development to Development

#9 Updated by Simon Holt over 1 year ago

  • Status changed from Development to Needs design decision
  • Assignee changed from Simon Holt to Rolf Madsen

Nå men jeg faldt lige over denne kommentar fra Steen: https://platform.dandigbib.org/issues/2530#note-24 

Som jeg skriver ovenfor, er der tilføjet flere "nullable" properties til Patron.php. Men som Steen pointere mangler følgende:

  • preferredPickupBranch
  • postalCode
  • street
  • city
  • country

Det har den konsekvens, at hvis en låner f.eks. ikke har indstillet en tilhørsfilial i Cicero (preferredPickupBranch) fejler log-in, da preferredPickupBranch ikke må være null. Det samme med postalcode,street,city,country, der svarer til adresse-felterne i Cicero. Hvis der er tomme, fejler log-ind også. Sidstnævnte ser ikke ud til at være så kritisk: de udfyldes automatisk ved brugeroprettelse, og det ser ud til at disse felter er obligatoriske, når man opretter en låner i Cicero. Men tilhørsfilial er ikke obligatorisk.

@Steen er det stadig muligt at oprette en låner med tomme adresse-felter?

Det er vigtigt at FPS-API specifikationen er korrekt ift. hvad der potentielt kan være null. Ellers virker vores flow med automatisk generering af kode ikke.

Der er desværre svært at komme videre her fordi:

1. Vi kan ikke opdatere FBS API kode uden også at skulle opdatere JSON Mapper. 

2. Hvis vi opdaterer JSON Mapper kan nogle lånere ikke logge ind, hvis de f.eks. ikke har indstillet nogen tilhørsfilial.

Jeg kunne godt undersøge nærmere hvorfor vi ikke kan logge ind uden at opdatere JSON-mapper og se om vi kan finde en lappe-løsning.

Kan dette ikke lade sig gøre, er der desværre ikke andet at gøre end at få Systematic til opdatere FBS API specifikationen, så den stemmer overens med hvordan systemet rent faktisk opfører sig.

 

#10 Updated by Rolf Madsen over 1 year ago

  • preferredPickupBranch => obligatorisk
  • postalCode => Hentes fra CPR-registeret
  • street => Hentes fra CPR-registeret
  • city => Hentes fra CPR-registeret
  • country => Hentes fra CPR-registeret

IFS0002 CMS Integration Services

/external/{agencyid}/patrons/v3

[...]

Implementation Notes
When a patron doesn't have a patron account in the library system, but logs in using a trusted authentication source (e.g NemId), the patron
account can be created using this service. Name and address will be automatically fetched from CPR-Registry, and cannot be supplied by the
client.

[...]

CreatePatronRequestV3 {
cprNumber (string),
pincode (string),
patron (PatronSettingsV3)
}

PatronSettingsV3 {
emailAddress (string, optional): Required if patron should receive email notifications Existing email addresses are overwritten with this value If left empty existing email addresses are deleted,
preferredLanguage (string, optional): Language in which the patron prefers the communication with the library to take place If left empty default library language will be used,
phoneNumber (string, optional): Required if patron should receive SMS notifications Existing phonenumbers are overwritten with this value If left empty existing phonenumbers are deleted,
preferredPickupBranch (string): ISIL-number of preferred pickup branch,
onHold (Period, optional): If not set then the patron is not on hold,
receiveEmail (boolean),
receivePostalMail (boolean),
receiveSms (boolean)
}

Period {
from (string, optional): Open-ended if not set,
to (string, optional): Open-ended if not set
}

[...]

#11 Updated by Simon Holt over 1 year ago

Ja, preferredPickupBranch burde stå som optional også.

Men Steen skrev i den anden sag:

I første omgang havde mit lånerkort ikke defineret noget i adressefelterne for den sekundære adresse, så det fejlede. I anden omgang startede jeg med et blankt lånerkort med mindst muligt indtastet for at se hvilke felter der så dukkede op i fejlbeskeden.

Så derfor ville jeg lige høre ham om det stadig er muligt at oprette lånere uden noget i adressefelterne.

Alternativt, kunne vi vel også bare selv gøre preferredPickupBranch nullable i modellen for at komme videre. Men så skal vi huske det hver gang API-koden opdateres.

#12 Updated by Rolf Madsen over 1 year ago

Jeg gad godt vide hvordan det hængere sammen for brugere der har adresse- og navnebeskyttelse?

Der er måske tilsvarende værdier ala for navnet hvor værdien bliver sat til "navnet er beskyttet".

#13 Updated by Simon Holt over 1 year ago

Jeg har selv navnebeskyttelse og der er heldigvis ikke nogle problemer i dette tilfælde. Den indsætter nogle placeholder værdier:

- Navn: "Navnet er beskyttet"

- Adresse: "Adressen er beskyttet"

- Postnummer: "0000"

- By: "-"

#14 Updated by Simon Holt over 1 year ago

Lige for god ordens skyld: Det er Patron.php og ikke PatronSettings.php, der skal have nullable preferredPickupBranch.

PatronSettings.php bruges ved oprettelse/redigering af lånere og det er ikke den der er problemet. Det er den Patron FBS API returnerer ved autentificering.

#15 Updated by Steen Larsen over 1 year ago

Jeg har oprettet en låner med mindst mulig information. Krævede felter ved oprettelse er navn, adresse, postnummer og by. Jeg har derudover også indtastet lånerkortnummer og en pinkode. Resultatet fra API er dette (jeg har udeladt patronId)

 "patron" : {
    "address" : {
       "city" : "-",
       "coName" : null,
       "country" : "DK",
       "postalCode" : "-",
       "street" : "-"
    },
    "allowBookings" : false,
    "birthday" : null,
    "blockStatus" : null,
    "defaultInterestPeriod" : 180,
    "emailAddress" : null,
    "name" : "Testkort",
    "onHold" : null,
    "phoneNumber" : null,
    "preferredLanguage" : null,
    "preferredPickupBranch" : null,
    "receiveEmail" : false,
    "receivePostalMail" : false,
    "receiveSms" : false,
    "resident" : false,
    "secondaryAddress" : {
       "city" : null,
       "coName" : null,
       "country" : null,
       "postalCode" : null,
       "street" : null
    }
 }

De tomme adressefelter jeg tidligere har nævnt er felterne i den sekundære adresse som jeg ikke rørte ved oprettelse.
Hvis man tilføjer noget i felterne under den sekundære adresse eller i coName feltet i adressen og derefter sletter indholdet igen så ændres værdien fra null til den tomme streng. Kan være vigtigt i forbindelse med test.

Jeg prøvede også at oprette en låner manuelt men denne gang med mit CPR og funktionen "Hent information fra CPR" - der var ingen forskel mht hvilke felter der var null bortset fra at feltet birthday også blev udfyldt.

Jeg kan se i externalapidocs at f.eks. den sekundære adresse er af typen Address og denne består af 5 krævede felter ("country", "city", "street", "coName", "postalCode")
Opretter JSONmapper en værdi som den her

"secondaryAddress" : {
   "city" : null,
   "coName" : null,
   "country" : null,
   "postalCode" : "8000",
   "street" : null
}

på samme måde som

"secondaryAddress" : {
   "postalCode" : "8000"
}

for så skal det jo fejle (da de 4 felter jo mangler i sidstnævnte)

Jeg har ingen forslag til løsning - hack i swaggerapi er ikke rigtigt en god løsning jvf https://platform.dandigbib.org/issues/2530#note-29

 

#16 Updated by Rolf Madsen over 1 year ago

  • Status changed from Needs design decision to Need more info
  • Assignee changed from Rolf Madsen to Simon Holt

Er det her ved at udvikle sig til to issues?

  1. opdatering API kode + jsonmapper
  2. konfigurationsmuligheder med valg imellem name og description og visning i materialegruppe

#17 Updated by Simon Holt over 1 year ago

@Steen tak for input! Så vi har indtil videre to steder der er problemer:

- Tilhørsfilial

- Sekundær adresse / coName

@Rolf Ja, det burde nok være to sager.

#18 Updated by Steen Larsen over 1 year ago

Hvis vi skal "hacke" i swaggerApi så skal det i hvertfald følges op af nogen som får opgaven at forklare Systematic betydningen af "null" og "required" i swagger-sammenhæng.

@Simon:

Jeg synes du skal teste en ny-oprettet låner og se hvad der sker med dine rettelser - så du er sikker på at de krævede felter faktisk indeholder null fremfor tom streng (i fald de har været rettet) - du burde jo få problemer både med tilhørsfilial og den sekundære adresse?

 

 

#19 Updated by Simon Holt over 1 year ago

@Steen

Ja, jeg vil lige prøve at teste igen. Synes nemlig ikke jeg havde nogle problemer med den sekundære adresse. Men tager lige et kig på det igen.

#20 Updated by Rolf Madsen about 1 year ago

  • Target version changed from Release 29-2 - Bugfixes (Vejle) to Release 33 - Bugfixes

#21 Updated by Rolf Madsen about 1 year ago

  • Status changed from Need more info to Needs analysis

Also available in: Atom PDF