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.

Encoding

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.

<?php

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.