CommSy-SOAP
Im Folgenden finden Sie Informationen zur SOAP-Schnittstelle von CommSy (ab Version 6.1.3).
Was ist SOAP?
SOAP (ursprünglich für Simple Object Access Protocol) ist ein Protokoll, mit dessen Hilfe Daten zwischen Systemen ausgetauscht und Remote Procedure Calls durchgeführt werden können. SOAP stützt sich auf die Dienste anderer Standards, XML zur Repräsentation der Daten und Internet-Protokolle der Transport- und Anwendungsschicht zur Übertragung der Nachrichten. Die gängigste Kombination ist SOAP über HTTP und TCP. Die Abkürzung SOAP wird jedoch offiziell seit Version 1.2 nicht mehr als Abkürzung gebraucht, da es erstens (subjektiv) keineswegs einfach (Simple) ist und da es zweitens nicht (nur) dem Zugriff auf Objekte (Object Access) dient.
Mehr zu SOAP erfahren Sie unter http://de.wikipedia.org/wiki/SOAP.
Requirements
Auf dem CommSy-Server muss die SOAP-Extension bei PHP (>= 5.0.0) aktiviert sein.
- Linux / Unix: Aktivierung in der SOAP-Extension in der php.ini durch extension=php_soap.so.
- Windows: Aktivierung in der SOAP-Extension in der php.ini durch extension=php_soap.dll.
Stellen Sie sicher, dass die entsprechende PHP-SOAP-Bibliothek auf Ihrem System vorhanden ist.
Generell
SOAP ist "nur" ein Tür, über die Methoden zur Verfügung gestellt werden können. Welche Methoden dies sind, müssen Sie entweder wissen bzw. erfahren Sie über eine WSDL-Datei. In dieser sind alle über SOAP angebotenen Methoden definiert ... so auch bei CommSy.
D.h. generell haben Sie zwei Möglichkeiten, sich mit dem CommSy-Server via SOAP zu verbinden:
- ohne WSDL
- mit WSDL
ohne WSDL
Hier ein Beispiel zur Verbindung mit dem CommSy-Server ohne WSDL-Datei (in PHP):
$url = 'http://URL.COMMSY.SERVER/soap.php';
$uri = 'urn:xmethodsCommSy';
$client = new SoapClient(null, array( 'location' => $url, 'uri' => $uri, 'style' => SOAP_RPC, 'use' => SOAP_ENCODED ) );
Eine spezielle Methode (hier die Authentifizierung) muss dann wie folgt angesprochen werden:
$params1 = array(
new SoapParam($a, 'user_id'),
new SoapParam($b, 'password'),
new SoapParam($c, 'portal_id')
);
$params2 = array("uri" => $uri,"soapaction" => $uri."#authenticate");
$result = $client->__soapCall("authenticate",$params1,$params2);
Einfacher geht es mit der Nutzung der WSDL-Datei.
mit WSDL
Hier ein Beispiel zur Verbindung mit dem CommSy-Server mit WSDL-Datei (in PHP):
$url = 'http://URL.COMMSY.SERVER/soap_wsdl.php'; //
soap_wsdl.php nicht nur soap.php
$client = new SoapClient($url, array('exceptions' => 0));
// exceptions = 0 - exceptions werden als Objekt zurück gegeben
Eine spezielle Methode (hier die Authentifizierung) wird dann wie folgt angesprochen:
$result = $client->authenticate('user_id','password','portal_id');
Im Folgenden beziehen sich die weiteren Informationen und Beispiele immer auf die Verwendung der WSDL-Datei und sind in der Scriptsprache PHP verfasst.
Achtung: SOAP setzt zwingend eine Codierung in utf8 voraus, d.h. alle Input-Daten müssen im utf8-Format kodiert sein und alle Output-Daten sind im utf8-Format kodiert. D.h. ggf. müssen bei der Parameterübergabe bzw. der Ergebnisverarbeitung die Werte umkodiert werden.
Authentifizierung
Mit der Methode authenticate authentifiziert sich ein Nutzender mit seiner Kennung und Passwort an einem CommSy-Portal. Die Angabe einer Portal-ID ist hier zwingend, da der CommSy-Server autarke Instanzen (CommSy-Portale) zur Verfügung stellt und sich Nutzenden nicht am Server direkt sondern nur an Portalen anmelden können.
Überblick:
Input:
- user_id (string) - Kennung eines Nutzenden
- password (string) - das zur Kennung passende Passwort
- portal_id (integer) - die Item-ID des Portals, an dem sich der Nutzende anmelden will
Output:
- Erfolg: session_id (string) - Session-ID zu einer gültigen Session.
- Fehler: soap_fault (object) - SOAP-Fehlerobjekt mit Informationen zum Fehler
Anwendung:
$result = $client->authenticate('user_id','password','portal_id');
Achtung: Um die verschiedenen folgenden Methoden über die SOAP-Schnittstelle nutzen zu können, ist eine gültige Session nötig. D.h. die Authentifizierungsmethode muss immer als erstes bei der Kommunikation über die SOAP-Schnittstelle aufgerufen werden, so dass die Session-ID bei den folgenden Methoden als Übergabeparameter genutzt werden kann.
Materialaustausch
Es existieren verschiedene Methoden zum Austausch von Materialien zwischen CommSy und einer externen Applikation. Generell gilt zurzeit, dass Materialien zwischen CommSy und einer externen Applikation nur über den persönlichen Raum eines Nutzenden ausgetauscht werden können. Ausnahmen bestätigen die Regel.
getPrivateRoomMaterialList
Die Methode getPrivateRoomMaterialList ermöglicht den lesende Zugriff auf die Materialien im persönlichen Raum eines Nutzenden auf einem CommSy-Portal.
Bedingungen:
- Gültige Session-ID - Kennung, Portal und persönlichen Raum sucht sich CommSy aus den Daten in der Session.
Überblick:
Input:
- session_id (string) - Session-ID zu einer gültigen Session des Nutzenden
Output:
- Erfolg: xml_material_list (string) - Liste der Materialien in XML-Notation.
- Fehler: soap_fault (object) - SOAP-Fehlerobjekt mit Informationen zum Fehler
Anwendung:
$result = $client->getPrivateRoomMaterialList('session_id');
Detaillierter Output im Erfolgsfall:
<material_list>
<material_item>
<item_id>276963</item_id>
<version_id>0</version_id>
<context_id>235366</context_id>
...
<title>Hallo Die Enten</title>
<description>Eine tolle Beschreibung</description>
...
<extras>
<study_log></study_log>
</extras>
sofern gesetzt erscheinen auch folgende Inhalte
<bib_kind>book</bib_kind>
<common>Allgemeine bibliografischen Angaben</common>
<booktitle>Das große Entenbuch</booktitle>
<publisher>Hamburg University Press</publisher>
<address>Hamburg</address>
<volume>4</volume>
<series>13</series>
<isbn>3608935444</isbn>
<issn>978-3608935448</issn>
<pages>12-24</pages>
<journal>26</journal>
<issue>3</issue>
<university>Universität Hamburg</university>
<faculty>MIN-Fakultät</faculty>
<thesis_kind>dissertation</thesis_kind>
<url>http://service.commsy.net</url>
<url_date>26.03.2007</url_date>
<date>
<day></day>
<month></month>
<year>2010</year>
</date>
<author_list>
<author_item>Jackewitz, Iver</author_item>
...
</author_list>
<editor_list>
<editor_item>Jackewitz, Iver</editor_item>
...
</editor_list>
<keyword_list>
<keyword_item>CommSy</keyword_item>
...
</keyword_list>
<label>Hausaufgabe</label>
</material_item>
<material_item>
...
</material_item>
...
</material_list>
Die Werte für bib_kind sind:
- none
- common
- book
- collection
- incollection
- article
- inpaper
- thesis
- manuscript
- website
Die Werte für thesis_kind sind:
- term
- bachelor
- master
- exam
- diploma
- dissertation
- postdoc
getSectionListFromMaterial
Mit der Methode getSectionListFromMaterial ist der lesende Zugriff auf die an ein Material angehängten Abschnitte möglich.
Bedingungen:
- Gültige Session-ID
- Kennung muss lesenden Zugriff auf das Material haben, d.h. Mitglied im entsprechenden Raum sein.
Überblick:
Input:
- session_id (string) - Session-ID zu einer gültigen Session des Nutzenden
- material_id (integer) - Item-ID des Materials
Output:
- Erfolg: xml_file_list (string) - Liste der Abschnitte des Materials in XML-Notation.
- Fehler: soap_fault (object) - SOAP-Fehlerobjekt mit Informationen zum Fehler
Anwendung:
$result = $client->getSectionListFromMaterial('session_id','material_id');
Detaillierter Output im Erfolgsfall:
<section_list>
<section_item>
<item_id>753239</item_id>
...
<title>Meine Hausaufgaben</title>
<description>... hab ich nicht gemacht.</description>
</section_item>
<section_item>
...
</section_item>
...
</section_list>
getFileListFromItem
Mit der Methode getFileListFromItem ist der lesende Zugriff auf die an irgendeinen Eintrag in CommSy angehängten Dateien möglich.
Achtung: Es werden hier nur die Metadaten der Dateien übertragen, nicht die Dateien selbst. Da potentiell sehr viele Dateien an einem Eintrag angehängt sein können, muss sich die Datei einzeln mit der Methode getFileItem geholt werden. So kann dem Nutzenden auf Seiten des externen Tools Feedback über den Downloadstatus gegeben werden.
Bedingungen:
- Gültige Session-ID
- Kennung muss lesenden Zugriff auf den Eintrag haben, d.h. Mitglied im entsprechenden Raum sein.
Überblick:
Input:
- session_id (string) - Session-ID zu einer gültigen Session des Nutzenden
- item_id (integer) - Item-ID des Eintrags in CommSy
Output:
- Erfolg: xml_file_list (string) - Liste der Dateien des Materials in XML-Notation.
- Fehler: soap_fault (object) - SOAP-Fehlerobjekt mit Informationen zum Fehler
Anwendung:
$result = $client->getFileListFromItem('session_id','item_id');
Detaillierter Output im Erfolgsfall:
<file_list>
<file_item>
<files_id>39264</files_id>
...
<filename>iver_jackewitz.jpg</filename>
<md5>d41d8cd98f00b204e9800998ecf8427e</md5>
</file_item>
<file_item>
...
</file_item>
...
</file_list>
Der md5-Wert wird aus den eigentlichen Daten der Datei gewonnen. Ein externes Tool kann so überprüfen, ob es die Datei schon herunter geladen hat oder nicht.
getFileListFromMaterial
Diese Methode ist alt. Bitte verwenden Sie getFileListFromItem.
getFileItem
Mit der Methode getFileItem wird ein lesender Zugriff auf die Datei selbst und die Metadaten realisiert. Die Datei selbst wird als base64-kodierter String übertragen.
Hinweis: Die base64-Kodierung erzeugt einen Overhead von ca. 33%.
Bedingungen:
- Gültige Session-ID
- Kennung muss lesenden Zugriff auf die Datei haben, d.h. Mitglied im entsprechenden Raum sein.
Überblick:
Input:
- session_id (string) - Session-ID zu einer gültigen Session des Nutzenden
- file_id (integer) - Item-ID der Datei
Output:
- Erfolg: xml_file_item (string) - Datei in XML-Notation mit Dateidaten (base64 kodiert).
- Fehler: soap_fault (object) - SOAP-Fehlerobjekt mit Informationen zum Fehler
Anwendung:
$result = $client->getFileItem('session_id','file_id');
Detaillierter Output im Erfolgsfall:
<file_item>
<files_id>39264</files_id>
...
<filename>iver_jackewitz.jpg</filename>
<base64>/9j/4AAQSkZJRgABAQEEsASwAAD/2wBDAA...</base64>
</file_item>
Um die eigentliche Datei wieder herzustellen, muss der base64-String dekodiert und in eine Datei mit dem entsprechenden Namen geschrieben werden.
deleteFileItem
Mit der Methode deleteFileItem wird eine vorhandene Datei gelöscht.
Bedingungen:
- Gültige Session-ID
- Kennung muss Zugriff auf die Datei haben, d.h.
- Mitglied im entsprechenden Raum sein
- und Ersteller der Datei
- oder den Eintrag bearbeiten dürfen, an dem die Datei hängt.
Überblick:
Input:
- session_id (string) - Session-ID zu einer gültigen Session des Nutzenden
- file_id (integer) - Item-ID der Datei
Output:
- Erfolg: "success" (string)
- Fehler: soap_fault (object) - SOAP-Fehlerobjekt mit Informationen zum Fehler
Anwendung:
$result = $client->deleteFileItem('session_id','file_id');
Detaillierter Output im Erfolgsfall:
success
addPrivateRoomMaterialList
Mit der Methode addPrivateRoomMaterialList werden Materialien dem persönlichen Raum eines Nutzenden hinzugefügt.
Bedingungen:
- Gültige Session-ID - Kennung, Portal und persönlicher Raum sucht sich CommSy aus den Daten in der Session.
Überblick:
Input:
- session_id (string) - Session-ID zu einer gültigen Session des Nutzenden
- xml_material_list (string) - XML-String zur Definition der Materialienliste
Output:
- Erfolg: xml_link_list (string) - Datei in XML-Notation
- Fehler: soap_fault (object) - SOAP-Fehlerobjekt mit Informationen zum Fehler
Anwendung:
$result = $client->addPrivateRoomMaterialList('session_id','xml_material_list');
Detaillierter Input (xml_material_list):
<material_list>
<material_item>
<item_id>12345</item_id>
<title>Hallo Die Enten</title>
<description>Eine tolle Beschreibung</description>
<extras>
<study_log></study_log>
</extras>
<bib_kind>book</bib_kind>
<common>Allgemeine bibliografischen Angaben</common>
<booktitle>Das große Entenbuch</booktitle>
<publisher>Hamburg University Press</publisher>
<address>Hamburg</address>
<volume>4</volume>
<series>13</series>
<isbn>3608935444</isbn>
<issn>978-3608935448</issn>
<pages>12-24</pages>
<journal>26</journal>
<issue>3</issue>
<university>Universität Hamburg</university>
<faculty>MIN-Fakultät</faculty>
<thesis_kind>dissertation</thesis_kind>
<url>http://service.commsy.net</url>
<url_date>26.03.2007</url_date>
<date>
<year>2010</year>
</date>
<author_list>
<author_item>Jackewitz, Iver</author_item>
...
</author_list>
<editor_list>
<editor_item>Jackewitz, Iver</editor_item>
...
</editor_list>
<keyword_list>
<keyword_item>CommSy</keyword_item>
...
</keyword_list>
<label>Hausaufgabe</label>
</material_item>
<material_item>
...
</material_item>
...
</material_list>
Die Werte für bib_kind sind:
- none
- common
- book
- collection
- incollection
- article
- inpaper
- thesis
- manuscript
- website
Die Werte für thesis_kind sind:
- term
- bachelor
- master
- exam
- diploma
- dissertation
- postdoc
Detaillierter Output im Erfolgsfall:
<link_list>
<link>
<original_id>12345</original_id>
<commsy_id>654321</commsy_id>
</link>
...
</link_list>
Durch diesen Output können in einem zweiten Schritt mit den Methoden addFileForMaterial bzw. linkFileToMaterial Dateien an die gerade hinzugefügten Materialien gehängt werden.
addFileForMaterial
Mit der Methode addFileForMaterial ist es möglich, gezielt an vorhandene Materialien, neue Dateien zu hängen.
Bedingungen:
- Gültige Session-ID
- Kennung muss schreibenden Zugriff auf die Datei haben, d.h. Mitglied im entsprechenden Raum sein und das Material bearbeiten dürfen.
Überblick:
Input:
- session_id (string) - Session-ID zu einer gültigen Session des Nutzenden
- material_id (integer) - Item-ID des Materials, an die die Datei gehängt werden soll
- xml_file_item (string) - XML-String zur Definition der Datei
Output:
- Erfolg: file_id (integer) - Item-ID der neu angelegten Datei
- Fehler: soap_fault (object) - SOAP-Fehlerobjekt mit Informationen zum Fehler
Anwendung:
$result = $client->addFileForMaterial('session_id','material_id','xml_file_item');
Detaillierter Input (xml_material_list):
<file_item>
<filesname>iver_jackewitz.jpg</filesname>
<base64>/9j/4AAQSkZJRgABAQEEsASwAAD/2wBDAA...</base64>
</file_item>
linkFileToMaterial
Mit dieser Methode wird eine vorhandene Datei kopiert und neu an das spezifizierte Material gehängt. Durch diese Methode können externe Tools einen mehrfachen Upload der selben Datei vermeiden.
Bedingungen:
- Gültige Session-ID
- Kennung muss lesenden Zugriff auf Datei und schreibenden auf das Material haben, d.h. Mitglied im entsprechenden Raum sein und das Material bearbeiten dürfen.
Überblick:
Input:
- session_id (string) - Session-ID zu einer gültigen Session des Nutzenden
- material_id (integer) - Item-ID des Materials, an die die Datei gehängt werden soll
- file_id (integer) - Item-ID der bereits vorhandenen Datei, die neu an das Material gehängt werden soll
Output:
- Erfolg: file_id (integer) - Item-ID der neu angelegten Datei
- Fehler: soap_fault (object) - SOAP-Fehlerobjekt mit Informationen zum Fehler
Anwendung:
$result = $client->linkFileToMaterial('session_id','material_id','file_id');
Dateiupload
Da das Hochladen von Dateien via SOAP einen Overhead von 33% erzeugt, kann über folgenden Weg einen Datei an einen Eintrag in einem CommSy-Raum gehängt werden.
Definitionen:
URL = http://COMMSY_SERVER/commsy.php?cid=RAUM_ID&mod=file&fct=upload
COMMSY_SERVER = die URL des CommSy-Servers bzw. Portals
RAIM_ID = Die Item-ID des Raumes in den die Datei geladen werden soll.
Übergabe per POST oder GET:
item_id = ItemID des CommSy-Elementes, an die die Datei angehängt werden soll.
SID = session_id einer gültigen Session des Nutzenden
Übergabe per POST:
Per POST muss dann die Datei selbst übermittelt werden, wobei der Name "upload" sein muss. <input type="file" name="upload"/>
IMS
Es existiert auch eine Schnittstelle für IMS.
