Inhaltsverzeichnis

• 1.      Allgemeine Informationen.
• 2.      Technischer Ablauf
• 2.1        Datentransfer (Vorschlag)
• 2.2        Adresse der XML-Dateien.
• 2.3        Kurzbeschreibung der Tabellen und Felder
• 2.3.1    kooperationspartner_agentur.xml
• 2.3.2    kooperationspartner_einrichtung.xml
• 2.3.3    kooperationspartner_angebot.xml
• 2.3.4    kooperationspartner_matching_nm.xml
• 2.3.5    kooperationspartner_matching.xml
• 2.4        Besondere Hinweise zu einigen Spalten
• 2.4.1    Kontaktierbarkeit der Einrichtungen / Angebote (Tabelle Angebote)
• 2.5        Sonstige Informationen.
• 2.5.1    Schlüssel der Spalte Anrede
• 2.5.2    Schlüssel der Matchingkategorien
• 2.5.3    Zahlenschlüssel der Bundesländer  (Tabellen Agentur, Einrichtung, Angebote)
• 3.         Bidirektionale Kooperationsmerkmale.
• 3.1        Previewlink zum ihrem Detail-Endpoint
• 3.2        Pageimpressions

 

 

Allgemeine Informationen

In diesem Dokument wird der mögliche Ablauf eines Datenaustausches auf Basis mehrerer XML Dateien skizziert.

Hierbei wird das System von Freinet Online beschrieben, mit dem Daten zu verschiedenen Drittanbietern fließen. Ziel ist hier die Übertragung von ehrenamtlichen Tätigkeiten (im folgenden „Angeboten“) für engagementwillige Bürger:innen.
Hierbei werden

• die Kerndaten der teilnehmenden Freiwilligenagenturen
• die Kerndaten der gelisteten Einrichtungen
• die Kerndaten der Angebote der gelisteten Einrichtungen
• die VermittlungsKategorien (Matchingkriterien)
  aus den Bereichen „Zielgruppen“, „Arbeitsweise“ etc
• sowie eine Tabelle mit m:n Verknüpfungen von Angebot-Matchingkriterien

übertragen.

Grundsätzlich ist dazu folgender Ablauf gedacht

• Der Daten-“Besitzer“ stellt die Daten als XML-Datei Dateien bereit.
• Der Daten-“ Bezieher“ verarbeitet die Daten weiter, um sie für die eigenen Datenbanktabellen aufzubereiten.
• Es folgen nun einige Vorschläge zum technischen Ablauf, die besonders für den/die Programmierer gedacht sind.

 

2. Technischer Ablauf

Der Austausch der Daten zwischen Daten-„Besitzer“ und Daten-„Bezieher“ kann wie folgt aussehen:

1. Mittels cronjob werden die XML-Dateien täglich in einem geschützten Verzeichnis bereitgestellt.
2. Der Daten-„Bezieher“ holt diese Daten zu sich und überträgt anschließend die Daten in geeigneter Form in die tatsächlichen Tabellen.

2.1 Datentransfer (Vorschlag)

Die Daten werden einmal täglich um ca 03.20 Uhr aktualisiert und können somit kurze Zeit später abgeholt werden.

 

2.2 Adresse der XML-Dateien

Die Dateien liegen in einem eigenen Verzeichnis bei Freinet-Online bereit.
Folgende Dateien stellen wir bereit, z.B. in folgendem Format:

kooperationspartner_agentur.xml
https://freinet-online.de/files/kooperationspartner/download.php?f=agentur

kooperationspartner_einrichtung.xml
https://freinet-online.de/files/kooperationspartner/download.php?f=einrichtung

kooperationspartner_angebot.xml
https://freinet-online.de/files/kooperationspartner/download.php?f=angebot

kooperationspartner_matching.xml
https://freinet-online.de/files/kooperationspartner/download.php?f=matching

kooperationspartner_matching_nm.xml
https://freinet-online.de/files/kooperationspartner/download.php?f=matching_nm

 

2.3 Kurzbeschreibung der Tabellen und Felder

Es folgt eine exemplarische Ansicht der gelieferten Dateien.
(Die Bezeichnungen der Keys sowie der Umfang können in der Version, die wir für Sie bereitstellen, abweichen)

2.3.1 kooperationspartner_agentur.xml

