How-to: Service Layer

This article provides a comprehensive guide on how to use and configure the EFS Service Layer, which is the API that allows access to key EFS functionalities from external applications.

Configuring the Services

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 our support team has activated the 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:

  • Our support team has to add the service.
  • The service must be activated. If necessary, the button Activate all services allows the 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 survey.questionnaire.createPage or survey.questionnaire.deletePage, for example, the staff team needs to 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.

Access Modes

The service layer offers two access modes:

  • Description: In this modus, the service layer will describe itself. In SOAP format, for example, a WSDL will be generated and delivered. This modus allows clients to find out which services are provided and which parameters they have
  • Transaction: In this modus, a service method is called and executed. How you address these modes depends on the format handler used.

Format Handler

When requesting access to the EFS Service Layer, all format handlers can be used as needed. So one of your applications could access EFS using SOAP, while another using REST, through the same token or user authentication.
Currently, the service layer supports HTTPS and four handlers:

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

Authentication

Two authentication methods can be used:

  • Tokens: (recommended) 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. We recommend to use tokens.

Calling the Service Description

Requesting the WSDL for SOAP access:
https://your-efs-installation.com/service/?handler=soap&wsdl=1

Requesting the RAML file for REST access:
https://your-efs-installation.com/service/?handler=rest&raml=1

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

When accessing the service layer, you will find a dynamic list of services activated on your installation and which are accessible by the user. A list of all available services can be found on this page.

Important Parameters

These are the most important parameters:

  • handler: name of the format handler (soap, rest, php, json).
  • method: name of the called method for PHP and JSON handler.
  • 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.

SOAP XML request and response

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>

Example: JSON call with http authentication using PHP and Zend Framework

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

The full EFS Service-Layer service overview provides example REST requests and responses.

Exploring available SOAP and REST services using 3rd party tools

You can easily get familiar with our EFS Service-Layer, by using 3rd party REST or SOAP clients. Two of such tools are SoapUI for SOAP requests and Postman for REST.

Configuring SoapUI

You need to have the full URL to the WSDL description, as described above, and the token. Basic authentication is also possible, the client will ask you to provide login information automatically. In this example we use https://my-efs/service/?handler=soap&wsdl=1&token=1234567890.

SoapUI will read the description and create example SOAP requests for all available services. Double-clicking on a request will open the following window, click on the green execute button to submit the request and a response will be shown.

Configuring Postman

You can create single requests by clicking on “New” and selecting “Request”, selecting the correct method and pasting the link to the service. When using POST requests, you need to specify the Body, selecting “raw” and “JSON” in the respective settings. All other tabs can be left to default values.


To import all available EFS Service-Layer REST services, you will need to download the RAML file (https://my-efs/service/?handler=rest&raml=1&token=1234567890) and import it as a collection in Postman.


The collections tab will now have a list of all available services on the EFS installation.

Please note, that some complex EFS rest services cause Postman to reject the RAML file. In that case we recommend creating the requests individually.

Filtering results with conditions

Requests with “ByCriteria” in their name have the possibility to filter results by condition. These conditions can be simple one to one comparisons and complex requests joined by an operator. All examples are based on the POST /panel/circles/listByCondition REST service, which returns a list of Portals groups (circles).

Comparison

This is the easiest request, it matches the items based on a single property of the item, in this case the circleType. Please note, that condition must be replaced with the string logicalCondition for some services.

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

Possible operator values for comparison: EQUAL, UNEQUAL, LESS_EQUAL, LESS_THAN, GREATER_EQUAL, GREATER_THAN, CONTAINS. Greater/smaller operators should only be applied to numeric values.

InComparison

This request allows comparison of a property to a list of acceptable values.

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

The only acceptable operator value for inComparison is IN.

Join

This type allows more complex requests, allowing two conditions (comparison, inComparison or join) to be joined by an AND or OR operator.

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

The operator for joining two or more conditions can be AND, OR, the individual conditions are similarly structured as their single instances. Since join is an acceptable condition, more complex structures are allowed:

{
    "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"
                    ]
                }
            }
        }
    }
}

FAQ

What is the EFS Service Layer?

The EFS Service Layer is an API that allows access to key EFS functionalities from external applications. It enables developers to create applications outside of EFS that can interact with EFS data and functionalities.

How can I authenticate requests to the EFS Service Layer?

You can authenticate using either tokens (recommended) provided by the support team, or by using your EFS admin area account name and password with basic HTTP authentication.

What format handlers are supported by the EFS Service Layer?

The EFS Service Layer supports four format handlers: SOAP, REST, PHP-serialized, and JSON.

Leave a Reply

Your email address will not be published. Required fields are marked *