13 Weitere bereitgestellte Funktionen

In diesem Abschnitt werden weitere Funktionen und Aktionen erläutert, die ABES/Objects spezifisch vorhanden sind.
Es wird die jeweilige Funktionalität erläutert sowie die Aufrufsyntax und das Rückgabeergebnis beschrieben.

1. Funktion CheckHealth

Die Funktion prüft das ordnungemäße Funktionieren der OData-Schnittstelle und der Datenbank-Verbindung.
Sie wird ohne Parameter aufgerufen.

Beispielaufruf

Request
GET	http://test.server.de/odata/CheckHealth()

Rückgabe/Response

Im Erfolgsfall wird der Statuscode 200 (OK), andernfalls der Statuscode 503 (Service Unavailable) zurückgegeben.

2. Funktion GetVersions

Diese Funktion ist eine Diagnose-Funktion, die die aktuell vorhandenen Versionsstände ausliest und als Json-Objekt zurückliefert.

Diese Funktion hat keine Parameter und kann mit und ohne Autorisierung aufgerufen werden.

Beispielaufruf

Aufruf mit Autorisierung

Request
Header	Authorization: AbesObjects 123456…
GET	http://test.server.de/odata/GetVersions()

Rückgabe/Response

Response (Status=200)

{

“Versions”: {

“VersionOData”: “2.1.3”,

“VersionFramework”: “2.0.0.10215”,

“VersionDBfound”: “110206”,

“VersionDBrequired”: “10206”

}

Die Elemente geben Auskunft über die Versionen der verwendeten Odata-Schnittstelle, des Backend-Framworks und der aktiven Datenbank.

Außerdem wird die für das Backend-Framework benötigte Datenbank-Version ausgegeben.

Falls keine oder eine ungültige Autorisierung mitgegeben wurde, dann wird das Feld ” VersionDBfound” entsprechend gefüllt und die Angabe zu benötigten Datenbank fehlt.

Beispielaufruf

Aufruf ohne Autorisierung

Request
GET	http://test.server.de/odata/GetVersions()

Rückgabe/Response

Response (Status=200)

{

“Versions”: {

“VersionOData”: “2.1.3”,

“VersionFramework”: “2.0.0.10215”,

“VersionDBfound”: “? (not authorized)”

}

3. Funktion GetRoles

Mittels der Funktion GetRoles können die Rollen eines Objektes ermittelt werden.

Dazu sind der Schlüssel und der Klassenname des Objektes zu übergeben.

Parametername	Parametertyp	Beschreibung
_OID	string	Schlüssel des Objektes
Classname	string	Klasse, zu der das Objekt gehört

Beispielaufruf

Request

GET

http://test.server.de/odata/GetRoles(

_OID=’477167524F722B793545453746634932716D50793446′,

Classname=’Person’)

Rückgabe/Response

Im Beispiel würde folgende Auflistung der Rollen zum angefragten Objekt zurückgegeben werden:

Response (Status=200)

{

“Actor”: {

“_OID”: “477167524F722B793545453746634932716D50793446”,

“Classname”: “Person”

“Roles”: [

{

“_OID”: “48587862302F50775A495462732B6347322B43583178”,

“Classname”:”Anwender”

}

]

}

Dass Array “Roles” kann auch leer sein, falls keine Rollen für das angefragte Objekt definiert sind.

4. Funktion SetAssociation

Mittels der Funktion SetAssociation können Assoziationen auf Objekte aus anderen Entitäten gesetzt werden.

Da Navigations-Properties in OData für ABES/Objects nicht editiert werden können, wird die entsprechende Funktionalität mit dieser und der nachfolgenden Funktion (ClearAssociation) bereitgestellt.

Parametername	Parametertyp	Beschreibung
AOParentClassName	string	Klasse, zu der das Objekt gehört, das die Assoziation beinhaltet
AOParentItemOID	string	Schlüssel des Objektes, das die Assoziation beinhaltet
AOAssociationClassName	string	Klasse, zu der das assoziierte Objekt gehört
AOAssociationItemOID	string	Schlüssel des Objektes, das assoziiert werden soll

Beispielaufruf

Request

GET

http://test.server.de/odata/SetAssociation(

AOParentClassName=’Kurs’,

AOParentItemOID=’477167524F722B793545453746634932716D50793446′,

AOAssociationClassName=’KursTyp’,

AOAssociationItemOID=’475721679524F722B79354545374663548932716D5B0′)

Rückgabe/Response

Im Erfolgsfall wird folgende Struktur zurückgegeben:

Response (Status=200)

{

“status”: “succsess”,

“message” : “Association was set.”

}

Die nachfolgenden Bedingungen werden geprüft und ziehen ggf. Fehlermeldungen nach sich:

Http-Statuscode	Beschreibung
400	Unbekannte Entität für AOParentClassName
400	Unbekannte Entität für AOAssociationClassName
404	Schlüssel AOParentItemOID nicht vorhanden
404	Schlüssel AOAssociationItemOID nicht vorhanden
400	Angegebene Assoziation ist in der Parent-Entität nicht definiert
901 (app defined)	Änderung der Assoziation wurde durch das FrameWork aus fachlichen Gründen abgelehnt, Hinweis auf ABES/Objects-Ereignisprotokoll

5. Funktion ClearAssociation

Mittels der Funktion ClearAssociation können Assoziationen auf Objekte aus anderen Entitäten entfernt werden.

Da Navigations-Properties in OData für ABES/Objects nicht editiert werden können, wird die entsprechende Funktionalität mit dieser und der vorhergehenden Funktion (SetAssociation) bereitgestellt.

Parametername	Parametertyp	Beschreibung
AOParentClassName	string	Klasse, zu der das Objekt gehört, das die Assoziation beinhaltet
AOParentItemOID	string	Schlüssel des Objektes, das die Assoziation beinhaltet
AOAssociationClassName	string	Klasse, zu der das assoziierte Objekt gehört

Beispielaufruf

Request

GET

http://test.server.de/odata/ClearAssociation(

AOParentClassName=’Kurs’,

AOParentItemOID=’477167524F722B793545453746634932716D50793446′,

AOAssociationClassName=’KursTyp’)