<?xml version="1.0" encoding="UTF-8"?>
<agenturen count="1">
    <agentur>
     <id>52</id>
     <name>Musteragentur</name>
     <agentur_strasse>Hauptstrasse 12</agentur_strasse>
     <agentur_plz>26121</agentur_plz>
     <agentur_ort>Oldenburg</agentur_ort>
     <bundesland>9</bundesland>
     <agentur_telefon>0815 7411</agentur_telefon>
     <agentur_mail>rademacher@freinet-online.de</agentur_mail>
     <agentur_homepage>http://www.freinet-online.org</agentur_homepage>
     <beschreibung><![CDATA[
    <p>Beschreibung der Agentur</p> ]]></beschreibung>
     <agentur_anrede>1</agentur_anrede>
     <agentur_vorname>Wilhelm</agentur_vorname>
     <agentur_nachname>Muster</agentur_nachname>
     <agentur_geo_breite/>
     <agentur_geo_laenge/>
    </agentur>
</agenturen>

2.3.2 kooperationspartner_einrichtung.xml

<?xml version="1.0" encoding="UTF-8"?>
<einrichtungen count="2">
    <einrichtung>
     <id>1156</id>
     <agentur_id>52</agentur_id>
     <einrichtung_name>Kindergarten Flöhe e.V.</einrichtung_name>
     <traeger_name/>
     <einrichtung_strasse>Hauptstrasse 0815</einrichtung_strasse>
     <einrichtung_plz>26135</einrichtung_plz>
     <einrichtung_ort>Oldenburg</einrichtung_ort>
     <einrichtung_bundesland>7</bundesland>
     <einrichtung_telefon>0441-123456</einrichtung_telefon>
     <einrichtung_mail>Floh@online.de</einrichtung_mail>
     <einrichtung_homepage>http://www.ihre-homepage.de</einrichtung_homepage>
     <einrichtung_beschreibung>Lorem ipsum...</einrichtung_beschreibung>
     <einrichtung_anrede>0</einrichtung_anrede>
     <einrichtung_vorname/>
     <einrichtung_nachname/>
     <einrichtung_geo_breite>53.1367</einrichtung_geo_breite>
     <einrichtung_geo_laenge>8.21989</einrichtung_geo_laenge>
    </einrichtung>
</einrichtungen>

2.3.3 kooperationspartner_angebot.xml

<?xml version="1.0" encoding="UTF-8"?>
<angebote count="2">
    <angebot>
     <angebot_id>95718</angebot_id>
     <agentur_id>52</agentur_id>
     <gebot_name>ein Angebot</gebot_name>
     <einrichtung_id>27929</einrichtung_id>
     <angebot_strasse>Winterallee 0815</angebot_strasse>
     <angebot_plz>26127</angebot_plz>
     <angebot_ort>Oldenburg</angebot_ort>
     <bundesland>0</bundesland>
     <angebot_telefon>23456</angebot_telefon>
     <angebot_mail>huhu@example.org</angebot_mail>
     <angebot_homepage/>
     <info><![CDATA[
<p>Beschreibung des Engagements</p> ]]></info>
     <angebot_anrede>1</angebot_anrede>
     <angebot_vorname>Vorname</angebot_vorname>
     <angebot_nachname>Nachname</angebot_nachname>
     <angebot_kontaktierbar>0</angebot_kontaktierbar>
     <angebot_geo_breite>53.1588</angebot_geo_breite>
     <angebot_geo_laenge>8.19158</angebot_geo_laenge>
     <angebot_bef_von>0</angebot_bef_von>
     <angebot_bef_bis>0</angebot_bef_bis>
     <angebot_leistungen><![CDATA[
        <ul><li>Haftpflichtversicherung</li>
        <li>Unfallversicherung</li></ul> ]]></angebot_leistungen>
     <angebot_anforderungen><![CDATA[
        <ul><li>Führungszeugnis</li>
        <li>Personenbeförderungsschein</li></ul> ]]></angebot_anforderungen>
    </angebot>
</angebote>

2.3.4 kooperationspartner_matching_nm.xml

Die ›id‹-Werte sind die KriterienId´s, die ›values‹ repräsentieren die AngebotId´s.

<?xml version="1.0" encoding="UTF-8"?>
<matching_nm>
     <arbeitsweise count="0"></arbeitsweise>
     <globalbereiche count="22">
         <v id="6">93285</v>
         <v id="6">97150</v>
         <v id="13">124758</v>
     </globalbereiche>
         <handlungsfelder count="65">
         <v id="4706">93285</v>
         <v id="4689">97151</v>
     </handlungsfelder>
     <zielgruppen count="42">
         <v id="5">93285</v>
         <v id="1418">93285</v>
         <v id="11">97150</v>
     </zielgruppen>
</matching_nm>

2.3.5 kooperationspartner_matching.xml

