Freinet Online
64342 Burkhardtstraße 24
Seeheim-JugenheimGermany

Tel: +49 6257 - 5037290
.

Portal-API für Kooperationspartner

Mittels unserer Portal-API für Kooperationspartner können Sie die veröffentlichten Datensätze eines Engagement-Portals tagesaktuell beziehen, um sie z.B. auf Ihrer Homepage zu präsentieren.
Im Gegensatz zur Portal-API ermöglicht die Portal-API für Kooperationspartner den tagesaktuellen Download mehrerer KundenDaten (›Freiwilligenagenturen‹)

Das Beispiel-Skript welches Sie hier zum Download finden, ist umfangreich kommentiert.
Wenn Sie Fragen haben, können Sie uns gerne kontaktieren.

[download coming soon]
 

Technische Informationen zum Datenaustausch
auf Basis eines XML-Exports

Inhaltsverzeichnis

Allgemeine Informationen

In diesem Dokument wird der 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. Geplant ist eine Übertragung von ehrenamtlichen Tätigkeiten (im folgenden „Angeboten“) für engagementwillige Bürger.
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:

Mittels cronjob werden die XML-Dateien täglich in einem geschützten Verzeichnis bereitgestellt.

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.

Die Daten 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:

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.

2.3.1 kooperationspartner_agentur.xml

    <?xml version="1.0" encoding="UTF-8"?><agenturen count="6">
    <agentur>
     <id>52</id>
     <name>Musteragentur</name>
     <ag_adress_strasse>Hauptstrasse 12</ag_adress_strasse>
     <ag_adress_plz>26121</ag_adress_plz>
     <ag_adress_ort>Oldenburg</ag_adress_ort>
     <bundesland>9</bundesland>
     <ag_adress_tel_d>0815 7411</ag_adress_tel_d>
     <ag_adress_mail1>rademacher@freinet-online.de</ag_adress_mail1>
     <ag_adress_homepage>http://www.freinet-online.org</ag_adress_homepage>
     <beschreibung><![CDATA[
    <p>Beschreibung der Agentur</p> ]]></beschreibung>
     <ag_adress_anrede>1</ag_adress_anrede>
     <ag_adress_vorname>Wilhelm</ag_adress_vorname>
     <ag_adress_nachname>Muster</ag_adress_nachname>
     <ag_adress_geo_quality/>
     <ag_adress_geo_breite/>
     <ag_adress_geo_laenge/>
    </agentur>
    </agenturen>

2.3.2 kooperationspartner_einrichtung.xml

    <?xml version="1.0" encoding="UTF-8"?><einrichtungen count="1">
    <einrichtung>
     <id>1156</id>
     <agentur_id>52</agentur_id>
     <name>Kindergarten Flöhe e.V.</name>
     <traeger_name/>
     <adress_strasse>Am Festungsgraben 21</adress_strasse>
     <adress_plz>26135</adress_plz>
     <adress_ort>Oldenburg</adress_ort>
     <bundesland>7</bundesland>
     <adress_tel_d>06155-87878</adress_tel_d>
     <adress_mail1>Floh@online.de</adress_mail1>
     <adress_homepage>http://www.bild.de</adress_homepage>
     <beschreibung>Beschreibung des Kindergartens</beschreibung>
     <adress_anrede>0</adress_anrede>
     <adress_vorname/>
     <adress_nachname/>
     <geo_quality>8</geo_quality>
     <geo_breite>53.1367</geo_breite>
     <geo_laenge>8.21989</geo_laenge>
    </einrichtung>
    <einrichtung>
     <id>6381</id>
     <agentur_id>52</agentur_id>
     <name>AditestEinrichtung</name>
     <traeger_name>Demoagenturs
    Vereinsträger</traeger_name>
     <adress_strasse/>
     <adress_plz>34119</adress_plz>
     <adress_ort>Kassel</adress_ort>
     <bundesland>10</bundesland>
     <adress_tel_d>05251 11223344</adress_tel_d>
     <adress_mail1>info@freinet-online.de</adress_mail1>
     <adress_homepage>http://www.freinet-online.de</adress_homepage>
     <beschreibung><![CDATA[
    <p>Beschreibung der Einrichtung</p> ]]></beschreibung>
     <adress_anrede>1</adress_anrede>
     <adress_vorname>Tini</adress_vorname>
     <adress_nachname>Titus</adress_nachname>
     <geo_quality>0</geo_quality>
     <geo_breite>0</geo_breite>
     <geo_laenge>0</geo_laenge>
    </einrichtung>
    </einrichtungen>