Rückgabe/Response

Im Erfolgsfall wird folgende Struktur zurückgegeben:

Response (Status=200)

{

“status”: “succsess”,

“message” : “Association was cleared.”

}

Die nachfolgenden Bedingungen werden geprüft und ziehen ggf. Fehlermeldungen nach sich:

Http-Statuscode	Beschreibung
400	Unbekannte Entität für AOParentClassName
400	Unbekannte Entität für AOAssociationClassName
404	Schlüssel AOParentItemOID nicht vorhanden
400	Angegebene Assoziation ist in der Parent-Entität nicht definiert
901 (app defined)	Löschung der Assoziation wurde durch das FrameWork aus fachlichen Gründen abgelehnt, Hinweis auf ABES/Objects-Ereignisprotokoll

6. Funktion ReconnectDb

Es kann vorkommen, dass die Odata-Schnittstelle die Verbindung zum DB-Server verliert – bspw. weil vorübergehende Verbindungsprobleme zur Datenbank auftraten.
In diesem Fall liefert die Odata-Schnittstelle „
Internal Server Error
“ (Statuscode 500) zurück, obwohl der Request selbst fehlerfrei war.
In diesem Fall sollte ein Neu-Aufbau der DB-Verbindung mittels der Funktion ReconnectDb initiiert werden:

Request
GET	http://test.server.de/odata/ReconnectDb()

Die Funktion selbst erfordert keine Parameter.
Als Rückgabe erfolgt der Statuscode 200 (Ok), im Fehlerfall erneut der Statuscode 500.

7. Funktion GetFunctionsForClass

Die Funktion liefert eine Liste aller für den Typ aoClassName vorhandenen Funktionen.

Parametername	Parametertyp	Beschreibung
AOClassName	string	Objektklassen-Displayname des Datenkontexts z.B. “Anmeldung”, “Mitarbeiter”, “Teilnehmer” etc.

Beispielaufruf

Request

GET

http://test.server.de/odata/GetFunctionsForClass(

AOClassName=’GespraechsNotiz’

)

Rückgabe/Response

Im Erfolgsfall wird folgende Struktur zurückgegeben:

Response (Status=200)

