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:
The description/documentation for the interface:
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 or a Data Slot Key which enable the use of a custom header overriding
the need for a signature.
The REST API also implements some additional methods that are not in the SOAP interface:
The endpoint for RESTFull HTTP requests is
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. For data slot specific method calls a Data Slot Key (see Authentication below) may be used instead of the method signing procedure.
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:
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
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.
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: firstname.lastname@example.org
The Data Slot Key value can be used in RESTful API method calls simply by adding the HTTP header
|Authorization: DataSlotKey <Email or Identifier>:<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 when using a Data Slot Key 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
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.