Page Comparison

...

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 different technologies. The services can be called from outside via HTTPS, using SOAP or REST specifications. Various data exchange formats can be used (e.g. JSON or XML).
A list of all available EFS Service-Layer services can be found on this page.

...

A dedicated configuration menu allows viewing and configuring of the services, which are available on your EFS installation. The menu is in Options → Service-Layer. The Service-Layer  menu is only available if Questback’s Support-Team our 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.

The following steps are necessary to use a specific service:

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

• The service must be activated. If necessary, the button Activate all services allows activation of all available 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.

...

• SOAP: Provides API access using the SOAP protocol.

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

  • The name of the invoked method is handed over in the URL parameter "method". The method name is structured as follows: MODULENAME_ACTORNAME_METHODNAME (separator: underscore, ”_”).

  • 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. Since the WSDL also specifies a Stylesheet, the file is also viewable in a browser.

• REST: Provides REST API access, see the full list of services for REST examples.

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

  • To get the RAML description file, triggering the description mode, 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 "php".

  • The name of the invoked method is handed over in the URL parameter "method". The method name is structured as follows: MODULENAME.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.

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

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

  • The name of the invoked method is handed over in the URL parameter "method". The method name is structured as follows: MODULENAME.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.

...

Two authentication methods can be used:

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

• Account name and password for the EFS admin area: Uses basic authentication of the HTTP protocol. The passwords are the same as for the administration area of EFS. QuestBack recommends We recommend to use tokens.

Calling the Service Description

...

Important Parameters

These are the most important parameters:

...

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

...

List of available services

A list of all available EFS Service-Layer services can be found on this page.