VacatureRadar/docs/operations/SOURCE_ONBOARDING.md

Bron onboarden

De actueel gereviewde werkgeverfeeds, proefresultaten en dekkingsgrenzen staan in LIVE_SOURCE_CATALOG.md. config-data/seed_sources.yaml installeert uitsluitend de daar vastgelegde bronnen en verbergt de oude fixturebron uit het normale overzicht.

Een nieuwe bron wordt nooit direct als onbeperkt actief beschouwd. Gebruik het traject candidate → trial → active en ga bij veiligheids- of kwaliteitsproblemen naar quarantined.

Toegestane broncategorieën

Voorkeursvolgorde:

1. openbare carrièrepagina van de feitelijke werkgever;
2. openbare, door de werkgever bedoelde ATS-vacaturepagina;
3. expliciete RSS/Atom-feed of sitemap met vacatures;
4. vacaturemail die de gebruiker zelf heeft geactiveerd;
5. handmatige browserimport door de gebruiker.

Niet onboarden zonder expliciete, aantoonbare toestemming:

• ingelogde zoekresultaten of profielpagina's;
• pagina's achter CAPTCHA, anti-bot challenge of toegangscontrole;
• denylistplatformen via directe crawling;
• verborgen/private endpoints die alleen door reverse engineering zijn gevonden;
• bronnen waarvan robots/voorwaarden of technische signalen automatisering verbieden.

Reviewchecklist

Leg per bron vast:

• naam, bronsoort, hoofddomein en exacte start-URL;
• eigenaar/eindwerkgever en eventuele ATS-provider;
• publieke toegankelijkheid zonder login;
• datum en samenvatting van robots- en voorwaardenreview;
• toegestane paden en eventuele uitgesloten paden;
• parserstrategie: JSON-LD, RSS, gespecialiseerd ATS of generieke HTML;
• verwachte frequentie en minimale interval;
• maximaal documentvolume en paginatie;
• welke velden daadwerkelijk aanwezig zijn;
• retentiebehoefte en mogelijke persoonsgegevens;
• contact-/user-agentinformatie indien passend;
• rollback/quarantainecriterium.

robots.txt alleen is geen volledige juridische toestemming, en afwezigheid ervan is geen automatische toestemming. Het technische bronbeleid ondersteunt een conservatieve beslissing; de beheerder blijft verantwoordelijk voor de bronreview.

Candidate aanmaken

Gebruik Django admin of seed_sources met een gecontroleerd YAML-record. Begin met:

name: Voorbeeld Werkgever
source_type: employer
base_url: https://careers.example.org/jobs
status: candidate
policy: review
parser_key: auto
strict_mode: true
honor_robots: true
crawl_interval_minutes: 720
minimum_interval_seconds: 30
max_concurrency: 1

Zet policy: allow pas na review. Een onbekende bron blijft in strict mode zonder fetch.

Fixture vóór live request

Bewaar een gesaneerd voorbeeld onder fixtures/pages, fixtures/feeds of fixtures/emails. Verwijder trackingtokens, persoonsgegevens en niet-noodzakelijke volledige teksten. Schrijf tests voor:

• normale vacature;
• ontbrekende optionele velden;
• nul vacatures;
• gewijzigde markup of meerdere jobs;
• kwaadaardige HTML en onveilige links;
• idempotente replay;
• parserconfidence en waarschuwingen.

Trialrun

1. Zet bron op trial en policy=allow.
2. Voer één handmatige run uit via de retryknop of Celerytask.
3. Controleer status, final URL, bytes, parser, warnings en tellers.
4. Open alleen gesaniteerde jobweergave; vergelijk steekproefsgewijs met de publieke bron.
5. Controleer canonieke URL, werkgever, locatie, datum, verloopdatum, taal en duplicaten.
6. Verifieer dat redirectdoelen, rate limit en conditional requests correct zijn.
7. Laat minimaal twee geplande cycli goed verlopen vóór promotie naar active.

Automatische quarantainecriteria

Een bron moet worden gepauzeerd of in quarantaine gezet bij:

• redirect naar denylist, login, private adresruimte of onverwacht domein;
• herhaalde 401/403/429, CAPTCHA of anti-botpagina;
• contenttype/grootte buiten beleid;
• parseroutput met plotseling nul jobs terwijl de bron zichtbaar jobs bevat;
• abnormale volumestijging of duplicaatstorm;
• HTML-sanitization/securityfout;
• voorwaardenwijziging of verlopen bronreview;
• opeenvolgende fouten boven de vastgelegde drempel.

Gespecialiseerde ATS-adapter

Voeg alleen een adapter toe wanneer meerdere bronnen hetzelfde stabiele publieke formaat gebruiken of de generieke adapter onvoldoende bewijs levert. De adapter:

• krijgt geen credentials;
• gebruikt uitsluitend gedocumenteerde publieke jobdata of publieke pagina's;
• implementeert het interne adaptercontract;
• heeft providerfixtures en contracttests;
• valt veilig terug zonder globale pipeline te breken;
• documenteert paginatie, sluitingssignalen en rate limits.

Bron verwijderen

Pauzeer eerst. Behoud canonieke vacatures en herkomst zolang productretentie dat vereist; verwijder niet blind clusters die ook andere aliassen hebben. Verwijder raw documents volgens retentie, trek de policy in en noteer de reden en datum.

Reviewbeleid bij bronbeoordeling

