Bulkinvoer naar watchfolder via FTPS

Owned by stijn.bovy (Unlicensed), created
Last updated: Apr 03, 2024
5 min read

Inleiding

De automatische invoer met metadata is een uitbreiding op de semi-automatische invoer met metadata, zoals hier toegelicht. De semi-automatische invoer met metadata via de browser is beperkt tot een datavolume van 1,5 GB. Voor het opladen van grotere volumes (SIP > 1,5 GB) naar het E-depot is de automatische invoer met metadata geschikt.​ Deze laatste invoermethode kan evengoed worden gebruikt voor datavolumes kleiner dan 1,5 GB.

De 'automatische invoer met metadata' of de 'bulkinvoer naar een watchfolder via FTPS' zijn synoniemen voor eenzelfde invoermethode.​​​​

Watchfolder

Elke klant van het E-depot kan beschikken over een afgeschermde, organisatie-eigen watchfolder. Deze folder is een veilige omgeving waar de klant dossiers en stukken in bulk kan opladen en waar het E-depot deze informatie kan ophalen om verder te verwerken.

Door gebruik te maken van een watchfolder is het mogelijk om grotere volumes (> 1,5 GB) in te voeren. Waar de gebruiker bij een semi-automatische invoer met metadata de SIP via de browser oplaadt naar het E-depot, zal de gebruiker bij een automatische invoer met metadata de SIP naar een watchfolder opladen waar het E-depot deze ophaalt voor verwerking.

Het opladen van informatie naar de watchfolder verloopt niet via een webclient in de browser maar via het bestandsoverdrachtprotocol FTPS.

De watchfolder is beschikbaar op

  • ftps://ingest.digitaalarchief-uat.vlaanderen.be (voor de ontwikkelomgeving van het E-depot),

  • ftps://ingest.digitaalarchief-ti.vlaanderen.be (voor de test- en opleidingsomgeving van het E-depot),

  • ftps://ingest.digitaalarchief.vlaanderen.be (voor de productie-omgeving van het E-depot).

Digitaal Archief Vlaanderen zal de specifieke logingegevens als gebruikersnaam en paswoord aan de klant meedelen. Zie ook Aanvraagprocedure.

Indien de connectie naar de watchfolder via het netwerk (proxy- of firewall) moet worden geconfigureerd:

ftps://ingest.digitaalarchief-ti.vlaanderen.be (watchfolder test- en opleidingsomgeving)

IP: 54.247.175.150 (voorheen was dit 108.128.81.241)
Poort 21 (voor de communicatie)
Poorten 50.000 t.e.m. 50.100 (voor de data)

ftps://ingest.digitaalarchief.vlaanderen.be (watchfolder productie-omgeving)

IP: 176.34.86.71, 52.213.10.62, 34.252.79.19 (voorheen was dit 52.213.99.69)
Poort 21 (voor de communicatie)
Poorten 50.000 t.e.m. 50.100 (voor de data)

FTPS

Het overbrengen van data naar de watchfolder gebeurt via FTPS, ook bekend als FTP-SSL en FTP Secure. FTPS heeft een hogere overdrachtssnelheid dan een upload via de browser. Bovendien laat het een betere opvolging van de transfer toe dan een upload via de browser.

Een FTP-client is vereist om connectie te maken met de watchfolder en data door te sturen naar deze locatie. Digitaal Archief Vlaanderen maakt bijvoorbeeld gebruik van de gratis FTP-toepassing FileZilla. Voor een lijst van beschikbare FTP-clients verwijzen we graag naar deze pagina.

De interface van Filezilla:​​​​​​​​​​​​​​​​​​​​​

FTP-client FileZilla

​Koppel

Het systeem haalt de data op uit de watchfolder en verwerkt deze. In de watchfolder moet een koppel bestanden worden geschreven van de volgende vorm:

  • <serie ID>-<titel>.zip,

  • <serie ID>-<titel>.xml.

De bestanden worden pas opgepikt als een overeenstemmend koppel wordt gevonden. Zorg ervoor dat eerst het zipbestand wordt opgeladen en pas als laatste het XML-bestand.

Metadata

Elke zip gemaakt voor de semi-automatische invoer met metadata moet vergezeld zijn van een sidecar XML-bestand van de vorm:

<?xml version="1.0" encoding="UTF-8"?> <mhs:Sidecar xmlns:mhs="https://zeticon.mediahaven.com/metadata/20.3/mhs/" version="20.3" xmlns:mh="https://zeticon.mediahaven.com/metadata/20.3/mh/"> <mhs:Technical> <mh:Md5>5609a5f5abe6e5c715fd52e8a33d5058</mh:Md5> </mhs:Technical> </mhs:Sidecar>

