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 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)”

}

2. 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.

3. 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

4. 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

5. 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.

6. 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
400	AOContextOID nicht angegeben
404	Schlüssel AOContextOID nicht vorhanden (in AOClassName)

7. 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

8. 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)

9. 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

10. 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:

Die Bildschirmfotos können in aktuellen Programmversionen visuell abweichen.

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