16. VLACC updating

Auteur Jan Corthouts
Aanmaak 18 jun 2003
Aangepast door Alain Descamps
Aangepast op 20 sep 2005
Oud BVV nr 2063

16.1. Abstract

Dit document beschrijft de wijze waarop in Brocade OpenVlacc updates kunnen worden verwerkt. De verwerking van de OpenVlacc updates maakt gebruik van een infrastructuur met volgende componenten:

FTP
Brocade server, die via ftp de OpenVlacc bestanden binnenhaalt.
Distributie
Brocade server die de Vlacc gegevens verwerkt naar XML-bestanden en vervolgens deze bestanden toestuurt naar individuele Brocade-servers die de OpenVlacc gegevens wensen te verwerken.
Input
Brocade-server die de ontvangen OpenVlacc gegevens in de lokale databank verwerkt.

16.2. FTP

De OpenVlacc FTP manager wordt gekarakteriseerd door de servers waarop project /vlacc/ftp wordt geïnstalleerd.

De taak van deze server is: ‘s morgens, na 7 uur, via ftp worden de nieuwe OpenVlacc update bestanden overgehalen via het commando vlaccftp -get workmode=yes. Volgende Delphi waarden zijn daarbij behulpzaam:

  • vlacc-ftp-book-site: de naam van de FTP site voor de niet-muziekrecords.
  • vlacc-ftp-book-login: het FTP login ID.
  • vlacc-ftp-book-password: g=het FTP paswoord
  • vlacc-ftp-book-remotedir: de subdirectory van de FTP site.
  • vlacc-ftp-book-pattern het patroon, van bestandsnamen, dat moet worden overgehaald.
  • vlacc-ftp-bookmusic-site: idem voor de data over boeken + muziekrecords
  • vlacc-ftp-bookmusic-login: idem voor de data over boeken + muziekrecords
  • vlacc-ftp-bookmusic-remotedir: idem voor de data over boeken + muziekrecords
  • vlacc-ftp-bookmusic-password: idem voor de data over boeken + muziekrecords
  • vlacc-ftp-bookmusic-pattern: idem voor de data over boeken + muziekrecords
  • vlacc-ftp-deleted-site: idem voor de data over records, geschrapt in de Vlacc catalogus
  • vlacc-ftp-deleted-login: idem voor de data over records, geschrapt in de Vlacc catalogus
  • vlacc-ftp-deleted-remotedir: idem voor de data over records, geschrapt in de Vlacc catalogus
  • vlacc-ftp-deleted-password: idem voor de data over records, geschrapt in de Vlacc catalogus
  • vlacc-ftp-deleted-pattern: idem voor de data over records, geschrapt in de Vlacc catalogus
  • vlacc-ftp-processdir: de naam van de processdirectory, waaronder de bestanden worden geplaatst.

Hiervoor wordt op de server, die als FTP manager dienst doet, een automatisch process moto.vlaccftp aangemaakt, dat zowat elke 20 minuten opstart. Belangrijk is dat dit proces stopt als de distributie fase begint.

Resultaat van dit proces is:

  • De inkomende files staan onder vlacc-ftp-processdir/incoming
  • Boek files krijgen een prefix b_
  • Boek+music files krijgen een prefix m_

Status informatie kan steeds worden opgevraagd door het commando vlaccftp -status.

In de huidige context fungeert de distributrieserver zelf als ftp manager.

16.3. Distributie

De OpenVlacc distribute server (VDS) wordt gekarakteriseerd door de delphi waarde vlacc-type. Dit is een string die het karakter d bevat.

Deze server kan ook beperkt zijn. Behalve de nodige software (/vlacc/distribute) moet hij ook passende meta-informatie bezitten in de vorm van een python module anet.brocade.library. Deze module bevat diverse gegevens omtrent de targets:

  • Acroniem van de target
  • dnsname (+SSH port) van de target
  • Incoming directory op de target (meestal: /library/process/vlacc/vi/incoming)
  • Parameters voor de installatie op de target. Deze parameters moeten in een string staan die geen ‘.’ of ‘ ‘ bevatten. Voor een brocade systeem is dit gewoon het regelwerk van de betreffende catalogus (voorbeeld: ob)

Indien op de VDS een Brocade systeem huist, dan kan deze meta-informatie worden beheerd via Brocade ‣ Instellingen ‣ Instelling invoeren/wijzigen [link].

De VDS vertrouwt niemand en iedere target + de VSS moeten de VDS vertrouwen.

Op de VDS lopen er 3 processen. Deze mogen worden gebundeld in 1 proces of onafhankelijk van elkaar worden gescheduled. De periode van het proces is onbelangrijk: opnieuw lijkt 1 uur een goede keuze.

