Der Provider Hansalog holt Stellenanzeigen aus den Hansalog-Bewerbermanagement-Systemen zweier Mercedes-Benz-Händlergruppen und stellt sie im Projekt Zukunft mit Stern bereit.

Was ein Crawler tut

Ein Crawler liest alle aktuellen Stellenanzeigen einer Händlergruppe, ordnet jede Anzeige den passenden Mercedes-Benz-Standorten zu, ergänzt sie um Kategorie, Berufsprofil, Kontakt und Bilder und schreibt das Ergebnis in den Solr-Suchindex der Zielseite oder in eine Datei.

Jeder Lauf ist ein vollständiger Abgleich: Nach dem Schreiben nach Solr werden alle Anzeigen dieses Crawlers für diese Seite gelöscht, die im aktuellen Lauf nicht mehr vorkamen.

Begriffe

Zielseiten

Der Site-Hash kennzeichnet in Solr, zu welcher Seite eine Anzeige gehört. Er ist der SHA1-Wert des Site-Namens (z. B. sha1("dev-zms.local")) und muss im Runner exakt zur Zielseite passen. Die Suche der Zielseite filtert nach genau diesem Wert.

Jeder Lauf durchläuft dieselben vier Schritte. Was in einem Schritt passiert, steht im Protokoll.

1. Einlesen (collect)

Je nach Runner-Einstellung Input:

• API: Anmeldung an der Hansalog-API mit dem Token, Abruf aller Stellen über /applicantManagement/jobs, danach Abmeldung. Die Sitzung wird in data/<source>/cookie.txt gehalten.
• Datei: Die Anzeigen werden aus der JSON-Datei gelesen, die im Runner unter from_file steht. Gut für Tests ohne API-Zugriff.

2. Zuordnen (transform)

Jede Anzeige wird geprüft und den Standorten zugeordnet:

• Fehlen Pflichtangaben (z. B. ID oder Titel), wird die Anzeige verworfen. Im Protokoll erscheint eine Warnung.
• Der Hansalog-Standort der Anzeige muss in der Standortliste des Crawlers bekannt sein. Ein Standort kann mehreren Händlern zugeordnet sein. Dann entsteht pro Händler ein eigener Eintrag.
• Die Händlerdaten (Name, Adresse, Geo-Koordinaten, Website, Logo, Bewerbungslink) kommen aus der lokalen Händlerliste, nicht aus der API.

Die Besonderheiten je Crawler stehen in den Kapiteln zu HAL und HAS.

3. Anreichern (enrich)

Für jeden Eintrag werden ergänzt:

Pro aufgenommener Anzeige erscheint eine INFO-Zeile „Die Anzeige ist valide und wurde aufgenommen“. Im Protokoll der Oberfläche sind diese Zeilen eingeklappt.

4. Ausgeben (transmit)

Je nach Runner-Einstellung Output:

• Solr: Zuerst wird gezählt, wie viele Anzeigen dieses Crawlers für die Site schon im Index sind. Dann werden alle neuen Einträge in den Core core_de geschrieben und erneut gezählt. Zum Schluss werden alle älteren Einträge dieses Crawlers für diese Site gelöscht (Bereinigung). Die Bereinigung läuft nur, wenn das Schreiben erfolgreich war.
• Datei: Alle Einträge werden als JSON in die Datei unter to_file geschrieben. Eine vorhandene Datei wird überschrieben.

Schutz bei Solr: Liefert die Quelle keine gültigen Anzeigen, wird weder geschrieben noch bereinigt. Die bisherigen Anzeigen bleiben auf der Seite, im Protokoll steht eine Warnung „Es gibt keine gültigen Anzeigen …“. Lehnt Solr das Schreiben ab oder ist nicht erreichbar, bricht der Lauf mit einem Fehler ab, und die bisherigen Anzeigen bleiben ebenfalls erhalten.

Der Crawler Hansalog Lueg (HAL) liest die Stellen der Autohaus Lueg GmbH.

Welche Anzeigen aufgenommen werden

Eine Anzeige wird nur übernommen, wenn alle Bedingungen erfüllt sind:

1. Stellen-ID, Titel, Standort-ID und Standort-Name sind gefüllt. Sonst: Warnung „Die Mindestanforderung an die Daten ist nicht erfüllt“.
2. Die Standort-ID ist in der Standortliste von HAL bekannt.
3. Das Unternehmen der Anzeige ist „Mercedes-Benz“.

Ist Punkt 2 oder 3 nicht erfüllt, erscheint die Warnung „Die Location (…) ist nicht bekannt, oder gehört nicht zu Mercedes (…)“. Das ist bei Lueg normal, weil die API auch Stellen anderer Marken und Gesellschaften liefert (z. B. Volvo, Ferrari, Mobexo, LUEG Holding).

Standorte

HAL kennt 12 Hansalog-Standorte, die auf 14 Händler verweisen. Einige Standorte sind Sammelstandorte und mehreren Händlern zugeordnet:

Eine Anzeige an einem Sammelstandort erscheint deshalb mehrfach, einmal pro Händler.

Sonstiges

