Die Software

• Download
• Technik
• FAQ
• Features
• Testimonials
• Infomaterial
• Historische Galerie

Die Entwicklung

• Designprinzipien
• Vorgehen
• Unterstützung
• Tools
• Evaluation

Die Nutzung

• Universitäten HH
• Schulen HH
• eww

Die Bereitstellung

Das Team

• Mitglieder
• Partner & Sponsoren
• Publikationen
• Kontakt
• Impressum

IMS Soap

Was ist IMS?

IMS Content Packaging ist eine Spezifikation, die ein Datenformat für das eLearning beschreibt. Das spezifizierte Datenformat auf XML-Basis soll Online-Lernmaterialien vereinheitlichen, und wurde von der Organisation IMS Global Learning Consortium entworfen. Der genaue Standard ist in IEEE LTSC P1484.17 definiert. ( Quelle: Wikipedia).

CommSy nutzt Teile des IMS-Standards, um das Anlegen, Löschen und Verwalten von NutzerInnen, Räumen und Mitgliedschaften von außerhalb eines CommSy-Systems zu ermöglichen.

Aufruf

Die Methode IMS ist der zentrale Einstiegspunkt in die Fernsteuerung von CommSy. Hier können Räume angelegt oder gelöscht, BenutzerInnen angelegt, gelöscht oder editiert werden und Mitgliedschaften von NutzerInnen in Räumen angelegt oder gelöscht werden.

Bedingungen:

• Gültige Session-ID
• Kennung muss spezielle Berechtigungen für IMS Zugriff besitzen
• Gültiges IMS-XML Paket

Überblick:

Input:

• session_id (string) - Session-ID zu einer gültigen Session eines Nutzenden mit IMS-Berechtigung
• ims_xml (string) - Ein XML-String der spezifiziert, welche Aktionen ausgeführt werden sollen

Output:

• return_xml (string) - XML-String, der Auskunft über Erfolg oder Mißerfolg der verschiedenen Aktionen kodiert

XML (Input)

CommSy wird per SOAP über sogenannte XML-Pakate angesteuert. Die IMS-Pakete haben dabei folgende Gesamtstruktur:

   <?xml version="1.0" encoding="UTF-8"?>
   <enterprise>
      <properties>
         <datasource>${DATASOURCE}</datasource>
         <datetime>${DATETIME}</datetime>
         <extension>
            <target>${TARGET}</target>
         </extension>
      </properties>

      <!-- Hier folgen die Aktionen -->
      ...
      ...
      ...
   </enterprise>

Die einzelnen Werte der XML-Tags (gekennzeichnet durch ${WERTNAME}) haben dabei folgende Bedeutung:

• ${DATASOURCE}: Name des aufraggebenden Systems. Woher stammt die Nachricht? Unterschiedliche Systeme müssen unterschiedliche Bezeichnungen wählen, gleiche Systeme sollten über die Zeit die Bezeichnung nicht wechseln.
• ${DATETIME}: Zeitpunkt des Auftrags im Datetime-Format (YY-MM-DD HH:MM:SS)
• ${TARGET}: Wird von CommSy verwendet, um das Portal zu ermitteln, auf der die Aktion ausgeführt werden soll.. Dient zur Identifizierung der Zielsysteme, wenn IMS-Nachrichten über einen Broker an diverse Systeme geschickt werden können. Format des Strings ist folgendes: "SystemName1;SystemName2;...;SystemNameN"

Nach dem XML-Kommentar folgen beliebig viele Aktionen, die vom CommSy ausgeführt werden sollen. Diese werden in den Abschnitten User, Räume und Mitgliedschaften erläutert.

XML (Output)

Als Rückgabewert produziert CommSy einen XML String, der den Erfolgsstatus jeder Aktion angibt. Das Schema des XML-Strings ist im folgenden zu sehen:

   <?xml version="1.0" encoding="UTF-8"?>
   <enterprise>
      <properties>
         <datasource>CommSy</datasource>
         <datetime>${DATETIME}</datetime>
         <extension>
            <message code="${SUCCESS}" target="${TARGET}"
                  ref="${ID}">${DESCRIPTION}</message>
            ...
            ...
            ...
         </extension>
      </properties>
   </enterprise>

