Gewusst-wie: Service-Layer

1 Services konfigurieren
2 Zugriffsmodi
3 Format-Handler
4 Authentifizierung
5 Aufruf der Service-Beschreibung
6 Wichtige Parameter
7 Beispiele
8 Testen verfügbarer SOAP- und REST-Methoden mit Tools von Drittanbietern
9 Ergebnisse mit Bedingungen filtern
10 Verfügbare Service Layer Methoden

EFS Service Layer, unsere API in EFS, ermöglicht den Zugriff auf EFS Kern-Funktionalitäten durch externe Anwendungen. Somit können Anwendungen, die auf EFS-Daten und -Funktionalitäten beruhen, außerhalb von EFS mit verschiedenen Technologien erstellt werden. Die Dienste können von außen über HTTPS aufgerufen werden, wobei SOAP oder REST als Protokolle verwendet werden können. Es können verschiedene Datenaustauschformate verwendet werden (z.B. JSON oder XML).

Eine Übersicht aller EFS Service-Layer Methoden finden Sie in der englischsprachigen EFS Dokumentation. Aufgrund der Komplexität und Umfang dieser Liste, kann dieses Dokument aktuell nur auf Englisch zur Verfügung gestellt werden. Wir bitten um Ihr Verständnis.

Der EFS-Service Layer ist seit EFS 9.1 verfügbar, einige Installationen haben jedoch auch weiterhin Zugriff auf die älteren "Web-Services" (Optionen > Service-Layer > Web-Services). Die Verwendung von Web-Services wird nicht mehr empfohlen, da diese Funktionalität veraltet ist und demnächst entfernt wird.

Services konfigurieren

Die auf Ihrer EFS-Installation verfügbaren Services können in einem speziell eingerichteten Konfigurations-Menü eingesehen und konfiguriert werden. Das Menü befindet sich im Administrationsbereich von EFS unter Optionen → Service-Layer. Das Menü Service-Layer ist grundsätzlich nur verfügbar, wenn das Support-Team auf Ihrer Installation die Nutzung von Services freigeschaltet hat. Für den Zugang zum Menü ist entweder Schreibrecht auf das ACL-Recht webservice_conf oder Mitgliedschaft im Root-Team erforderlich.

Die folgenden Schritte müssen ausgeführt werden, um einen bestimmten Service nutzen zu können:

Der jeweilige Service muss von dem Support-Team hinzugefügt werden.
Der Service muss aktiviert werden. Falls erforderlich, können mit dem Button Alle Services aktivieren auch sämtliche auf der Installation vorhandenen Services en bloc aktiviert werden.
Das Mitarbeiterteam, zu dem der Account gehört, mit dem auf einen Service zugegriffen wird, muss Zugriffsrecht für diesen Service haben. Auf der Registerkarte Zugriffsgruppen können die Zugriffsrechte auf die einzelnen Services separat definiert werden.
Des Weiteren beinhalten viele Services eine Prüfung auf die Objektrechte des Mitarbeiterteams. Bei survey.questionnaire.createPage oder survey.questionnaire.deletePage beispielsweise benötigt das Mitarbeiterteam Schreibrecht auf das betreffende Projekt.
Auf der Registerkarte Zugriffslog werden alle Aufrufe geloggt. Die Einträge können nach IP-Adresse, Name des verwendeten Adminaccounts, Service-Name und Datum durchsucht werden.

Zugriffsmodi

Der Service-Layer bietet zwei Zugriffsmodi:

Beschreibung: In diesem Modus beschreibt sich der Service-Layer selbst. Es wird z. B. beim SOAP-Format eine WSDL erzeugt und ausgeliefert. Dieser Modus ist notwendig, damit Clients sich informieren können, welche Services angeboten werden und welche Parameter sie haben.
Transaktion: Hier wird eine Service-Methode aufgerufen und ausgeführt Je nach Format-Handler ist die Ansteuerung der Modi unterschiedlich.

Format-Handler

Bei der Beantragung des Zugriffs auf den EFS Service-Layer können bei Bedarf alle Format-Handler beliebig verwendet werden. So könnte eine Ihrer Anwendungen über SOAP auf EFS zugreifen, während eine andere über REST auf das gleiche Token oder die gleiche Benutzerauthentifizierung zugreift.

