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 ) angesprochen werden. Der Service-Layer deckt das Leistungsspektrum der früheren SOAP-Services aboder XML). Eine Liste aller EFS Service-Layer-Dienste ist auf dieser Seite verfügbar.

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. Layer. Das Menü Service-Konfiguration Layer ist grundsätzlich nur verfügbar, wenn Questbacks 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.

...

• 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 interne Formate: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 MODULNA- MEMODULNAME.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 MODULNA- MEMODULNAME.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.

...

Folgende Authentifizierungsmechanismen können verwendet werden:

• Tokens (empfohlen): 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-HandlersWSDL aufrufen:
http://your-domain-.com/service/?handler=soap&wsdl=php1WSDL

RAML aufrufen:
httphttps://your-efs-domaininstallation.com/service/?handler=soaprest&wsdlraml=1

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

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 **/

...

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.

...

/**

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

...

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

...

/**

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

...

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