Für jede Aktion im XML-Input wird dabei ein <message> Tag erzeugt, dass Informationen über diese Aktion enthält. Desweiteren können auch <message> Tags erzeugt werden, die über generelle Probleme auskunft geben. Weitere <message> Tags sind obenstehend mit "..." angedeutet.

Die einzelnen Werte in diesem XML-Schema sind:

• ${DATETIME}: Der Zeitstempel des Input-XMLs. Dies dient dazu, ein eingehendes und ein ausgehendes XML-Paket miteinander in Verbindung zu bringen.
• ${SUCCESS}: Einer der Werte ERROR!, WARNING! oder SUCCESS!
• ${TARGET}: Name des auftraggebenden Systems und somit Name des Antwortempfängers
• ${ID}: ID der Aktion:
  • Bei User: ID des Users im auftraggebenden System: UserID
  • Bei Räumen: ID des Raumes im auftraggebenden System: GroupId
  • Bei Mitgliedschaften: RaumId und UserId im auftraggebenden System: GroupID;UserID
• ${DESCRIPTION}: Natürlichsprachliche Beschreibung des Ergebnisses

Die Quelle der Antwort ist immer das CommSy-System, weshalb das Tag <datasource> immer den Wert "CommSy" hat. Dieses Feld ist wieder für einen Brker gedacht, der verschiedene Systeme (und ihre Antworten) verwaltet.

Aktionen

Eine Aktion stößt einen Prozess im CommSy an, der zu dem gewünschten Ergebnis führt. Folgende Operationen sind möglich:

• Anlegen eines Elements (User, Raum, Mitgliedschaft)
• Löschen eines Elements (User, Raum, Mitgliedschaft)
• Editieren eines Elements (nur User!)

In der Regel erfordert das Anlegen eines Elements die meisten Daten, weshalb diese XML-Pakete die größten sind. Die anderen Pakete bestehen aus Teilmengen der Anlegen-Pakete. Prinzipiell ist es möglich, auch bei einem Löschen-Paket alle Daten mitschicken, CommSy wird jedoch nur die zur Ausführung der Aktion nötigen Daten auswerten. Welche Aktion mit einem gegebenen Datenpaket ausgeführt wird, wird in dem Attribut recstatus des User/Raum/Mitgliedschafts-Elements festgelegt:

• recstatus="1": Anlegen eines Elements
• recstatus="2": Editieren eines Elements
• recstatus="3": Löschen eines Elements

Generell gilt: Gleiche Variablen-Namen bedeuten gleiche Variablen-Inhalte! Wenn eine Variable in einer Aktion einen Namen trägt, der auch im umfassenden XML unter XML (Input) vorkommt, so sind auch diese Inhalte gleich (z.B. ${DATASOURCE}).

User

Mit diesen Aktionen können BenutzerInnen-Accounts (User) im CommSy angelegt werden, ihre Daten editiert werden oder aus dem System wieder gelöscht werden.

Die vollständige Spezifikation der User-Aktionen wird unten angegeben. Die einzelnen Aktionen bestehen aus Teilmengen dieser Daten. Auf diese Teilmengen wird im Anschluss an das allgemeine eingegangen. Wenn in einer Aktion mehr Daten gesendet werden als benötigt (sprich: unter den einzelnen Aktionen angegeben), so werden diese zusätzlichen Daten ignoriert. Lediglich die OpCodes der verschiedenen Aktionen sind (natürlich) festgelegt.

Die allgemeine Spezifikation eines User-Paktes lautet wie folgt:

   <person recstatus="${OP}">
      <sourcedid>
         <source>${DATASOURCE}</source>
         <id>${USERID}</id>
      </sourcedid>
      <userid password="${PASSWORD}"
              pwencryptiontype="${PWENC}">${USERID}</userid>
      <name>
         <fn>${PREFIX} ${GIVEN} ${FAMILY}</fn>
         <n>
            <family>${FAMILY}</family>
            <given>${GIVEN}</given>
            <prefix>${PREFIX}</prefix>
            <suffix>${SUFFIX}</suffix>
         </n>
      </name>
      <email>${EMAIL}</email>
      <datasource>${DATASOURCE}</datasource>
      <extension>
         <institution>${INSTITUTION}</institution>
         <faculty>${FACULTY}</faculty>
         <comment>${COMMENT}</comment>
         <birthdate>${BIRTHDATE}</birthdate>
         <role>${ROLE}</role>
         <id>${ID}</id>
      </extension>
   </person>