2.3.3 kooperationspartner_angebot.xml

    <?xml version="1.0" encoding="UTF-8"?><angebote count="1">
    <angebot>
     <angebot_id>95718</angebot_id>
     <agentur_id>52</agentur_id>
     <gebot_name>ein Angebot</gebot_name>
     <einrichtung_id>27929</einrichtung_id>
     <adress_strasse>Wittingsbrok 24</adress_strasse>
     <adress_plz>26127</adress_plz>
     <adress_ort>Oldenburg</adress_ort>
     <bundesland>0</bundesland>
     <adress_tel_d>23456</adress_tel_d>
     <adress_mail1>huhu@example.org</adress_mail1>
     <adress_homepage/>
     <info><![CDATA[
<p>Beschreibung des Engagements</p> ]]></info>
     <adress_anrede>1</adress_anrede>
     <adress_vorname>Vorname</adress_vorname>
     <adress_nachname>Nachname</adress_nachname>
     <is_contactable>0</is_contactable>
     <geo_quality>8</geo_quality>
     <geo_breite>53.1588</geo_breite>
     <geo_laenge>8.19158</geo_laenge>
     <bef_von>0</bef_von>
     <bef_bis>0</bef_bis>
     <leistungen/>
    </angebot>
    <angebot>
     <angebot_id>95719</angebot_id>
     <agentur_id>52</agentur_id>
     <gebot_name>ein zweites Angebot</gebot_name>
     <einrichtung_id>27929</einrichtung_id>
     <adress_strasse>Wittingsbrok 24</adress_strasse>
     <adress_plz>26127</adress_plz>
     <adress_ort>Oldenburg</adress_ort>
     <bundesland>0</bundesland>
     <adress_tel_d>23456</adress_tel_d>
     <adress_mail1>huhu@example.org</adress_mail1>
     <adress_homepage/>
     <info><![CDATA[
    <p>Beschreibung des Engagements</p> ]]></info>
     <adress_anrede>1</adress_anrede>
     <adress_vorname>Vorname</adress_vorname>
     <adress_nachname>Nachname</adress_nachname>
     <is_contactable>0</is_contactable>
     <geo_quality>8</geo_quality>
     <geo_breite>53.1588</geo_breite>
     <geo_laenge>8.19158</geo_laenge>
     <bef_von>0</bef_von>
     <bef_bis>0</bef_bis>
     <leistungen/>
    </angebot>
    </angebote>

2.3.4 kooperationspartner_matching_nm.xml

    <?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 Run 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 ->is_contactable folgendes:


Fall 1 - WENN Angebot kontaktierbar

if($angebot->is_contactable==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

if(($angebot->is_contactable==0) 
{
  /*
   NUR die Adress- und Kontaktdaten der Freiwilligenagentur dürfen 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

/**
  * Array der Geschlechter
  */
  $ArrFreinetGender=array(
   '0'=>'',
   '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:

/**
* Array der Matchingkategorien
* (Auszug! Nach Absprache können weitere/abweichende Kategorien geliefert werden)
*/
$ArrFreinetMatchingkategorien=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:

/**
*    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:
$url=‘https://freinet-online.de/portal/visits_api.php‘.
          ‘?portalId=56‘. // Portal caritas-ehrenamt.de
     ‘&count_typ=621‘. // DetailAnsicht
     ‘&agencyId={AgenturID}‘. // MandantenID
     ‘&offerId={FreinetAngebotID}‘; // AngebotID

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