Mit Hilfe der Cordaware API Schnittstelle steht Ihnen eine sog. REST API zur Verfügung.
Prinzipiell werden alle Anfragen an die REST API mittels einer HTTP POST Anfrage an die Adresse Ihres Infoservers mit dem Pfad "/rest" gesendet. Sollte Ihr Infoserver beispielsweise unter "bestinformed.local" erreichbar sein und den Standard Port 8431 für die TLS gesicherte Verbindung nutzen, dann lautet die Adresse der REST API somit:
|
https://bestinformed.local:8431/rest |
Authentifizierung am Server
Um die API Schnittstelle nutzen zu können, ist eine Authentifizierung notwendig. Dies geschieht mit Hilfe eines Secrets, welches in einem Passwort Tresor abgespeichert wird.
Um einen Passwort Tresor anzulegen, öffnen Sie die Passwort App und klicken Sie auf das grüne "+" Icon um einen neuen Tresor zu erstellen.
Geben Sie nun einen Namen, eine optionale Beschreibung sowie ein Passwort für Ihren Tresor an und speichern Sie diesen ab.
|
Bitte beachten Sie, dass der Name des Passwort Tresors mit "rest_" beginnen muss! |
Der Hash des Passwortes muss im HTTP Header "X-Best-Auth" mitgesendet werden.
Der Algorithmus im Pseudocode berechnet diesen Header wie folgt:
|
Salt = random_string() |
Der Inhalt der Variable "XBestAuth" kann nun in den Header eingesetzt werden.
|
Bitte beachten Sie, dass aus Sicherheitsgründen ein Salt nur einmalig genutzt werden darf und für jede Anfrage erneut generiert werden sollte. |
Sollten die an den Server gesendeten Anmeldedaten falsch sein, wird die Verbindung geschlossen ohne eine Antwort zu senden. (ECONNCLOSED)
Anfragen an die API Schnittstelle
Die eigentliche Anfrage an die REST API wird im Body der POST Anfrage gesendet. Es muss sich hierbei um einen UTF8 JSON enkodierten String handeln welcher den Key "action" beinhaltet. Dieser gibt an welche Aktion seitens der API durchgeführt werden soll. Je nach gewählter Aktion können weitere erforderliche und optionale Keys hinzukommen.
|
Bitte beachten Sie, dass der Origin Header in Ihrer Anfrage mitgegeben werden muss. Im Origin Header muss sich die Adresse der verwendeten Webseite oder des Servers befinden, von welchem die REST API angesprochen wird. Diese müssen zusätzlich in den Systemeinstellungen unter System -> System (Global) hinterlegt werden.
 |