Die einzelnen Werte in diesem XML-Schema sind:

• ${OP}: OpCode der Operation:
  • 1: Anlegen
  • 2: Editieren
  • 3: Löschen
• ${DATASOURCE}: Name des Quellsystems.
• ${USERID}: Eindeutige Bezeichnung des Users im Quellsystem.
• ${PASSWORD}: Passwort des Users.
• ${PWENC}: In welcher Form liegen die Daten des Passworts vor?
  • Leer (bzw Attribut nicht vorhanden): Passwort liegt unverschlüsselt vor (nicht empfohlen!)
  • MD5: MD5-Hash des Passworts liegt vor
• ${PREFIX}: Prefix des Names (z.B. Dr.)
• ${GIVEN}: Vorname
• ${FAMILY}: Nachname
• ${SUFFIX}: Suffix des Names (z.B. Senior)
• ${EMAIL}: Email-Adresse
• ${DATASOURCE}: Name des Quellsystems.
• ${INSTITUTION}: Institution des Users
• ${FACULTY}: Fachbereich/Department/Fakultät des Users
• ${COMMENT}: Kommentar (z.B Student)
• ${BIRTHDATE}: Geburtsdatum
• ${ROLE}: Rolle des Users (z.B um Berechtigungen zu setzen)
• ${ID}: ID des Users in einem anderen Kontext

Anlegen eines Users

Ein minimales, vollständiges, dem IMS-Standard folgendes XML-Paket (Aktion und genereller Input) zum anlegen eines Users im CommSy sieht wie folgt aus:

   <?xml version="1.0" encoding="UTF-8"?>
   <enterprise>
      <properties>
         <datasource>${DATASOURCE}</datasource>
         <datetime>${DATETIME}</datetime>
         <extension>
            <target>${TARGET}</target>
         </extension>
      </properties>
      <person recstatus="1">
         <sourcedid>
            <source>${SOURCE}</source>
            <id>${USERID}</id>
         </sourcedid>
         <userid password="${PASSWORD}">${USERID}</userid>
         <name>
            <fn>${GIVEN} ${FAMILY}</fn>
            <n>
               <family>${FAMILY}</family>
               <given>${GIVEN}</given>
            </n>
         </name>
         <email>${EMAIL}</email>
      </person>
   </enterprise>

Editieren eines Users

Ein minimales, vollständiges, dem IMS-Standard folgendes XML-Paket (Aktion und genereller Input) zum editieren eines bestehenden Users sieht wie folgt aus. Dabei sind weiße Werte optional und können (je nach Bedarf) weggelassen werden. In diesem Fall bleiben die alten Werte erhalten, ansonsten werden die neuen Werte eingesetzt. Die Passwort-bezogenen Attribute des Userid-Tags können zusätzlich weggelassen werden. In diesem Fall wird eine neue Id gesetzt, das Passwort selbst bleibt erhalten. Das <fn>-Tag wird für die Datenauswertung nicht verwendet, ist aber in der IMS-Spezifikation zwingend vorgeschrieben.

   <?xml version="1.0" encoding="UTF-8"?>
   <enterprise>
      <properties>
         <datasource>${DATASOURCE}</datasource>
         <datetime>${DATETIME}</datetime>
         <extension>
            <target>${TARGET}</target>
         </extension>
      </properties>
      <person recstatus="2">
         <sourcedid>
            <source>${SOURCE}</source>
            <id>${USERID}</id>
         </sourcedid>
         <userid password="${NEW_PASSWORD}">${NEW_USERID}</userid>
         <name>
            <fn>${GIVEN} ${FAMILY}</fn>
            <n>
               <family>${NEW_FAMILY}</family>
               <given>${NEW_GIVEN}</given>
            </n>
         </name>
         <email>${NEW_EMAIL}</email>
      </person>
   </enterprise>

Löschen eines Users

Ein minimales, vollständiges, dem IMS-Standard folgendes XML-Paket (Aktion und genereller Input) zum löschen eines bestehenden Users sieht wie folgt aus:

   <?xml version="1.0" encoding="UTF-8"?>
   <enterprise>
      <properties>
         <datasource>${DATASOURCE}</datasource>
         <datetime>${DATETIME}</datetime>
         <extension>
            <target>${TARGET}</target>
         </extension>
      </properties>
      <person recstatus="3">
         <sourcedid>
            <source>${SOURCE}</source>
            <id>${USERID}</id>
         </sourcedid>
         <name>
            <fn>${GIVEN} ${FAMILY}</fn>
         </name>
      </person>
   </enterprise>