{

“@odata.context”: “http://test.server.de/odata/$metadata#Edm.String”,

“value”: [

{

“_OID”: “9CD2B61E-ED30-459F-94B1-EC648D514193”

“DisplayName”: “TeilnehmerStunde erzeugen”

…

]

}

Die nachfolgenden Bedingungen werden geprüft und ziehen ggf. Fehlermeldungen nach sich:

Http-Statuscode	Beschreibung
400	AOClassName nicht abgegeben oder unbekannt

8. Funktion ExecuteFunction

Wendet die durch AOFunktionOID angegebene Funktion auf die Objektmenge representiert durch AOObjectOIDList an.

Parametername	Parametertyp	Beschreibung
AOClassName	string	Objektklassen-Displayname des Datenkontexts z.B. “Anmeldung”, “Mitarbeiter”, “Teilnehmer” etc.
AOFunctionOID	string	OID/OIDHex der anzuwendenden Funktion
AOObjectsOIDList	string	Komma-separierte Liste von OID- oder OIDHex-Werten der zu behandelnden Datenobjekte; kann – je nach Funktion – auch ein leerer String sein

Beispielaufruf

Request

GET

http://test.server.de/odata/ExecuteFunction(

AOClassName=’GespraechsNotiz’,

AOFunctionOID=’9CD2B61E-ED30-459F-94B1-EC648D514193′,

AOObjectsOIDList=’4870675846587A384E4A5A7170674D5870566A423473, 486F6B76304362366C4A4D4A2F7A385672396D54784B’

)

Rückgabe/Response

Im Erfolgsfall wird folgende Struktur zurückgegeben:

Response (Status=200)

{

“@odata.context”: “http://test.server.de/odata/$metadata#Edm.String”,

“value”: {

“count”: “2”,

“message”: “”

}

Falls die Funktion eine Liste der zu behandelnden Datenobjekte erwartet, beim Aufruf für AOObjectsOIDList aber ein leerer String übergeben wird, erfolgt keine Fehlermeldung.
Stattdessen enthält die Response eine entsprechende Message-Angabe “Keine OID-Liste für Datenobjekte übergeben”.

Die nachfolgenden Bedingungen werden geprüft und ziehen ggf. Fehlermeldungen nach sich:

Http-Statuscode	Beschreibung
400	AOClassName nicht abgegeben oder unbekannt
400	AOFunctionOID nicht angegeben

9. Funktion GetPropertyInfo

GetPropertyInfo liefert erweiterte Eigenschaften für die betreffende Property des übergebenen Objektes.
Mit Hilfe der Funktion kann so bspw. geprüft werden, ob eine bestimmte Eigenschaft für das betreffende Datenobjekt schreibgeschützt ist.

Parametername	Parametertyp	Beschreibung
AOClassName	string	Objektklassen-Displayname des Datenkontexts z.B. “Anmeldung”, “Mitarbeiter”, “Teilnehmer” etc.
AOObjectOID	string	OID/OIDHex des Datenobjektes
AOPropertyName	string	Name der Property, bspw. “Strasse” für ein Datenobjekt vom Typ “Anmeldung”

Beispielaufruf

Request

GET

http://test.server.de/odata/GetPropertyInfo(

AOClassName=’GespraechsNotiz’,

AOObjectOID=’457741737762564568477261786564622B2B484D7671′,

AOPropertyName=’Notiz’

)

Rückgabe/Response

Im Erfolgsfall wird folgende Struktur zurückgegeben:

Response (Status=200)

{

“@odata.context”: “http://test.server.de/odata/$metadata#Edm.String”,

“value”: {

“isReadOnly”: true,

“kind”: “string”

}

Die nachfolgenden Bedingungen werden geprüft und ziehen ggf. Fehlermeldungen nach sich:

Http-Statuscode	Beschreibung
400	AOClassName nicht abgegeben oder unbekannt
400 / 500	AOPropertyName nicht abgegeben oder ungültig
404	Datenobjekt mit der angegebenen OID nicht gefunden

10. Funktion GetWordTemplates

Die Funktion liefert eine Liste aller WordVorlagen des angegebenen Datenkontextes zurück. Eventuelle Anzeigebedingungen der WordVorlagen werden gegen das angegebene Kontext-Datenobjekt validiert.

Parametername	Parametertyp	Beschreibung
AOClassName	string	Objektklassen-Displayname des Datenkontexts z.B. “Anmeldung”, “Mitarbeiter”, “Teilnehmer” etc.
AOContextOID	string	OID/OIDHex der Objektinstanz, für welche die verfügbaren WordVorlagen ausgegeben werden sollen

Beispielaufruf

Request

GET

http://test.server.de/odata/GetWordTemplates(

AOClassName=’Mitarbeiter’,

AOContextOID=’45784E684B77725146486A3630772F52776933764934′

)