De waarde in het element Md5 is de Md5 checksum van de zip. De regel <mh:Md5>…</mh:Md5> bevat de Md5 checksum van de zip.

Een sjabloon voor het sidecar XML-bestand downloaden:

De gebruiker kan het XML-bestand ook makkelijk zelf aanmaken. Het volstaat om een nieuw tekstbestand aan te maken met de Windows-applicatie Kladblok, bovenstaande code te kopiëren en te plakken in het lege tekstbestand, en dit bestand niet als .txt- maar als .xml-bestand op te slaan.

Zorg er zeker voor dat elke regel begint en eindigt met de correcte tags.

image-20240129-075902.png
Tekstbestand met code

De naamgeving van het XML-bestand moet een specifiek formaat hebben:

  • <serie ID>-<titel>.xml.

Voorbeeld: f3f3991bde6a439a9bbfb765cb44c8e1897a54ff4a8e4fbbafd426bde5d5f16a-voorbeeld.xml.

ZIP

De naamgeving van het zipbestand moet eveneens een specifiek formaat hebben:

  • <serie ID>-<titel>.zip.

Voorbeeld: f3f3991bde6a439a9bbfb765cb44c8e1897a54ff4a8e4fbbafd426bde5d5f16a-voorbeeld.zip.​​​​​​​​​​​​​​

Verwerking​​​​​​​​​​​​​​

Het zipbestand zal niet worden verwerkt en in de watchfolder blijven staan wanneer:

  • Er geen XML-bestand is meegegeven,

  • Het XML-bestand qua syntax niet correct is,

  • Het XML-bestand niet in het bovenstaande formaat is opgemaakt,

  • Het XML-bestand geen Md5 bevat,

  • De vermelde Md5 niet overeenkomt met de berekende Md5 van de zip,

  • De bestandsnaam niet voldoet aan de vormvereiste <serieId>-<titel>,

  • De serieId geen geldige RecordId is, zoals beschreven in het metadatamodel,

  • De serieId niet naar een gepubliceerde serie binnen de organisatie van de watchfolder verwijst.

Als wel aan al deze voorwaarden is voldaan, zal het koppel automatisch verdwijnen uit de watchfolder en in het E-depot verschijnen onder de Verwerkingslijst.

Stappenplan

  1. Serieregister: serieid ophalen, id noteren

  2. E-depot: Import sjabloon of metadatabestand serie downloaden

  3. Windows Verkenner: Dossiers klaarzetten

  4. Excel: Importsjabloon invullen, opslaan als xlsx

  5. Verkenner: Zip aanmaken (dossiers en metadatabestand)

  6. Verkenner: Zip hernoemen (serieid-titel.zip)

  7. Cmd of Opdrachtprompt/website: Hash berekenen, noteren

    1. Via website: MD5 File Checksum ​​​​​​​ > hash noteren (goed voor kleinere bestanden; 1 GB duurt circa 15-20 min)

    2. Via Windows: Start > Zoek > Cmd > CertUtil -hashfile "<path to file>" MD5 (goed voor grotere bestanden; gaat veel sneller)

      1. Path ophalen kan makkelijk

        1. in Verkenner > Ga naar bestand > Rechtermuisknop > Snelkoppeling maken

        2. Snelkoppeling > Rechtermuisknop > Eigenschappen > Kopieer pad van bestand

        3. Path tussen "" invullen in cmd-commando > Hash noteren

  8. Verkenner: Xml-bestand opmaken

    1. Xml-bestand ophalen

  9. Kladblok: Xml-bestand openen, wijzigen, opslaan

    1. Hash invullen, wijziging opslaan, zelfde locatie als zip

    2. Opslaan als xml

  10. Verkenner: Xml-bestand hernoemen (serieid-titel.xml)

  11. FTP-client: 2 bestanden uploaden

    1. Open client

    2. Credentials

      1. Host

      2. Gebruiker

      3. Wachtwoord

      4. Poort

    3. Laad de zip en het xml-bestand op

  12. E-depot: Verwerkingslijst

Aanvraagprocedure

Bij de aansluiting krijgt ​​​​​elke klant van het E-depot een tenant en een afgeschermde, organisatie-eigen watchfolder. De leverancier voorziet een generieke organisatie-account die toegang geeft tot de watchfolder. De toegang is niet gelimiteerd in de tijd.

Het gebruik van de watchfolder moet worden aangevraagd bij Digitaal Archief Vlaanderen, via digitaalarchief@vlaanderen.be. Digitaal Archief Vlaanderen fungeert als tussenpersoon voor de communicatie tussen de klant en de leverancier. DAV stuurt de aanvraag door naar de leverancier. Wij bezorgen u vervolgens de details hoe de organisatie kan verbinden met de watchfolder, samen met de beveiligde aanmeldgegevens (login, paswoord) van de leverancier.