Mitgliedschaften von Usern in Räumen

Mit dieser Aktion kann einem bestehenden User der Zugang zu einem bestehenden Raum gewährt werden; Der User wird Mitglied in diesem Raum, IMS nennt diese Relation "Membership".

Eine solche Membership-Aktion sieht wie folgt aus:

   <membership recstatus="${OP}">
      <sourcedid>
         <source>${DATASOURCE}</source>
         <id>${GROUPID}</id>
      </sourcedid>
      <member>
         <sourcedid>
            <source>${DATASOURCE}</source>
            <id>${USERID}</id>
         </sourcedid>
         <idtype>1</idtype>
         <role recstatus="${OP}" roletype="${ROLETYPE}">
            <userid>${USERID}</userid>
            <status>1</status>
         </role>
      </member>
   </membership>

Die einzelnen Werte in diesem XML-Schema sind:

• ${OP}: OpCode der Operation:
  • 1: Anlegen
  • 3: Löschen
• ${DATASOURCE}: Quellsystem des Users und des Raumes
• ${GROUPID}: Eindeutige Bezeichnung des Raumes im Quellsystem, in dem der User Mitglied werden soll
• ${USERID}: Eindeutige Bezeichnung des Users im Quellsystem, der Zugang zum Raum erhalten soll
• ${ROLETYPE}: Rolle des Users im Raum. Enweder Moderator (Nummer dafür ist in der cs_config.php anzugeben, standardmäßig '05'), oder normales Mitglied (jede andere, nicht-Moderator Nummer).

Anlegen einer Mitgliedschaft

Ein minimales, vollständiges, dem IMS-Standard folgendes XML-Paket (Aktion und genereller Input) zum anlegen einer Mitgliedschaft:

   <?xml version="1.0" encoding="UTF-8"?>
   <enterprise>
      <properties>
         <datasource>${DATASOURCE}</datasource>
         <datetime>${DATETIME}</datetime>
         <extension>
            <target>${TARGET}</target>
         </extension>
      </properties>
      <membership recstatus="1">
         <sourcedid>
            <source>${DATASOURCE}</source>
            <id>${GROUPID}</id>
         </sourcedid>
         <member>
            <sourcedid>
               <source>${DATASOURCE}</source>
               <id>${USERID}</id>
            </sourcedid>
            <idtype>1</idtype>
            <role recstatus="1" roletype="${ROLETYPE}">
               <userid>${USERID}</userid>
               <status>1</status>
            </role>
         </member>
      </membership>
   </enterprise>

Löschen einer Mitgliedschaft

Ein minimales, vollständiges, dem IMS-Standard folgendes XML-Paket (Aktion und genereller Input) zum löschen einer Mitgliedschaft:

   <?xml version="1.0" encoding="UTF-8"?>
   <enterprise>
      <properties>
         <datasource>${DATASOURCE}</datasource>
         <datetime>${DATETIME}</datetime>
         <extension>
            <target>${TARGET}</target>
         </extension>
      </properties>
      <membership recstatus="3">
         <sourcedid>
            <source>${DATASOURCE}</source>
            <id>${GROUPID}</id>
         </sourcedid>
         <member>
            <sourcedid>
               <source>${DATASOURCE}</source>
               <id>${USERID}</id>
            </sourcedid>
            <idtype>3</idtype>
            <role recstatus="1" roletype="${ROLETYPE}">
               <userid>${USERID}</userid>
               <status>1</status>
            </role>
         </member>
      </membership>
   </enterprise>

Räume

Mit dieser Aktion können im CommSy Räume angelegt oder gelöscht werden. Die IMS-Spezifikation bietet Raum-Entitäten als soches nicht, deshalb wurde die Group-Spezifikation genutzt.

