Page Comparison

...

...

Mittels des Service-Layers werden EFS Service Layer, unsere API in EFS, ermöglicht den Zugriff auf EFS Kern-Funktionalitäten von EFS für durch externe Anwendungen zur Verfügung gestellt. Zukünftig entstehende EFS-Funktionalitäten werden ebenfalls von außen ansteuerbar sein. Die Services können über HTTP oder HTTPS aufgerufen werden. Die Services können mittels verschiedener Datenaustauschformate . 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) angesprochen werden. Der .

Eine Übersicht aller EFS Service-Layer deckt das Leistungsspektrum der früheren SOAP-Services ab.

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 → Services → Service-Konfiguration. Es ist analog zu dem Menü für die SOAP-Services (Optionen → Services → Web Services) gestaltet. Das Menü Service-Konfiguration ist grundsätzlich nur verfügbar, wenn Questbacks Support-Team auf Ihrer Installation 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.

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.

...

• Der jeweilige Service muss von Questbacks 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 HTTP/ HTTPS und darin drei vier interne Formate:

• PHP-serializedSOAP: Hier werden die Input- und Output-Parameter als serialisierte PHP-Arrays übergeben. Dies ist ideal, wenn der Client PHP ist Daten werden mittels SOAP als XML übertragen.

  • Der Handler wird über den URL-Parameter "handler" mit Wert "phpsoap" aktiviert.

  • Der Name der aufgerufenen Methode wird im URL-Parameter "method" übergeben. Der Methodenname hat den Aufbau MODULNA- ME.ACTORNAME.MODULNAME_ACTORNAME_METHODNAME (mit Punkten Unterstrichen getrennt).

  • Wenn der Request ein HTTP GET-Request 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.

• JSONREST: 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 MODULNA- ME.ACTORNAME.METHODNAME (mit Punkten getrennt).

  • Wenn der Request ein HTTP GET-Request ist, wird der Beschreibungsmodus getriggert. Andernfalls wird der Transaktionsmodus verwendet.

• SOAP: Daten werden mittels SOAP übertragen. Siehe Beispiel unten.

  • Der Handler wird über den URL-Parameter "handler" mit Wert "soap" aktiviert.

  • Der Methodenname hat den Aufbau MODULNA- ME_ACTORNAME_METHODNAME (mit Unterstrichen getrennt).

  • Wenn im Request der URL-Parameter "wsdl" gesetzt ist, wird der Beschrei- bungsmodus getriggert und eine WSDL generiert. Andernfalls wird der Transaktionsmodus verwendet.

Authentifizierung

Folgende Authentifizierungsmechanismen können verwendet werden:

• Tokens: Questbacks 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. Beachten Sie bitte: Bei Authentifizierung über http werden Accountname und Passwort unverschlüsselt übertragen, d.h. man kann sie auf Proxies u.U. mitloggen. Dies würde beispielsweise Zugriff auf den Adminbereich ermöglichen. Daher empfiehlt Questback, Tokens zu verwenden oder die Services über SSL aufzurufen.

Aufruf der Service-Beschreibung

Selbstbeschreibung des PHP-Handlers:

http://your-domain-com/service/?handler=php

WSDL aufrufen:

...

• ü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

Wichtige Parameter

...

Wichtige Parameter

Die wichtigsten Parameter im Überblick:

• handler: Name des Format-Handlers (soap, rest, php, json, soap).

• method: Name der aufgerufenen Methode bei PHP- und JSON-Handler.version: Optionale Versionsnummer der Service-API.

• 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 JSONSOAP-Aufruf mit http-Authentifizierung vorgeführt und im zweiten der SOAPJSON-Aufruf mit http-Authentifizierung.

JSON-Aufruf mit http-Authentifizierung

/**

*Bitte anpassen **/

$baseUrl="http://your.server.name/"; $userName="user1"; $passwd="topsecret";
/* *********************** */

/**

*ggf. bitte anpassen */

set_include_path(get_include_path().':'.dirname(__FILE__).'/../wcp/3rd/');

/* **************** */

require 'Zend/Http/Client.php';

$call = array('method'=>'efs.system.getLoad','params'=>array());

$url=$baseUrl."service/index.php?handler=json";

$client=new Zend_Http_Client(); $client->setUri($url); $client->setAuth($userName,$passwd); $client->setMethod(Zend_Http_Client::POST);

$client->setRawData (json_encode(array('method'=>$call['method'],'jsonrpc'=>'2.0','id'=>1,'params'=>$call['pa rams'])));

$response=$client->request();

/**

• Get JSON result */

$return=$response->getBody();

SOAP-Aufruf mit http-Authentifizierung

/**

*Bitte anpassen **/

$baseUrl="http://your.server.name/"; $userName="user1"; $passwd="topsecret";
/* *********************** */

ini_set("soap.wsdl_cache_enabled",0); ini_set("default_socket_timeout",10);