Rückgabe/Response

Im Erfolgsfall wird folgende Struktur zurückgegeben:

Response (Status=200)

{

“@odata.context”: “http://test.server.de/odata/$metadata#WordVorlage”,

“value”: [

{

“Name”: “Info für alle Mitarbeiter”,

“_OID”: “4870675846587A384E4A5A7170674D5870566A423473”

{

“Name”: “Betriebsvereinbarung”,

“_OID”: “486F6B76304362366C4A4D4A2F7A385672396D54784B”

}

]

}

Die nachfolgenden Bedingungen werden geprüft und ziehen ggf. Fehlermeldungen nach sich:

Http-Statuscode	Beschreibung
400	AOClassName nicht abgegeben oder unbekannt
400	AOContextOID nicht angegeben
404	Schlüssel AOContextOID nicht vorhanden (in AOClassName)

11. Funktion GetDocumentFromWordTemplate

Erzeugt ein Ausgabe-Dokument basierend auf der übergebenen WordVorlage mit den Daten des angegebenen Datenobjektes. Die verwendete Ablage und das erzeugte Dokument werden zurückgegeben. Der Aufrufer muss den Typ des gelieferten Dokumentes überprüfen – dies kann ein WordDokument oder eine Datei (PDF-Datei) sein.

Parametername	Parametertyp	Beschreibung
AOClassName	string	Objektklassen-Displayname des Datenkontexts z.B. “Anmeldung”, “Mitarbeiter”, “Teilnehmer” etc.
AOContextOID	string	OID/OIDHex der Objektinstanz, für welche die verfügbaren WordVorlagen ausgegeben werden sollen
AOWordTemplateOID	string	OID/OIDHex der zu verwendenden WordVorlage

Beispielaufruf

Request

GET

http://test.server.de/odata/GetDocumentFromWordTemplate(

AOClassName=’Mitarbeiter’,

AOContextOID=’45784E684B77725146486A3630772F52776933764934′,

AOWordTemplateOID=’4870675846587A384E4A5A7170674D5870566A423473′

)

Rückgabe/Response

Im Erfolgsfall wird folgende Struktur zurückgegeben:

Response (Status=200)