Der Service-Layer unterstützt aktuell HTTPS und darin vier interne Formate:

SOAP: Daten werden mittels SOAP als XML übertragen.
- Der Handler wird über den URL-Parameter "handler" mit Wert "soap" aktiviert.
- Der Methodenname hat den Aufbau MODULNAME_ACTORNAME_METHODNAME (mit Unterstrichen getrennt).
- Wenn im Request der URL-Parameter "wsdl" gesetzt ist, wird der Beschreibungsmodus getriggert und eine WSDL generiert. Andernfalls wird der Transaktionsmodus verwendet. Da die WSDL auch ein Stylesheet angibt, ist die Datei auch in einem Browser anzeigbar.
REST: Daten werden über REST als JSON übertragen.
- Um den Handler zu aktivieren, müssen sie nur eine REST Anfrage durchführen, wie in der RAML oder Online Dokumentation beschrieben, z.B.: GET https://efs-installation.com/service/survey/surveys/?token=TOKEN.
  Der Content-Type aller Anfragen mit einem HTTP Body muss application/json sein und der HTTP Body muss in der Regel JSON kodiert sein.
- Um die RAML Beschreibung abzurufen, führen Sie eine Anfrage mit dem Parameter "handler=rest&raml=1" aus, z.B.. GET https://efs-installation.com/service/?handler=rest&raml=1&token=TOKEN
PHP-serialized: Hier werden die Input- und Output-Parameter als serialisierte PHP-Arrays übergeben. Dies ist ideal, wenn der Client PHP basiert ist.
- Der Handler wird über den URL-Parameter "handler" mit Wert "php" aktiviert.
- Der Name der aufgerufenen Methode wird im URL-Parameter "method" übergeben. Der Methodenname hat den Aufbau MODULNAME.ACTORNAME.METHODNAME (mit Punkten getrennt).
- Wenn der Request ein HTTP GET-Request ist, wird der Beschreibungsmodus getriggert. Andernfalls wird der Transaktionsmodus verwendet.
JSON: Daten werden JSON-encoded übergeben. Siehe Beispiel unten.
- Der Handler wird über den URL-Parameter "handler" mit Wert "json" aktiviert.
- Der Name der aufgerufenen Methode wird im URL-Parameter "method" übergeben. Der Methodenname hat den Aufbau MODULNAME.ACTORNAME.METHODNAME (mit Punkten getrennt).
- Wenn der Request ein HTTP GET-Request ist, wird der Beschreibungsmodus getriggert. Andernfalls wird der Transaktionsmodus verwendet.

Authentifizierung

Folgende Authentifizierungsmechanismen können verwendet werden:

Tokens (empfohlen): Das Support-Team kann für Sie und Ihre Mitarbeiter Tokens generieren. Diese Tokens können dann beim Aufruf des Service zur Authentifizierung genutzt werden (Parametername: "token").
Accountname und Passwort für den EFS-Adminbereich: Da jeder Mitarbeiter mit Adminbereichs-Zugang über diese Daten verfügt, ist dies die einfachste Möglichkeit, sich für die Services zu authentifizieren.

Aufruf der Service-Beschreibung

WSDL aufrufen:
http://your-domain.com/service/?handler=soap&wsdl=1

RAML aufrufen:
https://your-efs-installation.com/service/?handler=rest&raml=1

Selbstbeschreibung des PHP-Handlers:
http://your-domain-com/service/?handler=php

Da die Rechte für jeden Service und jedes Mitarbeiterteam individuell einstellbar sind, ist die Liste der Services beim Zugriff auf den Service-Layer dynamisch. Es gibt nicht mehr eine zentrale WSDL-Datei, sondern die WSDL- Datei wird anhand der Rechte des Aufrufers jedes Mal dynamisch generiert. So sieht der Aufrufer eine WSDL für diejenigen Services, die er tatsächlich benutzen kann. Für eine Übersicht aller Services, verwenden Sie bitte die Online Dokumentation.

Wichtige Parameter

Die wichtigsten Parameter im Überblick:

handler: Name des Format-Handlers (soap, rest, php, json).
method: Name der aufgerufenen Methode bei PHP- und JSON-Handler.
token: Enthält das Token für die Authentifizierung.
wsdl: Generiert die WSDL bei Nutzung des SOAP-Handlers.
raml: Generiert die RAML Beschreibung für den REST-Handler.