16.3.1. Voorbereidende fase

Deze fase wordt opgestart via vlaccds -prep source=vlacc-ftp-processdir/incoming archive=yes remove=yes en bestaat uit de volgende onderdelen:

  1. De gespecifieerde directory (source=..) wordt onderzocht naar MARCXML bestanden.
  2. Deze worden geconverteerd naar CAT XMLbestanden, die , in een gezipte vorm, worden geplaatst in vlacc-ds-process-dir/xml.

16.3.2. Distribute fase

Deze fase wordt opgestart via vlaccds -distribute handling=yes transport=yes en bestaat uit de volgende onderdelen:

  1. De vlacc-ds-process-dir/xml directory wordt geïnspecteerd op de passende gezipte bestanden.
  2. Via de meta informatie van de targetbibliotheken wordt dan bij elke target een marker (=naam van het gezipped XML archief) geplaatst. Dit is een bestand dat staat in de directory vlacc-ds-process-dir/targets/derde component van de library-loi. In deze faze wordt de marker nooit overschreven. Bij aanmaak bevat hij gewoonweg de string 0.
  3. Eens alle markers geplaatst, dan wordt het bestand verschoven van vlacc-ds-process-dir/xml naar vlacc-ds-process-dir/distribute.
  4. Vervolgens worden alle uitstaande markers in vlacc-ds-process-dir/targets overlopen. bevat de marker enkel een 0, dan wordt het corresponderende bestand uit vlacc-ds-process-dir/distribute via scp verschoven naar de incoming directory op de target server (deze gegevens worden gehaald uit de meta informatie in anet.brocade.library. Een SSH request naar deze machine met de opdracht vlaccvi -check filename param rondt het geheel af: de target machine ontvangt de parameters nodig om verder te werken en heeft de mogelijkheid om een bevestiging te sturen naar de VDS. Komt de bevestiging aan, dan wordt de inhoud van de marker op ‘1‘ gezet.
  5. Functioneert de VDS op een brocade systeem, dan wordt ook bij de meta informatie van de ontvangende bibliotheek een datum van ontvangst gefiled.
  6. De status informatie kan steeds worden opgevraagd door het commando vlaccds -status.

16.3.3. Clean fase

Deze fase wordt opgestart via vlaccds -clean , en mag gecombineerd worden in één proces met vorige, en bestaat uit de volgende onderdelen:

  1. Alle uitstaande markers in vlacc-ds-process-dir/targets worden overlopen. Bevat alle gelijknamige markers enkel de code ‘1‘, dan worden de markers geschrapt en wordt het gelijknamige bestand geschrapt uit vlacc-ds-process-dir/distribute geschrapt.
  2. De status informatie wordt weggeschreven in vlacc-ds-process-dir/status/clean.
  3. De status informatie kan steeds worden opgevraagd door hetzelfde commando vlaccds -status dat de stand van alle distributiefazen toont.

16.4. Input

Dit is het enige onderdeel van de toepassing dat Brocade specifiek is: de rest van deze paragraaf gaat er van uit dat de machine waarop de OpenVlacc updating gebeurt, een Brocade toepassing is.

Deze machines worden gekarakteriseerd door de delphi waarde vlacc-type. Dit is een string die het karakter i bevat. De Brocade-toepassing die de OpenVlacc bestanden in de lokale databank verwerkt, moet aan de voorwaarden voldoen, beschreven in Open Vlacc Updating.

De aansturing van het transport van de bestanden naar deze servers gebeurt door de distributie server.

16.5. OpenVlacc updates in de praktijk

FTP manager

anet.ua.ac.be

anet.ua.ac.be haalt via ftp de OpenVlacc bestanden binnen.

DISTRIBUTIE server

anet.ua.ac.be

anet.ua.ac.be is tevens de distributie-server. De server moto converteert de OpenVlacc bestanden naar CAT XML. De code voor deze verwerking bevindt zich in project /vlacc/vlaccin.

In het instellingsbeheer op deze server staat bij COB-Antwerpen aangegeven dat de machine waarop de OpenVlacc gegevens voor OB-Antwerpen terecht moeten komen, de server obib.antwerpen.be is. Een overzicht van de betroffen INPUT servers en parameters vind je door het commando vlaccds -info in te geven. Deze servers ontvangen dagelijks de OpenVlacc XML-bestanden en verwerken ze in hun eigen databank.

Waarschuwing

Bij de verwerking van de OpenVlacc updates moet rekening gehouden worden met het volgende:

  • Er wordt een onderscheid gemaakt tussen nieuwe records en bestaande records. Criterium hierbij is het voorkomen van het OpenVlacc-nummer in het nummer-veld van het Brocade record. Het OpenVlacc-nummer is van het type co (conversienummer) en heeft steeds de vorm vl.nnnnnn.

  • Alle nieuwe OpenVlacc-records die toekomen krijgen automatisch het lidmaatschap vlacc

  • Een update voor een bestaand record wordt niet verwerkt indien het record de status “Bevroren” heeft.

  • Het inladen van nieuwe records wordt aangestuurd door het Update patroon, dat bepaald is in het instellingsbeheer op de distributieserver. Voorbeeld : m_*:upd,b_*:all, d_*:upd : book+music (m_) : verwerk enkel de upd(dates) ; book (b_) : verwerk alles ; deleted records (d_) : verwerk enkel de upd(ates)

  • Een update voor een bestaand record wordt enkel verwerkt indien het record het lidmaatschap “vlacc” heeft. M.a.w. als je een nieuw OpenVlacc-record binnenkrijgt, dan heeft dat het lidmaatschap vlacc. Als je vervolgens het lidmaatschap vlacc verwijdert, en daags nadien komt een update tot voor dat record, dan wordt die update niet verwerkt.

  • Het resultaat van de verwerking van de OpenVlacc-updates wordt dagelijks weggeschreven in lijsten. Deze lijsten zijn toegankelijk via Brocade ‣ Lijstbeheer ‣ Globaal overzicht lijsten [link] en vlacc - conversion. In de naam van de lijst is de datum opgenomen. Voor elke update worden drie lijsten gemaakt: die met de nieuwe records, die met bestaande records en die met de records, die om de een of andere reden niet zijn bijgewerkt. (bevroren,..). Voorbeeld

    b_ovdnmbr20080805.cat_existing
    b_ovdnmbr20080805.cat_forbidden
    b_ovdnmbr20080805.cat_new
    m_ovdalbr20080805.cat_existing
    m_ovdalbr20080805.cat_forbidden
    
  • Bij de verwerking van de trefwoorden, themawoorden, SISO en ZIZO-codes wordt in eerste instantie nagegaan of het aangeboden trefwoord bestaat in het authority-bestand. Als dat het geval is dan wordt de authority-code (a:: ...) in het record overgenomen. Is dat niet het geval, dan wordt een nieuwe authority-code gecreëerd en vervolgens in het record overgenomen.

  • Deze werkwijze wordt NIET gevolgd voor de verwerking van personele of corporatieve auteurs. Auteursnamen worden as is in het record overgenomen. Let op: indien in het record de auteursnaam is opgenomen als authority-code, en voor dit record is OpenVlacc updating toegestaan (het is niet bevroren en het record heeft het lidmaatschap vlacc) dan zal bij updating de bestaande authority code worden overschreven door de naam van de auteur.

16.6. OpenVlacc: Foutenanalyse

Na het detecteren van een fout in een gecompliceerd vraagstuk als de OpenVlacc verwerking kan het wel moeite kosten om na te gaan wat er aan de hand is. Hieronder volgen alvast enkele tips, trucks en aanbevelingen in de vorm van Vraag en Antwoord.

16.6.1. Hoe ziet de nieuwe flow van de bestanden er uit?

Op de distributieserver
  • vlaccftp -get haalt de OpenVlacc files (in MARC XML) over en plaatst ze in vlacc-ftp-processdir/incoming.
  • vlaccds -prepare source=vlacc-ftp-processdir/incoming archive=yes remove=yes pikt ze daar op, verwerkt ze tot een gezipped CAT XML formaat, en plaatst dit in vlacc-ds-process-dir/xml.
  • vlaccds -distribute handling=yes transport=yes pikt ze daar op, en plaatste ze in vlacc-ds-process-dir/distribute. Bovendien maakt ze markers in vlacc-ds-process-dir/targets/libid, zoals eerder beschreven. In een tweede fase (transport=yes) tracht ze de CATXML bestanden naar de IMPORT servers te sturen en past de markers aan. De info over de target servers en directories, waar deze terechtkomen, vind je via vlaccds -info.
Op de import server(s)
  • vlaccvi -update pikt de gezipte CAT XML bestanden op, en importeert ze. Daarbij wordt gebruik gemaakt van het (lokaal gedefinieerde) catman profiel vlacc.

16.6.2. Wat zit er precies in de verschillende subdirectories van vlacc-ds-process-dir?

  • vlacc-ds-process-dir/incoming is obsolete.
  • vlacc-ds-process-dir/xml bevat de nieuwe gezipte catxml files.
  • vlacc-ds-process-dir/distribute bevat de gezipte catxml files in behandeling.
  • vlacc-ds-process-dir/status bevat de statusinfo van de laatste run.
  • vlacc-ds-process-dir/targets/libid bevat files met dezelfde naam als in /distribute, maar met een 0 (=nog niet succesvol opgestuurd) of 1 (=succesvol opgestuurd) als enige inhoud van de file.

16.6.3. Wie zorgt voor de archivering in docman?

Op de distributieserver
vlaccds -prep .. archive=yes zorgt voor de archivering van de originele MARCXML bestanden (extensie.xml) EN de gezipte cat xml bestanden (extensie .zip).
Op de import server(s)
vlaccvi -update zorgt voor de archivering van de bekomen gezipte cat xml bestanden, met aangepaste prefixen.

16.6.4. Welke zijn de huidige target servers?

Voer uit op de distributieserver: vlaccds -info.

Vergeet niet een update van python module ‘library’ uit te voeren bij het aanpassen van de Vlacc meta info van de instelling.

16.6.5. Hoe een verwerkt bestand alsnog terug opsturen en verwerken?

  • Plaats je in een lege temp directory op de distributieserver, en voer uit : docman -fetch db=vlaccds pattern='*20080619*.zip' (met een aangepaste pattern)
  • Transfereer de bestanden naar de inkomende directory voor vlaccvi op de remote server: Voorbeeld : scp *.zip obib.antwerpen.be:/library/process/vlacc/vi/incoming
  • Voer uit voor elk van deze files op de remote import server, met de JUISTE modifier waarden:
    • vlaccvi -check b_ovdnmbr20080619.zip lvd=ob updmode=all
    • vlaccvi -check m_ovdalbr20080629.zip lvd=ob updmode=upd
  • Om de import te starten: voer uit op de import server:
    • vlaccvi -update voor de echte update
    • Eventueel: vlaccvi -update fake=yes als test

16.6.6. Ik wens dat een bepaald update bestand een tweede maal wordt verwerkt: wat doe ik ?

Voer uit: vlaccftp -get pattern=somefile.xml workmode=no

Verdere verwerking gebeurt dan automatisch. Voeg desgewenst targetdir=somedir eraan toe, en verwerk manueel.

16.6.7. Men vertelt dat er geen Vlacc updates doorkomen. Wat doe ik eerst?

Voer uit op de distributieserver:

  • vlaccftp -status vertelt je de laatste succesvolle ftp sessie, en over welke files het ging.
  • vlaccds -status vertelt je de laatste situatie van de voorbereiding, handling en remote transfert van de OpenVlacc bestanden.

16.6.8. Een probe melding vlaccds -prep: errors: wat moet ik doen?

  • Voer uit op de distributieserver : vlaccds -status

    Dit zal je wijzer maken, welke problemen er zijn.

  • Mogelijke meldingen en passende remedies (dit overzicht is indicatief en niet compleet):

    • PROBLEM IN PREP
      • ... RECORDS with ERRORS: de verwerking van Vlacc records van MARC naar catxml formaat is wel degelijk gelukt, maar inhoudelijk werden onvolkomenheden vastgesteld. Hoewel de verwerking en distributie van Vlacc records niet in het gedrang komt, is het mogelijk dat er inhoudelijk data verloren gaat. Dit vereist uiteindelijk een ingreep van de specialist-ontwikkelaar.
    • PROBLEM IN CLEAN DATA: het verwijderen van de nodige files is mislukt. Check file permissions,..
    • ERROR : transport of dist files more than .. days ago: sinds meer dan .. dagen werden geen Vlacc files gedistribueerd. Mogelijke redenen :
      • Er werden gedurende geruime tijd geen Vlacc files aangeboden
      • Er scheelt iets met het overhalen van de Vlacc updates : ftp, ..
    • `` ERROR in distributing files``: het distribueren van Vlacc updates naar de Vlacc import servers lukt niet (helemaal). Controleer toegangen, firewalls, .. van de vermelde servers.

16.6.9. Ik wil de inhoudelijke fouten van een verwerkt bestand zien: wat doe ik?

Voer uit op de distributieserver:

  • docman -fetch db=vlaccds pattern='*20100106*.xml' (met de juiste pattern)
  • vlaccin -check xxx20100106xxx.xml

16.6.10. Ik wil dat nieuwe of inhoudelijk gewijzigde elementen in Vlacc updates gerapporteerd worden: wat doe ik?

Maak een automatisch proces aan dat uitvoert vlaccds -status warn=myemail@somewhere.com.

Vervang myemail@somewhere.com door het e-mail adres van de ontvanger. Laat dit proces lopen na de voorbereidende fase, bij voorkeur eenmaal per dag.