<?xml version="1.0" encoding="UTF-8"?><matching>
    <kat_arbeitsweise count="15">
     <arbeitsweise id="1">Arbeit eher alleine</arbeitsweise>
     <arbeitsweise id="2">Arbeit mit einzelnen Menschen</arbeitsweise>
     […]
     </kat_arbeitsweise>
     <kat_globalbereiche count="14">
     <globalbereiche id="1">Bildung</globalbereiche>
     <globalbereiche id="15">Bürgerengagement</globalbereiche>
     […]
     </kat_globalbereiche>
     <kat_handlungsfelder count="101">
     <handlungsfelder id="1">Arbeit &amp; Arbeitslosigkeit</handlungsfelder>
     <handlungsfelderid="20">Sucht</handlungsfelder>
     […]
     </kat_handlungsfelder>
     <kat_kenntnisse count="31">
     <kenntnisse id="1">Beratung</kenntnisse>
     <kenntnisse id="2">Betreuung / Begleitung</kenntnisse>
     […]
     </kat_kenntnisse>
     <kat_sprachen count="40">
     <sprachen id="1">Afghanische Sprache</sprachen>
     <sprachen id="2">Afrikanische Sprache</sprachen>
     […]
     </kat_sprachen>
     <kat_zielgruppen count="31">
     <zielgruppen id="1">Alleinerziehende</zielgruppen>
     <zielgruppen id="2">Angehörige</zielgruppen>
     […]
     </kat_zielgruppen>
 </matching>

 

2.4 Besondere Hinweise zu einigen Spalten

Einige Elemente bedürfen besonderer Erklärung, es folgen einige Hinweise

2.4.1 Kontaktierbarkeit der Einrichtungen / Angebote (Tabelle Angebote)

Einige Agenturen möchten, dass der Erstkontakt zwischen dem Freiwilligen und dem Angebot ÜBER die Freiwilligenagentur läuft. Z.B.

• um die Einrichtung vor einem „Ansturm Engagementwilliger Personen“ zu schützen,
• um die Kontrolle zu haben, dass nur „ausgewählte“ Freiwillige dieses Angebot kontaktieren,
• um eine Statistik zur Anzahl der Vermittlungen erheben zu können.
  („Wie erfolgreich haben wir vermittelt“)

Deswegen bedeutet die Spalte angebot ->angebot_kontaktierbar folgendes:

Fall 1 - WENN Angebot kontaktierbar

<?php
if($angebot->angebot_kontaktierbar==1)
 {
  /*
   1. Alle Kontaktinformationen zur Einrichtung / zum Angebot
   (Adresse, Telefon, Vor- Nachname etc) dürfen preisgegeben werden!
   2. Die Informationen zur bereitstellenden Freiwilligenagentur dürfen
   „ganz unten“ [Am Ende der Details] ruhig auch nochmal erwähnt werden.
   (Z.B „Bereitgestellt durch die Freiwilligenagentur XY“)
  */
  }
?>

Fall 2 - WENN Angebot NICHT kontaktierbar

<?php
if($angebot->angebot_kontaktierbar==0)
  {
    /*
     * NUR die Adress- und
     * Kontaktdaten der Freiwilligenagentur
     * dürfen (sollten) preisgegeben werden.
    */
  }
?>

 

2.5 Sonstige Informationen

2.5.1 Schlüssel der Spalte Anrede

Das Geschlecht der Ansprechpartner in den Spalten `anrede` ist wie folgt definiert

<?php
/**
  *    Array der Geschlechter
  */
  $freinet_gender_keys=array(
        1=>'Männlich/Herr',
        2=>'Weiblich/Frau',
        3=>'Eheleute',
        4=>'Divers'
  );

2.5.2 Schlüssel der Matchingkategorien

In der Tabelle `kooperationspartner_matching.xml` finden sich die Kategorien der Matchingkategorien, die unter dem Element kriteriumgruppe_id zusammgefasst sind.

Die Schlüssel ergeben wie folgt:

<?php
/**
  *    Array der Bundesland-Schlüssel von Freinet Online
  */
  $freinet_bundesland_keys=array(
        501=>'arbeitsweise',
        502=>'globalbereiche',
        504=>'handlungsfelder',
        506=>'kenntnisse',
        509=>'sprachen',
        511=>'zielgruppen'
  );

Ein „Knackpunkt“ beim Datenaustausch zwischen den Kooperierenden Parteien dürfte die Vielzahl der Matchingkriteriumskategorien (z.B. Zielgruppe Senioren, Familie, Schüler etc.) sein.

