Data Integration

Automatic Web Services

Automatic web services is a setting, that when configured, makes Plum Insight automatically send the results of a survey visit to a SOAP or REST endpoint. This setting has to be configured individually for each survey users want to use it for.

Enabling Automatic Webservices

To enable Automatic web services for a survey, navigate to that survey's settings page.

That page contains an “Automatic Webservices” section, which looks like this:

Field Description
Web Session Timeout This field determines the timeout duration for web survey sessions. If a user is idle for this period of time, their session will expire. At that time the automatic webservice request will be made. Note: By default, the web session timeout is set at 60 minutes, regardless of whether or not automatic web services is enabled.
Web Service Type SOAP or REST, indicating which type of service will be called.
Web Service URL The URL for the SOAP or REST service. If specifying SOAP, make sure this is the URL to the WSDL and not the service itself (i.e. make sure you append ?WSDL to the URL).

To enable automatic webservices for a survey, users must set a Web Service Type and a Web Service URL. Failure to set both of these fields makes it impossible for Insight to reasonably determine whether to interact with a REST or SOAP service and, as a result, Insight will abandon the attempt altogether.

Data Integration for Automatic Webservices

The request data submitted by Plum Insight's automatic webservices feature will be identical to that of the SOAP and REST webservice question type. Users can build their services in the same manner as they would for a SOAP or REST webservice question type.

Automatic webservice requests will be made at the conclusion of a survey session or under the following circumstances:

  • After all transcriptions have been returned for an audio recordings for comment question types
  • After a web session has exceeded the set web session timeout

Plum Insight Webservice Question Type

The webservice question type allows data from a survey to be submitted to a SOAP or REST service endpoint.

The following data is submitted to the web service, regardless of whether it is being sent to a SOAP or REST service:

Type Name Description
string[] question_texts Zero-indexed array of question text from the survey
string[] answers Zero-indexed array of question answers from the current session
string ani_ip ANI of the caller or the IP address of the user taking the survey
string dnis DNIS of the number dialed to take the survey. This value is always NULL for web surveys
string session_id Unique session id for the survey session

It is recommended that users become familiar with the details of their specific service type in order to determine how to handle this data when it is sent to their service.

SOAP Integration

Users need to build their SOAP service so that it has a single plumEval method that accepts the above parameters and returns a string value that will be stored as the answer for the webservice question in your survey. Users can branch on this returned value using the webservice question's skip logic options; it is also possible to branch on a SOAP fault.

Handling a SOAP Fault

The webservice question type for SOAP is architected so that if a SOAP webservice returns a SOAP fault, then Plum Insight stores the value 'SOAPFault' as the answer to the webservice question.

Users can utilize this value in the skip logic for the webservice question to branch on a SOAP fault returned from their service.

Handling Audio Files

Comments provided over the phone by end-users for the comment question type are in the WAV format appear as Base64 encoded strings in the answers array. Users who want to save these recordings in their SOAP service should review the answers array for Base64 encoded strings. These strings can be decoded into WAV files of the audio recordings.

REST Integration

To integrate with the REST webservice question type, users need to build a REST service that accepts the data submitted from Plum Insight.

HTTP Method

Data is always submitted to the REST service as an HTTP POST.


Data is always sent as 'multipart/form-data'.

Accepted HTTP Response Codes

An HTTP response code of 2xx is treated as a successful response. Any other HTTP code: 3xx, 4xx, 5xx, is treated as an error and Plum Insight stores the answer for the webservice question as 'RESTFault'.

Handling a REST Error

Any non-2xx HTTP code returned from the REST service is treated as an error. In this circumstance, Plum Insight stores the answer for the webservice question as 'RESTFault'.

Users can utilize this value in the skip logic for the webservice question to branch on a REST error returned from their service.

Handling Audio Files

WAV recordings of comments left via phone for the comments question type are submitted along with the other POST data. The filename format for these recordings is 'file-{counter}.wav'. In this case, 'counter' refers to the number of recordings the survey has collected. For example, the first audio recording in a survey would have the filename 'file-1.wav', the second 'file-2.wav', etc. To save these files users should review the answers array for names matching the filename format for 'file-{counter}.wav' and save the files from $_FILES array, or their language-specific equivalent.

Sample Code

This is a basic, working sample of a REST service. Note that this only for reference purposes. The script accepts the data, dumps the $_POST and $_FILES arrays to a text file, and returns the string 'it worked' as the response. At this point it is possible to check the survey responses for the REST webservice question type to validate that the service is accessible and correctly returns a value.