Beispiele

Im Folgenden finden Sie zwei Beispiele. Im ersten Beispiel wird SOAP-Aufruf mit http-Authentifizierung vorgeführt und im zweiten der JSON-Aufruf mit http-Authentifizierung.

Request

POST https://efs-installation.com/service/?handler=soap&token=TOKEN HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "https://efs-installation.com/service/?handler=soap&token=TOKEN#survey_surveys_getList"
Content-Length: 241
Host: efs-installation.com
Connection: Keep-Alive

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://www.globalpark.com/efs/services">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:survey_surveys_getList/>
   </soapenv:Body>
</soapenv:Envelope>

Response

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.globalpark.com/efs/services">
   <SOAP-ENV:Body>
      <ns1:survey_surveys_getListResponse>
         <survey_surveys_getListResponseValue>
            <success>true</success>
            <errors/>
            <warnings/>
            <messages/>
            <return>
               <survey>
                  <id>1234</id>
                  <title>Example Survey</title>
                  <description/>
                  <marked>false</marked>
                  <author>Example User</author>
                  <staff/>
                  <comment/>
                  <isMarked>false</isMarked>
                  <url>https://efs-installation.com/uc/main/12345/</url>
                  <createTime>2019-10-18T13:44:43+00:00</createTime>
                  <fieldTime>
                     <startTime>2019-10-18T00:00:00+00:00</startTime>
                     <endTime>2019-11-01T00:00:00+00:00</endTime>
                  </fieldTime>
                  <status>GENERATED</status>
                  <type>PERSONALIZED</type>
                  <numberOfParameters>0</numberOfParameters>
                  <bonusPoints>
                     <label/>
                     <value>0</value>
                  </bonusPoints>
               </survey>
            </return>
         </survey_surveys_getListResponseValue>
      </ns1:survey_surveys_getListResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

<?php
/* Example requires Zend Framework */
require_once('Zend/Loader/Autoloader.php');
function serviceLayerCall($method, $params=null)
{
    $autoloader = Zend_Loader_Autoloader::getInstance();
    $url="http://EFSINSTALLATIONURL/service/index.php?handler=json&token=TOKEN";
    $client = new Zend_Http_Client();
    $client->setUri($url);
    $client->setConfig(array('timeout' => 30));
    $client->setMethod(Zend_Http_Client::POST);
    /* not using TOKEN? Here is basic auth: */
    //$user = "USER";
    //$passwd = "PASSWORD";
    //$client->setAuth($user, $passwd);
    
    $client->setRawData(json_encode(array('method' => $method, 'jsonrpc' => '2.0', 'id' => 1, 'params' => $params)));
    $request = $client->request();
    //print "<pre>";
    //var_dump($request->getBody());
    $return = json_decode($request->getBody());
    $return=$return->result;
    return $return->return;
}

/* 1. Step - Get projects
 */
print "<h3>1. step - get projects</h3>";
$projects=serviceLayerCall("survey.surveys.getList");

foreach($projects as $project)
{
    print "- ".$project->title." (".$project->id.")<br>";
}


//2. Step - Get Structure for Pid 1112
, first a helper function:
function sub($pages, &$myquestions)
{
    foreach($pages as $page)
    {
        if(count($page->subPages) > 0)
            $this->sub($page->subPages, $myquestions);
        foreach($page->questions as $question)
        {
            $myquestions[]=$question;
        }
    }
    return $myquestions;
}

$relevantVars=array();
print "<hr><h3>2. step - get structure for Pid 1112</h3>";
$project=serviceLayerCall("survey.surveys.getQuestionnaireStructure", array("surveyId" => 1112));
$questions=sub($project, $myquestions);
foreach($questions as $question)
{
    if($question->questiontext) {
        print $question->questiontext . "<br>";
        foreach ($question->variables as $variable) {
            if ($variable->type == "char" || $variable->type == "text") {
                print "Text-Var: ".$variable->varname . "<br>";
                //add to $relevantVars for export
                $relevantVars[] = $variable->varname;
            }
        }
    }
}

