Page Comparison

...

...

...

...

...

The new EFS Service Layer, our API, allows to access EFS key functionalities from outside EFS. Thus, applications relying on EFS data and functionalities can be created outside of EFS with quite different technologies. EFS functions which are of interest to customers will be made available as well. The services can be called from outside via HTTP or HTTPSHTTPS, using SOAP or REST as protocols. Various data exchange formats can be used (e.g. JSON or XML).

...

Configuring the Services

A dedicated configuration menu allows to view and configure the services, which are available on your EFS installation. The menu is in Options → Service-Layer →Service-Layer . The menu has the same structure as the menu for the deprecated SOAP services (Options → Service-Layer→ Web services). The Service-Layer  menu is only available if Questback’s Support-Team has activated usage of services for your installation. To view and access the menu, you need either read rights for the ACL right webservice_conf or membership in the root team.

...

• Questback’s Support-Team has to add the service.

• The service must be activated. If necessary, the button Activate all services allows to activate activation of all services available on the installation en blocavailable services at once.

• The staff account used to access the service is allocated to a specific staff team. This staff team must have the necessary access rights to the service. Access rights to individual services can be assigned on the tab Access groups.

• Furthermore, many services include a check for object rights. To use sur- vey.questionnaire.createPage or survey.questionnaire.deletePage, for example, the staff team needs write rights for the target project.

• All calls are logged on the Access log tab. The entries can be searched by IP address, name of the admin account used, service name and date.

...

Currently the service layer supports HTTP/ HTTPS and three internal formatsfour protocols:

• PHP-serialized: Here, the input and output parameters are transferred as serialized PHP arrays. This is the recommended approach for PHP clientsSOAP: The SOAP protocol is used to transfer data.

  • To activate the handler, use the URL parameter "handler" with the value "phpsoap".

  • The name of the invoked method is handed over in the URL parameter "meth- odmethod". The method name is structured as follows: MODU- LENAME.ACTORNAME.MODULENAME_ACTORNAME_METHODNAME (separator: periodsunderscore, ”_”).

  • If the request is an HTTP GET URL parameter "wsdl" is set in the request, the description mode will be triggered and a WSDL will be generated. Otherwise, the transaction mode will be used. Since the WSDL also specifies a Stylesheet, the file is also viewable in a browser.

• REST: See REST API documentation on this page

  • To activate the handler, just create the REST request, as specified in the documentation or RAML file, e.g. GET https://efs-installation.com/service/survey/surveys/?token=TOKEN.
    The content type of all requests containing a HTTP body must be application/json and therefore all request bodies must be JSON

  : Data are transferred in JSON encoding. See the example below

  • encoded.

  • To get the RAML description file, create a request to /service/ using the URL parameters "handler=rest&raml=1", e.g. GET https://efs-installation.com/service/?handler=rest&raml=1&token=TOKEN

• PHP-serialized: Here, the input and output parameters are transferred as serialized PHP arrays. This is the recommended approach for PHP clients.

  • To activate the handler, use the URL parameter "handler" with the value "jsonphp".

  • The name of the invoked method is handed over in the URL parameter "meth- odmethod". The method name is structured as follows: MODU- LENAMEMODULENAME.ACTORNAME.METHODNAME (separator: periods).

  • If the request is an HTTP GET request, the description mode will be triggered. Otherwise, the transaction mode will be used.

• SOAP: SOAP is used to transfer dataJSON: Data are transferred in JSON encoding. See the example below.

  • To activate the handler, use the URL parameter "handler" with the value "soapjson".

  • The name of the invoked method is handed over in the URL parameter "method". The method name is structured as follows: MODU- LENAME_ACTORNAME_MODULENAME.ACTORNAME.METHODNAME (separator: underlines _periods).

  • If the URL parameter "wsdl" is set in the request , the description mode will be triggered and a WSDL will be generated. Otherwise, the transaction mode will be used.

  REST: See REST API documentation on this page

  • To activate the handler, use the URL parameter "handler" with the value "rest".

  • If the URL parameter "raml=1" is set in the is an HTTP GET request, the description mode will be triggered and a RAML of available API services will be generated. Otherwise, the transaction mode will be used.

...

Two authentication methods can be used:

• Tokens: (recommended) QuestBack Support can provide tokens for you and your staff members. These tokens can be used for authentication when invoking a service (parameter name: "to- kentoken").

• Account name and password for the EFS admin area: The easiest authentication meth- od, as any staff member with admin area access already owns an account. But please mind: When calling the services via http, account name and password will be trans- ferred unencrypted, i.e. it is possible to log them e.g. on proxies and use them to access the admin area. Therefore, Uses basic authentication of the HTTP protocol. The passwords are the same as for the administration area of EFS. QuestBack recommends to use tokens or to call the services via SSL.

Calling the Service Description

Self-description of the PHP handlerCalling the WSDL:
httphttps://your-domainefs-installation.com/service/?handler=phpsoap&wsdl=1

Calling the WSDL:
httphttps://your-efs-domaininstallation.com/service/?handler=soaprest&wsdlraml=1

...

Self-description of the PHP handler:
https://your-efs-installation.com/service/?handler=php

Important Parameters

These are the most important parameters:

• handler: name of the format handler (soap, rest, php, json, soap).

• method: name of the called method for PHP and JSON handler.

• version: optionally-used version number of the Service API.

• token: contains the token for authentication.

• wsdl: generates the WSDL description, if the SOAP handler is used.

• raml: generates the RAML description, if REST handler is used.

Examples

Below are two examples. The first example illustrates JSON call with http authentication and the second illustrates SOAP call with http authentication.

Example: JSON call with http authentication

/**

*Please adapt **/

$baseUrl

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/

...

/**

*if necessary please adapt */

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

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

require 'Zend/Http/Client.php';

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

...

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

Example: SOAP call with http authentication

/**

*Please adapt **/

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

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

/**

*if necessary please adapt */

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

Overview of the REST API’s

Besides the legacy adapters SOAP, PHP and JSON-RPC, a new handler has been implemented to follow the RESTful services paradigm.

The new REST Api is addressed by URIs that contain more than 3 path-elements i.e. https://myinstallation.questback.com/service/survey/surveys/

• /service/ element is mandatory to address the service layer for any adapter

• If further path elements exist, REST adapter will automatically be used:

• /service/survey/surveys/ → REST adapter will automatically be involved and handler parameter isn't needed

• /service/index.php → This format is used to access SOAP, PHP and JSON-RPC API. REST adapter will not be involved and a handler parameter must be declared i.e. /service/index.php?handler=soap.

The REST api provides a service-description in RAML 0.8 format.

• Description will be delivered if parameters raml=1 and handler=rest are provided in URL:

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

• This description can be used to automatically create test-suites as well as service-stubs for various programming languages, see http://raml.org/ for further information.

• Description is created dynamically and will contain only methods, which are accessible by the currently logged-in service layer user.

• As with other service layer adapters, individual services need to be activated for the user/ group in order to be used by that user/ group. (See System > Options > Services in EFS)

The content type of all requests containing a HTTP body must be application/json

• That means that BODY content must be JSON-Encoded.

[Direct link to the REST API documentation]

...

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