Sampling operation

A Sampling operation is the activity to perform on survey record invitations after they have been imported and sampled. The records can be sent to the Survey engine to create a survey with a URL, or they can bypass the engine and just create the survey record. Omitting a sampling operation disables sampling and just imports data.

Flow chart of import and sampling outcomes: SURVEYS_ONLY go to finished; SEND_INVITES and PUSH_TO_SURVEY_ENGINE both go through the Survey Engine before finished; no sampling goes to Completed

The operation is declared in the Auto Importer specification's Sampling Operation setting (samplingOperation XML attribute).

Auto Importer UI showing the Sampling Operations with one selected: "Sampling operations is determined at the record level"

In the XML specification, use the samplingOperation attribute of the survey-processor-options element:

<import-spec ... >
  ...
  <output-column-group pluginName="Survey" recordUpdateMode="CREATE">
    ...
  
    <!-- Use record-level sampling operations -->
    <survey-processor-options ... samplingOperation="SEND_INVITES" />
  </output-column-group>
</import-spec>

With the exception of the record-level directive, all other options apply to the entire feed-file. The options are:

NONE (No specification)No sampling; import records and mark them as completed (survey status will be set to COMPLETED).

This is typically used for ingesting historical data so it is available for reporting, or dummy data for testing purposes.

SEND_INVITES Create surveys, generate survey URLs, and send email invitations.
PUSH_TO_SURVEY_ENGINE Create surveys, generate survey URLs, but do not send invitations (survey status will be set to SURVEY_ENGINE_ONLY).
SURVEYS_ONLY

Sample the records, but do not generate survey URLs or send invitations (survey status will be set to NO_SURVEY_ENGINE).

This operation imports records directly into the system, bypassing the Survey Engine. This is typically used for SMS surveys whose records do not need to go through the Survey engine.

RECORD_LEVEL Sampling operation is determined on a per-record basis instead of the entire file. See Record-level sampling operation below for details.
Important: There must be a sampling operation setting to initiate sampling. Otherwise, the record is imported but not sampled.

Record-level sampling operation

Record-level sampling is where a field in the import specification determines the sampling operation for the associated record. This process is useful when a single feed file has some records need to receive email invitations while others do not, such as for SMS- or paper-based surveys. Still other records might not get a survey at all.

Four records with their sampling_operation field values set to one of SEND_INVITES, SURVEYS_ONLY, or PUSH_TO_SURVEY_ENGINE

When using RECORD_LEVEL post-sampling, a special target field called as sampling_operation in the Auto Importer specification identifies the operation for the associated record. 

Auto Importer UI for an output column mapped to an existing field named "sampling_operation", which is an enumerated field

The value of the Sampling operation field is either SEND_INVITES, PUSH_TO_SURVEY_ENGINE, or SURVEYS_ONLY.

The field can be a literal value that came in with the record in the feed-file, it can be a constant (which is the same as setting the operation at the file-level), or it can be a computed value based on other fields in the record. For example, if there is a value in an email address field, send invitations; otherwise, just push the record to the Survey engine.

This example demonstrates such a transformation in the XML specification:

<import-spec ... >
  ...
  <output-column-group pluginName="Survey" recordUpdateMode="CREATE">
    ...
    <output-column>
      <!-- Perform a record-level sampling operation -->
      <target-field fieldId="sampling_operation"   
                    fieldName="Sampling Operation" 
                    requiredness="OPTIONAL_INVALID_CONVERTED_TO_NULL"
                    type="ENUMERATED">
        <enumerated-field-parse-options mappingKey="NAME" />
        <!-- Sample and invite only if there is a value in the email field. -->
        <javascript-transform><![CDATA[
            
            if(hasContent(record['email_field'])) {
                return 'SEND_INVITES';
            }
            else {
                return 'PUSH_TO_SURVEY_ENGINE';
            }

        ]]></javascript-transform>
      </target-field>
    </output-column>
    ...
    <transfer-to-survey-engine />
 
    <!-- Use record-level sampling operations -->
    <survey-processor-options primaryUnitFieldId="e_unit_field" 
                              samplingOperation="RECORD_LEVEL" />
  </output-column-group>
</import-spec>