/* 3 - Relevant vars for export */
print "<hr><h3>3. Collected variables for export:</h3>";
var_dump($relevantVars);
print "</pre>";

/* 4 - Get CSV export */
print "<hr><h3>4. Get results for specific vars</h3>";
$exportData=serviceLayerCall("survey.results.getRawdataCSV", array("surveyId" => 1112, "exportTypes" => array("QUESTIONNAIRE"), "includeVariables" => $relevantVars));
print base64_decode($exportData);

Die Übersicht der EFS Service-Layer Methoden hat darüberhinaus auch Beispiele für REST Aufrufe und Antworten.

Testen verfügbarer SOAP- und REST-Methoden mit Tools von Drittanbietern

Sie können sich leicht mit unserem EFS-Service-Layer vertraut machen, indem Sie REST- oder SOAP-Clients von Drittanbietern verwenden. Als Beispiel, sind zwei solcher Tools SoapUI für SOAP-Anfragen und Postman für REST.

Sie benötigen die vollständige URL zur WSDL-Beschreibung, wie oben beschrieben, und das Token. Eine BASIC-Authentifizierung ist ebenfalls möglich, der Client wird Sie automatisch nach Ihren Login-Daten fragen. In diesem Beispiel verwenden wir https://my-efs/service/?handler=soap&wsdl=1&token=1234567890.

SoapUI wird die Beschreibung lesen und Beispiel-SOAP-Anfragen für alle verfügbaren Methoden erstellen. Ein Doppelklick auf eine Anfrage öffnet das folgende Fenster, klicken Sie auf den grünen Ausführungsknopf, um die Anfrage abzuschicken, die Antwort wird dann angezeigt.

Sie können einzelne Anfragen erstellen, indem Sie auf "New" klicken und "Request" wählen, die richtige Methode auswählen und den Link zum Dienst einfügen. Wenn Sie POST-Anfragen verwenden, müssen Sie den Body angeben, indem Sie "raw" und "JSON" in den entsprechenden Einstellungen wählen. Alle anderen Registerkarten können auf Standardwerten belassen werden.

Um alle verfügbaren EFS Service-Layer REST-Dienste zu importieren, müssen Sie die RAML-Datei (https://my-efs/service/?handler=rest&raml=1&token=1234567890) herunterladen und in Postman importieren.

Die Registerkarte Collections enthält nun eine Liste aller für den Aufrufer verfügbaren Dienste auf der EFS-Installation.

Ergebnisse mit Bedingungen filtern

Abfragen mit "ByCriteria" im Namen haben die Möglichkeit, Ergebnisse nach Bedingungen zu filtern. Diese Bedingungen können einfache Eins-zu-Eins-Vergleiche und komplexe Anfragen sein, die durch einen Operator verbunden werden. Alle Beispiele basieren auf dem REST-Dienst POST /panel/circles/listByCondition, der eine Liste von Portals-Gruppen (Circles) zurückgibt.

Comparison

Dies ist die einfachste Abfrage, sie gleicht die Elemente basierend auf einer einzigen Eigenschaft des Elements ab, in diesem Fall dem circleType. Bitte beachten Sie, dass condition bei einigen Services durch die Zeichenkette logicalCondition ersetzt werden muss.

Mögliche operator Werte für den Vergleich: EQUAL, UNEQUAL, LESS_EQUAL, LESS_THAN, GREATER_EQUAL, GREATER_THAN, CONTAINS. Größer/Kleiner-Operatoren sollten nur auf numerische Werte angewendet werden.

InComparison

Diese Abfrage ermöglicht den Vergleich einer Eigenschaft mit einer Liste von Werten.

Der einzige zulässige Wert für operator in inComparison-Vergleich ist IN.

Join

Dieser Typ erlaubt komplexere Anfragen, bei denen zwei Bedingungen (comparison, inComparison oder join) durch einen AND oder OR Operator verbunden werden können.

Der operator Wert der join-Bedingung kann AND oder OR sein,die einzelnen Bedingungen sind ähnlich aufgebaut wie ihre Einzelinstanzen oben. Da auch join erlaubt ist, sind komplexere Strukturen möglich:

Verfügbare Service Layer Methoden

Eine Übersicht aller EFS Service-Layer Methoden finden Sie in der englischsprachigen EFS Dokumentation.