if (isset($_POST)) {
    file_put_contents(time().".txt", var_export($_POST,TRUE)."\n".var_export($_FILES,TRUE));
    echo 'it worked';

NOTE: For this script to work, the target directory needs to be writable in order to create the text file in the web directory of the script.

Subdialog Integration

The subdialog question type allows users to add custom VoiceXML to their surveys.

Data Transmission

When encountering a subdialog question, data is submitted as multipart/form-data to the subdialog URL. The data submitted includes the following:

Required Type Name Description
Yes string ani ANI of the caller taking the survey
Yes string dns DNIS the caller called to reach the survey
Yes string lang Language code for the language in which the call is being taken
Yes string session_id Unique id for the session of the caller taking the survey
Yes string questions JSON encoded, zero-indexed array of question text from the survey. The question and answer arrays are parallel arrays.
Yes string answers JSON encoded, zero-indexed array of question answers from the call session. The question and answer arrays are parallel arrays.
No file __comment_{some_id} WAV files of any recorded comments via the comment question type

Note: When a file is present in the POST data, users will see 'file://__comment_{some_id}' stored in the answers JSON array. To access this file in the subdialog question, users need to use that name set to save the file from the $_FILES array, or their language equivalent.

Handling Audio Files

When a subdialog question type is placed after a comment question type on a phone survey, the recorded comment is submitted to the subdialog question type as expected. To process the audio file, users first need to detect the audio file. To accomplish this, review the answers array for answers that match the format 'file://__comment_{some_id}'. When encountering an answer in this format, check the $_FILES array, or the language equivalent, to locate the uploaded file and process it accordingly.

Per-Page Data Submission

For other questions to send data to a subdialog question, those questions must be on the same page as the subdialog question. For example, if a survey has 5 questions on one page and the next page contains the sudbialog question, then those 5 questions will not be included in the data posted to the subdialog. This is important to keep in mind when designing surveys to ensure that subdialog questions are placed properly.

Subdialog Response

By default, if the subdialog does not return any data, then the answer for the subdialog question is stored as an empty value. To return a value to be stored as the answer to the subdialog question, this can be done by returning a single variable named 'result'.

The following subdialog sample returns 'it worked' as a single variable, which is saved as the answer for the subdialog question.

<?xml version="1.0"?>
<vxml version="2.0">
            <var name="result" expr="'it worked'"/>
	    <return namelist="result"/>

Result URL

Insight allows users to configure their outbound calls to automatically send the status of each outbound call to a REST service upon completion. To do so, it is necessary to provide a result_url when queuing the outbound calls.

Insight provides three different ways to accomplish this: queuing through the Outbound UI, queuing a single outbound call through the Queue Call API , and queuing multiple outbound calls via the Bulk Queue API.

The result_url callback will be POSTed to when the outbound call completes, when all outbound attempts are exhausted, or when the outbound call is canceled. The body of this request will be identical to the 'call_details' element in the Outbound Call Status API method.

Request Parameters

The following parameters will be POSTed to your result_url:

statusstringCall outcome: 'completed', 'canceled', 'failed', 'rejected'
attemptsintNumber of outbound attempts that were made
max_attemptsintTotal number of call attempts to be made
queued_timestampintTimestamp of when the call was queued
last_attempt_timestampintTimestamp of the last time the call was attempted
start_timestampintTimestamp of when the calls were scheduled to begin. If not supplied when queuing, this will be an empty value
end_timestampintTimestamp of when the calls were scheduled to no longer make attempts. If not supplied when queuing, this will be an empty value
reattempt_waitintTime (in seconds) to wait between call re-try attempts
eventsarrayArray of call events, including the timestamp of the event

Associating Metadata with a Caller

It's commonplace to want to associate metadata with a specific inbound or outbound caller. This section will describe how to achieve this for both inbound and outbound calls.

Outbound Association

Associating a metadata record with an outbound caller is a very straightforward process. When queuing the outbound call, either via the api methods or though the outbound interface, you can optionally choose to include metadata for the caller. What this actually does is allow for automatic association of that record within the call. This means that you can instantly use the metadata store question type to record any of the columns values specified when queuing the call.

Here's a basic breakdown of those steps:

  1. You queue an outbound call with metadata
  2. When the call connects, that metadata record from your metadatabase is automatically available in your call
  3. Whenever you encounter a metadata store question in your survey during the call, the column you specify to store is saved as the answer to the question

Now, when you run reports you will have that metadata associated with the call as metadata store answers.

Documentation on queuing outbound calls can be found here:
Queuing an Outbound Call
Queuing Multiple Outbound Calls

Inbound Association

Associating a metadata record with an inbound call can be accomplished via the metadata filter and metadata store question types. The metadata filter question type will take a provided value as well as a column in your metadatabase to filter on and will match all rows in your metadatabase that match that value. It's as simple as that; if the value exists in your metadatabase you immediately have that metadata associated with the caller. You can even filter on the ANI/IP address of the user taking the survey such that if you add the ANI or IP address of users to your metadatabase before they take your survey you can instantly associate metadata with those users.

There may come a time where you have multiple ANI/IP address duplicates in your metadatabase and therefore the metadata filter question will match multiple values. For this circumstance, you can utilize the metadata store question's store row option to store only the latest stored record. This way you can ensure you're only associating with the last added record when storing the column values for the associated metadata as the metadata store question answers.

Let's use a sample use case to demonstrate this process:
You have a call center where your agents are working with your callers. After your agent has completed the call, you wish to transfer the caller to your feedback survey and want to associate the agent who handled the call with the survey response. This is where your metadatabase comes into play. You have two options, if you know your callers ANI beforehand, you can pre-populate the metadatabase for your survey with the ANI of your caller and any additional columns you wish to associate with the caller. If you are transferring in real time, you can utilize the metadata push api method to add that metadata record into your metadatabase right before you call connects. Once your caller has connected to the survey and the associated ANI is stored in your metadatabase you can use the metadata filter question type to filter that column with the ANI of your caller, associated the metadata record with the current call. You can then use the metadata store question to store any columns from the associated metadata record by utilizing the store row option as 'Latest', therefore storing only the last added record for that ANI.

Documentation on adding metadata records via the api can be found here:
Adding Metadatabase Records

data_integration.txt · Last modified: 2016/09/01 14:23 by admin