FM2.0 API Playground
Domain
Instanz
Sprache

Einleitung

Verwendung der FM2.0 API

Austausch von Informationen zwischen Kunden mit Beratungsbedarf zum Thema Grenzüberschreitung und Beratern von Grenzinfopunkten.

Diese Testumgebung dient der Dokumentation der Schnittstelle des FM-Systems. Durch kurze Codebeispiele wird die Ansteuerung der Endpoints erläutert.

Der Programmablauf sowie der Datenaustausch und der Aufbau der JSON-Objekte können über die Dev-Tools des Browsers analysiert werden.

Header

Bei jeder Anfrage muss im Request-Header das Kürzel der Instanz mitschickt werden. Dies geschieht über den Bezeichner "X-GIP". Beispiel:

const HEADERS = { "X-GIP": "demo", "Accept": "application/json", "Content-Type": "application/json" }

API-Endpoints

Formularfelder zur Erfassung eines neuen Falles holen:
GET https://crm-staging.grenzinfo.eu/api/api/ext/form/{language}

Neuen Fall mit Daten aus Formular erzeugen:
POST https://crm-staging.grenzinfo.eu/api/api/ext/case/

Bestehenden Fall anhand der Fall-ID holen:
GET https://crm-staging.grenzinfo.eu/api/api/ext/case/{case_id}

Persönliche Daten im Fall aktualisieren:
PUT https://crm-staging.grenzinfo.eu/api/api/ext/case/{case_id}

Beitrag/Kommentar verfassen:
POST https://crm-staging.grenzinfo.eu/api/api/ext/comment/{case_id}

Scripts

Die JS-Codebeispiele sind in drei Scripts enthalten:

  • js/main.js Click-events der Buttons und Aufruf der fetch-Methoden der FMConnector-Klasse
  • js/fmconnector.js Klasse mit Methoden zum Aufruf der Endpoints
  • js/renderer.js Erzeugung der DOM-Elemente zur Darstellung der Formulfelder

Zum besseren Verständnis ist der Source-Code einfach gehalten und in nativem JS geschrieben. Zudem wird auf jegliche Abhängigkeiten verzichtet.
Lediglich zur Bedienung der Oberfläche sowie zum Styling wird das Bootstrap-Framework verwendet.

Sonstiges

In der Seitenleiste können Parameter zur Rückgabe definiert werden:

Instanz Das Kürzel des regionalen Grenzinfopunktes (z.B. emra = Euregio Maas/Rhein Aachen)
Sprache Formularfelder, Labels und Optionen werden in der entspr. Spache ausgeliefert
Fall-ID Eindeutige ID zum Abrufen eines Falles

Fall holen/anzeigen

Holt einen Fall anhand seiner Fall-ID

  • Aufruf der getCase()-Methode in main.js
  • GET-Request an /api/ext/case/{case_id}/-Endpoint per getCase()-Klassenmethode
  • Erzeugung der DOM-Ausgabe

Rückgabe: JSON || Error

Neuer Fall

Formular zur Eingabe eines neuen Falles holen

  • Aufruf der loadForm()-Methode in main.js
  • GET-Request an /api/ext/form/{language}/-Endpoint per getRequestForm-Klassenmethode
  • Erzeugung der Formularfelder mit renderForm

Beim Absenden wird ein neuer Fall erzeugt und eine Fall-ID zurückgeliefert. Diese Fall-ID wird in der Sidebar eingetragen. Der neue Fall kann dann über "Fall anzeigen" geholt werden.

Hinweis: Um Fälle später wieder aufrufen zu können, sollten neu erzeugte Fall-IDs notiert werden, da diese nicht lokal gespeichert werden.

Push-Benachrichtigung

Bei Änderungen am Fall durch Berater (z.B. neue Nachricht) wird ein POST-Request (mit JSON) an einen externen API-Endpoint geschickt.

Der aufzurufende Endpoint kann in den Einstellungen des CRM hinterlegt werden.

 

Fall bearbeiten

Holt das Fallformular und füllt Felder mit Falldaten

  • Aufruf der editCase()-Methode in main.js
  • Holen der Falldaten mit getCase() in main.js
  • Holen des Fallformulars mit Übergabe der Falldaten mit loadForm() in main.js
  • GET-Request an /api/ext/form/{language}/-Endpoint per getRequestForm-Klassenmethode
  • Erzeugung des Formularfelder incl. Werten (renderForm())

Beim Absenden werden die Fromluardaten per updateCase()-Klassenmethode als PUT-Request an /case/{case_id}/ gesendet. Als Antwort wird der komplette aktualisierte Fall als JSON-Objekt zurückgegeben.

Rückgabe: JSON || Error

Antwort schreiben

Verfassen einer Antwort im Kontext des Kunden.
Die Antwort wird dem aktuellen Fall hinzugefügt und kann über Fall anzeigen -> Fall holen angezeigt werden.

  • Aufruf der addComment()-Methode in main.js
  • PUT-Request an /api/ext/comment/{case_id}-Endpoint über createComment()-Klassenmethode

Rückgabe: True || Error

Upload

Dokument hochladen
Über das Upload-Formular kann eine Datei hochgeladen werden. Der Upload erscheint anschließend unter "Dokumente" über Fall anzeigen -> Fall holen.

  • Aufruf der addAttachment()-Methode in main.js
  • PUT-Request an /api/ext/cases/${case_id}/documents/-Endpoint über addAttachment()-Klassenmethode

Rückgabe: True || Error

Download

Dokument holen
Mit der ID des Dokumentes kann dieses heruntergeladen werden

  • Aufruf der getAttachment()-Methode in main.js
  • GET-Request an /api/ext/cases/${case_id}/documents/${document_id}-Endpoint über getAttachment()-Klassenmethode

Rückgabe: Binary || Error

Update Event Trigger

Wenn neue Nachrichten im System bereitstehen oder Erinnerungen für Termine anstehen, wird ein POST-Request an einen Endpoint ausgelöst.
Um den Empfang des Requests zu testen, kann dieser hier manuell ausgelöst werden. Geben Sie einen Endpoint ein, an den der Request geschickt werden soll.

Fetch/XHR Log

Ausgabe