{

“Ablage”: {

“_OID”: “4654507A384D507A39457836374C2B542F6A624F656D”,

“_OIDHex”: null,

“Bez”: “Ablage Anmeldung Mustermann, Thomas …”,

“BesitzerName”: “Mustermann, Thomas …”,

“BesitzerTyp”: “Anmeldung”,

“_OwnerOID”: “45784E684B77725146486A3630772F52776933764934”

“Datei”: {

“_OID”: “474334626379634E4E4C484A78327838584C72466363”,

“_OIDHex”: “474334626379634E4E4C484A78327838584C72466363”,

“Bez”: “Info für alle Mitarbeiter”,

“OID_Ablage”: “4654507A384D507A39457836374C2B542F6A624F656D”

}

Die Angaben zur Ablage sind in der Response immer enthalten. Je nach WordVorlage sind zusätzlich entweder Details zur erstellten Datei (PDF-Datei) oder zum erzeugten WordDokument enthalten.

Die nachfolgenden Bedingungen werden geprüft und ziehen ggf. Fehlermeldungen nach sich:

Http-Statuscode	Beschreibung
400	AOClassName nicht abgegeben oder unbekannt
400	AOContextOID nicht angegeben
400	AOWordTemplateOID nicht angegeben
404	Schlüssel AOContextOID nicht vorhanden (in AOClassName)
404	Schlüssel AOWordTemplateOID nicht vorhanden (in “WordVorlage”)
500	Erzeugung des Dokumentes ist fehlgeschlagen

12. Funktion GetApplicationParameters

Die Funktion liefert den Wert des angegebenen Anwendungsparameters.
Innerhalb eines Anwendungsparameters können auch komplexe xml- oder json-Strukturen mit untergeordneten Einzelwerten hinterlegt werden.
Das kann insbesondere von Dritt-Anwendungen genutzt werden.
Falls Bedarf an weiteren Anwendungsparametern besteht, können diese nach Abstimmung mit Rackow-Software angelegt werden.

Parametername	Parametertyp	Beschreibung
AOParameterPropertyName	string	Bezeichnung des Anwendungsparameters

Beispielaufruf

Request

GET

http://test.server.de/odata/GetApplicationParameters(

AOParameterPropertyName=’DrittAnwendungSettings’

)

Rückgabe/Response

Im Erfolgsfall wird folgende Struktur zurückgegeben:

Response (Status=200)

{

“@odata.context”: “http://test.server.de/odata/$metadata#Edm.String”,

“value”: “#INHALT#”

}

Die nachfolgenden Bedingungen werden geprüft und ziehen ggf. Fehlermeldungen nach sich:

Http-Statuscode	Beschreibung
400	AOParameterPropertyName nicht abgegeben oder unbekannt

13. Aktion Upload

Für den Datei-Upload sind 2 Schritte notwendig:

Neu-Anlage oder Auswahl einer bestehenden AbesObjects-Entität, welcher die Datei zugeordnet werden soll;
Dies kann bpsw. eine neue oder bestehende Anfrage sein. Benötigt wird dann die OID der Entität.
Upload der Datei als “POST” mit Hilfe des folgenden Endpunktes: …/odata/Upload;
Die Datei selbst wird als Formdata im Body des Requests übertragen. Zusätzlich werden im Body noch die beiden Parameter „AblageKontextClassName“ und „AblageKontextOID“ benötigt. Die Werte der Parameter stellen den Bezug zur Entität in AbesObjects her, welcher die Datei zugeordnet wird. Der Wert „AblageKontextClassName“ bezeichnet die Klasse und der zweite Parameter die OID.

Zu beachten ist, dass im Header ein gültiges „Authorization“-Token mitgeschickt werden muss.

Im Erfolgsfall erhält man in der Response den Statuscode 201 und falls keine Daten übertragen wurden, den Statuscode 204. Mögliche Fehler sind:

401: nicht autorisiert
400: fehlender oder falscher Parameter (mit zusätzlichen Informationen)
500: interner Fehler (mit zusätzlichen Informationen)

Nachfolgend ein exemplarischer POST-Request über Postman:

14. AktionSetApplicationParameters

Die Funktion schreibt den Wert des angegebenen Anwendungsparameters.
Innerhalb eines Anwendungsparameters können auch komplexe xml- oder json-Strukturen mit untergeordneten Einzelwerten hinterlegt werden.
Das kann insbesondere von Dritt-Anwendungen genutzt werden.
Falls Bedarf an weiteren Anwendungsparametern besteht, können diese nach Abstimmung mit Rackow-Software angelegt werden.

Die benötigten Parameter müssen im Body des Requests übergeben werden.

Parametername	Parametertyp	Beschreibung
aoParameterPropertyName	string	Bezeichnung des Anwendungsparameters
value	string	Inhalt

Beispielaufruf

Request

POST

http://test.server.de/odata/SetApplicationParameters()

Body

{

“aoParameterPropertyName”: “DrittAnwendungSettings”,

“value”: “#INHALT#”

}

Rückgabe/Response

Im Erfolgsfall wird folgende Struktur zurückgegeben:

Response (Status=200)

{

“@odata.context”: “http://test.server.de/odata/$metadata#Edm.Boolean”,

“value”: true

}

Die nachfolgenden Bedingungen werden geprüft und ziehen ggf. Fehlermeldungen nach sich:

Http-Statuscode	Beschreibung
400	AOParameterPropertyName nicht abgegeben oder unbekannt

Die Bildschirmfotos können in aktuellen Programmversionen visuell abweichen.

Sie haben Fragen oder Anregungen? Schreiben Sie uns gerne an support@rackow-software.de