/**

*ggf. bitte anpassen */

set_include_path(get_include_path().':'.dirname(__FILE__).'/../wcp/3rd/');

/* **************** */

$call = array('method'=>'efs.system.getLoad','params'=>array());

$client = new SoapClient($baseUrl."service/index.php?handler=soap&wsdl=1",array( "style"=>SOAP_RPC,

"use"=>SOAP_ENCODED, "encoding"=>"UTF-8", "login"=>$userName, "password"=>$passwd, "trace"=>1,

));

$r=call_user_func_array(array($client,str_replace('.','_',$call['method'])),$call['params']);

/**

• Get result as XML String

• */

$req = $s->__getLastRequest();

Übersicht über REST API

Neben den bisherigen Anpassungen SOAP, PHP und JSON-RPC wurde ein neuer Handler implementiert, der dem RESTful-Services-Paradigma folgt. Die neue REST Api wird von URLs adressiert, die mehr als 3 Pfad-Elemente enthalten(beispielsweise: https://eigeneInstallation.questback.com/service/survey/surveys/).

• Das /service/-Element ist obligatorisch, um den Service-Layer anzusprechen.

• Falls weitere Pfad-Elemente vorhanden sind, wird automatisch der REST-Adapter verwendet:

• /service/survey/surveys/ → Rest-Adapter wird automatisch verwendet und der handler-Paramter wird nicht benötigt

• /service/index.php → Dieses Format wird verwendet, um auf SOAP, PHP und JSON-RPC API zuzugreifen. Der REST-Adapter wird nicht verwendet. Der handler-Paramter muss festgelegt werden (beispielsweise: /service/index.php?handler=soap).

Die REST API liefert eine Service-Beschreibung im RAML 0.8-Format.

• Die Beschreibung wird ausgegeben, wenn die Parameter raml=1 und hander=reset in der URL angegeben werden.

  • https://eigeneInstallation.questback.com/service/?handler=rest&raml=1

• Diese Beschreibung kann verwendet werden, um automatisch Testanwendungen und Service-Stellen für verschiedene Programmiersprachen zu erzeugen (siehe für weitere Informationen: http://raml.org/).

• Die Beschreibung wird dynamisch erzeugt und beinhaltet nur Methoden, die für die in dieser Zeit eingeloggten Service-Layer-Nutzer*innen zugänglich sind.

• Wie bei anderen Service-Layer-Adaptern müssen die einzelnen Services für die Nutzer*innen und Gruppen aktiviert werden, um von diesen Nutzer*innen und Gruppen verwendet werden zu können (Siehe System → Optionen → Services)

Der Inhaltstyp aller Anfragen, die den HTTP-Body beinhalten, muss application/json sein.

• Das bedeutet, dass der Body-Inhalt JSON-Encoded sein muss.

...

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>

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

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.

Expand
title Konfiguration von SoapUI
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. Image Added 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. Image Added

Expand
title Konfiguration von Postman
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. Image Added 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. Image Added Die Registerkarte Collections enthält nun eine Liste aller für den Aufrufer verfügbaren Dienste auf der EFS-Installation. Info Bitte beachten Sie, dass in seltenen Fällen Postman die RAML-Datei aus EFS ablehnt. In diesem Fall empfehlen wir, die Anfragen individuell zu erstellen.

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.

{
    "condition": {
        "comparison": {
            "variable": "circleType",
            "operator": "EQUAL",
            "value": "COMPANY_MANAGED"
        }
    }
}

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.

{
    "condition": {
        "inComparison": {
            "variable": "circleType",
            "operator": "IN",
            "value": [
                "COMPANY_MANAGED",
                "USER_MANAGED"
            ]
        }
    }
}

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.

{
    "condition": {
        "join": {
            "operator": "AND",
            "condition1": {
                "comparison": {
                    "variable": "title",
                    "operator": "CONTAINS",
                    "value": "Test"
                }
            },
            "condition2": {
                "inComparison": {
                    "variable": "circleType",
                    "operator": "IN",
                    "value": [
                        "COMPANY_MANAGED",
                        "USER_MANAGED"
                    ]
                }
            }
        }
    }
}

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:

{
    "condition": {
        "join": {
            "operator": "AND",
            "condition1": {
                "join": {
                    "operator": "AND",
                    "condition1": {
                        "comparison": {
                            "variable": "title",
                            "operator": "CONTAINS",
                            "value": "Test"
                        }
                    },
                    "condition2": {
                        "inComparison": {
                            "variable": "circleProcessStatus",
                            "operator": "IN",
                            "value": [
                                "IDLE","IN_PROGRESS"
                            ]
                        }
                    }
                }
            },
            "condition2": {
                "inComparison": {
                    "variable": "circleType",
                    "operator": "IN",
                    "value": [
                        "COMPANY_MANAGED",
                        "USER_MANAGED"
                    ]
                }
            }
        }
    }
}

Verfügbare Service Layer Methoden

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