Etuma

EFC API Basics

The Etuma Feedback Categorizerâ„¢ system may be accessed through a web service interface.

The SOAP (Simple Object Access Protocol) and interface enables the user to add signals (customer feedbacks, messages, other texts) and make queries into the system to receive analysis results for specific signals, results for specified search terms and the internet addresses for the visualisations for groups of signals.

The WSDL (Web Service Description Language) definition for SOAP-method calls:
https://www.etuma.eu/websrv/cococo/Soap/?wsdl

The description/documentation for the interface:
https://www.etuma.eu/websrv/cococo/Soap/

The SOAP interface supports both Document/Literal and RPC/Encoded SOAP-bindings.

The RESTful (HTTP request) API exposes the same methods as the SOAP API with an additional GetAccessToken() method which enables the use of an access token in the sent message header overriding the need for the signature.
The REST API also implements some additional methods that are not in the SOAP interface:

  • GetSignals
  • GetSignalComplex
  • GetSignalsComplex
Please see the REST method reference for further information.

The endpoint for RESTFull HTTP requests is
https://www.etuma.eu/websrv/cococo/Rest/
HTTP verbs POST, GET and PUT are supported. The interface produces JSON encoded results by default and expects input by POST/PUT to be JSON encoded.

The interface may be used after a user has been established in the system with an Etuma Access Key and an Etuma Secret Key for signing the interface call messages. The signing procedure is required to ensure the identity of the user and the validity of the request.
In addition to the access credentials, a user requires at least one data slot, where signals may be added for analysis and visualisation.
A data slot (signal group, storage item) is a collection item specific to the user where the user may add new signals. In the webservice methods the identifier parameter for the data slot is subsignalformid.
Eg. When adding a signal to the system the message (signal) must contain the subject, the text body, possibly a number of background variables, the signature, and the subsignalformid which is the identifier for the system internal storage item (of which a user may have multiple). All incoming material is encrypted with user specific 256-bit AES encryption.

Each SOAP API method call must be validated by including an XML-signature with the call as a parameter (signature).
The signature string:
The RFC 2104 HMAC-SHA1 digest (see http://www.ietf.org/rfc/rfc2104.txt) of the concatenation of:

  1. 'Semport'
  2. OPERATION
  3. Timestamp

using your Etuma Secret Key as the key.
For example, in an 'AddSignal' function request, the signature element would contain the HMAC-SHA1 digest of the value
'SemportAddSignal2009-01-01T12:00:00Z'
=
'f34dd1cad5302e8e635443bb7f5d5629af2af575'
given the key 'XXXXX'

Each method call must also include the user's Etuma Access Key (accesskey) and the timestamp (timestamp) that was used to create the signature. The timestamp must be within a few hours of the current time (GMT) on Etuma servers or the request will be refused.


The RESTful API can be used in the same manner as the SOAP API, but also an access token may be used for authentication.

Obtaining an access token:

To obtain an access token one must first make a signature authenticated call to the GetAccessToken() method. The return value of a successful call will contain the 'accesstoken' and 'expiresin' (expiration in seconds) values.

The 'accesstoken' value can then be used in subsequent RESTful API method calls by adding the HTTP header

Authorization: CoCoCo <Etuma Access Key>:<accesstoken>

to any call made to the service.

The access token expires after 10 minutes. It is always best to check elapsed time between time at which token was issued and the current time. If elapsed time exceeds the 10 minute time period, renew the access token by following the 'Obtaining an access token' procedure.


The RESTful API can now also be accessed using a Data Slot Key.

A Data Slot Key will allow an EtumaReports user to use the API to access a specific data slot easily.

A Data Slot Key for a specific data slot can be requested from Etuma Support: support@etuma.com

The Data Slot Key value can be used in RESTful API method calls simply by adding the HTTP header

Authorization: DataSlotKey <EtumaReports Email Address>:<Data Slot Key>

to any dataslot specific call made to the service. No other authentication (signature, access token) or data slot identifier (subsignalformid) is necessary when making the method call.

Methods that are unavailable are: GetAccessToken, AddStorage, DeleteStorage, GetStorageList, GetStorageListCounts.

For basic usage only a handfull of methods need to be used.
Provided you have at least one data slot and the corresponding subsignalformid identifier for it, you may use the AddSignal and AddSignals methods to add new signals (messages) to the system.
You may list your current data slot identifiers (subsignalformids) with the GetStorageList method.
You may create new data slots with AddStorage and delete them with DeleteStorage.
GetStorageListCounts tells you how many data slots you are using and how many are available to be created.
To receive a sessioned URL for the Research Tool visualisation, use the GetVisual method.
GetDashboard returns a sessioned URL for the Dashboard visualisation.

Here is an example GET call to GetDashboard using signature authentication:

https://www.etuma.eu/websrv/cococo/Rest/GetDashboard/?subsignalformid=MYSSFID& lang=en& useraccesskey=MYUSERACCESSKEY& timestamp=2013-01-01T12:00:00Z& signature=XXXXX
  • The sessioned URLs remain valid for 4 hours after last use and may be used from 3 separate IP addresses (including the maker of the call). Where applicable, a total of 100 sessions (with separate settings) for a given data slot may be created per hour, after that the last created session will be used.
To fetch the analysis results for specific signals you may use GetSignal, GetSignalAdvanced, GetSignalFull or GetSignalComplex. They all take a parameter receipt which is returned by each call to AddSignal and AddSignals (array of receipts).
The receipt is a unique identifier of a signal in the system. To fetch the analysis for a specific signal you need to save the receipts when adding signals and use them when retrieving the analysis. There is also the possibility of adding your own unique identifiers to the signals as background variables and using those to retrieve the analysis.
Using GetSignals and GetSignalsComplex it's possible to fetch all or some of the signals from a data slot.
The system works asynchronously by first receiving a signal to be analysed and returning the receipt for it, and then proceeding to analyse and visualise it. Therefore it's not possible to operate in synchronous manner in analysing material as the queued analysis may take as long as a few minutes under heavy load although under normal circumstances the analysis will be available in near real time. It's advisable to have separate timed jobs sending signals for analysis as they arrive but retrieving the results eg. every hour.
To set private data slot properties:
SetStorageProperty with property parameter values 1-8 are free to use to deposit any string data as the value parameter.
use GetStorageProperty to retrieve the values.
To set data slot analysis segment:
SetStorageProperty with property parameter value 11 can be used to set the analysis segment value to one of these two character sequences:
XX - Default ontology
CO - Food production vocabulary: groceries, processed food, cookies, candies, bread etc.
CA - Automobile production and retail
ET - Segment for airline companies.
ME - Segment for telecom companies that have a broad offering. For example, internet, mobile network operating and tv services.
ED - General purpose segment
FO - Lottery and slot-machine companies.
TU - Segment for companies dealing with logistics.
FL - Small, medium and large retail companies. Currently only food side is supported.
RL - Internet shopping
TR - Segment for companies such as travel agencies, selling package tours, etc.						
To delete a specific signal:
Use the ClearSignal method.

General / RESTful

SOAP