• Een bron mag alleen automatisch gefetcht worden wanneer een actuele SourcePolicyReview bestaat met geldige reden, scope en vervaldatum.
• Terms review blijft menselijk, niet automatisch door AI of heuristiek.
• Bij ontbrekende of verlopen review of bij expliciet pause/deny besluit blokkeert de taakuitvoering.

Handmatige import in de interface

Voor uitzonderlijke vacatures kan de beheerder handmatig importeren via de bronpagina:

• navigeer naar Brongezondheid en gebruik het "Handmatige import" formulier;
• gebruik de bookmarklet om de huidige pagina-URL te vullen in source_url;
• of plak direct relevante vacaturetekst in het tekstveld wanneer fetch niet is toegestaan.

De bookmarklet stuurt alleen source_url naar de import-URL, zonder secret of broninhoud.

Na import toont de bronlijst:

• de gekozen modus (url of paste);
• bron-ID/bron-URL;
• aantallen herkend, nieuw en duplicaat;
• waarschuwingen;
• links naar vacaturedetail voor direct vervolg.

Providerdetails (VR-106)

Voor het onboarden van publieke ATS-bronnen moet het bronrecord minimaal een van de volgende providerspecificaties gebruiken:

• Greenhouse (*.greenhouse.io / *.boards.greenhouse.io) — max 15 requests/min, alleen publiek toegankelijke jobdata.
• Lever (jobs.lever.co) — max 60 requests/min, alleen jobs.lever.co en officiële publieke endpoints.
• Recruitee (*.recruitee.com) — max 60 requests/min, geen login/partner endpoint.
• SmartRecruiters (*.smartrecruiters.com) — max 30 requests/min, alleen publieke vacaturepagina/feeds.
• Workable (apply.workable.com) — max 30 requests/min, alleen publieke vacaturepagina/feeds.

Bij twijfel altijd op review blijven en eerst via een trialrun met gesloten evaluatiecriteria (gesloten job, lege joblijst, markeringswijziging) valideren.

Meerdere werkgevers kunnen dezelfde ATS-host gebruiken. Registreer ze als afzonderlijke bronnen met een unieke exacte publieke base_url; gebruik het providerdomein nooit als werkgeveridentiteit. Rate limiting en leases blijven per origin gedeeld, dus laat opeenvolgende liveproeven op Lever of SmartRecruiters het ingestelde minimuminterval respecteren.

Brede jobboards via platformmailboxen

VDAB, Indeed, LinkedIn, ictjob.be, Jobat, StepStone, Careerjet, Randstad en Robert Half blijven directe-fetchdenylistbronnen. Activeer op het jobboard zelf een officiële vacaturealert en koppel op de bronpagina per platform een afzonderlijke Gmail-, Outlook- of aangepaste IMAP-mailbox. Kies per mailbox een interval van 5 tot 360 minuten; de scheduler pakt alleen verschuldigde actieve koppelingen. De parser houdt per koppeling uitsluitend gelabelde HTTPS-links op het gekozen jobboarddomein over. Zonder mailboxcredentials gebruikt de beheerder handmatige URL- of tekstimport; dit is geen reden om platformpagina's automatisch te crawlen.

seed_sources ondersteunt daarnaast retire_source_urls. Zo wordt een bron die buiten de gekozen regio valt uitgeschakeld en uit het normale bronoverzicht verborgen, terwijl eerdere documenten, vacature-aliassen en provenance behouden blijven. Gebruik dit mechanisme voor een regionale koerswijziging; verwijder bronhistoriek niet handmatig.

Voor de Mol-regio geldt postcode 2400 met een straal van 40 km als cataloguscentrum. Leg per werkgever een expliciete gemeentemarker vast en behandel een ontbrekende concrete vacaturelocatie als onbekend. De regional-mol-employers-parser mag uitsluitend de vijf gereviewde routes uit de livecatalogus verwerken; een nieuwe host, pad, CVWarehouse-GUID of vestiging vereist eerst een nieuwe fixture, securitytest en bronreview.

De aanvullende regional-kempen-employers-parser volgt dezelfde regel voor zeven exacte routes: Ziekenhuis Geel, lokaal bestuur Geel, Stad Turnhout, Renotec, Ravago, Sanofi en DAF Trucks Westerlo. Gemeente Mol gebruikt de officiële RSS-route. Controleer bij landelijke of gedeelde joblijsten dat iedere kaart de gereviewde gemeente expliciet noemt; een onduidelijke locatie wordt niet stil aan een vestiging toegewezen.

Gebruik metadata.watchlist: true voor een interessante regionale werkgever die momenteel geen vacature heeft of nog geen stabiele publieke listing heeft. Zo'n bron staat op paused, verschijnt afzonderlijk in de UI en wordt niet door bulkacties of de scheduler gescand. Activeer hem pas na een nieuwe voorwaardenreview, fixture, negatieve host/padtest en twee geslaagde trialcycli.

Een mailboxkoppeling vraagt alleen IMAP-gegevens. VacatureRadar vraagt of bewaart geen LinkedIn-, ictjob-, Jobat-, StepStone- of ander jobboardwachtwoord en activeert alerts niet automatisch. Wanneer een jobboard zijn mailformaat wijzigt en geen herkenbare platformlink resteert, werk dan eerst een gesaneerde fixture en parsertest bij.

VDAB documenteert daarnaast een officiële Vacature API voor het ophalen en synchroniseren van vacatures. Registreer die pas als nieuwe adapter/brontype nadat VDAB het partnership schriftelijk heeft goedgekeurd, de samenwerkingsovereenkomst rond is en testcredentials beschikbaar zijn. Publieke developerportal-documentatie alleen is geen toestemming om de API te gebruiken.