Jede Freiwilligenagentur hat bei Freinet Online die Möglichkeit auf einen vorgefertigten Katalog von Kriterien zurückzugreifen. Darüber hinaus kann jede Agentur eigene Kriterien erstellen. Daraus folgt, dass es eine ziemlich große Zahl von Kriterien gibt, die mitunter sogar Agenturübergreifend doppelt eingetragen sind.

Vielleicht ist es eine gute Idee, eine Art Matrix zu erstellen, mittels der die Freinet-Online-Kategorien zu (bestehenden) AktionMensch/betterplace.org Kriterien portiert werden, z.B:

Freinet-Online		Ihr Portal
„Alte Menschen“ „SeniorInnen“ „Senioren/Seniorinnen“		„Senioren“

2.5.3     Zahlenschlüssel der Bundesländer
(Tabellen Agentur, Einrichtung, Angebote)

Freinet liefert in der Spalte `bundesland` eine Zahl. Der Schlüssel lautet wie folgt:

<?php
/**
  *    Array der Bundesland-Schlüssel von Freinet Online
  */
  $freinet_bundesland_keys=array(
        1=>'Baden-Württemberg',
        2=>'Bayern',
        3=>'Berlin',
        4=>'Brandenburg',
        5=>'Bremen',
        6=>'Hamburg',
        7=>'Hessen',
        8=>'Mecklenburg-Vorpommern',
        9=>'Niedersachsen',
        10=>'Nordrhein-Westfalen',
        11=>'Rheinland-Pfalz',
        12=>'Saarland',
        13=>'Sachsen',
        14=>'Sachsen-Anhalt',
        15=>'Schleswig-Holstein',
        16=>'Thüringen');

2.5.4  Leistungen (Tabelle Angebote)

Die Leistungen eines Angebotes werden als html Liste geliefert.

<ul>
<li>Haftpflichtversicherung</li>
<li>Unfallversicherung</li>
<li>kostenloser Mittagstisch</li>
...
</ul>

 

3. Bidirektionale Kooperationsmerkmale

In Freinet haben die Mandanten die Möglichkeit, ihre Daten auf mehreren Portalen zu veröffentlichen („eigene Homepage“, Aktion Mensch, AnpackerApp, Let´s Act, etc.)

Um den Freiwilligenagenturen weiteren Service und Anreiz zum „mitmachen in Ihrem Portal“ zu bieten, können zweierlei Dinge eingerichtet werden.

 

3.1 Previewlink zum ihrem Detail-Endpoint

In Freinet haben die Mandanten die Möglichkeit, ihre Daten auf mehreren Portalen zu veröffentlichen („eigene Homepage“, Aktion Mensch, AnpackerApp, Let´s Act, etc.)

Für die meisten dieser Portale haben wir einen PreviewLink ermöglichen können, der einen direkten Sprung zum Detail-Endpoint ermöglicht.

Gerne würden wir auch zu Ihrem Portal einen solchen Preview-Link einrichten.
Hierfür sind wahrscheinlich zwei Dinge notwendig:

1. Erste Voraussetzung ist sicherlich, daß die Primär-ID des Angebotes bei Ihnen gespeichert wird, da Freinet die PrimärID des Angebotes in ihrem Portal ja nicht kennt.
2. Zweite Voraussetzung wäre eine Weiterleitung zu ihrem Detailansicht-Endpoint.
   
   Ein Preview-Link aus Freinet könnte zum Beispiel folgendermaßen lauten:
   
   exemplarisch: https://ihr-portal.de/forward_freinet/{angebot_id}
   (Dieser Link leitet dann zu ihrem Endpoint weiter)
   
   oder direkt zum Detailansicht-Endpoint:
   
   exemplarisch: https://ihr-portal.de/ehrenamtssuche/detail.php?freinet_id={angebot_id}

 

3.2 Pageimpressions

Wenn ein Angebot von Freinet in Ihrem Portal aufgerufen wird (Detail-Endpoint), können Sie uns einen „Ping“ über die Page-Impression senden.
Freinet zählt lediglich die Page-Impression und bietet den Mandanten eine entsprechende, einfache Statistik. Dem Mandanten wird damit eine Orientierungshilfe geboten, um sein Angebotsportfolio zu optimieren.

Sie können die Pageimpression z.B. folgendermaßen übertragen:

<?php
$url="https://freinet-online.de/portal/visits_api.php".
"?portalId={portalId}". // PortalID
"&count_typ={count_typ}". // Zähler-Kategorie
"&agencyId={AgenturID}". // MandantenID
"&offerId={FreinetAngebotID}" // AngebotID

// Übertragung der PageImpression an Freinet  z.B. via cURL
if($AngebotVonFreinet==true) curl_get($url);