• Für die API-Anmeldung wird nur der Token gebraucht. user und pass im Runner bleiben leer.
• Neue Standorte oder Händler können nicht in Directus gepflegt werden. Sie stehen im Code (app/model/location.php, app/model/retailer.php). Nach einer Änderung lädt Neu aufbauen im Bereich „Händlerspeicher“ der Übersicht sie in den lokalen Speicher. Für die Änderung selbst ist eine Entwicklerin oder ein Entwickler nötig.

Der Crawler Hansalog Senger (HAS) liest die Stellen der Egon Senger GmbH.

Welche Anzeigen aufgenommen werden

1. Stellen-ID und Titel müssen gefüllt sein. Sonst: Warnung „Die Mindestanforderung an die Daten ist nicht erfüllt“.
2. Eine Senger-Anzeige kann mehreren Standorten zugeordnet sein. Für jeden Standort, der in der Standortliste von HAS bekannt ist, entsteht ein Eintrag.

Anders als bei HAL gibt es keinen Filter auf „Mercedes-Benz“. Für jeden unbekannten Standort einer Anzeige erscheint die Warnung „Die Location (…) ist nicht bekannt, oder gehört nicht zu Mercedes (…)“. In der Klammer am Ende steht hier der Standortname. Viele solcher Warnungen sind normal, weil Senger-Anzeigen oft auch an Standorten anderer Marken (z. B. Audi, VW, Skoda) veröffentlicht sind. Fehlt eine Mercedes-Anzeige auf der Seite, liegt es meist an einem Standort, der in der Liste fehlt.

Standorte

HAS kennt 29 Hansalog-Standorte (Kennungen beginnen mit A, z. B. A1005, A2100, A4000). Jeder Standort ist genau einem Händler zugeordnet.

Sonstiges

• Für die API-Anmeldung wird nur der Token gebraucht. user und pass im Runner bleiben leer.
• Neue Standorte oder Händler können nicht in Directus gepflegt werden. Sie stehen im Code (app/model/location.php, app/model/retailer.php). Nach einer Änderung lädt Neu aufbauen im Bereich „Händlerspeicher“ der Übersicht sie in den lokalen Speicher. Für die Änderung selbst ist eine Entwicklerin oder ein Entwickler nötig.

Alles, was diese Oberfläche anzeigt und ausführt, kommt aus Directus. Die Einrichtung erfolgt von oben nach unten.

1. Projekt und Provider

Die url muss die Adresse sein, unter der diese Oberfläche aufgerufen wird. Daran erkennt die Oberfläche, welcher Provider gemeint ist.

2. Crawler (data_crawler)

source und short bestimmen, welche Anzeigen in Solr zu einem Crawler gehören. Werden sie geändert, gelten alle bisherigen Anzeigen als fremd: Der nächste Lauf legt alle Anzeigen neu an, die alten bleiben zusätzlich stehen. Am besten beide Felder in Directus auf „nur lesen“ stellen.

3. Runner (crawler_config)

Pro Crawler und Modus beliebig viele Runner, z. B. einen für den API-Abruf nach Solr und einen zum Testen mit Dateien.

Zeitplan

Ein Runner startet automatisch, wenn schedule_enabled an ist, schedule_pattern gefüllt ist und der Crawler auf status: on steht. Das Muster hat fünf Stellen: Minute, Stunde, Tag, Monat, Wochentag.

Ein leeres Muster bedeutet „nur manuell“. Steht dort der Vorgabewert * * * * *, läuft der Runner nach dem Einschalten jede Minute. Ein ungültiges Muster wird nicht ausgeführt und im Cron-Log auf dem Server vermerkt. Mehrere Runner zur selben Zeit laufen getrennt voneinander. Bricht einer ab, laufen die anderen weiter.

Pflichtfelder

Vor jedem Lauf wird geprüft, ob alles Nötige gefüllt ist. Fehlt etwas, startet der Lauf nicht, und das Protokoll zeigt den Fehler „Der Runner (…) ist unvollständig, es fehlt: …“.

Beispiel: Dev-Runner HAL, API → Solr

Dateipfade sind relativ zum Projektordner auf dem Server. Wer Pfade aus einem anderen Projekt kopiert, schreibt in den falschen Ordner. Pfade immer auf data/hansalog-lueg/… bzw. data/hansalog-senger/… prüfen.

4. Dokumentation (docs)

Diese Seite. Ein Eintrag pro Kapitel mit title, content (Markdown), sort für die Reihenfolge, provider und optional crawler. Sichtbar sind nur Kapitel mit Status published.

Übersicht

Die Startseite zeigt alle Crawler des Providers mit Status, Runnern je Modus und dem Datum der letzten Änderung in Directus. Ein Klick auf eine Karte öffnet den Crawler. Zurück zur Übersicht geht es auf der Crawler-Seite über den Link mit dem Provider-Namen (z. B. „← Hansalog“) über dem Crawler-Namen oder über das Logo oben links.

Im Kopf der Übersicht steht der Händlerspeicher: die lokale Liste aller Händler und Standorte, denen die Anzeigen zugeordnet werden. Angezeigt werden Anzahl und Datum des letzten Aufbaus, auf jeder Crawler-Karte zusätzlich die Zahlen dieses Crawlers.