Beispiele
Im Folgenden sehen Sie eine Auflistung aller verfügbaren Aktionen, deren Keys und ein Beispiel dieser Anfrage:
Action: running
Gibt eine Liste aller derzeit aktiven Infos und deren Details aus.
Beispiel Anfrage:
{ "action": "running" } |
Hinweis:
In dieser Rückgabe sind keine abgebrochene Infos enthalten. Abgebrochene Infos lassen sich daran erkennen, dass diese den Key "canceled" mit einem Zeitstempel, an welchem diese abgebrochen wurden, enthalten.
Weitere verwendbare Keys:
•"skip" (integer) - Überspringt die ersten N Ergebnisse. (optional)
•"limit" (integer) - Limitiert die Anzahl der Ergebnisse auf maximal N. (optional)
•"begin" (date) - Nur Infos ab diesem Zeitpunkt werden angezeigt. (optional)
•"end" (date) - Nur Infos vor diesem Zeitpunkt werden angezeigt. (optional)
•"month" (integer) - Nur Infos aus diesem Monat werden angezeigt. (optional)
•"year" (integer) - Nur Infos aus diesem Jahr werden angezeigt. (optional)
•"canceled" (boolean) - Nur abgebrochene Infos werden angezeigt. (optional)
•"includerecipient" (boolean) - In der Rückmeldung ist ebenfalls die Anzahl von Gesendet (_sent), Antworten (_response) und Empfänger (_received) zu jeder Info enthalten. (optional)
Beispiel Antwort der API:
{ "type": "running", "count": 1, "result": [ { "_id": "bi-info_05affc0d82f97dbbaaebf45420674173", "timestamp": "2020-09-23T14:39:36Z", "end": "2020-09-23T14:42:36Z", "begin": "2020-09-23T14:39:36Z", "minutes": 5, "active": 3, "doc_user": "admin", "info_0": "Exchange Server heute ab 13:00 nicht mehr erreichbar!" // ... & viele weitere Keys gekürzt } ] } |
Action: all
Gibt eine Liste aller Infos und deren Details aus.
Beispiel Anfrage:
{ "action": "all" } |
Weitere verwendbare Keys:
•"skip" (integer) - Überspringt die ersten N Ergebnisse. (optional)
•"limit" (integer) - Limitiert die Anzahl der Ergebnisse auf maximal N. (optional)
•"begin" (date) - Nur Infos ab diesem Zeitpunkt werden angezeigt. (optional)
•"end" (date) - Nur Infos vor diesem Zeitpunkt werden angezeigt. (optional)
•"month" (integer) - Nur Infos aus diesem Monat werden angezeigt. (optional)
•"year" (integer) - Nur Infos aus diesem Jahr werden angezeigt. (optional)
•"includerecipient" (boolean) - In der Rückmeldung ist ebenfalls die Anzahl von Gesendet (_sent), Antworten (_response) und Empfänger (_received) zu jeder Info enthalten. (optional)
Action: history
Gibt eine Liste aller Infos aus der Infohistorie und deren Details aus.
Beispiel Anfrage:
{ "action": "history" } |
Weitere verwendbare Keys:
•"skip" (integer) - Überspringt die ersten N Ergebnisse. (optional)
•"limit" (integer) - Limitiert die Anzahl der Ergebnisse auf maximal N. (optional)
•"begin" (date) - Nur Infos ab diesem Zeitpunkt werden angezeigt. (optional)
•"end" (date) - Nur Infos vor diesem Zeitpunkt werden angezeigt. (optional)
•"month" (integer) - Nur Infos aus diesem Monat werden angezeigt. (optional)
•"year" (integer) - Nur Infos aus diesem Jahr werden angezeigt. (optional)
•"includerecipient" (boolean) - In der Rückmeldung ist ebenfalls die Anzahl von Gesendet (_sent), Antworten (_response) und Empfänger (_received) zu jeder Info enthalten. (optional)
Action: received
Liest alle Empfänger einer bestimmten Info aus. In dieser Rückgabe sind die Infoclients enthalten, welche die Info empfangen und den Erhalt bestätigt haben.
Beispiel Anfrage:
{ "action": "received", "myid": "bi-info_05affc7e3052da74c37b98e31eb83fc9" "limit": 1 } |
Hinweis:
Wenn die angesprochene Info nicht existiert, wird eine leere Liste zurückgegeben.
Weitere verwendbare Keys:
•"myid" (string) - Die ID der Info, deren Empfänger ausgelesen werden soll. (erforderlich!)
•"skip" (integer) - Überspringt die ersten N Ergebnisse. (optional)
•"limit" (integer) - Limitiert die Anzahl der Ergebnisse auf maximal N. (optional)
•"countonly" (boolean) - "True" gibt nur die Zählung ohne Ergebnisse zurück. (optional)
Beispiel Antwort der API:
{ "type": "receive", "count": 1, "result": [ { "version": "6.3.1.2", "username": "max.mustermann", "computername": "CW-TEST-427", "guid": "CW-TEST-427-D3-C5-1D-05-7A-3F-77-A3-1", "domain": "cordawaretest", "connected": "2020-09-23T09:47:53Z", "ssl": true, // ... & viele weitere Keys gekürzt } ] } |
Action: sent
Liest alle Infoclients aus, an welche der Infoserver eine bestimmte Info gesendet hat, unabhängig davon ob der Infoclient die Info erhalten hat. (Letzteres kann mit Hilfe der "received" Action durchgeführt werden)
Beispiel Anfrage:
{ "action": "sent", "myid": "bi-info_05affc90dfb0b5bca5b95223a1b207db" } |
Hinweis:
Wenn die Info deren Empfänger ausgelesen werden soll nicht existiert, wird eine leere Liste zurückgegeben.
Weitere verwendbare Keys:
•"myid" (string) - Die ID der Info, deren Empfänger ausgelesen werden soll. (erforderlich!)
•"skip" (integer) - Überspringt die ersten N Ergebnisse. (optional)
•"limit" (integer) - Limitiert die Anzahl der Ergebnisse auf maximal N. (optional)
•"countonly" (boolean) - "True" gibt nur die Zählung ohne Ergebnisse zurück. (optional)
Beispiel Antwort der API:
{ "type": "sent", "count": 1, "result": [ { "version": "6.3.1.2", "username": "erika.musterfrau", "computername": "CW-TEST-659", "guid": "CW-TEST-659-D3-C5-1D-05-7A-3F-77-A3-1", "domain": "cordawaretest", "connected": "2020-09-23T09:47:53Z", "ssl": true, // ... & viele weitere Keys gekürzt } ] } |
Action: response
Liest alle Antworten (response) auf eine bestimmte Info aus.
Beispiel Anfrage:
{ "action": "response", "myid": "bi-info_05affcab0c041377482976012ff9eda2" } |
Hinweis:
Anders als bei anderen Aktionen sind alle Keys der Antwort groß geschrieben (ausgenommen "date").
Weitere verwendbare Keys:
•"myid" (string) - Die ID der Info, deren Empfänger ausgelesen werden soll. (erforderlich!)
•"skip" (integer) - Überspringt die ersten N Ergebnisse. (optional)
•"limit" (integer) - Limitiert die Anzahl der Ergebnisse auf maximal N. (optional)
•"countonly" (boolean) - "True" gibt nur die Zählung ohne Ergebnisse zurück. (optional)
Beispiel Antwort der API:
{ "type": "response", "count": 2, "result": [ { "date": "2020-09-23T15:24:18Z", "computername": "CW-TEST-421", "username": "erika.mustefrau", "domain": "cordawaretest", "response": "Verstanden. Vielen Dank für die Information.", "os": "Windows" }, { "date": "2020-09-23T15:24:18Z", "computername": "CW-TEST-842", "username": "max.mustermann", "domain": "cordawaretest", "response": "Wann wird der Server wieder verfügbar sein?", "os": "Windows" } ] } |
Action: info
Liest alle Details zu einer spezifischen Info aus.
Beispiel Anfrage:
{ "action": "info", "myid": "bi-info_05b001f0231e517b5c2ab73d4387c796" } |
Weitere verwendbare Keys:
•"myid" (string) - Die ID der Info, deren Empfänger ausgelesen werden soll. (erforderlich!)
Beispiel Antwort der API:
{ "type": "info", "count": 1, "result": { "_id": "bi-info_05b001f0231e517b5c2ab73d4387c796", "end": "2020-09-24T09:55:46Z", "begin": "2020-09-24T09:55:46Z", "doc_editor": "", "minutes": 5, "showonuserdesktop": true, "doc_roles": [], "profile_id": "root", "active": 3, "cancloseonuserdesktop": true, "closeonclick": true, "cancloseonwinlogondesktop": true, "cancelonclose": true, "info_0": "Die Reinigungskräfte kommen heute aufgrund der Firmenfeier eine Stunde früher als üblich." // ... & viele weitere Keys gekürzt } } |
Action: newinfo
Mit Hilfe der newinfo Action können neue Infos erstellt werden.
Beispiel Anfrage:
{ "action": "newinfo", "info": "Hallo Welt von der REST API!", "minutes": "5", "active": "3" } |
Weitere verwendbare Keys:
•"isinifile" - Hiermit können Sie festlegen, dass Ihre Info eine Konfiguration an der Infoclient.ini der Empfänger vornimmt.
•"isinifiletext" - Hiermit können Sie die Infoclient.ini Einstellungen angeben, welche angepasst werden sollen.
|
Hinweis:
Zur Erstellung neuer Infos können Sie die Info bereits auf der Weboberfläche von Cordaware bestinformed erstellen und gestalten. Anschließend können Sie sich über den Button JSON->REST eine REST API Ansicht anzeigen lassen.
Den Inhalt der API Ansicht können Sie nun kopieren und in Ihrer API Anfrage verwenden. |
Beginn und Ende der Info festlegen.
Möchten Sie den Beginn und das Ende der Info festlegen, verwenden Sie die Schlüsselwörter "begin" und "end". Hier finden Sie ein Beispiel.
{ "begin": "01.01.2025 07:00:00", "end": "01.01.2025 15:30:00" } |
*diese Info beginnt am 01.01.2025 um 7 Uhr und endet am 01.01.2025 um 15:30 Uhr (UTC), für die tatsächliche Anzeigezeit berücksichtigen Sie Ihre Zeitzone.
Action: editinfo
Hiermit lassen sich Infos bearbeiten.
Beispiel Anfrage:
{ "action": "editinfo", "myid": "bi-info_e0fec51d1fff72fea4fe6e827ca3f9", "info": "Die Info wurden über die REST API bearbeitet!" } |
Weitere verwendbare Keys:
•"myid" (string) - Die ID der Info, deren Empfänger ausgelesen werden soll. (erforderlich!) - Beachten Sie hier, dass bei der Info ID der beginn "bi-info_" nicht mit angegeben wird!
Action: cancelinfo
Hiermit lassen sich Infos abbrechen.
Beispiel Anfrage:
{ "action": "cancelinfo", "myid": "bi-info_e0fec51d1fff72fea4fe6e827ca3f9" } |
Weitere verwendbare Keys:
•"myid" (string) - Die ID der Info, deren Empfänger ausgelesen werden soll. (erforderlich!)
Action: deleteinfo
Hiermit lassen sich Infos Löschen.
Hinweis:
Gelöschte Infos, welche bei einem Benutzer noch aktiv sind, werden auch weiterhin auf deren Bildschirmen dargestellt! Ein löschen der Info bricht eine Info auf den Bildschirmen nicht ab.
Beispiel Anfrage:
{ "action": "deleteinfo", "myid": "bi-info_e0fec51d1fff72fea4fe6e827ca3f9" } |
Weitere verwendbare Keys:
•"myid" (string) - Die ID der Info, deren Empfänger ausgelesen werden soll. (erforderlich!)
Action: copycancel
Hiermit lassen sich Infos entwarnen.
Hinweis:
Infos können nur entwarnt werden, wenn auch eine Entsprechende Entwarnung bei der Erstellung der Info mit angegeben wurde.
Beispiel Anfrage:
{ "action": "copycancel", "myid": "bi-info_e0fec51d1fff72fea4fe6e827ca3f9" } |
Weitere verwendbare Keys:
•"myid" (string) - Die ID der Info, deren Empfänger ausgelesen werden soll. (erforderlich!)