Eine Group/Raum-Aktion sieht wie folgt aus:

   <group recstatus="${OP}">
      <sourcedid>
         <source>${DATASOURCE}</source>
         <id>${GROUPID}</id>
      </sourcedid>
      <grouptype>
         <typevalue level="0">CLASSES</typevalue>
      </grouptype>
      <description>
         <short>${TITLE}</short>
         <long>${FULL}</long>
      </description>
      <datasource>${DATASOURCE}</datasource>
      <extension>
         <institution>${INSTITUTION}</institution>
         <faculty>${FACULTY}</faculty>
         <code>${CODE}</code>
         <charset>${CHARSET}</charset>
         <template>${TEMPLATE}</template>
         <language>${LANG}</language>
      </extension>
   </group>

Die einzelnen Werte in diesem XML-Schema sind:

• ${OP}: OpCode der Operation:
  • 1: Anlegen
  • 3: Löschen
• ${INSTITUTION}: Institution des Users (nicht von CommSy genutzt)
• ${FACULTY}: Fachbereich/Department/Fakultät des Users (nicht von CommSy genutzt)
• ${CODE}: ??? (nicht von CommSy genutzt)
• ${CHARSET}: Schriftkodierung im Raum (nicht von CommSy genutzt)
• ${TEMPLATE}: ??? (nicht von CommSy genutzt)
• ${LANG}: Sprache des Raumes (nicht von CommSy genutzt)

Anlegen eines Raumes

CommSy kann keinen Raum anlegen, ohne dass zumindest ein User als Moderator in diesem Mitglied ist (bzw: Nur User können Räume eröffnen uns sind dann automatisch Mitglied im neuen Raum).

Aus diesem Grund muss zwingend (mindestens) eine "Membership-anlegen" Aktion für den neuen Raum existieren, in der der User Moderator-Rechte eingeräumt bekommt. Um einen Raum anzulegen, werden also zwei Aktionen benötigt: Eine Raumaktion und eine Membershipaktion! Die Reihenfolge der Aktionen im gesendeten Paket ist dabei egal. Welcher ${ROLETYPE} nun einem Moderator entspricht, ist in der cs_config.php festgelegt (standardmäßig "05"). Ein laut IMS vollständiges, minimales Paket zum anlegen eines Raumes sieht also wie folgt aus:

   <?xml version="1.0" encoding="UTF-8"?>
   <enterprise>
      <properties>
         <datasource>${DATASOURCE}</datasource>
         <datetime>${DATETIME}</datetime>
         <extension>
            <target>${TARGET}</target>
         </extension>
      </properties>

   <!-- Membership Aktion: Welcher User soll Moderator werden?-->

      <membership recstatus="1">
         <sourcedid>
            <source>${DATASOURCE}</source>
            <id>${GROUPID}</id>
         </sourcedid>
         <member>
            <sourcedid>
               <source>${DATASOURCE}</source>
               <id>${USERID}</id>
            </sourcedid>
            <idtype>1</idtype>
            <role recstatus="1" roletype="${ROLETYPE:MODERATOR}">
               <userid>${USERID}</userid>
               <status>1</status>
            </role>
         </member>
      </membership>

   <!-- Raum Aktion: Welcher Raum soll eröffnet werden?-->

      <group recstatus="1">
         <sourcedid>
            <source>${DATASOURCE}</source>
            <id>${GROUPID}</id>
         </sourcedid>
         <grouptype>
            <typevalue level="0">CLASSES</typevalue>
         </grouptype>
         <description>
            <short>${TITLE}</short>
            <long>${FULL}</long>
         </description>
         <datasource>${DATASOURCE}</datasource>
      </group>
   </enterprise>

Löschen eines Raumes

Beim Löschen muss keine Mitgliedschaft explizit gelöscht werden, es reicht also eine Raum-Aktion:

   <?xml version="1.0" encoding="UTF-8"?>
   <enterprise>
      <properties>
         <datasource>${DATASOURCE}</datasource>
         <datetime>${DATETIME}</datetime>
         <extension>
            <target>${TARGET}</target>
         </extension>
      </properties>
      <group recstatus="3">
         <sourcedid>
            <source>${DATASOURCE}</source>
            <id>${GROUPID}</id>
         </sourcedid>
         <grouptype>
            <typevalue level="0">CLASSES</typevalue>
         </grouptype>
         <description>
            <short>${TITLE}</short>
            <long>${FULL}</long>
         </description>
         <datasource>${DATASOURCE}</datasource>
      </group>
   </enterprise>