Neu aufbauen lädt die Listen aus dem Code neu, nach einer Rückfrage. Der bisherige Stand wird ersetzt, danach erscheint eine Bestätigung mit den neuen Zahlen. Nötig ist das nur, nachdem eine Entwicklerin oder ein Entwickler die Listen geändert hat.

Einen Lauf starten

1. Crawler öffnen.
2. Den Tab des Modus wählen (Dev, Stage, Live). Die Zahl am Tab zeigt, wie viele Runner es gibt.
3. Beim gewünschten Runner auf Starten klicken.

Während des Laufs zeigt der Button „Läuft …“, und alle anderen Start-Buttons sind gesperrt. Ein Lauf mit API und Solr kann je nach Datenmenge einige Sekunden bis Minuten dauern. Die Seite nicht neu laden, solange er läuft.

Bei Runnern mit Input API gibt es links neben „Starten“ einen zweiten Button (Pfeil nach unten). Er speichert die aktuelle API-Antwort unverändert in die Datei unter from_file, ohne etwas zu verarbeiten. Diese Datei kann danach ein Runner mit Input Datei zum Testen verwenden. Ist im Runner kein from_file angegeben, ist der Button ausgegraut.

Zeitplan ein- und ausschalten

Der Button mit dem Wecker links neben „Starten“ schaltet den Zeitplan des Runners ein oder aus. Die Änderung wird sofort in Directus gespeichert (schedule_enabled), die Seite muss nicht neu geladen werden.

• Grün: Der Zeitplan ist aktiv, der Runner startet automatisch nach seinem Muster.
• Hell: Der Zeitplan ist aus, der Runner startet nur über „Starten“.
• Ausgegraut: Im Runner ist kein schedule_pattern hinterlegt.

Bei Live-Runnern und bei Mustern, die mehrmals pro Stunde laufen (z. B. * * * * *), fragt die Oberfläche vor dem Einschalten nach. Unter den Details zeigt Zeitplan das Muster mit „aktiv“ oder „aus“, ohne Muster steht dort „nur manuell“.

Ist der Crawler deaktiviert, zeigt der Runner Deaktiviert statt „Starten“. Eingeschaltet wird er in Directus über status.

Das Protokoll lesen

Nach dem Lauf erscheint die Crawler-Seite wieder, unter den Runnern das Protokoll:

• Grüner Hinweis „Lauf beendet“: Der Lauf ist durchgelaufen. Warnungen sind möglich und meist normal.
• Roter Hinweis „Lauf fehlgeschlagen“: Der Lauf wurde nicht ausgeführt, siehe Fehlerzeilen.

Die wichtigsten CORE-Zeilen:

Das Protokoll wird einmal angezeigt. Nach dem Neuladen der Seite ist es weg. Auf dem Server steht es zusätzlich im Log unter logs/<source>/<Jahr>/<Monat>/<Tag>_out.log.

Dieses Kapitel richtet sich an Entwicklerinnen, Entwickler und den Betrieb.

Konfiguration

Alles Fachliche steht in Directus: Quelle, Ziel, Zielseite, Zugangsdaten und Zeitplan jedes Runners. Auf dem Server liegen nur noch:

Automatische Läufe (Cron)

Die System-Crontab ruft jede Minute php index.php /cron im Projektordner auf. Dabei werden alle Runner des Providers mit schedule_enabled und schedule_pattern aus Directus gelesen. Jeder fällige Runner startet in einem eigenen Prozess. Bei automatischen Läufen wird der Provider über die Kennung hansalog erkannt, nicht über die Adresse der Oberfläche.

Ausgeführte und ungültige Jobs stehen in logs/cron.log.

Fehler und Fehlermails

Schwere Fehler (ab 500, z. B. PHP-Fehler oder Directus nicht erreichbar) und jeder Fehler eines automatischen Laufs (z. B. API oder Solr nicht erreichbar) werden

1. mit dem bisherigen Protokoll des Laufs an protocol/fatal/<Jahr>/<Monat>/<Tag>_out_protocol.txt angehängt,
2. per Mail an die Empfänger aus notify_to geschickt, Betreff „Fehler (<Code>) Hansalog“.

Derselbe Fehler (gleicher Code, gleiche Adresse) erzeugt höchstens eine Mail pro Stunde, im Protokoll steht er jedes Mal. Fehler wie 404 (falsche Adresse) oder 403 (Seite veraltet) in der Oberfläche lösen keine Mail aus. Die Fehlerseite zeigt den Grund (DEBUG=1).

Standorte und Händler

Die Standort- und Händlerlisten stehen im Code (app/model/location.php, app/model/retailer.php). Nach einer Änderung lädt Neu aufbauen im Bereich „Händlerspeicher“ der Übersicht sie in den lokalen Speicher (data/fv_retailer.json, data/fv_location.json). Der bisherige Stand wird dabei ersetzt. Zugeordnet werden sie über das Feld source des Crawlers in Directus.

Dateien auf dem Server

<source> ist hansalog-lueg bzw. hansalog-senger.